@intentic/sandbox-contract 1.176.3 → 1.209.1

package/src/chores/extension-update.ts

@@ -0,0 +1,37 @@
+import { composeAsk } from "./prompt.js";
+
+/* AN EXTENSION UPDATE, READ AS A DIFF. The commit that is installed was approved once already — re-reading all
+ * of it would bury the one question an update asks: what is different, and did any of it change the deal? So
+ * the turn's subject is the diff between the two commits, and the manifest's delta leads, because a new entry
+ * in `permissions.sandbox` is reach the owner never approved, arriving dressed as an update.
+ *
+ * Here in the contract's chores rather than in the web app, because two callers build it: the update card's
+ * "read the diff" button, and the daemon's agent-prepared update policy — which runs this exact read
+ * unprompted when the registry lists a new sha, so the owner opens a finished account instead of starting one. */
+const UPDATE_INVARIANTS =
+    `This turn reads and reports; it changes nothing and installs nothing. Clone into a scratch directory ` +
+    `outside the workspace and read the diff between the two commits — the installed code was approved once ` +
+    `already, so what is between them is the whole subject. Lead with the manifest's delta: any route added to ` +
+    `\`permissions.sandbox\` is reach the owner never approved and the headline whatever else changed. Then the ` +
+    `code: what behaviour changed, in the owner's terms, citing file and line.`;
+
+export interface UpdateBrief {
+    // The listing's display name, or the repository when it is being installed straight from a URL.
+    readonly label: string;
+    readonly url: string;
+    // What is installed and what the update proposes — both full shas, both facts, neither a branch.
+    readonly fromRef: string;
+    readonly toRef: string;
+    // Subdirectory inside the repository, for a monorepo source. Empty for a repo of its own.
+    readonly path: string;
+}
+
+export const updateBrief = ({ label, url, fromRef, toRef, path }: UpdateBrief): string =>
+    composeAsk({
+        subject: `Read what changed in the ${label} extension before it is updated here: ${url}, from ${fromRef} to ${toRef}${path === `` ? `` : `, in ${path}`}.`,
+        why: `The installed commit was approved once already; the update replaces it wholesale, because the sha is the identity and there is no build step between the pushed bytes and the code that runs.`,
+        diagnosis: `The manifest (intentic-extension.json at the extension root) is the contract on both sides of the diff, so its delta is readable exactly like the code's.`,
+        goal: `Read the diff and say what the update actually is: the manifest delta first, then what the code now does that it did not, and what it stopped doing.`,
+        invariants: UPDATE_INVARIANTS,
+        done: `Done when you end on a recommendation the owner can act on — update, update and watch something named, or stay on ${fromRef.slice(0, 7)} — with the change that decided it cited by file and line.`,
+    });

package/src/chores/fix-deps.ts

@@ -0,0 +1,40 @@
+/* THE FIX CHORE — one definition for the two surfaces that must agree on it.
+ *
+ * The daemon seeds this automation into a workspace (default-automations.ts in the sandbox package) and the
+ * automations extension offers it as a recipe for anyone who deleted it and wants it back. Written once here
+ * for the chore book's own reason: two copies of a prompt drift, and only one of them gets fixed when we
+ * learn how to phrase it.
+ *
+ * It wakes on `deps.broken` — the dependency verifier's edge event: a landed change drifted the installed
+ * dependencies, the daemon reinstalled them, ran the tree's own checks, and they came back red. The payload
+ * is that event: `deps.project` is the project whose checks failed, `deps.command` the exact command that
+ * judged it, `deps.exitCode` and `deps.logTail` what it said, and `deps.attempt` which consecutive red this
+ * is since the last green.
+ *
+ * THE GUARD IS THE LOOP CAP, and it lives in guard shell — one visible, owner-editable line — rather than in
+ * daemon code, because whoever tunes "how many tries before a human looks" must be able to see the number.
+ * Attempt 1 is the breakage, attempt 2 is one landed fix that still failed; past that the loop stops and the
+ * standing red is the owner's to read (the activity feed has been narrating every step).
+ *
+ * THE HOLD IS THE CONSENT. This automation is seeded enabled — the one exception to "the owner started it",
+ * made deliberately: a broken tree costs every conversation that builds on it, and the countdown is what
+ * keeps the owner in charge — each fire is held, visibly, for this many seconds on the Automations page
+ * before it starts, cancellable the whole way, and it never starts while another agent is mid-turn. */
+export const FIX_DEPS_AUTOMATION = {
+    id: "fix-dependency-breakage",
+    title: "Fix what a dependency change broke",
+    event: "deps.broken",
+    holdForSeconds: 60,
+    guard: `test "$(printf '%s' "$AUTOMATION_PAYLOAD" | jq -r '.deps.attempt // 1')" -le 2`,
+    guardNote: "stops after 2 attempts",
+    prompt:
+        "A landed change drifted this workspace's dependencies; the daemon reinstalled them and ran the project's own checks, " +
+        "and they failed. The payload names the project (`deps.project`), the check command (`deps.command`), how it exited " +
+        "(`deps.exitCode`) and the tail of its output (`deps.logTail`); the full log is in the project's `--verify` terminal.\n\n" +
+        "Re-run the check yourself to see the failure first-hand, then fix the ROOT CAUSE. That usually means updating call " +
+        "sites, types or tests to match what actually changed — never loosening or deleting the checks, pinning or downgrading " +
+        "dependencies just to silence them, or editing generated files. If the breakage needs a decision only the owner can " +
+        "make (an intentional breaking upgrade, a license change, a dependency that should be dropped), stop and say exactly " +
+        "that instead of guessing.\n\n" +
+        "Finish by running the same check command and reporting what was broken, what you changed, and whether it is green now.",
+} as const;

