@starci/hfs 5.0.7 → 5.1.0

package/runtime/scripts/hfs/rule-memo.d.mts

@@ -0,0 +1,30 @@
+import type { CheckFinding } from './check.mjs';
+/** A rule whose findings for one file depend on that file alone (and the files `deps` names), so the cache reuses them per file. */
+export interface FileRule {
+    /** Names the rule in its record and in the spec that proves its declaration. */
+    readonly id: string;
+    /** The findings over `files` (scope-relative tracked paths); every finding's `path` is one of `files`. */
+    run(files: string[]): CheckFinding[];
+    /** Other scope-relative files whose content the findings for `file` read. */
+    deps?(file: string): string[];
+}
+/** What the cache gives the rule runner. */
+export interface RuleMemo {
+    /** The findings of `rules` over the tracked `files` of the scope at `scopeRoot` (absolute), reusing what the cache holds per file. */
+    files(scopeRoot: string, files: readonly string[], rules: readonly FileRule[]): CheckFinding[];
+    /** The findings of the cross-file rule `id` of the scope at `scopeRoot`, reused while every file it read and the tracked path list are unchanged. */
+    keyed(scopeRoot: string, id: string, run: () => CheckFinding[]): CheckFinding[];
+    /**
+     * The value `compute` yields for `file` (scope-relative) of the scope at `scopeRoot`, reused while the file's bytes and `extra` (every other input the value
+     * depends on, as text) are unchanged. `compute` reads only that file; the value is plain JSON; `empty` is the value a file with nothing to say yields.
+     */
+    unit<T>(scopeRoot: string, id: string, file: string, extra: string, empty: T, compute: () => T): T;
+}
+/** Runs `run` with `memo` serving the per-file and cross-file rules of every checkRepo inside it. */
+export declare function withRuleMemo<T>(memo: RuleMemo, run: () => T): T;
+/** The findings of per-file `rules` over `files`, from the cache when one is installed. Rules run in order, each over the files it must judge. */
+export declare function memoFiles(scopeRoot: string, files: readonly string[], rules: readonly FileRule[]): CheckFinding[];
+/** The value of a per-file unit of a cross-file rule, from the cache when one is installed (see `RuleMemo.unit`). */
+export declare function memoUnit<T>(scopeRoot: string, id: string, file: string, extra: string, empty: T, compute: () => T): T;
+/** The findings of a cross-file rule, from the cache when one is installed. */
+export declare function memoKeyed(scopeRoot: string, id: string, run: () => CheckFinding[]): CheckFinding[];

package/runtime/scripts/hfs/rule-memo.mjs

@@ -0,0 +1,24 @@
+let active = null;
+/** Runs `run` with `memo` serving the per-file and cross-file rules of every checkRepo inside it. */
+export function withRuleMemo(memo, run) {
+    const before = active;
+    active = memo;
+    try {
+        return run();
+    }
+    finally {
+        active = before;
+    }
+}
+/** The findings of per-file `rules` over `files`, from the cache when one is installed. Rules run in order, each over the files it must judge. */
+export function memoFiles(scopeRoot, files, rules) {
+    return active ? active.files(scopeRoot, files, rules) : rules.flatMap((rule) => rule.run([...files]));
+}
+/** The value of a per-file unit of a cross-file rule, from the cache when one is installed (see `RuleMemo.unit`). */
+export function memoUnit(scopeRoot, id, file, extra, empty, compute) {
+    return active ? active.unit(scopeRoot, id, file, extra, empty, compute) : compute();
+}
+/** The findings of a cross-file rule, from the cache when one is installed. */
+export function memoKeyed(scopeRoot, id, run) {
+    return active ? active.keyed(scopeRoot, id, run) : run();
+}

package/runtime/scripts/hfs/rules/a15-findings.d.mts

@@ -14,5 +14,11 @@ import type { Parsed } from './rule-types.mjs';
 /** The failure codes the finders above emit, so `starci app check` ships their labels (check.mjs adds them to CHECK_CODES). Append-only; the coordinator regenerates it at merge time. */
 export declare const A15_CODES: string[];
 export declare const FINDERS: (typeof feBuildArgsFindings | typeof featureFileFindings | typeof assetsFindings | typeof unusedSymbolFindings | typeof databaseBaselineFindings | typeof databaseConfigFindings | typeof docFreshFindings | typeof releaseProvenanceFindings | typeof secretCustodyOnlyFindings | typeof scriptHygieneFindings | typeof supplyChainFindings | typeof liteProofLaneFindings)[];
