@starci/eslint-canon-be 3.0.5 → 3.0.6

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 3.0.6 - 2026-10-01
+
+- Changed: the runtime api layer (lib/git.mjs became api/git/lib.mjs), R112 and the dead-exports pairing, test-world 1.0.5 and the integration test shape.
+
 ## 3.0.5 - 2026-10-01
 
 - Changed: bundled slots.yaml (workflow worktree), sonar-gate.yaml (service coverage) and canon-pins.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-be",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
   "license": "UNLICENSED",

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

@@ -31,14 +31,14 @@ pins:
     source: packages/grammar/package.json
     why: nivo-fe pins 0.4.11 and 0.5.0 in one workspace, starci-next-fe 0.5.1, miamia-fe 0.5.0; the runtime source is 0.8.0 (the brand layer sets `--font-sans` and `--font-mono`; the grammar reads them; 0.7.2 added the Input tel kind and IconButton disclosure props).
   '@starci/eslint-canon-be':
-    version: 3.0.5
+    version: 3.0.6
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: '3.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2 and hfs 4.0.3; no rule changed. 3.0.2: its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root (app.starcistacks, app.sops) and pin hfs 4.0.2. 3.0.1: its bundled canon-pins copy pins hfs 4.0.1. 3.0.0: `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; the project graph is built per side. 2.0.0 (C0 release): starciBeConfig({ hfs: loadHfs(import.meta.url) }) typed factory and the BE-CONVENTION laws.'
   '@starci/eslint-canon-fe':
-    version: 8.0.5
+    version: 8.0.6
     group: starci
     install: registry
     side: fe
@@ -71,14 +71,14 @@ pins:
     source: packages/jest-preset/package.json
     why: '2.2.2: the unit run writes the lcov Sonar and Codecov import (services only); 2.2.0: the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; 2.1.0: four projects on the test world, the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
   '@starci/test-world':
-    version: 1.0.3
+    version: 1.0.5
     group: starci
     install: registry
     side: be
     source: packages/test-world/package.json
-    why: '1.0.3: the globalSetup registers the path aliases as TypeScript resolves them (the extends chain, paths from the config that declares them, the effective baseUrl), so a tests tsconfig that only extends the side config loads the declaration. 1.0.2: every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json), where .starcistacks lives, never from the be side. The shared e2e library of every back end (R47, R48): the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs, the outage lock and the starci-test-stack bin behind the managed test:stack script; a devDependency of every back end. 1.0.1: world.keycloak.events/sessions (the user events of the realm and live sessions through the admin API) and world.infra.postgresql.connection(name) (the database of one connection down while the others serve, under the outage lock).'
+    why: '1.0.5: a modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, and w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client. 1.0.4: world.resolve and scope.resolve take any Nest token (class, string or symbol). 1.0.3: the globalSetup registers the path aliases as TypeScript resolves them (the extends chain, paths from the config that declares them, the effective baseUrl), so a tests tsconfig that only extends the side config loads the declaration. 1.0.2: every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json), where .starcistacks lives, never from the be side. The shared e2e library of every back end (R47, R48): the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs, the outage lock and the starci-test-stack bin behind the managed test:stack script; a devDependency of every back end. 1.0.1: world.keycloak.events/sessions (the user events of the realm and live sessions through the admin API) and world.infra.postgresql.connection(name) (the database of one connection down while the others serve, under the outage lock).'
   '@starci/hfs':
-    version: 4.0.5
+    version: 4.0.6
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/slots.yaml

@@ -818,9 +818,9 @@ slots:
     tier: integrations
     owner: true
     requires: [index.ts, "<provider>.config.ts"]
-    tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts, nothing else
+    tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts; plus src/tests/integration/<provider>/ (R112)
     budget: {indexExports: 60}
-    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT]
+    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING]
   - id: be.integrations.model
     profiles: [be]
     path: "src/modules/integrations/<provider>/model/"
@@ -897,8 +897,8 @@ slots:
     tracked: tracked
     tier: e2e
     tests: e2e
