@starci/eslint-canon-fe 9.9.9 → 9.9.10

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 9.9.10
+
+- Changed: Refresh shared repository identity and release-aligned canon data.
+
+- Fixed: Preserve generated-contract provenance in front-end tier and bounds checks.
+
 ## 9.9.9
 
 - Changed: Preserve mounted RootPage children through selected native body layouts only when their metadata constraints, immutable props and required context are proven. Retain exact body and import identity, and refresh the generated canon pins.

package/dist/swr-family.js

@@ -1,7 +1,9 @@
 /** R285: API operations are wrapped by the SWR family before product code calls them. */
 import { hfsOf } from "./lib/hfs.js";
 import { readFileSync, readdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { join } from "node:path";
+import ts from "typescript";
+import { isBoundsExport } from "#runtime/scripts/hfs/architecture/contract-bounds.mjs";
 import { stringOf, walk } from "./lib/ast.js";
 import { functionOf } from "./lib/bindings.js";
 import { defineRule } from "./lib/rule.js";
@@ -152,36 +154,6 @@ const isOperationSource = (context, value, only) => {
         return found.some((entry) => entry.slot === only);
     return found.some((entry) => OPERATION_SLOTS.includes(entry.slot));
 };
-/** The generated input-bounds module holds constants and a pure reader derived from the contract, never an operation. */
-const BOUNDS_MODULE = /(?:^|\/)__generated__\/input-bounds\.ts$/;
-const RE_EXPORT = /export\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g;
-const ENTRY = /^\s*(type\s+)?([\w$]+)(?:\s+as\s+([\w$]+))?\s*$/;
-/** True when the named export of `target` is, through a chain of relative named re-exports, defined by a generated input-bounds module. */
-const isBoundsExport = (target, name, depth = 0) => {
-    if (depth > 4)
-        return false;
-    for (const file of [`${target}.ts`, `${target}/index.ts`, target]) {
-        if (BOUNDS_MODULE.test(file.replaceAll("\\", "/")))
-            return true;
-        let text;
-        try {
-            text = readFileSync(file, "utf8");
-        }
-        catch {
-            continue;
-        }
-        for (const [, list, source] of text.matchAll(RE_EXPORT)) {
-            if (list === undefined || source === undefined || !source.startsWith("."))
-                continue;
-            for (const entry of list.split(",")) {
-                const [, kind, origin, exported] = ENTRY.exec(entry) ?? [];
-                if (origin !== undefined && kind === undefined && (exported ?? origin) === name && isBoundsExport(resolve(dirname(file), source), origin, depth + 1))
-                    return true;
-            }
-        }
-    }
-    return false;
-};
 /** The specifiers of an import or a re-export; the other inspected nodes have none. */
 const specifiersOf = (node) => node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" ? node.specifiers : undefined;
 /** An import of named values that all come from a generated input-bounds module is data, not an operation. */
@@ -192,9 +164,16 @@ const importsOnlyBounds = (context, node, value) => {
     const target = resolveImport(context, value);
     if (target === null)
         return false;
+    const hfs = hfsOf(context);
+    const owner = hfs.ownerOf(target);
+    const ownsGenerated = (file) => {
+        const found = hfs.classify(file);
+        return owner !== null && hfs.ownerOf(file) === owner && found.status === "owned" &&
+            (found.slot === "fe.transport.generated" || found.slot === "fe.package.api");
+    };
     return specifiers.every((s) => {
         const name = s.type === "ImportSpecifier" ? exportName(s.imported) : s.type === "ExportSpecifier" ? exportName(s.local) : undefined;
-        return name !== undefined && isBoundsExport(target, name);
+        return name !== undefined && isBoundsExport(ts, target, name, ownsGenerated);
     });
 };
 const unwrap = (start) => {

package/package.json

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

package/runtime/bundle.json

@@ -43,8 +43,8 @@
     "scripts/hfs/architecture/canon-jsx-clones.mjs",
     "scripts/hfs/architecture/client-reaches-server.mjs",
     "scripts/hfs/architecture/clones.mjs",
-    "scripts/hfs/architecture/config-unread.mjs",
     "scripts/hfs/architecture/component-tiers.mjs",
+    "scripts/hfs/architecture/config-unread.mjs",
     "scripts/hfs/architecture/config.mjs",
     "scripts/hfs/architecture/connection-map.mjs",
     "scripts/hfs/architecture/constructor-deps.mjs",
@@ -53,6 +53,7 @@
     "scripts/hfs/architecture/context-owner.mjs",
     "scripts/hfs/architecture/context-platform-tables.mjs",
     "scripts/hfs/architecture/context-transaction.mjs",
+    "scripts/hfs/architecture/contract-bounds.mjs",
     "scripts/hfs/architecture/contract-fixture-guard.mjs",
     "scripts/hfs/architecture/contracts-readonly.mjs",
     "scripts/hfs/architecture/contracts.mjs",

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

@@ -31,35 +31,35 @@ 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.21.9
+    version: 0.21.10
     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.11.16
+    version: 3.11.17
     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.9.9
+    version: 9.9.10
     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.21.9
+    version: 0.21.10
     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.21.9
+    version: 0.21.10
     group: starci
     install: registry
     side: fe
@@ -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: 5.0.5
+    version: 5.0.6
     group: starci
     install: registry
     side: both

package/runtime/scripts/hfs/architecture/contract-bounds.mjs

@@ -0,0 +1,72 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/** The generated input-bounds owner is contract data, not an operation. */
+const BOUNDS_MODULE = /(?:^|\/)__generated__\/input-bounds\.ts$/;
+/** Directly exported declarations with the requested name; multiple declarations are ambiguous. */
+function declaredExports(ts, source, name) {
+    let count = 0;
+    for (const statement of source.statements) {
+        if (!ts.canHaveModifiers(statement) || !ts.getModifiers(statement)?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        if (ts.isVariableStatement(statement)) {
+            count += statement.declarationList.declarations.filter(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === name).length;
+        }
+        else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement) ||
+            ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) && statement.name?.text === name)
+            count += 1;
+    }
+    return count;
+}
+/** The concrete file a relative module specifier resolves to, in the same order as the rule's owner resolver. */
+function readSource(ts, target) {
+    for (const file of [`${target}.ts`, `${target}/index.ts`, target]) {
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+        if (source.parseDiagnostics.length)
+            return null;
+        return { file, source };
+    }
+    return null;
+}
+/** True only for an unambiguous named export proven through actual declarations to a generated contract declaration. */
+export function isBoundsExport(ts, target, name, ownsGenerated, seen = new Set()) {
+    const found = readSource(ts, target);
+    if (!found)
+        return false;
+    const { file, source } = found;
+    const key = `${file}#${name}`;
+    if (seen.has(key) || seen.size >= 32)
+        return false;
+    const direct = declaredExports(ts, source, name);
+    const matches = [];
+    let wildcard = false;
+    for (const statement of source.statements) {
+        if (!ts.isExportDeclaration(statement))
+            continue;
+        const module = statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
+        if (!statement.exportClause) {
+            wildcard = true;
+            continue;
+        }
+        if (!ts.isNamedExports(statement.exportClause))
+            continue;
+        for (const item of statement.exportClause.elements)
+            if (item.name.text === name) {
+                matches.push({ origin: (item.propertyName ?? item.name).text, module });
+            }
+    }
+    if (wildcard || direct + matches.length !== 1)
+        return false;
+    if (BOUNDS_MODULE.test(file.replaceAll('\\', '/')))
+        return ownsGenerated(file) && direct === 1 && matches.length === 0;
+    const match = matches[0];
+    if (direct || !match || !match.module?.startsWith('.'))
+        return false;
+    return isBoundsExport(ts, resolve(dirname(file), match.module), match.origin, ownsGenerated, new Set([...seen, key]));
+}

