@oscharko-dev/keiko-workspace 0.2.0

package/dist/repoSearchScan.js

@@ -0,0 +1,292 @@
+// Candidate gathering and the per-file scan loop for the repo-search facade (Issue #179).
+// Kept separate from the public API surface so repoSearch.ts stays inside the 400-LOC cap.
+// Every file system touch goes through the injected WorkspaceFs port; nothing here calls
+// node:fs directly.
+import { CONNECTED_CONTEXT_SCHEMA_VERSION, isValidScopePath, } from "@oscharko-dev/keiko-contracts/connected-context";
+import { discoverWithStats, readWorkspaceFile } from "./discovery.js";
+import { FileTooLargeError, RepoSearchInvalidQueryError } from "./errors.js";
+import { isDenied } from "./ignore.js";
+import { resolveWithinWorkspace } from "./paths.js";
+import { containedRealPathInfo } from "./realpath.js";
+import { looksBinary } from "./binaryDetect.js";
+import { collectFromEntries } from "./repoSearchEntries.js";
+import { collectBestLines } from "./repoSearchLineSelection.js";
+import { evidenceAtomStableId } from "./stableId.js";
+import { extraIgnoreLinesForSearch, legacyDiscoveryPolicy, orderCandidatesForSearch, policyOmissionReason, resolveSearchPolicy, shouldScoreContent, } from "./repoSearchPolicy.js";
+const BINARY_PROBE_BYTES = 512;
+const IMAGE_EXTENSIONS = new Set([
+    ".avif",
+    ".bmp",
+    ".gif",
+    ".heic",
+    ".heif",
+    ".ico",
+    ".jpeg",
+    ".jpg",
+    ".png",
+    ".tif",
+    ".tiff",
+    ".webp",
+]);
+function normalizeScopePath(scopePath) {
+    return scopePath.split("\\").join("/");
+}
+export function isImageScopePath(scopePath) {
+    const lastSlash = Math.max(scopePath.lastIndexOf("/"), scopePath.lastIndexOf("\\"));
+    const basename = scopePath.slice(lastSlash + 1).toLowerCase();
+    const dot = basename.lastIndexOf(".");
+    return dot >= 0 && IMAGE_EXTENSIONS.has(basename.slice(dot));
+}
+export function buildAtom(shape) {
+    const stableId = evidenceAtomStableId({
+        scopeId: shape.scopeId,
+        scopePath: shape.scopePath,
+        lineRange: shape.lineRange,
+        provenanceKind: shape.provenanceKind,
+        provenanceTool: shape.tool,
+        queryFingerprint: shape.queryFingerprint,
+    });
+    return {
+        schemaVersion: CONNECTED_CONTEXT_SCHEMA_VERSION,
+        stableId,
+        scopePath: shape.scopePath,
+        lineRange: shape.lineRange,
+        score: shape.score,
+        provenance: {
+            kind: shape.provenanceKind,
+            tool: shape.tool,
+            queryFingerprint: shape.queryFingerprint,
+        },
+        redactionState: "redacted",
+        emittedAtMs: shape.emittedAtMs,
+        ledgerRef: undefined,
+    };
+}
+export function buildCandidate(scopePath, omitted) {
+    return { scopePath, score: 0, signals: [], omitted };
+}
+function collectFromDirectory(scope, limits, fs, policy) {
+    const extraIgnoreLines = extraIgnoreLinesForSearch(policy);
+    const workspace = extraIgnoreLines.length === 0
+        ? scope.workspace
+        : { ...scope.workspace, ignoreLines: [...scope.workspace.ignoreLines, ...extraIgnoreLines] };
+    const result = discoverWithStats(workspace, {
+        maxDepth: 12,
+        maxFiles: limits.maxFilesScanned + 1,
+        applyGitignore: policy.applyGitignore,
+    }, fs);
+    const files = result.files;
+    return {
+        files: files.slice(0, limits.maxFilesScanned),
+        truncated: files.length > limits.maxFilesScanned,
+        ignored: result.stats.ignored,
+        denied: result.stats.denied,
+    };
+}
+const DEFAULT_GATHER_QUERY = {
+    kind: "natural-language",
+    text: "generic repository search",
+    caseSensitive: false,
+    maxResults: 100,
+    emittedAtMs: 0,
+};
+function isRetrievalQuery(value) {
+    return typeof value === "object" && value !== null && "kind" in value && "text" in value;
+}
+function resolveGatherInputs(scope, queryOrLimits, limitsOrFs, fsOrPolicy, policy) {
+    if (isRetrievalQuery(queryOrLimits)) {
+        return {
+            query: queryOrLimits,
+            limits: limitsOrFs,
+            fs: fsOrPolicy,
+            policy: policy ?? resolveSearchPolicy(scope.relativePaths.length > 0, undefined),
+        };
+    }
+    return {
+        query: DEFAULT_GATHER_QUERY,
+        limits: queryOrLimits,
+        fs: limitsOrFs,
+        policy: legacyDiscoveryPolicy(scope.relativePaths.length > 0),
+    };
+}
+export function gatherCandidates(scope, queryOrLimits, limitsOrFs, fsOrPolicy, policy) {
+    const inputs = resolveGatherInputs(scope, queryOrLimits, limitsOrFs, fsOrPolicy, policy);
+    // Defense in depth alongside the realpath gate: validate scope.relativePaths against the
+    // contracts-layer shape rules (no absolute paths, no `..`, no drive letters, no backslashes).
+    // resolveWithinWorkspace + assertContainedRealPath already provide a complete barrier; this
+    // pre-check rejects shape-invalid inputs at the API boundary with a typed error rather than
+    // letting a normalization quirk slip past unnoticed.
+    for (const entry of scope.relativePaths) {
+        if (!isValidScopePath(entry, { mustBeRelative: true })) {
+            throw new RepoSearchInvalidQueryError(`invalid scope.relativePaths entry: ${entry}`);
+        }
+    }
+    if (scope.relativePaths.length === 0) {
+        const result = collectFromDirectory(scope, inputs.limits, inputs.fs, inputs.policy);
+        const ordered = orderCandidatesForSearch(result.files, inputs.query, inputs.policy, result.ignored, result.denied);
+        return {
+            files: ordered.files,
+            truncated: result.truncated,
+            diagnostics: ordered.diagnostics,
+        };
+    }
+    const result = collectFromEntries(scope, inputs.limits, inputs.fs);
+    const ordered = orderCandidatesForSearch(result.files, inputs.query, inputs.policy, 0, 0);
+    return {
+        files: ordered.files,
+        truncated: result.truncated,
+        diagnostics: ordered.diagnostics,
+    };
+}
+export async function probeBinary(fs, abs, size) {
+    const cap = Math.min(BINARY_PROBE_BYTES, size);
+    if (cap === 0) {
+        return false;
+    }
+    if (fs.readFileBytes !== undefined) {
+        return looksBinary(await fs.readFileBytes(abs, cap));
+    }
+    const text = fs.readFileUtf8(abs);
+    return looksBinary(new TextEncoder().encode(text.slice(0, cap)));
+}
+export function elapsed(runner) {
+    return runner.nowMs() - runner.startMs;
+}
+function isRunnerAborted(runner) {
+    return runner.signal?.aborted === true;
+}
+export function hitLimit(runner, state) {
+    if (isRunnerAborted(runner)) {
+        state.truncated = true;
+        return true;
+    }
+    if (state.filesScanned >= runner.limits.maxFilesScanned) {
+        state.truncated = true;
+        return true;
+    }
+    if (state.matchesReturned >= runner.limits.maxMatchesReturned) {
+        state.truncated = true;
+        return true;
+    }
+    if (elapsed(runner) > runner.limits.elapsedMsMax) {
+        state.truncated = true;
+        return true;
+    }
+    return false;
+}
+function hitEmissionLimit(runner, state) {
+    if (isRunnerAborted(runner)) {
+        state.truncated = true;
+        return true;
+    }
+    if (state.matchesReturned >= runner.limits.maxMatchesReturned) {
+        state.truncated = true;
+        return true;
+    }
+    if (elapsed(runner) > runner.limits.elapsedMsMax) {
+        state.truncated = true;
+        return true;
+    }
+    return false;
+}
+// Returns true for NodeJS.ErrnoException (EACCES, ENOENT, EIO, …). Checked by the presence of a
+// string `code` property so TypeError and other programmer errors are NOT swallowed.
+export function isIoError(err) {
+    if (err === null || typeof err !== "object" || !("code" in err)) {
+        return false;
+    }
+    const { code } = err;
+    return typeof code === "string";
+}
+function readForScan(runner, relativePath, candidates) {
+    try {
+        return readWorkspaceFile(runner.scope.workspace, relativePath, { maxBytes: runner.limits.maxBytesPerFileScanned }, runner.fs).text;
+    }
+    catch (err) {
+        if (err instanceof FileTooLargeError) {
+            candidates.push(buildCandidate(relativePath, "size-exceeded"));
+            return undefined;
+        }
+        // TOCTOU: permissions or availability may change between discovery and read.
+        // A single unreadable file must degrade to a skip, not crash the whole scan.
+        if (isIoError(err)) {
+            candidates.push(buildCandidate(relativePath, "tool-unavailable"));
+            return undefined;
+        }
+        throw err;
+    }
+}
+function emitBestLines(runner, relativePath, state, atoms, best) {
+    for (const match of best) {
+        if (hitEmissionLimit(runner, state)) {
+            return;
+        }
+        atoms.push(buildAtom({
+            scopeId: runner.scope.scopeId,
+            scopePath: relativePath,
+            lineRange: { startLine: match.line, endLine: match.line },
+            provenanceKind: "lexical-search",
+            tool: "repo.searchText",
+            queryFingerprint: runner.fingerprint,
+            score: match.score,
+            emittedAtMs: runner.nowMs(),
+        }));
+        state.matchesReturned += 1;
+    }
+}
+function scanLines(runner, relativePath, text, state, atoms) {
+    emitBestLines(runner, relativePath, state, atoms, collectBestLines(runner, text, state));
+}
+function filePolicyOmission(runner, file) {
+    if (isImageScopePath(file.relativePath)) {
+        return { omitted: "binary" };
+    }
+    if (isDenied(file.relativePath)) {
+        return { omitted: "ignored" };
+    }
+    const abs = resolveWithinWorkspace(runner.scope.workspace.root, file.relativePath);
+    const contained = containedRealPathInfo(runner.fs, runner.scope.workspace.root, abs);
+    const realRel = normalizeScopePath(contained.realRelative);
+    if (isDenied(realRel)) {
+        return { omitted: "ignored" };
+    }
+    return { omitted: policyOmissionReason(file.relativePath, runner.policy), path: contained.path };
+}
+async function binaryOmission(runner, file, path) {
+    try {
+        return (await probeBinary(runner.fs, path, file.sizeBytes)) ? "binary" : undefined;
+    }
+    catch (err) {
+        // TOCTOU: file may have become unreadable (EACCES, ENOENT, …) between discovery and probe.
+        if (isIoError(err)) {
+            return "tool-unavailable";
+        }
+        throw err;
+    }
+}
+export async function scanFile(runner, file, state, atoms, candidates) {
+    if (isRunnerAborted(runner)) {
+        state.truncated = true;
+        return;
+    }
+    const policy = filePolicyOmission(runner, file);
+    if (policy.omitted !== undefined) {
+        candidates.push(buildCandidate(file.relativePath, policy.omitted));
+        return;
+    }
+    const binary = policy.path === undefined ? "binary" : await binaryOmission(runner, file, policy.path);
+    if (binary !== undefined) {
+        candidates.push(buildCandidate(file.relativePath, binary));
+        return;
+    }
+    if (isRunnerAborted(runner)) {
+        state.truncated = true;
+        return;
+    }
+    state.filesScanned += 1;
+    const text = readForScan(runner, file.relativePath, candidates);
+    if (text === undefined || !shouldScoreContent(runner.query, text, runner.policy)) {
+        return;
+    }
+    scanLines(runner, file.relativePath, text, state, atoms);
+}

