@mjasnikovs/pi-task 0.40.50 → 0.42.0

package/dist/task/run-context.d.ts

@@ -0,0 +1,152 @@
+import type { SpawnFn } from '../shared/child-process.js';
+import { type EcosystemId } from '../workers/docs-ecosystems.js';
+import type { GateEvidence } from './gate-evidence.js';
+import { type OrientationResult } from './orientation.js';
+/**
+ * What a verified command is FOR, and the only column that decides whether the
+ * gate-evidence runner may execute it: `check` and `build` terminate on their own,
+ * `serve` does not and is never launched.
+ */
+export type ToolingClass = 'check' | 'build' | 'serve';
+/**
+ * The exit code of a command nobody has run. verify-tooling confirms a command
+ * from STATIC evidence (a script in the manifest, a binary in node_modules/.bin)
+ * and is forbidden to execute it, so its entries carry this until the evidence
+ * runner replaces them with a real result.
+ */
+export declare const NOT_RUN = -1;
+/** One command this run has verified, with the manifest state that vouched for it. */
+export interface VerifiedCommand {
+    cmd: string;
+    /** Where it runs — the repo root today; a monorepo package tomorrow. */
+    cwd: string;
+    class: ToolingClass;
+    /** {@link NOT_RUN} until something actually runs it. */
+    exitCode: number;
+    verifiedAt: number;
+    manifestHash: string;
+}
+/** The worktree content as a git tree object (see tree-hash.ts), or null when
+ *  git cannot say. */
+export declare function treeHash(cwd: string, opts?: {
+    signal?: AbortSignal;
+    spawnFn?: SpawnFn;
+}): Promise<string | null>;
+/**
+ * Content hash of the files that decide which commands this project HAS — the
+ * manifests `discoverHealthCommands` reads, plus the Makefile. A missing file
+ * contributes nothing, and since each contributing file is hashed under its own
+ * name, adding or deleting one moves the hash.
+ */
+export declare function manifestHash(cwd: string): Promise<string>;
+/** Produce one tree's gate evidence, given the commands that may be run against it
+ *  and the hash of the tree they are being run against (see gate-evidence.ts). */
+export type EvidenceRunner = (commands: readonly VerifiedCommand[], treeHash: string | null) => Promise<GateEvidence>;
+/** A verify-tooling verdict as the child reported it, before it is dated and stored. */
+export interface ToolingVerdict {
+    cmd: string;
+    class: ToolingClass;
+}
+/** Everything the run-level tooling cache asks of its verifier. */
+export type VerifyToolingFn = (commands: string[]) => Promise<{
+    verified: ToolingVerdict[];
+    rejected: string[];
+}>;
+export interface RunContextOptions {
+    cwd: string;
+    /** Reuse an existing id (a resumed /task-auto run); minted when absent. */
+    runId?: string;
+    signal?: AbortSignal;
+}
+/**
+ * The per-run facts, computed on first ask and then held.
+ *
+ * Every getter is memoised on the PROMISE, not on the value, so two phases asking
+ * at once still produce one computation.
+ */
+export declare class RunContext {
+    readonly cwd: string;
+    readonly runId: string;
+    private readonly _signal;
+    private _inventory;
+    private readonly _orientation;
+    private _orientationExclude;
+    private _manifestDeps;
+    private _ecosystems;
+    private _verifiedTooling;
+    /** Commands verify-tooling has already refused under `_toolingHash`. */
+    private _rejectedTooling;
+    private _toolingHash;
+    private _evidence;
+    private _evidenceQueue;
+    constructor(opts: RunContextOptions);
+    /** `git ls-files` for this run; '' outside a git tree (see file-inventory.ts). */
+    inventory(): Promise<string>;
+    /** This run's inventory as paths, blank lines dropped. */
+    inventoryPaths(): Promise<string[]>;
+    /**
+     * The orientation core over this run's whole inventory — the block the
+     * exploring research workers get, built once however many tasks ask.
+     *
+     * Memoised per CITED SET, not once: the files a task points at are part of the
+     * question, and two tasks citing different specs are asking for different
+     * blocks. Every task in a /task-auto run carries the same threaded spec ref, so
+     * in practice this is still one build.
+     */
+    orientation(cited?: readonly string[]): Promise<OrientationResult>;
+    /** The same block over a NARROWED candidate list (refine takes the manifest and
+     *  config tiers only), which is per-caller and so not memoised. */
+    orientationOf(paths: string[] | undefined, cited?: readonly string[]): Promise<OrientationResult>;
+    /**
+     * What this project says is not its own source, on top of `VENDORED_DIRS`:
+     * its `.gitignore`, plus the user's `orientationExclude`. Read once — a run
+     * that re-read it mid-way would orient two tasks differently.
+     */
+    private orientationExclusions;
+    /**
+     * Dependency names this project's manifests declare, across every ecosystem it
+     * is a project of. `[]` when no manifest could be read — callers use it to tell
+     * "this bullet is about a library" from "this bullet is about our source", and
+     * that degrades to a no-op rather than an error.
+     */
+    manifestDeps(): string[];
+    ecosystems(): EcosystemId[];
+    /** What this run has verified so far, newest verdict per command. */
+    get verifiedTooling(): readonly VerifiedCommand[];
+    /**
+     * The verified subset of `commands`, running `verify` only for the ones this
+     * run has no verdict for.
+     *
+     * A manifest edit — a new script, a new Makefile target — is the only thing that
+     * can change which commands the project has, so it is the only thing that drops
+     * the verdicts. Short of that, the second task's identical TOOLING list is
+     * answered from the first task's child.
+     */
+    verifiedToolingFor(commands: string[], verify: VerifyToolingFn): Promise<VerifiedCommand[]>;
+    /**
+     * This gate session's evidence: the run's verified check and build commands,
+     * run against the CURRENT tree, at most once per tree (see gate-evidence.ts).
+     *
+     * The TREE HASH is the key, so a lint-fix or an autofix that changes the tree
+     * costs exactly one re-run and a second gate child on the same tree costs none.
+     * A tree git cannot hash is never cached: "unchanged" is not something we could
+     * claim about it.
+     */
+    gateEvidenceFor(produce: EvidenceRunner): Promise<GateEvidence>;
+    private freshEvidence;
+}
+/** Open a run: every task inside it now shares one context. Nests — an inner
+ *  bracket returns the outer run's context untouched. */
+export declare function openRunContext(cwd: string, runId?: string): RunContext;
+/** Close the run `rc` opened. A stale close (an inner bracket ending after the
+ *  outer one) is a no-op. */
+export declare function closeRunContext(rc: RunContext): void;
+/**
+ * The open run's context, or a fresh one for a caller outside any bracket (a
+ * direct `runSingleTask`, a test). The fallback is deliberately NOT registered:
+ * an unbracketed caller has no run to end, and a context that outlived its caller
+ * would serve a later run a stale inventory.
+ */
+export declare function currentRunContext(cwd: string): RunContext;
+/** The open run's id for `cwd`, or null outside any bracket. */
+export declare function openRunId(cwd: string): string | null;

