@starci/hfs 4.17.0 → 4.17.2

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 4.17.2 - 2026-11-02
+
+- Changed: bundled pins follow Grammar 0.21.2 with disabled tab items and its coherent canon cohort; existing runtime checks are unchanged.
+
+## 4.17.1 - 2026-11-02
+
+- Fixed: unit provider contracts recognize the real Nest `Optional()` injection decorator through direct, aliased and namespace imports; TypeScript optional parameters and unrelated decorator names still require their providers.
+- Fixed: cross-file `label-in-grid` judges the nearest peer-card layout (`Grid kind="cards"`), matching the existing one-file rule. Dated week regions keep their day headings; labelled peer tiles still fail, with generic regression coverage for both semantic week layouts and nested layout ownership. Bundled R356 knowledge names the same owner.
+
 ## 4.17.0 - 2026-11-02
 
 - Fixed: the architecture machine run on an app root that has its own tsconfig threw "Cannot destructure property 'lines'" out of `checkClones`: the app resolver has no rule parameters, so the clone threshold (`ruleParams.common.duplicateBlock`, shared by every profile) is read from a side. Spec `architecture-clones-app-root`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.17.0",
+  "version": "4.17.2",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "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.21.0
+    version: 0.21.2
     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.7
+    version: 3.11.9
     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.0
+    version: 9.9.2
     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.0
+    version: 0.21.2
     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.0
+    version: 0.21.2
     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: 4.17.0
+    version: 4.17.2
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -6323,7 +6323,7 @@ rules:
       - {path: packages/eslint-grammar-core/src/surface-card.spec.ts, editions: [lite, full], codes: [FE_SURFACE_CARD_KIND]}
   - id: R356
     code: "FE_SURFACE_NESTING"
-    law: "Across files, a card is not drawn inside a card, a Pane surface or an overlay, a DataTable is not drawn inside a card, a PaneGrid stands only in Page chrome=\"panes\" or a Pane, a Section or Heading holds more than one card, and a labelled card is not repeated in a Grid: the render graph replaces every component by what it draws and every children by what its caller handed it."
+    law: "Across files, a card is not drawn inside a card, a Pane surface or an overlay, a DataTable is not drawn inside a card, a PaneGrid stands only in Page chrome=\"panes\" or a Pane, a Section or Heading holds more than one card, and a labelled card is not repeated in the peer-card layout Grid kind=\"cards\": the render graph replaces every component by what it draws and every children by what its caller handed it."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_SURFACE_NESTING"]

package/runtime/scripts/hfs/architecture/surface-nesting.d.mts

@@ -13,7 +13,7 @@ import type { CheckInput } from './hfs-graph.mjs';
  *   table-in-card        a `DataTable` inside a card (a table stands on the page);
  *   grid-outside-panes   a `PaneGrid` inside a card or a Page whose chrome is not `panes`;
  *   heading-over-card    a `Heading`, or a region `Section`, whose only neighbour or child is one card (a card carries its own label);
- *   label-in-grid        a labelled card repeated by a `.map` in a `Grid` (a repeated tile has no label).
+ *   label-in-grid        a labelled card repeated by a `.map` in a `Grid kind="cards"` (a repeated tile has no label).
  *
  * A finding carries `crossFile: true` when the two elements are drawn in different files, which is what one-file lint cannot see.
  */

package/runtime/scripts/hfs/architecture/surface-nesting.mjs

@@ -11,7 +11,7 @@ import { RenderGraph } from './render-graph.mjs';
  *   table-in-card        a `DataTable` inside a card (a table stands on the page);
  *   grid-outside-panes   a `PaneGrid` inside a card or a Page whose chrome is not `panes`;
  *   heading-over-card    a `Heading`, or a region `Section`, whose only neighbour or child is one card (a card carries its own label);
- *   label-in-grid        a labelled card repeated by a `.map` in a `Grid` (a repeated tile has no label).
+ *   label-in-grid        a labelled card repeated by a `.map` in a `Grid kind="cards"` (a repeated tile has no label).
  *
  * A finding carries `crossFile: true` when the two elements are drawn in different files, which is what one-file lint cannot see.
  */
