@starci/eslint-canon-fe 9.6.2 → 9.6.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 9.6.5 - 2026-10-31
+
+- Changed: the bundled runtime copies follow @starci/hfs 4.13.2 (R344 on the `be.integrations` slot) and the canon pins name hfs 4.13.2, eslint-canon-be 3.10.0, eslint-canon-fe 9.6.5, eslint-grammar-core and eslint-grammar-offset-pop 0.16.5; no rule changed.
+
+## 9.6.4 - 2026-10-31
+
+- Changed: the bundled canon pins name @starci/hfs 4.13.1 and the lint cohort (eslint-canon-be 3.9.4, eslint-canon-fe 9.6.4, eslint-grammar-core and eslint-grammar-offset-pop 0.16.4); no rule changed.
+
+## 9.6.3 - 2026-10-31
+
+- Changed: the bundled canon pins name the 0.16.3 cohort (@starci/grammar, eslint-grammar-core and eslint-grammar-offset-pop 0.16.3, eslint-canon-fe 9.6.3, eslint-canon-be 3.9.3, stylelint-canon 2.3.0, jest-preset 2.6.0, hfs 4.13.0); ChatWorkspace and PaneLayout are removed with no alias; PaneGrid and Pane are the one generic pane grid: grammar names are generic. The surface-rules spec uses PaneGrid.
+- Added: lib/freestyle (`exemptFreestyle`, `freestyleContext`): no-arbitrary-value, no-app-surface-paint, no-raw-brand-value, no-list-panel-padding, no-inline-class-name and no-native-img do not report the raw elements inside a `<Freestyle>` subtree of the same file; a Grammar component inside it is judged as before (owner ruling grammar-freestyle-region). Specs: src/freestyle.spec.ts.
+- Added: the lint result cache of `starci app check` (ruling app-check-cache): `crossFileInputs`, the files and folders each rule reads beyond the linted file (an fs-audit spec proves every rule declares what it reads), and the `projectGraph` export the cache keys a file's lint record on.
+
 ## 9.6.2 - 2026-10-31
 
 - Changed: the bundled canon pins name @starci/grammar 0.16.2 (the horizontal Stepper connector line; SurfaceListCard takes its depth from the surface context).

package/dist/brand-values.d.ts

@@ -19,10 +19,10 @@
  */
 import { type Recommended } from "./lib/rule.js";
 /** No raw colour, hex or pixel value outside `brand.css`. */
-export declare const noRawBrandValue: import("./lib/rule.js").Rule<"color" | "length" | "named", []>;
+export declare const noRawBrandValue: import("./lib/rule.js").Rule<"length" | "color" | "named", []>;
 /** The rules this law contributes to the plugin. */
 export declare const rules: {
-    "no-raw-brand-value": import("./lib/rule.js").Rule<"color" | "length" | "named", []>;
+    "no-raw-brand-value": import("./lib/rule.js").Rule<"length" | "color" | "named", []>;
 };
 /** Every rule is an error. */
 export declare const recommended: Recommended;

package/dist/brand-values.js

@@ -19,6 +19,7 @@
  */
 import { isContentFile } from "./comments.js";
 import { defineRule } from "./lib/rule.js";
+import { exemptFreestyle } from "./lib/freestyle.js";
 /** A hex colour: 3, 4, 6 or 8 digits, not a longer word and not part of an identifier. */
 const HEX_COLOR = /(?<![\w&])#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![\w-])/;
 /** A functional colour notation. */
@@ -84,7 +85,7 @@ const staticString = (node) => {
     return null;
 };
 /** No raw colour, hex or pixel value outside `brand.css`. */