package/dist/task/run-context.js

@@ -0,0 +1,277 @@
+/**
+ * run-context — what is true of the RUN rather than of the task inside it.
+ *
+ * A /task-auto run is many task pipelines over one unchanging project. The file
+ * inventory, the orientation core, the manifest's dependency names, the detected
+ * ecosystems and the verified tooling commands are all facts about the PROJECT,
+ * and every one of them was being re-derived per task: twenty-one verify-tooling
+ * children asking the same question of the same package.json, each free to answer
+ * differently.
+ *
+ * So they are held here, once per run, and handed to the phases through
+ * `PhaseDeps.runContext`. A bare `/task` is a run of one task and gets its own
+ * context with a minted id, so nothing has two code paths.
+ *
+ * INVALIDATION. Verified tooling is invalidated by the MANIFEST HASH alone — the
+ * content of the files `discoverHealthCommands` reads. A task that edits source
+ * cannot change which commands exist; a task that adds a script can, and that is
+ * exactly what the hash moves on. Everything else here describes the tree as the
+ * run found it and is not re-read: a mid-run inventory refresh would hand two
+ * tasks different orientation cores for the same question.
+ *
+ * TREE HASH is the other half, used by the gate-evidence cache; its one
+ * implementation lives in tree-hash.ts.
+ */
+import { createHash } from 'node:crypto';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { makeGit } from '../shared/git-runner.js';
+import { declaredDepNames, detectEcosystems } from '../workers/docs-ecosystems.js';
+import { newRunToken } from '../workers/research-cache.js';
+import { getFileInventory } from './file-inventory.js';
+import { getConfig } from '../config/config.js';
+import { buildOrientation, parseIgnorePatterns } from './orientation.js';
+import { HEALTH_MANIFEST_FILES } from './repo-health-check.js';
+import { worktreeTreeHash } from './tree-hash.js';
+/**
+ * The exit code of a command nobody has run. verify-tooling confirms a command
+ * from STATIC evidence (a script in the manifest, a binary in node_modules/.bin)
+ * and is forbidden to execute it, so its entries carry this until the evidence
+ * runner replaces them with a real result.
+ */
+export const NOT_RUN = -1;
+/** The worktree content as a git tree object (see tree-hash.ts), or null when
+ *  git cannot say. */
+export async function treeHash(cwd, opts = {}) {
+    return worktreeTreeHash(makeGit(cwd, opts.signal, opts.spawnFn));
+}
+/**
+ * Content hash of the files that decide which commands this project HAS — the
+ * manifests `discoverHealthCommands` reads, plus the Makefile. A missing file
+ * contributes nothing, and since each contributing file is hashed under its own
+ * name, adding or deleting one moves the hash.
+ */
+export async function manifestHash(cwd) {
+    const h = createHash('sha256');
+    for (const file of HEALTH_MANIFEST_FILES) {
+        try {
+            h.update(file);
+            h.update('\u0000');
+            h.update(await fsp.readFile(path.join(cwd, file)));
+            h.update('\u0000');
+        }
+        catch {
+            // absent or unreadable ⇒ contributes nothing
+        }
+    }
+    return h.digest('hex');
+}
+/** The classes the gate-evidence runner may execute. `serve` is absent by
+ *  definition: it never returns, and the parent has nothing to kill it with. */
+const EVIDENCE_CLASSES = new Set(['check', 'build']);
+/**
+ * The per-run facts, computed on first ask and then held.
+ *
+ * Every getter is memoised on the PROMISE, not on the value, so two phases asking
+ * at once still produce one computation.
+ */
+export class RunContext {
+    cwd;
+    runId;
+    _signal;
+    _inventory;
+    _orientation = new Map();
+    _orientationExclude;
+    _manifestDeps;
+    _ecosystems;
+    _verifiedTooling = [];
+    /** Commands verify-tooling has already refused under `_toolingHash`. */
+    _rejectedTooling = new Set();
+    _toolingHash;
+    _evidence;
+    _evidenceQueue = Promise.resolve();
+    constructor(opts) {
+        this.cwd = opts.cwd;
+        this.runId = opts.runId ?? newRunToken();
+        this._signal = opts.signal;
+    }
+    /** `git ls-files` for this run; '' outside a git tree (see file-inventory.ts). */
+    inventory() {
+        this._inventory ??= getFileInventory(this.cwd, this._signal).catch(() => '');
+        return this._inventory;
+    }
+    /** This run's inventory as paths, blank lines dropped. */
+    async inventoryPaths() {
+        return (await this.inventory()).split('\n').filter(l => l.trim().length > 0);
+    }
+    /**
+     * The orientation core over this run's whole inventory — the block the
+     * exploring research workers get, built once however many tasks ask.
+     *
+     * Memoised per CITED SET, not once: the files a task points at are part of the
+     * question, and two tasks citing different specs are asking for different
+     * blocks. Every task in a /task-auto run carries the same threaded spec ref, so
+     * in practice this is still one build.
+     */
+    orientation(cited = []) {
+        const key = JSON.stringify([...cited].sort());
+        let built = this._orientation.get(key);
+        if (!built) {
+            built = this.orientationOf(undefined, cited);
+            this._orientation.set(key, built);
+        }
+        return built;
+    }
+    /** The same block over a NARROWED candidate list (refine takes the manifest and
+     *  config tiers only), which is per-caller and so not memoised. */
+    async orientationOf(paths, cited = []) {
+        const candidates = paths ?? (await this.inventoryPaths());
+        return buildOrientation(candidates, async (p) => {
+            try {
+                return await fsp.readFile(path.resolve(this.cwd, p), 'utf8');
+            }
+            catch {
+                return null;
+            }
+        }, { cited, excludePatterns: await this.orientationExclusions() }).catch(() => ({ block: '', supplied: new Set() }));
+    }
+    /**
+     * What this project says is not its own source, on top of `VENDORED_DIRS`:
+     * its `.gitignore`, plus the user's `orientationExclude`. Read once — a run
+     * that re-read it mid-way would orient two tasks differently.
+     */
+    orientationExclusions() {
+        this._orientationExclude ??= fsp
+            .readFile(path.join(this.cwd, '.gitignore'), 'utf8')
+            .then(parseIgnorePatterns)
+            .catch(() => [])
+            .then(fromGit => [...fromGit, ...getConfig().orientationExclude]);
+        return this._orientationExclude;
+    }
+    /**
+     * Dependency names this project's manifests declare, across every ecosystem it
+     * is a project of. `[]` when no manifest could be read — callers use it to tell
+     * "this bullet is about a library" from "this bullet is about our source", and
+     * that degrades to a no-op rather than an error.
+     */
+    manifestDeps() {
+        this._manifestDeps ??= [...(declaredDepNames(this.cwd) ?? [])];
+        return this._manifestDeps;
+    }
+    ecosystems() {
+        this._ecosystems ??= detectEcosystems(this.cwd);
+        return this._ecosystems;
+    }
+    /** What this run has verified so far, newest verdict per command. */
+    get verifiedTooling() {
+        return this._verifiedTooling;
+    }
+    /**
+     * The verified subset of `commands`, running `verify` only for the ones this
+     * run has no verdict for.
+     *
+     * A manifest edit — a new script, a new Makefile target — is the only thing that
+     * can change which commands the project has, so it is the only thing that drops
+     * the verdicts. Short of that, the second task's identical TOOLING list is
+     * answered from the first task's child.
+     */
+    async verifiedToolingFor(commands, verify) {
+        const hash = await manifestHash(this.cwd);
+        if (hash !== this._toolingHash) {
+            this._verifiedTooling = [];
+            this._rejectedTooling = new Set();
+            this._toolingHash = hash;
+        }
+        const decided = new Set([
+            ...this._verifiedTooling.map(v => v.cmd),
+            ...this._rejectedTooling
+        ]);
+        const unknown = commands.filter(c => !decided.has(c));
+        if (unknown.length > 0) {
+            const r = await verify(unknown);
+            const at = Date.now();
+            for (const v of r.verified) {
+                this._verifiedTooling.push({
+                    cmd: v.cmd,
+                    cwd: this.cwd,
+                    class: v.class,
+                    exitCode: NOT_RUN,
+                    verifiedAt: at,
+                    manifestHash: hash
+                });
+            }
+            for (const c of r.rejected)
+                this._rejectedTooling.add(c);
+        }
+        const wanted = new Set(commands);
+        return this._verifiedTooling.filter(v => wanted.has(v.cmd));
+    }
+    /**
+     * This gate session's evidence: the run's verified check and build commands,
+     * run against the CURRENT tree, at most once per tree (see gate-evidence.ts).
+     *
+     * The TREE HASH is the key, so a lint-fix or an autofix that changes the tree
+     * costs exactly one re-run and a second gate child on the same tree costs none.
+     * A tree git cannot hash is never cached: "unchanged" is not something we could
+     * claim about it.
+     */
+    gateEvidenceFor(produce) {
+        // Serialised rather than merely memoised: two gate children asking at once
+        // is exactly the duplicate suite run this cache exists to kill.
+        const next = this._evidenceQueue.then(() => this.freshEvidence(produce));
+        this._evidenceQueue = next.catch(() => { });
+        return next;
+    }
+    async freshEvidence(produce) {
+        const hash = await treeHash(this.cwd, this._signal ? { signal: this._signal } : {});
+        if (hash !== null && this._evidence?.hash === hash)
+            return this._evidence.value;
+        const value = await produce(this._verifiedTooling.filter(v => EVIDENCE_CLASSES.has(v.class)), hash);
+        // {@link NOT_RUN} stands until something runs the command. This is that
+        // something, so the verdicts stop claiming nobody has.
+        for (const c of value.commands) {
+            const verified = this._verifiedTooling.find(v => v.cmd === c.cmd);
+            if (verified)
+                verified.exitCode = c.exitCode;
+        }
+        if (hash !== null)
+            this._evidence = { hash, value };
+        return value;
+    }
+}
+/**
+ * The context of the run that owns the session right now, set by the run bracket.
+ *
+ * A module-level holder rather than a parameter because the path from a command
+ * handler to a phase runs through `runTask`, a seam whose signature is shared with
+ * the gates; threading the context through it would put a field on two dep bags
+ * that nothing but this would ever set.
+ */
+let currentRun = null;
+/** Open a run: every task inside it now shares one context. Nests — an inner
+ *  bracket returns the outer run's context untouched. */
+export function openRunContext(cwd, runId) {
+    if (currentRun && currentRun.cwd === cwd)
+        return currentRun;
+    currentRun = new RunContext({ cwd, ...(runId === undefined ? {} : { runId }) });
+    return currentRun;
+}
+/** Close the run `rc` opened. A stale close (an inner bracket ending after the
+ *  outer one) is a no-op. */
+export function closeRunContext(rc) {
+    if (currentRun === rc)
+        currentRun = null;
+}
+/**
+ * The open run's context, or a fresh one for a caller outside any bracket (a
+ * direct `runSingleTask`, a test). The fallback is deliberately NOT registered:
+ * an unbracketed caller has no run to end, and a context that outlived its caller
+ * would serve a later run a stale inventory.
+ */
+export function currentRunContext(cwd) {
+    return currentRun && currentRun.cwd === cwd ? currentRun : new RunContext({ cwd });
+}
+/** The open run's id for `cwd`, or null outside any bracket. */
+export function openRunId(cwd) {
+    return currentRun && currentRun.cwd === cwd ? currentRun.runId : null;
+}