+/**
+ * The finders the result cache keeps by the files they read: each reads the tracked tree only through `readText` / `readJson` (rules/read.mts) and the tracked
+ * path lists it is given, so its findings are a function of those. `check-cache-structure-rules.spec.mts` proves every member under a file-system recorder
+ * and fails on a read it does not go through the gateway. A finder that stats, lists or walks the work tree (stacks-release, the stacks gate) is not a member.
+ */
+export declare const KEYED_FINDERS: ReadonlySet<(context: Parsed) => Parsed>;
 /** Findings of every alpha.15 content rule over one repository. */
 export declare function a15Findings(context: Parsed): any[];

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -38,6 +38,7 @@ import { ciCustodyFindings } from './ci-custody.mjs';
 import { workflowContextsFindings } from './workflow-contexts.mjs';
 import { ciStandardAppFindings } from './ci-standard.mjs';
 import { feBuildArgsFindings } from './fe-build-args.mjs';
+import { memoKeyed } from '../rule-memo.mjs';
 // finders-import-end
 /** The failure codes the finders above emit, so `starci app check` ships their labels (check.mjs adds them to CHECK_CODES). Append-only; the coordinator regenerates it at merge time. */
 export const A15_CODES = [
@@ -90,15 +91,23 @@ export const FINDERS = [
     ciCustodyFindings,
     // finders-end
 ];
+/**
+ * The finders the result cache keeps by the files they read: each reads the tracked tree only through `readText` / `readJson` (rules/read.mts) and the tracked
+ * path lists it is given, so its findings are a function of those. `check-cache-structure-rules.spec.mts` proves every member under a file-system recorder
+ * and fails on a read it does not go through the gateway. A finder that stats, lists or walks the work tree (stacks-release, the stacks gate) is not a member.
+ */
+export const KEYED_FINDERS = new Set([docFreshFindings, scriptHygieneFindings, databaseConfigFindings, feBuildArgsFindings]);
 /** Findings of every alpha.15 content rule over one repository. */
 export function a15Findings(context) {
     // `starci app check` always passes the full context; a partial one (a finder spec driving the registry with only the fields its rule reads) must not crash the finders of other rules.
     const full = Boolean(context.repoRoot && context.repo && context.resolver && context.manifest);
     return FINDERS.flatMap((finder) => {
+        const run = () => finder(context);
+        const once = KEYED_FINDERS.has(finder) && full ? () => memoKeyed(context.repoRoot, finder.name, run) : run;
         if (full)
-            return finder(context);
+            return once();
         try {
-            return finder(context);
+            return once();
         }
         catch {
             return [];

package/runtime/scripts/hfs/rules/ci-standard.mjs

@@ -149,7 +149,7 @@ function fullHistory(doc, say) {
     for (const [id, job] of jobsOf(doc)) {
         const steps = stepsOf(job);
         const base = steps.findIndex((step) => /STARCI_BASE_REF=.*>>\s*"?\$GITHUB_ENV"?/.test(runOf(step)));
-        const lint = steps.findIndex((step) => /\bnpm run lint\b|\bstarci app lint\b/.test(runOf(step)));
+        const lint = steps.findIndex((step) => /\bnpm run lint\b|\bapp check\b[^\n]*--gate[ =]lint\b/.test(runOf(step)));
         if (lint >= 0 && (base < 0 || base > lint))
             out.push(say('full-history-base-ref', `job ${id} must write STARCI_BASE_REF to GITHUB_ENV before its first lint step`));
     }
@@ -174,7 +174,7 @@ function sonarLintPerSide(doc, say) {
     for (const [id, job] of jobsOf(doc)) {
         for (const step of stepsOf(job)) {
             const run = runOf(step);
-            if (/\b(?:npm run lint|starci(?:\.mjs)?["']?\s+app lint|app lint)\b/.test(run) && /\s--out\b/.test(run) && !/\s--side\s+(?:be\b|fe\b|\$\{\{\s*matrix\.side\s*\}\})/.test(run)) {
+            if (/\b(?:npm run lint|app check)\b/.test(run) && /\s--out\b/.test(run) && !/\s--side\s+(?:be\b|fe\b|\$\{\{\s*matrix\.side\s*\}\})/.test(run)) {
                 out.push(say('sonar-lint-per-side', `job ${id}, step ${step.name ?? 'lint'}: a lint with a Sonar import must name its side (--side be|fe) and the reports are merged afterwards; a combined lint with Sonar breaks the standard`));
             }
         }

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

@@ -1,9 +1,7 @@
 import type { Parsed, Repo } from './rule-types.mjs';
 /** The npm workspaces of every app, in this order. */
 export declare const WORKSPACES: readonly string[];
-/** The lint script of every fe workspace: the one lint of the app, scoped to the workspace. */
-export declare const WORKSPACE_LINT = "starci app lint --workspace .";
-/** The scripts of every fe app workspace, exactly: turbo runs build, dev, lint and typecheck; start serves a build. */
+/** The scripts of every fe app workspace, exactly: turbo runs build, dev and typecheck; start serves a build. The lint is the root's (`starci app check --gate lint`), never a workspace script. */
 export declare const FE_APP_SCRIPTS: Readonly<Record<string, string>>;
 /** The package manager every app root declares (turbo reads it to parse the lockfile); the starci app scaffold writes it. */
 export declare const PACKAGE_MANAGER = "npm@11.6.2";

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

@@ -22,12 +22,10 @@ const MONO_NEST_PROJECTS = 'HFS_MONO_NEST_PROJECTS';
 const MONO_WORKSPACE_DEP = 'HFS_MONO_WORKSPACE_DEP';
 /** The npm workspaces of every app, in this order. */
 export const WORKSPACES = Object.freeze(['fe/apps/*', 'fe/packages/*']);
-/** The lint script of every fe workspace: the one lint of the app, scoped to the workspace. */
-export const WORKSPACE_LINT = 'starci app lint --workspace .';
-/** The scripts of every fe app workspace, exactly: turbo runs build, dev, lint and typecheck; start serves a build. */
-export const FE_APP_SCRIPTS = Object.freeze({ build: 'next build', dev: 'next dev', lint: WORKSPACE_LINT, start: 'next start', typecheck: 'tsc --noEmit' });
-/** The scripts every fe package workspace has (its build and typecheck commands are its own; its lint is the workspace lint). */
-const FE_PACKAGE_SCRIPTS = Object.freeze(['build', 'typecheck', 'lint']);
+/** The scripts of every fe app workspace, exactly: turbo runs build, dev and typecheck; start serves a build. The lint is the root's (`starci app check --gate lint`), never a workspace script. */
+export const FE_APP_SCRIPTS = Object.freeze({ build: 'next build', dev: 'next dev', start: 'next start', typecheck: 'tsc --noEmit' });
+/** The scripts every fe package workspace has (its build and typecheck commands are its own); it has no lint script. */
+const FE_PACKAGE_SCRIPTS = Object.freeze(['build', 'typecheck']);
 /** The package manager every app root declares (turbo reads it to parse the lockfile); the starci app scaffold writes it. */
 export const PACKAGE_MANAGER = 'npm@11.6.2';
 /** The npm name of an fe app workspace. */
@@ -61,7 +59,7 @@ function rootFindings(repoRoot) {
     if (!PACKAGE_MANAGER_FORM.test(String(pkg.packageManager ?? '')))
         findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares packageManager ${JSON.stringify(pkg.packageManager ?? null)}; turbo needs \`npm@<exact version>\` there.`, { packageManager: pkg.packageManager ?? null }));
     if (typeof pkg.devDependencies?.turbo !== 'string')
-        findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} does not declare turbo in its devDependencies; the turbo task graph (turbo.json) runs build, dev, lint and typecheck over the fe workspaces.`, { missing: 'turbo' }));
+        findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} does not declare turbo in its devDependencies; the turbo task graph (turbo.json) runs build, dev and typecheck over the fe workspaces.`, { missing: 'turbo' }));
     return findings;
 }
 /** R144: the manifest of each fe workspace. */
@@ -73,16 +71,16 @@ function appWorkspaceScriptFindings(file, project, name, pkg, scripts) {
     const want = Object.keys(FE_APP_SCRIPTS).sort(byCodeUnit);
     const off = [...new Set([...want, ...Object.keys(scripts)])].sort(byCodeUnit).filter((key) => scripts[key] !== FE_APP_SCRIPTS[key]);
     if (off.length)
-        findings.push(found(MONO_FE_WORKSPACE, file, `${file} has scripts ${JSON.stringify(scripts)}; an fe app workspace has exactly ${JSON.stringify(FE_APP_SCRIPTS)} (turbo runs build, dev, lint and typecheck; differs at ${off.join(', ')}).`, { scripts: off }));
+        findings.push(found(MONO_FE_WORKSPACE, file, `${file} has scripts ${JSON.stringify(scripts)}; an fe app workspace has exactly ${JSON.stringify(FE_APP_SCRIPTS)} (turbo runs build, dev and typecheck; the lint is the root's, \`starci app check --gate lint\`; differs at ${off.join(', ')}).`, { scripts: off }));
     return findings;
 }
 function packageWorkspaceScriptFindings(file, scripts) {
     const findings = [];
     const missing = FE_PACKAGE_SCRIPTS.filter((key) => typeof scripts[key] !== 'string' || !scripts[key]);
     if (missing.length)
-        findings.push(found(MONO_FE_WORKSPACE, file, `${file} has no ${missing.join(', ')} script; an fe package workspace builds, type-checks and lints (turbo builds it before the apps that import it).`, { scripts: missing }));
-    else if (scripts.lint !== WORKSPACE_LINT)
-        findings.push(found(MONO_FE_WORKSPACE, file, `${file} lints with ${JSON.stringify(scripts.lint)}; a workspace lints with ${JSON.stringify(WORKSPACE_LINT)}, the one lint of the app scoped to it.`, { scripts: ['lint'] }));
+        findings.push(found(MONO_FE_WORKSPACE, file, `${file} has no ${missing.join(', ')} script; an fe package workspace builds and type-checks (turbo builds it before the apps that import it).`, { scripts: missing }));
+    if (scripts.lint !== undefined)
+        findings.push(found(MONO_FE_WORKSPACE, file, `${file} has a lint script; a workspace has none, the app is linted once from the root with \`starci app check --gate lint\`.`, { scripts: ['lint'] }));
     return findings;
 }
 function workspaceManifestFindings(repoRoot, project, workspaces) {

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/declaration-surface.d.mts

@@ -0,0 +1,35 @@
+import type { TypeScript } from './ts-ast.mjs';
+/** What the declaration emit cannot write without reading other files, and where: one export (or one part of it) the author must annotate. */
+export interface SurfaceProblem {
+    /** The TypeScript diagnostic code (9007: function without a return type, 9010: variable without a type, ...). */
+    code: number;
+    /** The offset and length of the offending span in the file's text. */
+    start: number;
+    length: number;
+    /** The name of the export (or member) the span sits in, or `default export`. */
+    name: string;
+    /** What to annotate: `return type`, `variable type`, `parameter type`, `property type`, `accessor type`, `destructured export` or `exported value`. */
+    annotate: string;
+    /** TypeScript's own reason, one sentence. */
+    reason: string;
+}
+/** The declaration emit of one file: its text (the digest of the type surface) and the exports it could not write explicitly. */
+export interface DeclarationSurface {
+    outputText: string;
+    problems: SurfaceProblem[];
+}
+/** A script file (`.js`, `.mjs`, `.cjs`, `.jsx`): it has no declaration emit and stands for its content. */
+export declare const SCRIPT: RegExp;
+/** A declaration file: it is its own surface. */
+export declare const DECLARATION: RegExp;
+/** A TypeScript source file whose surface the declaration emit writes. */
+export declare const TYPESCRIPT: RegExp;
+/** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
+export declare const isEmittableSource: (file: string) => boolean;
+/**
+ * The declaration emit of one TypeScript source and the exports it could not write explicitly (a type inferred from bodies and other files), or null
+ * when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the
+ * surface its emit shows. `module` is the side's `module` compiler option, which the emit reads. A throw from the compiler propagates: the caller
+ * decides what an unreadable file means.
+ */
+export declare function declarationSurface(ts: TypeScript, file: string, text: string, module?: number): DeclarationSurface | null;

package/runtime/scripts/lib/declaration-surface.mjs

@@ -0,0 +1,112 @@
+/** A script file (`.js`, `.mjs`, `.cjs`, `.jsx`): it has no declaration emit and stands for its content. */
+export const SCRIPT = /\.(?:[cm]?jsx?)$/;
+/** A declaration file: it is its own surface. */
+export const DECLARATION = /\.d\.[cm]?ts$/;
+/** A TypeScript source file whose surface the declaration emit writes. */
+export const TYPESCRIPT = /\.(?:[cm]?tsx?)$/;
+/** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
+export const isEmittableSource = (file) => TYPESCRIPT.test(file) && !DECLARATION.test(file);
+/** Whether `expression` is a JSX element, fragment, `null` or `undefined`, or a conditional of those: its type does not depend on any other file. */
+function isJsxValue(ts, expression) {
+    if (expression === undefined)
+        return false;
+    let node = expression;
+    while (ts.isParenthesizedExpression(node))
+        node = node.expression;
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node) || node.kind === ts.SyntaxKind.NullKeyword)
+        return true;
+    if (ts.isIdentifier(node))
+        return node.text === 'undefined';
+    return ts.isConditionalExpression(node) && isJsxValue(ts, node.whenTrue) && isJsxValue(ts, node.whenFalse);
+}
+/**
+ * Whether the function (or method) the declaration diagnostic at `start` points at has the type `JSX.Element | null | undefined` whatever its body
+ * reads: not async, not a generator, and every `return` of its own (and its concise body) a JSX value. A React component written without a return
+ * type is the common case; its inferred type is one the JSX namespace of the installed packages gives, which a lockfile change dirties as a whole.
+ */
+function returnsOnlyJsx(ts, source, start) {
+    let found;
+    const find = (node) => {
+        if (found !== undefined || start < node.getFullStart() || start >= node.end)
+            return;
+        const named = (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name !== undefined && node.name.getStart(source) === start;
+        if (named || ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.getStart(source) === start)) {
+            found = node;
+            return;
+        }
+        ts.forEachChild(node, find);
+    };
+    find(source);
+    const fn = found;
+    if (fn === undefined || fn.type !== undefined || fn.body === undefined)
+        return false;
+    if (fn.asteriskToken !== undefined || (ts.getCombinedModifierFlags(fn) & ts.ModifierFlags.Async) !== 0)
+        return false;
+    if (!ts.isBlock(fn.body))
+        return isJsxValue(ts, fn.body);
+    let only = true;
+    const visit = (node) => {
+        if (!only || ts.isFunctionLike(node) || ts.isClassLike(node))
+            return;
+        if (ts.isReturnStatement(node) && node.expression !== undefined && !isJsxValue(ts, node.expression))
+            only = false;
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(fn.body, visit);
+    return only;
+}
+/** What to annotate for each isolated-declaration diagnostic code; any other code asks for the exported value's type. */
+const ANNOTATE = new Map([
+    [9007, 'return type'], [9008, 'return type'], [9009, 'accessor type'], [9010, 'variable type'], [9011, 'parameter type'], [9012, 'property type'],
+    [9019, 'destructured export'], [9025, 'parameter type'],
+]);
+/** The declaration kinds whose name labels the export a diagnostic sits in, innermost first. */
+function nameOf(ts, source, start) {
+    let innermost = source;
+    const descend = (node) => {
+        if (start < node.getFullStart() || start >= node.end)
+            return;
+        innermost = node;
+        ts.forEachChild(node, descend);
+    };
+    ts.forEachChild(source, descend);
+    for (let node = innermost; node !== undefined && node !== source; node = node.parent) {
+        if (ts.isExportAssignment(node))
+            return 'default export';
+        if (ts.isBindingElement(node) && ts.isIdentifier(node.name))
+            return node.name.text;
+        if ((ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isPropertyAssignment(node) || ts.isGetAccessorDeclaration(node)) && node.name !== undefined && ts.isIdentifier(node.name))
+            return node.name.text;
+        if (ts.isFunctionDeclaration(node) && (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Default) !== 0)
+            return 'default export';
+    }
+    return 'default export';
+}
+/**
+ * The declaration emit of one TypeScript source and the exports it could not write explicitly (a type inferred from bodies and other files), or null
+ * when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the
+ * surface its emit shows. `module` is the side's `module` compiler option, which the emit reads. A throw from the compiler propagates: the caller
+ * decides what an unreadable file means.
+ */
+export function declarationSurface(ts, file, text, module) {
+    const emit = ts.transpileDeclaration;
+    if (emit === undefined)
+        return null;
+    const declared = emit.call(ts, text, { compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, ...(module === undefined ? {} : { module }) }, fileName: file, reportDiagnostics: true });
+    const diagnostics = (declared.diagnostics ?? []);
+    if (diagnostics.length === 0)
+        return { outputText: declared.outputText, problems: [] };
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const problems = [];
+    for (const diagnostic of diagnostics) {
+        const exempt = (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start);
+        if (exempt)
+            continue;
+        const start = diagnostic.start ?? 0;
+        problems.push({
+            code: diagnostic.code, start, length: diagnostic.length ?? 0, name: nameOf(ts, source, start), annotate: ANNOTATE.get(diagnostic.code) ?? 'exported value',
+            reason: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0] ?? '',
+        });
+    }
+    return { outputText: declared.outputText, problems };
+}

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,