package/dist/retrieval.d.ts

@@ -0,0 +1,10 @@
+import { type DiscoveredFile, type SelectionReason } from "./types.js";
+export interface RankedFile {
+    readonly file: DiscoveredFile;
+    readonly selectionReason: SelectionReason;
+}
+export interface RetrievalStrategy {
+    readonly rank: (files: readonly DiscoveredFile[], task: string | undefined) => readonly RankedFile[];
+}
+export declare const lexicalRetrievalStrategy: RetrievalStrategy;
+//# sourceMappingURL=retrieval.d.ts.map

package/dist/retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../src/retrieval.ts"],"names":[],"mappings":"AAKA,OAAO,EAA6B,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAElG,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAGhC,QAAQ,CAAC,IAAI,EAAE,CACb,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,IAAI,EAAE,MAAM,GAAG,SAAS,KACrB,SAAS,UAAU,EAAE,CAAC;CAC5B;AAoED,eAAO,MAAM,wBAAwB,EAAE,iBAatC,CAAC"}

package/dist/retrieval.js

@@ -0,0 +1,74 @@
+// Retrieval seam (ADR-0005 D5). `RetrievalStrategy` is the typed extension point a future
+// embedding ranker (e.g. `example-embedding-model`) plugs into. Wave-1 ships ONLY the seam and
+// a deterministic lexical default — no embeddings, no vector DB, no new dependency. The
+// default ranker is pure and clock/RNG-free so context packs are reproducible.
+import { SELECTION_REASON_PRIORITY } from "./types.js";
+const ENTRYPOINT_BASENAMES = new Set([
+    "index.ts",
+    "index.js",
+    "main.ts",
+    "main.js",
+    "cli.ts",
+    "cli.js",
+]);
+const MANIFEST_BASENAMES = new Set([
+    "package.json",
+    "tsconfig.json",
+    "tsconfig.build.json",
+]);
+const DOC_EXTENSIONS = new Set([".md", ".mdx", ".rst", ".txt"]);
+const CONFIG_EXTENSIONS = new Set([".json", ".yml", ".yaml", ".toml"]);
+const CONFIG_BASENAME_HINTS = [".config.", "eslint", "prettier", "vitest"];
+function basename(path) {
+    const idx = path.lastIndexOf("/");
+    return idx === -1 ? path : path.slice(idx + 1);
+}
+function extension(name) {
+    const idx = name.lastIndexOf(".");
+    return idx <= 0 ? "" : name.slice(idx);
+}
+function isTest(name) {
+    return /\.(test|spec)\.[cm]?[jt]sx?$/.test(name);
+}
+function isConfig(name) {
+    return (CONFIG_EXTENSIONS.has(extension(name)) || CONFIG_BASENAME_HINTS.some((h) => name.includes(h)));
+}
+function classify(path) {
+    const name = basename(path);
+    if (isTest(name) || path.startsWith("tests/") || path.startsWith("test/")) {
+        return "test";
+    }
+    if (ENTRYPOINT_BASENAMES.has(name)) {
+        return "entrypoint";
+    }
+    if (MANIFEST_BASENAMES.has(name)) {
+        return "manifest";
+    }
+    if (DOC_EXTENSIONS.has(extension(name))) {
+        return "documentation";
+    }
+    if (isConfig(name)) {
+        return "config";
+    }
+    return "source";
+}
+function priorityIndex(reason) {
+    return SELECTION_REASON_PRIORITY.indexOf(reason);
+}
+// Deterministic lexical ranking: by selection-reason priority, then by path (ascending).
+export const lexicalRetrievalStrategy = {
+    rank: (files) => {
+        const ranked = files.map((file) => ({ file, selectionReason: classify(file.relativePath) }));
+        return [...ranked].sort((a, b) => {
+            const byReason = priorityIndex(a.selectionReason) - priorityIndex(b.selectionReason);
+            if (byReason !== 0) {
+                return byReason;
+            }
+            if (a.file.relativePath < b.file.relativePath)
+                return -1;
+            if (a.file.relativePath > b.file.relativePath)
+                return 1;
+            return 0;
+        });
+    },
+};

