@starci/hfs 4.7.34 → 4.7.36

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
+## 4.7.36 - 2026-10-26
+- Changed: the bundled canon pins select @starci/eslint-canon-be 3.4.45, @starci/eslint-canon-fe 9.1.0, the Grammar lint families 0.12.4 and @starci/grammar 0.12.4.
+- Added: the five R319 button-intent finding codes are catalogued and proven, and the `app codemod button-intent` migration is bundled.
+- Changed: the Grammar vendor-parity proof is strict. It reads the DNA vendor, parity and arrangement declarations, judges undeclared wraps and stale overrides, and exports repaint findings with `starci work export-repaints`; `wrappers.yaml` carries the owner-ruled overrides and one pin.
+- Changed: releases follow the alpha.N.M counter (owner ruling `release-waves`): the next tag is derived from the highest released one.
+
+## 4.7.35 - 2026-10-26
+- Changed: the bundled canon pins select @starci/stylelint-canon 2.0.12, @starci/eslint-canon-be 3.4.44, @starci/eslint-canon-fe 9.0.0, the Grammar lint families 0.12.3 and @starci/grammar 0.12.3.
+- Added: `app lint` composes the selected Grammar family lint with the universal front-end canon and refuses canon-fe 9 without it; the Grammar vendor-parity proof reads the generated HeroUI reference; the UI proof checks component ownership and surface layers.
+- Fixed: managed stack renders match and leave unpinned the compose `version` the scaffold declares; the history-hook spec judges the stdin handshake, not a fixed kill; the restamp inventory is active-only and clearer.
+- Changed: the runtime centralizes its parsing and gate summaries.
+
 ## 4.7.34 - 2026-10-26
+- Added: `starci app codemod button-intent` previews legacy Grammar button migrations, applies safe edits with `--write`, and reports ambiguous consequences, competing commits and repeated item commits in JSON or Markdown.
 - Fixed: `starci app db restamp` considers only active migrations when validating names and choosing unoccupied versions. Legacy archive names no longer block preview or apply, and archived files stay untouched.
 - Changed: the loosening check reads the tree as it stands and never its history. The bundled `scripts/lib/loosening-state.mjs` (with `js-lex.mjs` and `loosening-config.mjs`) replaces the diff detector; `HFS_BYPASS_MARKER` (R303) reads it: a suppression word opens a comment, a test marker stands in code, a swallowed failure stands in a shell line or in the string a script hands a shell, a package.json is judged by its scripts, and the same words quoted as data are no bypass. It also refuses a coverage target or threshold below the canon, a relaxing switch, a disabled ESLint rule, a tsconfig strictness option turned off and an exception file that `knowledge/hfs/design-truths.yaml` does not list. `--passWithNoTests`, `--coverageThreshold`, `--no-error-on-unmatched-pattern` and a `--max-warnings` budget are bypasses in a script, a hook or a workflow.
 - Added: `starci app emit` carries class-validator `MaxLength`, `ArrayMaxSize`, `Min` and `Max` of GraphQL input types and REST operation DTOs into the contract (a GraphQL `@inputBounds` directive and an OpenAPI constraint), and the `@starci/hfs/form-bounds` codegen plugin turns them into typed `INPUT_BOUNDS` and `inputBoundsIssues` for the form canon. The app codegen template refuses legacy or unsupported bounds metadata.

package/README.md