-    why: one capability module on the real database, no HTTP (SQL, transactions, concurrency, inbox claims) through useTestWorld({ modules }); run by test:integration
-    rules: [BE_TEST_TOPOLOGY]
+    why: one capability module through useTestWorld({ modules }), no HTTP door of ours (SQL, transactions, concurrency, inbox claims on the real database; and every integration client, `<capability>` being its provider folder, against our real infra, a real peer app or the library fake at the network edge, with its success, its ErrorCode refusal mapping and an outage through the world, R112); run by test:integration
+    rules: [BE_TEST_TOPOLOGY, BE_INTEGRATION_SPEC_MISSING]
   - id: be.tests.e2e
     profiles: [be]
     path: "src/tests/e2e/<area>/*.e2e-spec.ts"

package/runtime/scripts/{lib/git.mjs → api/git/lib.mjs}

@@ -1,11 +1,11 @@
-// git.mjs — the one spawn the runtime's guard/kernel scripts run git through.
+// scripts/api/git/lib.mjs — the one place the runtime spawns git (scripts/checks/check-layers.mjs enforces it).
 //
-// Every copy spelt the same options by hand - encoding:'utf8', windowsHide:true, sometimes a
-// timeout - with two shapes: `git args` in a cwd (shim's pathspec scans, footprint-scan,
-// safe-remove's prune) and `git -C dir args` (settle-landed, install, terminal-dedupe's worktree
-// list). gitOutput is the throwing shape (stdout text, or an Error on a non-zero exit). gitSpawn keeps the spawnSync(file, args, options) signature so an injected runner or a
-// spec's fake takes the same three arguments; runGit is the `-C` convenience; gitResult folds the
-// result into settle-landed's {ok, stdout, error} envelope.
+// Every caller spelt the same options by hand - encoding:'utf8', windowsHide:true, sometimes a timeout - with two shapes:
+// `git args` in a cwd and `git -C dir args`. gitOutput is the throwing shape (stdout text, or an Error on a non-zero exit).
+// gitSpawn keeps the spawnSync(file, args, options) signature so an injected runner or a spec's fake takes the same three
+// arguments; runGit is the `-C` convenience; gitResult folds the result into the {ok, stdout, error} envelope; gitRunner
+// folds any caller's runner into {ok, stdout, stderr}. The call files beside this one (worktree-*.mjs, rev-parse.mjs, ...)
+// each name one git verb.
 import { spawnSync } from 'node:child_process';
 
 /**
@@ -43,11 +43,10 @@ export function gitResult(args, options = {}) {
 }
 
 /**
- * git's C-quoted diff path decoded - `"b\303\251"` a `+++ ` header line prints when core.quotePath
- * covers the name. Octal escapes become \u00XX for JSON.parse (which answers \n, \t, \" and \\);
- * a value not wrapped in quotes passes through unchanged.
+ * A caller's git runner folded to (args, opts) -> {ok, stdout, stderr}. `git`: the caller's runner (args, {cwd}) ->
+ * {ok|status, stdout|out, stderr|err} (a spec's fake); null: runGit with a 5-minute timeout and a 64 MB buffer.
  */
-export const unquoteDiffPath = (value) =>
-  /^".*"$/.test(value)
-    ? JSON.parse(value.replace(/\\([0-7]{3})/g, (_, octal) => `\\u00${Number.parseInt(octal, 8).toString(16).padStart(2, '0')}`))
-    : value;
+export const gitRunner = (git = null) => (args, opts = {}) => {
+  const r = git ? git(args, opts) : runGit(args, { timeout: 300_000, maxBuffer: 64 * 1024 * 1024, ...opts });
+  return { ok: r?.ok ?? (!r?.error && r?.status === 0), stdout: String(r?.stdout ?? r?.out ?? '').trim(), stderr: String(r?.stderr ?? r?.err ?? r?.error?.message ?? r?.error ?? '').trim() };
+};

package/runtime/scripts/checks/architecture/dead-exports.mjs

@@ -18,8 +18,12 @@
  * used by the importers of that file; a re-exporting file nobody imports is a framework entry (a route file) and uses it.
  * Specs and tests are not in the graph, so an export used only by a spec is dead, on purpose, with one exception (unit test
  * standard): a `<name>.service.spec.ts` (the only unit spec kind) and a `*.builder.ts` under src/tests/fixtures/builders read from
