@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/chores/stack.test.ts

@@ -1,15 +1,10 @@
 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. */
+// Guards shell-safety of interpolated patterns (checked unattended on a remote machine) and the stem normalizer below
+// the table.
 
 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(`'`);
@@ -19,26 +14,18 @@ describe(`the patterns are safe to interpolate`, () => {
         }
     });
 
-    // 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) {
@@ -58,8 +45,6 @@ describe(`the patterns are safe to interpolate`, () => {
         }
     });
 
-    // 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);
@@ -72,12 +57,8 @@ describe(`the patterns are safe to interpolate`, () => {
     });
 });
 
-/* THE PATTERNS AGAINST LINES, which is the only place a false finding can be caught before a reader is told to go
- * and fix one. The invariants above ask whether a rule is well formed; these ask whether it is right, and the cases
- * are lines from real files rather than invented ones.
- *
- * Only the rule whose names are ordinary words is covered here. `@NgModule(` and `ReactDOM.render(` cannot be
- * mistaken for anything, and a test that restated them would be asserting that a literal is itself. */
+// Only rule names built from ordinary words are tested against real lines; `@NgModule(` and `ReactDOM.render(` can't be
+// mistaken for anything else.
 describe(`the Vue 2 teardown hooks`, () => {
     const hits = (line: string): boolean => new RegExp(idiomRule(`vue-2-lifecycle`)?.pattern ?? `(?:)`).test(line);
 
@@ -86,13 +67,9 @@ describe(`the Vue 2 teardown hooks`, () => {
         expect(hits(`    beforeDestroy() {`)).toBe(true);
         expect(hits(`    destroyed: function () {`)).toBe(true);
         expect(hits(`    destroyed: async () => {`)).toBe(true);
-        // The name is Vue's alone, so it is the finding whatever it is assigned.
         expect(hits(`    beforeDestroy: this.teardown,`)).toBe(true);
     });
 
-    /* The finding this rule really produced, against a module that deletes idle machines. Every line below is a
-     * fact about a tally, and a chore that reads them as a lifecycle hook sends its reader at a file with no
-     * component in it. */
     test(`a field named after the word is not a hook`, () => {
         expect(hits(`): Promise<{ warned: number; destroyed: number; dropped: number }> => {`)).toBe(false);
         expect(hits(`    const tally = { warned: 0, destroyed: 0, dropped: 0 };`)).toBe(false);
@@ -101,8 +78,6 @@ describe(`the Vue 2 teardown hooks`, () => {
         expect(hits(`type IdleVerdict = "kept" | "warned" | "destroyed" | "dropped";`)).toBe(false);
     });
 
-    // The other half of the same guard: the pattern above is only ever asked about a component file, so a backend
-    // module is not eligible for this finding whatever it happens to name a variable.
     test(`the sweep asks the question of components only`, () => {
         expect(idiomRule(`vue-2-lifecycle`)?.globs).toEqual([`*.vue`]);
     });
@@ -115,8 +90,6 @@ describe(`recognising the stack`, () => {
         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([]);
     });
@@ -127,8 +100,8 @@ describe(`recognising the stack`, () => {
     });
 });
 
-/* 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. */
+// The stem normalizer is the component-overlap chore's only evidence; each case is a family that must form, or must
+// not.
 describe(`the name two components share`, () => {
     test(`framework and qualifier noise falls away`, () => {
         expect(componentStem(`src/components/Button.vue`)).toBe(`button`);
@@ -138,15 +111,10 @@ describe(`the name two components share`, () => {
         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 same argument, for the names the framework hands out rather than the author. A monorepo has one root
-     * per app and a Next App Router has one `page` per route, so these families form by construction: the thirty
-     * `page.tsx` of a thirty-route app would sort above every real finding the chore has. */
     test(`framework entry names never form a family`, () => {
         expect(componentStem(`apps/web/src/App.vue`)).toBeUndefined();
         expect(componentStem(`apps/desktop/src/App.vue`)).toBeUndefined();
@@ -155,25 +123,18 @@ describe(`the name two components share`, () => {
         expect(componentStem(`app/settings/not-found.tsx`)).toBeUndefined();
     });
 
-    // …and only on the whole name. A component that merely BEGINS with one is the author's own and keeps its
-    // stem, or the guard above would swallow half the components in a repo that prefixes them.
     test(`a component that only starts with a framework name is kept`, () => {
         expect(componentStem(`src/shell/AppShell.vue`)).toBe(`appshell`);
         expect(componentStem(`src/ErrorBoundary.tsx`)).toBe(`errorboundary`);
         expect(componentStem(`src/PageHeader.vue`)).toBe(`pageheader`);
     });
 
-    /* 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`);

package/src/chores/stack.ts

@@ -1,45 +1,24 @@
-/* WHAT THIS REPOSITORY IS BUILT WITH, and the patterns that follow from it, the table the UI chores are written
- * against, kept apart from both the probe that runs it and the chores that read it.
- *
- * It sits in the middle on purpose. probes.ts composes ONE ripgrep sweep out of the rules below, and chores.ts
- * turns the counts that come back into findings and prose. Put the rules in either of those and the other one
- * grows a copy: the probe would hard-code patterns the chore has to describe in words, or the chore would restate
- * globs the probe already walked. Both copies would then be free to disagree about what a component is.
- *
- * NOTHING HERE IS A VERDICT. A framework is a set of dependency names, an idiom is a regex and the name of what
- * replaced it. Which of those amount to work worth doing is the chore book's judgement, made in chores.ts against
- * the same three rules everything else there obeys.
- *
- * THE PATTERNS ARE RIPGREP'S DIALECT, and they carry two constraints that are not obvious from reading them:
- *
- *   No literal apostrophe, ever. The scan command wraps each pattern in shell single quotes, so a `'` inside one
- *   would end the quoting and hand the rest of the regex to the shell. Match quotes as `[\x22\x27]` instead,
- *   Rust's regex crate reads those escapes, and the shell never sees a quote character at all. stack.test.ts
- *   enforces this, because the failure is a probe that dies at three in the morning in someone else's workspace
- *   rather than anything a reader would notice here.
- *
- *   No lookaround. Rust's regex crate has none, and reaching for ripgrep's PCRE2 mode to get it would make the
- *   sweep depend on how the box's ripgrep was compiled. A rule that seems to need it is usually asking a question
- *   about the FILE rather than about a line, see `absent` below, which is what that question actually is. */
+// Table of UI frameworks and idiom-migration rules that probes.ts sweeps and chores.ts turns into findings; kept apart
+// so neither duplicates the other's patterns.
+// Patterns are Rust-regex via ripgrep: no literal apostrophe (match quotes as `[\x22\x27]`; the scan shell-quotes each
+// pattern) and no lookaround (use `absent` for a file-level question instead).
+// A pattern names a framework or idiom only; whether it is worth fixing is chores.ts's judgement.
 
 export interface UiFramework {
     readonly id: string;
     readonly label: string;
-    // The dependency names that mean "this repository is built with it". Any one of them is enough.
+    // Dependency names that mean this repo is built with it; any one match is enough.
     readonly packages: readonly string[];
 }
 
-/* The three the maintenance surface knows how to say something specific about. Deliberately not "every framework
- * with a npm package": a framework earns a row here by having idiom rules underneath it, and a table entry with
- * no rules would let a chore announce it recognised Svelte and then have nothing to report. */
+// The three frameworks with idiom rules defined below; a table entry with no rules gives a chore nothing to report.
 export const UI_FRAMEWORKS: readonly UiFramework[] = [
     { id: `react`, label: `React`, packages: [`react`] },
     { id: `vue`, label: `Vue`, packages: [`vue`] },
     { id: `angular`, label: `Angular`, packages: [`@angular/core`] },
 ];
 
-// Tailwind is not in the table above because it is not a UI framework and does not own any idiom rules, it is a
-// styling system that any of the three can be wearing, and it gates exactly one chore.
+// Not a UI framework: a styling system any of the three above can use; gates exactly one chore.
 export const TAILWIND_PACKAGES: readonly string[] = [`tailwindcss`];
 
 export const frameworksOf = (deps: readonly string[]): UiFramework[] =>
@@ -47,11 +26,7 @@ export const frameworksOf = (deps: readonly string[]): UiFramework[] =>
 
 export const usesTailwind = (deps: readonly string[]): boolean => TAILWIND_PACKAGES.some((name) => deps.includes(name));
 
-/* Directories a UI scan must never walk, spelled out rather than left to the repository's .gitignore. ripgrep
- * does honour .gitignore, and relying on that is how a repo whose build output is not ignored gets its own
- * minified bundle reported back to it as a thousand hard-coded colours. Tests, specs and stories are excluded for
- * a different reason: they are component-shaped files that are not components, and counting them would put a
- * fixture at the top of every finding. */
+// Dirs a UI scan must skip, spelled out rather than relying on .gitignore; also excludes test/spec/story files.
 export const SCAN_IGNORES: readonly string[] = [
     `!**/node_modules/**`,
     `!**/dist/**`,
@@ -64,58 +39,30 @@ export const SCAN_IGNORES: readonly string[] = [
     `!**/*.{test,spec,stories}.*`,
 ];
 
-// What counts as a component file, across all three frameworks at once. The sweep cannot vary by repository, a
-// probe's command is a fixed string, so it asks for all of them and a Vue-only repo simply has no `.tsx` files.
+// Component file extensions across all three frameworks; the sweep is one fixed command for every repo.
 export const COMPONENT_GLOBS: readonly string[] = [`*.vue`, `*.tsx`, `*.jsx`, `*.component.ts`];
 
-// Where a Tailwind class can appear. Wider than COMPONENT_GLOBS because a class list lives in markup as often as
-// in a component, an Angular template and a plain .html page both style with the same utilities.
+// Where a Tailwind class can appear; wider than COMPONENT_GLOBS since plain markup like .html carries classes too.
 export const MARKUP_GLOBS: readonly string[] = [`*.vue`, `*.tsx`, `*.jsx`, `*.html`, `*.svelte`, `*.astro`];
 
-/* THE DESIGN SYSTEM BYPASS. Not "any arbitrary value", `grid-cols-[1fr_auto]` and `w-[calc(100%-2rem)]` are
- * Tailwind working as designed, and a chore that counted them would be objecting to the feature rather than to
- * anything wrong. What this matches is the two arbitrary values that route around a decision the theme already
- * made: a colour that is not in the palette, and a pixel size that is not on the spacing or type scale.
- *
- * The leading `-` is required. It anchors the match to a utility prefix (`bg-`, `text-`, `w-`), so a bare
- * `[...]` in ordinary prose or an array index cannot be mistaken for a class. */
+// Matches only bypass values: a raw color or px size; leading `-` anchors to a utility prefix, not prose text.
 export const BYPASS_PATTERN = `-\\[(#[0-9a-fA-F]{3,8}|(rgb|hsl)a?\\(|[0-9]+(\\.[0-9]+)?px)`;
 
 export interface IdiomRule {
     readonly id: string;
-    // Which framework's migration this belongs to, so a finding can be grouped under the thing that moved on.
+    // Which framework's migration this belongs to.
     readonly framework: string;
-    // What the repository still has, named as the reader would name it.
+    // Named the way a person reading it would say it, not a code term.
     readonly label: string;
-    // What replaced it. Carried so the prompt can say where to go rather than only what to leave, an agent told
-    // "you still use NgModule" and nothing else will pick a destination, and it may not pick this one.
+    // The destination the agent should move to, not merely what it is leaving.
     readonly replacement: string;
     readonly pattern: string;
     readonly globs: readonly string[];
-    /* THE IDIOM IS THE PATTERN BEING MISSING, not present, `pattern` names the NEW way, and the file is on the
-     * old one precisely because the new one does not appear in it anywhere. The sweep spells this
-     * `--files-without-match`.
-     *
-     * This exists because the alternative got it wrong in a way that is worth remembering. "A Vue file not using
-     * <script setup>" was first written as a lookahead over `<script`, which matches per LINE: a migrated
-     * component with a second plain `<script>` block for defineOptions, or one that merely mentions `<script` in
-     * a comment, both read as un-migrated. It reported five files in an application whose 167 SFCs are every one
-     * of them migrated. The question was never "is there a line like this", it is "does this file contain the
-     * new idiom at all", which is one flag rather than a cleverer regex, and it costs no PCRE2.
-     *
-     * The globs carry more weight on an absent rule than on a normal one, and narrowly is the only safe way to
-     * write them: the population is every file they match, so `*.ts` on an absent rule reports the entire
-     * repository. Keep them to the file type the migration is actually about. */
+    // Marks a rule as absence-based: the file is on the old idiom because `pattern` (the new one) never appears.
     readonly absent?: true;
 }
 
-/* THE IDIOMS THEIR OWN MAINTAINERS HAVE MOVED ON FROM. Every rule here names something the framework's own
- * documentation now steers people away from, and every one of them still works, which is exactly why they
- * accumulate, and why no editor and no linter will bring them up unprompted.
- *
- * High confidence over coverage. Each pattern is one a reader can check by eye against a file, and the ones that
- * would need real parsing to get right are left out rather than approximated: a rule that is wrong a third of the
- * time trains people to stop reading the row it appears in. */
+// Idioms still functional but steered away from by their frameworks; patterns favor precision over coverage.
 export const IDIOM_RULES: readonly IdiomRule[] = [
     {
         id: `react-class-component`,
@@ -136,8 +83,7 @@ export const IDIOM_RULES: readonly IdiomRule[] = [
     {
         id: `react-unsafe-lifecycle`,
         framework: `react`,
-        // Named as what they are rather than by the UNSAFE_ prefix: a reader who has never renamed one would not
-        // recognise "UNSAFE_componentWillMount" as describing their own file.
+        // Named for what it is, not the UNSAFE_ prefix a reader may not recognize.
         label: `the pre-16.3 lifecycle methods`,
         replacement: `effects, or the UNSAFE_ prefixed names if the behaviour is genuinely wanted`,
         pattern: `\\bcomponentWill(Mount|ReceiveProps|Update)\\b`,
@@ -156,9 +102,7 @@ export const IDIOM_RULES: readonly IdiomRule[] = [
         framework: `vue`,
         label: `the Options API`,
         replacement: `<script setup> with the Composition API`,
-        // The new idiom, inverted by `absent` below, an SFC that never opens a `<script setup>` tag is still on
-        // the old one. A file with no script block at all is swept up too, and that is the honest reading: it has
-        // not been migrated because there was nothing there to migrate.
+        // New idiom, inverted via `absent`: no `<script setup>` (or no script at all) reads as unmigrated.
         pattern: `<script[^>]*\\bsetup\\b`,
         globs: [`*.vue`],
         absent: true,
@@ -168,17 +112,7 @@ export const IDIOM_RULES: readonly IdiomRule[] = [
         framework: `vue`,
         label: `the Vue 2 teardown hooks`,
         replacement: `beforeUnmount and unmounted`,
-        /* TWO NAMES, AND ONLY ONE OF THEM IS VUE'S. `beforeDestroy` is a word nobody writes by accident, so its
-         * presence is the finding. `destroyed` is ordinary English, and asking only for a `(` or a `:` after it
-         * matched `{ warned: number; destroyed: number }` in a backend module that reaps idle machines: the chore
-         * told its reader to migrate a Node file to beforeUnmount, which is the kind of row that teaches people to
-         * stop reading the rest. So the ambiguous half has to be a FUNCTION in an options object, the only shape a
-         * hook is ever written in, and a field or a type named after the word is no longer evidence of anything.
-         *
-         * The globs are the second half of the same guard, and `*.ts` was the reason a backend file was eligible at
-         * all. A teardown hook is a component's, so this reads components. What that gives up is a Vue 2 mixin
-         * living in a plain `.js` file, and it is the right trade: `vue-global-api` still catches such a file when
-         * it constructs anything, and an idiom found nowhere costs less than one found in the wrong repository. */
+        // .vue only: hook belongs to a component. `destroyed` counts only as a function, not a field or type.
         pattern: `\\bbeforeDestroy\\s*[(:]|\\bdestroyed\\s*(\\(\\s*\\)\\s*\\{|:\\s*(async\\s+)?(function|\\(\\s*\\)\\s*=>))`,
         globs: [`*.vue`],
     },
@@ -218,50 +152,25 @@ export const IDIOM_RULES: readonly IdiomRule[] = [
 
 export const idiomRule = (id: string): IdiomRule | undefined => IDIOM_RULES.find((rule) => rule.id === id);
 
-/* Two tools naming the same file two ways. The scan reports repo-relative paths because that is what ripgrep
- * prints; jscpd prints whatever it was handed, which for a `.` scan is the same path behind a `./`. Normalising
- * here rather than at each comparison keeps the component-overlap chore from quietly matching nothing because one
- * side had two extra characters. */
+// Strips a leading `./`: ripgrep prints repo-relative paths, jscpd's `.` scan prints the same path with `./` prepended.
 export const normalizePath = (path: string): string => path.replace(/^\.\//, ``);
 
-// Below this a stem is too short to have survived the stripping above with its meaning intact, `H1` and `H2`
-// would both reduce to `h` and read as one family of heading components that are not duplicates of anything.
+// Below this a stem lost its meaning in stripping; `H1`/`H2` would both reduce to `h`.
 const MIN_STEM = 3;
 
 const QUALIFIER_PREFIX = /^(base|the)/;
 const QUALIFIER_SUFFIX = /(v[0-9]+|new|old|legacy|copy|component|[0-9]+)$/;
 
-/* NAMES THE FRAMEWORK CHOSE, NOT THE AUTHOR, and therefore never evidence of anything.
- *
- * A repository gets one of these per app (`app`, `main`, `root`) or one per route directory (Next's App Router
- * mandates `page`, `layout`, `loading`, `error`, `not-found`, `template`, `default`) BY CONSTRUCTION, so two files
- * sharing one is a fact about the framework and not about duplication. A monorepo with two front-ends has two
- * `App.vue`; a thirty-route Next app has thirty `page.tsx`, which sorts to the top of the families list and becomes
- * the loudest thing the chore says while being entirely false.
- *
- * Same argument as `index` below, and the same disposal. Matched against the whole base name rather than as a
- * prefix, so `AppShell.vue` and `ErrorBoundary.tsx` are ordinary components and keep their own stems: the only
- * files dropped are the ones that could not have been built twice in the first place. */
+// Names the framework mandates per app or route; sharing one is never evidence of duplication.
 const FRAMEWORK_NAMES = new Set([`index`, `app`, `main`, `root`, `page`, `layout`, `loading`, `error`, `template`, `default`, `notfound`]);
 
-/* THE NAME TWO COMPONENTS SHARE WHEN THEY ARE THE SAME COMPONENT TWICE, or `undefined` when the file has no
- * name worth comparing.
- *
- * This is a normaliser, not a similarity score, and that is the point: it answers a question the reader can check
- * by eye. `BaseButton.vue` and `ButtonV2.tsx` both reduce to `button`, so a panel claiming they are the same
- * component is making a claim anyone can agree or disagree with in a second. A fuzzy distance would be right more
- * often and checkable never, and an unarguable finding is one nobody can improve.
- *
- * `index` is dropped rather than normalised, along with the rest of the framework's own vocabulary
- * (FRAMEWORK_NAMES). Every barrel file in the repository is called it, and a family of forty index files is a
- * finding about the naming convention rather than about any duplication. */
+// Normalizes a file name to a comparison key, not a similarity score, so a match is one a reader can check by eye;
+// framework names and `index` are dropped since barrels and route files share them by convention.
 export const componentStem = (path: string): string | undefined => {
     const file = normalizePath(path).split(`/`).pop() ?? ``;
-    // `.component.ts` loses both suffixes, `.vue` loses one, taking everything before the first dot handles both
-    // without a table, since a component's name is never the part after a dot.
+    // First-dot split handles both `.component.ts` and `.vue` suffixes; a component's name never follows a dot.
     const base = (file.split(`.`)[0] ?? ``).toLowerCase().replace(/[^a-z0-9]/g, ``);
-    // Tested before the stripping below, so a framework name is dropped on its own terms rather than after a
-    // qualifier rule has had a chance to turn it into something else.
+    // Framework names are dropped before qualifier stripping runs, on their own terms.
     if (base === `` || FRAMEWORK_NAMES.has(base)) {
         return undefined;
     }