@@ -84,9 +84,7 @@ Every file of a spec-required role of `ruleParams.be.unitRoles` — a `*.service
 
 The spec skeleton is `Test.createTestingModule({ providers: [Service, { provide: TOKEN, useValue: double }, ...] }).compile()` and `moduleRef.get(Service)`, with one provider per constructor dependency and nothing else, every double imported from `@starci/jest-preset` (the root), and one placeholder `it` per public method. The double of a token comes from `ruleParams.be.specDoubles` of the slot manifest, the table the lint law `spec-infra-double-from-kit` holds a spec to (`*_ENTITY_MANAGER` -> `mockEntityManager()`, `CLOCK` -> `new FakeClock(...)`, `EVENT_BUS` -> `recordingEventBus()`, `QUEUE_OUTBOX` -> `recordingQueueOutbox()`, `CACHE` -> `fakeCache(clock)`, lock, lease, fence and hold -> `fakeLock(clock)`, ids -> `fakeIds()`, `*_OPTIONS` -> a literal to fill in, everything else and every class -> `mock<T>()`), so the skeleton satisfies the law by construction: no cast, no `new` of the service, no ambient clock. A back end only (a front end has no services); the files are written for prettier (print width 120).
 
-`starci app check` reads the app's `hfs.json` and the tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and then runs the
-whole architecture machine over each side folder. Every finding carries a why code and its Vietnamese text
-(`modules/kernel/failure-codes.yaml`).
+`starci app check` runs ESLint once per side through the app's installed managed flat config: the backend canon on `be/`, and the universal FE canon plus the explicitly selected Grammar-family package on `fe/`. It also reads the app's `hfs.json` and tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and runs the whole architecture machine over each side folder. HFS findings carry their why code and Vietnamese text (`modules/kernel/failure-codes.yaml`); ESLint findings retain their rule id and failure code.
 
 Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file checks (`sync/managed.mjs`) and the prettier check (`sync/format.mjs`) live in `sync/` because they read the templates and the repository's own install, and reach `starci app check` as `extraFindings`; the jest / vitest preset the coverage exclusions come from and prettier are read from the repository's `node_modules`, so run `npm ci` first):
 
@@ -103,7 +101,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 | `HFS_CANON_PIN_DRIFT` | error | a dependency not at the exact version of `knowledge/hfs/canon-pins.yaml` |
 | `HFS_SIZE_SOFT_BACKLOG` | info | a source file over `ruleParams.fileLines.soft`; report only, never fails |
 | `HFS_MANAGED_FILE_DRIFT` | error | a managed file that exists but differs from its render (the `managedBy` slots: hooks, workflows, sonar, the back-end `be.tool-config` files, `app.format-config`, the `scripts` block of `app.package-manifest`, compared as parsed JSON) |
-| `HFS_RULE_OFF_WITHOUT_REPLACEMENT` | error | `eslint.config.mjs`, or a front end's `stylelint.config.mjs`, differs from its one-line render, so a rule could be off, warned or redefined in it |
+| `HFS_RULE_OFF_WITHOUT_REPLACEMENT` | error | `eslint.config.mjs`, or a front end's `stylelint.config.mjs`, differs from its managed factory render, so a rule could be off, warned or redefined in it |
 | `HFS_TOOL_CONFIG_LOCAL` | error | a repository holds a tool config outside the managed set (`.eslintrc*`, `.eslintignore`, a second `eslint.config.*` or `stylelint.config.*`, another prettier or lint-staged config, or a jest config in a back end that is not the one root file), a file that defines an ESLint rule or a stylelint plugin, a tool configuration key in a `package.json` (`eslintConfig`, `stylelint`, `prettier`, `lint-staged`, `jest`), or a script that runs eslint, stylelint or prettier with a flag that swaps the configuration |
 | `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render (no host URL; the ESLint report and HFS import paths), or the stack declaration names another quality gate than the one of `knowledge/sonar-gate.yaml` |
 | `HFS_TS_STRICT` | error | the root `tsconfig.json` sets, lowers or adds anything but `extends` the preset (`be.json`, `next.json`), the template's `exclude` and (back end) the three `paths`; the finding names the flag |
@@ -145,8 +143,8 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 
 The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
 files is the `managedBy` slots of `slots.yaml`; `starci app sync --write` renders them and `starci app check` compares them, so a hand edit and a forgotten `sync` are the same finding.
-Each finding is reported once: the eslint and stylelint one-liners under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
-The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:stack`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its eslint one-liner, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is the one lint gate, `starci app lint`: ESLint over each side with its canon, the app check and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
+Each finding is reported once: the managed ESLint and stylelint factory configs under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
+The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:stack`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its managed ESLint factory config, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is the one lint gate, `starci app lint`: ESLint over each side with its canon, the app check and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
 (slot `app.task-graph`): it carries the task graph, which no preset can render.
 
 The architecture machine (`scripts/hfs/architecture.mjs` of the runtime, the same code bundled here): tiers and import
@@ -156,12 +154,12 @@ finding under the machine's own rule id (`BE_TIER_DIRECTION`, `HFS_UNUSED_EXPORT
 repository without `typescript` installed fails with `ARCH_TYPESCRIPT_MISSING`; the check never passes because it could not run.
 
 `--fast` judges only what changed since the merge-base of `HEAD` with
-`origin/main` (else `main`; `--base <ref>` names another ref): the slot and pin checks on the changed paths, the machine on the owners
+`origin/main` (else `main`; `--base <ref>` names another ref): ESLint on changed source files, the slot and pin checks on the changed paths, the machine on the owners
 of the changed source files without clones and dead exports, and no file-system tree checks. The required-file and minimum-instance
 checks still cover the whole tree. With no merge-base `--fast` is a refusal (exit 2) that names the fix, never a silent full
 pass.
 
-Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). `starci app check` and `starci app lint` never write to the app
+Exit codes: 0 clean, 1 an error finding, 2 a tool could not run or a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). `starci app check` and `starci app lint` never write to the app
 (`starci app lint --fix` lets ESLint and stylelint fix in place).
 
 ## Sonar
@@ -169,7 +167,7 @@ Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad f
 One mechanism for both sides: every finding of the canon is imported into Sonar, and the quality gate
 fails while any is open. Nothing is configured per app; the pieces are managed files (`starci app sync`) and this package.
 
-One entry, one report, one file: `npm run lint` is `starci app lint`; `npm run lint -- --sonar reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings of `starci app check`, rule id = the finding code), `eslint` (the BE and FE canon plugins alike, rule id = the ESLint rule) and `stylelint` over fe (rule id = the stylelint rule). `starci app lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
+One entry, one report, one file: `npm run lint` is `starci app lint`; `npm run lint -- --sonar reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings, rule id = the finding code), `eslint` (the BE canon, universal FE canon and selected Grammar-family plugin, rule id = the ESLint rule) and `stylelint` over fe (rule id = the stylelint rule). App lint shares app check's ESLint runner and calls its HFS checks in process, so each side's ESLint config runs once. `starci app lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
 
 `--sonar` writes the findings as a Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`) before the verdict, so a
 failing lint still leaves its report. A rule's name and description are the catalog's English title and Vietnamese title, meaning and next step;
@@ -202,8 +200,7 @@ derived from the machine's rule id lists). After changing any of those files, `k
 `starci release sync-runtime --check` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.
 
 The examples workflow (`.github/workflows/examples.yml`) runs `starci app lint` of this CLI at the root of every `examples/*`
