@mjasnikovs/pi-task 0.40.28 → 0.40.30

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-4508%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-4631%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -201,11 +201,14 @@ Resolves an installed package, indexes its API surface and README into a local S
 | `npm` | `package.json`, or a `node_modules/` directory | the `.d.ts` files the package ships, plus README | the installed `package.json` |
 | `cargo` | `Cargo.toml`, at the directory or one level below it | `.rs` source reduced to public item heads, doc comments and attributes | `Cargo.lock` |
 | `hackage` | `*.cabal`, `cabal.project`, `stack.yaml` or `package.yaml` | `.hs` source reduced to the export list, signatures and type declarations | `dist-newstyle/cache/plan.json`, then `cabal.project.freeze`, then `stack.yaml.lock` |
+| `go` | `go.mod` or `go.work`, at the directory, above it or one level below | `.go` source reduced to exported declarations, struct fields, interface methods and doc comments | `go.mod`, which since Go 1.17 carries the resolved closure |
 
 - **No manifest, no lookup.** In a directory with none of the above the tool refuses, spawns nothing and installs nothing, and points you at `pi-worker-search` / `pi-worker-fetch` instead.
 - **Two manifests** (a Tauri app, say) are resolved by whichever registry already has the package on disk. If neither does, the call is refused as ambiguous and you pass `ecosystem: "cargo"` to say which.
