@starci/eslint-canon-be 3.0.8 → 3.0.9

package/runtime/scripts/hfs/project-graph.mjs

@@ -4,7 +4,7 @@
 // Both @starci/eslint-canon-be and @starci/eslint-canon-fe ship a byte copy of this file (and of the machine it imports) in their
 // runtime/ bundle (scripts/hfs/sync-runtime.mjs). There is no second graph: `projectGraph` runs `checkArchitecture`
 // (scripts/hfs/architecture/index.mjs) with `surface: 'lint'`, which judges exactly the checks whose findings attach to a
-// TypeScript file, and indexes the findings by repository-relative path. `hfs check` runs the other surface ('check') and never
+// TypeScript file, and indexes the findings by repository-relative path. `starci app check` runs the other surface ('check') and never
 // the lint one, so no rule has two enforcers.
 //
 // The per-path judgements of the slot manifest (hfs-path-findings.mjs: slot ownership, source file name, spec placement) over the
@@ -16,7 +16,7 @@ import fs from 'node:fs';
 import { checkArchitecture } from './architecture/index.mjs';
 import { openHfs } from './slots.mjs';
 import { pathFindings } from './path-findings.mjs';
-import { runGit } from '../api/git/lib.mjs';
+import { lsFiles } from '../api/git/ls-files.mjs';
 import { posixPath } from '../lib/path-key.mjs';
 import { onLintSurface } from './architecture/surface.mjs';
 
