+
+
- """.format(cards="".join(run_cards))
+ """.format(cards="".join(run_cards), base_css=base_css)
return HTMLResponse(html)
return app
diff --git a/src/main.py b/src/main.py
index 3ecc8df..a604628 100644
--- a/src/main.py
+++ b/src/main.py
@@ -651,12 +651,30 @@ def package_run(
):
import shutil
- run_dir = Path(reports_dir) / run_id
+ def _safe_segment(value: str, label: str) -> str:
+ """Validate a user-supplied path segment (no traversal)."""
+
+ if not value:
+ raise typer.BadParameter(f"{label} must not be empty")
+ if "/" in value or "\\" in value:
+ raise typer.BadParameter(f"{label} must be a simple name (no path separators)")
+ if value.startswith(".") or ".." in value:
+ raise typer.BadParameter(f"Invalid {label}")
+ if Path(value).is_absolute():
+ raise typer.BadParameter(f"Invalid {label}")
+ return value
+
+ run_id = _safe_segment(run_id, "run_id")
+
+ reports_root = Path(reports_dir).resolve()
+ run_dir = (reports_root / run_id).resolve()
+ if not run_dir.is_relative_to(reports_root):
+ raise typer.BadParameter("Invalid run_id")
if not run_dir.exists() or not run_dir.is_dir():
typer.secho(f"Run directory not found: {run_dir}", fg=typer.colors.RED)
raise typer.Exit(code=1)
- out_path = Path(output) if output else Path(reports_dir) / f"{run_id}.zip"
+ out_path = Path(output) if output else reports_root / f"{run_id}.zip"
out_path.parent.mkdir(parents=True, exist_ok=True)
base_name = out_path.with_suffix("")
archive = shutil.make_archive(str(base_name), "zip", run_dir)
@@ -675,6 +693,8 @@ def clean_cache(
):
"""Permanently delete stale cache files beyond the retention window."""
+ import os
+
now = datetime.now(UTC)
threshold = now - timedelta(days=max_age_days)
targets: list[tuple[str, Path]] = [("data", Path(cache_dir))]
@@ -689,7 +709,23 @@ def clean_cache(
typer.echo(f"cache-clean: {label} cache not found at {root}, skipping")
continue
- candidate_files = [file for file in root.rglob("*") if file.is_file()]
+ root = root.resolve()
+ candidate_files: list[Path] = []
+ # Avoid following symlinked directories (which could escape the cache root).
+ for dirpath, _dirnames, filenames in os.walk(root, followlinks=False):
+ dir_path = Path(dirpath)
+ for name in filenames:
+ file_path = dir_path / name
+ # Skip symlinks to avoid acting on files outside cache roots.
+ if file_path.is_symlink():
+ continue
+ try:
+ if not file_path.resolve().is_relative_to(root):
+ continue
+ except OSError:
+ continue
+ if file_path.is_file():
+ candidate_files.append(file_path)
if not candidate_files:
typer.echo(f"cache-clean: {label} cache at {root} has no files")
continue
@@ -716,8 +752,11 @@ def clean_cache(
typer.echo(f"cache-clean: failed to remove {file_path}: {exc}", err=True)
if not dry_run:
- # Remove emptied directories bottom-up.
- for dir_path in sorted({p.parent for p in candidate_files}, reverse=True):
+ # Remove emptied directories bottom-up (do not follow symlink dirs).
+ for dirpath, _dirnames, _filenames in os.walk(root, topdown=False, followlinks=False):
+ dir_path = Path(dirpath)
+ if dir_path == root:
+ continue
try:
if dir_path.exists() and not any(dir_path.iterdir()):
dir_path.rmdir()
diff --git a/src/reporting/dashboard.py b/src/reporting/dashboard.py
index e21e6c1..6a123d7 100644
--- a/src/reporting/dashboard.py
+++ b/src/reporting/dashboard.py
@@ -42,6 +42,7 @@
DOWNLOAD_FILE_CANDIDATES: tuple[str, ...] = (
"report.html",
+ "plotly.min.js",
"summary.json",
"summary.csv",
"all_results.csv",
diff --git a/src/reporting/html.py b/src/reporting/html.py
index 852ccc1..0fdde67 100644
--- a/src/reporting/html.py
+++ b/src/reporting/html.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+import html as html_stdlib
import json
import math
from pathlib import Path
@@ -10,6 +11,8 @@
if TYPE_CHECKING:
pass
+PLOTLY_MIN_JS_FILENAME: str = "plotly.min.js"
+
class HTMLReporter:
def __init__(
@@ -27,6 +30,57 @@ def __init__(
self.inline_css = inline_css
def export(self, best: list[object]):
+ def _esc(value: Any) -> str:
+ if value is None:
+ return ""
+ text: str
+ # `params` can be a dict; JSON is more readable than Python's repr.
+ if isinstance(value, dict):
+ try:
+ text = json.dumps(value, sort_keys=True, ensure_ascii=True, default=str)
+ except Exception:
+ text = str(value)
+ else:
+ text = str(value)
+ return html_stdlib.escape(text, quote=True)
+
+ def _json_for_inline_script(value: Any) -> str:
+ """JSON-safe for embedding directly in a ` breakouts by escaping `<` and also guards common HTML parser
+ edge cases (`>`, `&`). Values come from configs/strategies and may be user-controlled.
+ """
+
+ text = json.dumps(value, ensure_ascii=True)
+ return (
+ text.replace("<", "\\u003c")
+ .replace(">", "\\u003e")
+ .replace("&", "\\u0026")
+ )
+
+ def _write_plotly_asset() -> str:
+ """Write Plotly JS to disk and return relative script src.
+
+ Plotly is loaded from a CDN by default, but the offline HTML mode uses a local copy
+ written alongside the report so opening `report.html` works without internet access.
+ """
+
+ dest = self.out_dir / PLOTLY_MIN_JS_FILENAME
+ if dest.exists() and dest.stat().st_size > 0:
+ return PLOTLY_MIN_JS_FILENAME
+
+ try:
+ import importlib.resources as resources
+
+ src = resources.files("plotly").joinpath("package_data/plotly.min.js")
+ dest.write_bytes(src.read_bytes())
+ except Exception:
+ # Fallback: keep report functional without charts if we cannot materialize the asset.
+ # (The rest of the HTML is still useful.)
+ return "https://cdn.plot.ly/plotly-2.32.0.min.js"
+
+ return PLOTLY_MIN_JS_FILENAME
+
# Load all rows for top-N sections from results cache
all_rows = self.cache.list_by_run(self.run_id)
# Fallback: if the current run reused cached results and didn't write
@@ -101,12 +155,12 @@ def strategy_section() -> str:
row = strategy_best[key]
rows_html.append(
"
"
- f"| {row.get('symbol')} | "
- f"{row.get('strategy')} | "
- f"{row.get('timeframe')} | "
- f"{row.get('metric')} | "
+ f"{_esc(row.get('symbol'))} | "
+ f"{_esc(row.get('strategy'))} | "
+ f"{_esc(row.get('timeframe'))} | "
+ f"{_esc(row.get('metric'))} | "
f"{row.get('metric_value', float('nan')):.4f} | "
- f"{row.get('collection')} | "
+ f"{_esc(row.get('collection'))} | "
"
"
)
body = "\n".join(rows_html)
@@ -142,12 +196,12 @@ def metric_section() -> str:
row = entry["row"]
rows_html.append(
"
"
- f"| {metric_name.title()} | "
+ f"{_esc(metric_name.title())} | "
f"{entry['value']:.4f} | "
- f"{row.get('strategy')} | "
- f"{row.get('collection')} | "
- f"{row.get('symbol')} | "
- f"{row.get('timeframe')} | "
+ f"{_esc(row.get('strategy'))} | "
+ f"{_esc(row.get('collection'))} | "
+ f"{_esc(row.get('symbol'))} | "
+ f"{_esc(row.get('timeframe'))} | "
"
"
)
if not rows_html:
@@ -182,11 +236,11 @@ def top_section() -> str:
rows_html.append(
"
"
f"| {idx} | "
- f"{row.get('collection')} | "
- f"{row.get('symbol')} | "
- f"{row.get('strategy')} | "
- f"{row.get('timeframe')} | "
- f"{row.get('metric')} | "
+ f"{_esc(row.get('collection'))} | "
+ f"{_esc(row.get('symbol'))} | "
+ f"{_esc(row.get('strategy'))} | "
+ f"{_esc(row.get('timeframe'))} | "
+ f"{_esc(row.get('metric'))} | "
f"{row.get('metric_value', float('nan')):.4f} | "
"
"
)
@@ -245,7 +299,7 @@ def _safe_float(val: Any) -> float | None:
)
scatter_section = ""
- chart_json = json.dumps(chart_data)
+ chart_json = _json_for_inline_script(chart_data)
if chart_data:
scatter_section = """
@@ -273,7 +327,7 @@ def _safe_float(val: Any) -> float | None:
}
)
- detail_json = json.dumps(detail_records)
+ detail_json = _json_for_inline_script(detail_records)
detail_section = ""
if detail_records:
@@ -309,13 +363,13 @@ def card_for_row(row: dict[str, Any]) -> str:
return f"""
-
{row.get("collection", "")} / {row.get("symbol", "")}
- {row.get("timeframe", "")}
+ {_esc(row.get("collection", ""))} / {_esc(row.get("symbol", ""))}
+ {_esc(row.get("timeframe", ""))}
-
Strategy: {row.get("strategy", "")}
-
Metric: {row.get("metric", "")} = {float(row.get("metric_value", float("nan"))):.6f}
-
Params: {row.get("params", {})}
+
Strategy: {_esc(row.get("strategy", ""))}
+
Metric: {_esc(row.get("metric", ""))} = {float(row.get("metric_value", float("nan"))):.6f}
+
Params: {_esc(row.get("params", {}))}
Sharpe: {float(stats.get("sharpe", float("nan"))):.4f}
@@ -333,8 +387,8 @@ def card_for_row(row: dict[str, Any]) -> str:
def table_for_topn(rows: list[dict[str, Any]]) -> str:
rows = sorted(rows, key=lambda x: x["metric_value"], reverse=True)[: self.top_n]
body = "\n".join(
- f"
| {r['timeframe']} | {r['strategy']} | {r['metric']} | {r['metric_value']:.6f} | "
- f"{r['params']} | "
+ f"
| {_esc(r['timeframe'])} | {_esc(r['strategy'])} | {_esc(r['metric'])} | {r['metric_value']:.6f} | "
+ f"{_esc(r['params'])} | "
f"{r['stats'].get('sharpe', float('nan')):.4f} | "
f"{r['stats'].get('sortino', float('nan')):.4f} | "
f"{r['stats'].get('omega', float('nan')):.4f} | "
@@ -382,6 +436,56 @@ def table_for_topn(rows: list[dict[str, Any]]) -> str:
"" + card_for_row(top) + table_for_topn(rows) + ""
)
+ plotly_cdn_sri = (
+ "sha384-7TVmlZWH60iKX5Uk7lSvQhjtcgw2tkFjuwLcXoRSR4zXTyWFJRm9aPAguMh7CIra"
+ )
+ plotly_src = _write_plotly_asset() if self.inline_css else "https://cdn.plot.ly/plotly-2.32.0.min.js"
+ if plotly_src.startswith("http"):
+ plotly_tag = (
+ f''
+ )
+ else:
+ plotly_tag = f''
+
+ head_assets = ""
+ if self.inline_css:
+ css_inline = (
+ ":root{--bg:#020617;--panel:#0f172a;--text:#e2e8f0;--muted:#94a3b8} "
+ "body{background:var(--bg);color:var(--text);} "
+ ".container{max-width:72rem;margin:0 auto;padding:1.5rem} "
+ ".btn{padding:.25rem .75rem;border-radius:.375rem;background:#1e293b;color:#e2e8f0} "
+ ".grid{display:grid;gap:1rem} "
+ ".card{padding:1rem;border-radius:.75rem;background:var(--panel);box-shadow:0 1px 2px rgba(0,0,0,.3)} "
+ ".badge{font-size:.75rem;padding:.1rem .5rem;border-radius:.25rem;background:#1e293b} "
+ ".space-y-6>*+*{margin-top:1.5rem} "
+ ".summary-section{margin-bottom:1.5rem} "
+ ".hidden{display:none} "
+ ".detail-header{display:flex;justify-content:space-between;align-items:flex-end;gap:1.5rem;flex-wrap:wrap} "
+ ".detail-control{display:flex;flex-direction:column;gap:.4rem;min-width:220px} "
+ ".detail-control label{font-size:.75rem;text-transform:uppercase;letter-spacing:.08em;color:#94a3b8} "
+ ".detail-control select{background:#1e293b;border:1px solid rgba(148,163,184,.35);border-radius:.5rem;padding:.5rem .75rem;color:#e2e8f0} "
+ ".detail-charts{margin-top:1.5rem} "
+ ".trade-table{overflow-x:auto} "
+ ".trade-table table{width:100%;border-collapse:collapse;font-size:.8rem} "
+ ".trade-table thead{background:rgba(148,163,184,.1);text-transform:uppercase;letter-spacing:.06em;color:#94a3b8} "
+ ".trade-table th,.trade-table td{padding:.4rem .55rem;text-align:left;border-bottom:1px solid rgba(148,163,184,.2)} "
+ "table{width:100%;font-size:.875rem} thead{background:#334155;color:#cbd5e1} "
+ "th,td{padding:.5rem .75rem;text-align:left} code{font-family:ui-monospace,Menlo,Monaco,Consolas,monospace}"
+ )
+ head_assets = f""
+ else:
+ # Tailwind is convenient for rich reports, but requires internet. Users who want a fully
+ # offline report can pass `--inline-css`.
+ head_assets = (
+ '\n'
+ " "
+ )
+
html = f"""
@@ -389,10 +493,7 @@ def table_for_topn(rows: list[dict[str, Any]]) -> str:
Backtest Report
-
-
+ {head_assets}
",
- )
- html = html.replace("tailwind.config = { darkMode: 'class' };", "")
html = html.replace("max-w-6xl mx-auto p-6", "container")
html = html.replace(
"px-3 py-1 rounded bg-slate-800 text-slate-200 hover:bg-slate-700", "btn"
diff --git a/tests/test_html_reporter.py b/tests/test_html_reporter.py
index 1b82ceb..ffa6a0e 100644
--- a/tests/test_html_reporter.py
+++ b/tests/test_html_reporter.py
@@ -1,11 +1,42 @@
from __future__ import annotations
+from html.parser import HTMLParser
from pathlib import Path
from src.backtest.runner import BestResult
from src.reporting.html import HTMLReporter
+class _ScriptTagParser(HTMLParser):
+ """Collect