package/src/chores/index.ts

@@ -1,9 +1,14 @@
-export { CHORES, choreAutomationPrompt, choreById, chorePrompt, repoLabel } from "./chores.js";
-export type { Chore, ChoreContext, ChoreFinding, ChoreStance } from "./chores.js";
+export { CHORE_KINDS, CHORES, choreAutomationPrompt, choreById, chorePrompt, repoLabel, repoName } from "./chores.js";
+export { FIX_DEPS_AUTOMATION } from "./fix-deps.js";
+export type { Chore, ChoreContext, ChoreFinding, ChoreKind, ChoreKindSpec, ChoreStance } from "./chores.js";
 export { bucketOf, digestOf } from "./digest.js";
 export { CHORE_INVARIANTS, composeAsk, REFACTOR_INVARIANTS, REPORT_INVARIANTS, TRIAGE_NOTE } from "./prompt.js";
 export type { Ask } from "./prompt.js";
+export { updateBrief } from "./extension-update.js";
+export type { UpdateBrief } from "./extension-update.js";
 export { PROBES, probeSpec } from "./probes.js";
 export type { ProbeSpec } from "./probes.js";
+export { componentStem, frameworksOf, IDIOM_RULES, idiomRule, normalizePath, UI_FRAMEWORKS, usesTailwind } from "./stack.js";
+export type { IdiomRule, UiFramework } from "./stack.js";
 export { assessChore, assessReport, ledgerKey, unseenVerdicts } from "./verdict.js";
 export type { ChoreState, ChoreVerdict } from "./verdict.js";

package/src/chores/probes.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vitest";
 import { probeSpec } from "./probes.js";
