@starci/hfs 5.0.7 → 5.0.8

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

@@ -1,7 +1,8 @@
-// pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned `starci app lint`.
-//   .github/workflows/ci.yml   a `run:` step that runs the one lint entry: `starci app lint`,
-//                              `npx starci-harness[@<version>] app lint`, or `npm run <script>` whose command runs `starci app lint`
-//                              (`npm run lint`, arguments after `--` allowed); a version named in the step is the starci-harness pin,
+// pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned lint gate of `starci app check`.
+//   .github/workflows/ci.yml   a `run:` step that runs the lint gate: `starci app check --gate lint`,
+//                              `npx starci-harness[@<version>] app check --gate lint`, or `npm run <script>` whose command runs it
+//                              (`npm run lint`, arguments after `--` allowed);
+//                              a version named in the step is the starci-harness pin,
 //                              the version of the CLI that runs the check (canon-pins.mjs; an installed one is pinned by the pin check, R15)
 //   (the push hook is no lint or typecheck step: it checks the release gate, scripts/hfs/runtime-rules/hook-shape.mjs keeps its shape)
 // 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.
@@ -13,7 +14,8 @@ const CI_FILE = '.github/workflows/ci.yml';
 const hfsPackage = 'starci-harness';
 const RUN_PREFIX = /^\s*(?:-\s+)?run:/;
 const NPX_PREFIX = /^npx\s+(?:(?:--no-install|-y)\s+)?/;
-const LINT_COMMAND = /^(?:starci-harness(?:@(\S+))?|starci)\s+app\s+lint/;
+const LINT_COMMAND = /^(?:starci-harness(?:@(\S+))?|starci)\s+app\s+check/;
+const GATE_ARGUMENT = /(?:^|\s)--gate(?:=|\s+)(\S+)/g;
 const NPM_RUN_PREFIX = 'npm run ';
 const EXAMPLE_RUN_PREFIX = 'node node_modules/@starci/hfs/runtime/scripts/hfs/example-secrets.mjs --run . -- ';
 const SCRIPT_NAME = /^[\w:.-]+/;
@@ -56,7 +58,9 @@ function parseNpmRun(command) {
     const args = separator ? tail.slice(separator[0].length) : null;
     return args !== null && !LINE_TERMINATOR.test(args) ? { script, args } : null;
 }
-/** { version } of a `starci app lint` command (`version` undefined when no starci-harness version is named), else null. */
+/** Whether the arguments of an `app check` select the lint gate: `--gate lint` (or `--gate=lint`) among them. */
+const runsLintGate = (tail) => [...tail.matchAll(GATE_ARGUMENT)].some((gate) => gate[1] === 'lint');
+/** { version } of a `starci app check` command that runs the lint gate (`version` undefined when no starci-harness version is named), else null. */
 function lintCommandOf(command) {
     const rest = command.replace(NPX_PREFIX, '');
     const match = LINT_COMMAND.exec(rest);
@@ -65,7 +69,7 @@ function lintCommandOf(command) {
     const tail = rest.slice(match[0].length);
     if (tail && !(WHITESPACE.test(tail[0]) && !LINE_TERMINATOR.test(tail.slice(1))))
         return null;
-    return { version: match[1] };
+    return runsLintGate(tail) ? { version: match[1] } : null;
 }
 /** `npm run <script> -- <args>` spelled out as the root package.json script it runs; any other command is itself. */
 function expanded(command, scripts) {
@@ -87,9 +91,9 @@ export function pipelineFindings({ repoRoot, files, pins }) {
         const selected = isRuntimeExampleApp(repoRoot) ? commands.map(exampleCommandOf) : commands;
         const lints = selected.flatMap((command) => chainedCommands(expanded(command, scripts))).map(lintCommandOf).filter(Boolean);
         if (!lints.length)
-            findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`starci app lint\` (directly or through \`npm run lint\`); CI runs the one lint entry, which includes the repository check`, { step: 'starci app lint' }));
+            findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`starci app check --gate lint\` (directly or through \`npm run lint\`); CI runs the lint gate of the one app check`, { step: 'starci app check --gate lint' }));
         else if (pinned && !lints.some((match) => match.version === undefined || match.version === pinned)) {
-            findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs starci app lint at ${lints[0].version}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'starci app lint', pinned }));
+            findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs starci app check at ${lints[0].version}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'starci app check --gate lint', pinned }));
         }
     }
     return findings;

