@mjasnikovs/pi-task 0.39.5 → 0.40.0

package/dist/workers/eco-hackage.d.ts

@@ -0,0 +1,93 @@
+/**
+ * eco-hackage — reading Haskell packages for the docs Worker tool.
+ *
+ * Two things make Haskell unlike the other rows.
+ *
+ * A package is distributed as a tarball, not as a checked-out tree: cabal keeps
+ * `<name>-<version>.tar.gz` and nothing else, so a package has to be extracted
+ * before it can be read. Extraction is a spawn, and a row's `resolve` is
+ * synchronous, so it happens in `acquire` — which is also where a package cabal
+ * has never fetched is downloaded from Hackage. Both paths end the same way: an
+ * extracted tree under the tool's own modules directory.
+ *
+ * And a Haskell MODULE name is not its PACKAGE name. `Data.Aeson` lives in
+ * `aeson`; asking Hackage for `Data.Aeson` finds nothing. That is the mistake
+ * issue #18 opened on, so it is refused by name with the correction in the
+ * message rather than silently missing.
+ */
+import { type ResolvedPackage } from './docs-resolve.js';
+import type { NpmVersionInfo } from './npm-version.js';
+export declare function isValidHackageName(name: string): boolean;
+/** True for a dotted Haskell MODULE name, which is never a package name. */
+export declare function looksLikeModuleName(name: string): boolean;
+/**
+ * Every package version this build resolved, name to version.
+ *
+ * Three sources in falling order of authority. `dist-newstyle/cache/plan.json` is
+ * what cabal actually built and is exact. A `cabal.project.freeze` is what the
+ * project asked for and is exact too, but may predate the build. `stack.yaml.lock`
+ * covers a stack project, which has no plan.json at all. None of them present is
+ * a real answer — the project pins nothing here — and the caller then falls back
+ * to whatever Hackage calls latest.
+ */
+export declare function resolvedVersions(cwd: string): Record<string, string> | undefined;
+export declare function parsePlanJson(text: string): Record<string, string> | undefined;
+/**
+ * `cabal.project.freeze` states each pin as `any.<name> ==<version>`. Scanned
+ * across the whole file rather than line by line: cabal writes the first
+ * constraint on the `constraints:` line itself and the rest indented below it.
+ */
+export declare function parseFreeze(text: string): Record<string, string>;
+/** `stack.yaml.lock` names each extra dep as `hackage: <name>-<version>@sha256:…`. */
+export declare function parseStackLock(text: string): Record<string, string>;
+export declare function hackageVersion(name: string, cwd: string): string | null;
+export declare function hackageTarballUrl(name: string, version: string): string;
+/** The tarball cabal has already downloaded, in any of its package directories. */
+export declare function findCabalTarball(name: string, version: string, packageDirs: readonly string[]): string | null;
+/** Every version of `name` cabal holds a tarball for, oldest first. */
+export declare function cachedVersions(name: string, packageDirs: readonly string[]): string[];
+/** Where the tool keeps its own extracted copies. */
+export declare function hackageExtractDir(modulesDir: string): string;
+/** Library sources only — `tests/` and `benchmarks/` answer no API question. */
+export declare const HACKAGE_SKIP_DIRS: readonly ["tests", "test", "benchmarks", "bench", "examples", "dist-newstyle", "golden"];
+export interface HackageResolveDirs {
+    modulesDir: string;
+}
+/**
+ * Find an EXTRACTED package. A tarball cabal holds is not readable in place, and
+ * unpacking it is a spawn, so getting it into this state is `acquire`'s job.
+ */
+export declare function resolveHackage(name: string, cwd: string, dirs: HackageResolveDirs): ResolvedPackage;
+/**
+ * The newest version Hackage does not deprecate. `/preferred` returns them newest
+ * first, with the deprecated ones in their own list — so this never names a
+ * version the maintainer has withdrawn.
+ */
+export declare function hackageLatest(name: string, fetchFn: typeof fetch, signal?: AbortSignal): Promise<NpmVersionInfo | null>;
+/** Where a Haskell declaration begins, so a chunk never splits a signature. */
+export declare const HACKAGE_DECL_SPLIT_RE: RegExp;
+/**
+ * Reduce Haskell source to its public API surface: the module header with its
+ * export list, every top-level type signature, every type and class
+ * declaration, and the haddock attached to each.
+ *
+ * Equations go. In Haskell the signature IS the interface and the equations
+ * below it are the implementation, so dropping them loses nothing a caller can
+ * name — and an `instance` body is the same thing under another keyword, which
+ * is why only its head survives.
+ */
+/**
+ * Blank out `{- … -}` block comments, nesting included, keeping line count.
+ *
+ * Without this, code inside a comment is read as real API. `vector`'s
+ * `thawMany` is commented out and surfaced as a genuine signature sitting
+ * between two real functions — a plausible declaration for a function that does
+ * not exist, which is the worst answer this tool can give.
+ *
+ * `{-|` and `{-^` are haddock, not commentary, and are handled by the caller.
+ */
+export declare function stripBlockComments(src: string): string;
+export declare function haskellSurface(rawSrc: string): string;
+export declare function isHaskellFile(name: string): boolean;
+/** The `name:` field of the project's own `.cabal` file. */
+export declare function hackageProjectName(cwd: string): string | null;