-app with an `hfs.json` (each `examples/<app>` root) and fails on any finding or any tool that could not run;
-`starci app check` alone would miss the machine's source rules, which the canons judge.
+app with an `hfs.json` (each `examples/<app>` root) and fails on any finding or any tool that could not run. This includes the ESLint canons and repository checks also run by `starci app check`, plus stylelint over the frontend stylesheets.
 
 ## Serving knowledge to other packages
 

package/codemod/button-intent.mjs

@@ -0,0 +1,356 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { sourceLocation } from '../runtime/scripts/lib/ts-ast.mjs';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GRAMMAR = /^@starci\/grammar(?:\/|$)/;
+const VARIANTS = Object.freeze({ primary: 'commit', tertiary: 'dismiss', danger: 'destructive', 'danger-soft': 'destructive', outline: 'neutral', ghost: 'neutral' });
+const WEAK = new Set(['outline', 'ghost', 'secondary']);
+const GENERATED = new Set(['node_modules', '.next', '.turbo', 'dist', 'coverage', '.git']);
+
+function attributes(ts, opening) {
+  return new Map(opening.attributes.properties.filter(ts.isJsxAttribute).map(prop => [prop.name.getText(), prop]));
+}
+
+function literal(ts, attribute) {
+  const value = attribute?.initializer;
+  if (value && ts.isStringLiteralLike(value)) return value.text;
+  return value && ts.isJsxExpression(value) && value.expression && ts.isStringLiteralLike(value.expression) ? value.expression.text : null;
+}
+
+function buttonImports(ts, source) {
+  const names = new Set();
+  const namespaces = new Set();
+  for (const node of source.statements) {
+    if (!ts.isImportDeclaration(node) || !GRAMMAR.test(node.moduleSpecifier.text)) continue;
+    const bindings = node.importClause?.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const binding of bindings.elements) {
+        if (['Button', 'IconButton'].includes(binding.propertyName?.text ?? binding.name.text)) names.add(binding.name.text);
+      }
+    }
+  }
+  return { names, namespaces };
+}
+
+function isButton(ts, opening, imports) {
+  const tag = opening.tagName;
+  if (ts.isIdentifier(tag)) return imports.names.has(tag.text);
+  return ts.isPropertyAccessExpression(tag) && ts.isIdentifier(tag.expression)
+    && imports.namespaces.has(tag.expression.text) && ['Button', 'IconButton'].includes(tag.name.text);
+}
+
+function bindingNames(ts, binding) {
+  if (ts.isIdentifier(binding)) return [binding.text];
+  if (ts.isObjectBindingPattern(binding) || ts.isArrayBindingPattern(binding)) return binding.elements.flatMap(element => ts.isBindingElement(element) ? bindingNames(ts, element.name) : []);
+  return [];
+}
+
+function shadowedBinding(ts, opening) {
+  const tag = opening.tagName;
+  const name = ts.isIdentifier(tag) ? tag.text : tag.expression.text;
+  for (let at = opening.parent; at && !ts.isSourceFile(at); at = at.parent) {
+    if (ts.isFunctionLike(at) && (at.parameters.some(parameter => bindingNames(ts, parameter.name).includes(name))
+      || (ts.isFunctionExpression(at) && at.name?.text === name))) return true;
+    if (ts.isCatchClause(at) && at.variableDeclaration && bindingNames(ts, at.variableDeclaration.name).includes(name)) return true;
+    const statements = ts.isBlock(at) ? at.statements : [];
+    for (const statement of statements) {
+      if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name?.text === name) return true;
+      if (ts.isVariableStatement(statement) && statement.declarationList.declarations.some(declaration => bindingNames(ts, declaration.name).includes(name))) return true;
+    }
+    if ((ts.isForStatement(at) || ts.isForOfStatement(at) || ts.isForInStatement(at)) && at.initializer && ts.isVariableDeclarationList(at.initializer)
+      && at.initializer.declarations.some(declaration => bindingNames(ts, declaration.name).includes(name))) return true;
+  }
+  return false;
+}
+
+function isMap(ts, node) {
+  if (!ts.isCallExpression(node)) return false;
+  return ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text === 'map'
+    : ts.isElementAccessExpression(node.expression) && ts.isStringLiteralLike(node.expression.argumentExpression) && node.expression.argumentExpression.text === 'map';
+}
+
+function callbackArgument(ts, node) {
+  let expression = node;
+  while (expression.parent && ts.isParenthesizedExpression(expression.parent)) expression = expression.parent;
+  return isMap(ts, expression.parent) && expression.parent.arguments[0] === expression;
+}
+
+function inlineRenderCallback(ts, node) {
+  let expression = node;
+  while (expression.parent && ts.isParenthesizedExpression(expression.parent)) expression = expression.parent;
+  if (!expression.parent || !ts.isJsxExpression(expression.parent)) return false;
+  const container = expression.parent.parent;
+  if (ts.isJsxElement(container) || ts.isJsxFragment(container)) return true;
+  return ts.isJsxAttribute(container) && /^(?:children|render[A-Z].*|.*Renderer)$/.test(container.name.getText());
+}
+
+/** Resolve same-file callback aliases before walking buttons: ancestry alone misses rows.map(renderRow). */
+function collectionCallbacks(ts, source) {
+  const definitions = new Map();
+  const callbacks = [];
+  const collect = node => {
+    if (isMap(ts, node) && node.arguments[0]) callbacks.push(node.arguments[0]);
+    const name = (ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name;
+    if (name && ts.isIdentifier(name)) definitions.set(name.text, [...(definitions.get(name.text) ?? []), ts.isVariableDeclaration(node) ? node.initializer : node]);
+    ts.forEachChild(node, collect);
+  };
+  collect(source);
+  const owners = new Set();
+  const seen = new Set();
+  const resolve = node => {
+    if (!node || seen.has(node)) return;
+    seen.add(node);
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) owners.add(node);
+    else if (ts.isIdentifier(node)) for (const definition of definitions.get(node.text) ?? []) resolve(definition);
+    else if (ts.isParenthesizedExpression(node)) resolve(node.expression);
+    else if (ts.isPropertyAccessExpression(node)) for (const definition of definitions.get(node.name.text) ?? []) resolve(definition);
+    else if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'bind') resolve(node.expression.expression);
+  };
+  for (const callback of callbacks) resolve(callback);
+  return owners;
+}
+
+function renderOwner(ts, node, source) {
+  for (let at = node.parent; at; at = at.parent) {
+    if (ts.isArrowFunction(at) || ts.isFunctionExpression(at) || ts.isFunctionDeclaration(at) || ts.isMethodDeclaration(at)) {
+      // Collection and JSX render callbacks belong to their enclosing component's render, including nested SlotView children.
+      if (callbackArgument(ts, at) || inlineRenderCallback(ts, at)) continue;
+      return at;
+    }
+  }
+  return source;
+}
+
+function inMap(ts, node, owner) {
+  for (let at = node.parent; at && at !== owner; at = at.parent) {
+    if (isMap(ts, at)) return true;
+  }
+  return false;
+}
+
+function siblingGroup(ts, node, owner) {
+  for (let at = node.parent; at && at !== owner; at = at.parent) {
+    if (ts.isJsxElement(at) || ts.isJsxFragment(at)) return at;
+  }
+  return owner;
+}
+
+function stableName(ts, node) {
+  if (ts.isIdentifier(node)) return node.text;
+  if (ts.isPropertyAccessExpression(node) && stableName(ts, node.expression)) return `${stableName(ts, node.expression)}.${node.name.text}`;
+  return null;
+}
+
+function conditionFact(ts, expression, choice) {
+  if (ts.isParenthesizedExpression(expression)) return conditionFact(ts, expression.expression, choice);
+  if (ts.isPrefixUnaryExpression(expression) && expression.operator === ts.SyntaxKind.ExclamationToken) return conditionFact(ts, expression.operand, !choice);
+  if (ts.isBinaryExpression(expression)) {
+    const operator = expression.operatorToken.kind;
+    const equality = operator === ts.SyntaxKind.EqualsEqualsEqualsToken;
+    const inequality = operator === ts.SyntaxKind.ExclamationEqualsEqualsToken;
+    if (!equality && !inequality) return null;
+    const name = stableName(ts, expression.left);
+    const value = expression.right;
+    if (name && (ts.isStringLiteralLike(value) || ts.isNumericLiteral(value) || [ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.NullKeyword].includes(value.kind))) {
+      const canonical = ts.isStringLiteralLike(value) ? `string:${value.text}` : ts.isNumericLiteral(value) ? `number:${Number(value.text)}` : value.getText();
+      return { name, value: canonical, equal: equality === choice };
+    }
+  }
+  const name = stableName(ts, expression);
+  return name ? { name, value: 'truthy', equal: choice } : null;
+}
+
+function branchChoices(ts, node, owner) {
+  const choices = new Map();
+  const facts = [];
+  const record = (branch, expression, choice) => {
+    choices.set(branch, choice);
+    const fact = conditionFact(ts, expression, choice);
+    if (fact) facts.push(fact);
+  };
+  for (let at = node; at.parent && at.parent !== owner; at = at.parent) {
+    const parent = at.parent;
+    if (ts.isConditionalExpression(parent)) {
+      if (at === parent.whenTrue) record(parent, parent.condition, true);
+      if (at === parent.whenFalse) record(parent, parent.condition, false);
+    }
+    if (ts.isIfStatement(parent)) {
+      if (at === parent.thenStatement) record(parent, parent.expression, true);
+      if (at === parent.elseStatement) record(parent, parent.expression, false);
+    }
+    if (ts.isBinaryExpression(parent) && at === parent.right) {
+      if (parent.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) record(parent, parent.left, true);
+      if (parent.operatorToken.kind === ts.SyntaxKind.BarBarToken) record(parent, parent.left, false);
+    }
+  }
+  return { choices, facts };
+}
+
+function canCoexist(first, second) {
+  for (const [branch, choice] of first.branches) if (second.branches.has(branch) && second.branches.get(branch) !== choice) return false;
+  for (const left of first.facts) for (const right of second.facts) {
+    if (left.name !== right.name) continue;
+    if (left.value === right.value && left.equal !== right.equal) return false;
+    if (left.equal && right.equal && left.value !== right.value && left.value !== 'truthy' && right.value !== 'truthy') return false;
+  }
+  return true;
+}
+
+function destructiveSignal(text) {
+  const words = text.normalize('NFD').replace(/\p{M}/gu, '').replaceAll('\u0111', 'd').replaceAll('\u0110', 'D')
+    .replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ').toLowerCase();
+  return /\b(delete|remove|revoke|discard|destroy|purge|trash|terminate|clear|erase|reset|reject|decline|xoa)\b|\bthu[\s_-]*hoi\b|\b(?:cancel|huy)[\s_-]+(?:offer|booking|appointment|order|subscription|lich|don|de\s+nghi)\b/.test(words);
+}
+
+function describe(ts, source, opening, imports, callbacks) {
+  const props = attributes(ts, opening);
+  const element = ts.isJsxOpeningElement(opening) ? opening.parent : opening;
+  const owner = renderOwner(ts, element, source);
+  const variant = literal(ts, props.get('variant'));
+  const intent = literal(ts, props.get('intent'));
+  const branch = branchChoices(ts, element, owner);
+  return { opening, element, owner, props, variant, intent, branches: branch.choices, facts: branch.facts,
+    group: siblingGroup(ts, element, owner), mapped: variant === 'secondary' ? null : VARIANTS[variant],
+    repeated: callbacks.has(owner) || inMap(ts, element, owner), shadowed: shadowedBinding(ts, opening), name: opening.tagName.getText(source), imports };
+}
+
+/** Migrate imported Grammar buttons using source edits; ambiguous buttons retain their original props and gain a report finding. */
+export function transformButtonIntent({ ts, text, file = 'component.tsx' }) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, /\.jsx$/i.test(file) ? ts.ScriptKind.JSX : ts.ScriptKind.TSX);
+  const imports = buttonImports(ts, source);
+  const callbacks = collectionCallbacks(ts, source);
+  const buttons = [];
+  const visit = node => {
+    if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && isButton(ts, node, imports)) buttons.push(describe(ts, source, node, imports, callbacks));
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  const findings = [];
+  const changes = [];
+  const edits = [];
+  const flag = (button, code, reason) => findings.push({ file, ...sourceLocation(source, button.opening), code, reason,
+    component: button.name, variant: button.variant, source: button.element.getText(source) });
+  if (source.parseDiagnostics.length) {
+    return { text, changes, findings: [{ file, line: 1, column: 1, code: 'parse-error', reason: ts.flattenDiagnosticMessageText(source.parseDiagnostics[0].messageText, '\n') }] };
+  }
+  const commits = buttons.filter(button => button.variant === 'primary' || button.intent === 'commit');
+  for (const button of buttons) {
+    if (button.shadowed) {
+      flag(button, 'shadowed-button-binding', 'A local binding shadows the Grammar import; inspect its actual component before migrating.');
+      continue;
+    }
+    const pending = [];
+    if (button.intent === 'commit' || button.variant === 'primary') {
+      if (button.repeated) pending.push(['commit-in-collection', 'A repeated item needs a human choice of alternative or neutral.']);
+      if (commits.some(other => other !== button && other.owner === button.owner && canCoexist(button, other))) pending.push(['multiple-commits', 'More than one commit can render in this component; choose the decision owner and next action.']);
+    }
+    if (button.props.has('intent') && !button.props.has('variant')) {
+      for (const [code, reason] of pending) flag(button, code, reason);
+      continue;
+    }
+    if (button.props.has('intent')) pending.push(['intent-and-variant', 'Existing intent and variant need a human reconciliation.']);
+    if (!button.props.has('variant')) pending.push(['missing-variant', 'No old variant declares the command role; choose its consequence and rank.']);
+    else if (button.variant === null) pending.push(['dynamic-variant', 'A dynamic variant needs a human intent for every branch.']);
+    else if (button.variant !== 'secondary' && !button.mapped) pending.push(['unknown-variant', 'This variant has no published mechanical intent mapping.']);
+    if (button.opening.attributes.properties.some(ts.isJsxSpreadAttribute)) pending.push(['spread-props', 'Spread props can supply or override intent, step or variant; inspect the source.']);
+    if (WEAK.has(button.variant) && destructiveSignal(button.element.getText(source))) pending.push(['destructive-verb', 'A destructive or negative command on a weak variant needs its actual consequence and confirmation step reviewed.']);
+    if (button.props.has('step')) pending.push(['existing-step', 'An existing destructive step needs reconciliation with the migrated intent.']);
+    if (pending.length) {
+      for (const [code, reason] of pending) flag(button, code, reason);
+      continue;
+    }
+    const intent = button.variant === 'secondary'
+      ? commits.some(other => other.group === button.group && canCoexist(button, other)) ? 'alternative' : 'neutral'
+      : button.mapped;
+    const step = button.variant === 'danger' ? 'confirm' : button.variant === 'danger-soft' ? 'entry' : null;
+    const attribute = button.props.get('variant');
+    const replacement = `intent="${intent}"${step ? ` step="${step}"` : ''}`;
+    edits.push({ start: attribute.getStart(source), end: attribute.end, replacement });
+    changes.push({ file, ...sourceLocation(source, button.opening), component: button.name, from: button.variant, intent, ...(step ? { step } : {}) });
+  }
+  let output = text;
+  for (const edit of edits.sort((first, second) => second.start - first.start)) output = output.slice(0, edit.start) + edit.replacement + output.slice(edit.end);
+  return { text: output, changes, findings };
+}
+
+function sourceFiles(directory) {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) return GENERATED.has(entry.name) ? [] : sourceFiles(target);
+    return entry.isFile() && /\.[jt]sx$/i.test(entry.name) ? [target] : [];
+  }).sort();
+}
+
+/** Preview or apply safe migrations in one app's FE tree; every unresolved case is retained in the returned report. */
+export function migrateButtonIntent({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+  if (!ts) throw new Error('button-intent needs TypeScript installed in the app or @starci/hfs development checkout');
+  const frontend = path.join(root, 'fe');
+  if (!fs.statSync(frontend, { throwIfNoEntry: false })?.isDirectory()) throw new Error('button-intent runs at an app root with a fe/ directory');
+  const report = { schema: 'starci/button-intent-codemod@1', root, write, filesScanned: 0, filesChanged: [], changes: [], findings: [] };
+  for (const target of sourceFiles(frontend)) {
+    const file = path.relative(root, target).split(path.sep).join('/');
+    const original = fs.readFileSync(target, 'utf8');
+    const result = transformButtonIntent({ ts, text: original, file });
+    report.filesScanned += 1;
+    report.changes.push(...result.changes);
+    report.findings.push(...result.findings);
+    if (result.text !== original) {
+      report.filesChanged.push(file);
+      if (write) fs.writeFileSync(target, result.text);
+    }
+  }
+  return report;
+}
+
+const cell = value => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+
+/** Render the migration and human decision list as Markdown; JSON consumers use the same unabridged report object. */
+export function buttonIntentMarkdown(report) {
+  const lines = ['# Button intent migration', '', `${report.write ? 'Applied' : 'Dry run'}: ${report.changes.length} safe changes in ${report.filesChanged.length} files; ${report.findings.length} unresolved findings.`, '',
+    '## Safe changes', '', '| Location | Before | Intent | Step |', '| --- | --- | --- | --- |',
+    ...report.changes.map(change => `| ${cell(`${change.file}:${change.line}:${change.column}`)} | ${change.from} | ${change.intent} | ${change.step ?? ''} |`), '',
+    '## Human decisions', '', '| Location | Code | Reason |', '| --- | --- | --- |',
+    ...report.findings.map(finding => `| ${cell(`${finding.file}:${finding.line}:${finding.column}`)} | ${finding.code} | ${cell(finding.reason)} |`), ''];
+  return lines.join('\n');
+}
+
+function parse(argv) {
+  const [name, ...rest] = argv;
+  if (name !== 'button-intent') throw new Error('starci app codemod takes button-intent');
+  const options = { write: false, format: 'markdown' };
+  const args = rest.values();
+  for (const arg of args) {
+    const [flag, inline] = arg.split(/=(.*)/s);
+    if (flag === '--write' || flag === '--json') {
+      if (inline !== undefined && !['true', 'false'].includes(inline)) throw new Error(`${flag} expects true or false`);
+      const value = inline === undefined || inline === 'true';
+      if (flag === '--write') options.write = value;
+      else if (value) options.format = 'json';
+    } else if (flag === '--format' || flag === '--report') {
+      const value = inline ?? args.next().value;
+      if (!value || value.startsWith('--')) throw new Error(`${flag} needs a value`);
+      options[flag.slice(2)] = value;
+    } else throw new Error(`unknown codemod option ${arg}`);
+  }
+  if (!['json', 'markdown'].includes(options.format)) throw new Error('--format accepts json or markdown');
+  return options;
+}
+
+/** CLI boundary: dry-run by default, --write mutates only safe FE source; findings return exit 1 with a complete report. */
+export function codemodMain(argv, { cwd, stdout }) {
+  const options = parse(argv);
+  if (options.report && !/\.(?:json|md)$/i.test(options.report)) throw new Error('--report needs a .json or .md report file');
+  const report = migrateButtonIntent({ root: path.resolve(cwd), write: options.write });
+  const output = options.format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : buttonIntentMarkdown(report);
+  if (options.report) {
+    const target = path.resolve(cwd, options.report);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, output);
+  }
+  stdout(output);
+  return report.findings.length ? 1 : 0;
+}