+import { IDIOM_RULES } from "./stack.js";
 
 /* The parsers are the part of this library that faces someone else's output, so they are tested the way that
  * output actually arrives: real shapes, then the shapes that have historically broken things — a tool that
@@ -30,8 +31,14 @@ describe(`outdated`, () => {
     });
 
     test(`skips entries pnpm could not resolve, rather than inventing a version for them`, () => {
-        const facts = parse(`outdated`, JSON.stringify({ ok: { current: `1.0.0`, latest: `2.0.0` }, broken: { current: `1.0.0` }, alsoBroken: null }));
-        expect(facts).toEqual({ id: `outdated`, packages: [{ name: `ok`, current: `1.0.0`, latest: `2.0.0`, kind: `major`, section: `dependencies` }] });
+        const facts = parse(
+            `outdated`,
+            JSON.stringify({ ok: { current: `1.0.0`, latest: `2.0.0` }, broken: { current: `1.0.0` }, alsoBroken: null }),
+        );
+        expect(facts).toEqual({
+            id: `outdated`,
+            packages: [{ name: `ok`, current: `1.0.0`, latest: `2.0.0`, kind: `major`, section: `dependencies` }],
+        });
     });
 
     // pnpm prints deprecation and lockfile notices on the same stream in some versions; the JSON still has to be
@@ -94,7 +101,14 @@ describe(`knip`, () => {
             `knip`,
             JSON.stringify({
                 issues: [
-                    { file: `src/a.ts`, exports: [{ name: `x` }, { name: `y` }], types: [{ name: `T` }], dependencies: [{ name: `lodash` }], devDependencies: [], files: [] },
+                    {
+                        file: `src/a.ts`,
+                        exports: [{ name: `x` }, { name: `y` }],
+                        types: [{ name: `T` }],
+                        dependencies: [{ name: `lodash` }],
+                        devDependencies: [],
+                        files: [],
+                    },
                     { file: `src/b.ts`, exports: [{ name: `z` }], types: [], dependencies: [], devDependencies: [{ name: `jest` }], files: [] },
                     { file: `src/old.ts`, exports: [], files: [{ name: `src/old.ts` }] },
                     { file: `src/older.ts`, exports: [], files: [{ name: `src/older.ts` }] },
@@ -164,3 +178,141 @@ describe(`jscpd`, () => {
         expect(parse(`jscpd`, ``)).toBeUndefined();
     });
 });
+
+/* The UI sweep is the one probe whose output we produce ourselves, which removes the "their JSON moved" failure
+ * and replaces it with a worse one: a command of eleven piped ripgreps in which any single stage can silently
+ * contribute nothing. The marker line is what tells those two apart, and most of what is below is about it. */
+describe(`ui`, () => {
+    const sweep = (...lines: readonly string[]) => [`UI`, ...lines].join(`\n`);
+
+    test(`sorts the labelled lines into an inventory, per-file counts and idioms`, () => {
+        const facts = parse(
+            `ui`,
+            sweep(
+                `COMPONENT\tsrc/Button.vue`,
+                `COMPONENT\tsrc/Card.tsx`,
+                `BYPASS\tsrc/Button.vue:3`,
+                `IDIOM\tvue-options-api\tsrc/Button.vue`,
+                `IDIOM\tvue-2-lifecycle\tsrc/Button.vue`,
+                `IDIOM\tvue-options-api\tsrc/Old.vue`,
+            ),
+        );
+        expect(facts).toEqual({
+            id: `ui`,
+            scan: {
+                components: [`src/Button.vue`, `src/Card.tsx`],
+                bypasses: [{ path: `src/Button.vue`, count: 3 }],
+                idioms: [
+                    { id: `vue-options-api`, files: [`src/Button.vue`, `src/Old.vue`] },
+                    { id: `vue-2-lifecycle`, files: [`src/Button.vue`] },
+                ],
+            },
+        });
+    });
+
+    /* The distinction the marker exists for, and the one this whole probe would get wrong without it: a
+     * repository with no components and no findings emits exactly the marker, while a sweep that never ran emits
+     * nothing. Collapsing them would report a spotless front-end for a command that failed to start. */
+    test(`the marker alone is a clean repository`, () => {
+        expect(parse(`ui`, sweep())).toEqual({ id: `ui`, scan: { components: [], bypasses: [], idioms: [] } });
+    });
+
+    test(`output with no marker is a failure, however much of it there is`, () => {
+        expect(parse(`ui`, ``)).toBeUndefined();
+        expect(parse(`ui`, `COMPONENT\tsrc/Button.vue`)).toBeUndefined();
+        expect(parse(`ui`, `rg: unrecognized flag --count-matches`)).toBeUndefined();
+    });
+
+    // A path with a colon in it is legal and rare; the count is always the digits after the last one.
+    test(`splits a count off the end of a path that contains a colon`, () => {
+        expect(parse(`ui`, sweep(`BYPASS\tsrc/weird:name.vue:7`))).toMatchObject({ scan: { bypasses: [{ path: `src/weird:name.vue`, count: 7 }] } });
+    });
+
+    test(`a line that is not a count is dropped rather than counted as zero`, () => {
+        expect(parse(`ui`, sweep(`BYPASS\tsrc/Button.vue`, `BYPASS\tsrc/Card.tsx:notanumber`))).toMatchObject({ scan: { bypasses: [] } });
+    });
+
+    /* Every path the sweep prints wears a `./`, because every ripgrep in it is handed `.` to walk. Downstream this
+     * would have to be remembered at each comparison — jscpd's paths against the component list, a bypass against
+     * a component — so it is spent once, here, and one spelling of a path leaves the parser. */
+    test(`strips the prefix ripgrep prints for a path it was told to walk`, () => {
+        expect(parse(`ui`, sweep(`COMPONENT\t./src/Button.vue`, `BYPASS\t./src/Button.vue:3`, `IDIOM\tvue-options-api\t./src/Old.vue`))).toEqual({
+            id: `ui`,
+            scan: {
+                components: [`src/Button.vue`],
+                bypasses: [{ path: `src/Button.vue`, count: 3 }],
+                idioms: [{ id: `vue-options-api`, files: [`src/Old.vue`] }],
+            },
+        });
+    });
+
+    test(`an idiom line naming no file is dropped rather than recorded as an empty path`, () => {
+        expect(parse(`ui`, sweep(`IDIOM\tvue-options-api`, `IDIOM\tvue-options-api\t`))).toMatchObject({ scan: { idioms: [] } });
+    });
+});
+
+/* THE COMMAND ITSELF, which for this probe is generated and therefore the thing to test. Both cases below are
+ * bugs that reached a real repository and could not be seen in the output: one made the sweep silently empty, the
+ * other made it depend on a ripgrep feature that is a compile-time option. */
+describe(`the sweep's composed command`, () => {
+    const stages = (): string[] => probeSpec(`ui`).command.split(`; `);
+
+    /* Given no path, ripgrep searches STDIN whenever stdin is not a TTY — which is exactly how a probe is spawned.
+     * The sweep exited 0, printed its marker and matched nothing, in every repository, forever, which the marker
+     * line cannot catch because the sweep really did run. It reproduces from a child process and never from an
+     * interactive shell, so the command is the only place it is visible. */
+    test(`every ripgrep is given a path to walk, including the availability gate`, () => {
+        const searches = stages().filter((stage) => stage.startsWith(`rg `));
+        expect(searches).toHaveLength(IDIOM_RULES.length + 2);
+        for (const search of searches) {
+            expect(search.split(`2>/dev/null`)[0], search).toMatch(/ \.\s*$/);
+        }
+        expect(probeSpec(`ui`).available).toMatch(/ \. >\/dev\/null$/);
+    });
+
+    test(`an absent rule asks which files do NOT match, and no rule reaches for PCRE2`, () => {
+        for (const rule of IDIOM_RULES) {
+            const stage = stages().find((part) => part.includes(`"IDIOM\\t${rule.id}\\t"`));
+            expect(stage, rule.id).toContain(rule.absent === undefined ? `rg --no-messages -l ` : `rg --no-messages --files-without-match `);
+        }
+        expect(probeSpec(`ui`).command).not.toContain(`-P `);
+    });
+});
+
+describe(`bundle`, () => {
+    test(`reads the directory and each asset's raw and gzipped size`, () => {
+        const facts = parse(
+            `bundle`,
+            [`DIR\tdist`, `ASSET\t54038\t41096\tdist/assets/vendor-abc.js`, `ASSET\t2704\t2103\tdist/assets/style.css`].join(`\n`),
+        );
+        expect(facts).toEqual({
+            id: `bundle`,
+            bundle: {
+                dir: `dist`,
+                totalBytes: 56742,
+                totalGzip: 43199,
+                assets: [
+                    { path: `dist/assets/vendor-abc.js`, bytes: 54038, gzip: 41096 },
+                    { path: `dist/assets/style.css`, bytes: 2704, gzip: 2103 },
+                ],
+            },
+        });
+    });
+
+    // The `find` prints nothing for a directory that exists but holds no assets. `available` is supposed to catch
+    // that, and this is the second line of defence — a zero-byte bundle would otherwise read as a fact.
+    test(`a directory line with no assets is an empty build, not a failure`, () => {
+        expect(parse(`bundle`, `DIR\tbuild`)).toMatchObject({ bundle: { dir: `build`, assets: [], totalBytes: 0, totalGzip: 0 } });
+    });
+
+    test(`no directory line is a failure`, () => {
+        expect(parse(`bundle`, ``)).toBeUndefined();
+        expect(parse(`bundle`, `find: dist: No such file or directory`)).toBeUndefined();
+    });
+
+    test(`an asset whose sizes did not come through is skipped, never counted as zero bytes`, () => {
+        expect(parse(`bundle`, [`DIR\tdist`, `ASSET\t\t\tdist/broken.js`, `ASSET\t10\t5\tdist/ok.js`].join(`\n`))).toMatchObject({
+            bundle: { assets: [{ path: `dist/ok.js`, bytes: 10, gzip: 5 }] },
+        });
+    });
+});