package/dist/task/spec-doc.d.ts

@@ -0,0 +1,78 @@
+export type BlockKind = 'para' | 'list-item' | 'table-row' | 'fence' | 'quote';
+export interface Block {
+    kind: BlockKind;
+    /** The source lines, verbatim. */
+    text: string;
+    /** `text` with markdown MARKUP removed — see `demark`. */
+    plain: string;
+    /** 1-based line of the block's first line; the anchor a grounded quote records. */
+    line: number;
+}
+export interface Section {
+    /** The heading text without its `#` run. */
+    heading: string;
+    depth: number;
+    blocks: Block[];
+}
+export interface SpecDoc {
+    /** Blocks above the first heading. Empty unless the doc has headings at all. */
+    preamble: Block[];
+    sections: Section[];
+}
+/**
+ * Markdown MARKUP dropped before grounding — emphasis runs, list and heading
+ * markers, blockquote markers, table pipes and CODE BACKTICKS. Not content: no
+ * word, number or punctuation inside a sentence is touched, so this cannot make
+ * an invented quote match.
+ *
+ * WHY. A model copies a spec line as it READS, and what it reads is rendered:
+ * `2. **Auth** — sessions, login/logout/me, guards + tests.` comes back as
+ * `Auth — sessions, login/logout/me, guards + tests.` That is a verbatim copy of
+ * the line's TEXT, and the exact-substring test called it fabricated and threw
+ * it away — including, as here, the "+ tests" line that is the restoration
+ * module's own worked example.
+ *
+ * BACKTICKS ARE THE SAME CLASS and were the larger half. A code span renders as
+ * bare text, so `3. **Invites** — create/validate/redeem, \`/join/:token\` page.`
+ * comes back as `Invites — create/validate/redeem, /join/:token page.` Screening
+ * every spec line in its RENDERED form is what makes those quotes match at all.
+ *
+ * The two directions this has to hold in, both run:
+ *   FLOOR   a real spec line with ONE content word altered must NOT be grounded —
+ *           changing `sessions` to `tokens`, or `redeem` to `revoke`, drops it.
+ *   CEILING a real spec line quoted without its markup MUST be grounded — both the
+ *           `2. **Auth** —` numbering-and-bold case and the backticked
+ *           `` `/join/:token` `` case still match.
+ */
+export declare function demark(s: string): string;
+export declare function parseSpecDoc(text: string): SpecDoc;
+/** Every block, in document order. */
+export declare function blocksOf(doc: SpecDoc): Block[];
+/**
+ * The blocks above the first CONTENT section — where a spec says what the thing
+ * IS rather than what the work must do.
+ *
+ * Two shapes, both real. A doc can open with prose and then head its sections; or
+ * it can open with its TITLE as the only top-level heading and put the same prose
+ * under it, which is what `# MX-5 Private — Project Design` does. A lone depth-1
+ * heading above deeper ones is a title, not a section, so its body is preamble
+ * too.
+ *
+ * A document with NO sections at all has no preamble: "preamble" means "above the
+ * body", so without a body there is nothing to be above — otherwise a heading-less
+ * prose spec would have its whole content excluded by any preamble policy.
+ */
+export declare function preambleOf(doc: SpecDoc): Block[];
+/** Heading-delimited section texts in `plain` form, pre-normalised for
+ *  containment tests. The preamble is its own leading section. */
+export declare function sectionPlains(doc: SpecDoc): string[];
+/** The whole doc in `plain` form — the flat fallback for a quote that spans
+ *  block boundaries (a model quoting two consecutive bullets as one line). */
+export declare function specPlain(doc: SpecDoc): string;
+/**
+ * The first block whose `plain` contains `quote`, both demarked and normalised —
+ * the anchor a grounded quote records. `accept` narrows candidacy: a quote whose
+ * only match lies outside it is NOT grounded, which is how a requirement policy
+ * rejects a DDL column or a table cell the model quoted as an obligation.
+ */
+export declare function groundIn(doc: SpecDoc, quote: string, accept?: (b: Block) => boolean): Block | null;