@starci/eslint-canon-fe 9.15.0 → 9.16.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 9.16.0 - 2026-11-06
+
+- Added: `starci-fe/renderer-presentation-only` (R384, `FE_RENDERER_LOGIC`, RENDERER-PURITY-1) at error: in a client renderer of a root workspace package (`packages/<pkg>/src/client/**/*.tsx`) data computation (arithmetic between two data values, `+=` accumulation), aggregation (`reduce`, a chain of `filter`/`sort`/`flatMap`, `Math.max/min(...spread)`), date math (`Date.now()`/`getTime()` arithmetic, Date setters, date-fns add/sub/diff/compare/round), a relational comparison of two data values and a mutation outside a declared action (a write to a prop or an outer value, an in-place array mutator on data, `fetch`, storage, a beacon) are refused; they belong in a measured `.ts` module the renderer calls. Mapping, display filters, ternaries that pick a view, comparisons and arithmetic with a literal and `handle.run(...)` stay allowed. A front-end package (`fe/packages/*`) is not judged by it.
+
+## 9.15.1 - 2026-11-05
+
+- Fixed (FE-PACKAGES-2): the package config (`starciFePackagesConfig` and `scopeToPackages`, which the Grammar family's `...PackagesConfig` reads) covered only `packages/*/src/workbench/**` and `src/public/**`, and the back-end package config takes no `.tsx`, so a `.tsx` file anywhere else in a root package (a `src/client/` renderer of a block library) matched no config and was never linted. `PACKAGE_SOURCE_FILES` now also lists `packages/*/src/**/*.tsx`: every React file of a package source gets the front-end canon and the Grammar family rules, as the files of `fe/packages` do. The workbench contract stays back end; a plain `.ts` file outside the two subpaths stays the back-end canon's.
+
 ## 9.15.0 - 2026-11-05
 
 - Changed (decision release-only-what-changed): the canon reads the @starci/hfs runtime from the installed hfs at run time, which it peers by `~5.13.0`, and bundles no copy; `runtime/` keeps only the project graph rule, the jsdoc, sonar and next helpers and the package-scripts template, and the stale forks (slots 3.13.0) are gone.

package/dist/index.js

@@ -29,6 +29,7 @@ import { recommended as landmarkRecommended, rules as landmarkRules } from "./la
 import { recommended as listsRecommended, rules as listsRules } from "./lists.js";
 import { recommended as loadingRecommended, rules as loadingRules } from "./loading.js";
 import { recommended as directiveFirstRecommended, rules as directiveFirstRules } from "./directive-first.js";
+import { recommended as rendererPurityRecommended, rules as rendererPurityRules } from "./renderer-purity.js";
 import { recommended as explicitSurfaceRecommended, rules as explicitSurfaceRules } from "./explicit-surface.js";
 import { recommended as skeletonStatesRecommended, rules as skeletonStatesRules } from "./skeleton-states.js";
 import { recommended as lintEscapeRecommended, rules as lintEscapeRules } from "./lint-escape-hatch.js";
@@ -78,6 +79,7 @@ const CONTRIBUTIONS = [
     { law: "lists", rules: listsRules, recommended: listsRecommended },
     { law: "loading", rules: loadingRules, recommended: loadingRecommended },
     { law: "directive-first", rules: directiveFirstRules, recommended: directiveFirstRecommended },
+    { law: "renderer-purity", rules: rendererPurityRules, recommended: rendererPurityRecommended },
     { law: "explicit-surface", rules: explicitSurfaceRules, recommended: explicitSurfaceRecommended },
     { law: "skeleton-states", rules: skeletonStatesRules, recommended: skeletonStatesRecommended },
     { law: "lint-escape-hatch", rules: lintEscapeRules, recommended: lintEscapeRecommended },

package/dist/lib/config.d.ts

@@ -88,7 +88,7 @@ export declare const buildPlainSourceConfig: ({ root, plugin, hooks, reactHooks,
     readonly sonar: SonarPlugins;
     readonly canon?: boolean;
 }) => Linter.Config[];
-/** The front-end subpaths of a root workspace package: its workbench (drawn with Grammar) and its public face; the React-free workbench contract stays back end. */
+/** The front-end files of a root workspace package: its workbench (drawn with Grammar) and its public face, and every `.tsx` file of the package source wherever it sits (a `src/client/` renderer is drawn too: FE-PACKAGES-2); the React-free workbench contract stays back end. */
 export declare const PACKAGE_SOURCE_FILES: readonly string[];
 /** What a package folder never lints: installed packages, build output, generated wire types. */
 export declare const PACKAGE_IGNORED: readonly string[];

package/dist/lib/config.js

@@ -105,7 +105,7 @@ export const SLOT_FREE_RULES = Object.freeze([
     "outcome-kinds-exhaustive", "no-await-in-loop", "prefer-code-point", "prefer-string-raw", "no-nested-conditional", "no-void-operator", "no-unused-import",
     "prefer-export-from", "no-unused-prop-types", "media-has-caption", "max-params",
     "no-list-panel-padding", "no-hand-built-panes", "no-table-in-card", "no-heading-above-card", "no-selectable-tag-group", "no-fill-command-in-header", "no-app-surface-paint", "divider-full-bleed", "control-height", "selection-fill-no-check", "no-grammar-shim",
-    "no-swr-default-array", "no-foreign-slot-status", "no-validating-as-loading", "no-placeholder-object", "no-hand-skeleton", "explicit-export-surface", "directive-first",
+    "no-swr-default-array", "no-foreign-slot-status", "no-validating-as-loading", "no-placeholder-object", "no-hand-skeleton", "explicit-export-surface", "directive-first", "renderer-presentation-only",
     "button-intent-required", "destructive-confirm-in-dialog", "single-commit-per-render", "no-commit-in-collection-item",
 ]);
 /** The source of a plain front-end tree: its `src/`. */
@@ -148,8 +148,8 @@ export const buildPlainSourceConfig = ({ root, plugin, hooks, reactHooks, tsPlug
         { files: [...PLAIN_SOURCE_FILES], ignores: [...OUTSIDE_THE_SCAN_FILES], plugins: { sonarjs: sonar.sonarjs, unicorn: sonar.unicorn }, rules: sonarWayRules(sonar.sonarjs, "fe").rules },
     ];
 };
-/** The front-end subpaths of a root workspace package: its workbench (drawn with Grammar) and its public face; the React-free workbench contract stays back end. */
-export const PACKAGE_SOURCE_FILES = Object.freeze(["packages/*/src/workbench/**/*.{ts,tsx}", "packages/*/src/public/**/*.{ts,tsx}"]);
+/** The front-end files of a root workspace package: its workbench (drawn with Grammar) and its public face, and every `.tsx` file of the package source wherever it sits (a `src/client/` renderer is drawn too: FE-PACKAGES-2); the React-free workbench contract stays back end. */
+export const PACKAGE_SOURCE_FILES = Object.freeze(["packages/*/src/workbench/**/*.{ts,tsx}", "packages/*/src/public/**/*.{ts,tsx}", "packages/*/src/**/*.tsx"]);
 const PACKAGE_CONTRACT = Object.freeze(["packages/*/src/workbench/contract/**"]);
 /** What a package folder never lints: installed packages, build output, generated wire types. */
 export const PACKAGE_IGNORED = Object.freeze(["**/node_modules/**", "**/.next/**", "**/dist/**", "**/coverage/**", "**/__generated__/**"]);

package/dist/lib/why.d.ts

@@ -102,6 +102,11 @@ export declare const why: {
         en: string;
         fix: string;
     };
+    "renderer-presentation-only": {
+        code: string;
+        en: string;
+        fix: string;
+    };
     "directive-first": {
         code: string;
         en: string;

package/dist/lib/why.js

@@ -102,6 +102,11 @@ export const why = {
         en: "`<file>` draws a skeleton by hand.",
         fix: "Pass isLoading to the Grammar component and let it draw its loading structure; the block hands it the same-shape placeholder (FE-ERROR-1).",
     },
+    "renderer-presentation-only": {
+        code: "FE_RENDERER_LOGIC",
+        en: "`<file>` is a client renderer of a root package that holds `<what>`.",
+        fix: "Move the data computation, aggregation, date math, domain comparison or mutation into a measured .ts module (rules/ or a hook beside it) that the renderer calls; the renderer maps, chooses what to show and formats, and runs only declared actions.",
+    },
     "directive-first": {
         code: "FE_DIRECTIVE_FIRST",
         en: "`<file>` has a `<what>` directive below another statement.",

package/dist/renderer-purity.d.ts

@@ -0,0 +1,11 @@
+import { type Recommended } from "./lib/rule.js";
+/** True for a client renderer of a root workspace package; a front-end package (`fe/packages/*`) is judged by the front-end canon alone. */
+export declare const isRootPackageRenderer: (filename: string) => boolean;
+type Id = "arithmetic" | "accumulation" | "aggregation" | "chain" | "dateMath" | "dateFns" | "domainRule" | "mutation" | "network";
+/** The one rule of the law. */
+export declare const rules: {
+    "renderer-presentation-only": import("./lib/rule.js").Rule<Id, []>;
+};
+/** The rule reaches consumers at error. */
+export declare const recommended: Recommended;
+export {};

package/dist/renderer-purity.js

@@ -0,0 +1,238 @@
+/**
+ * RENDERER-PURITY-1: a client renderer of a root workspace package (`packages/<pkg>/src/client/**\/*.tsx`) holds presentation only: mapping rows to
+ * components, choosing what to show, formatting. The business logic it would otherwise hold lives in a measured `.ts` module the renderer calls,
+ * where the unit run holds it at 100 per file (BE-TEST-13); the renderer itself is outside coverage (SHARED-TEST-1).
+ *
+ * Refused in such a file, each as `FE_RENDERER_LOGIC`:
+ *   - data computation: arithmetic (`- * / % **`) between two non-literal values, `+=`/`-=` accumulation of a data value;
+ *   - aggregation: `.reduce`/`.reduceRight`, two or more of `.filter`/`.sort`/`.toSorted`/`.flatMap` in one chain, `Math.max/min(...spread)`;
+ *   - date math: arithmetic on `Date.now()`, `new Date()` or `.getTime()`, the `Date` setters, the date-fns functions that add, subtract, compare or round;
+ *   - a domain rule: a relational comparison (`< <= > >=`) between two data values (a size or an index against a collection length is display);
+ *   - a mutation outside a declared action: a write to a prop or an outer value, an in-place array mutator on data, `fetch`, storage, a beacon.
+ * Allowed: `.map`, one `.filter` (a display filter), ternaries and `&&` that pick a view, comparisons with a literal (`rows.length === 0`),
+ * arithmetic with a literal (`index + 1`, `ratio * 100`), a template, and a call of a declared action (`handle.run(...)`).
+ */
+import { TSESLint } from "@typescript-eslint/utils";
+import { defineRule } from "./lib/rule.js";
+const RENDERER = /(?:^|\/)packages\/[^/]+\/src\/client\/.+\.tsx$/u;
+const FRONT_END_PACKAGE = /(?:^|\/)fe\/packages\//u;
+/** True for a client renderer of a root workspace package; a front-end package (`fe/packages/*`) is judged by the front-end canon alone. */
+export const isRootPackageRenderer = (filename) => {
+    const path = filename.replaceAll("\\", "/");
+    return RENDERER.test(path) && !FRONT_END_PACKAGE.test(path);
+};
+const ARITHMETIC = new Set(["-", "*", "/", "%", "**"]);
+const RELATIONAL = new Set(["<", "<=", ">", ">="]);
+const COMPOUND = new Set(["+=", "-=", "*=", "/=", "%=", "**="]);
+const CHAINED = new Set(["filter", "sort", "toSorted", "flatMap"]);
+const IN_PLACE = new Set(["push", "pop", "shift", "unshift", "splice", "fill", "copyWithin", "reverse", "sort"]);
+const STORES = new Set(["localStorage", "sessionStorage", "indexedDB", "caches"]);
+const NETWORK = new Set(["fetch", "XMLHttpRequest", "WebSocket", "EventSource"]);
+const DATE_SETTER = /^set(?:UTC)?(?:Date|FullYear|Month|Hours|Minutes|Seconds|Milliseconds|Time)$/u;
+const DATE_FNS = /^(?:add|sub|differenceIn|diff|isBefore|isAfter|isSame|startOf|endOf|eachDay|intervalToDuration|closestTo|set[A-Z])/u;
+const COUNT_NAMES = new Set(["index", "i", "idx", "position", "length", "count", "size"]);
+const MESSAGES = {
+    arithmetic: "arithmetic on two data values ({{what}}) is data computation",
+    accumulation: "accumulating a data value with `{{what}}` is data computation",
+    aggregation: "`{{what}}` aggregates data",
+    chain: "a chain of {{what}} shapes data beyond a display filter",
+    dateMath: "{{what}} is date math",
+    dateFns: "`{{what}}` from date-fns is date math",
+    domainRule: "comparing two data values ({{what}}) is a domain rule, not a choice of view",
+    mutation: "{{what}} changes data outside a declared action",
+    network: "`{{what}}` reaches data outside a declared action",
+};
+const unwrap = (node) => {
+    if (node.type === "ChainExpression")
+        return unwrap(node.expression);
+    if (node.type === "TSNonNullExpression" || node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression")
+        return unwrap(node.expression);
+    return node;
+};
+const isLiteral = (node) => {
+    const inner = unwrap(node);
+    if (inner.type === "Literal")
+        return true;
+    if (inner.type === "TemplateLiteral")
+        return inner.expressions.length === 0;
+    return inner.type === "UnaryExpression" && isLiteral(inner.argument);
+};
+/** A value read from data: a member access or a call. A bare name may be a local the renderer derived, so it is not judged alone. */
+const isDataRead = (node) => {
+    const inner = unwrap(node);
+    return inner.type === "MemberExpression" || inner.type === "CallExpression";
+};
+const callee = (node) => {
+    const target = unwrap(node.callee);
+    if (target.type === "Identifier")
+        return { object: null, name: target.name };
+    if (target.type !== "MemberExpression")
+        return { object: null, name: null };
+    const name = target.computed ? (target.property.type === "Literal" ? String(target.property.value) : null) : target.property.type === "Identifier" ? target.property.name : null;
+    return { object: unwrap(target.object), name };
+};
+const text = (context, node) => {
+    const source = context.sourceCode.getText(node).replaceAll(/\s+/gu, " ");
+    return source.length > 48 ? `${source.slice(0, 45)}...` : source;
+};
+/** True when the expression reads a size or an index (display), so a comparison with it chooses a view. */
+const readsCount = (node) => {
+    const inner = unwrap(node);
+    if (inner.type === "Identifier")
+        return COUNT_NAMES.has(inner.name);
+    if (inner.type === "MemberExpression" && !inner.computed && inner.property.type === "Identifier")
+        return COUNT_NAMES.has(inner.property.name);
+    if (inner.type === "BinaryExpression")
+        return readsCount(inner.left) || readsCount(inner.right);
+    return false;
+};
+/** True for a value built in this renderer (a literal, a call's result, a `new`), which it may fill, as against a prop, an import or an alias of data. */
+const isFresh = (context, node) => {
+    const inner = unwrap(node);
+    if (inner.type === "ArrayExpression" || inner.type === "ObjectExpression" || inner.type === "NewExpression" || inner.type === "CallExpression")
+        return true;
+    if (inner.type === "MemberExpression")
+        return false;
+    if (inner.type !== "Identifier")
+        return false;
+    let scope = context.sourceCode.getScope(inner);
+    while (scope !== null) {
+        const variable = scope.set.get(inner.name);
+        if (variable !== undefined) {
+            const definition = variable.defs[0];
+            if (definition === undefined || definition.type !== TSESLint.Scope.DefinitionType.Variable)
+                return false;
+            const init = definition.node.init;
+            return init !== null && init !== undefined && init.type !== "Identifier" && isFresh(context, init);
+        }
+        scope = scope.upper;
+    }
+    return false;
+};
+const rootOf = (node) => {
+    const inner = unwrap(node);
+    return inner.type === "MemberExpression" ? rootOf(inner.object) : inner;
+};
+const dateOperand = (node) => {
+    const inner = unwrap(node);
+    if (inner.type === "NewExpression")
+        return inner.callee.type === "Identifier" && inner.callee.name === "Date";
+    if (inner.type !== "CallExpression")
+        return false;
+    const { object, name } = callee(inner);
+    return name === "getTime" || (name === "now" && object?.type === "Identifier" && object.name === "Date");
+};
+/** True inside the comparator of `.sort`/`.toSorted`: ordering rows by a field is display, whatever the subtraction inside it. */
+const inComparator = (context, node) => context.sourceCode.getAncestors(node).some((ancestor) => {
+    if (ancestor.type !== "CallExpression")
+        return false;
+    const { name } = callee(ancestor);
+    return (name === "sort" || name === "toSorted") && ancestor.arguments.some((argument) => argument.range[0] <= node.range[0] && node.range[1] <= argument.range[1]);
+});
+const chainLength = (node) => {
+    const links = [];
+    let current = node;
+    while (current.type === "CallExpression") {
+        const { object, name } = callee(current);
+        if (name !== null && CHAINED.has(name))
+            links.push(current);
+        if (object === null)
+            break;
+        current = object;
+    }
+    return links;
+};
+const rendererPurity = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "RENDERER-PURITY-1: a client renderer of a root package holds presentation only; data computation, aggregation, date math, domain rules and mutations live in measured .ts." },
+        schema: [],
+        messages: Object.fromEntries(Object.entries(MESSAGES).map(([id, message]) => [id, `FE_RENDERER_LOGIC: ${message}; move it into a measured .ts module the renderer calls (BE-TEST-13, FE-PACKAGES-2) and let the renderer map, choose and format.`])),
+    },
+    create(context) {
+        if (!isRootPackageRenderer(context.filename))
+            return {};
+        const seen = new Set();
+        const report = (node, messageId, what) => {
+            if (seen.has(node))
+                return;
+            seen.add(node);
+            context.report({ node, messageId, data: { what } });
+        };
+        const checkCall = (node) => {
+            const { object, name } = callee(node);
+            if (name === null)
+                return;
+            if (object === null && NETWORK.has(name))
+                report(node, "network", name);
+            if (name === "reduce" || name === "reduceRight")
+                report(node, "aggregation", `.${name}(...)`);
+            if ((name === "max" || name === "min") && object?.type === "Identifier" && object.name === "Math" && node.arguments.some((argument) => argument.type === "SpreadElement"))
+                report(node, "aggregation", `Math.${name}(...)`);
+            if (object !== null && DATE_SETTER.test(name))
+                report(node, "dateMath", `.${name}(...)`);
+            if (object?.type === "Identifier" && STORES.has(object.name) && name !== "getItem")
+                report(node, "network", `${object.name}.${name}`);
+            if (object?.type === "Identifier" && object.name === "navigator" && name === "sendBeacon")
+                report(node, "network", "navigator.sendBeacon");
+            if (object !== null && IN_PLACE.has(name) && !isFresh(context, object))
+                report(node, "mutation", `\`.${name}(...)\` on ${text(context, object)}`);
+            const links = chainLength(node);
+            if (links.length >= 2 && links[0] === node) {
+                for (const link of links)
+                    seen.add(link);
+                context.report({ node, messageId: "chain", data: { what: links.map((link) => `.${callee(link).name ?? ""}`).reverse().join("") } });
+            }
+        };
+        const checkWrite = (target, node) => {
+            const inner = unwrap(target);
+            if (inner.type !== "MemberExpression")
+                return;
+            if (!isFresh(context, rootOf(inner)))
+                report(node, "mutation", `writing ${text(context, inner)}`);
+        };
+        return {
+            CallExpression: checkCall,
+            BinaryExpression(node) {
+                if (ARITHMETIC.has(node.operator) || node.operator === "+") {
+                    if ((node.operator === "-" || node.operator === "+") && (dateOperand(node.left) || dateOperand(node.right)))
+                        report(node, "dateMath", text(context, node));
+                    else if (ARITHMETIC.has(node.operator) && !isLiteral(node.left) && !isLiteral(node.right) && (isDataRead(node.left) || isDataRead(node.right)) && !inComparator(context, node))
+                        report(node, "arithmetic", text(context, node));
+                    return;
+                }
+                if (!RELATIONAL.has(node.operator) || isLiteral(node.left) || isLiteral(node.right))
+                    return;
+                if (!isDataRead(node.left) && !isDataRead(node.right))
+                    return;
+                if (readsCount(node.left) || readsCount(node.right))
+                    return;
+                report(node, "domainRule", text(context, node));
+            },
+            AssignmentExpression(node) {
+                if (COMPOUND.has(node.operator) && !isLiteral(node.right) && isDataRead(node.right))
+                    report(node, "accumulation", node.operator);
+                checkWrite(node.left, node);
+            },
+            UpdateExpression(node) {
+                checkWrite(node.argument, node);
+            },
+            UnaryExpression(node) {
+                if (node.operator === "delete")
+                    checkWrite(node.argument, node);
+            },
+            ImportDeclaration(node) {
+                if (!/^date-fns(?:\/|$)/u.test(node.source.value))
+                    return;
+                for (const specifier of node.specifiers) {
+                    if (specifier.type === "ImportSpecifier" && specifier.imported.type === "Identifier" && DATE_FNS.test(specifier.imported.name))
+                        report(specifier, "dateFns", specifier.imported.name);
+                }
+            },
+        };
+    },
+});
+/** The one rule of the law. */
+export const rules = { "renderer-presentation-only": rendererPurity };
+/** The rule reaches consumers at error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/docs/renderer-purity.md

@@ -0,0 +1,17 @@
+# Renderer purity (RENDERER-PURITY-1, R384)
+
+A client renderer of a root workspace package (`packages/<pkg>/src/client/**/*.tsx`) holds presentation only: it maps rows to components, chooses what to show and formats. The unit run measures `.ts` only (BE-TEST-13) and the front end has no tests (SHARED-TEST-1), so logic written inside a renderer has no spec and no coverage bar. The logic lives in a measured `.ts` module (`rules/`, a hook beside the renderer) that the renderer calls.
+
+| Rule | Finding code | Fix |
+|---|---|---|
+| `starci-fe/renderer-presentation-only` | `FE_RENDERER_LOGIC` | Move the computation, aggregation, date math, domain comparison or mutation into a measured `.ts` module and call it; run an action through its declared `ActionHandle`. |
+
+Refused in such a file:
+
+- data computation: `-`, `*`, `/`, `%`, `**` between two non-literal values (one side a member access or a call), `+=`/`-=` accumulation of a data value;
+- aggregation: `.reduce`/`.reduceRight`, two or more of `.filter`/`.sort`/`.toSorted`/`.flatMap` in one chain, `Math.max/min(...spread)`;
+- date math: arithmetic on `Date.now()`, `new Date()` or `.getTime()`, the `Date` setters, the date-fns functions `add*`, `sub*`, `differenceIn*`, `diff*`, `isBefore`, `isAfter`, `isSame*`, `startOf*`, `endOf*`, `set*`;
+- a domain rule: `<`, `<=`, `>`, `>=` between two data values; a size or an index against a collection length is display and stays allowed;
+- a mutation outside a declared action: a write to a prop, a parameter or an imported value, an in-place array mutator (`push`, `splice`, `sort`, ...) on data, `fetch`, `localStorage`/`sessionStorage` writes, `navigator.sendBeacon`.
+
+Allowed: `.map`, one `.filter` (a display filter), a sort comparator, ternaries and `&&` that pick a view, comparisons and arithmetic with a literal (`rows.length === 0`, `index + 1`, `ratio * 100`), templates, values the renderer builds itself (a local array it fills, `useRef().current`), and `handle.run(...)` of a declared action. A front-end package (`fe/packages/*`) is judged by the front-end canon alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.15.0",
+  "version": "9.16.0",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",