-- A package the project does not have is fetched once into a dedicated cache dir: `npm install --ignore-scripts` for npm, the `.crate` tarball for cargo, the Hackage tarball (or cabal's own cached copy) for hackage.
+- A package the project does not have is fetched once into a dedicated cache dir: `npm install --ignore-scripts` for npm, the `.crate` tarball for cargo, the Hackage tarball (or cabal's own cached copy) for hackage, the module zip from `proxy.golang.org` for go.
 - A Haskell **module** name is refused by name — `Data.Aeson` is not a package, `aeson` is.
+- For **go you pass the import path**, `github.com/gin-gonic/gin/binding` or `net/http`, because that is what a Go file names. The module serving it is worked out by asking the proxy for the longest prefix that resolves — `gin/binding` belongs to `gin`, while `aws-sdk-go-v2/service/s3` is its own module. Vendored source and the local module cache are read first and cost nothing.
+- The **Go standard library** is not on the proxy. It is read from a local `GOROOT` where there is one, and otherwise sliced out of the `golang.org/toolchain` archive over HTTP range requests — about 2 MB for `net/http` against 83 MB for the archive.
 - The first call for a `(ecosystem, package, version)` triple pays a one-time ingestion cost; later calls are FTS-only.
 - Cache lives at `${XDG_CACHE_HOME:-~/.cache}/pi-worker/docs.sqlite` — delete it to reset.
 
@@ -260,7 +263,7 @@ them checked in.
 
 ```sh
 bun install
-bun run test       # 4508 tests pass across 243 files (1 skip)
+bun run test       # 4631 tests pass across 247 files (1 skip)
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/dist/shared/zip.d.ts

@@ -0,0 +1,86 @@
+/**
+ * zip — reading a zip archive in-process, whole or a slice at a time.
+ *
+ * Go module zips are why this exists. `unzip` is absent from a default Windows
+ * install and GNU tar cannot read zip at all, so shelling out behaves
+ * differently on every machine the agent runs on.
+ *
+ * The slice half is what makes the Go standard library affordable. It ships
+ * inside an 83 MB toolchain archive of which any one package is under a
+ * megabyte, and a reader that can pull the central directory and then only the
+ * entries it wants leaves the other 82 MB on the server.
+ */
+/** The comment is a 16-bit length, so the EOCD starts no further back than this. */
+export declare const EOCD_SEARCH_SPAN: number;
+export interface ZipEntry {
+    name: string;
+    method: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    /** Offset of the entry's LOCAL header, which is not where its data begins. */
+    localHeaderOffset: number;
+}
+interface CentralDirectoryLocation {
+    offset: number;
+    size: number;
+}
+/**
+ * Where the central directory is, given the tail of the file.
+ *
+ * `tailStart` is that tail's offset in the whole archive, so a caller that
+ * fetched only the last few kilobytes still gets absolute offsets back.
+ */
+export declare function findCentralDirectory(tail: Buffer, tailStart?: number): CentralDirectoryLocation;
+/**
+ * The entries a central directory declares.
+ *
+ * Sizes come from HERE and never from a local header: every Go module zip sets
+ * the data-descriptor flag, which zeroes the size and CRC fields in the local
+ * header and moves the real values to a trailer after the data.
+ */
+export declare function parseCentralDirectory(cd: Buffer): ZipEntry[];
+/**
+ * Where an entry's compressed bytes start, read from its LOCAL header.
+ *
+ * The local header's name and extra lengths are its own and may differ from the
+ * central directory's — deriving this from the central record produces an offset
+ * that is silently a few bytes wrong.
+ */
+export declare function dataOffset(local: Buffer, at: number): number;
+/** Decompress one entry's raw bytes. */
+export declare function inflateEntry(raw: Buffer, method: number): Buffer;
+/** Every entry of an archive held whole in memory. */
+export declare function readZip(archive: Buffer): ZipEntry[];
+/** One entry's decompressed content, from an archive held whole in memory. */
+export declare function readEntry(archive: Buffer, entry: ZipEntry): Buffer;
+/**
+ * True for an entry path that would write outside its destination directory.
+ * A module zip has never carried one; a malicious archive is the reason to look.
+ */
+export declare function isUnsafeEntryName(name: string): boolean;
+export interface ExtractOptions {
+    /** Which entries to write. Directory entries are absent from a module zip. */
+    filter?: (entry: ZipEntry) => boolean;
+    /** Path segments to drop from the front of every name, for a prefixed archive. */
+    strip?: number;
+}
+/** Write an in-memory archive's entries under `dest`. Returns what was written. */
+export declare function extractZip(archive: Buffer, dest: string, options?: ExtractOptions): string[];
+/** Fetch `[start, end]` inclusive, the way an HTTP Range request is written. */
+export type RangeFetch = (start: number, end: number) => Promise<Buffer>;
+/**
+ * The entries of a remote archive, read from its tail alone.
+ *
+ * Two requests: the tail, then the central directory. `size` is the archive's
+ * total length, which a HEAD or the first ranged response reports.
+ */
+export declare function readRemoteZip(size: number, fetchRange: RangeFetch): Promise<ZipEntry[]>;
+/**
+ * Fetch some entries of a remote archive, coalescing neighbours into one request.
+ *
+ * Zip entries are laid out in central-directory order, and the entries of one
+ * directory are almost always adjacent, so a package's files come back as a
+ * single contiguous read.
+ */
+export declare function readRemoteEntries(entries: readonly ZipEntry[], fetchRange: RangeFetch): Promise<Map<string, Buffer>>;
+export {};

package/dist/shared/zip.js

@@ -0,0 +1,251 @@
+/**
+ * zip — reading a zip archive in-process, whole or a slice at a time.
+ *
+ * Go module zips are why this exists. `unzip` is absent from a default Windows
+ * install and GNU tar cannot read zip at all, so shelling out behaves
+ * differently on every machine the agent runs on.
+ *
+ * The slice half is what makes the Go standard library affordable. It ships
+ * inside an 83 MB toolchain archive of which any one package is under a
+ * megabyte, and a reader that can pull the central directory and then only the
+ * entries it wants leaves the other 82 MB on the server.
+ */
+import { inflateRawSync } from 'node:zlib';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const EOCD_SIG = 0x06054b50;
+const ZIP64_EOCD_SIG = 0x06064b50;
+const ZIP64_LOCATOR_SIG = 0x07064b50;
+const CDFH_SIG = 0x02014b50;
+const EOCD_SIZE = 22;
+const ZIP64_LOCATOR_SIZE = 20;
+const LOCAL_HEADER_FIXED = 30;
+/** A 32-bit field carrying this asks to be read from the zip64 extra field. */
+const ZIP64_SENTINEL = 0xffffffff;
+/** The comment is a 16-bit length, so the EOCD starts no further back than this. */
+export const EOCD_SEARCH_SPAN = 0xffff + EOCD_SIZE;
+const STORED = 0;
+const DEFLATED = 8;
+/**
+ * Where the central directory is, given the tail of the file.
+ *
+ * `tailStart` is that tail's offset in the whole archive, so a caller that
+ * fetched only the last few kilobytes still gets absolute offsets back.
+ */
+export function findCentralDirectory(tail, tailStart = 0) {
+    const eocd = lastIndexOfSignature(tail, EOCD_SIG);
+    if (eocd < 0)
+        throw new Error('not a zip archive: no end-of-central-directory record');
+    const size = tail.readUInt32LE(eocd + 12);
+    const offset = tail.readUInt32LE(eocd + 16);
+    if (size !== ZIP64_SENTINEL && offset !== ZIP64_SENTINEL)
+        return { offset, size };
+    const locator = eocd - ZIP64_LOCATOR_SIZE;
+    if (locator < 0 || tail.readUInt32LE(locator) !== ZIP64_LOCATOR_SIG) {
+        throw new Error('zip64 archive without a zip64 locator');
+    }
+    const zip64Eocd = Number(tail.readBigUInt64LE(locator + 8)) - tailStart;
+    if (zip64Eocd < 0 || tail.readUInt32LE(zip64Eocd) !== ZIP64_EOCD_SIG) {
+        throw new Error('zip64 end-of-central-directory record is outside the read span');
+    }
+    return {
+        size: Number(tail.readBigUInt64LE(zip64Eocd + 40)),
+        offset: Number(tail.readBigUInt64LE(zip64Eocd + 48))
+    };
+}
+function lastIndexOfSignature(buf, sig) {
+    for (let i = buf.length - 4; i >= 0; i--) {
+        if (buf.readUInt32LE(i) === sig)
+            return i;
+    }
+    return -1;
+}
+/**
+ * The entries a central directory declares.
+ *
+ * Sizes come from HERE and never from a local header: every Go module zip sets
+ * the data-descriptor flag, which zeroes the size and CRC fields in the local
+ * header and moves the real values to a trailer after the data.
+ */
+export function parseCentralDirectory(cd) {
+    const entries = [];
+    let at = 0;
+    while (at + 46 <= cd.length && cd.readUInt32LE(at) === CDFH_SIG) {
+        const nameLen = cd.readUInt16LE(at + 28);
+        const extraLen = cd.readUInt16LE(at + 30);
+        const commentLen = cd.readUInt16LE(at + 32);
+        const entry = {
+            name: cd.toString('utf8', at + 46, at + 46 + nameLen),
+            method: cd.readUInt16LE(at + 10),
+            compressedSize: cd.readUInt32LE(at + 20),
+            uncompressedSize: cd.readUInt32LE(at + 24),
+            localHeaderOffset: cd.readUInt32LE(at + 42)
+        };
+        applyZip64Extra(entry, cd.subarray(at + 46 + nameLen, at + 46 + nameLen + extraLen));
+        entries.push(entry);
+        at += 46 + nameLen + extraLen + commentLen;
+    }
+    return entries;
+}
+/**
+ * Zip64 widens only the fields that overflowed, and packs them in that order.
+ * Reading a fixed layout would misplace every value on an entry that overflowed
+ * one field but not the one before it.
+ */
+function applyZip64Extra(entry, extra) {
+    let at = 0;
+    while (at + 4 <= extra.length) {
+        const id = extra.readUInt16LE(at);
+        const size = extra.readUInt16LE(at + 2);
+        if (id !== 0x0001) {
+            at += 4 + size;
+            continue;
+        }
+        let field = at + 4;
+        const next = () => {
+            const v = Number(extra.readBigUInt64LE(field));
+            field += 8;
+            return v;
+        };
+        if (entry.uncompressedSize === ZIP64_SENTINEL)
+            entry.uncompressedSize = next();
+        if (entry.compressedSize === ZIP64_SENTINEL)
+            entry.compressedSize = next();
+        if (entry.localHeaderOffset === ZIP64_SENTINEL)
+            entry.localHeaderOffset = next();
+        return;
+    }
+}
+/**
+ * Where an entry's compressed bytes start, read from its LOCAL header.
+ *
+ * The local header's name and extra lengths are its own and may differ from the
+ * central directory's — deriving this from the central record produces an offset
+ * that is silently a few bytes wrong.
+ */
+export function dataOffset(local, at) {
+    return at + LOCAL_HEADER_FIXED + local.readUInt16LE(at + 26) + local.readUInt16LE(at + 28);
+}
+/** Decompress one entry's raw bytes. */
+export function inflateEntry(raw, method) {
+    if (method === STORED)
+        return raw;
+    if (method === DEFLATED)
+        return inflateRawSync(raw);
+    throw new Error(`unsupported zip compression method ${method}`);
+}
+/** Every entry of an archive held whole in memory. */
+export function readZip(archive) {
+    const tailStart = Math.max(0, archive.length - EOCD_SEARCH_SPAN);
+    const { offset, size } = findCentralDirectory(archive.subarray(tailStart), tailStart);
+    return parseCentralDirectory(archive.subarray(offset, offset + size));
+}
+/** One entry's decompressed content, from an archive held whole in memory. */
+export function readEntry(archive, entry) {
+    const start = dataOffset(archive, entry.localHeaderOffset);
+    return inflateEntry(archive.subarray(start, start + entry.compressedSize), entry.method);
+}
+/**
+ * True for an entry path that would write outside its destination directory.
+ * A module zip has never carried one; a malicious archive is the reason to look.
+ */
+export function isUnsafeEntryName(name) {
+    if (name === '' || path.isAbsolute(name) || /^[A-Za-z]:/.test(name))
+        return true;
+    return name.split(/[/\\]/).some(seg => seg === '..');
+}
+/** Write an in-memory archive's entries under `dest`. Returns what was written. */
+export function extractZip(archive, dest, options = {}) {
+    const written = [];
+    for (const entry of readZip(archive)) {
+        if (entry.name.endsWith('/'))
+            continue;
+        if (options.filter && !options.filter(entry))
+            continue;
+        if (isUnsafeEntryName(entry.name))
+            continue;
+        const rel = stripSegments(entry.name, options.strip ?? 0);
+        if (rel === null)
+            continue;
+        const target = path.join(dest, rel);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, readEntry(archive, entry));
+        written.push(target);
+    }
+    return written;
+}
+function stripSegments(name, count) {
+    if (count === 0)
+        return name;
+    const parts = name.split('/');
+    return parts.length > count ? parts.slice(count).join('/') : null;
+}
+/**
+ * The entries of a remote archive, read from its tail alone.
+ *
+ * Two requests: the tail, then the central directory. `size` is the archive's
+ * total length, which a HEAD or the first ranged response reports.
+ */
+export async function readRemoteZip(size, fetchRange) {
+    const tailStart = Math.max(0, size - EOCD_SEARCH_SPAN);
+    const tail = await fetchRange(tailStart, size - 1);
+    const cd = findCentralDirectory(tail, tailStart);
+    const held = cd.offset - tailStart;
+    const bytes = held >= 0 && held + cd.size <= tail.length ?
+        tail.subarray(held, held + cd.size)
+        : await fetchRange(cd.offset, cd.offset + cd.size - 1);
+    return parseCentralDirectory(bytes);
+}
+/**
+ * Room for a local header whose name and extra fields we have not read yet.
+ * Go's zip writer emits no local extra field, so this is slack, not a guess at a
+ * real value — an entry that overruns it is re-fetched exactly.
+ */
+const LOCAL_HEADER_SLACK = 4096;
+/**
+ * A gap worth paying for rather than opening a second connection. Well under the
+ * bytes a TCP slow-start ramp wastes on an extra round trip.
+ */
+const COALESCE_GAP = 64 * 1024;
+/**
+ * Fetch some entries of a remote archive, coalescing neighbours into one request.
+ *
+ * Zip entries are laid out in central-directory order, and the entries of one
+ * directory are almost always adjacent, so a package's files come back as a
+ * single contiguous read.
+ */
+export async function readRemoteEntries(entries, fetchRange) {
+    const out = new Map();
+    const ordered = [...entries].sort((a, b) => a.localHeaderOffset - b.localHeaderOffset);
+    for (const span of coalesce(ordered)) {
+        const buf = await fetchRange(span.start, span.end);
+        for (const entry of span.entries) {
+            const at = entry.localHeaderOffset - span.start;
+            const from = dataOffset(buf, at);
+            const to = from + entry.compressedSize;
+            const raw = to <= buf.length ? buf.subarray(from, to) : await refetch(entry, fetchRange);
+            out.set(entry.name, inflateEntry(raw, entry.method));
+        }
+    }
+    return out;
+}
+async function refetch(entry, fetchRange) {
+    const head = await fetchRange(entry.localHeaderOffset, entry.localHeaderOffset + LOCAL_HEADER_FIXED - 1);
+    const start = dataOffset(head, 0) + entry.localHeaderOffset;
+    return fetchRange(start, start + entry.compressedSize - 1);
+}
+function coalesce(ordered) {
+    const spans = [];
+    for (const entry of ordered) {
+        const start = entry.localHeaderOffset;
+        const end = start + LOCAL_HEADER_FIXED + LOCAL_HEADER_SLACK + entry.compressedSize - 1;
+        const last = spans[spans.length - 1];
+        if (last && start - last.end <= COALESCE_GAP) {
+            last.end = Math.max(last.end, end);
+            last.entries.push(entry);
+            continue;
+        }
+        spans.push({ start, end, entries: [entry] });
+    }
+    return spans;
+}

package/dist/workers/docs-core.js

@@ -283,7 +283,7 @@ export async function acquirePackage(input) {
         const pin = declaredRange ?
             { source: 'declared-range', range: declaredRange, asked }
             : { source: 'npm-latest', asked };
-        const install = await profile.acquire(asked, declaredRange, io);
+        const install = await profile.acquire(asked, declaredRange, cwd, io);
         if (!install.success) {
             return { ok: false, stage: 'install', stderr: install.stderr, pin, asked };
         }

package/dist/workers/docs-ecosystems.d.ts

@@ -18,7 +18,7 @@ import { resolvePackage, type ResolvedPackage } from './docs-resolve.js';
 import { npmVersionLookup, type NpmVersionInfo } from './npm-version.js';
 import { type SpawnFn } from '../shared/child-process.js';
 import type { ExportGap } from './export-gap.js';
-export type EcosystemId = 'npm' | 'cargo' | 'hackage';
+export type EcosystemId = 'npm' | 'cargo' | 'hackage' | 'go';
 /**
  * Every filesystem, process and network reach a row is allowed. Rows read no
  * environment and call no global directly, so a test injects a fake registry and
@@ -33,6 +33,10 @@ export interface EcosystemIo {
     cargoHome: string;
     /** Every directory cabal may have filed a downloaded tarball under. */
     cabalPackageDirs: readonly string[];
+    /** Root of the Go module cache — `GOMODCACHE`, or its default. */
+    goModCache: string;
+    /** A local Go installation, whose `src/` is the standard library. */
+    goroot: string | undefined;
     signal?: AbortSignal | undefined;
 }
 /**
@@ -63,8 +67,14 @@ export interface EcosystemProfile {
     resolve: (name: string, cwd: string, io: EcosystemIo) => ResolvedPackage;
     /** The version range the project pins this package to, if it pins one. */
     declaredRange: (name: string, cwd: string) => string | null;
-    /** Fetch a package that is not on disk into `io.modulesDir`. */
-    acquire: (name: string, range: string | null, io: EcosystemIo) => Promise<AcquireResult>;
+    /**
+     * Fetch a package that is not on disk into `io.modulesDir`.
+     *
+     * `cwd` is the project, not the destination: Go reads its `go` directive to
+     * pick which toolchain's standard library an answer should describe, and to
+     * tell `net/http` from a dotless module's own `myapp/internal/db`.
+     */
+    acquire: (name: string, range: string | null, cwd: string, io: EcosystemIo) => Promise<AcquireResult>;
     /**
      * A second resolution hop, for ecosystems where the package that ships the
      * documented surface is not the one that was asked for.
@@ -122,6 +132,15 @@ export interface EcosystemProfile {
     commentPrefix: string;
     /** Directories the surface walk never descends into: tests, build output. */
     skipDirs: readonly string[];
+    /**
+     * Narrow the walked files to one copy of each declaration.
+     *
+     * Two ecosystems ship the same API twice in one package: npm as `.d.ts` and
+     * `.d.cts` twins, Go as build-tag variants of one file. Both cost the
+     * retrieval budget for text the reader already has, and neither is
+     * separable downstream — same identifiers, same package, same version.
+     */
+    selectFiles?: (files: readonly string[], pkg: ResolvedPackage) => string[];
     /** What this ecosystem's packages ship, for a "there is nothing to read" answer. */
     surfaceLabel: string;
     /**
@@ -167,6 +186,7 @@ export declare const ECOSYSTEMS: {
     readonly npm: EcosystemProfile;
     readonly cargo: EcosystemProfile;
     readonly hackage: EcosystemProfile;
+    readonly go: EcosystemProfile;
 };
 /** Which ecosystems `cwd` looks like a project of, in roster order. */
 export declare function detectEcosystems(cwd: string, roster?: readonly EcosystemProfile[]): EcosystemId[];

package/dist/workers/docs-ecosystems.js

@@ -20,9 +20,12 @@ import * as path from 'node:path';
 import { runAutoInstall, findDeclaredRange, extractParentPackage, resolveTypeSourceForDocs, getDocsModulesDir } from './docs-core.js';
 import { resolvePackage, isDtsFile, isValidModuleName } from './docs-resolve.js';
 import { DECL_SPLIT_RE, MEMBER_SPLIT_RE } from './docs-chunk.js';
+import { dropParallelDeclarations } from './docs-index.js';
 import { npmVersionLookup } from './npm-version.js';
 import { resolveCrate, cratesLatest, crateTarballUrl, crateOf, isValidCrateName, isRustFile, lockedVersion, rustSurface, cargoProjectName, childDirs, lockedDeps, manifestCrates, cargoExportGap, cargoContentFingerprint, cargoSupplementCandidates, CARGO_DECL_SPLIT_RE, CARGO_MEMBER_SPLIT_RE } from './eco-cargo.js';
 import { resolveHackage, hackageLatest, hackageVersion, hackageTarballUrl, hackageExtractDir, hackageProjectName, supplementCandidates, hackageExportGap, hackageContentFingerprint, findCabalTarball, cachedVersions, resolvedVersions, manifestPackages, isValidHackageName, isHaskellFile, haskellSurface, HACKAGE_DECL_SPLIT_RE, HACKAGE_SKIP_DIRS, HACKAGE_MEMBER_SPLIT_RE } from './eco-hackage.js';
+import { detectGo, isValidImportPath, resolveGoPackage, acquireGoModule, goDeclaredVersion, goLatest, goProjectName, goDeclaredDeps, goManifestDeps, isGoFile, selectBuildVariants, selectOwnPackage, defaultGoModCache, goContentFingerprintParts } from './eco-go.js';
+import { goSurface, goContentFingerprint, GO_DECL_SPLIT_RE, GO_MEMBER_SPLIT_RE } from './go-surface.js';
 import { runChild } from '../shared/child-process.js';
 /**
  * Is any of `names` present at `cwd` or above it?
@@ -76,6 +79,8 @@ export function defaultEcosystemIo(overrides = {}) {
         modulesDir: getDocsModulesDir(),
         cargoHome: process.env.CARGO_HOME?.trim() || path.join(os.homedir(), '.cargo'),
         cabalPackageDirs: defaultCabalPackageDirs(),
+        goModCache: defaultGoModCache(),
+        goroot: process.env.GOROOT?.trim() || undefined,
         ...overrides
     };
 }
@@ -122,7 +127,7 @@ export function npmProfile(hooks = {}) {
         parentPackage: extractParentPackage,
         resolve: (name, cwd) => resolve(name, cwd),
         declaredRange: findDeclaredRange,
-        acquire: (name, range, io) => runAutoInstall(io.spawn, name, {
+        acquire: (name, range, _cwd, io) => runAutoInstall(io.spawn, name, {
             signal: io.signal,
             versionRange: range ?? undefined
         }),
@@ -139,6 +144,7 @@ export function npmProfile(hooks = {}) {
         commentPrefix: '//',
         // A nested node_modules is another package's surface, never this one's.
         skipDirs: ['node_modules'],
+        selectFiles: dropParallelDeclarations,
         surfaceLabel: '.d.ts files or README',
         packageSubject: 'an npm package',
         projectGlobs: ['*.ts', '*.tsx'],
@@ -259,7 +265,7 @@ const cargoProfile = {
     resolve: (name, cwd, io) => resolveCrate(name, cwd, { cargoHome: io.cargoHome, modulesDir: io.modulesDir }),
     // Cargo has already resolved every version; the lock IS the pin.
     declaredRange: (name, cwd) => lockedVersion(name, cwd),
-    acquire: async (name, range, io) => {
+    acquire: async (name, range, _cwd, io) => {
         // Asked even when the range is known: the download host wants the name as
         // PUBLISHED, and only the API knows whether that is `tokio-util` or
         // `tokio_util`. A null answer falls back to the caller's spelling.
@@ -293,7 +299,7 @@ const cargoProfile = {
                 // Not unpacked here. `acquire` reads crates.io for the published
                 // spelling, so `tokio-util` and `tokio_util` both land.
             }
-            const got = await cargoProfile.acquire(c.name, c.version, io);
+            const got = await cargoProfile.acquire(c.name, c.version, cwd, io);
             if (!got.success)
                 continue;
             try {
@@ -359,7 +365,7 @@ const hackageProfile = {
     parentPackage: name => name,
     resolve: (name, cwd, io) => resolveHackage(name, cwd, { modulesDir: io.modulesDir }),
     declaredRange: (name, cwd) => hackageVersion(name, cwd),
-    acquire: async (name, range, io) => {
+    acquire: async (name, range, _cwd, io) => {
         const dir = hackageExtractDir(io.modulesDir);
         const version = range
             ?? cachedVersions(name, io.cabalPackageDirs).pop()
@@ -413,7 +419,7 @@ const hackageProfile = {
                 // Not unpacked yet. `acquire` prefers the tarball cabal already
                 // downloaded as a dependency, so this is local work, not a fetch.
             }
-            const got = await hackageProfile.acquire(c.name, c.version, io);
+            const got = await hackageProfile.acquire(c.name, c.version, cwd, io);
             if (!got.success)
                 continue;
             try {
@@ -459,10 +465,57 @@ function hasCabalManifest(cwd) {
         return false;
     }
 }
+/**
+ * A Go package's surface is cut out of `.go` source, and the row keeps `internal`
+ * out of it: Go's compiler enforces that no package outside the module may
+ * import one, so an `internal` tree is not API however exported its names are.
+ */
+const goProfile = {
+    id: 'go',
+    why: 'A Go IMPORT PATH is not a module — gin/binding is served by gin, while '
+        + 'aws-sdk-go-v2/service/s3 is its own module — so the boundary is found by '
+        + 'asking the proxy for the longest prefix that resolves, longest first. '
+        + 'Versions come from go.mod, which since Go 1.17 IS the lockfile: its '
+        + 'indirect block is the resolved closure, so nothing walks a graph and '
+        + 'go.sum is never read. The standard library is not on the proxy at all, '
+        + 'and is read from a local GOROOT or sliced out of the toolchain archive.',
+    registryLabel: 'proxy.golang.org',
+    manifestLabel: 'go.mod',
+    detect: detectGo,
+    isValidName: isValidImportPath,
+    // Identity, because the module a path belongs to cannot be found without the
+    // network. Everything that needs the real module — resolve, acquire, latest —
+    // is handed `io` and works it out there.
+    parentPackage: name => name,
+    resolve: (name, cwd, io) => resolveGoPackage(name, cwd, {
+        goModCache: io.goModCache,
+        modulesDir: io.modulesDir,
+        goroot: io.goroot
+    }),
+    declaredRange: goDeclaredVersion,
+    acquire: (name, range, cwd, io) => acquireGoModule(name, range, cwd, { goModCache: io.goModCache, modulesDir: io.modulesDir, goroot: io.goroot }, io.fetch, io.signal),
+    latest: (name, io) => goLatest(name, io.fetch, io.signal),
+    isSurfaceFile: isGoFile,
+    surface: content => goSurface(content),
+    contentFingerprint: () => [goContentFingerprint(), ...goContentFingerprintParts()].join('\u0000'),
+    declSplitRe: GO_DECL_SPLIT_RE,
+    memberSplitRe: GO_MEMBER_SPLIT_RE,
+    typeKeywords: ['type', 'struct', 'interface', 'func'],
+    commentPrefix: '//',
+    skipDirs: ['testdata', 'examples', 'vendor', 'internal', '.git'],
+    selectFiles: (files, pkg) => selectBuildVariants(selectOwnPackage(files, pkg.root, pkg.name, pkg.version)),
+    surfaceLabel: '.go source or README',
+    packageSubject: 'a Go package',
+    projectGlobs: ['*.go'],
+    projectName: goProjectName,
+    declaredDeps: goDeclaredDeps,
+    manifestDeps: goManifestDeps
+};
 export const ECOSYSTEMS = {
     npm: npmProfile(),
     cargo: cargoProfile,
-    hackage: hackageProfile
+    hackage: hackageProfile,
+    go: goProfile
 };
 /** Which ecosystems `cwd` looks like a project of, in roster order. */
 export function detectEcosystems(cwd, roster = Object.values(ECOSYSTEMS)) {

package/dist/workers/docs-index.d.ts

@@ -35,4 +35,17 @@ export interface IndexResult {
  * have said so.
  */
 export declare function chunkerFingerprint(): string;
+/**
+ * Drop a `.d.cts` / `.d.mts` that sits beside a `.d.ts` of the same name.
+ *
+ * Modern npm packages ship parallel declarations for ESM and CJS: the same API
+ * written twice. zod 4.5.4 indexed to 2565 chunks over 1215 distinct bodies,
+ * 1280 of them from `.d.cts`; hono, which ships none, had 704 distinct of 708.
+ * The cost is the eight-chunk retrieval budget — half of it can go to text the
+ * reader already has.
+ *
+ * The sibling test, not a blanket ban on the extensions: a package shipping only
+ * `.d.cts` still has to be readable, and all 123 of zod's had a `.d.ts` twin.
+ */
+export declare function dropParallelDeclarations(files: readonly string[]): string[];
 export declare function ensureIndexed(cache: CacheHandle, pkg: ResolvedPackage, profile?: EcosystemProfile, supplements?: readonly ResolvedPackage[]): IndexResult;

package/dist/workers/docs-index.js

@@ -59,7 +59,7 @@ function computeContentHash(pkg, profile, supplements = []) {
     hash.update(ZERO_SEP);
     // Source text, the same trick as `declSplitRe.source`: the fingerprint moves
     // whenever the selection rule does, with nothing to remember to bump.
-    hash.update(Buffer.from(`${String(profile.isSurfaceFile)}\u0000${String(dropParallelDeclarations)}`
+    hash.update(Buffer.from(`${String(profile.isSurfaceFile)}\u0000${String(profile.selectFiles)}`
         + `\u0000${String(dropDeadMajors)}`, 'utf8'));
     hash.update(ZERO_SEP);
     // The extractor and the writer, by source. Surfacing only `pkg.entry` below
@@ -144,7 +144,7 @@ function walkSurface(root, profile) {
  * The sibling test, not a blanket ban on the extensions: a package shipping only
  * `.d.cts` still has to be readable, and all 123 of zod's had a `.d.ts` twin.
  */
-function dropParallelDeclarations(files) {
+export function dropParallelDeclarations(files) {
     const esm = new Set(files.filter(f => f.endsWith('.d.ts')).map(f => f.slice(0, -'.d.ts'.length)));
     return files.filter(f => {
         const base = /\.d\.[cm]ts$/.exec(f) ? f.slice(0, -'.d.cts'.length) : null;
@@ -181,7 +181,7 @@ function collectFiles(pkg, profile) {
     const walked = walkSurface(pkg.root, profile);
     const surface = dropDeadMajors(walked, pkg.root, pkg.version);
     return {
-        surface: profile.id === 'npm' ? dropParallelDeclarations(surface) : surface,
+        surface: profile.selectFiles ? profile.selectFiles(surface, pkg) : surface,
         readme: pkg.readme
     };
 }