- * disk count as consumers, because a spec can only provide an Inject*() token or a param type the entry exports. Specs of any
- * other kind, e2e specs and world files still do not count. A consumer inside the owner is skipped like any inside consumer.
+ * disk count as consumers, because a spec can only provide an Inject*() token or a param type the entry exports. An integration
+ * spec (slot be.tests.integration, `src/tests/integration/<capability>/*.integration-spec.ts`) counts as a consumer of exactly one
+ * owner: the integration (slot be.integrations, `src/modules/integrations/<provider>/`) whose provider folder is its capability
+ * folder, because R112 makes that spec register the integration module and reference its ErrorCode enum. Specs of any other kind,
+ * an integration spec importing another owner, e2e specs and world files still do not count. A consumer inside the owner is
+ * skipped like any inside consumer.
  */
 import fs from 'node:fs';
 import { canonical } from './config.mjs';
@@ -168,13 +172,35 @@ function deadFiles(graph, config) {
 }
 
 const TEST_CONSUMER = /^(?:(?:src|apps)\/.+\.service\.spec\.ts|src\/tests\/fixtures\/builders\/.+\.builder\.ts)$/u;
+/** The slot of integration specs and the slot of the integrations they pair with by folder (knowledge/hfs/slots.yaml). */
+const INTEGRATION_SPEC_SLOT = 'be.tests.integration';
+const INTEGRATION_SLOT = 'be.integrations';
 
-/** Pseudo edges from the unit specs of services and the fixture builders (read from disk, outside the production program) to graph files. */
+/** The provider an integration spec pairs with (its `<capability>` folder), or null when `rel` is no integration spec. */
+function integrationSpecProvider(graph, rel) {
+  const classified = graph.resolver.classifyPath(rel);
+  return classified.slot === INTEGRATION_SPEC_SLOT && classified.status !== 'forbidden' ? classified.bindings?.capability ?? null : null;
+}
+
+/** Whether `to` belongs to the integration of `provider` (slot be.integrations, its `<provider>` binding). */
+function inIntegrationOf(graph, to, provider) {
+  const owner = graph.resolver.ownerOf(to);
+  return owner?.slot === INTEGRATION_SLOT && owner.bindings?.provider === provider;
+}
+
+/**
+ * Pseudo edges (read from disk, outside the production program) to graph files: from the unit specs of services and the fixture
+ * builders to anything, and from an integration spec only to the integration of its own provider folder.
+ */
 function testConsumerEdges({ context, graph, config }) {
   const { ts } = context;
   const options = context.projects?.[0]?.options ?? {};
   const edges = [];
-  for (const rel of [...treeOf(config.root).files].filter(file => TEST_CONSUMER.test(file)).sort()) {
+  const consumers = [...treeOf(config.root).files]
+    .map(file => ({ file, provider: TEST_CONSUMER.test(file) ? null : integrationSpecProvider(graph, file) }))
+    .filter(({ file, provider }) => provider !== null || TEST_CONSUMER.test(file))
+    .sort((a, b) => a.file.localeCompare(b.file));
+  for (const { file: rel, provider } of consumers) {
     const abs = path.join(config.root, ...rel.split('/'));
     let text;
     try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
@@ -183,7 +209,7 @@ function testConsumerEdges({ context, graph, config }) {
       if (!(ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) || !statement.moduleSpecifier || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue;
       const resolved = ts.resolveModuleName(statement.moduleSpecifier.text, abs, options, ts.sys).resolvedModule?.resolvedFileName;
       const to = resolved ? graph.abs(canonical(resolved)) : null;
-      if (to) edges.push({ from: rel, to, edge: { declaration: statement }, reexport: false });
+      if (to && (provider === null || inIntegrationOf(graph, to, provider))) edges.push({ from: rel, to, edge: { declaration: statement }, reexport: false });
     }
   }
   return edges;
@@ -254,7 +280,7 @@ export function checkDeadExports({ context, graph, config }) {
         ruleId: 'HFS_UNUSED_EXPORT',
         path: entry, line, column: 1,
         name, owner: owner.root, slot: owner.slot,
-        message: `${entry} exports ${name}, but no production file outside ${owner.root || 'the repository root'} imports it; remove the export (only a service unit spec or a fixture builder counts besides production files).`,
+        message: `${entry} exports ${name}, but no production file outside ${owner.root || 'the repository root'} imports it; remove the export (only a service unit spec, a fixture builder, or an integration spec of this integration's own provider folder counts besides production files).`,
       });
     }
   }

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

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { isIP } from 'node:net';
-import { gitOutput } from '../../lib/git.mjs';
+import { gitOutput } from '../../api/git/lib.mjs';
 import { repositoryName } from '../../lib/repo-identity.mjs';
 import { braceVariants } from '../../lib/glob.mjs';
 import { createSlotResolver, loadSlotManifest, openHfs } from '../../lib/hfs-slots.mjs';