package/dist/stableId.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectedContextPackStableIdInput, EvidenceAtomStableIdInput } from "@oscharko-dev/keiko-contracts/connected-context";
+export declare function evidenceAtomStableId(input: EvidenceAtomStableIdInput): string;
+export declare function connectedContextPackStableId(input: ConnectedContextPackStableIdInput): string;
+//# sourceMappingURL=stableId.d.ts.map

package/dist/stableId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stableId.d.ts","sourceRoot":"","sources":["../src/stableId.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,iCAAiC,EACjC,yBAAyB,EAC1B,MAAM,iDAAiD,CAAC;AA8BzD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,MAAM,CAa7E;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,iCAAiC,GAAG,MAAM,CAS7F"}

package/dist/stableId.js

@@ -0,0 +1,49 @@
+// Deterministic SHA-256 stable IDs for connected-context evidence atoms and packs
+// (Epic #177, Issue #179). Inputs are the DTOs defined in keiko-contracts; the producer
+// here owns the canonicalisation rules (key-sorted JSON, omit `undefined`, no whitespace,
+// caller-sorted-or-here-sorted arrays) so every downstream package hashes the same shape.
+// Prefixes `a-` / `p-` keep the two namespaces visually separable in logs.
+import { createHash } from "node:crypto";
+function canonicalize(value) {
+    if (value === undefined) {
+        return "null";
+    }
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        const items = value;
+        return `[${items.map((item) => canonicalize(item)).join(",")}]`;
+    }
+    const entries = Object.entries(value)
+        .filter((pair) => pair[1] !== undefined)
+        .sort((a, b) => (a[0] < b[0] ? -1 : 1));
+    const body = entries.map(([key, val]) => `${JSON.stringify(key)}:${canonicalize(val)}`).join(",");
+    return `{${body}}`;
+}
+function sha256Hex(canonical) {
+    return createHash("sha256").update(canonical).digest("hex");
+}
+export function evidenceAtomStableId(input) {
+    const shape = {
+        scopeId: input.scopeId,
+        scopePath: input.scopePath,
+        lineRange: input.lineRange === undefined
+            ? undefined
+            : { startLine: input.lineRange.startLine, endLine: input.lineRange.endLine },
+        provenanceKind: input.provenanceKind,
+        provenanceTool: input.provenanceTool,
+        queryFingerprint: input.queryFingerprint,
+    };
+    return `a-${sha256Hex(canonicalize(shape))}`;
+}
+export function connectedContextPackStableId(input) {
+    const sortedAtomIds = [...input.atomStableIds].sort((a, b) => (a < b ? -1 : 1));
+    const shape = {
+        scopeId: input.scopeId,
+        queryKind: input.queryKind,
+        queryText: input.queryText,
+        atomStableIds: sortedAtomIds,
+    };
+    return `p-${sha256Hex(canonicalize(shape))}`;
+}

