Expand run-sampler --compact: results register, vanished-output grouping, scope tier, visual-only tier

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.58.0] (22/07/2026)
+Expand `silverfin run-sampler --compact`: diff the `results` register alongside `named_results` (shown as a triggered-indicator count for 0/1 flag arrays), group entries whose rendered output vanished entirely into a single "output vanished" finding per template instead of dozens of individual lines, add a `dependencies`/`rollforward_params`/`required_keys_missing` scope-change tier (rendered as one sub-line per category, not a semicolon-packed dump), and add a visual-only tier that flags `view.html` changes invisible to the data diff - described field-by-field where a `data-name` anchors the change, with a plain "compare the files" fallback otherwise. Long values are now truncated and per-template/per-entry change lists are capped, both with an explicit "+N more" disclosure. Also adds `run-sampler --from-zip <path>` to build the compact diff from an already-downloaded `results.zip` with no sampler run or network call.
+
 ## [1.57.1] (15/07/2026)
 Improve `silverfin run-sampler` by adding a compact output mode.
 

bin/cli.js

@@ -519,7 +519,7 @@ program
 program
   .command("run-sampler", { hidden: true})
   .description("Run Liquid Sampler for partner templates (reconciliation texts, account detail templates, and/or shared parts)")
-  .requiredOption("-p, --partner <partner-id>", "Specify the partner to be used")
+  .option("-p, --partner <partner-id>", "Specify the partner to be used (required unless --from-zip is used)")
   .option("-h, --handle <handles...>", "Specify reconciliation text handle(s) - can specify multiple")
   .option("-at, --account-template <names...>", "Specify account detail template name(s) - can specify multiple")
   .option("-s, --shared-part <names...>", "Specify shared part name(s) - can specify multiple")
@@ -530,15 +530,39 @@ program
       "accountTemplate",
       "sharedPart",
       "firmIds",
+      "fromZip",
+    ])
+  )
+  .addOption(
+    new Option("--from-zip <path>", "Build the compact diff from an already-downloaded results.zip - no sampler run, no network call").conflicts([
+      "handle",
+      "accountTemplate",
+      "sharedPart",
+      "firmIds",
+      "id",
     ])
   )
   .option("--no-open", "Do not download/open the report locally; only print its URL (default in CI)")
-  .option("--compact", "Download the result and print a compact named_results diff (grouped by template) to stdout - review-friendly and safe in CI")
+  .option("--compact", "Download the result and print a compact diff (named_results/results, dependencies, vanished renders, visual-only changes) grouped by template - review-friendly and safe in CI")
   .action(async (options) => {
     // Commander sets options.open = false when --no-open is passed.
     // In CI, never open regardless of the flag.
     const runnerOptions = { openReport: options.open && !process.env.CI, compact: options.compact || false };
 
+    // A local zip needs no partner API access at all - it's pure offline
+    // re-analysis of a result someone already has on disk.
+    if (options.fromZip) {
+      await new LiquidSamplerRunner(options.partner, runnerOptions).printCompactDiffFromZip(options.fromZip);
+      return;
+    }
+
+    // Every other path talks to the partner/sampler API, so -p/--partner is
+    // required there - it's just not required for --from-zip's offline path.
+    if (!options.partner) {
+      consola.error("You need to specify a partner using -p or --partner");
+      process.exit(1);
+    }
+
     // If an existing sampler ID is provided, fetch and display results
     if (options.id) {
       if (!/^\d+$/.test(options.id)) {