@starci/hfs 2.0.2 → 3.0.0

package/runtime/scripts/lib/hfs-path-findings.mjs

@@ -0,0 +1,84 @@
+// hfs-path-findings.mjs - the per-path judgements of the slot manifest: what a tracked path is. One function, two surfaces: `hfs check`
+// (checkRepo) runs it over the tracked tree and keeps the findings that have no TypeScript file to sit on; the lint canon's project graph
+// (scripts/lib/project-graph.mjs) runs it over the same tree and serves the findings on a TypeScript file as ESLint reports.
+//   HFS_SLOT_UNDECLARED / HFS_SLOT_AMBIGUOUS / HFS_SLOT_NOT_ENABLED / HFS_FORBIDDEN_PRESENT / HFS_TOOL_CONFIG_LOCAL / HFS_TRACKED_MUST_BE_IGNORED (R01, R16)
+//   BE_SOURCE_FORM (R89, the file name), BE_SPEC_PLACEMENT (R102)
+import path from 'node:path';
+import { allowsFile } from './hfs-allows.mjs';
+import { isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
+import { slotOwnsSecrets } from './hfs-rules/secrets.mjs';
+import { specPlacementFindings } from './hfs-rules/spec-placement.mjs';
+
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SOURCE_ROOT = /^(?:src|apps)\//;
+const FREE_NAMES = new Set(['index.ts', 'main.ts']);
+const PLAIN_ENTRY = /^<[a-z][a-z0-9-]*>.ts$/;
+
+/**
+ * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
+ * be.persistence, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
+ * as order.service.spec.ts keeps its inner words kebab-case). A suffix of ruleParams.be.bannedSuffixes anywhere in the
+ * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
+ */
+function sourceFormFindings({ files, resolver }) {
+  const { suffixes, bannedSuffixes } = resolver.ruleParams();
+  // A suffix a slot names in its own file pattern (`*.builder.ts` of be.tests.fixtures.builders) is that slot's role: a file with it
+  // anywhere else is refused, so a builder cannot live beside a service or in the fixtures root.
+  const boundSuffixes = new Map();
+  for (const slot of resolver.slots()) {
+    const bound = /\*\.([a-z0-9-]+)\.ts$/.exec(slot.path ?? '')?.[1];
+    if (bound && suffixes.includes(bound)) boundSuffixes.set(bound, slot);
+  }
+  const findings = [];
+  for (const file of files) {
+    if (!file.endsWith('.ts') || !SOURCE_ROOT.test(file)) continue;
+    const c = resolver.classifyPath(file);
+    if (c.status !== 'owned' || c.tracking === 'ignored') continue;
+    const base = path.posix.basename(file);
+    if (FREE_NAMES.has(base)) continue;
+    // A literal file name the owning slot itself requires or allows (persistence/connection.ts, world/global-setup.ts) is its role.
+    const slot = resolver.slot(c.slot);
+    if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].some((entry) => entry === base)) continue;
+    // A slot whose `allows` holds a bare <name>.ts entry (be.tests.world.kit) names its files plainly, as platform/primitives does: kebab-case is the whole form.
+    const admitted = allowsFile(resolver, file);
+    if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) continue;
+    if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') continue;
+    const parts = base.slice(0, -'.ts'.length).split('.');
+    const banned = parts.slice(1).find((part) => bannedSuffixes.includes(part));
+    if (banned) {
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})` });
+    } else if (boundSuffixes.has(parts.at(-1)) && parts.length >= 2 && boundSuffixes.get(parts.at(-1)).id !== c.slot) {
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: parts.at(-1), message: `${file}: the suffix .${parts.at(-1)}.ts belongs to ${boundSuffixes.get(parts.at(-1)).path} only; move the file there` });
+    } else if (parts.length < 2 || !parts.every((part) => KEBAB.test(part)) || !suffixes.includes(parts.at(-1))) {
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, message: `${file}: the name must be <kebab-name>.<suffix>.ts with a suffix from the closed list (${suffixes.join(', ')}), or index.ts, main.ts or a migration` });
+    }
+  }
+  return findings;
+}
+
+/** The findings of the slot manifest over `files` (repository-relative tracked paths) of a repository of `profile`. */
+export function pathFindings({ files, resolver, profile }) {
+  const findings = [];
+  for (const file of files) {
+    if (profile === 'fe' && isFeTestPath(file)) continue;   // a test path of a front end is FE_NO_TESTS's, the one finding of that file
+    const c = resolver.classifyPath(file);
+    if (c.status === 'no-slot') {
+      findings.push({ code: 'HFS_SLOT_UNDECLARED', level: 'error', path: file, nearest: c.nearest, message: `${file} matches no slot${c.nearest ? `; nearest slot ${c.nearest.slot} (${c.nearest.pattern}), matched ${c.nearest.matchedPrefix || '.'} then expected ${c.nearest.expectedNext ?? 'nothing'}` : ''}` });
+    } else if (c.status === 'ambiguous') {
+      findings.push({ code: 'HFS_SLOT_AMBIGUOUS', level: 'error', path: file, candidates: c.candidates, message: `${file} is owned equally by ${c.candidates.map((x) => x.slot ?? x).join(', ')}` });
+    } else if (c.status === 'not-enabled') {
+      findings.push({ code: 'HFS_SLOT_NOT_ENABLED', level: 'error', path: file, slot: c.slot, message: `${file} belongs to ${c.slot}, an opt-in slot hfs.json neither lists in optionalSlots nor implies through an app kind` });
+    } else if (c.status === 'forbidden') {
+      const slot = resolver.slot(c.slot);
+      if (slotOwnsSecrets(slot)) continue;   // the secret scan reports the file (R06): one finding per file
+      const own = slot.rules?.includes('HFS_TOOL_CONFIG_LOCAL') ? 'HFS_TOOL_CONFIG_LOCAL' : 'HFS_FORBIDDEN_PRESENT';
+      findings.push({ code: own, level: 'error', path: file, slot: c.slot, goesTo: c.goesTo, message: `${file} is tracked but ${c.slot} is forbidden in the tree${c.goesTo ? `; it belongs at ${c.goesTo}` : ''}` });
+    } else if (c.tracking === 'ignored') {
+      findings.push({ code: 'HFS_TRACKED_MUST_BE_IGNORED', level: 'error', path: file, slot: c.slot, message: `${file} is tracked but ${c.slot} must be gitignored` });
+    }
+  }
+
+  if (profile === 'be') findings.push(...sourceFormFindings({ files, resolver }), ...specPlacementFindings({ files, resolver }));
+  // The lint canon's project graph serves these findings on a TypeScript file; the origin keeps them apart from the machine's.
+  return findings.map((finding) => ({ ...finding, origin: 'repo' }));
+}

package/runtime/scripts/lib/hfs-rules/pipeline.mjs

@@ -1,8 +1,9 @@
-// pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned `hfs check`; pre-push runs typecheck and lint.
-//   .github/workflows/ci.yml   a `run:` step that runs `hfs check` as a whole (not `--fast`): `npx hfs check`, `npx @starci/hfs[@<version>]
-//                              check`, or `npm run <script>` of the root package.json whose command is `hfs check`; a version named in
-//                              the step is the @starci/hfs pin of canon-pins.yaml (an installed one is pinned by the pin check, R15)
-//   .husky/pre-push            `npm run typecheck` and `npm run lint:check`, each on a line of its own
+// pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned `hfs lint`; pre-push runs typecheck and lint.
+//   .github/workflows/ci.yml   a `run:` step that runs `hfs lint` (the one lint entry: eslint, the repository check, stylelint): `npx hfs lint`,
+//                              `npx @starci/hfs[@<version>] lint`, or `npm run <script>` of the root package.json whose command runs `hfs lint`
+//                              (`npm run lint`, arguments after `--` allowed); a version named in the step is the @starci/hfs pin of
+//                              canon-pins.yaml (an installed one is pinned by the pin check, R15)
+//   .husky/pre-push            `npm run typecheck` and `npm run lint`, each on a line of its own
 // A missing file is the slot manifest's finding (HFS_SLOT_REQUIRED_MISSING); a file that is present and lacks the step is this rule's.
 // The redirect of `core.hooksPath` away from husky is the architecture machine's (HFS_HOOKS_PATH_REDIRECTED).
 import { found, readJson, readText } from './read.mjs';