package/dist/structuralAdapters.d.ts

@@ -0,0 +1,27 @@
+import type { EvidenceAtom, RetrievalQuery } from "@oscharko-dev/keiko-contracts/connected-context";
+import type { WorkspaceFs } from "./fs.js";
+import type { SearchLimits, SearchScope } from "./repoSearch.js";
+export interface StructuralAdapterDeps {
+    readonly nowMs?: () => number;
+}
+export interface StructuralAdapter {
+    readonly name: string;
+    readonly isAvailable: (scope: SearchScope, fs: WorkspaceFs) => Promise<boolean>;
+    readonly lookup: (scope: SearchScope, query: RetrievalQuery, limits: SearchLimits, fs: WorkspaceFs, deps?: StructuralAdapterDeps) => Promise<readonly EvidenceAtom[]>;
+}
+export interface StructuralAdapterRegistry {
+    readonly adapters: readonly StructuralAdapter[];
+}
+export interface AdapterError {
+    readonly name: string;
+    readonly message: string;
+}
+export interface RunAllResult {
+    readonly atoms: readonly EvidenceAtom[];
+    readonly unavailable: readonly string[];
+    readonly errored: readonly AdapterError[];
+    readonly elapsedMs: number;
+}
+export declare function createDefaultStructuralRegistry(): StructuralAdapterRegistry;
+export declare function runStructuralAdapters(registry: StructuralAdapterRegistry, scope: SearchScope, query: RetrievalQuery, limits: SearchLimits, fs: WorkspaceFs, deps?: StructuralAdapterDeps): Promise<RunAllResult>;
+//# sourceMappingURL=structuralAdapters.d.ts.map

