scenescout 3.15.0 → 3.17.0

package/dist/engine/calibration.js

@@ -244,8 +244,12 @@ export const MAX_UNFILED_NAMED = 10;
  * report, while the lane's session is still open.
  *
  * The check exists to catch unfiled defects, so a false "filed" costs more
- * than a false alarm, which only asks someone to look. A decision counts as
- * filed by one of three rules, tried in order:
+ * than a false alarm, which only asks someone to look. A decision that names
+ * the finding it was filed as (`finding`, the id scout_finding returned) is
+ * filed when the project holds a defect with that id: the lane's own link,
+ * exact, where matching evidence the lane may have reworded is not. An id the
+ * project does not hold is named in the line and the evidence is tried.
+ * Otherwise a decision counts as filed by one of three rules, tried in order:
  *
  * 1. Failing signatures. When the decision's evidence names one or more
  *    failing requests (the store's `failingSignatures`), it is filed only when
@@ -269,14 +273,17 @@ export const MAX_UNFILED_NAMED = 10;
  *    request does, and sends the decision to rule 1's verdict.
  * 3. Text. Evidence naming no failing request is matched on its text: the
  *    same evidence, a restatement of part of it, or shared identifiers and
- *    near-identical wording. The calibration join refuses a text match,
- *    because there a miss is scored against the lane.
+ *    near-identical wording, with the ids in paths templated on both sides.
+ *    The calibration join refuses a text match, because there a miss is
+ *    scored against the lane.
  */
 export function unfiledDefects(decisions, findings) {
     const keys = [];
     const filed = [];
     // A defect filed only as worth a look is not in the report's findings, so it is still unfiled.
-    for (const f of findings.filter((x) => !isWorthALook(x))) {
+    const defects = findings.filter((x) => !isWorthALook(x));
+    const ids = new Set(defects.map((f) => f.id));
+    for (const f of defects) {
         const text = `${f.evidence ?? ""} ${f.title}`;
         const requests = statedRequests(f.evidence ?? "");
         // The store's signatures, and the finding's own failing requests as
@@ -291,6 +298,7 @@ export function unfiledDefects(decisions, findings) {
             words: words(text),
             evidenceWords: words(f.evidence ?? ""),
             evidence: squash(f.evidence ?? ""),
+            templated: squash(templateIds(f.evidence ?? "")),
             raw: f.evidence ?? "",
             requests,
         });
@@ -299,31 +307,52 @@ export function unfiledDefects(decisions, findings) {
     for (const d of decisions) {
         if (d.verdict !== "defect")
             continue;
-        if (d.evidence) {
-            const evidence = d.evidence;
-            const joined = [...joinKeys(evidence)];
-            const failing = joined.flatMap((sig) => statedRequests(sig));
-            if (failing.length > 0 && failing.every((sig) => keys.some((k) => requestsPair(sig, k))))
-                continue;
-            if (filed.some((f) => restatesRequest(evidence, failing, f)))
-                continue;
-            // A failing-endpoint signature is the store's own identity for a bug. When
-            // the decision has one and no finding covers it, nothing else is a match.
-            if (joined.length > 0) {
-                out.push(`${d.observation} — ${d.evidence}`);
-                continue;
-            }
-            if (filed.some((f) => matchesText(evidence, f)))
-                continue;
-        }
-        out.push(d.evidence ? `${d.observation} — ${d.evidence}` : d.observation);
+        // The lane's own link to its filing: exact, so tried first. An id the
+        // project does not hold falls through to the evidence, and is named.
+        if (d.finding && ids.has(d.finding))
+            continue;
+        if (d.evidence && coveredByEvidence(d.evidence, keys, filed))
+            continue;
+        const look = d.finding ? findings.some((f) => f.id === d.finding) : false;
+        const unknown = !d.finding ? "" : look ? ` (finding ${d.finding} is filed only as worth a look)` : ` (finding ${d.finding} is not in this project)`;
+        out.push(`${d.evidence ? `${d.observation} — ${d.evidence}` : d.observation}${unknown}`);
     }
     return out;
 }
-/** Rule 3: the same evidence, a restatement of part of it, or shared identifiers and wording. */
+/** Rules 1 to 3: whether a finding's evidence covers the decision's. */
+function coveredByEvidence(evidence, keys, filed) {
+    const joined = [...joinKeys(evidence)];
+    const failing = joined.flatMap((sig) => statedRequests(sig));
+    if (failing.length > 0 && failing.every((sig) => keys.some((k) => requestsPair(sig, k))))
+        return true;
+    if (filed.some((f) => restatesRequest(evidence, failing, f)))
+        return true;
+    // A failing-endpoint signature is the store's own identity for a bug. When
+    // the decision has one and no finding covers it, nothing else is a match.
+    if (joined.length > 0)
+        return false;
+    return filed.some((f) => matchesText(evidence, f));
+}
+/**
+ * Rule 3: the same evidence, a restatement of part of it, or shared
+ * identifiers and wording — each with the ids in its paths templated, so a
+ * lane that reported the pages it visited (`/things/5,/1,/2`) matches the
+ * finding it filed against the route (`/things/:id`).
+ */
 function matchesText(reported, f) {
-    const text = squash(reported);
-    return (text !== "" && f.evidence === text) || restates(text, f) || covers(identifiers(reported), words(reported), f);
+    const text = squash(templateIds(reported));
+    return (text !== "" && f.templated === text) || restates(text, f.templated) || covers(identifiers(reported), words(reported), f);
+}
+/**
+ * Text with every id segment of a path written `:id`: a number, a list of
+ * numbers (`/5,/1,/2`, `/5,1`), or a template (`{thingId}`, `:id`, `*`). Only
+ * after a slash that follows a path segment holding a letter, so a ratio
+ * (`3/4`, `3.1:1`) or a count in the text is left alone.
+ */
+export function templateIds(text) {
+    return text
+        .replace(/(?<=[A-Za-z_}][\w.}-]*)\/\d+(?:\s*,\s*\/?\d+)*(?=$|[/\s,;:)?#\]])/g, "/:id")
+        .replace(/(?<=[A-Za-z_}][\w.}-]*)\/(?:\{[^}/\s]+\}|:[A-Za-z_][A-Za-z0-9_]*|\*)(?=$|[/\s,;)?#\]])/g, "/:id");
 }
 /**
  * Rule 2 of unfiledDefects: the decision names a request that did not fail,
@@ -344,7 +373,7 @@ function restatesRequest(evidence, failing, f) {
         if (!failing.every((sig) => sig.method === r.method && templatedPathsMatch(sig.segments, r.segments)))
             continue;
         const aligned = squash(evidence.slice(0, r.start) + f.raw.slice(paired.start, paired.end) + evidence.slice(r.end));
-        if (aligned !== "" && (f.evidence === aligned || restates(aligned, f) || addsOnlyExpectedStatus(aligned, f.evidence, r.status)))
+        if (aligned !== "" && (f.evidence === aligned || restates(aligned, f.evidence) || addsOnlyExpectedStatus(aligned, f.evidence, r.status)))
             return true;
     }
     return false;
@@ -373,7 +402,9 @@ function addsOnlyExpectedStatus(reported, filed, status) {
 const MIN_RESTATED = 24;
 /** A test id, captured without its attribute; and a kebab-case id of three or more parts. Lowercase text only. */
 const TESTID_RE = /testid=["']?([a-z0-9_-]+)/g;
-const KEBAB_ID_RE = /\b[a-z][a-z0-9]*(?:-[a-z0-9]+){2,}\b/g;
+// Underscores inside a part too: `row-stage-pending_review` is one id, where
+// without them it ended mid-word and yielded none.
+const KEBAB_ID_RE = /\b[a-z][a-z0-9_]*(?:-[a-z0-9_]+){2,}\b/g;
 /**
  * Whether the reported evidence appears word for word inside a finding's
  * evidence: a lane that filed "testid=row-1..6 non-interactive; GET /api/x 200
@@ -384,8 +415,8 @@ const KEBAB_ID_RE = /\b[a-z][a-z0-9]*(?:-[a-z0-9]+){2,}\b/g;
  * refuses. One direction only: a short FILED evidence found inside a longer
  * report proves nothing about the rest of the report.
  */
-function restates(reported, f) {
-    if (reported.length < MIN_RESTATED || !f.evidence.includes(reported))
+function restates(reported, filed) {
+    if (reported.length < MIN_RESTATED || !filed.includes(reported))
         return false;
     const rest = reported.replace(TESTID_RE, " ").replace(KEBAB_ID_RE, " ");
     return words(rest).size >= 2;

package/dist/engine/capture.js

@@ -7,6 +7,7 @@
  * comment runs (docs/ci.md).
  */
 /** CSS pixels kept around the element, so its edges and shadow are in the picture. */
+import { plainSegment } from "./replay.js";
 export const CAPTURE_MARGIN = 8;
 export const MAX_CAPTURE_MARGIN = 64;
 /**
@@ -26,6 +27,18 @@ export function captureClip(box, margin, viewport) {
         return null;
     return { x: left, y: top, width: right - left, height: bottom - top };
 }
+/**
+ * Whether an element itself (its margin aside) reaches outside the viewport
+ * once scrolled into view, so only the part inside is pictured: then a phrase
+ * saying so, for the report; null when all of it is in the picture. A pixel of
+ * slack, for boxes at fractional positions.
+ */
+export function cutByViewport(box, viewport) {
+    const inside = box.x >= -1 && box.y >= -1 && box.x + box.width <= viewport.width + 1 && box.y + box.height <= viewport.height + 1;
+    if (inside)
+        return null;
+    return `only the part inside the ${viewport.width}×${viewport.height} window is pictured: the element is ${Math.round(box.width)}×${Math.round(box.height)}`;
+}
 /** A capture's file name: lower-case letters, digits and dashes, then .png. Nothing else reaches the path. */
 export function captureFileName(name) {
     const base = String(name ?? "")
@@ -119,3 +132,154 @@ export function rebaseUrl(page, fromRoot, toRoot) {
 /** The files a capture run writes, under shots/ in the run's output. Fixed names: nothing a model says becomes a path. */
 export const SHOT_FILES = { preview: "preview.png", base: "base.png", diff: "diff.png" };
 export const SHOTS_DIRNAME = "shots";
+// ── a finding's picture ─────────────────────────────────────────────────────
+//
+// Every finding is filed with a picture of what it is about: the element it
+// names plus a margin, or the viewport when it names none. scout_finding
+// takes the picture (browser.ts), and these rules decide whether one is taken,
+// what it frames, how big it may be, whether the tool result carries it, and
+// where it is kept, so each is table-tested (ci-test) without a browser.
+/**
+ * What happens to a finding's picture. "inline": it is kept under the run's
+ * recordings/ folder, shown in report.html, and returned in the scout_finding
+ * result, so a chat client shows it as the finding is filed. "file": kept and
+ * shown in the report, not returned. "off": none is taken.
+ */
+export const EVIDENCE_MODES = ["inline", "file", "off"];
+export const EVIDENCE_ENV = "SCENESCOUT_EVIDENCE";
+export const EVIDENCE_MAX_PX_ENV = "SCENESCOUT_EVIDENCE_MAX_PX";
+export const EVIDENCE_MAX_KB_ENV = "SCENESCOUT_EVIDENCE_MAX_KB";
+export const EVIDENCE_INLINE_ENV = "SCENESCOUT_EVIDENCE_INLINE";
+export const RECORD_ENV = "SCENESCOUT_RECORD";
+/**
+ * The bounds a finding's picture is held to, and their defaults. The longer
+ * side keeps a picture readable while a chat client's cost for it stays small;
+ * the bytes bound what each picture adds to the conversation and the folder;
+ * the inline count stops a run that files many findings from filling the
+ * conversation with pictures (later ones are still kept and in the report).
+ */
+export const EVIDENCE_LIMITS = {
+    maxPx: { env: EVIDENCE_MAX_PX_ENV, min: 160, max: 2000, default: 800, unit: "pixels on the picture's longer side" },
+    maxKb: { env: EVIDENCE_MAX_KB_ENV, min: 16, max: 2048, default: 200, unit: "kilobytes a picture may take" },
+    inline: { env: EVIDENCE_INLINE_ENV, min: 0, max: 500, default: 10, unit: "pictures one session returns in its scout_finding results" },
+};
+/** CSS pixels kept around an element a finding names: more than scout_capture's, so what is next to it is in view. */
+export const EVIDENCE_MARGIN = 24;
+/** Whether this process runs in a CI job: the CI variable every hosted runner sets, read the way they set it. */
+export function isCiEnv(env) {
+    const ci = (env.CI ?? "").trim().toLowerCase();
+    return (ci !== "" && ci !== "0" && ci !== "false") || (env.GITHUB_ACTIONS ?? "").trim().toLowerCase() === "true";
+}
+function readLimit(kind, env) {
+    const spec = EVIDENCE_LIMITS[kind];
+    const raw = env[spec.env];
+    if (raw === undefined || raw.trim() === "")
+        return spec.default;
+    const text = raw.trim();
+    const value = Number(text);
+    if (!/^\d+$/.test(text) || value < spec.min || value > spec.max)
+        throw new Error(`${spec.env} must be a whole number of ${spec.unit}, from ${spec.min} to ${spec.max} (got "${raw}").`);
+    return value;
+}
+/**
+ * How this session treats a finding's picture: the attach option, else the
+ * environment, else the default for the kind of run. Interactive use returns
+ * the picture inline, which is what a person following the conversation
+ * wants. A CI job keeps it on file only: nobody reads the conversation, and
+ * `scenescout ci`'s model loop is text-only, so an image there is bytes no one
+ * sees. A value outside the known ones is refused, never guessed at.
+ */
+export function evidenceSettings(asked, env) {
+    const limits = { maxPx: readLimit("maxPx", env), maxBytes: readLimit("maxKb", env) * 1024, inlineMax: readLimit("inline", env) };
+    if (asked)
+        return { mode: asked, source: "option", ...limits };
+    const raw = (env[EVIDENCE_ENV] ?? "").trim().toLowerCase();
+    if (raw) {
+        if (!EVIDENCE_MODES.includes(raw))
+            throw new Error(`${EVIDENCE_ENV} must be one of ${EVIDENCE_MODES.join(", ")} (got "${env[EVIDENCE_ENV]}").`);
+        return { mode: raw, source: "environment", ...limits };
+    }
+    return isCiEnv(env) ? { mode: "file", source: "default (CI)", ...limits } : { mode: "inline", source: "default (interactive)", ...limits };
+}
+/**
+ * Whether a session keeps a frame after every action (scout_attach `record`):
+ * the option, else SCENESCOUT_RECORD, else off. Off in every kind of run by
+ * default: a recording is a picture per step of the app under test, and a
+ * team that wants every QA run recorded says so once, in the server's
+ * environment, rather than relying on each attach to ask.
+ */
+export function recordChoice(asked, env) {
+    if (asked !== undefined)
+        return asked;
+    const raw = (env[RECORD_ENV] ?? "").trim().toLowerCase();
+    if (!raw)
+        return false;
+    if (["on", "true", "1"].includes(raw))
+        return true;
+    if (["off", "false", "0"].includes(raw))
+        return false;
+    throw new Error(`${RECORD_ENV} must be on or off (got "${env[RECORD_ENV]}").`);
+}
+/**
+ * Whether a picture is taken for a filing, and of what. None when pictures
+ * are off, when the session has no page open, or when the filing was merged
+ * into a finding that already has its picture (one picture a finding, from
+ * when it was first seen) — unless the merge reopened it as a regression,
+ * when the new picture shows it is back. Otherwise the element the filing
+ * names, else the viewport.
+ */
+export function evidenceFrame(o) {
+    if (o.mode === "off")
+        return { take: false, why: "pictures are off for this session" };
+    if (!o.pageOpen)
+        return { take: false, why: "the session has no page open" };
+    if (!o.isNew && o.hasPicture && !o.regressed)
+        return { take: false, why: "the finding it merged into already has its picture" };
+    const ref = (o.ref ?? "").trim();
+    return ref ? { take: true, frame: "element", ref } : { take: true, frame: "viewport" };
+}
+/** Whether this picture goes into the tool result: inline mode, and the session's count not yet reached. */
+export function returnsInline(mode, shownSoFar, inlineMax) {
+    return mode === "inline" && shownSoFar < inlineMax;
+}
+/**
+ * Where a finding's picture is kept, relative to the project's .scenescout/
+ * folder, with forward slashes: beside the session's recorded frames, so the
+ * report and the live view reach it the way they reach a frame. The session
+ * name is the agent's, so it is reduced to a plain name; the id is the
+ * finding's, which is hex.
+ */
+export function findingPicturePath(session, id) {
+    // The same folder name as the session's frames (replay.ts framePath), so the two sit together.
+    const plain = plainSegment(session, "session");
+    const safeId = id.replace(/[^0-9a-f]/gi, "").slice(0, 40) || "finding";
+    return `recordings/${plain}/finding-${safeId}.png`;
+}
+/**
+ * A finding's picture read back from disk, or null when its path is not one
+ * of the engine's picture paths: the report links only what it can trust.
+ * A shot that does not read is left out, and the path still stands.
+ */
+export function readFindingPicture(f) {
+    const file = f.picture;
+    if (typeof file !== "string" || !/^recordings\/[a-z0-9._-]+\/finding-[0-9a-f]+\.png$/i.test(file))
+        return null;
+    const o = (f.pictureShot && typeof f.pictureShot === "object" ? f.pictureShot : {});
+    if (!Number.isInteger(o.width) || !Number.isInteger(o.height) || (o.frame !== "element" && o.frame !== "viewport"))
+        return { file };
+    return {
+        file,
+        width: o.width,
+        height: o.height,
+        frame: o.frame,
+        ...(typeof o.label === "string" && o.label ? { label: o.label } : {}),
+        at: typeof o.at === "string" ? o.at : "",
+    };
+}
+/** What a picture frames, in words for the report and the tool result. */
+export function describePicture(p) {
+    if (!p.frame || !p.width || !p.height)
+        return "what the page showed";
+    const what = p.frame === "element" ? (p.label ? `"${p.label.replace(/\s+/g, " ").slice(0, 80)}" and around it` : "the element and around it") : "the page as it was";
+    return `${p.width}×${p.height}, ${what}`;
+}