@@ -93,9 +93,9 @@ export function checkSurfaceNesting(input) {
             }
             if (element.repeated) {
                 const inGrid = [...ancestors].reverse().find(entry => isGrammarIn(entry.element, SURFACE_VOCABULARY.grids));
-                const card = inGrid ? cardOf(graph, element) : null;
+                const card = inGrid?.element.attributes.get('kind')?.text === 'cards' ? cardOf(graph, element) : null;
                 if (inGrid && card && card.attributes.has('label')) {
-                    report(element, inGrid.element, 'label-in-grid', `${describe(element)} repeats a labelled card in a Grid: a repeated tile has no label`, ancestors, stack);
+                    report(element, inGrid.element, 'label-in-grid', `${describe(element)} repeats a labelled card in a Grid kind="cards": a repeated tile has no label`, ancestors, stack);
                 }
             }
         },

package/runtime/scripts/hfs/architecture/unit-spec-providers.d.mts

@@ -4,7 +4,8 @@ import type { MachineContext } from './machine-ast.mjs';
 /**
  * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
  * subject with `Test.createTestingModule({ providers: [...] })`, and that providers array EQUALS the constructor
- * dependencies of the service under test: the service class first, then one provider for each constructor parameter.
+ * dependencies of the service under test: the service class first, then one provider for each required constructor parameter.
+ * A parameter decorated by `Optional()` imported from `@nestjs/common` may be omitted to exercise its absent-provider branch.
  *
  * The service under test is the sibling `<name>.service.ts` of every `<name>.service.spec.ts` under src/ or apps/ (a spec is
  * outside the production program, so it is read from disk). A parameter decorated with a custom `Inject<Thing>()` provides

package/runtime/scripts/hfs/architecture/unit-spec-providers.mjs

@@ -9,7 +9,8 @@ import { checkFunctionSubject, functionSubjectExports, keyOf as literalKey, valu
 /**
  * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
  * subject with `Test.createTestingModule({ providers: [...] })`, and that providers array EQUALS the constructor
- * dependencies of the service under test: the service class first, then one provider for each constructor parameter.
+ * dependencies of the service under test: the service class first, then one provider for each required constructor parameter.
+ * A parameter decorated by `Optional()` imported from `@nestjs/common` may be omitted to exercise its absent-provider branch.
  *
  * The service under test is the sibling `<name>.service.ts` of every `<name>.service.spec.ts` under src/ or apps/ (a spec is
  * outside the production program, so it is read from disk). A parameter decorated with a custom `Inject<Thing>()` provides
@@ -80,6 +81,7 @@ function serviceClassFor(ts, rel, serviceRel, serviceFile, imports, list, report
 }
 function checkDependencies(kit, rel, service, serviceFile, list, provided, report) {
     const { serviceName, serviceClass } = service;
+    const checker = kit.checkerOf(serviceFile.sourceFile);
     const dependencies = constructorDependencies(kit, serviceFile, serviceClass);
     const expected = [];
     for (const dependency of dependencies) {
@@ -87,18 +89,23 @@ function checkDependencies(kit, rel, service, serviceFile, list, provided, repor
             report(list, `${rel}: a constructor dependency of ${serviceName.name} cannot be resolved to a token (${dependency.reason}), so its provider cannot be checked; inject it through an exported Inject<Thing>() decorator or a class type.`);
             continue;
         }
-        expected.push(dependency.name);
+        const optional = kit.decorators(dependency.parameter).some(decorator => {
+            const expression = decorator.expression;
+            return kit.ts.isCallExpression(expression) && expression.arguments.length === 0
+                && kit.isImportOf(checker, expression.expression, 'Optional', '@nestjs/common');
+        });
+        expected.push({ name: dependency.name, optional });
     }
     const remaining = [...expected];
     for (const item of provided.slice(1)) {
-        const index = remaining.indexOf(item.name);
+        const index = remaining.findIndex(dependency => dependency.name === item.name);
         if (index === -1)
             report(item.node, `${rel}: ${item.name} is provided but is not a constructor dependency of ${serviceName.name}; a unit spec provides exactly what the constructor needs.`);
         else
             remaining.splice(index, 1);
     }
-    for (const name of remaining)
-        report(list, `${rel}: ${name} is a constructor dependency of ${serviceName.name} but is not provided; add \`{ provide: ${name}, useValue: double }\` (or the class itself) to the providers.`);
+    for (const dependency of remaining.filter(item => !item.optional))
+        report(list, `${rel}: ${dependency.name} is a constructor dependency of ${serviceName.name} but is not provided; add \`{ provide: ${dependency.name}, useValue: double }\` (or the class itself) to the providers.`);
 }
 function checkTestingModule({ ts, kit, rel, serviceRel, serviceFile, imports, call, report }) {
     const list = providerList(ts, call, rel, report);