package/runtime/scripts/checks/architecture/required-files.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { gitOutput } from '../../lib/git.mjs';
+import { gitOutput } from '../../api/git/lib.mjs';
 
 /**
  * HFS check 5: the files and directories the slot manifest requires (knowledge/hfs/slots.yaml `requires`,

package/runtime/scripts/lib/recorded-lines.mjs

@@ -1,7 +1,7 @@
 // recorded-lines.mjs - the one home of the file-size ratchet's arithmetic (R20 HFS_SIZE_GROWTH), shared by the back-end
 // and front-end lint canons (each ships a byte copy in its runtime/ bundle, kept by packages/hfs/scripts/sync-runtime.mjs).
 import path from 'node:path';
-import { runGit } from './git.mjs';
+import { runGit } from '../api/git/lib.mjs';
 
 /** The line count of a text; a trailing newline does not open a line. */
 export const lineCount = (text) => {

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

@@ -3,7 +3,7 @@
 // they carry the same README title, the same stack-declaration project name and the same sibling repositories.
 import fs from 'node:fs';
 import path from 'node:path';
-import { gitOutput } from './git.mjs';
+import { gitOutput } from '../api/git/lib.mjs';
 
 const git = (root, args) => gitOutput(args, { cwd: root }).trim();
 const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };

package/test-world.mjs

@@ -142,14 +142,18 @@ const plainKey = (property) => {
     return property.key.type === "Identifier" && !property.computed ? property.key.name : null
 }
 
-/** The world an integration spec (`{ modules }`) or an e2e spec (`{ apps }`) asks for; every such spec asks for one; the retired name `useE2eWorld` exists nowhere. */
+/**
+ * The world an integration spec (`{ modules }`, with real peer apps beside them as `apps` when its client calls another app of
+ * ours) or an e2e spec (`{ apps }`, never `modules`) asks for; every such spec asks for one; the retired name `useE2eWorld`
+ * exists nowhere.
+ */
 export const testWorldShape = {
     meta: {
         type: "problem",
-        docs: { description: "An integration spec calls useTestWorld({ modules }); an e2e spec calls useTestWorld({ apps })." },
+        docs: { description: "An integration spec calls useTestWorld({ modules }) (peer apps may join as `apps`); an e2e spec calls useTestWorld({ apps })." },
         schema: [],
         messages: {
-            modules: "An integration spec tests one capability module on the real database with no HTTP: call `useTestWorld({ modules: [...] })`, not `apps`.",
+            modules: "An integration spec tests capability modules with no HTTP door of ours: call `useTestWorld({ modules: [...] })`; real peer apps its client calls may join beside them as `apps`, never instead of them.",
             apps: "An e2e spec boots applications: call `useTestWorld({ apps: {...} })`, not `modules`.",
             literal: "The options of `useTestWorld(...)` must be one object literal with plain keys: a variable, a spread or a computed key hides whether the spec asks for `modules` or `apps`.",
             missing: "This spec never calls `useTestWorld(...)`: integration and e2e specs run inside the one test world.",
@@ -179,7 +183,8 @@ export const testWorldShape = {
                     if (key === null) return context.report({ node: property, messageId: "literal" })
                     keys.push(key)
                 }
-                if (!keys.includes(wants) || keys.includes(wants === "modules" ? "apps" : "modules")) context.report({ node, messageId: wants })
+                const refused = wants === "modules" ? !keys.includes("modules") : !keys.includes("apps") || keys.includes("modules")
+                if (refused) context.report({ node, messageId: wants })
             },
             "Program:exit"(node) {
                 if (!seen) context.report({ node, loc: { line: 1, column: 0 }, messageId: "missing" })