package/lint/run.mjs

@@ -17,7 +17,7 @@
 // turbo `lint` task); the root `npm run lint` stays the whole app. There is no second linter: a workspace lint is this lint, scoped.
 import fs from 'node:fs';
 import path from 'node:path';
-import { createRequire } from 'node:module';
+import { createRequire, registerHooks } from 'node:module';
 import { spawn } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { linterReport, mergeReports, sonarReport, sourceRootsOf } from '../report/sonar.mjs';
@@ -25,6 +25,7 @@ import { SIDES, appRelativeMessages, loadSlotManifest, readRepoDeclaration } fro
 import { STYLE_GLOB } from '../sync/index.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
+import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
 
 // --side judges only that side; root HFS findings belong to be, its Sonar report stays on that side.
 export const LINT_SCHEMA = 'starci/lint@1';
@@ -164,18 +165,46 @@ export function canonScope(config) {
   };
 }
 
-/** Read the installed canon's source selectors, then enumerate that scope; unavailable or unsupported selectors cannot prove coverage. */
-async function sourceFiles({ repoRoot, cwd, side, scope: folderScope }) {
-  const entry = createRequire(path.join(cwd, 'package.json')).resolve(`@starci/eslint-canon-${side}`);
+/** Resolve one canon from this app's install; a package from an enclosing repository cannot prove its lint contract. */
+function ownCanonEntry({ repoRoot, cwd }, packageName) {
+  const require = createRequire(path.join(cwd, 'package.json'));
+  // The entry is imported below, so resolve with Node's import conditions even when a package publishes no require target.
+  // The synchronous hook exists only for this lookup; later package resolution keeps its own conditions.
+  const hook = registerHooks({ resolve: (specifier, context, nextResolve) => nextResolve(specifier, specifier === packageName
+    ? { ...context, conditions: [...new Set([...context.conditions.filter(condition => condition !== 'require'), 'import'])] }
+    : context) });
+  let entry;
+  try { entry = require.resolve(packageName); }
+  finally { hook.deregister(); }
   // The canon must be the app's own install: resolved inside the app root, or inside the app's node_modules when that folder is a link to the install
   // (the runtime's examples lint in a sealed copy whose node_modules links the example's own install, scripts/hfs/example-secrets.mjs).
   const ownInstall = [repoRoot, path.join(repoRoot, 'node_modules')].filter((dir) => fs.existsSync(dir)).map((dir) => fs.realpathSync(dir));
   if (!ownInstall.some((root) => inside(root, fs.realpathSync(entry)))) throw new Error('the installed canon is outside the app root');
+  return entry;
+}
+
+/** Both installed FE canons supply the source config; family selection is explicit and an unavailable factory fails closed. */
+export async function installedLintConfig({ repoRoot, cwd, side }) {
+  const entry = ownCanonEntry({ repoRoot, cwd }, `@starci/eslint-canon-${side}`);
   const canon = await import(pathToFileURL(entry).href);
   const factory = side === 'be' ? canon.starciBeConfig : canon.starciFeConfig;
   if (typeof factory !== 'function' || typeof canon.loadHfs !== 'function') throw new Error('the installed canon has no supported config factory');
-  const config = await factory({ hfs: canon.loadHfs(pathToFileURL(path.join(cwd, 'eslint.config.mjs')).href) });
+  const hfs = canon.loadHfs(pathToFileURL(path.join(cwd, 'eslint.config.mjs')).href);
+  const config = await factory({ hfs });
   if (!Array.isArray(config)) throw new Error('the installed canon did not return a flat config');
+  if (side !== 'fe') return config;
+  const family = grammarLintFor(hfs.grammar);
+  if (family.package === null) return config;
+  const familyCanon = await import(pathToFileURL(ownCanonEntry({ repoRoot, cwd }, family.package)).href);
+  if (typeof familyCanon[family.factory] !== 'function') throw new Error(`${family.package} has no supported ${family.factory} factory`);
+  const familyConfig = await familyCanon[family.factory]({ hfs });
+  if (!Array.isArray(familyConfig)) throw new Error(`${family.package} did not return a flat config`);
+  return [...config, ...familyConfig];
+}
+
+/** Read both installed canons' source selectors, then enumerate that scope; unavailable selectors cannot prove coverage. */
+async function sourceFiles({ repoRoot, cwd, side, scope: folderScope }) {
+  const config = await installedLintConfig({ repoRoot, cwd, side });
   const scope = canonScope(config);
   const files = [];
   const visit = (folder) => {
@@ -217,7 +246,7 @@ function checkedEslintResults({ results, expected, cwd, scope, changed }) {
 }
 
 /** Starts the ESLint child of every side that has work and returns one record per side: skipped, a scope error, or the running child. */
-async function launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe }) {
+async function launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe, run = runLinter }) {
   const launches = [];
   for (const side of app ? SIDES.filter((candidate) => opts.side === undefined || opts.side === candidate) : []) {
     if (workspace !== null && side !== STYLE_SIDE) { launches.push({ side, skipped: `outside --workspace ${workspace}` }); continue; }
@@ -227,11 +256,38 @@ async function launchEslint({ app, repoRoot, opts, changed, existing, workspace,
     let expected;
     try { expected = changed ? sources : await sourceFiles({ repoRoot, cwd, side, scope: onFe }); }
     catch (error) { launches.push({ side, scopeError: `eslint source scope is unavailable in ${side}/: ${String(error?.message ?? error)}` }); continue; }
-    launches.push({ side, cwd, expected, run: runLinter({ cwd, pkg: 'eslint', bin: 'eslint', args: ['--format', 'json', ...(opts.fix ? ['--fix'] : []), ...(changed ? sources : [onFe ?? '.'])], bound: repoRoot }) });
+    launches.push({ side, cwd, expected, run: run({ cwd, pkg: 'eslint', bin: 'eslint', args: ['--format', 'json', ...(opts.fix ? ['--fix'] : []), ...(changed ? sources : [onFe ?? '.'])], bound: repoRoot }) });
   }
   return launches;
 }
 
+/** Execute each side's installed ESLint config once; check and lint share scope, coverage and tool-failure judgment. */
+export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loadSlotManifest(), repoRoot), opts = {}, changed = null, existing = [], workspace = null, onFe = null, run }) {
+  const findings = [], errors = [], raw = [];
+  const engine = { sides: {} };
+  if (!app.sides) throw new Error('ESLint runs at the app root, the folder of hfs.json');
+  const launches = await launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe, run });
+  const runs = await Promise.all(launches.map(launch => launch.run ?? null));
+  launches.forEach((launch, at) => {
+    const { side } = launch;
+    if (launch.skipped) { engine.sides[side] = { files: 0, skipped: launch.skipped }; return; }
+    if (launch.scopeError) { errors.push(launch.scopeError); engine.sides[side] = { files: 0 }; return; }
+    const linted = runs[at];
+    if (linted.error) errors.push(linted.error);
+    if (linted.results) {
+      const checked = checkedEslintResults({ results: linted.results, expected: launch.expected, cwd: launch.cwd, scope: onFe, changed: changed !== null });
+      errors.push(...checked.errors);
+      linted.results = checked.results;
+      const appRelative = appRelativeMessages(side, path.join(repoRoot, side));
+      for (const result of linted.results) for (const message of result.messages ?? []) message.message = appRelative(message.message);
+      raw.push(...linted.results);
+      findings.push(...eslintFindings(linted.results, repoRoot));
+    }
+    engine.sides[side] = { files: linted.results?.length ?? 0 };
+  });
+  return { findings, errors, raw, engine };
+}
+
 /** Starts stylelint over the fe stylesheets (the running child), or returns null when no stylesheet is in scope. */
 function launchStylelint({ repoRoot, opts, changed, existing, onFe }) {
   if (opts.side === 'be') return null;
@@ -244,7 +300,7 @@ function launchStylelint({ repoRoot, opts, changed, existing, onFe }) {
  * Run the whole lint of the app at `repoRoot`. `hfsCheck(repoRoot)` returns the `starci app check` result (`{ findings, tracked }`); the CLI
  * injects it. Returns `{ report, sonar, exit }`; `sonar` is the merged Generic Issue Import document.
  */
-export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles = () => [] }) {
+export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles = () => [], runLinter: linter }) {
   const changed = opts.changed === null ? null : new Set(opts.changed);
   const errors = [];
   let workspace = null;
@@ -269,31 +325,16 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
   const onFe = workspace === null ? null : workspace.slice(STYLE_SIDE.length + 1);
 
   // The linters and the app check are independent: every child starts first, the app check runs while they work, and the results are read in a fixed order.
-  const eslintLaunches = await launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe });
+  const eslintRun = app ? eslintRepository({ app, repoRoot, opts, changed, existing, workspace, onFe, run: linter }) : null;
   const styleLaunch = app ? launchStylelint({ repoRoot, opts, changed, existing, onFe }) : null;
   const checkRun = app ? Promise.resolve().then(() => hfsCheck(repoRoot)).then((value) => ({ value }), (error) => ({ error })) : null;
 
   // 1. ESLint, once per side, from the side folder with that side's config.