@@ -34,7 +34,7 @@ export function projectGraph({ repoRoot, runtimeRoot, injectedTypeScript }) {
     const opened = openHfs({ root: runtimeRoot, repoRoot: key });
     const report = checkArchitecture({ repositoryRoot: key, hfs: opened, injectedTypeScript, surface: 'lint' });
     if (report.errors.length) throw new Error(`the project graph of ${key} cannot be built: ${report.errors.map((e) => `${e.ruleId}: ${e.message}`).join('; ')}`);
-    const listed = runGit(['ls-files', '-z', '--cached', '--exclude-standard'], { dir: key, maxBuffer: 256 * 1024 * 1024 });
+    const listed = lsFiles(['-z', '--cached', '--exclude-standard'], { dir: key, maxBuffer: 256 * 1024 * 1024 });
     if (listed.error || listed.status !== 0) throw new Error(`the project graph of ${key} needs a Git work tree (git ls-files failed)`);
     const tracked = listed.stdout.split('\0').filter(Boolean).map(posixPath);
     const repoFindings = pathFindings({ files: tracked, resolver: opened, profile: opened.repo.profile }).filter((finding) => onLintSurface(key, finding));

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

@@ -1,11 +1,14 @@
 // repo-identity.mjs - who a repository is, independent of the folder it is checked out in.
-// A git worktree (D:/starci-lanes/<lane>/<name>) and the main checkout of the same repository are ONE repository:
+// A git worktree (<lanes root>/<lane>/<name>) and the main checkout of the same repository are ONE repository:
 // 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 '../api/git/lib.mjs';
+import { revParseQuery } from '../api/git/rev-parse-query.mjs';
+import { remote as gitRemote } from '../api/git/remote.mjs';
+import { gitOutputOf } from '../lib/git.mjs';
 
-const git = (root, args) => gitOutput(args, { cwd: root }).trim();
+/** 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();
 const real = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
 
 /** { repositoryRoot, inWorkTree, home } for `root`: home is the main checkout folder when root is a repository top level. */
@@ -13,9 +16,9 @@ function identityOf(root) {
   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.
-    repositoryRoot = real(git(root, ['rev-parse', '--show-toplevel'])) === real(root);
+    repositoryRoot = real(git(revParseQuery, root, ['--show-toplevel'])) === real(root);
     inWorkTree = true;
-    const common = path.resolve(root, git(root, ['rev-parse', '--git-common-dir']));
+    const common = path.resolve(root, git(revParseQuery, root, ['--git-common-dir']));
     if (repositoryRoot && path.basename(common) === '.git') home = path.dirname(common);
   } catch { /* Not a Git work tree; the caller falls back to the folder and package name. */ }
   return { inWorkTree, repositoryRoot, home };
@@ -31,7 +34,7 @@ export function repositoryName(root) {
   if (home) return path.basename(home);
   if (repositoryRoot) {
     try {
-      const remote = git(root, ['remote', 'get-url', 'origin']).replace(/[\/]+$/u, '').replace(/\.git$/iu, '');
+      const remote = git(gitRemote, root, ['get-url', 'origin']).replace(/[\/]+$/u, '').replace(/\.git$/iu, '');
       const name = remote.split(/[\/:]/u).pop();
       if (name) return name;
     } catch { /* No origin remote. */ }

package/runtime/scripts/hfs/rule-params-shape.mjs

@@ -0,0 +1,50 @@
+// rule-params-shape.mjs - the shape of `ruleParams` of an app slot manifest (knowledge/hfs/slots.yaml): the parameters both sides
+// share (`common`), the back end's own (`be`) and the front end's overrides (`fe`). Pure: a parsed manifest in, a list of
+// problems out, in the words of modules/schemas/hfs-slots.schema.yaml. scripts/hfs/slots.mjs (loadSlotManifest) is the reader.
+import { isPlainObject } from '../../engine/plain-object.mjs';
+import { paramNamesOk } from './param-names.mjs';
+import { kindParamProblems, scenarioProblem } from './declaration-slots.mjs';
+import { roleListProblems, SCHEMA_AUTHORITIES, unitRolesProblems } from './manifest-shape.mjs';
+
+const PROFILES = ['be', 'fe'];
+
+/** The shape problems of `m.ruleParams`. */
+export function ruleParamsProblems(m) {
+  const bad = [];
+  const blockOk = (v) => isPlainObject(v) && Number.isInteger(v.lines) && v.lines >= 2 && Number.isInteger(v.tokens) && v.tokens >= 1 && Object.keys(v).length === 2;
+  const fileLinesOk = (v) => isPlainObject(v) && Number.isInteger(v.soft) && v.soft >= 1 && typeof v.hardGrowth === 'boolean' && Object.keys(v).length === 2;
+  const rp = m.ruleParams;
+  if (!isPlainObject(rp) || Object.keys(rp).some((k) => ![...PROFILES, 'common'].includes(k)) || !isPlainObject(rp.common) || !isPlainObject(rp.be) || (rp.fe !== undefined && !isPlainObject(rp.fe))) bad.push('ruleParams must be a map with common, be and optionally fe');
+  else {
+    // common holds the parameters both sides share; a side may restate one of them (a valid value) as an override, nothing else.
+    const sharedParam = (key, v) => (key === 'fileLines' ? fileLinesOk(v) : blockOk(v));
+    const sideOk = (side, own, extra = []) => own.every((k) => side[k] !== undefined) && Object.entries(side).every(([k, v]) => own.includes(k) || extra.includes(k) || (['fileLines', 'duplicateBlock'].includes(k) && sharedParam(k, v)));
+    // Edition lite: a side's optional `lite` map overrides keys of the same side (never `lite` itself) when the app declares edition lite.
+    const liteOk = (lite, keys) => lite === undefined || (isPlainObject(lite) && Object.keys(lite).length > 0 && Object.keys(lite).every((k) => k !== 'lite' && keys.includes(k)));
+    const BE_OWN = ['infraOwners', 'eventBus', 'specDoubles', 'paramNames', 'suffixes', 'bannedSuffixes', 'contractShape', 'unitRoles', 'logicRoles', 'thinRoles', 'patternScenarios', 'kindPatterns', 'addKinds'];
+    if (Object.keys(rp.common).length !== 2 || !fileLinesOk(rp.common.fileLines) || !blockOk(rp.common.duplicateBlock)) bad.push('ruleParams.common needs exactly fileLines {soft, hardGrowth} and duplicateBlock {lines >= 2, tokens >= 1}');
+    if (!sideOk(rp.be, BE_OWN, ['schemaAuthority', 'lite']) || (rp.be.schemaAuthority !== undefined && !SCHEMA_AUTHORITIES.includes(rp.be.schemaAuthority)) || !liteOk(rp.be.lite, [...BE_OWN, 'fileLines', 'duplicateBlock', 'schemaAuthority'])) bad.push('ruleParams.be needs infraOwners, eventBus, specDoubles, paramNames, suffixes, bannedSuffixes, contractShape {helper}, unitRoles, logicRoles, thinRoles, patternScenarios, kindPatterns and addKinds (fileLines and duplicateBlock live in ruleParams.common, a side may override them); optional: schemaAuthority (' + SCHEMA_AUTHORITIES.join(' | ') + ') and lite (overrides of the same keys)'); else bad.push(...unitRolesProblems(rp.be), ...roleListProblems(rp.be));
+    bad.push(...scenarioProblem(rp.be.patternScenarios), ...kindParamProblems(rp.be, m.triggerKinds));
+    if (!isPlainObject(rp.be.contractShape) || Object.keys(rp.be.contractShape).length !== 1 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(String(rp.be.contractShape.helper))) bad.push('ruleParams.be.contractShape must be {helper: <identifier>}');
+    const owners = rp.be.infraOwners;
+    const ownerId = /^(platform|integrations)\/[a-z][a-z0-9-]*$/;
+    if (!isPlainObject(owners) || !Object.keys(owners).length || !Object.entries(owners).every(([key, list]) => key && Array.isArray(list) && list.every((o) => ownerId.test(String(o))) && new Set(list).size === list.length)) bad.push('ruleParams.be.infraOwners must map a non-empty specifier to a list of unique platform/<capability> or integrations/<provider> owners ([] means nowhere)');
+    const className = /^[A-Z][A-Za-z0-9]*$/;
+    const memberMap = (v, allowEmpty) => isPlainObject(v) && Object.keys(v).length > 0 && Object.values(v).every((list) => Array.isArray(list) && (allowEmpty || list.length > 0) && list.every((x) => className.test(String(x))) && new Set(list).size === list.length);
+    const eventBus = rp.be.eventBus;
+    if (!isPlainObject(eventBus) || Object.keys(eventBus).sort().join() !== 'classes,imports' || !memberMap(eventBus.imports, true) || !memberMap(eventBus.classes, false)) bad.push('ruleParams.be.eventBus must be {imports: {<module>: [unique PascalCase members]}, classes: {<module>: [non-empty unique PascalCase classes]}}');
+    if (!paramNamesOk(rp.be.paramNames)) bad.push('ruleParams.be.paramNames must be a non-empty list of unique {type | typeSuffix, names, nameSuffix?} entries');
+    const roleList = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => /^[a-z][a-z0-9-]*$/.test(String(x))) && new Set(v).size === v.length;
+    if (!roleList(rp.be.suffixes)) bad.push('ruleParams.be.suffixes must be a non-empty list of unique kebab-case role suffixes');
+    if (!roleList(rp.be.bannedSuffixes)) bad.push('ruleParams.be.bannedSuffixes must be a non-empty list of unique kebab-case suffixes');
+    else if (roleList(rp.be.suffixes) && rp.be.suffixes.some((x) => rp.be.bannedSuffixes.includes(x))) bad.push('ruleParams.be.suffixes and bannedSuffixes must be disjoint');
+    const formNames = ['call', 'new', 'curried', 'object', 'primitive', 'array'];
+    const formsOk = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => formNames.includes(x)) && new Set(v).size === v.length;
+    const doubleOk = (v) => isPlainObject(v) && /^[A-Za-z][A-Za-z0-9]*$/.test(String(v.double)) && formsOk(v.forms);
+    const regexOk = (v) => { try { return typeof v === 'string' && v.length > 0 && Boolean(new RegExp(v)); } catch { return false; } };
+    const sd = rp.be.specDoubles;
+    if (!isPlainObject(sd) || Object.keys(sd).sort().join() !== 'doubles,fallback,kit' || typeof sd.kit !== 'string' || !sd.kit || !Array.isArray(sd.doubles) || !sd.doubles.length || !sd.doubles.every((e) => doubleOk(e) && regexOk(e.token) && Object.keys(e).length === 3) || !doubleOk(sd.fallback) || Object.keys(sd.fallback).length !== 2) bad.push('ruleParams.be.specDoubles must be {kit, doubles: [{token: regex, double, forms}], fallback: {double, forms}} with forms drawn from call, new, curried, object, primitive, array');
+    if (rp.fe !== undefined && (!sideOk(rp.fe, [], ['lite']) || !liteOk(rp.fe.lite, ['fileLines', 'duplicateBlock']))) bad.push('ruleParams.fe may only restate fileLines and duplicateBlock of ruleParams.common, and carry a lite override of them');
+  }
+  return bad;
+}

package/runtime/scripts/hfs/rules/fe-no-tests.mjs

@@ -12,11 +12,12 @@ import { found, readJson } from './read.mjs';
 export const FE_NO_TESTS = 'FE_NO_TESTS';
 const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
 const TEST_DIRECTORY = /(?:^|\/)(?:e2e|__tests__|__mocks__|test-support)\//;
-const TEST_TOOL_FILE = /(?:^|\/)(?:(?:vitest|jest|playwright)\.[^/]+|cypress\.config\.[^/]+|tsconfig\.e2e\.json|e2e\.ya?ml)$/;
-const TEST_SCRIPT_NAME = /^(?:pre|post)?test(?::|$)/;
-const TEST_RUNNER_COMMAND = /(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b/;
-const TEST_DEPENDENCY = /^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$/;
-const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+export const TEST_TOOL_FILE = /(?:^|\/)(?:(?:vitest|jest|playwright)\.[^/]+|cypress\.config\.[^/]+|tsconfig\.e2e\.json|e2e\.ya?ml)$/;
+// The edition rule (rules/edition.mjs, L01) applies the same lists to the whole app tree in lite: they are the test vocabulary.
+export const TEST_SCRIPT_NAME = /^(?:pre|post)?test(?::|$)/;
+export const TEST_RUNNER_COMMAND = /(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b/;
+export const TEST_DEPENDENCY = /^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$/;
+export const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
 
 /** True for a path FE_NO_TESTS owns: a spec file, a test directory or a test-tool file. */
 export const isFeTestPath = (file) => SPEC_FILE.test(file) || TEST_DIRECTORY.test(file) || TEST_TOOL_FILE.test(file);

package/runtime/scripts/hfs/rules/read.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /** Files above this size are not read by a tree check (a tracked binary or a generated dump is no source of these laws). */
-export const MAX_READ_BYTES = 1024 * 1024;
+const MAX_READ_BYTES = 1024 * 1024;
 
 /** The text of `rel` under `repoRoot`, or null when it is absent, unreadable, over MAX_READ_BYTES or binary. */
 export function readText(repoRoot, rel) {

package/runtime/scripts/hfs/rules/secrets.mjs

@@ -6,10 +6,10 @@
 //   - a line of any other tracked text file that matches a secret pattern.
 // A finding names the file, the line and the pattern, never the value.
 import { FORBIDDEN_FILES, secretHits } from '../../lib/secret-patterns.mjs';
-import { isSopsEnvelope } from '../../lib/test-secrets.mjs';
+import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
 
-export const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
+const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
 /** Files whose lines are not secrets: a lockfile carries integrity hashes, never a credential. */
 const NOT_SCANNED = /(^|\/)package-lock\.json$/;
 
@@ -19,7 +19,7 @@ export const slotOwnsSecrets = (slot) => slot?.rules?.includes(PLAINTEXT_SECRET)
 /**
  * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
- * large, absent). The whole-tree check reads the work tree and the commit hook (`hfs work-hygiene`) reads the staged blob: one judgement.
+ * large, absent). The whole-tree check reads the work tree and the commit hook (`starci app hygiene`) reads the staged blob: one judgement.
  */
 export function secretFileFindings({ file, text }) {
   const being = FORBIDDEN_FILES.find((rule) => rule.test(file));

package/runtime/scripts/hfs/rules/spec-placement.mjs

@@ -7,7 +7,7 @@
 // finding names the rule rather than only the missing slot. Which folder is a layer is read from the slot manifest, never spelled here.
 import { found } from './read.mjs';
 
-export const SPEC_PLACEMENT = 'BE_SPEC_PLACEMENT';
+const SPEC_PLACEMENT = 'BE_SPEC_PLACEMENT';
 const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
 const TEST_SLOT_TESTS = new Set(['unit-beside', 'e2e']);