package/dist/workers/eco-hackage.js

@@ -0,0 +1,508 @@
+/**
+ * eco-hackage — reading Haskell packages for the docs Worker tool.
+ *
+ * Two things make Haskell unlike the other rows.
+ *
+ * A package is distributed as a tarball, not as a checked-out tree: cabal keeps
+ * `<name>-<version>.tar.gz` and nothing else, so a package has to be extracted
+ * before it can be read. Extraction is a spawn, and a row's `resolve` is
+ * synchronous, so it happens in `acquire` — which is also where a package cabal
+ * has never fetched is downloaded from Hackage. Both paths end the same way: an
+ * extracted tree under the tool's own modules directory.
+ *
+ * And a Haskell MODULE name is not its PACKAGE name. `Data.Aeson` lives in
+ * `aeson`; asking Hackage for `Data.Aeson` finds nothing. That is the mistake
+ * issue #18 opened on, so it is refused by name with the correction in the
+ * message rather than silently missing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ResolveError } from './docs-resolve.js';
+import { findAtOrAbove } from './eco-cargo.js';
+const HACKAGE = 'https://hackage.haskell.org/package';
+/** Where cabal files a downloaded tarball, under any of its package directories. */
+const HACKAGE_REPO = 'hackage.haskell.org';
+export function isValidHackageName(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(name);
+}
+/** True for a dotted Haskell MODULE name, which is never a package name. */
+export function looksLikeModuleName(name) {
+    return /^[A-Z][A-Za-z0-9_']*(?:\.[A-Z][A-Za-z0-9_']*)+$/.test(name);
+}
+function safeRead(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** The first existing file at `rel` at or above `cwd`, siblings included. */
+function findUpOrDown(cwd, rel) {
+    return findAtOrAbove(cwd, ...rel);
+}
+/**
+ * Every package version this build resolved, name to version.
+ *
+ * Three sources in falling order of authority. `dist-newstyle/cache/plan.json` is
+ * what cabal actually built and is exact. A `cabal.project.freeze` is what the
+ * project asked for and is exact too, but may predate the build. `stack.yaml.lock`
+ * covers a stack project, which has no plan.json at all. None of them present is
+ * a real answer — the project pins nothing here — and the caller then falls back
+ * to whatever Hackage calls latest.
+ */
+export function resolvedVersions(cwd) {
+    const plan = findUpOrDown(cwd, ['dist-newstyle', 'cache', 'plan.json']);
+    if (plan) {
+        const parsed = parsePlanJson(safeRead(plan) ?? '');
+        if (parsed)
+            return parsed;
+    }
+    const freeze = findUpOrDown(cwd, ['cabal.project.freeze']);
+    if (freeze) {
+        const parsed = parseFreeze(safeRead(freeze) ?? '');
+        if (Object.keys(parsed).length)
+            return parsed;
+    }
+    const stackLock = findUpOrDown(cwd, ['stack.yaml.lock']);
+    if (stackLock) {
+        const parsed = parseStackLock(safeRead(stackLock) ?? '');
+        if (Object.keys(parsed).length)
+            return parsed;
+    }
+    return undefined;
+}
+export function parsePlanJson(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const plan = body['install-plan'];
+    if (!Array.isArray(plan))
+        return undefined;
+    const out = {};
+    for (const entry of plan) {
+        const name = entry['pkg-name'];
+        const version = entry['pkg-version'];
+        if (typeof name === 'string' && typeof version === 'string')
+            out[name] = version;
+    }
+    return out;
+}
+/**
+ * `cabal.project.freeze` states each pin as `any.<name> ==<version>`. Scanned
+ * across the whole file rather than line by line: cabal writes the first
+ * constraint on the `constraints:` line itself and the rest indented below it.
+ */
+export function parseFreeze(text) {
+    const out = {};
+    const re = /\bany\.([A-Za-z0-9-]+)\s*==\s*([0-9][0-9.]*)/g;
+    let m;
+    while ((m = re.exec(text)))
+        out[m[1]] = m[2];
+    return out;
+}
+/** `stack.yaml.lock` names each extra dep as `hackage: <name>-<version>@sha256:…`. */
+export function parseStackLock(text) {
+    const out = {};
+    for (const raw of text.split('\n')) {
+        const m = /hackage:\s*([A-Za-z0-9-]+)-([0-9][0-9.]*)@/.exec(raw);
+        if (m)
+            out[m[1]] = m[2];
+    }
+    return out;
+}
+export function hackageVersion(name, cwd) {
+    return resolvedVersions(cwd)?.[name] ?? null;
+}
+export function hackageTarballUrl(name, version) {
+    return `${HACKAGE}/${name}-${version}/${name}-${version}.tar.gz`;
+}
+/** The tarball cabal has already downloaded, in any of its package directories. */
+export function findCabalTarball(name, version, packageDirs) {
+    for (const dir of packageDirs) {
+        const candidate = path.join(dir, HACKAGE_REPO, name, version, `${name}-${version}.tar.gz`);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** Every version of `name` cabal holds a tarball for, oldest first. */
+export function cachedVersions(name, packageDirs) {
+    const found = new Set();
+    for (const dir of packageDirs) {
+        try {
+            for (const entry of fs.readdirSync(path.join(dir, HACKAGE_REPO, name))) {
+                if (/^[0-9]/.test(entry))
+                    found.add(entry);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return [...found].sort(compareVersions);
+}
+function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] || 0) - (pb[i] || 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/** Where the tool keeps its own extracted copies. */
+export function hackageExtractDir(modulesDir) {
+    return path.join(modulesDir, 'hackage');
+}
+function newestExtracted(dir, name) {
+    let best = null;
+    try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const cut = entry.name.lastIndexOf('-');
+            if (cut < 0 || entry.name.slice(0, cut) !== name)
+                continue;
+            const version = entry.name.slice(cut + 1);
+            if (!/^\d/.test(version))
+                continue;
+            if (!best || compareVersions(version, best.version) > 0) {
+                best = { root: path.join(dir, entry.name), version };
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return best;
+}
+const README_NAMES = ['README.md', 'README.markdown', 'readme.md', 'ReadMe.md', 'changelog.md'];
+function readmeIn(root) {
+    for (const name of README_NAMES) {
+        const abs = path.join(root, name);
+        if (fs.existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+/**
+ * The module that carries the package's headline API — `aeson` documents itself
+ * in `Data/Aeson.hs`. Matched by the last path segment, since a package name is
+ * lowercase and its module path is not.
+ */
+function entryIn(root, name) {
+    const wanted = `${name.replace(/-/g, '').toLowerCase()}.hs`;
+    const files = walkHaskell(root);
+    const headline = files.find(f => path.basename(f).toLowerCase() === wanted);
+    if (headline)
+        return headline;
+    return files[0] ?? null;
+}
+/** Library sources only — `tests/` and `benchmarks/` answer no API question. */
+export const HACKAGE_SKIP_DIRS = [
+    'tests',
+    'test',
+    'benchmarks',
+    'bench',
+    'examples',
+    'dist-newstyle',
+    'golden'
+];
+function walkHaskell(root) {
+    const out = [];
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (!HACKAGE_SKIP_DIRS.includes(entry.name)) {
+                    stack.push(path.join(dir, entry.name));
+                }
+            }
+            else if (entry.isFile() && entry.name.endsWith('.hs')) {
+                out.push(path.join(dir, entry.name));
+            }
+        }
+    }
+    return out.sort();
+}
+/**
+ * Find an EXTRACTED package. A tarball cabal holds is not readable in place, and
+ * unpacking it is a spawn, so getting it into this state is `acquire`'s job.
+ */
+export function resolveHackage(name, cwd, dirs) {
+    if (looksLikeModuleName(name)) {
+        throw new ResolveError('invalid_name', `"${name}" is a Haskell MODULE name. Pass the Hackage PACKAGE that ships it `
+            + '(for example "aeson", not "Data.Aeson").');
+    }
+    if (!isValidHackageName(name)) {
+        throw new ResolveError('invalid_name', `Invalid Hackage package name: "${name}"`);
+    }
+    const extractDir = hackageExtractDir(dirs.modulesDir);
+    const pinned = hackageVersion(name, cwd);
+    const exact = pinned ? path.join(extractDir, `${name}-${pinned}`) : null;
+    // A pin that is not unpacked is not_installed, NOT an invitation to answer from
+    // whatever version another build left behind. Nothing marks that substitution,
+    // so the version banner stays empty and the swap reaches the model silently.
+    const found = exact ?
+        fs.existsSync(exact) ?
+            { root: exact, version: pinned }
+            : null
+        : newestExtracted(extractDir, name);
+    if (!found) {
+        throw new ResolveError('not_installed', `Hackage package "${name}"${pinned ? ` v${pinned}` : ''} is not unpacked under `
+            + `${extractDir}.`);
+    }
+    return {
+        ecosystem: 'hackage',
+        name,
+        version: found.version,
+        root: found.root,
+        entry: entryIn(found.root, name),
+        readme: readmeIn(found.root)
+    };
+}
+/**
+ * The newest version Hackage does not deprecate. `/preferred` returns them newest
+ * first, with the deprecated ones in their own list — so this never names a
+ * version the maintainer has withdrawn.
+ */
+export async function hackageLatest(name, fetchFn, signal) {
+    if (!isValidHackageName(name))
+        return null;
+    try {
+        const response = await fetchFn(`${HACKAGE}/${encodeURIComponent(name)}/preferred`, {
+            headers: { accept: 'application/json' },
+            ...(signal ? { signal } : {})
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        const versions = body['normal-version'];
+        if (!Array.isArray(versions) || typeof versions[0] !== 'string')
+            return null;
+        return { pkg: name, latest: versions[0], recent: versions.slice(0, 10) };
+    }
+    catch {
+        return null;
+    }
+}
+// ── surface extraction ──────────────────────────────────────────────────────
+/** Where a Haskell declaration begins, so a chunk never splits a signature. */
+export const HACKAGE_DECL_SPLIT_RE = /^(?:[a-z_][\w']*\s*::|data\s|newtype\s|type\s|class\s|instance\s|pattern\s)/m;
+const SIGNATURE_RE = /^[a-z_][\w']*(?:\s*,\s*[a-z_][\w']*)*\s*::/;
+const OPERATOR_SIGNATURE_RE = /^\([^)]+\)\s*::/;
+/** The same heads with the `::` wrapped onto the next line. */
+const BARE_NAME_RE = /^(?:[a-z_][\w']*|\([^)]+\))(?:\s*,\s*(?:[a-z_][\w']*|\([^)]+\)))*\s*$/;
+const TYPE_HEAD_RE = /^(data|newtype|type|class|instance|pattern|foreign import)\b/;
+const HADDOCK_RE = /^--\s*[|^]/;
+/**
+ * Reduce Haskell source to its public API surface: the module header with its
+ * export list, every top-level type signature, every type and class
+ * declaration, and the haddock attached to each.
+ *
+ * Equations go. In Haskell the signature IS the interface and the equations
+ * below it are the implementation, so dropping them loses nothing a caller can
+ * name — and an `instance` body is the same thing under another keyword, which
+ * is why only its head survives.
+ */
+/**
+ * Blank out `{- … -}` block comments, nesting included, keeping line count.
+ *
+ * Without this, code inside a comment is read as real API. `vector`'s
+ * `thawMany` is commented out and surfaced as a genuine signature sitting
+ * between two real functions — a plausible declaration for a function that does
+ * not exist, which is the worst answer this tool can give.
+ *
+ * `{-|` and `{-^` are haddock, not commentary, and are handled by the caller.
+ */
+export function stripBlockComments(src) {
+    const out = [];
+    let depth = 0;
+    for (const line of src.split('\n')) {
+        let kept = '';
+        let i = 0;
+        while (i < line.length) {
+            if (line.startsWith('{-', i) && !isHaddockOpen(line, i)) {
+                depth++;
+                i += 2;
+                continue;
+            }
+            if (line.startsWith('-}', i) && depth > 0) {
+                depth--;
+                i += 2;
+                continue;
+            }
+            // A `--` line comment outside a block runs to end of line, and may
+            // legitimately contain `{-`.
+            if (depth === 0 && line.startsWith('--', i)) {
+                kept += line.slice(i);
+                break;
+            }
+            if (depth === 0)
+                kept += line[i];
+            i++;
+        }
+        out.push(kept);
+    }
+    return out.join('\n');
+}
+/** `{-|` and `{-^` open haddock; `{-#` opens a pragma, which is not a comment. */
+function isHaddockOpen(line, i) {
+    const c = line[i + 2];
+    return c === '|' || c === '^' || c === '#';
+}
+/** A `{-| … -}` haddock block, flattened to the `-- |` form the rest of the pass keeps. */
+function haddockBlockAt(lines, start) {
+    if (!/^\{-[|^]/.test(lines[start].trim()))
+        return null;
+    const text = [];
+    for (let i = start; i < lines.length; i++) {
+        const closed = lines[i].includes('-}');
+        text.push(`-- ${lines[i]
+            .replace(/^\s*\{-[|^]?/, '')
+            .replace(/-\}\s*$/, '')
+            .trim()}`);
+        if (closed)
+            return { text: text.filter(l => l.trim() !== '--'), next: i + 1 };
+    }
+    return { text: text.filter(l => l.trim() !== '--'), next: lines.length };
+}
+export function haskellSurface(rawSrc) {
+    // Haddock blocks survive; ordinary `{- … -}` commentary does not.
+    const src = stripBlockComments(rawSrc);
+    const lines = src.split('\n');
+    const out = [];
+    let i;
+    // The export list is the module's own statement of its API, and it spans
+    // however many lines it takes to balance the parentheses.
+    const moduleStart = lines.findIndex(l => /^module\s/.test(l));
+    if (moduleStart >= 0) {
+        // The `{-| Module : … -}` header sits ABOVE the `module` keyword, and for
+        // most Hackage packages it IS the headline documentation. Emitting from
+        // `module` down dropped every line of it.
+        for (let h = 0; h < moduleStart; h++) {
+            const block = haddockBlockAt(lines, h);
+            if (!block)
+                continue;
+            out.push(...block.text);
+            h = block.next - 1;
+        }
+        if (out.length)
+            out.push('');
+        let depth = 0;
+        let seenParen = false;
+        for (i = moduleStart; i < lines.length; i++) {
+            out.push(lines[i]);
+            for (const c of lines[i]) {
+                if (c === '(') {
+                    depth++;
+                    seenParen = true;
+                }
+                else if (c === ')')
+                    depth--;
+            }
+            if (/\bwhere\b/.test(lines[i]) && (!seenParen || depth <= 0)) {
+                i++;
+                break;
+            }
+        }
+        out.push('');
+    }
+    else {
+        i = 0;
+    }
+    let pending = [];
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === '') {
+            i++;
+            continue;
+        }
+        if (/^\s/.test(line)) {
+            // A continuation with no head above it belongs to something dropped.
+            i++;
+            continue;
+        }
+        if (HADDOCK_RE.test(line)) {
+            pending.push(line);
+            i++;
+            continue;
+        }
+        // `{-| … -}` is how most modules write their documentation, and the
+        // module header block above all. Dropping it loses the part a reader
+        // actually wants.
+        const haddockBlock = haddockBlockAt(lines, i);
+        if (haddockBlock) {
+            pending.push(...haddockBlock.text);
+            i = haddockBlock.next;
+            continue;
+        }
+        if (line.startsWith('--') || line.startsWith('{-#') || /^import\s/.test(line)) {
+            pending = [];
+            i++;
+            continue;
+        }
+        const block = [line];
+        let j = i + 1;
+        while (j < lines.length && (lines[j].trim() === '' || /^\s/.test(lines[j]))) {
+            block.push(lines[j]);
+            j++;
+        }
+        // Drop the blank tail the block picked up on its way to the next head.
+        while (block.length && block[block.length - 1].trim() === '')
+            block.pop();
+        // A signature whose `::` starts the CONTINUATION line is the same
+        // declaration, and it is how most multi-constraint signatures are written:
+        //     decode
+        //       :: FromJSON a
+        //       => ByteString -> Maybe a
+        // Matching the head line alone drops those, and their haddock with them.
+        const wrappedSignature = BARE_NAME_RE.test(line) && (block[1]?.trim().startsWith('::') ?? false);
+        if (SIGNATURE_RE.test(line) || OPERATOR_SIGNATURE_RE.test(line) || wrappedSignature) {
+            out.push(...pending, ...block, '');
+        }
+        else if (TYPE_HEAD_RE.test(line)) {
+            const head = TYPE_HEAD_RE.exec(line)[1];
+            // An instance's indented lines are definitions, not fields.
+            out.push(...pending, ...(head === 'instance' ? [line] : block), '');
+        }
+        pending = [];
+        i = j;
+    }
+    return out
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function isHaskellFile(name) {
+    return name.endsWith('.hs');
+}
+/** The `name:` field of the project's own `.cabal` file. */
+export function hackageProjectName(cwd) {
+    let entries;
+    try {
+        entries = fs.readdirSync(cwd);
+    }
+    catch {
+        return null;
+    }
+    const cabal = entries.find(e => e.endsWith('.cabal'));
+    if (!cabal)
+        return null;
+    const match = /^\s*name\s*:\s*(\S+)/m.exec(safeRead(path.join(cwd, cabal)) ?? '');
+    return match ? match[1] : null;
+}

package/dist/workers/npm-version.d.ts

@@ -44,6 +44,8 @@ export interface NpmVersionOpts {
  */
 export declare function npmVersionLookup(pkg: string, opts?: NpmVersionOpts): Promise<NpmVersionInfo | null>;
 /** Format an NpmVersionInfo as a short Markdown block for EXTERNAL CONTEXT: a
- *  `### npm: <pkg>` heading, a `latest:` line that gains ` (published YYYY-MM-DD)`
- *  when the date is known, and a `recent:` line only when the list is non-empty. */
-export declare function formatNpmVersionSection(info: NpmVersionInfo): string;
+ *  `### <registry>: <pkg>` heading, a `latest:` line that gains ` (published
+ *  YYYY-MM-DD)` when the date is known, and a `recent:` line only when the list is
+ *  non-empty. The label defaults to npm, which is where every caller but the docs
+ *  tool's non-npm rows reads from. */
+export declare function formatNpmVersionSection(info: NpmVersionInfo, label?: string): string;

package/dist/workers/npm-version.js

@@ -73,10 +73,12 @@ export async function npmVersionLookup(pkg, opts = {}) {
     }
 }
 /** Format an NpmVersionInfo as a short Markdown block for EXTERNAL CONTEXT: a
- *  `### npm: <pkg>` heading, a `latest:` line that gains ` (published YYYY-MM-DD)`
- *  when the date is known, and a `recent:` line only when the list is non-empty. */
-export function formatNpmVersionSection(info) {
-    const lines = [`### npm: ${info.pkg}`, `latest: ${info.latest}`];
+ *  `### <registry>: <pkg>` heading, a `latest:` line that gains ` (published
+ *  YYYY-MM-DD)` when the date is known, and a `recent:` line only when the list is
+ *  non-empty. The label defaults to npm, which is where every caller but the docs
+ *  tool's non-npm rows reads from. */
+export function formatNpmVersionSection(info, label = 'npm') {
+    const lines = [`### ${label}: ${info.pkg}`, `latest: ${info.latest}`];
     if (info.publishedAt) {
         const date = info.publishedAt.slice(0, 10);
         lines[1] += ` (published ${date})`;

package/dist/workers/pi-worker-docs.d.ts

@@ -3,8 +3,10 @@ import { openCache as defaultOpenCache } from './docs-cache.js';
 import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
 import { resolvePackage as defaultResolvePackage } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
+import { type EcosystemId } from './docs-ecosystems.js';
 import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import type { SpawnFn } from '../shared/child-process.js';
+import { type CachePackage } from './shared.js';
 interface DocsDetails {
     version?: string;
     hitCache?: boolean;
@@ -13,7 +15,9 @@ interface DocsDetails {
     childExitCode?: number;
     indexingMs?: number;
     indexedFiles?: number;
-    resolveError?: 'not_installed' | 'invalid_name';
+    /** Which registry the answer was read from. Absent for the project-source path. */
+    ecosystem?: EcosystemId;
+    resolveError?: 'not_installed' | 'invalid_name' | 'unsupported_ecosystem' | 'ambiguous_ecosystem';
     cacheError?: string;
     aborted?: boolean;
     autoInstalled?: boolean;
@@ -73,14 +77,24 @@ export declare function docsCacheable(d: Pick<DocsDetails, 'typeOnly' | 'excerpt
 /** The docs cache key: a package's answer is per (module, question), with the question
  *  lowercased and its whitespace collapsed so phrasing variants share one entry. Returns
  *  null for the project-source `.` lookup, which is never cached — the working tree
- *  mutates as tasks implement. */
+ *  mutates as tasks implement.
+ *
+ *  The ecosystem joins the key only when the caller named one, so the keys of every
+ *  call that lets the manifest decide are the ones they always were. */
 export declare function docsCacheKey(params: {
     module: string;
     query: string;
+    ecosystem?: string;
 }): string | null;
 /** Package provenance for per-entry resume invalidation: the package ROOT of the
- *  specifier (`hono/client` → `hono`), and undefined for the project-source `.`. */
+ *  specifier (`hono/client` → `hono`), and undefined for the project-source `.`.
+ *
+ *  The ecosystem comes from the RESOLVED lookup, not from the optional argument.
+ *  Reading the argument would record npm for every single-manifest cargo or cabal
+ *  project — the ordinary case, since the argument only exists to disambiguate a
+ *  polyglot repo — and the entry's version would then be looked for in a
+ *  `package.json` that is not there, leaving it un-prunable forever. */
 export declare function docsCachePkg(params: {
     module: string;
-}): string | undefined;
+}, details: Pick<DocsDetails, 'ecosystem'>): CachePackage | undefined;
 export {};