scenescout 3.21.3 → 3.23.0

package/dist/engine/check.js

@@ -503,6 +503,7 @@ export const CHECK_OPTION_NAMES = [
     "sarif-file-anchor",
     "record",
     "video",
+    "template",
 ];
 /** Options that may be given alone, meaning on: `--record`, as well as `--record on` and `--record=off`. */
 const SWITCH_OPTIONS = new Set(["record", "video"]);
@@ -685,6 +686,12 @@ export function parseCheckArgs(args, cwd) {
     if (videoRaw !== undefined && !SWITCH_ON.includes(videoRaw) && !SWITCH_OFF.includes(videoRaw)) {
         return { ok: false, error: "--video is on or off, or given alone for on" };
     }
+    const template = flags.get("template");
+    if (template !== undefined && template.trim() === "")
+        return { ok: false, error: "--template needs the path of a report template (JSON)" };
+    if (template !== undefined && recordRaw !== undefined && SWITCH_OFF.includes(recordRaw)) {
+        return { ok: false, error: "--template renders the report from a recorded check's frames, so it cannot be used with --record off" };
+    }
     const resolve = (p) => resolveArgPath(cwd, p);
     return {
         ok: true,
@@ -713,6 +720,7 @@ export function parseCheckArgs(args, cwd) {
             ...(anchor ? { sarifFileAnchor: anchor.value } : {}),
             ...(recordRaw !== undefined ? { record: SWITCH_ON.includes(recordRaw) } : {}),
             ...(videoRaw !== undefined && SWITCH_ON.includes(videoRaw) ? { video: true } : {}),
+            ...(template !== undefined ? { template: resolve(template) } : {}),
         },
     };
 }
@@ -1178,5 +1186,6 @@ export function toSummaryJson(result, toolVersion) {
         worthALook: result.worthALook,
         // Routes a check with no session was sent to sign-in from: a coverage gap. Absent when the check had a session.
         ...(result.needsSignIn ? { needsSignIn: result.needsSignIn } : {}),
+        ...(result.testReport ? { testReport: result.testReport } : {}),
     };
 }

package/dist/engine/ci-lanes.js

@@ -8,7 +8,7 @@
  * and how the lanes' endings become the run's. The loop that runs them is
  * src/ci-run.ts; the shared budget is engine/ci.ts's. Why: ADR 20.
  */
-import { LANE_RULES, planLanes } from "./brief.js";
+import { LANE_RULES, planLanes, replayBriefs } from "./brief.js";
 import { CI_TOOLS } from "./ci.js";
 /** The session the run attaches first. It plans, holds no lane, and writes the report once every lane is done. */
 export const PLANNER_SESSION = "default";
@@ -88,6 +88,10 @@ export function crawlNotes(text) {
 export function crawlFoundNothing(text) {
     return /^(?:\[session [^\]]*\]\s*)?(Nothing to crawl|Nothing new to crawl|No routes to crawl yet)/m.test(text);
 }
