@starci/eslint-canon-be 3.11.16 → 3.11.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.11.17
4
+
5
+ - Changed: Refresh shared repository identity and quality-service rule data.
6
+
7
+ - Fixed: Preserve generated-contract provenance in front-end tier and bounds checks.
8
+
3
9
  ## 3.11.16
4
10
 
5
11
  - Changed: Refresh the generated canon pins for the governed app-check release.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.11.16",
3
+ "version": "3.11.17",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -44,8 +44,8 @@
44
44
  "scripts/hfs/architecture/canon-jsx-clones.mjs",
45
45
  "scripts/hfs/architecture/client-reaches-server.mjs",
46
46
  "scripts/hfs/architecture/clones.mjs",
47
- "scripts/hfs/architecture/config-unread.mjs",
48
47
  "scripts/hfs/architecture/component-tiers.mjs",
48
+ "scripts/hfs/architecture/config-unread.mjs",
49
49
  "scripts/hfs/architecture/config.mjs",
50
50
  "scripts/hfs/architecture/connection-map.mjs",
51
51
  "scripts/hfs/architecture/constructor-deps.mjs",
@@ -54,6 +54,7 @@
54
54
  "scripts/hfs/architecture/context-owner.mjs",
55
55
  "scripts/hfs/architecture/context-platform-tables.mjs",
56
56
  "scripts/hfs/architecture/context-transaction.mjs",
57
+ "scripts/hfs/architecture/contract-bounds.mjs",
57
58
  "scripts/hfs/architecture/contract-fixture-guard.mjs",
58
59
  "scripts/hfs/architecture/contracts-readonly.mjs",
59
60
  "scripts/hfs/architecture/contracts.mjs",
@@ -31,35 +31,35 @@ pins:
31
31
  source: packages/event-stream/package.json
32
32
  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.'
33
33
  '@starci/grammar':
34
- version: 0.21.9
34
+ version: 0.21.10
35
35
  group: starci
36
36
  install: registry
37
37
  side: fe
38
38
  source: packages/grammar/package.json
39
39
  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.'
40
40
  '@starci/eslint-canon-be':
41
- version: 3.11.16
41
+ version: 3.11.17
42
42
  group: starci
43
43
  install: registry
44
44
  side: be
45
45
  source: packages/eslint-canon-be/package.json
46
46
  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.'
47
47
  '@starci/eslint-canon-fe':
48
- version: 9.9.9
48
+ version: 9.9.10
49
49
  group: starci
50
50
  install: registry
51
51
  side: fe
52
52
  source: packages/eslint-canon-fe/package.json
53
53
  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.'
54
54
  '@starci/eslint-grammar-core':
55
- version: 0.21.9
55
+ version: 0.21.10
56
56
  group: starci
57
57
  install: registry
58
58
  side: fe
59
59
  source: packages/eslint-grammar-core/package.json
60
60
  why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
61
61
  '@starci/eslint-grammar-offset-pop':
62
- version: 0.21.9
62
+ version: 0.21.10
63
63
  group: starci
64
64
  install: registry
65
65
  side: fe
@@ -106,7 +106,7 @@ pins:
106
106
  source: packages/ai-router/package.json
107
107
  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.'
108
108
  '@starci/hfs':
109
- version: 5.0.5
109
+ version: 5.0.6
110
110
  group: starci
111
111
  install: registry
112
112
  side: both
@@ -5107,7 +5107,7 @@ rules:
5107
5107
  - {path: packages/eslint/be/module-shape.spec.mjs, editions: [lite, full], codes: [BE_MODULE_DEFINITION_MISSING]}
5108
5108
  - id: R296
5109
5109
  code: "CI_SECRET_SEALED"
5110
- law: "A name declared in ci.secrets or ci.dependabot.secrets never names a key stored inside an app sealed .starcistacks/<env>/secrets/<member>.enc member. App runtime and CI custody are separate; checks inspect key names without decrypting or printing values."
5110
+ law: "A sealed CI credential copy names an explicit service credential bound to the selected product project, environment, member and key; required product Sonar analysis uses sonar.enc.yaml and an app runtime key never becomes a CI credential. Checks inspect names without decrypting or printing values."
5111
5111
  kinds: [check]
5112
5112
  gates: [settle, land, ci]
5113
5113
  failureCodes: ["CI_SECRET_SEALED"]
@@ -5129,7 +5129,7 @@ rules:
5129
5129
  - {path: packages/hfs/src/ci-custody.spec.mjs, editions: [lite, full], codes: [CI_SECRET_SEALED]}
