@mjasnikovs/pi-task 0.18.23 → 0.18.25

package/dist/task/artifact-closure.d.ts

@@ -0,0 +1,107 @@
+export interface RuntimeRef {
+    /** Repo-relative normalized path (posix separators, no leading ./). */
+    path: string;
+    /** Where the reference lives: repo-relative file, `package.json scripts.X`, or 'spec'. */
+    referencer: string;
+    /** The construct that matched (Bun.file, readFile, script src, …). */
+    construct: string;
+    /** file = must exist as a file; dir = a static root that must exist as a directory. */
+    kind: 'file' | 'dir';
+}
+export interface DanglingRef extends RuntimeRef {
+    /** Why the producer resolution came up empty (human- and prompt-readable). */
+    reason: string;
+}
+/** Everything the tree/scripts/build POSITIVELY produce. */
+export interface ProducedOutputs {
+    /** Exact output files (tailwind -o, --outfile, redirects, Bun.write, cp dest…). */
+    files: Set<string>;
+    /** Enumerable outdir → output STEMS (basename sans extension) it emits —
+     *  from parsed Bun.build entrypoints, explicit output files, source args. */
+    enumerable: Map<string, Set<string>>;
+    /** Dirs produced by machinery we could not enumerate (vite/tsc/next/unknown
+     *  commands naming them) — everything under them steps aside. */
+    opaque: Set<string>;
+    /** Dirs known to be created (mkdir, outdirs) — satisfies dir-kind refs. */
+    dirs: Set<string>;
+}
+export declare function emptyProducers(): ProducedOutputs;
+/** Normalize a literal path: posix separators, strip ./ prefixes, query/hash
+ *  tails (HTML), trailing slash. Returns null when the literal is not a
+ *  checkable relative path (URL, absolute, template hole, glob — step aside). */
+export declare function normalizeRefPath(raw: string): string | null;
+/** Extract runtime refs from one JS/TS source. */
+export declare function extractJsRefs(source: string, referencer: string): RuntimeRef[];
+/** Extract local-asset refs from one HTML source. */
+export declare function extractHtmlRefs(source: string, referencer: string): RuntimeRef[];
+/** Script entrypoints: `bun x.ts`, `bun run x.ts`, `node x.js`, `tsx x.ts` —
+ *  the first path-shaped source arg of a runner command. */
+export declare function extractScriptEntrypoints(body: string, referencer: string): RuntimeRef[];
+/**
+ * Producer facts from ONE shell command: output flags (`-o x`, `--outfile x`,
+ * `--outdir d`), redirects, `cp`/`mv`/`touch` destinations, `mkdir` dirs, known
+ * opaque bundlers. Leftover path tokens of an UNRECOGNIZED command escalate any
+ * directory they point into to opaque — that command may produce there, and
+ * inconclusive is never evidence. `escalate: false` disables that escalation
+ * for command text embedded in PROSE (a markdown bullet's surrounding words
+ * tokenize as junk "commands" and would opaque half the spec's paths).
+ */
+export declare function collectProducersFromCommand(cmd: string, prod: ProducedOutputs, opts?: {
+    escalate?: boolean;
+}): void;
+/**
+ * Producer facts from JS/TS source: write-side calls (`Bun.write`,
+ * `writeFile(Sync)`, `createWriteStream`, `copyFile` dest, `mkdir(Sync)`),
+ * `Bun.build({entrypoints, outdir})` (enumerable — unless a `naming` option
+ * makes the output names underivable, then opaque), `outfile:`, and `Bun.spawn`
+ * argv arrays re-fed through the shell-command collector (the mx5 build.ts
+ * shape: tailwind's `-o dist/app.css` lives in a spawn array).
+ */
+export declare function collectProducersFromSource(source: string, prod: ProducedOutputs): void;
+/**
+ * Discover everything the project's own machinery produces: package.json script
+ * bodies, build files those scripts run (plus conventional root build files),
+ * tsconfig/vite outDirs.
+ */
+export declare function discoverProducers(cwd: string): ProducedOutputs;
+/**
+ * Resolve refs against existence + producers. DANGLING requires POSITIVE
+ * evidence (see the module doc): the ref sits under an ENUMERATED output dir
+ * and is not among its outputs, or is a missing source-only-extension file
+ * (nothing ever builds a `.ts`/`.tsx`). Everything inconclusive steps aside.
+ */
+export declare function resolveDanglingRefs(refs: RuntimeRef[], prod: ProducedOutputs, exists: (rel: string) => boolean): DanglingRef[];
+/**
+ * FINAL-GATE seam: scan the shipped tree for dangling runtime references.
+ * Deterministic, read-only, best-effort (throws nothing in normal operation;
+ * callers still guard). Producers are discovered first (scripts + build files +
+ * configs), then every authored source contributes refs AND runtime write-side
+ * producers (an app that writes its own cache file satisfies its own read).
+ */
+export declare function findDanglingArtifacts(cwd: string): DanglingRef[];
+/** Ranked-failure text for the final gate (names referencer + missing path). */
+export declare function danglingGateFailureText(d: DanglingRef): string;
+/** Does the spec LIST the file as its own artifact — a file-tree entry or a
+ *  bullet whose first token is (or ends with) the basename? Prose that merely
+ *  mentions the name mid-sentence ("serves the built index.html") does NOT
+ *  count: that is the CONSUMING side, exactly what must not self-satisfy. */
+export declare function specListsFile(spec: string, refPath: string): boolean;
+/** Backticked, asset-extension, path-shaped tokens on consuming-verb lines. */
+export declare function extractSpecProseRefs(spec: string): RuntimeRef[];
+/**
+ * PLAN-TIME seam: runtime refs in the spec's snippets AND consuming prose that
+ * neither the existing scaffold (`fileExists`), the spec's parsed build
+ * outputs, nor its own file tree produce. Each result becomes an UNOWNED
+ * coverage area until some task title claims the artifact.
+ */
+export declare function findSpecDanglingArtifacts(spec: string, fileExists: (rel: string) => boolean): DanglingRef[];
+/** Does some task title claim the artifact (by basename or full path)? Titles
+ *  are the one plan artifact the model cannot fake ownership INTO — mentioning
+ *  the file is the grounded signal a producing task exists. */
+export declare function titlesCoverArtifact(titles: string[], ref: {
+    path: string;
+}): boolean;
+/** Coverage-loop `missing` entry for an unowned dangling artifact. */
+export declare function danglingMissingText(d: DanglingRef): string;
+/** Carried-requirement line when still unowned at coverage exhaustion. */
+export declare function danglingCarryText(d: DanglingRef): string;