@starci/eslint-canon-fe 9.5.20 → 9.5.21

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 9.5.21 - 2026-10-30
+
+- Changed: the bundled slot manifest carries the `logic` field (passport declares its tokens, password and cookie files) and the object-storage slot's `object-storage.*` names; the bundled `allows.mjs` and manifest shape admit them; the bundled architecture machine takes a typed-configuration JWT audience; the bundled canon pins name hfs 4.11.20, jest-preset 2.5.2, eslint-canon-be 3.8.19, eslint-canon-fe 9.5.21 and the Grammar family 0.15.32. No rule of this package changed.
+
 ## 9.5.20 - 2026-10-30
 
 - Changed: the bundled canon pins name hfs 4.11.19 (the schedule scanner reads interpolated identifiers and const-named SQL), eslint-canon-be 3.8.18, eslint-canon-fe 9.5.20 and the Grammar family 0.15.31. No rule changed.

package/package.json

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

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.15.31
+    version: 0.15.32
     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.8.18
+    version: 3.8.19
     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.5.20
+    version: 9.5.21
     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.15.31
+    version: 0.15.32
     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.15.31
+    version: 0.15.32
     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.1
+    version: 2.5.2
     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.11.19
+    version: 4.11.20
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/slots.yaml

@@ -88,10 +88,14 @@ versioning:
 #   allows / forbids   names inside the instance; the loader exposes them, slot-check enforces them.
 #   tests       unit-beside | e2e | none.
 #   coverage    required | none, on every tracked slot of profile be. A required slot's subtree is measured at 100 per file on every
-#               ruleParams.be.logicRoles file (lines, branches, functions, statements); a none slot's subtree is never measured and
-#               is excluded from Sonar's coverage. scripts/hfs/coverage-scope.mjs derives the jest per-file thresholds, Sonar's
-#               sonar.coverage.exclusions and the Codecov paths and components from this field and nowhere else (R204).
-#               Orthogonal to the lite `editions`: an edition never changes what a slot measures.
+#               ruleParams.be.logicRoles file and on every file a slot of it declares in `logic` (lines, branches, functions,
+#               statements); a none slot's subtree is never measured and is excluded from Sonar's coverage. scripts/hfs/coverage-scope.mjs
+#               derives the jest per-file thresholds, Sonar's sonar.coverage.exclusions and the Codecov paths and components from this
+#               field and `logic` and nowhere else (R204). Orthogonal to the lite `editions`: an edition never changes what a slot measures.
+#   logic       on a coverage-required unit-beside directory slot: the files of the slot that carry logic without a logic-role suffix
+#               (`<name>.<part>.ts`, relative to the slot path, each one the slot requires or allows, none of a logic role). Each is
+#               measured at 100 per file like a logic-role file, and its `<name>.<part>.spec.ts` beside it is a legitimate unit spec
+#               (R47, R48): the slot admits it without listing it. No role name is added to ruleParams.be.logicRoles.
 #   composedBy the app kinds allowed to compose a transport slot (an app of another kind imports none of its modules); on an
 #               owner slot (be.cli) the app kinds that list its root module, every folder of the root holding one static module.
 #   budget      size budgets (lines per file, files per slot, exports).
@@ -1981,6 +1985,7 @@ slots:
     owner: true
     requires: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.tokens.ts, passport.password.ts, passport.cookie.ts]   # Secrets, no defaults (R44); options and named injectors (R83); tokens and JWKS; bcrypt; the refresh cookie
     allows: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.tokens.ts, passport.password.ts, passport.cookie.ts, strategies/, errors/]
+    logic: [passport.tokens.ts, passport.password.ts, passport.cookie.ts]   # JWT sign and verify over the own JWKS, bcrypt, the refresh cookie: measured at 100 per file
     tests: unit-beside
     rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_AUTH_PASSPORT_OWNER, BE_AUTH_JWT_OWN_JWKS, BE_AUTH_REFRESH_COOKIE]
     coverage: required
@@ -1997,8 +2002,8 @@ slots:
     tracked: tracked
     tier: integrations
     owner: true