package/runtime/scripts/hfs/rules/read.d.mts

@@ -1,7 +1,12 @@
 import type { Finding, Parsed } from './rule-types.mjs';
+/** Who is told which file a rule reads: the result cache records the read set of a cross-file rule through it. */
+type ReadSink = (repoRoot: string, rel: string) => void;
+/** Runs `run` with every `readText` / `readJson` it makes reported to `onRead` (before the read), and returns its value. */
+export declare function recordReads<T>(onRead: ReadSink, run: () => T): T;
 /** The text of `rel` under `repoRoot`, or null when it is absent, unreadable, over MAX_READ_BYTES or binary. */
 export declare function readText(repoRoot: string, rel: string): string | null;
 /** The JSON of `rel`, or null when it is absent or not JSON. */
 export declare function readJson(repoRoot: string, rel: string): Parsed | null;
 /** One error finding of `code` on `file`; `extra` carries the finding's own fields. */
 export declare const found: (code: string, file: string, message: string, extra?: Record<string, unknown>) => Finding;
+export {};

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

@@ -3,8 +3,21 @@ 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). */
 const MAX_READ_BYTES = 1024 * 1024;
+let sink = null;
+/** Runs `run` with every `readText` / `readJson` it makes reported to `onRead` (before the read), and returns its value. */
+export function recordReads(onRead, run) {
+    const before = sink;
+    sink = onRead;
+    try {
+        return run();
+    }
+    finally {
+        sink = before;
+    }
+}
 /** The text of `rel` under `repoRoot`, or null when it is absent, unreadable, over MAX_READ_BYTES or binary. */
 export function readText(repoRoot, rel) {
+    sink?.(repoRoot, rel);
     try {
         const target = path.join(repoRoot, rel);
         if (fs.statSync(target).size > MAX_READ_BYTES)

package/runtime/scripts/hfs/rules/secrets.d.mts

@@ -17,6 +17,8 @@ export declare function secretFileFindings({ file, text, manifestText }: {
     text: string | null;
     manifestText?: string | null | undefined;
 }): import("./rule-types.mjs").Finding[];
+/** The application-stacks manifest beside a README (the one other file a README's secret findings read), in the README's own scope; null for any other file. */
+export declare const readmeManifestOf: (file: string) => string[] | null;
 /** The findings of R06 over `files` (tracked paths) of `repoRoot`; `resolver` names the slots. */
 export declare function secretFindings({ repoRoot, files, resolver }: {
     repoRoot: string;

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

@@ -51,6 +51,8 @@ export function secretFileFindings({ file, text, manifestText }) {
     }
     return findings;
 }
+/** The application-stacks manifest beside a README (the one other file a README's secret findings read), in the README's own scope; null for any other file. */
+export const readmeManifestOf = (file) => (/(?:^|\/)README\.md$/.test(file) ? [path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')] : null);
 /** The findings of R06 over `files` (tracked paths) of `repoRoot`; `resolver` names the slots. */
 export function secretFindings({ repoRoot, files, resolver }) {
     const findings = [];
@@ -61,7 +63,8 @@ export function secretFindings({ repoRoot, files, resolver }) {
             findings.push(found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret file tracked in ${slot.slot}${destination}`, { slot: slot.slot, goesTo: slot.goesTo }));
             continue;
         }
-        const manifestText = /(?:^|\/)README\.md$/.test(file) ? readText(repoRoot, path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) : undefined;
+        const manifestPath = readmeManifestOf(file)?.[0];
+        const manifestText = manifestPath === undefined ? undefined : readText(repoRoot, manifestPath);
         findings.push(...secretFileFindings({ file, text: readText(repoRoot, file), manifestText }));
     }
     return findings;

package/runtime/scripts/hfs/rules/stacks-release.mjs

@@ -6,6 +6,7 @@ import { loadTypescript } from '../../lib/package-at.mjs';
 import { walkSqlAst, sqlParser, sqlCallArgument } from '../../lib/sql-ast.mjs';
 import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
 import { found, readText } from './read.mjs';
+import { memoUnit } from '../rule-memo.mjs';
 import { stacksDeploymentContexts } from './stacks-runtime.mjs';
 // PostgreSQL initializes asynchronously, while HFS finders must stay synchronous.
 // Optional loading also lets dependency-free relocated development gates import this rule.
@@ -39,20 +40,26 @@ function safeRelative(relative) {
         return false;
     return relative.split('/').every((part) => part && part !== '.' && part !== '..');
 }
-function publicReference(repoRoot, files, relative) {
+/** `links` remembers which directories are symbolic links for the duration of one scan, so a directory shared by many files is asked once. */
+function publicReference(repoRoot, files, relative, links = new Map()) {
     if (!repoRoot || !safeRelative(relative))
         return false;
-    if (!files.includes(relative))
+    if (!(files instanceof Set ? files.has(relative) : files.includes(relative)))
         return false;
     const root = path.resolve(repoRoot), target = path.resolve(root, relative);
     try {
-        let cursor = target;
-        while (cursor !== root) {
-            if (fs.lstatSync(cursor).isSymbolicLink())
+        const stat = fs.lstatSync(target);
+        if (stat.isSymbolicLink())
+            return false;
+        for (let cursor = path.dirname(target); cursor !== root; cursor = path.dirname(cursor)) {
+            let link = links.get(cursor);
+            if (link === undefined) {
+                link = fs.lstatSync(cursor).isSymbolicLink();
+                links.set(cursor, link);
+            }
+            if (link)
                 return false;
-            cursor = path.dirname(cursor);
         }
-        const stat = fs.lstatSync(target);
         return stat.isFile() && stat.size > 0 && stat.size <= MAX_BYTES;
     }
     catch {
@@ -356,30 +363,37 @@ function templateObservations(node, file) {
         return [{ id: null, cadence: null, at: file }];
     return sqlObservations(named, file);
 }
-function recurringObservations({ doc, repoRoot, files, file, issues }) {
-    const sql = file.startsWith('db/migrations/') && file.endsWith('.sql') && !file.startsWith('db/migrations/archive/');
-    const sourceFile = SOURCE.test(file) && !TEST.test(file);
-    if ((!sql && !sourceFile) || !publicReference(repoRoot, files, file))
-        return [];
+function observationsOf({ doc, repoRoot, file, sql }) {
     const text = readText(repoRoot, file);
     if (text === null)
-        return [];
+        return { observations: [], issues: [] };
     if (sql)
-        return sqlObservations(text, file);
+        return { observations: sqlObservations(text, file), issues: [] };
     ts ??= loadTypescript(repoRoot, HERE);
-    if (!ts) {
-        issues.push(scheduleIssue(file, 'TypeScript is required to inspect recurring application work'));
-        return [];
-    }
+    if (!ts)
+        return { observations: [], issues: [scheduleIssue(file, 'TypeScript is required to inspect recurring application work')] };
     const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
-    issues.push(...sourceObservationIssues(doc, file, source, sourceBindings(source)));
-    return sourceSqlObservations(source, file);
+    const issues = sourceObservationIssues(doc, file, source, sourceBindings(source));
+    return { observations: sourceSqlObservations(source, file), issues };
+}
+function recurringObservations({ doc, repoRoot, files, file, issues, links, tools }) {
+    const sql = file.startsWith('db/migrations/') && file.endsWith('.sql') && !file.startsWith('db/migrations/archive/');
+    const sourceFile = SOURCE.test(file) && !TEST.test(file);
+    if ((!sql && !sourceFile) || !publicReference(repoRoot, files, file, links))
+        return [];
+    // The result cache keeps this per file: the bytes of the file, the manifest and the parsers decide it (contexts/project/check-cache.md).
+    const one = memoUnit(repoRoot, 'recurring-observations', file, `${tools}
+${JSON.stringify(doc)}`, { observations: [], issues: [] }, () => observationsOf({ doc, repoRoot, file, sql }));
+    issues.push(...one.issues);
+    return one.observations;
 }
 function recurringSourceIssues({ doc, repoRoot, files }) {
     const issues = [], cron = new Map();
     const paths = [...new Set(files)].sort((left, right) => left.localeCompare(right));
+    const tracked = new Set(paths), links = new Map();
+    const tools = `typescript=${loadTypescript(repoRoot, HERE) !== null} sql=${pg !== null}`;
     for (const file of paths) {
-        const observations = recurringObservations({ doc, repoRoot, files, file, issues });
+        const observations = recurringObservations({ doc, repoRoot, files: tracked, file, issues, links, tools });
         for (const observation of observations) {
             if ('remove' in observation) {
                 if (observation.remove)

package/runtime/scripts/lib/worktree-exclude.mjs

@@ -5,7 +5,7 @@
 //   <repo>/.starciwork/worktrees/<name>    one runtime scratch tree
 // The directory is git-excluded (.git/info/exclude), so `git status`,
 // `git ls-files --others --exclude-standard` and sonar never see it; every scanner that walks the filesystem
-// (canon-scan's eslint, starci app lint, the architecture walkers, input digests, proof-integrity, Work readers)
+// (canon-scan's eslint, starci app check, the architecture walkers, input digests, proof-integrity, Work readers)
 // skips it with isWorktreesPath / WORKTREES_IGNORE_GLOBS, or it would lint and hash every sibling worktree.
 import path from 'node:path';
 import { posixPath } from './path-key.mjs';

package/scaffold/app.mjs

@@ -21,7 +21,7 @@ import { HARNESS_PACKAGE, canonPins } from '../runtime/scripts/hfs/canon-pins.mj
 import { TEMPLATES_DIR, appSource, imageFiles, render, renderTargets, writeTargets } from '../sync/index.mjs';
 import { ScaffoldError } from './service.mjs';
 import { testWorldFiles } from './test-world.mjs';
-import { FE_APP_SCRIPTS, PACKAGE_MANAGER, WORKSPACES, WORKSPACE_LINT, feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
+import { FE_APP_SCRIPTS, PACKAGE_MANAGER, WORKSPACES, feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
 import { isLinkLike } from '../runtime/scripts/api/fs/is-link-like.mjs';
 import { unlinkOnly } from '../runtime/scripts/api/fs/lib.mjs';
 import { initializeAppIdentity } from '../runtime/scripts/hfs/secret-init.mjs';
@@ -200,8 +200,8 @@ const FE_PACKAGES = Object.freeze({
     ui: { exports: ['.'], dependencies: { '@heroui/react': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'react-aria-components': null, 'next-intl': null, react: null, 'react-dom': null } },
     i18n: { exports: ['.', './proxy', './routing'], dependencies: { next: null, 'next-intl': null, 'server-only': null } },
 });
-/** The scripts of every fe package workspace: tsc builds it to dist and type-checks it; it lints with the workspace lint. */
-const PACKAGE_WORKSPACE_SCRIPTS = Object.freeze({ build: 'tsc -p tsconfig.build.json', lint: WORKSPACE_LINT, typecheck: 'tsc --noEmit -p tsconfig.json' });
+/** The scripts of every fe package workspace: tsc builds it to dist and type-checks it. */
+const PACKAGE_WORKSPACE_SCRIPTS = Object.freeze({ build: 'tsc -p tsconfig.build.json', typecheck: 'tsc --noEmit -p tsconfig.json' });
 /** The app hfs.json of a new app called `name`; full remains the byte-for-byte default declaration. */
 export const starterDeclaration = (name, manifest = loadSlotManifest(), edition = 'full') => ({
     hfs: manifest.major,

package/src/check-cache-structure-support.d.mts

@@ -0,0 +1,52 @@
+import type { TestContext } from 'node:test';
+import { type PassResult } from '../cache/hfs-family.mjs';
+import type { CacheRecord } from '../cache/types.mjs';
+import type { MachineFn } from '../runtime/scripts/hfs/check.mjs';
+export declare const PORTABLE: {
+    parts: {
+        name: string;
+        sha256: string;
+    }[];
+    portable: boolean;
+    localReasons: never[];
+};
+/** An AWS access key shape the secret scan refuses (built from parts: the fixture is data, not a credential). */
+export declare const FAKE_KEY: string;
+/** The files of the fixture app; the untracked ones (generated code) are written after the commit. */
+export declare const FILES: Readonly<Record<string, string>>;
+/** The untracked, git-ignored generated code the fe program includes. */
+export declare const GENERATED = "fe/src/__generated__/graphql.ts";
+export declare function write(root: string, file: string, text: string): void;
+/** A temp git repository holding `files` (committed) and the generated input (not tracked). */
+export declare function appRepo(t: TestContext, files?: Readonly<Record<string, string>>): string;
+/** The architecture machine as a double that counts its runs per side (`calls`) and can act while it runs (`during`). */
+export declare function machineDouble(during?: (side: string) => void): {
+    machine: MachineFn;
+    calls: string[];
+};
+export interface RunOptions {
+    readonly hfs?: boolean;
+    readonly secrets?: boolean;
+    readonly during?: (side: string) => void;
+    readonly fingerprint?: typeof PORTABLE;
+    readonly tracked?: readonly string[];
+}
+/** One structure pass over `root` against the committed cache of the work tree; the session is flushed. */
+export declare function runPass(root: string, options?: RunOptions): Promise<{
+    pass: PassResult;
+    calls: string[];
+    hfs: readonly CacheRecord[];
+    secrets: readonly CacheRecord[];
+}>;
+/** `path\0step` to hash, for comparing which records a run rewrote. */
+export declare const hashes: (records: readonly CacheRecord[]) => Map<string, string>;
+/** The record keys whose hash differs between two runs, added or removed ones included. */
+export declare function changed(before: readonly CacheRecord[], after: readonly CacheRecord[]): string[];
+/** Every file-system access `run` makes under `root` (outside node_modules, which the lockfile in the fingerprint stands for), as `method path`. */
+export declare function recordFs<T>(root: string, run: () => T): {
+    value: T;
+    accessed: Set<string>;
+};
+export declare const filesOf: (accessed: Set<string>) => Set<string>;
+/** The fixture of the per-file rules: a secret, a bypass marker, a long source, a README beside a stack manifest and files that are clean. */
+export declare const RULE_FILES: Readonly<Record<string, string>>;

package/src/main.d.mts

@@ -49,10 +49,11 @@ interface AppIo {
 type MainOptions = {
     [K in keyof AppIo]?: AppIo[K] | undefined;
 };
+/** An argument the parser refuses (an unknown flag, a missing value, a form a verb does not take): the one error `main` follows with the usage. */
+export declare class UsageError extends Error {
+}
 export declare const VERBS: readonly string[];
 export declare const USAGE: string;
-/** The nearest folder at or above `dir` that holds hfs.json (the app root of a workspace), or `dir` itself when none does (the lint then refuses it). */
-export declare function appRootAbove(dir: string): string;
 /**
  * `harness` ({ version }) is the CLI that runs this package in-process: its version is the starci-harness an app is judged and
  * scaffolded at (runtime/scripts/hfs/canon-pins.mjs). `run` injects the database runner, `runLinter` the linter transport, `checkApp`