package/runtime/scripts/hfs/architecture/index.mjs

@@ -243,7 +243,7 @@ function runHfsMachine(config, context, paths, injectedTypeScript, base, fast, v
         return hfsChecks;
     const graph = buildHfsGraph(config, hfsContext);
     const input = { config, context: hfsContext, graph, base };
-    const runs = { tiers: () => checkTiers(graph), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
+    const runs = { tiers: () => checkTiers(graph, hfsContext.ts), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
         requiredFiles: () => checkRequiredFiles(input), clones: () => checkClones(input), symbols: () => checkSymbols(input), docLanguage: () => checkDocLanguage(input) };
     if (graph.profile === 'be')
         for (const [name, [check]] of Object.entries(BACKEND_MACHINE))

package/runtime/scripts/hfs/architecture/tiers.mjs

@@ -1,4 +1,6 @@
 import { byCodeUnit } from '../../lib/list.mjs';
+import { dirname, relative } from 'node:path';
+import { isBoundsExport } from './contract-bounds.mjs';
 import { registryListImport, registrySlot } from './entity-registry.mjs';
 /**
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
@@ -139,14 +141,53 @@ function reportReasonedTierViolation(graph, edge, answer, tierRule, counts, viol
         message,
     });
 }
-function inspectTierEdge(graph, edge, tierRule, counts, violations, coverage) {
+/** A public API entry may expose generated contract data without exposing operations to a hook. */
+function contractMetadataEdge(graph, ts, edge, verdict) {
+    if (graph.profile !== 'fe' || verdict.reason !== 'tierDirection')
+        return false;
+    const from = graph.files.get(edge.from);
+    const to = graph.files.get(edge.to);
+    if (from?.tier !== 'hooks' || to?.tier !== 'transport' || to.slot !== 'fe.modules.api' || !to.owner || to.owner.slot !== 'fe.modules' || to.owner.bindings.capability !== 'api')
+        return false;
+    // The tier verdict precedes private-entry checks, so prove both app isolation and the owner entry here.
+    const fromApp = graph.resolver.classifyPath(edge.from).bindings?.app;
+    const toApp = graph.resolver.classifyPath(edge.to).bindings?.app;
+    if (!fromApp || fromApp !== toApp || edge.to !== `${to.owner.root}/index.ts`)
+        return false;
+    const declaration = edge.edge.declaration;
+    let names;
+    if (ts.isImportDeclaration(declaration)) {
+        const clause = declaration.importClause;
+        if (!clause || clause.name || !clause.namedBindings || !ts.isNamedImports(clause.namedBindings))
+            return false;
+        names = clause.namedBindings.elements.map(item => (item.propertyName ?? item.name).text);
+    }
+    else if (ts.isExportDeclaration(declaration)) {
+        if (!declaration.exportClause || !ts.isNamedExports(declaration.exportClause))
+            return false;
+        names = declaration.exportClause.elements.map(item => (item.propertyName ?? item.name).text);
+    }
+    else
+        return false;
+    const apiOwner = to.owner;
+    const dirnameOfEntry = dirname(to.abs);
+    const ownsGenerated = (file) => {
+        const rel = `${apiOwner.root}/${relative(dirnameOfEntry, file).replaceAll('\\', '/')}`;
+        const classified = graph.resolver.classifyPath(rel);
+        const owner = graph.resolver.ownerOf(rel);
+        return classified.status === 'owned' && classified.slot === 'fe.transport.generated' &&
+            owner?.slot === apiOwner.slot && owner.root === apiOwner.root;
+    };
+    return names.length > 0 && names.every(name => isBoundsExport(ts, to.abs, name, ownsGenerated));
+}
+function inspectTierEdge(graph, ts, edge, tierRule, counts, violations, coverage) {
     const verdict = graph.resolver.importAllowed(edge.from, edge.to);
     if (verdict.reason === 'unowned' || verdict.reason?.startsWith('slot')) {
         coverage.unclassifiedEdges += 1;
         return;
     }
     coverage.edgesChecked += 1;
-    if (verdict.reason === 'tierDirection' && registryListImport(graph.resolver, edge))
+    if (verdict.reason === 'tierDirection' && (registryListImport(graph.resolver, edge) || contractMetadataEdge(graph, ts, edge, verdict)))
         return;
     reportReasonedTierViolation(graph, edge, verdict, tierRule, counts, violations);
 }
@@ -197,14 +238,14 @@ function addOwnerCycleViolations(adjacency, witness, violations) {
     }
     return components.length;
 }
-export function checkTiers(graph) {
+export function checkTiers(graph, ts) {
     const { resolver, profile } = graph;
     const violations = [];
     const tierRule = profile === 'be' ? 'BE_TIER_DIRECTION' : 'FE_TIER_DIRECTION';
     const coverage = { edgesChecked: 0, unclassifiedEdges: 0 };
     const counts = { tierDirection: 0, layerOrder: 0, crossApp: 0 };
     for (const edge of graph.edges)
-        inspectTierEdge(graph, edge, tierRule, counts, violations, coverage);
+        inspectTierEdge(graph, ts, edge, tierRule, counts, violations, coverage);
     // Owner cycles: nodes are owner units, edges the imports between two distinct units.
     const { adjacency, witness } = ownerAdjacency(graph, resolver);
     const cycles = addOwnerCycleViolations(adjacency, witness, violations);

package/runtime/scripts/hfs/repo-identity.mjs

@@ -5,10 +5,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { revParseQuery } from '../api/git/rev-parse-query.mjs';
 import { remote as gitRemote } from '../api/git/remote.mjs';
-import { gitOutputOf } from '../lib/git.mjs';
+import { gitOutputOf, withoutGitLocalEnv } from '../lib/git.mjs';
 import { trimTrailingSlashes } from './trailing-slashes.mjs';
 /** One git call (a scripts/api/git call file) in `root`: its trimmed stdout; throws unless git exits 0. */
-const git = (call, root, args) => gitOutputOf(call(args, { cwd: root })).trim(); // gitOutputOf threw unless git exited 0, whose stdout is text
+const git = (call, root, args, env) => gitOutputOf(call(args, { cwd: root, env: identityQueryEnvironment(env) })).trim(); // gitOutputOf threw unless git exited 0, whose stdout is text
+/** Identity queries need repository configuration, never age identities or selected service connection credentials. */
+export function identityQueryEnvironment(parent, privateNames = []) {
+    const selected = new Set(privateNames.map((name) => name.toUpperCase()));
+    return Object.fromEntries(Object.entries(withoutGitLocalEnv(parent)).filter(([name]) => !selected.has(name.toUpperCase()) && !/^(?:SOPS_AGE_KEY(?:_FILE)?|SONAR_.*)$/iu.test(name)));
+}
 const real = (p) => { try {
     return fs.realpathSync(p);
 }
@@ -26,20 +31,20 @@ catch {
     return null;
 } };
 /** { repositoryRoot, inWorkTree, home } for `root`: home is the main checkout folder when root is a repository top level. */
-function identityOf(root) {
+function identityOf(root, env = process.env) {
     const state = stateOf(root);
     if (state === null)
-        return askGit(root);
+        return askGit(root, env);
     if (!known.has(state))
-        known.set(state, askGit(root));
+        known.set(state, askGit(root, env));
     return known.get(state);
 }
-function askGit(root) {
+function askGit(root, env) {
     let inWorkTree = false, repositoryRoot = false, home = null;
     try {
         // Identity comes from Git only when root IS a repository (or worktree) top level, never a folder inside one.
         // One git call answers both questions: the top level on the first line, the common git dir on the second.
-        const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir']).split(String.fromCodePoint(10)).map((line) => line.trim());
+        const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir'], env).split(String.fromCodePoint(10)).map((line) => line.trim());
         repositoryRoot = real(top) === real(root);
         inWorkTree = true;
         const common = path.resolve(root, commonDir);
@@ -55,11 +60,11 @@ function askGit(root) {
  * name outside Git, else the folder name. A folder inside a larger repository (a nested product, an example) is named by
  * its own folder.
  */
-export function repositoryName(root) {
-    const { inWorkTree, repositoryRoot, home } = identityOf(root);
+export function repositoryName(root, { env = process.env } = {}) {
+    const { inWorkTree, repositoryRoot, home } = identityOf(root, env);
     if (repositoryRoot) {
         try {
-            const remote = trimTrailingSlashes(git(gitRemote, root, ['get-url', 'origin'])).replace(GIT_SUFFIX, '');
+            const remote = trimTrailingSlashes(git(gitRemote, root, ['get-url', 'origin'], env)).replace(GIT_SUFFIX, '');
             const name = remote.split(/[/:]/u).pop();
             if (name)
                 return name;