5130
5130
  - id: R297
5131
5131
  code: "APP_SECRET_IN_CI"
5132
- law: "A sealed member key granted to an app container by a deploy grant never appears in ci.secrets or ci.vars. The grant environment, member and selected key determine app custody; online GitHub custody is verified by starci app ci verify."
5132
+ law: "A sealed member key selected by an app runtime secret declaration or deploy grant never appears in ci.secrets or ci.vars. The consumer environment, member and selected key determine app custody; online GitHub custody is verified by starci app ci verify."
5133
5133
  kinds: [check]
5134
5134
  gates: [settle, land, ci]
5135
5135
  failureCodes: ["APP_SECRET_IN_CI"]
@@ -0,0 +1,72 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { dirname, resolve } from 'node:path';
3
+ /** The generated input-bounds owner is contract data, not an operation. */
4
+ const BOUNDS_MODULE = /(?:^|\/)__generated__\/input-bounds\.ts$/;
5
+ /** Directly exported declarations with the requested name; multiple declarations are ambiguous. */
6
+ function declaredExports(ts, source, name) {
7
+ let count = 0;
8
+ for (const statement of source.statements) {
9
+ if (!ts.canHaveModifiers(statement) || !ts.getModifiers(statement)?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword))
10
+ continue;
11
+ if (ts.isVariableStatement(statement)) {
12
+ count += statement.declarationList.declarations.filter(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === name).length;
13
+ }
14
+ else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement) ||
15
+ ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) && statement.name?.text === name)
16
+ count += 1;
17
+ }
18
+ return count;
19
+ }
20
+ /** The concrete file a relative module specifier resolves to, in the same order as the rule's owner resolver. */
21
+ function readSource(ts, target) {
22
+ for (const file of [`${target}.ts`, `${target}/index.ts`, target]) {
23
+ let text;
24
+ try {
25
+ text = readFileSync(file, 'utf8');
26
+ }
27
+ catch {
28
+ continue;
29
+ }
30
+ const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
31
+ if (source.parseDiagnostics.length)
32
+ return null;
33
+ return { file, source };
34
+ }
35
+ return null;
36
+ }
37
+ /** True only for an unambiguous named export proven through actual declarations to a generated contract declaration. */
38
+ export function isBoundsExport(ts, target, name, ownsGenerated, seen = new Set()) {
39
+ const found = readSource(ts, target);
40
+ if (!found)
41
+ return false;
42
+ const { file, source } = found;
43
+ const key = `${file}#${name}`;
44
+ if (seen.has(key) || seen.size >= 32)
45
+ return false;
46
+ const direct = declaredExports(ts, source, name);
47
+ const matches = [];
48
+ let wildcard = false;
49
+ for (const statement of source.statements) {
50
+ if (!ts.isExportDeclaration(statement))
51
+ continue;
52
+ const module = statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
53
+ if (!statement.exportClause) {
54
+ wildcard = true;
55
+ continue;
56
+ }
57
+ if (!ts.isNamedExports(statement.exportClause))
58
+ continue;
59
+ for (const item of statement.exportClause.elements)
60
+ if (item.name.text === name) {
61
+ matches.push({ origin: (item.propertyName ?? item.name).text, module });
62
+ }
63
+ }
64
+ if (wildcard || direct + matches.length !== 1)
65
+ return false;
66
+ if (BOUNDS_MODULE.test(file.replaceAll('\\', '/')))
67
+ return ownsGenerated(file) && direct === 1 && matches.length === 0;
68
+ const match = matches[0];
69
+ if (direct || !match || !match.module?.startsWith('.'))
70
+ return false;
71
+ return isBoundsExport(ts, resolve(dirname(file), match.module), match.origin, ownsGenerated, new Set([...seen, key]));
72
+ }
@@ -243,7 +243,7 @@ function runHfsMachine(config, context, paths, injectedTypeScript, base, fast, v
243
243
  return hfsChecks;
244
244
  const graph = buildHfsGraph(config, hfsContext);
245
245
  const input = { config, context: hfsContext, graph, base };
246
- const runs = { tiers: () => checkTiers(graph), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
246
+ const runs = { tiers: () => checkTiers(graph, hfsContext.ts), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
247
247
  requiredFiles: () => checkRequiredFiles(input), clones: () => checkClones(input), symbols: () => checkSymbols(input), docLanguage: () => checkDocLanguage(input) };
248
248
  if (graph.profile === 'be')
249
249
  for (const [name, [check]] of Object.entries(BACKEND_MACHINE))
@@ -1,4 +1,6 @@
1
1
  import { byCodeUnit } from '../../lib/list.mjs';
2
+ import { dirname, relative } from 'node:path';
3
+ import { isBoundsExport } from './contract-bounds.mjs';
2
4
  import { registryListImport, registrySlot } from './entity-registry.mjs';
3
5
  /**
4
6
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
@@ -139,14 +141,53 @@ function reportReasonedTierViolation(graph, edge, answer, tierRule, counts, viol
139
141
  message,
140
142
  });
141
143
  }
142
- function inspectTierEdge(graph, edge, tierRule, counts, violations, coverage) {
144
+ /** A public API entry may expose generated contract data without exposing operations to a hook. */
145
+ function contractMetadataEdge(graph, ts, edge, verdict) {
146
+ if (graph.profile !== 'fe' || verdict.reason !== 'tierDirection')
147
+ return false;
148
+ const from = graph.files.get(edge.from);
149
+ const to = graph.files.get(edge.to);
150
+ if (from?.tier !== 'hooks' || to?.tier !== 'transport' || to.slot !== 'fe.modules.api' || !to.owner || to.owner.slot !== 'fe.modules' || to.owner.bindings.capability !== 'api')
151
+ return false;
152
+ // The tier verdict precedes private-entry checks, so prove both app isolation and the owner entry here.
153
+ const fromApp = graph.resolver.classifyPath(edge.from).bindings?.app;
154
+ const toApp = graph.resolver.classifyPath(edge.to).bindings?.app;
155
+ if (!fromApp || fromApp !== toApp || edge.to !== `${to.owner.root}/index.ts`)
156
+ return false;
157
+ const declaration = edge.edge.declaration;
158
+ let names;
159
+ if (ts.isImportDeclaration(declaration)) {
160
+ const clause = declaration.importClause;
161
+ if (!clause || clause.name || !clause.namedBindings || !ts.isNamedImports(clause.namedBindings))
162
+ return false;
163
+ names = clause.namedBindings.elements.map(item => (item.propertyName ?? item.name).text);
164
+ }
165
+ else if (ts.isExportDeclaration(declaration)) {
166
+ if (!declaration.exportClause || !ts.isNamedExports(declaration.exportClause))
167
+ return false;
168
+ names = declaration.exportClause.elements.map(item => (item.propertyName ?? item.name).text);
169
+ }
170
+ else
171
+ return false;
172
+ const apiOwner = to.owner;
173
+ const dirnameOfEntry = dirname(to.abs);
174
+ const ownsGenerated = (file) => {
175
+ const rel = `${apiOwner.root}/${relative(dirnameOfEntry, file).replaceAll('\\', '/')}`;
176
+ const classified = graph.resolver.classifyPath(rel);
177
+ const owner = graph.resolver.ownerOf(rel);
178
+ return classified.status === 'owned' && classified.slot === 'fe.transport.generated' &&
179
+ owner?.slot === apiOwner.slot && owner.root === apiOwner.root;
180
+ };
181
+ return names.length > 0 && names.every(name => isBoundsExport(ts, to.abs, name, ownsGenerated));
182
+ }
183
+ function inspectTierEdge(graph, ts, edge, tierRule, counts, violations, coverage) {
143
184
  const verdict = graph.resolver.importAllowed(edge.from, edge.to);
144
185
  if (verdict.reason === 'unowned' || verdict.reason?.startsWith('slot')) {
145
186
  coverage.unclassifiedEdges += 1;
146
187
  return;
147
188
  }
148
189
  coverage.edgesChecked += 1;
149
- if (verdict.reason === 'tierDirection' && registryListImport(graph.resolver, edge))
190
+ if (verdict.reason === 'tierDirection' && (registryListImport(graph.resolver, edge) || contractMetadataEdge(graph, ts, edge, verdict)))
150
191
  return;
151
192
  reportReasonedTierViolation(graph, edge, verdict, tierRule, counts, violations);
152
193
  }
@@ -197,14 +238,14 @@ function addOwnerCycleViolations(adjacency, witness, violations) {
197
238
  }
198
239
  return components.length;
199
240
  }
200
- export function checkTiers(graph) {
241
+ export function checkTiers(graph, ts) {
201
242
  const { resolver, profile } = graph;
202
243
  const violations = [];
203
244
  const tierRule = profile === 'be' ? 'BE_TIER_DIRECTION' : 'FE_TIER_DIRECTION';
204
245
  const coverage = { edgesChecked: 0, unclassifiedEdges: 0 };
205
246
  const counts = { tierDirection: 0, layerOrder: 0, crossApp: 0 };
206
247
  for (const edge of graph.edges)
207
- inspectTierEdge(graph, edge, tierRule, counts, violations, coverage);
248
+ inspectTierEdge(graph, ts, edge, tierRule, counts, violations, coverage);
208
249
  // Owner cycles: nodes are owner units, edges the imports between two distinct units.
209
250
  const { adjacency, witness } = ownerAdjacency(graph, resolver);
210
251
  const cycles = addOwnerCycleViolations(adjacency, witness, violations);
@@ -5,10 +5,15 @@ import fs from 'node:fs';
5
5
  import path from 'node:path';
6
6
  import { revParseQuery } from '../api/git/rev-parse-query.mjs';
7
7
  import { remote as gitRemote } from '../api/git/remote.mjs';
8
- import { gitOutputOf } from '../lib/git.mjs';
8
+ import { gitOutputOf, withoutGitLocalEnv } from '../lib/git.mjs';
9
9
  import { trimTrailingSlashes } from './trailing-slashes.mjs';
10
10
  /** One git call (a scripts/api/git call file) in `root`: its trimmed stdout; throws unless git exits 0. */
11
- const git = (call, root, args) => gitOutputOf(call(args, { cwd: root })).trim(); // gitOutputOf threw unless git exited 0, whose stdout is text
11
+ 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
12
+ /** Identity queries need repository configuration, never age identities or selected service connection credentials. */
13
+ export function identityQueryEnvironment(parent, privateNames = []) {
14
+ const selected = new Set(privateNames.map((name) => name.toUpperCase()));
15
+ return Object.fromEntries(Object.entries(withoutGitLocalEnv(parent)).filter(([name]) => !selected.has(name.toUpperCase()) && !/^(?:SOPS_AGE_KEY(?:_FILE)?|SONAR_.*)$/iu.test(name)));
16
+ }
12
17
  const real = (p) => { try {
13
18
  return fs.realpathSync(p);
14
19
  }
@@ -26,20 +31,20 @@ catch {
26
31
  return null;
27
32
  } };
28
33
  /** { repositoryRoot, inWorkTree, home } for `root`: home is the main checkout folder when root is a repository top level. */
29
- function identityOf(root) {
34
+ function identityOf(root, env = process.env) {
30
35
  const state = stateOf(root);
31
36
  if (state === null)
32
- return askGit(root);
37
+ return askGit(root, env);
33
38
  if (!known.has(state))
34
- known.set(state, askGit(root));
39
+ known.set(state, askGit(root, env));
35
40
  return known.get(state);
36
41
  }
37
- function askGit(root) {
42
+ function askGit(root, env) {
38
43
  let inWorkTree = false, repositoryRoot = false, home = null;
39
44
  try {
40
45
  // Identity comes from Git only when root IS a repository (or worktree) top level, never a folder inside one.
41
46
  // One git call answers both questions: the top level on the first line, the common git dir on the second.
42
- const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir']).split(String.fromCodePoint(10)).map((line) => line.trim());
47
+ const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir'], env).split(String.fromCodePoint(10)).map((line) => line.trim());
43
48
  repositoryRoot = real(top) === real(root);
44
49
  inWorkTree = true;
45
50
  const common = path.resolve(root, commonDir);
@@ -55,11 +60,11 @@ function askGit(root) {
55
60
  * name outside Git, else the folder name. A folder inside a larger repository (a nested product, an example) is named by
56
61
  * its own folder.
57
62
  */
58
- export function repositoryName(root) {
59
- const { inWorkTree, repositoryRoot, home } = identityOf(root);
63
+ export function repositoryName(root, { env = process.env } = {}) {
64
+ const { inWorkTree, repositoryRoot, home } = identityOf(root, env);
60
65
  if (repositoryRoot) {
61
66
  try {
62
- const remote = trimTrailingSlashes(git(gitRemote, root, ['get-url', 'origin'])).replace(GIT_SUFFIX, '');
67
+ const remote = trimTrailingSlashes(git(gitRemote, root, ['get-url', 'origin'], env)).replace(GIT_SUFFIX, '');
63
68
  const name = remote.split(/[/:]/u).pop();
64
69
  if (name)
65
70
  return name;