@@ -12,9 +13,8 @@ export const CI_FILE = '.github/workflows/ci.yml';
 export const PRE_PUSH_FILE = '.husky/pre-push';
 export const hfsPackage = '@starci/hfs';
 const RUN_LINE = /^\s*(?:-\s+)?run:\s*(.+?)\s*$/;
-const HFS_CHECK = /^(?:npx\s+(?:--no-install\s+|-y\s+)?)?(?:@starci\/hfs|hfs)(?:@(\S+))?\s+check(\s.*)?$/;
+const HFS_LINT = /^(?:npx\s+(?:--no-install\s+|-y\s+)?)?(?:@starci\/hfs|hfs)(?:@(\S+))?\s+lint(\s.*)?$/;
 const NPM_RUN = /^npm run ([\w:.-]+)(?:\s+--\s+(.*))?$/;
-const FAST = /(^|\s)--fast(\s|$)/;
 
 const commandsOf = (text) => text.split(/\r?\n/).map((line) => RUN_LINE.exec(line)?.[1]).filter(Boolean).map((command) => command.replace(/^["']|["']$/g, ''));
 
@@ -33,17 +33,16 @@ export function pipelineFindings({ repoRoot, files, pins }) {
   const ci = files.includes(CI_FILE) ? readText(repoRoot, CI_FILE) : null;
   if (ci !== null) {
     const scripts = readJson(repoRoot, 'package.json')?.scripts ?? {};
-    const checks = commandsOf(ci).map((command) => HFS_CHECK.exec(expanded(command, scripts))).filter(Boolean);
-    const whole = checks.filter((match) => !FAST.test(match[2] ?? ''));
-    if (!whole.length) findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`hfs check\` (\`npx hfs check\`, or an npm script that is exactly that); CI must run the whole pinned hfs check, not --fast`, { step: 'hfs check' }));
-    else if (pinned && !whole.some((match) => match[1] === undefined || match[1] === pinned)) {
-      findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs hfs check at ${whole[0][1]}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'hfs check', pinned }));
+    const lints = commandsOf(ci).flatMap((command) => expanded(command, scripts).split(/\s*&&\s*/)).map((command) => HFS_LINT.exec(command)).filter(Boolean);
+    if (!lints.length) findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`hfs lint\` (\`npm run lint\`, or \`npx hfs lint\`); CI runs the one lint entry, which includes the repository check`, { step: 'hfs lint' }));
+    else if (pinned && !lints.some((match) => match[1] === undefined || match[1] === pinned)) {
+      findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs hfs lint at ${lints[0][1]}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'hfs lint', pinned }));
     }
   }
   const prePush = files.includes(PRE_PUSH_FILE) ? readText(repoRoot, PRE_PUSH_FILE) : null;
   if (prePush !== null) {
     const lines = prePush.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
-    for (const step of ['typecheck', 'lint:check']) {
+    for (const step of ['typecheck', 'lint']) {
       if (!runsStep(lines, step)) findings.push(found(CI_MISSING_CANON, PRE_PUSH_FILE, `${PRE_PUSH_FILE} does not run \`npm run ${step}\`; pre-push runs typecheck and lint`, { step }));
     }
   }

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

@@ -2,8 +2,6 @@
 //   - a unit spec is `<name>.service.spec.ts` beside its service, in a slot whose `tests` is `unit-beside` (the slot and the lint rule
 //     `unit-test-colocated` judge the name);
 //   - integration, e2e and contract specs are `src/tests/{integration,e2e,contract}/...`, the slots whose `tests` is `e2e`;
-//   - an app's own folder (`apps/<app>/src/`, the slots that name an `appKind`) holds the app's composition spec, which the architecture
-//     machine's app-composition check judges.
 // Every other tracked `*.spec.*`, `*.test.*` or `*-spec.*` file is a finding, `scripts/` and `tools/` included: an operational script
 // carries no spec, and a spec that guards one moves into a layer or goes. A file no slot owns (`tools/x.spec.ts`) is judged too, so the
 // finding names the rule rather than only the missing slot. Which folder is a layer is read from the slot manifest, never spelled here.
@@ -23,7 +21,7 @@ export function specPlacementFindings({ files, resolver }) {
     if (!isSpecFile(file) || file.includes('node_modules/')) continue;
     const classified = resolver.classifyPath(file);
     const slot = classified.status === 'owned' ? resolver.slot(classified.slot) : null;
-    if (slot && (TEST_SLOT_TESTS.has(slot.tests) || slot.appKind !== undefined)) continue;
+    if (slot && TEST_SLOT_TESTS.has(slot.tests)) continue;
     const where = slot ? `slot ${slot.id}` : 'no slot';
     findings.push(found(SPEC_PLACEMENT, file, `${file} is a spec outside the test layers (${where}); a unit spec is <name>.service.spec.ts beside its service and an integration, e2e or contract spec sits under src/tests/{integration,e2e,contract}; an operational script or a tool carries no spec`));
   }

package/templates/be/ci-workflows/github/workflows/ci.yml

@@ -21,16 +21,8 @@ jobs:
           node-version: {{nodeMajor}}
           cache: npm
       - run: npm ci
-      - name: hfs check
-        run: npm run hfs:report
       - name: lint
-        run: npm run lint:check
-      - name: lint report
-        if: ${{ !cancelled() }}
-        run: npm run lint:report
-      - name: eslint sonar import
-        if: ${{ !cancelled() }}
-        run: npx hfs report eslint reports/eslint.json reports/eslint.sonar.json
+        run: npm run lint -- --sonar reports/lint.sonar.json
       - name: format
         run: npm run format:check
       - name: typecheck

package/templates/be/hooks/husky/pre-push

@@ -1,7 +1,6 @@
 {{header}}
-# Push gate: types, lint, format, the architecture check on the owners this push touches, unit specs affected since main. Never integration, e2e or contract.
+# Push gate: types, lint, format, unit specs affected since main. Never integration, e2e or contract.
 npm run typecheck
-npm run lint:check
+npm run lint
 npm run format:check
-npm run hfs:check -- --fast
 npm run test:affected -- --changedSince=origin/main

package/templates/be/package-scripts/package.json

@@ -4,9 +4,8 @@
     {{appScripts}}
     "typecheck": "tsc -p tsconfig.json",
     "typecheck:tests": "tsc -p src/tests/tsconfig.json",
-    "lint": "eslint --fix .",
-    "lint:check": "eslint .",
-    "lint:report": "eslint . --format json --output-file reports/eslint.json",
+    "lint": "hfs lint",
+    "lint:fix": "hfs lint --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "jest --selectProjects unit --coverage",
@@ -15,8 +14,6 @@
     "test:e2e": "npm run typecheck:tests && jest --selectProjects e2e",
     "test:contract": "npm run typecheck:tests && jest --selectProjects contract",
     "test:stack": "starci-test-stack",
-    "contract:emit": "hfs emit-contracts",
-    "hfs:check": "hfs check",
-    "hfs:report": "hfs check --sonar reports/hfs.sonar.json"
+    "contract:emit": "hfs emit-contracts"
   }
 }