-    requires: [index.ts, storage.config.ts, storage.options.ts, storage.decorators.ts, storage.client.ts]
-    allows: [index.ts, storage.config.ts, storage.options.ts, storage.decorators.ts, storage.client.ts, errors/]
+    requires: [index.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.client.ts]
+    allows: [index.ts, object-storage.module.ts, object-storage.module-definition.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.client.ts, errors/]
     tests: unit-beside
     rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_STORAGE_OWNER]
     coverage: required

package/runtime/scripts/hfs/allows.mjs

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { braceVariants, globExpression } from '../lib/glob.mjs';
+import { declaredLogicOf } from './manifest-shape.mjs';
 
 /**
  * What a slot's `requires`, `allows` and `forbids` entries (knowledge/hfs/slots.yaml) say about a file, read through the
@@ -8,9 +9,26 @@ import { braceVariants, globExpression } from '../lib/glob.mjs';
  *
  * An entry is a name relative to the slot instance root: `<var>` is the instance's bound variable when the slot binds it
  * (`<feature>`, `<capability>`) and one path segment of any text otherwise (`<action>`), `*` and `?` stay inside a segment,
- * `{a,b}` alternates, a trailing `/` names a directory and everything below it.
+ * `{a,b}` alternates, a trailing `/` names a directory and everything below it. A slot also admits, unlisted, the unit spec beside each
+ * measured file it names (isMeasuredSpec): a file it declares in `logic`, or a named file of a logic role.
  */
 const VAR = /<([A-Za-z][A-Za-z0-9-]*)>/g;