+/** The routes a run has to plan with: the page it attached on, then every route the planning crawl listed. */
+export function plannedRoutes(target, notes) {
+    return [...new Set([routeOf(target), ...notes.keys()])];
+}
 /** The path a target URL opens, as a route: the planning crawl never lists the page the run attached on. */
 function routeOf(url) {
     try {
@@ -119,12 +123,12 @@ export function laneSessions(names) {
  * run has nothing to split, and explores in one loop, saying why.
  */
 export function planCiLanes(o) {
-    const routes = [...new Set([routeOf(o.target), ...o.notes.keys()])];
+    const routes = plannedRoutes(o.target, o.notes);
     if (o.count < 2)
         return { lanes: [], oneLoop: "one lane was asked for" };
     if (o.notes.size === 0 && o.planningFailed)
         return { lanes: [], oneLoop: `${o.planningFailed}, so there was nothing to split` };
-    const briefs = planLanes(routes, o.count, { goal: o.focus, mode: o.mode });
+    const briefs = planLanes(routes, o.count, { goal: o.focus, mode: o.mode, ...(o.order ? { order: o.order } : {}) });
     if (briefs.length < 2) {
         const where = briefs[0]?.modules[0];
         return {
@@ -132,16 +136,27 @@ export function planCiLanes(o) {
             oneLoop: `the planning crawl found ${routes.length} route(s), all in ${where ? `one module (${where})` : "no module"}, so there was nothing to split`,
         };
     }
+    return { lanes: asCiLanes(briefs, o.target, o.notes) };
+}
+function asCiLanes(briefs, target, notes) {
     const sessions = laneSessions(briefs.map((b) => b.lane));
-    return {
-        lanes: briefs.map((b, i) => ({
-            ...b,
-            session: sessions[i],
-            // On the target's origin whatever the route says: a path written `//host/x` must not become another host.
-            url: `${new URL(o.target).origin}${b.landing.startsWith("/") ? "" : "/"}${b.landing}`,
-            crawl: b.routes.flatMap((r) => o.notes.get(r) ?? []).slice(0, LIST_MAX),
-        })),
-    };
+    return briefs.map((b, i) => ({
+        ...b,
+        session: sessions[i],
+        // On the target's origin whatever the route says: a path written `//host/x` must not become another host.
+        url: `${new URL(target).origin}${b.landing.startsWith("/") ? "" : "/"}${b.landing}`,
+        crawl: b.routes.flatMap((r) => notes.get(r) ?? []).slice(0, LIST_MAX),
+    }));
+}
+/**
+ * A replayed run's lanes (from-run.ts replayPlan): one per session the
+ * recorded run had, each with its routes in recorded order, however many lanes
+ * were asked for. With fewer than two the run replays in one loop.
+ */
+export function planReplayLanes(o) {
+    if (o.lanes.length < 2)
+        return { lanes: [], oneLoop: `the recorded run had ${o.lanes.length === 1 ? "one session" : "no steps"}, so it is replayed in one loop` };
+    return { lanes: asCiLanes(replayBriefs(o.lanes, o.focus), o.target, new Map()) };
 }
 // ── what a lane is told ─────────────────────────────────────────────────────
 /**
@@ -171,6 +186,7 @@ export function ciLaneKickoff(o) {
         `Target: ${o.url}`,
         `Your lane: ${lane.objective}`,
         `Your routes (${lane.routes.length}): ${lane.routes.slice(0, LIST_MAX).join(", ")}${lane.routes.length > LIST_MAX ? ` … and ${lane.routes.length - LIST_MAX} more` : ""}`,
+        ...(o.fromRun ?? []),
         `Your browser is on ${routeOf(lane.url)}.`,
         lane.crawl.length > 0 ? `What the planning crawl saw on your routes:\n${lane.crawl.map((l) => `  ${l.trim()}`).join("\n")}` : "",
         `Project directory (for scout_scan): ${o.projectDir}`,

package/dist/engine/ci.js

@@ -16,6 +16,7 @@ import { markdownCell } from "./check.js";
 import { parseLimitFlag } from "./limits.js";
 import { isWorthALook, redactSecrets } from "./memory.js";
 import { SARIF_ANCHOR_FALLBACKS, checkSarifAnchor, sarifLocation } from "./sarif.js";
+import { fromRunLine, resolveFromRun } from "./from-run.js";
 // ── options ─────────────────────────────────────────────────────────────────
 export const PROVIDERS = ["anthropic", "openai"];
 /** Where each provider's key is read from. Nothing else is: no flag, no file, no input. */
@@ -93,6 +94,9 @@ export const CI_OPTION_NAMES = [
     "show",
     "compare-url",
     "dedup",
+    "from-run",
+    "from-run-mode",
+    "from-run-turns-per-page",
     "sarif-file-anchor",
 ];
 /** The longest --show description: it becomes a line of the model's prompt. */
@@ -115,7 +119,8 @@ export function checkBaseUrl(raw) {
         return { ok: true, url: u.toString().replace(/\/+$/, "") };
     return { ok: false, error: "--base-url must be https (plain http only to 127.0.0.1 or localhost): the API key is sent to it" };
 }
-export function parseCiArgs(args, cwd) {
+/** `env` is read for the earlier run alone (SCENESCOUT_FROM_RUN, SCENESCOUT_FROM_RUN_MODE), since a flag wins over it. */
+export function parseCiArgs(args, cwd, env = {}) {
     const positional = [];
     const flags = new Map();
     for (let i = 0; i < args.length; i++) {
@@ -271,6 +276,13 @@ export function parseCiArgs(args, cwd) {
     const anchor = flags.has("sarif-file-anchor") ? checkSarifAnchor(flags.get("sarif-file-anchor")) : undefined;
     if (anchor && !anchor.ok)
         return anchor;
+    const runFlags = { path: flags.get("from-run"), mode: flags.get("from-run-mode"), turnsPerPage: flags.get("from-run-turns-per-page") };
+    if (show && (runFlags.path !== undefined || runFlags.mode !== undefined || runFlags.turnsPerPage !== undefined))
+        return { ok: false, error: "--from-run starts an exploration from an earlier run, and --show explores nothing: give one or the other" };
+    // A run asked to show an element explores nothing, so an earlier run named in the environment does not apply to it.
+    const fromRun = show ? { ok: true } : resolveFromRun(runFlags, env);
+    if (!fromRun.ok)
+        return fromRun;
     const resolve = (p) => (p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) ? p : `${cwd.replace(/[\\/]$/, "")}/${p}`);
     return {
         ok: true,
@@ -296,6 +308,7 @@ export function parseCiArgs(args, cwd) {
             ...(navTimeout.value !== undefined ? { navTimeoutMs: navTimeout.value } : {}),
             dedup: dedup,
             ...(anchor ? { sarifFileAnchor: anchor.value } : {}),
+            ...(fromRun.fromRun ? { fromRun: { ...fromRun.fromRun, path: resolve(fromRun.fromRun.path), given: fromRun.fromRun.path } } : {}),
         },
     };
 }
@@ -691,6 +704,7 @@ export function ciKickoff(o) {
     return [
         `Run an exploratory test session following the method.`,
         `Target: ${o.url}`,
+        ...(o.fromRunLines ?? []),
         `Project directory (for scout_scan): ${o.projectDir}`,
         `Level: ${o.level}`,
         `Write mode: ${o.mode}`,
@@ -760,6 +774,7 @@ export function ciSummaryMarkdown(r, secrets = []) {
         `| Model | ${r.provider} ${cell(r.model, secrets)}, effort ${r.effort} |`,
         ...(r.lanes ? [`| Lanes | ${lanesCell(r.lanes, secrets)} |`] : []),
         ...(r.dedup ? [`| Finding dedup | ${dedupLine(r.dedup)} |`] : []),
+        ...(r.fromRun ? [`| Started from | ${cell(fromRunLine(r.fromRun), secrets)} |`] : []),
         `| Usage | ${usageLine(r.spend, r.model, r.endedAt, r.price)} |`,
         ``,
     ];
@@ -785,6 +800,27 @@ export function ciSummaryMarkdown(r, secrets = []) {
     lines.push(r.capture ? `The pictures are in shots/.` : `The full report, with repro steps and the gap ledger, is report.md.`, ``);
     return lines.join("\n");
 }
+/** A run record with every text a page or a person wrote in it passed through `clean`, as everything else ci.json holds is. */
+function cleanRecord(r, clean) {
+    const all = (xs) => xs.map(clean);
+    return {
+        ...r,
+        knownRoutes: all(r.knownRoutes),
+        visited: all(r.visited),
+        lanes: r.lanes.map((l) => ({ session: l.session, routes: all(l.routes) })),
+        steps: r.steps.map((s) => ({ ...s, route: clean(s.route), ...(s.target !== undefined ? { target: clean(s.target) } : {}) })),
+        left: r.left.map((l) => ({
+            ...l,
+            route: clean(l.route),
+            unexercised: all(l.unexercised),
+            forms: all(l.forms),
+            unchosen: l.unchosen.map((d) => ({ key: clean(d.key), options: all(d.options) })),
+        })),
+        gaps: all(r.gaps),
+        ...(r.assigned ? { assigned: all(r.assigned) } : {}),
+        ...(r.prefixes ? { prefixes: r.prefixes.map((n) => ({ ...n, target: clean(n.target), ...(n.why !== undefined ? { why: clean(n.why) } : {}) })) } : {}),
+    };
+}
 function lanesCell(l, secrets) {
     if (l.oneLoop)
         return `${l.asked} asked; explored in one loop: ${cell(l.oneLoop, secrets)}`;
@@ -876,6 +912,8 @@ export function ciSummaryJson(r, version, secrets = []) {
         })),
         ...(r.capture ? { capture: cleanCapture(r.capture, clean) } : {}),
         ...(r.lanes ? { lanes: lanesJson(r.lanes, clean) } : {}),
+        ...(r.fromRun ? { fromRun: { mode: r.fromRun.mode, source: clean(r.fromRun.source), runId: r.fromRun.runId, recordAt: r.fromRun.recordAt } } : {}),
+        ...(r.record ? { record: cleanRecord(r.record, clean) } : {}),
     };
 }
 /** The lanes as ci.json holds them. Module paths and lane names come from the app's routes: redacted like the rest. */

package/dist/engine/flow.js

@@ -205,30 +205,41 @@ const target = z
         });
     }
 });