package/templates/be/quality-config/sonar-project.properties

@@ -5,5 +5,5 @@ sonar.sources=apps,src
 sonar.tests=apps,src
 sonar.exclusions={{sonarExclusions}}
 sonar.test.inclusions=**/*.spec.ts
-sonar.externalIssuesReportPaths=reports/hfs.sonar.json,reports/eslint.sonar.json
+sonar.externalIssuesReportPaths=reports/lint.sonar.json
 sonar.nodejs.maxspace=8192

package/templates/fe/ci-workflows/github/workflows/ci.yml

@@ -21,22 +21,8 @@ jobs:
           node-version: {{nodeMajor}}
           cache: npm
       - run: npm ci
-      - name: hfs check
-        run: npm run hfs:report
       - name: lint
-        run: npm run lint:check
-      - name: eslint report
-        if: ${{ !cancelled() }}
-        run: npm run lint:report
-      - name: eslint sonar import
-        if: ${{ !cancelled() }}
-        run: npx hfs report eslint reports/eslint.json reports/eslint.sonar.json
-      - name: stylelint report
-        if: ${{ !cancelled() }}
-        run: npm run lint:report:css
-      - name: stylelint sonar import
-        if: ${{ !cancelled() }}
-        run: npx hfs report stylelint reports/stylelint.json reports/stylelint.sonar.json
+        run: npm run lint -- --sonar reports/lint.sonar.json
       - name: format
         run: npm run format:check
       - name: typecheck

package/templates/fe/hooks/husky/pre-push

@@ -1,6 +1,5 @@
 {{header}}
-# Push gate: types, lint (eslint over the repository, stylelint over the CSS), format, the architecture check on the owners this push touches.
+# Push gate: types, lint (eslint over the repository, stylelint over the CSS), format; one `hfs lint` runs eslint, the repository check and stylelint.
 npm run typecheck
-npm run lint:check
+npm run lint
 npm run format:check
-npm run hfs:check -- --fast

package/templates/fe/package-scripts/package.json

@@ -5,13 +5,9 @@
     "codegen": "npm run codegen --workspaces --if-present",
     "build": "npm run build --workspaces --if-present",
     "typecheck": "npm run typecheck --workspaces --if-present",
-    "lint": "npm run codegen --silent && eslint . --fix --max-warnings=0 && stylelint \"{{styleGlob}}\" --fix",
-    "lint:check": "npm run codegen --silent && eslint . --max-warnings=0 && stylelint \"{{styleGlob}}\"",
-    "lint:report": "eslint . --format json --output-file reports/eslint.json",
-    "lint:report:css": "stylelint \"{{styleGlob}}\" --formatter json --output-file reports/stylelint.json",
+    "lint": "npm run codegen --silent && hfs lint --stylelint \"{{styleGlob}}\"",
+    "lint:fix": "npm run codegen --silent && hfs lint --fix --stylelint \"{{styleGlob}}\"",
     "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "hfs:check": "hfs check",
-    "hfs:report": "hfs check --sonar reports/hfs.sonar.json"
+    "format:check": "prettier --check ."
   }
 }

package/templates/fe/quality-config/sonar-project.properties

@@ -4,5 +4,5 @@ sonar.sourceEncoding=UTF-8
 sonar.sources={{sonarRoots}}
 sonar.exclusions=**/.next/**,**/node_modules/**,**/src/messages/**
 sonar.typescript.tsconfigPaths={{tsconfigPaths}}
-sonar.externalIssuesReportPaths=reports/hfs.sonar.json,reports/eslint.sonar.json,reports/stylelint.sonar.json
+sonar.externalIssuesReportPaths=reports/lint.sonar.json
 sonar.nodejs.maxspace=8192

package/runtime/scripts/checks/architecture/size-growth.mjs

@@ -1,73 +0,0 @@
-import fs from 'node:fs';
-import { gitOutput } from '../../lib/git.mjs';
-
-/**
- * HFS check 6, file size growth (knowledge/hfs/slots.yaml ruleParams.<profile>.fileLines {soft, hardGrowth}):
- * a production source file over `soft` lines may not grow against the merge-base, and a file that is new at the base
- * must stay within `soft`. A file at or under `soft` passes, even when it grows, as long as it does not cross `soft`
- * (crossing is growth of an over-budget file: the base had fewer lines than soft). Files are compared to the base file
- * of the same path only, so a moved file is judged as new. The per-slot budgets (component 300, hook 200 ...) belong to
- * the lint layer and are not judged here.
- */
-export const SIZE_GROWTH_RULE_IDS = ['HFS_SIZE_GROWTH'];
-
-const MAX_BUFFER = 64 * 1024 * 1024;
-
-function git(root, args) {
-  try {
-    return gitOutput(args, { cwd: root, maxBuffer: MAX_BUFFER });
-  } catch {
-    return null;
-  }
-}
-
-/** The commit the growth is measured against: the given commit-ish, else merge-base with upstream, origin/main, origin/master, else HEAD's first parent. */
-function resolveBase(root, requested) {
-  const commit = (rev) => { const out = git(root, ['rev-parse', '--verify', '--quiet', `${rev}^{commit}`]); return out ? out.trim() : null; };
-  if (requested) return commit(requested);
-  if (!commit('HEAD')) return null;
-  for (const other of ['@{upstream}', 'origin/main', 'origin/master']) {
-    if (!commit(other)) continue;
-    const merged = git(root, ['merge-base', 'HEAD', other]);
-    if (merged?.trim()) return merged.trim();
-  }
-  return commit('HEAD^');
-}
-
-export function countLines(text) {
-  if (!text) return 0;
-  const count = text.split('\n').length;
-  return text.endsWith('\n') ? count - 1 : count;
-}
-
-export function checkSizeGrowth({ config, graph, base } = {}) {
-  const root = config.root;
-  const sha = resolveBase(root, base);
-  if (!sha) return { violations: [], coverage: { status: 'unavailable', reason: 'no merge-base' } };
-  const { soft, hardGrowth } = graph.resolver.ruleParams().fileLines;
-  const violations = [];
-  let files = 0;
-  let overSoft = 0;
-  let grown = 0;
-  let newOverSoft = 0;
-  for (const rel of [...graph.files.keys()].sort()) {
-    let text;
-    try { text = fs.readFileSync(graph.files.get(rel).abs, 'utf8'); } catch { continue; }
-    files += 1;
-    const lines = countLines(text);
-    if (lines <= soft) continue;
-    overSoft += 1;
-    const baseText = git(root, ['cat-file', 'blob', `${sha}:${rel}`]);
-    const baseLines = baseText === null ? null : countLines(baseText);
-    if (baseLines === null) {
-      newOverSoft += 1;
-      if (hardGrowth) violations.push({ ruleId: 'HFS_SIZE_GROWTH', path: rel, line: 1, lines, baseLines: null, soft,
-        message: `${rel} is a new file of ${lines} lines, over the ${soft}-line soft budget; split it into smaller files before adding it.` });
-    } else if (lines > baseLines) {
-      grown += 1;
-      if (hardGrowth) violations.push({ ruleId: 'HFS_SIZE_GROWTH', path: rel, line: 1, lines, baseLines, soft,
-        message: `${rel} has ${lines} lines, over the ${soft}-line soft budget, and grew from ${baseLines} lines at the base; a file over budget may only shrink, so split the new code into another file.` });
-    }
-  }
-  return { violations, coverage: { status: 'checked', base: sha, files, overSoft, grown, newOverSoft } };
-}