-  engines.eslint = { sides: {} };
-  const eslintRuns = await Promise.all(eslintLaunches.map((launch) => launch.run ?? null));
-  eslintLaunches.forEach((launch, at) => {
-    const { side } = launch;
-    if (launch.skipped) { engines.eslint.sides[side] = { files: 0, skipped: launch.skipped }; return; }
-    if (launch.scopeError) { errors.push(launch.scopeError); engines.eslint.sides[side] = { files: 0 }; return; }
-    const linted = eslintRuns[at];
-    if (linted.error) errors.push(linted.error);
-    if (linted.results) {
-      const checkedResults = checkedEslintResults({ results: linted.results, expected: launch.expected, cwd: launch.cwd, scope: onFe, changed: changed !== null });
-      errors.push(...checkedResults.errors);
-      linted.results = checkedResults.results;
-      // The side canon names side-relative paths in its messages; the report names every path from the app root.
-      const appRelative = appRelativeMessages(side, path.join(repoRoot, side));
-      for (const result of linted.results) for (const message of result.messages ?? []) message.message = appRelative(message.message);
-      raw.eslint.push(...linted.results);
-      findings.push(...eslintFindings(linted.results, repoRoot));
-    }
-    engines.eslint.sides[side] = { files: linted.results?.length ?? 0 };
-  });
+  const eslint = eslintRun ? await eslintRun : { engine: { sides: {} }, errors: [], raw: [], findings: [] };
+  engines.eslint = eslint.engine;
+  errors.push(...eslint.errors);
+  raw.eslint.push(...eslint.raw);
+  findings.push(...eslint.findings);
 
   // 3. stylelint over the fe side's stylesheets.
   if (app) {