+const SPEC = /\.spec\.ts$/;
+
+/**
+ * Whether `relative` is the unit spec `<stem>.spec.ts` of a measured file beside it that the slot names: a file the slot declares in
+ * `logic`, or a `requires`/`allows` file of a logic role (ruleParams.be.logicRoles), in a slot whose coverage is required and whose tests
+ * are unit-beside. The slot admits that spec without listing it, as unit-test-colocated (R47) accepts it.
+ */
+function isMeasuredSpec(resolver, classified, slot, relative, named) {
+  if (!SPEC.test(relative) || slot.coverage !== 'required' || slot.tests !== 'unit-beside') return false;
+  const subject = relative.replace(SPEC, '.ts');
+  if (declaredLogicOf(slot).includes(subject)) return true;
+  const role = /\.([a-z0-9-]+)\.ts$/.exec(subject)?.[1];
+  // An app resolver keeps no rule parameters of its own: a path on a side reads that side's.
+  const params = classified.side ? resolver.sides?.[classified.side]?.ruleParams() : resolver.ruleParams?.();
+  return (params?.logicRoles ?? []).includes(role) && named.some(matcher => matcher.expression.test(subject));
+}
 
 function matchersOf(entries, bindings) {
   return (entries ?? []).flatMap(entry => {
@@ -36,7 +54,8 @@ export function slotAdmitsFile(resolver, file) {
   if (classified.status === 'no-slot' || classified.status === 'ambiguous' || !classified.slot) return null;
   const slot = resolver.slot(classified.slot);
   const relative = relativeToRoot(classified.path, classified.root);
-  const hit = matchersOf([...(slot.requires ?? []), ...(slot.allows ?? [])], classified.bindings).some(matcher => matcher.expression.test(relative));
+  const named = matchersOf([...(slot.requires ?? []), ...(slot.allows ?? [])], classified.bindings);
+  const hit = named.some(matcher => matcher.expression.test(relative)) || isMeasuredSpec(resolver, classified, slot, relative, named);
   const forbidden = matchersOf(slot.forbids, classified.bindings).some(matcher => matcher.expression.test(relative) || matcher.expression.test(`${relative}/`));
   return hit && !forbidden;
 }
@@ -51,7 +70,9 @@ export function allowsFile(resolver, file) {
   const slot = resolver.slot(classified.slot);
   if (!slot?.allows?.length) return null;
   const relative = relativeToRoot(classified.path, classified.root);
-  const hit = matchersOf([...(slot.requires ?? []), ...slot.allows], classified.bindings).find(matcher => matcher.expression.test(relative));
+  const named = matchersOf([...(slot.requires ?? []), ...slot.allows], classified.bindings);
+  const hit = named.find(matcher => matcher.expression.test(relative));
+  const spec = !hit && isMeasuredSpec(resolver, classified, slot, relative, named);
   const forbidden = matchersOf(slot.forbids, classified.bindings).find(matcher => matcher.expression.test(relative) || matcher.expression.test(`${relative}/`));
-  return { slot: slot.id, root: classified.root, relative, allowed: Boolean(hit) && !forbidden, entry: hit?.entry, forbiddenBy: forbidden?.entry, allows: slot.allows };
+  return { slot: slot.id, root: classified.root, relative, allowed: (Boolean(hit) || spec) && !forbidden, entry: hit?.entry, forbiddenBy: forbidden?.entry, allows: slot.allows };
 }

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

@@ -4,7 +4,7 @@
 // In both editions every jwtVerify call holds the JWT policy (R260, jwtPolicyProblems).
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
-import { importedFrom, jwtPolicyProblems, reportAt, unwrap } from './jwt-ast.mjs';
+import { fromConfig, importedFrom, jwtPolicyProblems, reportAt, unwrap } from './jwt-ast.mjs';
 import { accessName } from '../../lib/ts-ast.mjs';
 
 const PASSPORT_SLOT = 'be.integrations.passport';
@@ -87,7 +87,11 @@ function verifyJwtCall(kit, checker, file, node, counters, violations) {
   const issuer = property('issuer');
   const audience = values('audience');
   const algorithms = values('algorithms');
-  const good = jwksArgument(kit, checker, node.arguments[1]) && issuer != null && audience !== null && audience.length > 0
+  // The audience is pinned by a literal or, as R260 accepts, by typed configuration (the skeleton's TokenOptions.audience).
+  const audienceEntry = property('audience');
+  const pinnedAudience = (audience !== null && audience.length > 0)
+    || (audienceEntry != null && fromConfig(kit.ts, checker, kit.valueOfProperty(audienceEntry)));
+  const good = jwksArgument(kit, checker, node.arguments[1]) && issuer != null && pinnedAudience
     && algorithms !== null && algorithms.length > 0;
   if (!good) {
     reportAt(violations, kit, BE_JWT_VERIFIED, file, node, 'jwtVerify must check the app\'s own key set (createLocalJWKSet(...) over the keys integrations/passport signs with) and pin issuer, audience and a non-empty algorithms list; jwtVerify then enforces signature and exp.');

package/runtime/scripts/hfs/architecture/jwt-ast.mjs

@@ -62,7 +62,7 @@ const configType = (checker, node) => {
 };
 
 /** Trace an issuer or audience to typed configuration values through local URL/string transformations. */
-const fromConfig = (ts, checker, expression, seen = new Set()) => {
+export const fromConfig = (ts, checker, expression, seen = new Set()) => {
   const node = unwrap(ts, expression);
   if (!node || seen.has(node)) return false;
   const next = new Set(seen).add(node);

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -58,6 +58,40 @@ export const unitRolesOf = (manifest) => manifest.ruleParams.be.unitRoles;
 /** The roles that carry logic (ruleParams.be.logicRoles): measured at 100 per file inside a coverage-required slot. */
 export const logicRolesOf = (manifest) => manifest.ruleParams.be.logicRoles;
 
+/** A declared logic file: `<name>.<part>.ts` below the slot path, kebab-case parts, no placeholder, glob or spec. */
+const LOGIC_FILE = /^(?:[a-z0-9]+(?:-[a-z0-9]+)*\/)*[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)+\.ts$/;
+
+/** The role suffix of a file name (`passport.tokens.ts` gives `tokens`). */
+export const suffixOf = (file) => /\.([a-z0-9-]+)\.ts$/.exec(file)?.[1] ?? null;
+
+/**
+ * The files a slot declares as logic (`logic`, names relative to the slot path): a file that carries logic without a logic-role suffix.
+ * Each is measured at 100 per file like a logic-role file (scripts/hfs/coverage-scope.mjs), and its `<stem>.spec.ts` beside it is a
+ * legitimate unit spec its slot admits (scripts/hfs/allows.mjs, eslint-canon-be unit-test-colocated). No role name is added for it.
+ */
+export const declaredLogicOf = (slot) => (Array.isArray(slot?.logic) ? slot.logic : []);
+
+/** The unit spec beside a declared logic file: `passport.tokens.ts` gives `passport.tokens.spec.ts`. */
+export const declaredLogicSpecOf = (file) => file.replace(/\.ts$/, '.spec.ts');
+
+/**
+ * Shape problems of a slot's `logic`: a non-empty list of unique `<name>.<part>.ts` files, each one the slot requires or allows by that
+ * exact name, on a tracked directory slot of profile be that is coverage: required and unit-beside, and (given the logic roles) none
+ * already of a logic role, which its role measures.
+ */
+export function slotLogicProblems(slot, at, logicRoles = []) {
+  if (slot.logic === undefined) return [];
+  const list = slot.logic;
+  if (!strList(list) || !list.length || new Set(list).size !== list.length || !list.every((file) => LOGIC_FILE.test(file) && !file.endsWith('.spec.ts'))) return [`${at}: logic must be a non-empty list of unique <name>.<part>.ts files relative to the slot path`];
+  const bad = [];
+  const home = typeof slot.path === 'string' && slot.path.endsWith('/') && slot.tracked === 'tracked' && Array.isArray(slot.profiles) && slot.profiles.includes('be') && slot.coverage === 'required' && slot.tests === 'unit-beside';
+  if (!home) bad.push(`${at}: logic belongs to a tracked directory slot of profile be whose coverage is required and whose tests are unit-beside`);
+  const named = [...(slot.requires ?? []), ...(slot.allows ?? [])];
+  for (const file of list.filter((entry) => !named.includes(entry))) bad.push(`${at}: logic file ${file} must be one the slot requires or allows by that name`);
+  for (const file of list.filter((entry) => logicRoles.includes(suffixOf(entry)))) bad.push(`${at}: logic file ${file} is of the logic role ${suffixOf(file)}, which measures it already`);
+  return bad;
+}
+
 
 /** Shape problems of ruleParams.be.unitRoles: unique roles of the suffix vocabulary, each spec `<role>.spec`. */
 export function unitRolesProblems(be) {
@@ -87,7 +121,7 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
 export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
 const strList = (v) => stringList(v);
 
-const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy'];
+const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'logic'];
 /** The roles a file slot may play that a rule reads (`role`): the entity registry of persistence.md BE-PERSISTENCE-3 (architecture/entity-registry.mjs). */
 const SLOT_ROLES = ['entity-registry'];
 /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
@@ -266,7 +300,7 @@ function slotPolicyProblems(slot, at) {
   return bad;
 }
 
-export function slotProblems(slot, index, kind, { appScope = 'app', scopes = [] } = {}) {
+export function slotProblems(slot, index, kind, { appScope = 'app', scopes = [], logicRoles = [] } = {}) {
   const runtime = kind === RUNTIME_KIND;
   const slotKeys = new Set(runtime ? RUNTIME_SLOT_KEYS : APP_SLOT_KEYS);
   const tracked = runtime ? RUNTIME_TRACKED : TRACKED;
@@ -276,6 +310,7 @@ export function slotProblems(slot, index, kind, { appScope = 'app', scopes = []
   bad.push(...slotLocationProblems(slot, at, runtime, tracked), ...slotPatternProblems(slot, at), ...slotListProblems(slot, at));
   if (!runtime) bad.push(...slotAppOptionProblems(slot, at), ...slotLiteOverlayProblems(slot, at));
   bad.push(...slotEntryProblems(slot, at), ...slotPolicyProblems(slot, at));
+  if (!runtime) bad.push(...slotLogicProblems(slot, at, logicRoles));
   return bad;
 }
 

package/runtime/scripts/hfs/slot-manifest-shape.mjs

@@ -53,7 +53,8 @@ function checkAppKindAndTierShapes(m, bad) {
 
 function checkSlotShapes(m, bad) {
   if (!Array.isArray(m.slots) || !m.slots.length) { bad.push('slots must be a non-empty list'); return false; }
-  m.slots.forEach((slot, index) => bad.push(...slotProblems(slot, index, APP_KIND, { appScope: APP_SCOPE, scopes: SCOPES })));
+  const logicRoles = Array.isArray(m.ruleParams?.be?.logicRoles) ? m.ruleParams.be.logicRoles : [];
+  m.slots.forEach((slot, index) => bad.push(...slotProblems(slot, index, APP_KIND, { appScope: APP_SCOPE, scopes: SCOPES, logicRoles })));
   return true;
 }