@starci/hfs 5.0.7 → 5.1.0

package/cache/lint-family.mjs

@@ -138,17 +138,46 @@ const isFile = (file) => {
         return false;
     }
 };
+const isDirectory = (folder) => {
+    try {
+        return fs.statSync(folder).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * What the import graph reads of the disk, remembered for the build: a side's thousands of files probe the same few hundred folders and
+ * candidate paths while resolving their imports, and the tree does not change while the graph is built.
+ */
+function graphHost(ts, sideRoot, hashOf) {
+    const files = new Map(), folders = new Map();
+    const remembered = (known, ask) => (path) => {
+        let answer = known.get(path);
+        if (answer === undefined) {
+            answer = ask(path);
+            known.set(path, answer);
+        }
+        return answer;
+    };
+    return { ts, sideRoot, readText, fileExists: remembered(files, isFile), directoryExists: remembered(folders, isDirectory), hashOf };
+}
 /** A record's `data` object, or an empty one. */
 const dataOf = (record) => (record.data !== null && typeof record.data === 'object' && !Array.isArray(record.data) ? record.data : {});
-/** The graph findings of every canon that publishes graph rules, merged by file and sorted. */
-function mergedSnapshot(sideRoot, canons) {
+/**
+ * The graph findings of every canon that publishes graph rules, merged by file and sorted. A canon whose snapshot the ESLint child handed out (`handed`, by
+ * canon name) is not asked to build its graph again; any other canon builds it through its `projectGraph`.
+ */
+export function mergedSnapshot(sideRoot, canons, handed) {
     const merged = {};
     for (const canon of canons) {
         if (!canon.graphRules)
             continue;
-        if (canon.projectGraph === null)
+        const given = handed?.[canon.name];
+        if (given === undefined && canon.projectGraph === null)
             return null;
-        for (const [file, findings] of Object.entries(canon.projectGraph({ repoRoot: sideRoot }).byFile))
+        const { byFile } = given ?? canon.projectGraph({ repoRoot: sideRoot });
+        for (const [file, findings] of Object.entries(byFile))
             merged[posix(file)] = [...(merged[posix(file)] ?? []), ...findings];
     }
     for (const list of Object.values(merged))
@@ -162,7 +191,6 @@ const graphRecordFindings = (side, file, findings) => sortFindings(findings.map(
  */
 export async function lintSide(input) {
     const { session, side, sideRoot, scope, stylesheets } = input;
-    const inReport = input.report ?? (() => true);
     const scopeSet = new Set(scope);
     const styleSet = new Set(stylesheets);
     const folder = `lint/${side}`;
@@ -189,7 +217,7 @@ export async function lintSide(input) {
     const validStyle = new Map(reconcile(ofStep(LINT_STEPS.stylelint), hashOf).map((record) => [record.path, record]));
     const meta = ofStep(LINT_STEPS.meta).find((record) => record.path === SIDE_RECORD);
     const metaData = meta === undefined ? {} : dataOf(meta);
-    const previousFindings = new Set([...ofStep(LINT_STEPS.eslint), ...ofStep(LINT_STEPS.stylelint)].filter((record) => inReport(record.path)).flatMap((record) => record.findings.map(keyOf)));
+    const previousFindings = new Set([...ofStep(LINT_STEPS.eslint), ...ofStep(LINT_STEPS.stylelint)].flatMap((record) => record.findings.map(keyOf)));
     const progress = session.progress.step('lint', `lint ${side}`, scope.length + stylesheets.length);
     // ------------------------------------------------------------------ the plan
     let whole = input.full;
@@ -242,10 +270,10 @@ export async function lintSide(input) {
                     const imports = Array.isArray(data['imports']) ? data['imports'].filter((value) => typeof value === 'string') : [];
                     const kept = previous.get(record.path);
                     if (kept === undefined || record.hash === hashOf(record.path))
-                        previous.set(record.path, { hash: record.hash, imports, declaresGlobals: data['globals'] === true });
+                        previous.set(record.path, { hash: record.hash, imports, declaresGlobals: data['globals'] === true, api: typeof data['api'] === 'string' ? data['api'] : undefined, open: typeof data['open'] === 'boolean' ? data['open'] : undefined, refs: Array.isArray(data['refs']) ? data['refs'].filter((value) => typeof value === 'string') : undefined });
                 }
                 const recordedGraph = previous.size === 0 ? null : previous;
-                build = buildImportGraph({ ts, sideRoot, readText, fileExists: isFile, hashOf: (file) => hashOf(file) ?? null }, scope, recordedGraph, { pathsChanged: metaData['paths'] !== pathsDigest });
+                build = buildImportGraph(graphHost(ts, sideRoot, (file) => hashOf(file) ?? null), scope, recordedGraph, { pathsChanged: metaData['paths'] !== pathsDigest });
                 const dirty = dirtySetOf(recordedGraph, build.graph);
                 if (dirty.wholeSide !== null)
                     whole = dirty.wholeSide;
@@ -306,14 +334,16 @@ export async function lintSide(input) {
         dirtyStyle = new Set(stylesheets);
     }
     // ------------------------------------------------------------------ the run
-    const eslintList = [...dirtyEslint].filter(inReport).sort();
-    const styleList = [...dirtyStyle].filter(inReport).sort();
+    const eslintList = [...dirtyEslint].sort();
+    const styleList = [...dirtyStyle].sort();
+    let handedGraph;
     const freshEslint = new Map();
     const freshStyle = new Map();
     const rootOf = (file) => path.relative(sideRoot, file).replace(/\\/g, '/');
     if (eslintList.length > 0) {
         const run = await input.eslint(whole !== null ? null : eslintList);
         errors.push(...run.errors);
+        handedGraph = run.graph;
         for (const result of run.results)
             freshEslint.set(posix(rootOf(result.filePath)), result);
     }
@@ -331,8 +361,6 @@ export async function lintSide(input) {
     const styleRecords = [];
     const planHash = (file) => hashOf(file) ?? 'absent';
     for (const file of scope) {
-        if (!inReport(file))
-            continue;
         const fresh = freshEslint.get(file);
         const reuse = fresh === undefined ? validEslint.get(file) : undefined;
         if (fresh !== undefined) {
@@ -349,8 +377,6 @@ export async function lintSide(input) {
         }
     }
     for (const file of stylesheets) {
-        if (!inReport(file))
-            continue;
         const fresh = freshStyle.get(file);
         const reuse = fresh === undefined ? validStyle.get(file) : undefined;
         if (fresh !== undefined) {
@@ -367,38 +393,40 @@ export async function lintSide(input) {
         }
     }
     const checked = freshEslint.size + freshStyle.size;
-    const units = [...scope, ...stylesheets].filter(inReport).length;
+    const units = scope.length + stylesheets.length;
     const reused = Math.max(0, units - checked);
     progress.tick(units, reused, checked);
     progress.end();
     // ------------------------------------------------------------------ the records
     let written = false;
-    const complete = errors.length === 0 && input.write && input.report === null && !sideUnchanged;
+    const complete = errors.length === 0 && input.write && !sideUnchanged;
     if (complete) {
-        const stable = [...freshEslint.keys(), ...freshStyle.keys()].every((file) => hashFile(abs(file)) === hashOf(file));
-        if (stable) {
-            const records = [...eslintRecords, ...styleRecords];
-            // without an import graph or a project graph the next run lints the side whole; the results themselves are still stored
-            try {
-                if (build === null) {
-                    const ts = input.typescript();
-                    build = buildImportGraph({ ts, sideRoot, readText, fileExists: isFile, hashOf: (file) => hashOf(file) ?? null }, scope, null);
-                }
-                for (const [file, node] of build.graph)
-                    records.push({ path: file, step: LINT_STEPS.imports, hash: node.hash, findings: [], data: { globals: node.declaresGlobals, imports: node.imports } });
-                snapshot ??= mergedSnapshot(sideRoot, input.canons);
-                for (const [file, findings] of Object.entries(snapshot ?? {})) {
-                    if (scopeSet.has(file) && findings.length > 0)
-                        records.push({ path: file, step: LINT_STEPS.graph, hash: planHash(file), findings: graphRecordFindings(side, file, findings) });
-                }
+        // A file edited while the run read it gets no record of any step, and the others keep theirs: their hashes are those of the tree the run
+        // planned from, so the edited file is then added (no recorded graph entry) and its dependents are judged again, whatever they read of it.
+        const moved = new Set([...freshEslint.keys(), ...freshStyle.keys()].filter((file) => hashFile(abs(file)) !== hashOf(file)));
+        const records = [...eslintRecords, ...styleRecords].filter((record) => !moved.has(record.path));
+        // without an import graph or a project graph the next run lints the side whole; the results themselves are still stored
+        try {
+            if (build === null) {
+                const ts = input.typescript();
+                build = buildImportGraph(graphHost(ts, sideRoot, (file) => hashOf(file) ?? null), scope, null);
             }
-            catch {
-                records.splice(0, records.length, ...records.filter((record) => record.step === LINT_STEPS.eslint || record.step === LINT_STEPS.stylelint));
+            for (const [file, node] of build.graph) {
+                if (!moved.has(file))
+                    records.push({ path: file, step: LINT_STEPS.imports, hash: node.hash, findings: [], data: { globals: node.declaresGlobals, imports: node.imports, ...(node.api === undefined ? {} : { api: node.api }), open: node.open !== false, ...(node.refs === undefined ? {} : { refs: node.refs }) } });
             }
-            records.push({ path: SIDE_RECORD, step: LINT_STEPS.meta, hash: sideKey, findings: [], data: { extra: input.extraKey, files: scope.length, paths: pathsDigest, stylesheets: stylesheets.length } });
-            session.replace(folder, records);
-            written = true;
+            snapshot ??= mergedSnapshot(sideRoot, input.canons, handedGraph);
+            for (const [file, findings] of Object.entries(snapshot ?? {})) {
+                if (scopeSet.has(file) && !moved.has(file) && findings.length > 0)
+                    records.push({ path: file, step: LINT_STEPS.graph, hash: planHash(file), findings: graphRecordFindings(side, file, findings) });
+            }
+        }
+        catch {
+            records.splice(0, records.length, ...records.filter((record) => record.step === LINT_STEPS.eslint || record.step === LINT_STEPS.stylelint));
         }
+        records.push({ path: SIDE_RECORD, step: LINT_STEPS.meta, hash: sideKey, findings: [], data: { extra: input.extraKey, files: scope.length, paths: pathsDigest, stylesheets: stylesheets.length } });
+        session.replace(folder, records);
+        written = true;
     }
     const currentKeys = new Set(current.map(keyOf));
     let knownFindings = 0;

package/cache/records.d.mts

@@ -4,9 +4,15 @@ export declare class RecordSet {
     constructor(initial?: readonly CacheRecord[]);
     /** The record of (path, step) whose hash is `hash`, else undefined: a record of other content is no answer. */
     matching(path: string, step: string, hash: string): CacheRecord | undefined;
+    /** The record of (path, step) whatever its hash, for a step that validates the record's own inputs. */
+    get(path: string, step: string): CacheRecord | undefined;
     put(record: CacheRecord): void;
     /** Drops every record of `step` whose path is not in `keep`: a deleted path drops every record it owns. */
     retain(step: string, keep: ReadonlySet<string>): void;
+    /** Drops every record whose step starts with `prefix` and whose path is not in `keep`. */
+    retainPrefix(prefix: string, keep: ReadonlySet<string>): void;
+    /** Drops every record whose step starts with `prefix` and is not one of `keep`: a unit step no rule asked for this run belongs to no rule any more. */
+    dropPrefixExcept(prefix: string, keep: ReadonlySet<string>): void;
     /** Every finding the records of `step` hold. */
     findings(step: string): Finding[];
     toArray(): CacheRecord[];
@@ -24,6 +30,7 @@ export declare function scopedStep<T extends JsonValue>(session: CheckSession, r
     readonly key: string;
     readonly reuse: boolean;
     readonly inputs: readonly string[];
+    readonly captured?: Readonly<Record<string, string>>;
     compute(): T | Promise<T>;
     compact(value: T): Finding[];
     store?(value: T): boolean;

package/cache/records.mjs

@@ -14,6 +14,10 @@ export class RecordSet {
         const record = this.records.get(keyOf(path, step));
         return record?.hash === hash ? record : undefined;
     }
+    /** The record of (path, step) whatever its hash, for a step that validates the record's own inputs. */
+    get(path, step) {
+        return this.records.get(keyOf(path, step));
+    }
     put(record) {
         this.records.set(keyOf(record.path, record.step), record);
     }
@@ -23,6 +27,18 @@ export class RecordSet {
             if (record.step === step && !keep.has(record.path))
                 this.records.delete(key);
     }
+    /** Drops every record whose step starts with `prefix` and whose path is not in `keep`. */
+    retainPrefix(prefix, keep) {
+        for (const [key, record] of this.records)
+            if (record.step.startsWith(prefix) && !keep.has(record.path))
+                this.records.delete(key);
+    }
+    /** Drops every record whose step starts with `prefix` and is not one of `keep`: a unit step no rule asked for this run belongs to no rule any more. */
+    dropPrefixExcept(prefix, keep) {
+        for (const [key, record] of this.records)
+            if (record.step.startsWith(prefix) && !keep.has(record.step))
+                this.records.delete(key);
+    }
     /** Every finding the records of `step` hold. */
     findings(step) {
         return [...this.records.values()].filter((record) => record.step === step).flatMap((record) => record.findings);
@@ -48,7 +64,7 @@ export async function scopedStep(session, records, step) {
     if (held?.data !== undefined)
         return { value: held.data, reused: true };
     const value = await step.compute();
-    if ((step.store?.(value) ?? true) && session.unchanged(step.inputs))
+    if ((step.store?.(value) ?? true) && session.unchanged(step.inputs, step.captured))
         records.put({ path: step.path, step: step.step, hash: step.key, findings: step.compact(value), data: value });
     return { value, reused: false };
 }

package/cache/run.d.mts

@@ -17,7 +17,7 @@ export interface AppRunInput {
     readonly presets?: Presets | undefined;
     readonly prettier?: Prettier | undefined;
     readonly edition?: string | undefined;
-    /** Limits the formatter to these app-relative files (`app lint --changed`). */
+    /** Limits the formatter to these app-relative files. */
     readonly only?: readonly string[] | undefined;
     /** The ref the baseline database rules compare with, when the caller names one. */
     readonly base?: string | undefined;

package/cache/session.mjs

@@ -1,4 +1,4 @@
-// session.mts - the disk-backed CheckSession of `starci app check` and `starci app lint`. It decides per family whether a run is full or diff
+// session.mts - the disk-backed CheckSession of `starci app check`. It decides per family whether a run is full or diff
 // (the rules of contexts/project/check-cache.md "When a run is full"), serves the trusted records of a folder, takes the records a family
 // replaces and writes them once on flush: one JSON Lines file per area, byte-stable, only the files whose bytes changed. In CI it writes
 // nothing and compares the committed cache with what it inherited or computed instead.
@@ -127,7 +127,11 @@ export function createDiskSession(options) {
         replace(folder, records, replaceOptions) {
             replaced.set(folder, { records, depth: replaceOptions?.depth ?? 2 });
         },
-        unchanged: (paths) => paths.every((file) => hashFile(path.join(root, file)) === index.hashOf(file)),
+        unchanged: (paths, captured) => paths.every((file) => {
+            const now = hashFile(path.join(root, file));
+            const taken = captured?.[file];
+            return taken === undefined ? now === index.hashOf(file) : (now ?? 'absent') === taken;
+        }),
         report: (report) => void reports.push(report),
         verdicts: () => verdictList,
         flush() {

package/cache/side-key.d.mts

@@ -3,6 +3,8 @@ export interface SideKey {
     readonly key: string;
     /** Every path the key covers: tracked paths of the side and the untracked program inputs. */
     readonly inputs: readonly string[];
+    /** The hash each input had when the key was computed (`absent` for a missing one): the baseline `session.unchanged` compares an edit-during-the-run against. */
+    readonly hashes: Readonly<Record<string, string>>;
 }
 /** The untracked files the side's TypeScript program includes (generated code), side-relative paths prefixed with `side/`. */
 export declare function untrackedProgramInputs(root: string, side: string, tracked: ReadonlySet<string>): string[];

package/cache/side-key.mjs

@@ -43,5 +43,9 @@ export function sideKey(root, index, side) {
     const untracked = untrackedProgramInputs(root, side, new Set(index.paths));
     for (const file of untracked)
         parts[`untracked:${file}`] = hashFile(path.join(root, file)) ?? 'absent';
-    return { key: combineHashes(parts), inputs: [...trackedPaths, ...untracked] };
+    const hashes = {};
+    for (const [name, hash] of Object.entries(parts))
+        if (name.startsWith('tracked:') || name.startsWith('untracked:'))
+            hashes[name.slice(name.indexOf(':') + 1)] = hash;
+    return { key: combineHashes(parts), inputs: [...trackedPaths, ...untracked], hashes };
 }

package/cache/structure-memo.d.mts

@@ -0,0 +1,34 @@
+import type { RuleMemo } from '../runtime/scripts/hfs/rule-memo.mjs';
+import type { RecordSet } from './records.mjs';
+import type { CheckSession } from './types.mjs';
+export declare const FILE_RULES_STEP = "file-rules";
+export declare const RULE_STEP_PREFIX = "rule:";
+export declare const UNIT_STEP_PREFIX = "unit:";
+/** What the memo did, for the family's diagnosis line. */
+export interface MemoCounts {
+    /** Files whose per-file rules were judged afresh / taken from a record. */
+    filesChecked: number;
+    filesReused: number;
+    /** Cross-file rules run afresh / taken from a record. */
+    keyedChecked: number;
+    keyedReused: number;
+    /** Per-file units of cross-file rules judged afresh / taken from a record. */
+    unitsChecked: number;
+    unitsReused: number;
+}
+export interface StructureMemo {
+    readonly memo: RuleMemo;
+    readonly counts: MemoCounts;
+    /** The app paths whose per-file records this run holds (the rest are dropped with their files). */
+    readonly files: Set<string>;
+    /** The app paths whose unit records this run holds, by unit step. */
+    readonly units: Map<string, Set<string>>;
+}
+/** The memo of one structure pass over the app at `root`. `reuse` is false when the family runs in full: the records are then written and never read. */
+export declare function createStructureMemo(input: {
+    session: CheckSession;
+    records: RecordSet;
+    reuse: boolean;
+    root: string;
+    tracked: readonly string[];
+}): StructureMemo;

package/cache/structure-memo.mjs

@@ -0,0 +1,150 @@
+// structure-memo.mts - the result cache of the content rules of the structure pass (`--gate hfs`, `--gate secrets`). The rules of the pass used to run over every tracked
+// file on every run. Two kinds are now reused (contexts/project/check-cache.md "Which step reuses what"):
+//   - a per-file rule (`FileRule`: plaintext secrets, bypass markers, soft size): one record per file, `file-rules`, keyed on the file's content hash, the hashes of the
+//     other files the rule declares it reads (`deps`) and the names of the rules; it holds each rule's findings for the file. The cache folder is the only place a verdict is kept.
+//   - a cross-file rule (`memoKeyed`: the documentation freshness): one record per scope, `rule:<id>`, keyed on the exact set of files the rule read through `readText` /
+//     `readJson` (recorded when it ran, each with the hash it had then) and on the digest of the tracked path list, which every such rule derives its file sets from.
+// Everything else the pass runs (the slots, the tree, the pins, the managed files, the rules that stat or walk the work tree, git state, untracked entries) stays always-run.
+// A rule that must be judged on the work tree is never given to this memo; a finding that does not carry the path of the file it judges makes the whole batch uncacheable.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { recordReads } from '../runtime/scripts/hfs/rules/read.mjs';
+import { inCacheDir } from './content-index.mjs';
+import { combineHashes, hashFile, hashText } from './hash.mjs';
+export const FILE_RULES_STEP = 'file-rules';
+export const RULE_STEP_PREFIX = 'rule:';
+export const UNIT_STEP_PREFIX = 'unit:';
+const posix = (value) => value.split(path.sep).join('/');
+const compact = (finding) => ({
+    path: finding.path ?? '.', line: finding.line ?? 0, column: finding.column ?? 0, rule: finding.code, message: String(finding.message ?? ''),
+});
+const plain = (value) => JSON.parse(JSON.stringify(value));
+/** The memo of one structure pass over the app at `root`. `reuse` is false when the family runs in full: the records are then written and never read. */
+export function createStructureMemo(input) {
+    const { session, records, reuse, root } = input;
+    const counts = { filesChecked: 0, filesReused: 0, keyedChecked: 0, keyedReused: 0, unitsChecked: 0, unitsReused: 0 };
+    const files = new Set();
+    const units = new Map();
+    // What this run already judged, so a rule asked twice about one file in one run (the schedule scan is) answers from the first judgement.
+    const judged = new Map();
+    const textHashes = new Map();
+    // The hash of an app path now: the index's for a tracked file (the snapshot of this run), the work tree's for anything else, `absent` for a missing one.
+    const hashNow = (appPath) => session.index.hashOf(appPath) ?? hashFile(path.join(root, appPath)) ?? 'absent';
+    // What every cross-file rule derives its file sets and its parsing from: the tracked path list, and the TypeScript the rules parse with (the lockfile is a fingerprint part, but an app
+    // with no install resolves the compiler from the harness instead).
+    let trackedDigest;
+    const typescriptVersion = () => loadTypescript(root, path.dirname(fileURLToPath(import.meta.url)))?.version ?? 'none';
+    const digestOfTracked = () => (trackedDigest ??= hashText(`${[...input.tracked].sort().join('\n')}\0typescript=${typescriptVersion()}`));
+    const prefixOf = (scopeRoot) => {
+        const relative = posix(path.relative(root, scopeRoot));
+        return relative === '' ? '' : `${relative}/`;
+    };
+    const filesStep = (scopeRoot, list, rules) => {
+        const prefix = prefixOf(scopeRoot);
+        const names = rules.map((rule) => rule.id).join('+');
+        // The cache folder is rewritten by every run and is outside every step's file set: its files are judged live and never keyed.
+        const live = list.filter((file) => inCacheDir(`${prefix}${file}`));
+        const liveOut = live.length === 0 ? [] : rules.map((rule) => rule.run([...live]));
+        const entries = list.filter((file) => !inCacheDir(`${prefix}${file}`)).map((file) => {
+            const deps = [...new Set(rules.flatMap((rule) => rule.deps?.(file) ?? []))].sort().map((dep) => `${prefix}${dep}`);
+            const parts = { rules: names, self: hashNow(`${prefix}${file}`) };
+            const captured = { [`${prefix}${file}`]: parts['self'] };
+            for (const dep of deps) {
+                parts[`dep:${dep}`] = hashNow(dep);
+                captured[dep] = parts[`dep:${dep}`];
+            }
+            return { file, app: `${prefix}${file}`, deps, captured, key: combineHashes(parts) };
+        });
+        const held = new Map();
+        for (const entry of entries) {
+            const record = reuse ? records.matching(entry.app, FILE_RULES_STEP, entry.key) : undefined;
+            if (record?.data !== undefined)
+                held.set(entry.file, record.data);
+        }
+        const missing = entries.filter((entry) => !held.has(entry.file));
+        counts.filesReused += entries.length - missing.length;
+        counts.filesChecked += missing.length;
+        const computed = new Map(missing.map((entry) => [entry.file, {}]));
+        if (missing.length > 0) {
+            const names = new Set(missing.map((entry) => entry.file));
+            for (const rule of rules) {
+                for (const finding of rule.run(missing.map((entry) => entry.file))) {
+                    const own = finding.path !== undefined && names.has(finding.path) ? computed.get(finding.path) : undefined;
+                    // A finding on a file the batch did not hold is a rule that is not per-file: nothing of it can be kept per file.
+                    if (own === undefined)
+                        return rules.flatMap((each) => each.run([...list]));
+                    (own[rule.id] ??= []).push(finding);
+                }
+            }
+            for (const entry of missing) {
+                const result = computed.get(entry.file);
+                if (!session.unchanged(Object.keys(entry.captured), entry.captured))
+                    continue;
+                records.put({ path: entry.app, step: FILE_RULES_STEP, hash: entry.key, findings: Object.values(result).flat().map(compact), data: plain(result) });
+            }
+        }
+        for (const entry of entries)
+            files.add(entry.app);
+        const out = [];
+        rules.forEach((rule, at) => {
+            for (const entry of entries)
+                out.push(...((held.get(entry.file) ?? computed.get(entry.file))?.[rule.id] ?? []));
+            out.push(...(liveOut[at] ?? []));
+        });
+        return out;
+    };
+    const keyedStep = (scopeRoot, id, run) => {
+        const at = prefixOf(scopeRoot).replace(/\/$/, '') || '.';
+        const step = `${RULE_STEP_PREFIX}${id}`;
+        const digest = digestOfTracked();
+        const record = reuse ? records.get(at, step) : undefined;
+        const data = record?.data;
+        if (data?.tracked === digest && data.reads !== undefined && data.findings !== undefined && Object.entries(data.reads).every(([file, hash]) => hashNow(file) === hash)) {
+            counts.keyedReused += 1;
+            return data.findings;
+        }
+        counts.keyedChecked += 1;
+        const reads = {};
+        const findings = recordReads((from, rel) => {
+            const app = posix(path.relative(root, path.join(from, rel)));
+            if (app.startsWith('..') || path.isAbsolute(app) || app in reads)
+                return;
+            reads[app] = hashNow(app);
+        }, run);
+        if (session.unchanged(Object.keys(reads), reads)) {
+            const stored = { path: at, step, hash: combineHashes({ tracked: digest, ...Object.fromEntries(Object.entries(reads).map(([file, hash]) => [`read:${file}`, hash])) }), findings: findings.map(compact), data: plain({ tracked: digest, reads, findings }) };
+            records.put(stored);
+        }
+        return findings;
+    };
+    const unitStep = (scopeRoot, id, file, extra, empty, compute) => {
+        const app = `${prefixOf(scopeRoot)}${file}`;
+        const step = `${UNIT_STEP_PREFIX}${id}`;
+        let extraHash = textHashes.get(extra);
+        if (extraHash === undefined)
+            textHashes.set(extra, (extraHash = hashText(extra)));
+        const self = hashNow(app);
+        const key = combineHashes({ unit: id, extra: extraHash, self, typescript: typescriptVersion() });
+        (units.get(step) ?? units.set(step, new Set()).get(step))?.add(app);
+        const memory = judged.get(JSON.stringify([step, app, key]));
+        if (memory !== undefined)
+            return memory;
+        const record = reuse ? records.matching(app, step, key) : undefined;
+        let value;
+        if (record !== undefined) {
+            counts.unitsReused += 1;
+            value = (record.data ?? empty);
+        }
+        else {
+            counts.unitsChecked += 1;
+            value = compute();
+            const empties = JSON.stringify(empty) === JSON.stringify(value);
+            if (session.unchanged([app], { [app]: self }))
+                records.put({ path: app, step, hash: key, findings: [], ...(empties ? {} : { data: plain(value) }) });
+        }
+        judged.set(JSON.stringify([step, app, key]), value);
+        return value;
+    };
+    return { memo: { files: filesStep, keyed: keyedStep, unit: unitStep }, counts, files, units };
+}

package/cache/types.d.mts

@@ -91,8 +91,12 @@ export interface CheckSession {
     replace(folder: string, records: readonly CacheRecord[], options?: {
         readonly depth?: number;
     }): void;
-    /** True when none of `paths` changed in the work tree since the run began: a scoped step stores nothing keyed on a file edited during the run. */
-    unchanged(paths: readonly string[]): boolean;
+    /**
+     * True when none of `paths` changed in the work tree since the run began: a scoped step stores nothing keyed on a file edited during the run.
+     * A path the content index does not hold (an untracked program input, generated code) is compared with `captured`, the hash the step's key took
+     * of it (`absent` for a missing file); without a captured hash it is compared with the index, so an untracked path is never unchanged.
+     */
+    unchanged(paths: readonly string[], captured?: Readonly<Record<string, string>>): boolean;
     report(report: FamilyReport): void;
     readonly progress: ProgressSink;
     flush(): FlushResult;

package/cache/wiring-family.mjs

@@ -27,7 +27,7 @@ export async function runWiringFamily(session, { repoRoot, edition, files, run,
     };
     const step = session.progress.step('wiring', 'boot proof', Math.max(1, key.inputs.length));
     const { value, reused } = await scopedStep(session, records, {
-        path: 'be', step: 'boot-proof', key: key.key, reuse: decision.mode === 'diff', inputs: key.inputs,
+        path: 'be', step: 'boot-proof', key: key.key, reuse: decision.mode === 'diff', inputs: key.inputs, captured: key.hashes,
         compute: async () => JSON.parse(JSON.stringify(await prove())),
         compact: (found) => found.findings.map(compact),
         store: (found) => !found.findings.some((finding) => finding.code === BOOT_PROOF_TIMEOUT),

package/codemod/directive-first.d.mts

@@ -0,0 +1,48 @@
+/** The TypeScript compiler API of the app's own install (loadTypescript), typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** One move of the report: a directive taken from `line` to the top of its module. */
+export interface DirectiveFirstChange {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    from: string;
+    to: string;
+}
+/** One case left for a person. */
+export interface DirectiveFirstFinding {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod directive-first`). */
+export interface DirectiveFirstReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    changes: DirectiveFirstChange[];
+    findings: DirectiveFirstFinding[];
+}
+/** Move every `"use client"` / `"use server"` that is not in the prologue of the module to the top of it, as its first statement, with one blank line after. */
+export declare function transformDirectiveFirst({ ts, text, file }: {
+    ts: Ts;
+    text: string;
+    file?: string;
+}): {
+    text: string;
+    changes: DirectiveFirstChange[];
+    findings: DirectiveFirstFinding[];
+};
+/** Preview or apply the moves in one app (`be/`, `fe/`, or `src/` of a single-side app); a conflicting module is kept in the returned report. */
+export declare function migrateDirectiveFirst({ root, write, ts }: {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+}): DirectiveFirstReport;
+/** Render the moves and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function directiveFirstMarkdown(report: DirectiveFirstReport): string;
+export {};