package/src/chores/probes.ts

@@ -1,4 +1,15 @@
-import type { Advisory, DeadCode, Duplication, OutdatedPackage, ProbeFacts, ProbeId } from "../schemas.js";
+import type { Advisory, Bundle, DeadCode, Duplication, OutdatedPackage, ProbeFacts, ProbeId, UiScan } from "../schemas.js";
+import type { IdiomRule } from "./stack.js";
+import {
+    BYPASS_PATTERN,
+    COMPONENT_GLOBS,
+    IDIOM_RULES,
+    MARKUP_GLOBS,
+    normalizePath,
+    SCAN_IGNORES,
+    UI_FRAMEWORKS,
+    TAILWIND_PACKAGES,
+} from "./stack.js";
 
 /* THE PROBES — the measurements that cost a subprocess, declared once so the daemon that runs them and the panel
  * that explains them cannot disagree about what "outdated" meant.
@@ -68,7 +79,11 @@ const countOf = (value: unknown): number => (Array.isArray(value) ? value.length
 
 // Which semver step separates two versions. Compared as leading integers rather than by a semver library: the
 // only question is which position first differs, and prerelease/build metadata cannot change that answer.
-const versionParts = (version: string): number[] => version.replace(/^[^\d]*/, ``).split(`.`).map((part) => Number.parseInt(part, 10) || 0);
+const versionParts = (version: string): number[] =>
+    version
+        .replace(/^[^\d]*/, ``)
+        .split(`.`)
+        .map((part) => Number.parseInt(part, 10) || 0);
 
 const semverKind = (current: string, latest: string): OutdatedPackage["kind"] => {
     const [currentMajor = 0, currentMinor = 0] = versionParts(current);
@@ -195,18 +210,162 @@ const parseJscpd = (stdout: string): ProbeFacts | undefined => {
     const total = (statistics as Record<string, unknown>)[`total`];
     const percentage = typeof total === `object` && total !== null ? (total as Record<string, unknown>)[`percentage`] : undefined;
     const duplicates = Array.isArray(root?.[`duplicates`]) ? (root[`duplicates`] as Record<string, unknown>[]) : [];
-    const pathOf = (side: unknown): string => (typeof side === `object` && side !== null ? (asString((side as Record<string, unknown>)[`name`]) ?? `?`) : `?`);
+    const pathOf = (side: unknown): string =>
+        typeof side === `object` && side !== null ? (asString((side as Record<string, unknown>)[`name`]) ?? `?`) : `?`;
     const duplication: Duplication = {
         percentage: typeof percentage === `number` ? percentage : 0,
         clones: duplicates.length,
         top: duplicates
-            .map((clone) => ({ lines: typeof clone[`lines`] === `number` ? clone[`lines`] : 0, first: pathOf(clone[`firstFile`]), second: pathOf(clone[`secondFile`]) }))
+            .map((clone) => ({
+                lines: typeof clone[`lines`] === `number` ? clone[`lines`] : 0,
+                first: pathOf(clone[`firstFile`]),
+                second: pathOf(clone[`secondFile`]),
+            }))
             .toSorted((left, right) => right.lines - left.lines)
             .slice(0, DUPLICATION_SAMPLE),
     };
     return { id: `jscpd`, duplication };
 };
 
+/* THE UI SWEEP. The only probe here whose command is COMPOSED rather than written out, because its subject is a
+ * table (stack.ts) that will grow and a hand-written command would be a second copy of it going stale.
+ *
+ * Everything it emits is a labelled, tab-separated line, and the first line is always the bare marker `UI`. That
+ * marker is the whole reason this parser can tell "the sweep ran and this repository is clean" from "the sweep
+ * never ran": every other line is optional, so without it an empty stdout and a spotless codebase are the same
+ * string — and reporting the second when it was the first is the one thing probes.ts exists to prevent. */
+const UI_MARKER = `UI`;
+// Caps, applied after `sort` so truncation is alphabetical and therefore identical between runs — an unsorted
+// truncation would mint a new digest on every sweep and badge forever. What is dropped is genuinely dropped: a
+// component past the cap cannot join a family, and the chore says so rather than implying it saw everything.
+const COMPONENT_LIMIT = 2000;
+const RULE_FILE_LIMIT = 500;
+
+/* THE `.` IS LOAD-BEARING, and leaving it off cost this probe every finding it will ever have. Given no path,
+ * ripgrep searches the tree only when stdin is a TTY — otherwise it reads STDIN, which is exactly how the runner
+ * spawns a probe. The sweep therefore ran, exited 0, printed its marker and matched nothing, in every repository,
+ * forever: the precise failure the marker line was introduced to make impossible, arriving through the one door it
+ * does not cover. It reproduces from Node and not from an interactive shell, which is why it survived being read.
+ *
+ * The prefix that comes back with it (`./src/Button.vue`) is normalised away at the parse, so one spelling of a
+ * path reaches the chores no matter which tool produced it. */
+const SCAN_ROOT = `.`;
+
+const globArgs = (globs: readonly string[]): string => [...globs, ...SCAN_IGNORES].map((glob) => `-g '${glob}'`).join(` `);
+
+// `path:count` from `rg --count-matches`, normalised. Split at the LAST colon: a path may contain one, a count is
+// always the digits at the end.
+const splitCount = (text: string): { path: string; count: number } | undefined => {
+    const at = text.lastIndexOf(`:`);
+    if (at <= 0) {
+        return undefined;
+    }
+    const count = Number.parseInt(text.slice(at + 1), 10);
+    return Number.isNaN(count) || count <= 0 ? undefined : { path: normalizePath(text.slice(0, at)), count };
+};
+
+/* An idiom's line is a PATH AND NOTHING ELSE, which is what lets one line shape carry both kinds of rule. A
+ * present rule asks ripgrep which files match (`-l`); an absent one asks which files do not (`--files-without-
+ * match`), and neither has a count to report. Nothing downstream ever wanted one: a file is on the old idiom or
+ * it is not, and how many times it says so within itself is not a fact anyone would act on differently. */
+const idiomCommand = (rule: IdiomRule): string =>
+    `rg --no-messages ${rule.absent === undefined ? `-l` : `--files-without-match`} -e '${rule.pattern}' ${globArgs(rule.globs)} ${SCAN_ROOT} 2>/dev/null ` +
+    `| sort | head -n ${RULE_FILE_LIMIT} | awk '{print "IDIOM\\t${rule.id}\\t" $0}'`;
+
+const scanCommand = (): string =>
+    [
+        `echo ${UI_MARKER}`,
+        `rg --files ${globArgs(COMPONENT_GLOBS)} ${SCAN_ROOT} 2>/dev/null | sort | head -n ${COMPONENT_LIMIT} | awk '{print "COMPONENT\\t" $0}'`,
+        `rg --no-messages --count-matches -e '${BYPASS_PATTERN}' ${globArgs(MARKUP_GLOBS)} ${SCAN_ROOT} 2>/dev/null ` +
+            `| sort | head -n ${RULE_FILE_LIMIT} | awk '{print "BYPASS\\t" $0}'`,
+        ...IDIOM_RULES.map(idiomCommand),
+        // Every rg above exits 1 when it matches nothing, which is the healthy case and must not read as a broken
+        // command. The runner judges by the parse, but leaving the script's own status at 1 would be a lie.
+        `true`,
+    ].join(`; `);
+
+const parseUi = (stdout: string): ProbeFacts | undefined => {
+    const lines = stdout.split(`\n`).map((line) => line.trim());
+    if (lines.find((line) => line !== ``) !== UI_MARKER) {
+        return undefined;
+    }
+    const components: string[] = [];
+    const bypasses: UiScan["bypasses"] = [];
+    const byIdiom = new Map<string, string[]>();
+    for (const line of lines) {
+        const [label, ...rest] = line.split(`\t`);
+        if (label === `COMPONENT` && rest[0] !== undefined) {
+            components.push(normalizePath(rest[0]));
+        } else if (label === `BYPASS`) {
+            const hit = splitCount(rest.join(`\t`));
+            if (hit !== undefined) {
+                bypasses.push(hit);
+            }
+        } else if (label === `IDIOM` && rest[0] !== undefined) {
+            const path = normalizePath(rest.slice(1).join(`\t`));
+            if (path !== ``) {
+                byIdiom.set(rest[0], [...(byIdiom.get(rest[0]) ?? []), path]);
+            }
+        }
+    }
+    const scan: UiScan = { components, bypasses, idioms: [...byIdiom].map(([id, files]) => ({ id, files })) };
+    return { id: `ui`, scan };
+};
+
+/* THE BUILD OUTPUT, measured where it already is. See BundleSchema for why this never runs the build; the
+ * consequence here is that `available` is a question about the filesystem rather than about the toolchain, and a
+ * repository whose only builds happen in CI reports `unavailable` rather than a wrong number. */
+const BUILD_DIRS = [`dist`, `build`, `out`, `public/build`];
+const BUNDLE_MARKER = `DIR`;
+// Enough of the ranking to see the shape of a build. Past this the assets are the long tail of lazy chunks, and
+// carrying four hundred of them on a route the rail badge polls would cost more than the finding is worth.
+const ASSET_LIMIT = 40;
+
+const bundleCommand = (): string =>
+    [
+        `dir=""`,
+        `for d in ${BUILD_DIRS.join(` `)}; do if [ -d "$d" ]; then dir="$d"; break; fi; done`,
+        `[ -n "$dir" ] || exit 0`,
+        `printf '${BUNDLE_MARKER}\\t%s\\n' "$dir"`,
+        // `-exec ... {} +` rather than a `for` over command substitution: a hashed asset name will not contain a
+        // space, but a build that copies user content into the output can, and a probe is not the place to find
+        // out. Sorted by raw bytes so the head is the ranking rather than whatever order the walk returned.
+        `find "$dir" -type f \\( -name '*.js' -o -name '*.mjs' -o -name '*.cjs' -o -name '*.css' \\) ` +
+            `-exec sh -c 'for f; do printf "ASSET\\t%s\\t%s\\t%s\\n" "$(wc -c <"$f")" "$(gzip -c "$f" | wc -c)" "$f"; done' _ {} + ` +
+            `2>/dev/null | sort -k2 -rn | head -n ${ASSET_LIMIT}`,
+    ].join(`; `);
+
+const parseBundle = (stdout: string): ProbeFacts | undefined => {
+    const lines = stdout.split(`\n`).map((line) => line.trim());
+    const dirLine = lines.find((line) => line.startsWith(`${BUNDLE_MARKER}\t`));
+    if (dirLine === undefined) {
+        return undefined;
+    }
+    const assets: Bundle["assets"] = [];
+    for (const line of lines) {
+        const [label, rawBytes, rawGzip, ...path] = line.split(`\t`);
+        if (label !== `ASSET` || path.length === 0) {
+            continue;
+        }
+        const bytes = Number.parseInt(rawBytes ?? ``, 10);
+        const gzip = Number.parseInt(rawGzip ?? ``, 10);
+        if (Number.isNaN(bytes) || Number.isNaN(gzip)) {
+            continue;
+        }
+        assets.push({ path: path.join(`\t`), bytes, gzip });
+    }
+    const bundle: Bundle = {
+        dir: dirLine.slice(BUNDLE_MARKER.length + 1),
+        // Of the assets CARRIED, which is the top of the ranking rather than the whole build. The chore says so
+        // when it quotes the number: a total that silently excluded the tail would be the more misleading of the
+        // two, and re-walking the tree to sum it would double the probe's cost for a figure nobody splits on.
+        totalBytes: assets.reduce((sum, asset) => sum + asset.bytes, 0),
+        totalGzip: assets.reduce((sum, asset) => sum + asset.gzip, 0),
+        assets,
+    };
+    return { id: `bundle`, bundle };
+};
+
 // Where the tier-2 tools leave their reports. Under /tmp because they are inputs to a parse that happens
 // immediately after, never something to keep — the cached ProbeResult is the artefact that survives. The same
 // path the scheduled form of this chore uses (chores.ts), so a workspace running both keeps one copy.
@@ -271,6 +430,43 @@ export const PROBES: readonly ProbeSpec[] = [
             `cat ${JSCPD_DIR}/jscpd-report.json 2>/dev/null`,
         parse: parseJscpd,
     },
+    {
+        id: `ui`,
+        title: `Front-end source`,
+        measures: `components, hard-coded styles and idioms the framework has replaced`,
+        /* Tier 1 despite reading the whole tree, and the placement is a judgement rather than an oversight. The
+         * tier is about COST: this is a dozen ripgrep walks, seconds on a large monorepo, against knip
+         * type-checking the tree and jscpd tokenizing every file for minutes. A weekly TTL would also make it the
+         * wrong shape — its findings move whenever someone writes a component, which is daily. */
+        tier: 1,
+        ttlMs: DAY_MS,
+        timeoutMs: 5 * 60_000,
+        // Any manifest in the repo declaring a UI framework or Tailwind, not just the root's — a monorepo keeps
+        // React in the app package and the root manifest is a handful of build tools.
+        available:
+            `rg -l --no-messages -g '**/package.json' -g '!**/node_modules/**' ` +
+            `-e '[\\x22](${[...UI_FRAMEWORKS.flatMap((framework) => framework.packages), ...TAILWIND_PACKAGES].join(`|`)})[\\x22]\\s*:' . >/dev/null`,
+        unavailable: `no package here declares a UI framework or Tailwind`,
+        command: scanCommand(),
+        parse: parseUi,
+    },
+    {
+        id: `bundle`,
+        title: `Build output`,
+        measures: `what the last build put on disk for a browser to download`,
+        tier: 1,
+        ttlMs: DAY_MS,
+        timeoutMs: 5 * 60_000,
+        // A build directory that actually contains something a browser would download. `-d` alone would pass on
+        // the empty `dist/` a cleaned checkout leaves behind, and the measurement would report a zero-byte bundle
+        // as a fact about the application.
+        available: `find ${BUILD_DIRS.join(` `)} -maxdepth 4 -type f \\( -name '*.js' -o -name '*.mjs' -o -name '*.css' \\) 2>/dev/null | head -n 1 | grep -q .`,
+        // Says what is missing AND that this never builds, because the obvious reading of "no build output" is
+        // that we tried and it failed. The owner running their own build once is the whole fix.
+        unavailable: `no build output on disk — this reads the last build, it never runs one`,
+        command: bundleCommand(),
+        parse: parseBundle,
+    },
 ];
 
 export const probeSpec = (id: ProbeId): ProbeSpec => {

package/src/chores/stack.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "vitest";
+import { componentStem, frameworksOf, IDIOM_RULES, idiomRule, UI_FRAMEWORKS, usesTailwind } from "./stack.js";
+
+/* The table's own invariants, and the name normaliser under it.
+ *
+ * Most of what is below guards a failure that CANNOT be seen by reading the table: a pattern is interpolated into
+ * a shell command that runs on someone else's machine at three in the morning, so a stray quote is not a typo
+ * anyone reviews — it is a probe that dies in a workspace nobody is watching, with a shell error for a reason. */
+
+describe(`the patterns are safe to interpolate`, () => {
+    // The scan wraps every pattern and glob in shell single quotes. One apostrophe inside ends the quoting and
+    // hands the remainder of the regex to sh, which is how a pattern becomes a command.
+    test(`no pattern or glob contains an apostrophe`, () => {
+        for (const rule of IDIOM_RULES) {
+            expect(rule.pattern, rule.id).not.toContain(`'`);
+            for (const glob of rule.globs) {
+                expect(glob, rule.id).not.toContain(`'`);
+            }
+        }
+    });
+
+    // Not the dialect ripgrep will use, but it catches the unbalanced bracket and the stray backslash, which is
+    // what actually goes wrong when someone adds a rule.
+    test(`every pattern parses as a regex`, () => {
+        for (const rule of IDIOM_RULES) {
+            expect(() => new RegExp(rule.pattern), rule.id).not.toThrow();
+        }
+    });
+
+    /* Rust's regex crate has no lookaround, and getting it means ripgrep's -P, which is a compile-time option on
+     * the box the sweep happens to run on. A rule that seems to need one is asking a question about the FILE
+     * rather than about a line — which is what `absent` is. */
+    test(`no pattern uses a lookaround`, () => {
+        for (const rule of IDIOM_RULES) {
+            expect(rule.pattern, rule.id).not.toMatch(/\(\?<?[=!]/);
+        }
+    });
+
+    /* An absent rule's population is every file its globs match, so a glob that is merely broad on a normal rule
+     * is catastrophic on this one: `*.ts` would name every TypeScript file in the repository as legacy code. A
+     * component extension is safe because every file wearing it is the thing the migration is about. */
+    test(`an absent rule is scoped to a component file type, never to a whole language`, () => {
+        for (const rule of IDIOM_RULES.filter((candidate) => candidate.absent !== undefined)) {
+            for (const glob of rule.globs) {
+                expect([`*.ts`, `*.js`, `*.mts`, `*.cts`, `*.mjs`, `*.cjs`], rule.id).not.toContain(glob);
+            }
+        }
+    });
+
+    test(`every rule has a unique id and belongs to a framework in the table`, () => {
+        const ids = new Set(IDIOM_RULES.map((rule) => rule.id));
+        expect(ids.size).toBe(IDIOM_RULES.length);
+        for (const rule of IDIOM_RULES) {
+            expect(
+                UI_FRAMEWORKS.map((framework) => framework.id),
+                rule.id,
+            ).toContain(rule.framework);
+        }
+    });
+
+    // The chore names the replacement in its prompt; a rule without one would wake an agent, tell it what to stop
+    // doing and leave it to guess a destination.
+    test(`every rule names what replaced it`, () => {
+        for (const rule of IDIOM_RULES) {
+            expect(rule.replacement.length, rule.id).toBeGreaterThan(3);
+        }
+    });
+
+    test(`idiomRule finds a rule the scan reports, and admits when it cannot`, () => {
+        expect(idiomRule(`vue-options-api`)?.framework).toBe(`vue`);
+        expect(idiomRule(`from-a-newer-daemon`)).toBeUndefined();
+    });
+});
+
+describe(`recognising the stack`, () => {
+    test(`a framework is recognised from any manifest's dependency names`, () => {
+        expect(frameworksOf([`vue`, `vite`]).map((framework) => framework.id)).toEqual([`vue`]);
+        expect(frameworksOf([`react`, `@angular/core`]).map((framework) => framework.id)).toEqual([`react`, `angular`]);
+        expect(frameworksOf([`pino`, `zod`])).toEqual([]);
+    });
+
+    // A near-miss must not read as a hit: plenty of packages are named after the framework they plug into, and
+    // `@vueuse/core` in a repo with no Vue is a dependency somebody left behind rather than a Vue application.
+    test(`a package merely named after a framework is not that framework`, () => {
+        expect(frameworksOf([`@vueuse/core`, `react-hook-form`, `eslint-plugin-vue`])).toEqual([]);
+    });
+
+    test(`Tailwind is recognised on its own, without a framework`, () => {
+        expect(usesTailwind([`tailwindcss`])).toBe(true);
+        expect(usesTailwind([`@tailwindcss/typography`])).toBe(false);
+    });
+});
+
+/* THE NORMALISER, which is the whole evidence of the component-overlap chore and therefore the place a false
+ * finding would come from. Each case below is a family that must form, or one that must not. */
+describe(`the name two components share`, () => {
+    test(`framework and qualifier noise falls away`, () => {
+        expect(componentStem(`src/components/Button.vue`)).toBe(`button`);
+        expect(componentStem(`src/ui/BaseButton.vue`)).toBe(`button`);
+        expect(componentStem(`src/legacy/ButtonV2.tsx`)).toBe(`button`);
+        expect(componentStem(`src/app/user-card.component.ts`)).toBe(`usercard`);
+        expect(componentStem(`src/UserCard.tsx`)).toBe(`usercard`);
+    });
+
+    // Every barrel file in the repository is called this. A family of forty is a fact about the convention, not
+    // about duplication, and it would be the largest finding in every repo that has one.
+    test(`index files never form a family`, () => {
+        expect(componentStem(`src/components/Button/index.tsx`)).toBeUndefined();
+    });
+
+    /* The trap in stripping a trailing number. `H1` and `H2` are different components and reduce to the same
+     * single letter, so the stem is only accepted when what survives is still long enough to mean something —
+     * otherwise the untouched name is kept and the two stay apart. */
+    test(`short names keep their digits rather than collapsing together`, () => {
+        expect(componentStem(`src/type/H1.tsx`)).toBe(`h1`);
+        expect(componentStem(`src/type/H2.tsx`)).toBe(`h2`);
+        expect(componentStem(`src/type/H1.tsx`)).not.toBe(componentStem(`src/type/H2.tsx`));
+    });
+
+    // Same guard on the prefix side: `Theme` begins with `the`, and stripping it would leave `me` and put Theme
+    // in a family with anything else that reduced to it.
+    test(`a word that merely starts with a qualifier is left alone`, () => {
+        expect(componentStem(`src/Theme.tsx`)).toBe(`theme`);
+        expect(componentStem(`src/TheHeader.vue`)).toBe(`header`);
+    });
+});