@mjasnikovs/pi-task 0.40.28 → 0.40.30

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

@@ -0,0 +1,213 @@
+/**
+ * eco-go — reading Go packages for the docs Worker tool.
+ *
+ * Three things separate this row from the others.
+ *
+ * A Go IMPORT PATH is not a module. `github.com/gin-gonic/gin/binding` is served
+ * by the `gin` module, and `github.com/aws/aws-sdk-go-v2/service/s3` is its own
+ * module despite looking like a subdirectory of one. No syntactic rule tells
+ * them apart, so the module boundary is found by asking the proxy for the
+ * longest prefix that resolves — longest FIRST, because shorter prefixes answer
+ * too: `github.com/go-redis/redis` is a real, ancient, different module from
+ * `github.com/go-redis/redis/v8`.
+ *
+ * The go.mod IS the lockfile. From Go 1.17 the indirect block is the complete
+ * pruned closure with resolved versions, so nothing here walks a dependency
+ * graph and `go.sum` is never read: it carries integrity hashes for versions
+ * that were considered and rejected, so using it would over-report.
+ *
+ * And Go has no re-export syntax at all — no `pub use`, no export list — so this
+ * row sets neither `supplements` nor `exportGap`. Every name a package exports
+ * is declared in that package's own files.
+ */
+import { type ResolvedPackage } from './docs-resolve.js';
+import type { NpmVersionInfo } from './npm-version.js';
+export declare function isValidImportPath(name: string): boolean;
+/**
+ * The proxy and the module cache both spell an uppercase letter as `!` plus its
+ * lowercase form, so that a case-insensitive filesystem cannot collide two
+ * modules whose paths differ only in case.
+ */
+export declare function escapeModulePath(name: string): string;
+export declare function unescapeModulePath(name: string): string;
+/**
+ * Go's own rule, from `cmd/go`'s `IsStandardImportPath`: the first path element
+ * of a standard-library import contains no dot. `net/http` is stdlib,
+ * `go.uber.org/zap` is not.
+ */
+export declare function isStdlibImport(importPath: string): boolean;
+/**
+ * Is this import path the standard library, in THIS project?
+ *
+ * Go's rule is purely lexical, so a project whose own module path has no dot —
+ * `module myapp` — makes `myapp/internal/db` look like stdlib. The project's own
+ * module is stripped first, which is what `cmd/go` effectively does too.
+ */
+export declare function isProjectStdlib(importPath: string, cwd: string): boolean;
+export declare function isGoFile(name: string): boolean;
+export interface GoRequire {
+    module: string;
+    version: string;
+    indirect: boolean;
+}
+export interface GoMod {
+    module: string | null;
+    /** The `go` directive, which says which language version the source targets. */
+    goVersion: string | null;
+    toolchain: string | null;
+    requires: GoRequire[];
+    /** `replace` targets, by the module being replaced. */
+    replaces: Map<string, string>;
+}
+/**
+ * Parse a `go.mod`.
+ *
+ * Written against what real files contain rather than the grammar's happy path:
+ * gin has THREE `require` blocks, single-line and block forms mix freely, and
+ * the direct/indirect split is the `// indirect` comment and never the block a
+ * line happens to sit in.
+ */
+export declare function parseGoMod(text: string): GoMod;
+/** The `use` directories a `go.work` names, resolved against its own location. */
+export declare function parseGoWork(text: string, dir: string): string[];
+/**
+ * Every `go.mod` that governs `cwd`.
+ *
+ * A `go.work` wins where there is one: each of its `use` directories is a
+ * first-class module, and taking only the root would miss every dependency the
+ * members declare.
+ */
+export declare function goManifests(cwd: string): string[];
+export declare function detectGo(cwd: string): boolean;
+/** The project's own module path, from the nearest manifest. */
+export declare function goProjectName(cwd: string): string | null;
+/**
+ * Every module version the project resolves, direct and indirect.
+ *
+ * A `replace` onto a local directory is dropped: nothing can be fetched for it,
+ * and its recorded version is a placeholder rather than a fact about a release.
+ */
+export declare function goDeclaredDeps(cwd: string): Record<string, string> | undefined;
+/**
+ * The modules the project may import directly — the requires with no
+ * `// indirect` marker, less the workspace's own members, which resolve from the
+ * working tree rather than from a registry.
+ */
+export declare function goManifestDeps(cwd: string): Set<string> | undefined;
+/**
+ * The version the project pins the module serving `importPath` to.
+ *
+ * The longest require whose path prefixes the import wins, so
+ * `github.com/aws/aws-sdk-go-v2/service/s3` takes the s3 submodule's own pin and
+ * not the SDK core's.
+ */
+export declare function goDeclaredVersion(importPath: string, cwd: string): string | null;
+export interface VendorEntry {
+    module: string;
+    version: string;
+}
+/**
+ * The package-to-module map `vendor/modules.txt` states outright.
+ *
+ * Exact and free: no prefix walk, no request, and replaces already applied. Its
+ * one limit is that `go mod vendor` copies only the packages the project
+ * imports, so a question about an untouched corner of a dependency still needs
+ * the module zip.
+ */
+export declare function parseVendorModules(text: string): Map<string, VendorEntry>;
+export interface GoResolveDirs {
+    /** `$GOMODCACHE`, holding extracted module trees and downloaded zips. */
+    goModCache: string;
+    /** Where a module fetched by this tool was extracted. */
+    modulesDir: string;
+    /** A local Go installation, whose `src/` is the standard library for free. */
+    goroot?: string | undefined;
+}
+export declare function defaultGoModCache(): string;
+/** Candidate module paths for an import, longest first. */
+export declare function modulePrefixes(importPath: string): string[];
+/**
+ * Find a Go package's source on disk.
+ *
+ * Vendored source first: it is exact, already extracted, and needs nothing from
+ * the network. Then the module cache, then whatever this tool fetched earlier.
+ */
+export declare function resolveGoPackage(importPath: string, cwd: string, dirs: GoResolveDirs): ResolvedPackage;
+/**
+ * Which module serves `importPath`, by asking the proxy about the longest
+ * prefix first.
+ *
+ * Longest first is not an optimisation. `github.com/go-redis/redis/v8` and
+ * `github.com/go-redis/redis` both resolve, to different modules a major apart,
+ * and a walk that grows from the left returns the wrong one every time.
+ */
+export declare function resolveModulePath(importPath: string, fetchFn: typeof fetch, signal?: AbortSignal): Promise<{
+    module: string;
+    version: string;
+} | null>;
+/** The newest published version of the module serving `importPath`. */
+export declare function goLatest(importPath: string, fetchFn: typeof fetch, signal?: AbortSignal): Promise<NpmVersionInfo | null>;
+export declare function moduleZipUrl(module: string, version: string): string;
+/**
+ * Fetch a module and extract its Go source under `<modulesDir>/go`.
+ *
+ * Entries are laid out exactly as the module cache lays them out —
+ * `<module>@<version>/…`, in the module's original case — so what lands on disk
+ * is indistinguishable from a tree `go mod download` would have written, and
+ * `findInRoot` reads both with one rule.
+ */
+export declare function acquireGoModule(importPath: string, pinned: string | null, cwd: string, dirs: GoResolveDirs, fetchFn: typeof fetch, signal?: AbortSignal): Promise<{
+    success: boolean;
+    installDir: string;
+    stderr: string;
+}>;
+/**
+ * Keep one file per set of build-tag variants.
+ *
+ * Go does what npm's `.d.ts`/`.d.cts` twins do: `binding.go` and
+ * `binding_nomsgpack.go` declare the same twelve names under opposite
+ * constraints, and `internal/json` declares the same five names four times. All
+ * of them in one index is duplicate text competing for the retrieval budget with
+ * nothing to tell the copies apart.
+ *
+ * The default build decides, which is what a reader gets by running `go build`
+ * with no tags: a bare negation holds, a bare tag does not.
+ */
+export declare function selectBuildVariants(files: readonly string[]): string[];
+/**
+ * Keep the package the caller asked for, and only the subpackages it can reach.
+ *
+ * A Go subdirectory is a DIFFERENT importable package — `zapcore` is not reachable
+ * as `zap.X` and `ginS` is not `gin` — so walking a module's whole tree files every
+ * one of them under the parent's name and its version banner. Measured on re-run 9's
+ * cache: 71% of `encoding/json`'s chunks, 54% of zap's and 34% of gin's belonged to
+ * a package nobody asked about, and it reached retrieval — a question about
+ * registering a gin route came back with 10 `ginS` chunks of 51, in a corpus already
+ * spending 19,941 of its 24,000 bytes.
+ *
+ * The gate is the ROOT'S OWN IMPORTS, closed over: zap's `Field` is
+ * `= zapcore.Field`, so dropping `zapcore` would break the alias hop that defect 3
+ * exists to serve, and zapcore in turn reaches `buffer`. What that keeps is what a
+ * caller of this package can actually be handed; `zapgrpc`, `zaptest`, `ginS`,
+ * `httputil` and `net/http/pprof` are reachable only by importing them directly,
+ * which the tool already resolves on its own — `github.com/gin-gonic/gin/binding`
+ * asked for by path reads 0% foreign.
+ *
+ * A mismatching top-level `vN/` goes whatever the imports say. `encoding/json` is
+ * built ON `encoding/json/v2` and imports it, but v2 is a different major of the
+ * same API with the same identifiers — `Marshal`, `Unmarshal` — and half the
+ * retrieval for the commonest decode question came back from it under a
+ * `Per encoding/json@go1.25.14` header. That is `dropDeadMajors`' case, which
+ * cannot fire here because it reads the major with `/^(\d+)\./` and Go spells its
+ * versions `v1.12.0` and `go1.25.14`.
+ *
+ * A module whose root holds no Go files is not a package at all — the aws-sdk shape
+ * — and keeps everything, for the same reason `dropDeadMajors` keeps a package whose
+ * whole surface lives under one `vN/`.
+ */
+export declare function selectOwnPackage(files: readonly string[], root: string, name: string, version: string): string[];
+/**
+ * Everything below `goSurface` and the file-selection rule that feeds it, by
+ * source, so a fix to either re-indexes rather than being masked by a cache hit.
+ */
+export declare function goContentFingerprintParts(): string[];