-export const noRawBrandValue = defineRule({
+export const noRawBrandValue = exemptFreestyle(defineRule({
     meta: {
         type: "problem",
         docs: { description: "No hex, colour function, named paint colour or px length in TypeScript; tokens only." },
@@ -163,7 +164,7 @@ export const noRawBrandValue = defineRule({
             },
         };
     },
-});
+}));
 /** The rules this law contributes to the plugin. */
 export const rules = {
     "no-raw-brand-value": noRawBrandValue,

package/dist/class-names.js

@@ -3,6 +3,7 @@
  * classNames files own the utility-token composition.
  */
 import { defineRule } from "./lib/rule.js";
+import { exemptFreestyle } from "./lib/freestyle.js";
 import { isComponentFile, roleOfFile } from "./lib/scope.js";
 /** The owner a cn call may sit in, and the exports that publish one. */
 const FUNCTION_OWNERS = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
@@ -90,7 +91,7 @@ const usesImportedClassName = (node, imported) => {
     return false;
 };
 /** Report className values written directly in component JSX. */
-export const noInlineClassName = defineRule({
+export const noInlineClassName = exemptFreestyle(defineRule({
     meta: {
         type: "problem",
         docs: { description: "Component JSX must import a named className declaration." },
@@ -111,7 +112,7 @@ export const noInlineClassName = defineRule({
             },
         };
     },
-});
+}));
 /** Require every classNames declaration to use the colocated classNames.ts convention. */
 export const classNamesInColocatedFile = defineRule({
     meta: {

package/dist/index.d.ts

@@ -103,3 +103,7 @@ export declare const starciPlainSourceConfig: ({ root }?: {
 export declare const starciTypedSourceConfig: ({ root }?: {
     readonly root?: unknown;
 }) => Linter.Config[];
+export { crossFileInputs } from "./lib/cross-file-inputs.js";
+export type { CrossFileInput } from "./lib/cross-file-inputs.js";
+export { projectGraph } from "./project-graph.js";
+export type { ProjectGraphFinding, ProjectGraphSnapshot } from "./project-graph.js";

package/dist/index.js

@@ -306,3 +306,6 @@ for (const addition of A14_CONTRIBUTIONS) {
     Object.assign(rules, addition.rules);
     Object.assign(recommended, addition.recommended);
 }
+// The result cache of `starci app lint` (contexts/project/check-cache.md) reads these two declarations of the installed canon.
+export { crossFileInputs } from "./lib/cross-file-inputs.js";
+export { projectGraph } from "./project-graph.js";

package/dist/lib/cross-file-inputs.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The files a rule of this canon reads that ESLint's own import graph does not carry.
+ *
+ * The result cache of `starci app lint` (contexts/project/check-cache.md, ESLint) re-lints a file when it or a file it reaches through imports
+ * changed. A rule that reads another file by path, with `fs` (a sibling, a directory listing, a manifest, a module file it follows by hand),
+ * has an input the import graph cannot see, so the rule declares it here and the cache dirties the files that depend on it:
+ *
+ * - `content`: the rule reads the bytes of the files the globs match; a changed, added or removed match dirties the dependants.
+ * - `exists`: the rule only asks whether a file is there or lists a folder; an added or removed match dirties the dependants.
+ * - `git`: the rule compares the file with git history (the merge-base with the base branch), which no file holds; a change of the merge-base
+ *   dirties every dependant of more than `minLines` lines (the rule reads history only for a file over its size budget). `globs` is empty.
+ *
+ * `globs` are relative to the linted file's folder (`relativeTo: "file"`) or to the side root, the folder of the side's `eslint.config.mjs`
+ * (`relativeTo: "side"`); they use `*`, `**`, `?` and `{a,b}`, posix separators. `appliesTo` are side-root globs of the linted files that
+ * depend on the input. A declaration may be wider than the read, never narrower: a too wide one costs a lint, a too narrow one a wrong answer.
+ * `cross-file-inputs.spec.ts` proves the list complete: every source file that reads the disk is named here or accounted for, and a recorder of
+ * file reads checks each rule's real reads against these declarations and the import graph.
+ */
+/** One input of a rule that the import graph does not carry. */
+export interface CrossFileInput {
+    /** The published rule name (without the plugin prefix). */
+    readonly rule: string;
+    readonly kind: "content" | "exists" | "git";
+    readonly relativeTo: "file" | "side";
+    readonly globs: readonly string[];
+    /** For `git`: the line count above which the rule reads history; a file of fewer lines does not depend on it. */
+    readonly minLines?: number;
+    /** The linted files (side-root globs) whose result depends on the input. */
+    readonly appliesTo: readonly string[];
+    /** The source file of this package (relative to `src/`) that performs the read; the audit checks it exists and that no reader is missing. */
+    readonly reader: string;
+}
+/** The line count above which `file-size-growth` reads history: the soft budget of the shipped manifest (500) is never lower than this. */
+export declare const HISTORY_MIN_LINES = 400;
+/** Every disk read of this canon's rules beyond the import graph. */
+export declare const crossFileInputs: readonly CrossFileInput[];

package/dist/lib/cross-file-inputs.js

@@ -0,0 +1,31 @@
+/**
+ * The files a rule of this canon reads that ESLint's own import graph does not carry.
+ *
+ * The result cache of `starci app lint` (contexts/project/check-cache.md, ESLint) re-lints a file when it or a file it reaches through imports
+ * changed. A rule that reads another file by path, with `fs` (a sibling, a directory listing, a manifest, a module file it follows by hand),
+ * has an input the import graph cannot see, so the rule declares it here and the cache dirties the files that depend on it:
+ *
+ * - `content`: the rule reads the bytes of the files the globs match; a changed, added or removed match dirties the dependants.
+ * - `exists`: the rule only asks whether a file is there or lists a folder; an added or removed match dirties the dependants.
+ * - `git`: the rule compares the file with git history (the merge-base with the base branch), which no file holds; a change of the merge-base
+ *   dirties every dependant of more than `minLines` lines (the rule reads history only for a file over its size budget). `globs` is empty.
+ *
+ * `globs` are relative to the linted file's folder (`relativeTo: "file"`) or to the side root, the folder of the side's `eslint.config.mjs`
+ * (`relativeTo: "side"`); they use `*`, `**`, `?` and `{a,b}`, posix separators. `appliesTo` are side-root globs of the linted files that
+ * depend on the input. A declaration may be wider than the read, never narrower: a too wide one costs a lint, a too narrow one a wrong answer.
+ * `cross-file-inputs.spec.ts` proves the list complete: every source file that reads the disk is named here or accounted for, and a recorder of
+ * file reads checks each rule's real reads against these declarations and the import graph.
+ */
+/** The line count above which `file-size-growth` reads history: the soft budget of the shipped manifest (500) is never lower than this. */
+export const HISTORY_MIN_LINES = 400;
+/** Every disk read of this canon's rules beyond the import graph. */
+export const crossFileInputs = [
+    // the manifest name of the package that owns the linted file (the nearest package.json upward)
+    { rule: "no-grammar-shim", kind: "content", relativeTo: "side", globs: ["**/package.json", "../package.json"], appliesTo: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"], reader: "grammar-shim.ts" },
+    // an operation import is told from a workspace package by that package's manifest and entry
+    { rule: "swr-only-in-family", kind: "content", relativeTo: "side", globs: ["packages/*/package.json", "packages/*/src/**/*.{ts,tsx}"], appliesTo: ["**/*.{ts,tsx}"], reader: "swr-family.ts" },
+    { rule: "operations-only-in-swr-hooks", kind: "content", relativeTo: "side", globs: ["packages/*/package.json", "packages/*/src/**/*.{ts,tsx}"], appliesTo: ["**/*.{ts,tsx}"], reader: "swr-family.ts" },
+    { rule: "subscription-refetches-snapshot", kind: "content", relativeTo: "side", globs: ["packages/*/package.json", "packages/*/src/**/*.{ts,tsx}"], appliesTo: ["**/*.{ts,tsx}"], reader: "swr-family.ts" },
+    // an over-budget file is compared with its size at the merge-base with the base branch
+    { rule: "file-size-growth", kind: "git", relativeTo: "side", globs: [], minLines: HISTORY_MIN_LINES, appliesTo: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"], reader: "size-growth.ts" },
+];

package/dist/lib/freestyle.d.ts

@@ -0,0 +1,10 @@
+import type { AnyContext, Node, Rule } from "./rule.js";
+/** True when a reported node is a raw element (or its attribute) inside a Freestyle subtree. */
+export declare const isFreestyleRaw: (context: AnyContext, node: Node) => boolean;
+/**
+ * The context a rule is given inside the exemption: the same context, whose `report` drops a finding about a raw element in a
+ * Freestyle subtree. Every other property, and every other finding, is the original's.
+ */
+export declare const freestyleContext: <C extends object>(context: C) => C;
+/** A canon rule that leaves the raw elements of a Freestyle subtree alone. */
+export declare const exemptFreestyle: <M extends string, O extends readonly unknown[]>(rule: Rule<M, O>) => Rule<M, O>;

package/dist/lib/freestyle.js

@@ -0,0 +1,87 @@
+import { isNode } from "./ast.js";
+import { importOf } from "./bindings.js";
+/** The Grammar package entries a component can be imported from. */
+const GRAMMAR_SOURCE = /^@starci\/grammar(?:\/(?:common|core|offset-pop))?$/;
+/** The element name of a JSX name: `Freestyle`, or `G.Freestyle` as `Freestyle`. */
+const nameOf = (name) => {
+    if (name.type === "JSXIdentifier")
+        return name.name;
+    if (name.type === "JSXMemberExpression")
+        return name.property.name;
+    return null;
+};
+/** True for a `Freestyle` element name. */
+const isFreestyleName = (name) => nameOf(name) === "Freestyle";
+/** The opening element a node is about: the node itself, its attribute's element, or the nearest enclosing element. */
+const owningOpening = (node) => {
+    for (let current = node; current !== undefined && current !== null; current = current.parent) {
+        if (current.type === "JSXOpeningElement")
+            return current;
+        if (current.type === "JSXElement")
+            return current.openingElement;
+    }
+    return null;
+};
+/** The leftmost identifier of a JSX name (`G` of `G.Item`), or null for a namespaced name. */
+const rootOf = (name) => {
+    if (name.type === "JSXIdentifier")
+        return name;
+    if (name.type === "JSXMemberExpression")
+        return rootOf(name.object);
+    return null;
+};
+/** True when the element is a Grammar component other than Freestyle: judged normally. */
+const isGrammarComponent = (context, opening) => {
+    if (isFreestyleName(opening.name))
+        return false;
+    const root = rootOf(opening.name);
+    if (root === null || !/^[A-Z]/.test(root.name))
+        return false;
+    const origin = importOf(context, root);
+    return origin !== null && GRAMMAR_SOURCE.test(origin.source);
+};
+/** True when the opening element is a Freestyle element or sits inside one. */
+const inFreestyle = (opening) => {
+    if (isFreestyleName(opening.name))
+        return true;
+    for (let current = opening.parent?.parent; current !== undefined && current !== null; current = current.parent) {
+        if (current.type === "JSXElement" && isFreestyleName(current.openingElement.name))
+            return true;
+    }
+    return false;
+};
+/** True when a reported node is a raw element (or its attribute) inside a Freestyle subtree. */
+export const isFreestyleRaw = (context, node) => {
+    const opening = owningOpening(node);
+    return opening !== null && inFreestyle(opening) && !isGrammarComponent(context, opening);
+};
+/** The node a report descriptor is about, or null when it names only a location. */
+const reportedNode = (descriptor) => {
+    if (typeof descriptor !== "object" || descriptor === null)
+        return null;
+    const node = Reflect.get(descriptor, "node");
+    return isNode(node) ? node : null;
+};
+/** True for a rule context that can resolve an import (it carries the source code). */
+const readsImports = (context) => "sourceCode" in context;
+/**
+ * The context a rule is given inside the exemption: the same context, whose `report` drops a finding about a raw element in a
+ * Freestyle subtree. Every other property, and every other finding, is the original's.
+ */
+export const freestyleContext = (context) => {
+    const report = Reflect.get(context, "report");
+    if (typeof report !== "function")
+        return context;
+    const judged = (descriptor, ...rest) => {
+        const node = reportedNode(descriptor);
+        if (node !== null && readsImports(context) && isFreestyleRaw(context, node))
+            return undefined;
+        return Reflect.apply(report, context, [descriptor, ...rest]);
+    };
+    return Object.create(context, { report: { value: judged, enumerable: true } });
+};
+/** A canon rule that leaves the raw elements of a Freestyle subtree alone. */
+export const exemptFreestyle = (rule) => ({
+    ...rule,
+    create: (context) => rule.create(freestyleContext(context)),
+});

package/dist/native-controls.js

@@ -12,6 +12,7 @@
  * control. If the grammar lacks the control, the fix is to add it to the grammar, not to draw one here.
  */
 import { defineRule } from "./lib/rule.js";
+import { exemptFreestyle } from "./lib/freestyle.js";
 import { attribute } from "./lib/ast.js";
 /** Intrinsic elements a reader operates, that the grammar renders for the product. */
 const NATIVE = new Set(["select", "input", "textarea", "button"]);
@@ -37,7 +38,7 @@ export const noNativeFormControl = defineRule({
 });
 // -- NATIVE-2 --------------------------------------------------------------------------------------
 /** No bare `<img>`; the framework's image owns size, format, lazy loading and layout shift. */
-export const noNativeImg = defineRule({
+export const noNativeImg = exemptFreestyle(defineRule({
     meta: {
         type: "problem",
         docs: { description: "Use `next/image`, never a bare `<img>`." },
@@ -54,7 +55,7 @@ export const noNativeImg = defineRule({
             },
         };
     },
-});
+}));
 // -- NATIVE-3 --------------------------------------------------------------------------------------
 /** Every `next/image` reserves its space: a size, or `fill` inside a sized parent with `sizes`. */
 export const imageHasSize = defineRule({

package/dist/project-graph.d.ts

@@ -3,3 +3,30 @@ import type { Recommended, Rules } from "./lib/rule.js";
 export declare const rules: Rules;
 /** Every one at error. */
 export declare const recommended: Recommended;
+/** One finding of the project graph on a file, as the rule of its enforcer reports it. Lines and columns count from 1, the way the machine names them. */
+export interface ProjectGraphFinding {
+    readonly rule: string;
+    readonly code: string;
+    readonly line: number;
+    readonly column: number;
+    readonly message: string;
+}
+/** The project-graph findings of one side, by side-relative posix path, each list sorted by line, column, code and message. */
+export interface ProjectGraphSnapshot {
+    readonly files: number;
+    readonly byFile: Readonly<Record<string, readonly ProjectGraphFinding[]>>;
+}
+/**
+ * The findings every project-graph rule of this canon reports, per file, from one fresh build of the side's graph.
+ *
+ * The result cache of `starci app lint` calls this once for a side whose files changed and compares each file's findings with the recorded
+ * ones: a file whose graph findings differ is linted again by ESLint itself, so ESLint stays the only emitter of each message. It is the very
+ * graph the rules read (same machine, same manifest, same filter), never a second judge.
+ *
+ * @param input - The side folder (`repoRoot`, the folder of the side's `eslint.config.mjs`); `injectedTypeScript` is for hermetic fixtures only.
+ * @returns The findings of the rules of `recommended`, keyed by path relative to the side folder.
+ */
+export declare const projectGraph: ({ repoRoot, injectedTypeScript }: {
+    repoRoot: string;
+    injectedTypeScript?: object;
+}) => ProjectGraphSnapshot;

package/dist/project-graph.js

@@ -7,7 +7,8 @@
  * rules and their codes is `LINT_ENFORCERS` of the machine (scripts/hfs/architecture/surface.mjs); `starci app check` keeps the
  * findings that have no TypeScript file to sit on. A graph that cannot be built stops the run with the machine's message.
  */
-import { LINT_ENFORCERS } from "#runtime/scripts/hfs/architecture/surface.mjs";
+import { LINT_ENFORCERS, belongsTo, codeOf } from "#runtime/scripts/hfs/architecture/surface.mjs";
+import { projectGraph as buildProjectGraph, resetProjectGraphs } from "#runtime/scripts/hfs/project-graph.mjs";
 import { projectRule } from "#runtime/scripts/hfs/project-rule.mjs";
 import { hfsOf } from "./lib/hfs.js";
 import { RUNTIME_ROOT } from "./lib/package-root.js";
@@ -17,3 +18,31 @@ const mine = LINT_ENFORCERS.filter((enforcer) => enforcer.plugins.includes("fe")
 export const rules = Object.fromEntries(mine.map((e) => [e.id, projectRule({ enforcer: e, runtimeRoot: RUNTIME, hfsOf })]));
 /** Every one at error. */
 export const recommended = Object.fromEntries(mine.map((e) => [`starci-fe/${e.id}`, "error"]));
+/**
+ * The findings every project-graph rule of this canon reports, per file, from one fresh build of the side's graph.
+ *
+ * The result cache of `starci app lint` calls this once for a side whose files changed and compares each file's findings with the recorded
+ * ones: a file whose graph findings differ is linted again by ESLint itself, so ESLint stays the only emitter of each message. It is the very
+ * graph the rules read (same machine, same manifest, same filter), never a second judge.
+ *
+ * @param input - The side folder (`repoRoot`, the folder of the side's `eslint.config.mjs`); `injectedTypeScript` is for hermetic fixtures only.
+ * @returns The findings of the rules of `recommended`, keyed by path relative to the side folder.
+ */
+export const projectGraph = ({ repoRoot, injectedTypeScript }) => {
+    resetProjectGraphs();
+    const graph = buildProjectGraph({ repoRoot, ...(injectedTypeScript === undefined ? {} : { injectedTypeScript }), runtimeRoot: RUNTIME });
+    const byFile = {};
+    for (const [file, findings] of graph.byFile) {
+        for (const finding of findings) {
+            for (const enforcer of mine.filter((entry) => belongsTo(entry, finding))) {
+                const line = finding.line !== undefined && Number.isInteger(finding.line) && finding.line >= 1 ? finding.line : 1;
+                const column = finding.column !== undefined && Number.isInteger(finding.column) && finding.column >= 1 ? finding.column : 1;
+                (byFile[file] ??= []).push({ rule: `starci-fe/${enforcer.id}`, code: String(codeOf(finding)), line, column, message: String(finding.message) });
+            }
+        }
+    }
+    const order = (a, b) => a.line - b.line || a.column - b.column || a.code.localeCompare(b.code) || a.message.localeCompare(b.message);
+    for (const list of Object.values(byFile))
+        list.sort(order);
+    return { files: graph.files, byFile };
+};

package/dist/surface-rules.js

@@ -4,6 +4,7 @@ import { functionOf, importOf, isFn, patternPath, unwrap, variableOf } from "./l
 import { typedClassStrings, typedPropertyStrings } from "./lib/typed-class-values.js";
 import { reactHookOf } from "./lib/react.js";
 import { defineRule } from "./lib/rule.js";
+import { exemptFreestyle } from "./lib/freestyle.js";
 /** True when `text` is a string among `values`; any other value never is. */
 const isOneOf = (values, text) => typeof text === "string" && values.includes(text);
 /** The name a member expression reads: its static computed text or its identifier. */
@@ -316,7 +317,7 @@ export const nestedControlVariant = defineRule({
     },
 });
 /** App classes carry layout; Grammar owns surface paint. */
-export const noAppSurfacePaint = defineRule({
+export const noAppSurfacePaint = exemptFreestyle(defineRule({
     meta: {
         type: "problem",
         docs: { description: "App composition CSS is layout-only; Grammar paints surfaces." },
@@ -377,9 +378,9 @@ export const noAppSurfacePaint = defineRule({
             },
         };
     },
-});
+}));
 /** PADDING-0: app padding wrappers cannot add a second horizontal inset to Grammar's list or section caption. */
-export const noListPanelPadding = defineRule({
+export const noListPanelPadding = exemptFreestyle(defineRule({
     meta: {
         type: "problem",
         docs: { description: "PADDING-0: panel lists and section captions share the Grammar surface's content edge." },
@@ -412,7 +413,7 @@ export const noListPanelPadding = defineRule({
             },
         };
     },
-});
+}));
 /** BOUNDARY-1 case-5: only content bands carry inset; horizontal separators reach the surface edges. */
 export const dividerFullBleed = defineRule({
     meta: {

package/dist/tokens.js

@@ -1,12 +1,13 @@
 /** Universal closed-token discipline, independent of a Grammar scale. */
 import { classTextVisitors } from "./lib/class-text.js";
 import { defineRule } from "./lib/rule.js";
+import { exemptFreestyle } from "./lib/freestyle.js";
 /** A bracketed length: a value chosen once, for one screen, findable by nobody. */
 const ARBITRARY_LENGTH = /\b(?:gap|gap-x|gap-y|p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|space-x|space-y|size|w|h|min-w|min-h|max-w|max-h)-\[[^\]]+\]/;
 /** A raw colour, which escapes the semantic palette even when it matches it today. */
 const RAW_COLOUR = /\b(?:text|bg|border|ring|from|to|via|fill|stroke|shadow|decoration)-\[#[0-9a-fA-F]/;
 /** An arbitrary value escapes the system, whatever it happens to evaluate to. */
-export const noArbitraryValue = defineRule({
+export const noArbitraryValue = exemptFreestyle(defineRule({
     meta: {
         type: "problem",
         docs: { description: "Bracketed lengths and raw colours escape the closed vocabulary." },
@@ -28,7 +29,7 @@ export const noArbitraryValue = defineRule({
                 context.report({ node, messageId: "colour", data: { cls: colour[0] } });
         });
     },
-});
+}));
 /** Rules of universal token discipline. */
 export const rules = { "no-arbitrary-value": noArbitraryValue };
 /** Every token-discipline rule is mandatory. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.6.2",
+  "version": "9.6.5",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",
@@ -61,7 +61,7 @@
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\" && tsc -p tsconfig.build.json && node -e \"const fs = require('node:fs'); for (const f of fs.readdirSync('dist', {recursive: true}).filter((n) => n.endsWith('.d.ts'))) fs.writeFileSync('dist/' + f, fs.readFileSync('dist/' + f, 'utf8').replace(/((?:from |import\\()['\\x22]\\.\\.?\\/[^'\\x22]+)\\.ts(['\\x22])/g, (all, head, quote) => head + '.js' + quote))\"",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "node --test \"src/**/*.spec.ts\"",
+    "test": "node --import ./fixtures/fs-audit-preload.ts --test \"src/**/*.spec.ts\"",
     "prepack": "npm run typecheck && npm run build && npm test"
   },
   "keywords": [

package/runtime/bundle.json

@@ -32,6 +32,7 @@
     "scripts/api/git/remote.mjs",
     "scripts/api/git/rev-parse-query.mjs",
     "scripts/api/git/show.mjs",
+    "scripts/api/git/tag.mjs",
     "scripts/hfs/allows.mjs",
     "scripts/hfs/architecture/ast-walks.mjs",
     "scripts/hfs/architecture/automatic-gates.mjs",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,42 +31,42 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.16.2
+    version: 0.16.5
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.9.2
+    version: 3.10.0
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.6.2
+    version: 9.6.5
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.16.2
+    version: 0.16.5
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.16.2
+    version: 0.16.5
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-offset-pop/package.json
     why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
   '@starci/stylelint-canon':
-    version: 2.2.1
+    version: 2.3.0
     group: starci
     install: registry
     side: fe
@@ -85,7 +85,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.5.3
+    version: 2.6.0
     group: starci
     install: registry
     side: be
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.12.2
+    version: 4.13.2
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/slots.yaml

@@ -1956,7 +1956,7 @@ slots:
     tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts; plus src/tests/integration/<provider>/ (R112)
     coverage: required
     budget: {indexExports: 80}   # a provider's port surface includes clients, config, options, tokens and errors
-    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING, BE_AI_KEY_CUSTODY, BE_AI_GATEWAY_CLIENT]
+    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING, BE_AI_KEY_CUSTODY, BE_AI_GATEWAY_CLIENT, BE_AI_VIRTUAL_KEY]
   - id: be.integrations.model
     since: 3.1.0
     profiles: [be]

package/runtime/scripts/api/git/tag.mjs

@@ -0,0 +1,4 @@
+// tag.mjs — `git tag <args>`: list or create tags (--points-at <rev>, -l <pattern>, -a <name> -m <message>).
+import { runGit } from './lib.mjs';
+/** The spawn result {status, stdout, stderr, error} of `git tag ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const tag = (args = [], options = {}) => runGit(['tag', ...args], options);

package/runtime/scripts/hfs/rules/database-migrations.mjs

@@ -3,6 +3,7 @@
 import { lsTree } from '../../api/git/ls-tree.mjs';
 import { mergeBase } from '../../api/git/merge-base.mjs';
 import { show } from '../../api/git/show.mjs';
+import { tag } from '../../api/git/tag.mjs';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
 import { eachInOrder, findInOrder } from '../../lib/in-order.mjs';
 import { sameText } from '../../lib/same-text.mjs';
@@ -37,12 +38,21 @@ export function defaultGit(args, { cwd }) {
         const sha = mergeBase(cwd, rest[0], rest[1]);
         return { ok: sha !== null, stdout: sha ?? '' };
     }
+    if (verb === 'previous-release')
+        return previousReleaseTag(cwd, env, rest[0]);
     let call = show;
     if (verb === 'ls-tree')
         call = lsTree;
     const result = call(rest, { cwd, env, maxBuffer: 64 * 1024 * 1024 });
     return { ok: !result.error && result.status === 0, stdout: result.stdout };
 }
+/** The nearest release tag before HEAD: the newest version among the tags HEAD contains that do not point at HEAD itself. `pattern` is a tag glob (v*). */
+function previousReleaseTag(cwd, env, pattern) {
+    const listed = (args) => { const result = tag(args, { cwd, env }); return !result.error && result.status === 0 ? String(result.stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean) : []; };
+    const here = new Set(listed(['--points-at', 'HEAD']));
+    const previous = listed(['--merged', 'HEAD', '--list', pattern, '--sort=-v:refname']).find((name) => !here.has(name));
+    return { ok: previous !== undefined, stdout: previous ?? '' };
+}
 const runGit = (git, repoRoot, args) => Promise.resolve(git(args, { cwd: repoRoot }))
     .then((result) => ({ ok: result?.ok === true, stdout: String(result?.stdout ?? '') }));
 async function baseShaOf(git, repoRoot, base) {
@@ -515,6 +525,51 @@ function destructiveFileFindings(file, text, references) {
         return finding ? [finding] : [];
     });
 }
+const BE_SQL_SOURCE = /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/;
+/** The tag glob of a release (release.tagPrefix defaults to v). */
+const RELEASE_TAG_GLOB = 'v*';
+/**
+ * A contract migration must not ship in the same release as the code change it depends on (cicd.md, Database migrations). The deploy applies
+ * a contract migration right after the accept, while the release it replaced is still the rollback target: if that release's code still names
+ * the destroyed object, a rollback after the contract would run code against a schema that no longer has it. The check judges exactly that
+ * with git: each contract migration that is new since the previous release tag (absent there) is read for the objects it destroys, and the
+ * be/src sources AS THEY WERE AT THE PREVIOUS RELEASE TAG must not reference them (the sources at HEAD are judged by destructiveMigrationFindings).
+ * The first release, a repository without a release tag, or an unreadable git history has no previous release and no finding. It reports
+ * DB_MIGRATION_DESTRUCTIVE (R259), a hard blocker: ship the code change in one release and its contract migration in the next.
+ */
+export async function contractReleaseFindings({ repoRoot, migrations, git }) {
+    const contracts = migrations.filter((file) => /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/.test(file));
+    if (!contracts.length)
+        return [];
+    const previous = await runGit(git, repoRoot, ['previous-release', RELEASE_TAG_GLOB]);
+    const release = previous.stdout.trim();
+    if (!previous.ok || !release)
+        return [];
+    const known = new Set(await migrationFilesAt(git, repoRoot, release));
+    const fresh = contracts.filter((file) => !known.has(file));
+    if (!fresh.length)
+        return [];
+    const listing = await runGit(git, repoRoot, ['ls-tree', '-r', '--name-only', '-z', release, '--', 'be/src']);
+    const sources = listing.ok ? listing.stdout.split('\0').filter((file) => BE_SQL_SOURCE.test(file)) : [];
+    if (!sources.length)
+        return [];
+    const ts = loadTypescript(repoRoot, HERE);
+    if (!ts)
+        return [found(DB_MIGRATION_DESTRUCTIVE, 'hfs.json', 'the contract-release check requires the TypeScript parser to read the be/src references of the previous release')];
+    const references = [];
+    await eachInOrder(sources, async (file) => {
+        references.push({ file, scopes: sourceNameScopes(ts, await baseFileText(git, repoRoot, release, file) ?? '', file) });
+    });
+    return fresh.flatMap((file) => {
+        const text = readText(repoRoot, file);
+        if (text === null)
+            return [];
+        return databaseSqlStatements(databaseExecutableTokens(text)).flatMap(destructiveObjects).flatMap((object) => {
+            const reference = references.find(({ scopes }) => referencesObject(scopes, object));
+            return reference ? [found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destroys ${object.name}, which the previous release ${release} still references in ${reference.file}; the contract migration runs right after the accept while that release is the rollback target: ship the code change in one release and this contract migration in the next`, { line: object.line, object: object.name, release, reference: reference.file })] : [];
+        });
+    });
+}
 /** Destructive changes require a contract migration and no remaining SQL/entity reference in be/src. */
 export function destructiveMigrationFindings({ repoRoot, migrations, files }) {
     const sources = files.filter((file) => /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/.test(file));