package/dist/structuralAdapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuralAdapters.d.ts","sourceRoot":"","sources":["../src/structuralAdapters.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iDAAiD,CAAC;AAEpG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAOjE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAGhF,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,YAAY,EACpB,EAAE,EAAE,WAAW,EACf,IAAI,CAAC,EAAE,qBAAqB,KACzB,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAID,wBAAgB,+BAA+B,IAAI,yBAAyB,CAI3E;AA+ED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,yBAAyB,EACnC,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,YAAY,EACpB,EAAE,EAAE,WAAW,EACf,IAAI,CAAC,EAAE,qBAAqB,GAC3B,OAAO,CAAC,YAAY,CAAC,CA2BvB"}

package/dist/structuralAdapters.js

@@ -0,0 +1,87 @@
+// Optional structural exploration adapter contract + default registry (Epic #177, Issue #180).
+// Adapters surface structural signals (test/source pairing, import graph, git history) and
+// degrade gracefully when their data sources are missing. Output is normalized to EvidenceAtom
+// from @oscharko-dev/keiko-contracts; the runner merges, dedupes, and caps adapter output so
+// one broken adapter never blocks the rest. Stays within ADR-0019 rule 3b.
+import { RepoSearchInvalidQueryError, RepoSearchInvalidRangeError } from "./errors.js";
+import { testSourcePairingAdapter } from "./testSourcePairing.js";
+import { importGraphAdapter } from "./importGraph.js";
+import { gitHistoryAdapter } from "./gitHistory.js";
+// ─── Default registry ─────────────────────────────────────────────────────────
+export function createDefaultStructuralRegistry() {
+    return {
+        adapters: [testSourcePairingAdapter, importGraphAdapter, gitHistoryAdapter],
+    };
+}
+async function probeAvailability(adapters, scope, fs) {
+    return Promise.all(adapters.map(async (adapter) => ({
+        adapter,
+        available: await adapter.isAvailable(scope, fs).catch(() => false),
+    })));
+}
+function isTypedAdapterError(error) {
+    return (error instanceof RepoSearchInvalidQueryError || error instanceof RepoSearchInvalidRangeError);
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function runOne(adapter, scope, query, limits, fs, deps) {
+    try {
+        const atoms = await adapter.lookup(scope, query, limits, fs, deps);
+        return { name: adapter.name, atoms, error: undefined };
+    }
+    catch (error) {
+        if (isTypedAdapterError(error)) {
+            throw error;
+        }
+        return {
+            name: adapter.name,
+            atoms: [],
+            error: { name: adapter.name, message: describeError(error) },
+        };
+    }
+}
+function mergeAtoms(outcomes, cap) {
+    const seen = new Set();
+    const merged = [];
+    for (const outcome of outcomes) {
+        for (const atom of outcome.atoms) {
+            if (merged.length >= cap) {
+                return merged;
+            }
+            if (seen.has(atom.stableId)) {
+                continue;
+            }
+            seen.add(atom.stableId);
+            merged.push(atom);
+        }
+    }
+    return merged;
+}
+export async function runStructuralAdapters(registry, scope, query, limits, fs, deps) {
+    const nowMs = deps?.nowMs ?? Date.now;
+    const startMs = nowMs();
+    const availability = await probeAvailability(registry.adapters, scope, fs);
+    const unavailable = [];
+    const available = [];
+    for (const row of availability) {
+        if (row.available) {
+            available.push(row.adapter);
+        }
+        else {
+            unavailable.push(row.adapter.name);
+        }
+    }
+    const outcomes = await Promise.all(available.map((adapter) => runOne(adapter, scope, query, limits, fs, deps)));
+    const errored = outcomes
+        .map((outcome) => outcome.error)
+        .filter((error) => error !== undefined);
+    const cap = Math.min(limits.maxMatchesReturned, query.maxResults);
+    const atoms = mergeAtoms(outcomes, cap);
+    return {
+        atoms,
+        unavailable,
+        errored,
+        elapsedMs: nowMs() - startMs,
+    };
+}

package/dist/summary.d.ts

@@ -0,0 +1,4 @@
+import type { AuditSummary, ContextPack, DiscoveryStats, WorkspaceInfo, WorkspaceSummary } from "./types.js";
+export declare function buildWorkspaceSummary(workspace: WorkspaceInfo, pack?: ContextPack, stats?: DiscoveryStats): WorkspaceSummary;
+export declare function summarizeForAudit(pack: ContextPack): AuditSummary;
+//# sourceMappingURL=summary.d.ts.map

package/dist/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EAEX,cAAc,EACd,aAAa,EACb,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAuBpB,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,EACxB,IAAI,CAAC,EAAE,WAAW,EAClB,KAAK,CAAC,EAAE,cAAc,GACrB,gBAAgB,CAYlB;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,YAAY,CAejE"}

package/dist/summary.js

@@ -0,0 +1,54 @@
+// The structured, redacted view CLI/SDK/UI render WITHOUT touching the filesystem. Every
+// string that could carry file content is already redacted upstream (context excerpts pass
+// through redact() in discovery/contextPack). This module only reshapes already-safe data;
+// it performs no IO and adds no raw file contents. Pure and deterministic.
+function toContextSummary(pack) {
+    return {
+        totalCandidates: pack.totalCandidates,
+        usedBytes: pack.usedBytes,
+        budgetBytes: pack.budgetBytes,
+        droppedForBudget: pack.droppedForBudget,
+        entries: pack.selected.map((entry) => ({
+            path: entry.path,
+            sizeBytes: entry.sizeBytes,
+            excerptBytes: entry.excerptBytes,
+            selectionReason: entry.selectionReason,
+            truncated: entry.truncated,
+            excerpt: entry.excerpt,
+        })),
+    };
+}
+function statsFor(pack) {
+    return { discovered: pack?.totalCandidates ?? 0, denied: 0, ignored: 0 };
+}
+export function buildWorkspaceSummary(workspace, pack, stats) {
+    return {
+        root: workspace.root,
+        name: workspace.name,
+        version: workspace.version,
+        testFramework: workspace.testFramework,
+        sourceDirs: workspace.sourceDirs,
+        testDirs: workspace.testDirs,
+        languages: workspace.languages,
+        counts: stats ?? statsFor(pack),
+        context: pack === undefined ? undefined : toContextSummary(pack),
+    };
+}
+// Selected-context metadata for audit evidence: paths, sizes, reasons, and budget usage.
+// Deliberately excludes excerpt TEXT so an audit record carries no file content at all.
+export function summarizeForAudit(pack) {
+    return {
+        workspaceRoot: pack.workspaceRoot,
+        totalCandidates: pack.totalCandidates,
+        usedBytes: pack.usedBytes,
+        budgetBytes: pack.budgetBytes,
+        droppedForBudget: pack.droppedForBudget,
+        entries: pack.selected.map((entry) => ({
+            path: entry.path,
+            sizeBytes: entry.sizeBytes,
+            excerptBytes: entry.excerptBytes,
+            selectionReason: entry.selectionReason,
+            truncated: entry.truncated,
+        })),
+    };
+}

package/dist/testSourcePairing.d.ts

@@ -0,0 +1,3 @@
+import type { StructuralAdapter } from "./structuralAdapters.js";
+export declare const testSourcePairingAdapter: StructuralAdapter;
+//# sourceMappingURL=testSourcePairing.d.ts.map

package/dist/testSourcePairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testSourcePairing.d.ts","sourceRoot":"","sources":["../src/testSourcePairing.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,iBAAiB,EAAyB,MAAM,yBAAyB,CAAC;AAkKxF,eAAO,MAAM,wBAAwB,EAAE,iBAoBtC,CAAC"}