Merge pull request #35 from QuantStrategyLab/codex/qar-publisher-period-2b1

QAR PR-2B1: validate candidates before publisher selection

Author: Pigbibi

src/quant_advisor_research/archive_backfill.py

@@ -7,7 +7,7 @@
 from typing import Any
 
 from .build_pipeline import DEFAULT_FEED_TITLE, DEFAULT_SITE_URL, copy_if_different
-from .publisher import publish_reports, unique_report_paths_by_content
+from .publisher import preflight_publish_destinations, publish_reports, require_publish_candidates
 
 
 REPORT_JSON_PATTERN = re.compile(r"advisory_report_\d{4}-\d{2}-\d{2}\.json")
@@ -24,29 +24,35 @@ def load_report(path: Path) -> dict[str, Any] | None:
 
 
 def discover_report_paths(artifact_roots: list[str | Path], explicit_reports: list[str | Path]) -> list[Path]:
-    candidates: list[Path] = []
+    explicit_candidates: list[Path] = []
     for report in explicit_reports:
         path = Path(report)
         if path.exists() and path.name.startswith("advisory_report_") and path.suffix == ".json":
-            candidates.append(path)
+            explicit_candidates.append(path)
+    root_candidates: list[Path] = []
     for root in artifact_roots:
         root_path = Path(root)
         if not root_path.exists():
             continue
-        candidates.extend(
+        root_candidates.extend(
             path
             for path in root_path.rglob("advisory_report_*.json")
             if path.is_file() and REPORT_JSON_PATTERN.fullmatch(path.name)
         )
 
-    by_as_of: dict[str, Path] = {}
-    for path in sorted(candidates, key=lambda item: (item.name, str(item))):
-        payload = load_report(path)
-        if not payload:
+    unique_paths: list[Path] = []
+    seen: set[Path] = set()
+    all_candidates = explicit_candidates + root_candidates
+    all_candidates.sort(key=lambda item: str(item))
+    all_candidates.sort(key=lambda item: item.name, reverse=True)
+    candidates = all_candidates
+    for path in candidates:
+        resolved = path.resolve()
+        if resolved in seen:
             continue
-        as_of = str(payload.get("as_of", ""))
-        by_as_of[as_of] = path
-    return [by_as_of[key] for key in sorted(by_as_of, reverse=True)]
+        seen.add(resolved)
+        unique_paths.append(path)
+    return unique_paths
 
 
 def backfill_site_archive(
@@ -55,13 +61,23 @@ def backfill_site_archive(
     output_dir: str | Path,
     site_url: str,
     feed_title: str,
+    current_report: str | Path | None = None,
 ) -> list[Path]:
-    if not report_paths:
+    if not report_paths and current_report is None:
         raise ValueError("No advisory_report_YYYY-MM-DD.json files found for backfill.")
-    report_paths = unique_report_paths_by_content(report_paths)
+    selection = require_publish_candidates(current_report, report_paths)
+    report_paths = list(selection.selected_paths)
+    preflight_publish_destinations(report_paths)
     output = Path(output_dir)
     output.mkdir(parents=True, exist_ok=True)
-    written = publish_reports(report_paths, output, site_url=site_url, feed_title=feed_title)
+    written = publish_reports(
+        report_paths,
+        output,
+        site_url=site_url,
+        feed_title=feed_title,
+        mandatory_current=current_report,
+        recovered_history=report_paths if current_report is not None else None,
+    )
     for report_path in report_paths:
         copy_if_different(report_path, output / report_path.name)
         markdown_path = report_path.with_suffix(".md")
@@ -77,6 +93,7 @@ def build_arg_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Backfill advisory site archive from local workflow artifacts.")
     parser.add_argument("--artifact-root", action="append", default=[], help="Directory to recursively scan for advisory reports.")
     parser.add_argument("--report", action="append", default=[], help="Explicit advisory report JSON path.")
+    parser.add_argument("--current-report", help="Optional explicit mandatory current report; --report remains history-only.")
     parser.add_argument("--output-dir", required=True, help="Static site output directory.")
     parser.add_argument("--site-url", default=DEFAULT_SITE_URL)
     parser.add_argument("--feed-title", default=DEFAULT_FEED_TITLE)
@@ -86,7 +103,13 @@ def build_arg_parser() -> argparse.ArgumentParser:
 def main(argv: list[str] | None = None) -> None:
     args = build_arg_parser().parse_args(argv)
     reports = discover_report_paths(args.artifact_root, args.report)
-    backfill_site_archive(report_paths=reports, output_dir=args.output_dir, site_url=args.site_url, feed_title=args.feed_title)
+    backfill_site_archive(
+        report_paths=reports,
+        current_report=args.current_report,
+        output_dir=args.output_dir,
+        site_url=args.site_url,
+        feed_title=args.feed_title,
+    )
     print(f"archive_backfill_reports={len(reports)} output={args.output_dir}")
 
 

src/quant_advisor_research/build_pipeline.py

@@ -21,7 +21,12 @@
     write_market_confirmation_csv,
 )
 from .monthly_review import build_monthly_review, render_monthly_review_markdown
-from .publisher import publish_reports, unique_report_paths_by_content
+from .publisher import (
+    preflight_publish_destinations,
+    publish_reports,
+    require_publish_candidates,
+    unique_report_paths_by_content,
+)
 from .recommendation_review import build_recommendation_review, render_recommendation_review_markdown
 
 
@@ -285,7 +290,11 @@ def build_advisory_artifacts(
         report_paths = [report_json, *recovered_report_paths]
     else:
         report_paths = [report_json]
-    report_paths = unique_report_paths_by_content(report_paths)
+    if site_output:
+        report_paths = list(require_publish_candidates(report_json, recovered_report_paths).selected_paths)
+        preflight_publish_destinations(report_paths)
+    else:
+        report_paths = unique_report_paths_by_content(report_paths)
 
     recommendation_review_json: Path | None = None
     recommendation_review_md: Path | None = None
@@ -304,7 +313,14 @@ def build_advisory_artifacts(
         write_text(recommendation_review_md, render_recommendation_review_markdown(review))
 
     if site_output:
-        publish_reports(report_paths, site_output, site_url=site_url, feed_title=feed_title)
+        publish_reports(
+            report_paths,
+            site_output,
+            site_url=site_url,
+            feed_title=feed_title,
+            mandatory_current=report_json,
+            recovered_history=recovered_report_paths,
+        )
         for path in report_paths:
             copy_if_different(Path(path), site_output / Path(path).name)
         copy_if_different(report_md, site_output / report_md.name)