+/**
+ * What a step should bring about, in the words of the test it belongs to: the
+ * expected result a template-driven test report (`--template`) shows beside
+ * the step. Documentation only: it is never checked, so a step passes or
+ * fails on its action and its assertions alone.
+ */
+const expected = z.string().trim().min(1, "is the result the step should bring about, in words").max(500).optional();
 /** Most times a repeat step may run its steps. A longer loop is a page that should be reached another way. */
 export const MAX_REPEATS = 100;
 const SINGLE_STEP_SCHEMAS = [
-    z.object({ action: z.literal("navigate"), target: z.string().regex(/^\//, "must be a path on the app, starting with /") }).strict(),
-    z.object({ action: z.literal("click"), target }).strict(),
-    z.object({ action: z.literal("type"), target, value: z.string(), pressEnter: z.boolean().optional(), replace: z.boolean().optional() }).strict(),
-    z.object({ action: z.literal("select"), target, value: z.string() }).strict(),
-    z.object({ action: z.literal("press"), value: z.string().min(1, "names the key to press, e.g. Enter") }).strict(),
+    z.object({ action: z.literal("navigate"), expected, target: z.string().regex(/^\//, "must be a path on the app, starting with /") }).strict(),
+    z.object({ action: z.literal("click"), expected, target }).strict(),
+    z.object({ action: z.literal("type"), expected, target, value: z.string(), pressEnter: z.boolean().optional(), replace: z.boolean().optional() }).strict(),
+    z.object({ action: z.literal("select"), expected, target, value: z.string() }).strict(),
+    z.object({ action: z.literal("press"), expected, value: z.string().min(1, "names the key to press, e.g. Enter") }).strict(),
     // A small valid file generated for the input (its kind from `fixture`, else the input's accept attribute), as
     // scout_upload attaches one. `target` is the file input or the control that opens its chooser; absent, the page's only file input.
     z
         .object({
         action: z.literal("upload"),
+        expected,
         target: target.optional(),
         fixture: z.enum(FIXTURE_KINDS).optional(),
         name: z.string().min(1).max(120).optional(),
     })
         .strict(),
-    z.object({ action: z.literal("expect-text"), text: z.string().min(1, "is the text that must be visible") }).strict(),
-    z.object({ action: z.literal("expect-element"), target, state: z.enum(ELEMENT_STATES) }).strict(),
-    z.object({ action: z.literal("expect-url"), pattern: z.string().min(1).refine(isRegex, { message: "is not a valid regular expression" }) }).strict(),
+    z.object({ action: z.literal("expect-text"), expected, text: z.string().min(1, "is the text that must be visible") }).strict(),
+    z.object({ action: z.literal("expect-element"), expected, target, state: z.enum(ELEMENT_STATES) }).strict(),
+    z
+        .object({ action: z.literal("expect-url"), expected, pattern: z.string().min(1).refine(isRegex, { message: "is not a valid regular expression" }) })
+        .strict(),
     z
         .object({
         action: z.literal("expect-request"),
+        expected,
         request: z.string().regex(REQUEST_RE, 'must be a method and a path, e.g. "GET /api/things"'),
         status: z.union([z.number().int().min(100).max(599), z.string().regex(/^[1-5]xx$/, 'must be a status such as 200, or a class such as "2xx"')]),
     })
@@ -246,6 +257,7 @@ const isRepeatCondition = (s) => s.action === "expect-text" || s.action === "exp
 const repeatSchema = z
     .object({
     action: z.literal("repeat"),
+    expected,
     steps: z
         .array(singleStepSchema)
         .min(1, "needs at least one step to repeat")
@@ -262,6 +274,10 @@ const flowSchema = z
     .object({
     name: z.string().min(1).max(100).optional(),
     description: z.string().max(500).optional(),
+    /** The test's identifier in a template-driven test report (--template). Traceability only: the replay never reads it. */
+    id: z.string().trim().min(1, "is the test's identifier").max(100).optional(),
+    /** The requirement identifiers the flow covers, shown beside it in a template-driven test report. */
+    requirements: z.array(z.string().trim().min(1, "is a requirement identifier").max(100)).max(50, "holds at most 50 identifiers").optional(),
     /**
      * Who walks the flow: a role whose sign-in `scenescout login --role` saved in the project. Absent, the flow runs
      * in the check's own session. Flows run in file-name order, so one role's flow can pick up what another's left.
@@ -330,6 +346,10 @@ export function parseFlow(text, file) {
     const flow = { name: parsed.data.name ?? file.replace(/\.json$/i, ""), file, steps: parsed.data.steps };
     if (parsed.data.role !== undefined)
         flow.role = parsed.data.role;
+    if (parsed.data.id !== undefined)
+        flow.id = parsed.data.id;
+    if (parsed.data.requirements !== undefined)
+        flow.requirements = parsed.data.requirements;
     return { ok: true, flow };
 }
 /**