@codeledger/selector 0.1.1

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2025 Intelligent Context AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: This license applies to the CLI wrapper, types, repository scanning,
+instrumentation, harness, and report packages (the "Plugin"). The scoring
+engine (packages/core-engine/bin/) is licensed separately under LICENSE-CORE.

package/dist/bundle.d.ts

@@ -0,0 +1,14 @@
+import type { Budget, ContextBundle, RepoIndex, SelectorConfig } from '@codeledger/types';
+import { type LedgerStats } from './scorer.js';
+export interface BuildBundleOptions {
+    taskText: string;
+    repoIndex: RepoIndex;
+    selectorConfig: SelectorConfig;
+    budget?: Budget;
+    sufficiencyThreshold?: number;
+    ledgerStats?: LedgerStats;
+    /** When true, include per-file scoring breakdown in the bundle */
+    explain?: boolean;
+}
+export declare function buildBundle(opts: BuildBundleOptions): ContextBundle;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,MAAM,EAEN,aAAa,EAEb,SAAS,EACT,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAOnE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,cAAc,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,aAAa,CAoLnE"}

package/dist/bundle.js

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import { generateCandidates, tokenizeTask } from './candidates.js';
+import { scoreAllCandidates } from './scorer.js';
+import { shouldStop, estimateTokens } from './stop-rule.js';
+import { extractExcerpt } from './excerpt.js';
+import { assessConfidence } from './confidence.js';
+import { generateInterfaceStubs } from './stubs.js';
+import { scanDeprecations } from './deprecation.js';
+export function buildBundle(opts) {
+    const { taskText, repoIndex, selectorConfig, budget = selectorConfig.default_budget, sufficiencyThreshold = selectorConfig.sufficiency_threshold, ledgerStats, explain = false, } = opts;
+    const keywords = tokenizeTask(taskText);
+    // Step 1: Generate candidates (includes IDF token weights + fan-out)
+    const { candidates: candidateSet, tokenWeights, fanoutFiles } = generateCandidates(taskText, repoIndex, selectorConfig);
+    // Step 2: Score all candidates (with IDF weights + fan-out bonus)
+    const scored = scoreAllCandidates(candidateSet, keywords, repoIndex, selectorConfig.weights, ledgerStats, tokenWeights, fanoutFiles);
+    // Step 3: Compute max cumulative score for threshold
+    const maxCumulative = scored.reduce((sum, f) => sum + Math.max(0, f.score), 0);
+    // Step 3.5: Reserve slots for test pairing under tight budgets.
+    // Under generous budgets, test pairing uses leftover space. Under tight
+    // budgets (max_files <= 15), reserve 2 slots so tests aren't crowded out.
+    const tightBudget = (budget.max_files ?? Infinity) <= 15;
+    const reservedTestSlots = tightBudget ? 2 : 0;
+    const mainBudget = {
+        ...budget,
+        max_files: budget.max_files ? budget.max_files - reservedTestSlots : undefined,
+    };
+    // Step 4: Iterate with stop rule (using reduced budget to leave test slots)
+    const state = {
+        files: [],
+        totalTokens: 0,
+        cumulativeScore: 0,
+    };
+    // Collect explain data if requested
+    const explainData = {};
+    for (const scoredFile of scored) {
+        if (shouldStop(state, mainBudget, sufficiencyThreshold, maxCumulative)) {
+            break;
+        }
+        // Extract excerpt
+        const excerpt = extractExcerpt(repoIndex.root, scoredFile.path, keywords, selectorConfig.excerpt_full_file_max_lines, selectorConfig.excerpt_window_lines);
+        const tokenEst = estimateTokens(excerpt.lineCount);
+        // Check if adding this file would blow the budget
+        if (budget.tokens && state.totalTokens + tokenEst > budget.tokens * 1.1) {
+            // Allow 10% overshoot, then stop
+            if (state.files.length > 0)
+                break;
+        }
+        // Scan for deprecated API patterns
+        const deprecationWarnings = scanDeprecations(excerpt.content, selectorConfig.deprecation_rules);
+        const bundleFile = {
+            path: scoredFile.path,
+            score: Math.round(scoredFile.score * 1000) / 1000,
+            reasons: scoredFile.reasons,
+            excerpt_spans: excerpt.spans,
+            content: excerpt.content,
+            token_estimate: tokenEst,
+            deprecation_warnings: deprecationWarnings.length > 0 ? deprecationWarnings : undefined,
+        };
+        state.files.push(bundleFile);
+        state.totalTokens += tokenEst;
+        state.cumulativeScore += Math.max(0, scoredFile.score);
+        if (explain) {
+            explainData[scoredFile.path] = scoredFile.features;
+        }
+    }
+    // Step 5: Deterministic test pairing — if a source file was selected and
+    // it has a mapped test, auto-include the test unless we're at the hard cap.
+    // Pairs are sorted by source file score so the most relevant tests fill
+    // reserved slots first. This prevents test starvation under tight budgets.
+    const selectedPaths = new Set(state.files.map((f) => f.path));
+    const sourceScoreMap = new Map(state.files.map((f) => [f.path, f.score]));
+    const testPairCandidates = [];
+    for (const mapping of repoIndex.test_map) {
+        if (selectedPaths.has(mapping.source_file) && !selectedPaths.has(mapping.test_file)) {
+            testPairCandidates.push({
+                testPath: mapping.test_file,
+                sourceScore: sourceScoreMap.get(mapping.source_file) ?? 0,
+            });
+        }
+    }
+    // Sort by source score descending — pair tests for highest-scored files first
+    testPairCandidates.sort((a, b) => b.sourceScore - a.sourceScore);
+    for (const { testPath } of testPairCandidates) {
+        if (budget.max_files && state.files.length >= budget.max_files)
+            break;
+        const excerpt = extractExcerpt(repoIndex.root, testPath, keywords, selectorConfig.excerpt_full_file_max_lines, selectorConfig.excerpt_window_lines);
+        const tokenEst = estimateTokens(excerpt.lineCount);
+        if (budget.tokens && state.totalTokens + tokenEst > budget.tokens * 1.1)
+            continue;
+        // Find the scored entry if it exists, otherwise create a minimal one
+        const scoredEntry = scored.find((s) => s.path === testPath);
+        state.files.push({
+            path: testPath,
+            score: scoredEntry ? Math.round(scoredEntry.score * 1000) / 1000 : 0,
+            reasons: scoredEntry?.reasons ?? ['test_relevant'],
+            excerpt_spans: excerpt.spans,
+            content: excerpt.content,
+            token_estimate: tokenEst,
+        });
+        state.totalTokens += tokenEst;
+    }
+    // Step 6: Generate interface stubs for unselected dependencies.
+    // These give the agent the type signatures of files adjacent to the bundle
+    // without the full token cost.
+    const finalSelectedPaths = new Set(state.files.map((f) => f.path));
+    const tokenBudgetRemaining = (budget.tokens ?? Infinity) - state.totalTokens;
+    const maxStubs = Math.max(0, (budget.max_files ?? 25) - state.files.length);
+    if (maxStubs > 0 && tokenBudgetRemaining > 0) {
+        const stubs = generateInterfaceStubs(repoIndex.root, finalSelectedPaths, repoIndex.dep_graph, Math.min(maxStubs, 5), // cap at 5 stubs
+        Math.min(tokenBudgetRemaining, 1000));
+        for (const stub of stubs) {
+            state.files.push(stub);
+            state.totalTokens += stub.token_estimate;
+        }
+    }
+    // Step 7: Assess bundle confidence
+    const confidence = assessConfidence(state.files, state.cumulativeScore, keywords.length);
+    return {
+        bundle_id: `bnd_${randomUUID().slice(0, 12)}`,
+        task: taskText,
+        budget,
+        sufficiency_threshold: sufficiencyThreshold,
+        cumulative_score: Math.round(state.cumulativeScore * 1000) / 1000,
+        files: state.files,
+        total_tokens: state.totalTokens,
+        generated_at: new Date().toISOString(),
+        confidence,
+        explain: explain ? explainData : undefined,
+    };
+}
+//# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAoB,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAkB,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAapD,MAAM,UAAU,WAAW,CAAC,IAAwB;IAClD,MAAM,EACJ,QAAQ,EACR,SAAS,EACT,cAAc,EACd,MAAM,GAAG,cAAc,CAAC,cAAc,EACtC,oBAAoB,GAAG,cAAc,CAAC,qBAAqB,EAC3D,WAAW,EACX,OAAO,GAAG,KAAK,GAChB,GAAG,IAAI,CAAC;IAET,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAExC,qEAAqE;IACrE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,GAC3D,kBAAkB,CAAC,QAAQ,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;IAE1D,kEAAkE;IAClE,MAAM,MAAM,GAAG,kBAAkB,CAC/B,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,cAAc,CAAC,OAAO,EACtB,WAAW,EACX,YAAY,EACZ,WAAW,CACZ,CAAC;IAEF,qDAAqD;IACrD,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAE/E,gEAAgE;IAChE,wEAAwE;IACxE,0EAA0E;IAC1E,MAAM,WAAW,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzD,MAAM,iBAAiB,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAW;QACzB,GAAG,MAAM;QACT,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,GAAG,iBAAiB,CAAC,CAAC,CAAC,SAAS;KAC/E,CAAC;IAEF,4EAA4E;IAC5E,MAAM,KAAK,GAAc;QACvB,KAAK,EAAE,EAAE;QACT,WAAW,EAAE,CAAC;QACd,eAAe,EAAE,CAAC;KACnB,CAAC;IAEF,oCAAoC;IACpC,MAAM,WAAW,GAAiC,EAAE,CAAC;IAErD,KAAK,MAAM,UAAU,IAAI,MAAM,EAAE,CAAC;QAChC,IAAI,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,CAAC,EAAE,CAAC;YACvE,MAAM;QACR,CAAC;QAED,kBAAkB;QAClB,MAAM,OAAO,GAAG,cAAc,CAC5B,SAAS,CAAC,IAAI,EACd,UAAU,CAAC,IAAI,EACf,QAAQ,EACR,cAAc,CAAC,2BAA2B,EAC1C,cAAc,CAAC,oBAAoB,CACpC,CAAC;QAEF,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEnD,kDAAkD;QAClD,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YACxE,iCAAiC;YACjC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM;QACpC,CAAC;QAED,mCAAmC;QACnC,MAAM,mBAAmB,GAAG,gBAAgB,CAC1C,OAAO,CAAC,OAAO,EACf,cAAc,CAAC,iBAAiB,CACjC,CAAC;QAEF,MAAM,UAAU,GAAe;YAC7B,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,IAAI;YACjD,OAAO,EAAE,UAAU,CAAC,OAAO;YAC3B,aAAa,EAAE,OAAO,CAAC,KAAK;YAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc,EAAE,QAAQ;YACxB,oBAAoB,EAAE,mBAAmB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,SAAS;SACvF,CAAC;QAEF,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC7B,KAAK,CAAC,WAAW,IAAI,QAAQ,CAAC;QAC9B,KAAK,CAAC,eAAe,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;QAEvD,IAAI,OAAO,EAAE,CAAC;YACZ,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC;QACrD,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,4EAA4E;IAC5E,wEAAwE;IACxE,2EAA2E;IAC3E,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1E,MAAM,kBAAkB,GAAqD,EAAE,CAAC;IAChF,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,QAAQ,EAAE,CAAC;QACzC,IAAI,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACpF,kBAAkB,CAAC,IAAI,CAAC;gBACtB,QAAQ,EAAE,OAAO,CAAC,SAAS;gBAC3B,WAAW,EAAE,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC;aAC1D,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,8EAA8E;IAC9E,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IAEjE,KAAK,MAAM,EAAE,QAAQ,EAAE,IAAI,kBAAkB,EAAE,CAAC;QAC9C,IAAI,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,SAAS;YAAE,MAAM;QAEtE,MAAM,OAAO,GAAG,cAAc,CAC5B,SAAS,CAAC,IAAI,EACd,QAAQ,EACR,QAAQ,EACR,cAAc,CAAC,2BAA2B,EAC1C,cAAc,CAAC,oBAAoB,CACpC,CAAC;QACF,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEnD,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,GAAG;YAAE,SAAS;QAElF,qEAAqE;QACrE,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;QAE5D,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YACpE,OAAO,EAAE,WAAW,EAAE,OAAO,IAAI,CAAC,eAAe,CAAC;YAClD,aAAa,EAAE,OAAO,CAAC,KAAK;YAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc,EAAE,QAAQ;SACzB,CAAC,CAAC;QACH,KAAK,CAAC,WAAW,IAAI,QAAQ,CAAC;IAChC,CAAC;IAED,gEAAgE;IAChE,2EAA2E;IAC3E,+BAA+B;IAC/B,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACnE,MAAM,oBAAoB,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC;IAC7E,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAE5E,IAAI,QAAQ,GAAG,CAAC,IAAI,oBAAoB,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,sBAAsB,CAClC,SAAS,CAAC,IAAI,EACd,kBAAkB,EAClB,SAAS,CAAC,SAAS,EACnB,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,iBAAiB;QACxC,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,CAAC,CACrC,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC,cAAc,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,mCAAmC;IACnC,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEzF,OAAO;QACL,SAAS,EAAE,OAAO,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;QAC7C,IAAI,EAAE,QAAQ;QACd,MAAM;QACN,qBAAqB,EAAE,oBAAoB;QAC3C,gBAAgB,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,IAAI;QACjE,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,YAAY,EAAE,KAAK,CAAC,WAAW;QAC/B,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtC,UAAU;QACV,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;KAC3C,CAAC;AACJ,CAAC"}

package/dist/candidates.d.ts

@@ -0,0 +1,20 @@
+import type { RepoIndex, SelectorConfig } from '@codeledger/types';
+export interface CandidateResult {
+    candidates: Set<string>;
+    tokenWeights: Map<string, number>;
+    fanoutFiles: Set<string>;
+}
+export declare function tokenizeTask(taskText: string): string[];
+/**
+ * Compute IDF-like token weights based on how many files each keyword matches.
+ *
+ * idf = 1 / sqrt(max(1, matchCount)), clamped to [0.35, 1.0].
+ *
+ * Additional penalties:
+ *  - Short tokens (length <= 2): floor to 0.35 — "ts", "db", "id" are noise.
+ *  - Generic tokens (matchCount > hotZoneCount): floor to 0.35 — "api",
+ *    "service" appear everywhere and shouldn't dominate scoring.
+ */
+export declare function computeTokenWeights(keywords: string[], repoIndex: RepoIndex, hotZoneCount: number): Map<string, number>;
+export declare function generateCandidates(taskText: string, repoIndex: RepoIndex, config: SelectorConfig): CandidateResult;
+//# sourceMappingURL=candidates.d.ts.map

package/dist/candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../src/candidates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,SAAS,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAoE7E,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAcvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAAE,EAClB,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,MAAM,GACnB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAwCrB;AAyCD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,cAAc,GACrB,eAAe,CAoHjB"}

package/dist/candidates.js

@@ -0,0 +1,305 @@
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+    'of', 'with', 'by', 'from', 'is', 'it', 'that', 'this', 'be', 'as',
+    'are', 'was', 'were', 'been', 'being', 'have', 'has', 'had', 'do',
+    'does', 'did', 'will', 'would', 'could', 'should', 'may', 'might',
+    'shall', 'can', 'need', 'must', 'not', 'no', 'if', 'then', 'else',
+    'when', 'up', 'out', 'so', 'than', 'too', 'very', 'just', 'about',
+    'into', 'over', 'after', 'before', 'between', 'under', 'above',
+    'all', 'each', 'every', 'both', 'few', 'more', 'most', 'some', 'any',
+    'add', 'fix', 'update', 'change', 'make', 'use', 'get', 'set',
+    'find', 'check', 'look', 'see', 'know', 'think', 'want', 'try',
+    'run', 'show', 'help', 'work', 'take', 'give', 'tell', 'call',
+    'go', 'come', 'keep', 'let', 'begin', 'start', 'end', 'stop',
+    'ready', 'live', 'done', 'good', 'new', 'old', 'big', 'small',
+]);
+/**
+ * Words that are contextual: they act as stop words in broad/assessment tasks
+ * but are useful keywords in targeted coding tasks.
+ *
+ * "test the app for readiness" -> "test" is noise (broad assessment)
+ * "fix the test for authService" -> "test" is signal (specific target)
+ *
+ * Heuristic: if the task contains broad-assessment phrases, demote these
+ * words by treating them as stop words.
+ */
+const CONTEXTUAL_WORDS = new Set([
+    'test', 'tests', 'testing', 'build', 'lint', 'debug', 'deploy',
+    'review', 'audit', 'evaluate', 'assess', 'analyze', 'examine',
+    'application', 'app', 'project', 'codebase', 'code', 'repo',
+]);
+/** Phrases indicating a broad assessment task rather than a focused coding task.
+ *  Matched with word boundaries to avoid false positives
+ *  (e.g. "full" in "full-text search"). */
+const BROAD_TASK_PHRASES = [
+    'ready for', 'go live', 'production ready', 'readiness',
+    'find out', 'evaluate', 'assess', 'audit', 'review the',
+    'status of', 'state of', 'quality of', 'health of',
+    'overall', 'end to end', 'full', 'comprehensive',
+].map((phrase) => new RegExp(`\\b${phrase}\\b`));
+/**
+ * Phrases that signal cross-cutting fan-out intent: the task wants to touch
+ * every file that depends on a target module.
+ * Matched with word boundaries to prevent false positives
+ * (e.g. "replace" in "irreplaceable").
+ */
+const FANOUT_TRIGGERS = [
+    'replace', 'everywhere', 'all files', 'every file',
+    'migrate', 'files that import', 'files that use',
+    'across all', 'update all', 'rename all',
+].map((phrase) => new RegExp(`\\b${phrase}\\b`));
+const FANOUT_CEILING = 50;
+/** Default contract/schema patterns when not configured */
+const DEFAULT_CONTRACT_PATTERNS = [
+    '.sql', '.proto', '.prisma', '.graphql', '.gql',
+];
+/** Path segments that indicate contract/schema files */
+const CONTRACT_PATH_INDICATORS = [
+    'openapi', 'swagger', 'schema', 'migrations',
+];
+export function tokenizeTask(taskText) {
+    const lower = taskText.toLowerCase();
+    const isBroadTask = BROAD_TASK_PHRASES.some((re) => re.test(lower));
+    // Build effective stop word set: include contextual words for broad tasks
+    const effectiveStopWords = isBroadTask
+        ? new Set([...STOP_WORDS, ...CONTEXTUAL_WORDS])
+        : STOP_WORDS;
+    const words = lower
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((w) => w.length > 1 && !effectiveStopWords.has(w));
+    return [...new Set(words)];
+}
+/**
+ * Compute IDF-like token weights based on how many files each keyword matches.
+ *
+ * idf = 1 / sqrt(max(1, matchCount)), clamped to [0.35, 1.0].
+ *
+ * Additional penalties:
+ *  - Short tokens (length <= 2): floor to 0.35 — "ts", "db", "id" are noise.
+ *  - Generic tokens (matchCount > hotZoneCount): floor to 0.35 — "api",
+ *    "service" appear everywhere and shouldn't dominate scoring.
+ */
+export function computeTokenWeights(keywords, repoIndex, hotZoneCount) {
+    const weights = new Map();
+    for (const kw of keywords) {
+        let matchCount = 0;
+        for (const file of repoIndex.files) {
+            // Count matches from both path and content keywords
+            if (file.path.toLowerCase().includes(kw)) {
+                matchCount++;
+            }
+            else if (file.content_keywords?.some((ck) => ck === kw || ck === kw + 's' || kw === ck + 's')) {
+                matchCount++;
+            }
+        }
+        // Keywords matching zero files are noise — weight 0 so they don't
+        // inflate the keyword normalization denominator.
+        if (matchCount === 0) {
+            weights.set(kw, 0);
+            continue;
+        }
+        let idf = 1 / Math.sqrt(Math.max(1, matchCount));
+        // Short tokens (≤2 chars): weight floor
+        if (kw.length <= 2) {
+            idf = Math.min(idf, 0.35);
+        }
+        // Generic token penalty: matchCount > hotZoneCount → floor
+        if (matchCount > hotZoneCount) {
+            idf = Math.min(idf, 0.35);
+        }
+        // Clamp to [0.35, 1.0]
+        idf = Math.max(0.35, Math.min(1.0, idf));
+        weights.set(kw, idf);
+    }
+    return weights;
+}
+/**
+ * Detect whether the task text signals cross-cutting fan-out intent.
+ */
+function detectFanoutIntent(taskText) {
+    const lower = taskText.toLowerCase();
+    return FANOUT_TRIGGERS.some((re) => re.test(lower));
+}
+/**
+ * Find files whose basename stem matches a keyword exactly (with plural
+ * tolerance). These are "strong targets" for fan-out expansion.
+ *
+ * Stem splitting: basename without extension, split on `-` and `_`.
+ *   e.g. "rate-limiter.ts" → ["rate", "limiter"]
+ *        "helpers.ts" → ["helpers"]
+ */
+function findStrongTargets(keywords, repoIndex) {
+    const targets = [];
+    for (const file of repoIndex.files) {
+        const pathLower = file.path.toLowerCase();
+        const basename = pathLower.split('/').pop()?.replace(/\.\w+$/, '') ?? '';
+        const stems = basename.split(/[-_]/);
+        for (const kw of keywords) {
+            const isStemMatch = stems.some((stem) => stem === kw || stem === kw + 's' || kw === stem + 's');
+            if (isStemMatch) {
+                targets.push(file.path);
+                break;
+            }
+        }
+    }
+    return targets;
+}
+export function generateCandidates(taskText, repoIndex, config) {
+    const candidates = new Set();
+    const fanoutFiles = new Set();
+    const keywords = tokenizeTask(taskText);
+    // Compute IDF token weights
+    const tokenWeights = computeTokenWeights(keywords, repoIndex, config.hot_zone_count);
+    // 1. Keyword match: file paths + names + content keywords
+    for (const file of repoIndex.files) {
+        const pathLower = file.path.toLowerCase();
+        for (const kw of keywords) {
+            if (pathLower.includes(kw)) {
+                candidates.add(file.path);
+                break;
+            }
+            // Content-aware matching: check identifiers extracted during scanning
+            if (file.content_keywords?.some((ck) => ck === kw || ck === kw + 's' || kw === ck + 's')) {
+                candidates.add(file.path);
+                break;
+            }
+        }
+    }
+    // 2. Hot zone: top N by churn — only when budget is generous.
+    //    Under tight budgets (max_files <= 15), hot-zone is a precision killer
+    //    because churn-heavy files crowd out task-specific ones. In that case
+    //    hot-zone only contributes files that already have a keyword hit.
+    const tightMode = (config.default_budget.max_files ?? Infinity) <= 15;
+    const hotZone = repoIndex.churn.slice(0, config.hot_zone_count);
+    for (const churnEntry of hotZone) {
+        if (!repoIndex.files.some((f) => f.path === churnEntry.path))
+            continue;
+        if (tightMode && !candidates.has(churnEntry.path))
+            continue;
+        candidates.add(churnEntry.path);
+    }
+    // 3. Dependency neighborhood: expand from keyword-matched files
+    const keywordMatched = [...candidates];
+    for (const seed of keywordMatched) {
+        expandDependencies(seed, repoIndex, candidates, config.dependency_depth, config.dependency_cap_per_seed);
+    }
+    // 4. Fan-out expansion: when task describes a cross-cutting change AND a
+    //    strong target file is identified, expand ALL direct dependents (depth=1)
+    //    without per-seed cap. Optionally expand depth=2 if under ceiling.
+    if (detectFanoutIntent(taskText)) {
+        const strongTargets = findStrongTargets(keywords, repoIndex);
+        for (const target of strongTargets) {
+            if (candidates.size >= FANOUT_CEILING)
+                break;
+            // Depth 1: all direct dependents — always mark as fanout even if
+            // already discovered by normal dependency expansion, so they receive
+            // the fan-out scoring bonus.
+            const dependents = repoIndex.dep_graph.dependents[target] ?? [];
+            for (const dep of dependents) {
+                if (candidates.size >= FANOUT_CEILING)
+                    break;
+                candidates.add(dep);
+                fanoutFiles.add(dep);
+            }
+            // Depth 2: only if under ceiling
+            if (candidates.size < FANOUT_CEILING) {
+                for (const dep of dependents) {
+                    if (candidates.size >= FANOUT_CEILING)
+                        break;
+                    const depth2Deps = repoIndex.dep_graph.dependents[dep] ?? [];
+                    for (const dep2 of depth2Deps) {
+                        if (candidates.size >= FANOUT_CEILING)
+                            break;
+                        candidates.add(dep2);
+                        fanoutFiles.add(dep2);
+                    }
+                }
+            }
+        }
+    }
+    // 5. Test neighborhood: add test files mapped to candidates
+    const currentCandidates = [...candidates];
+    for (const mapping of repoIndex.test_map) {
+        if (currentCandidates.includes(mapping.source_file)) {
+            candidates.add(mapping.test_file);
+        }
+        if (currentCandidates.includes(mapping.test_file)) {
+            candidates.add(mapping.source_file);
+        }
+    }
+    // 6. Contract/schema auto-inclusion: when the bundle touches DB models,
+    //    API routes, or services, auto-include related contract files (.sql,
+    //    .proto, .prisma, .graphql, openapi specs) so the agent sees the
+    //    actual data model instead of guessing.
+    const contractFiles = findContractFiles(repoIndex.files, config.contract_patterns);
+    if (contractFiles.length > 0 && candidates.size > 0) {
+        // Only include contracts that share a directory prefix with existing candidates
+        const candidateDirs = new Set([...candidates].map((p) => p.split('/').slice(0, -1).join('/')));
+        for (const cf of contractFiles) {
+            const cfDir = cf.split('/').slice(0, -1).join('/');
+            // Include if the contract shares a directory with any candidate,
+            // or if any candidate is in a subdirectory of the contract's dir
+            const isRelated = candidateDirs.has(cfDir) ||
+                [...candidateDirs].some((d) => d.startsWith(cfDir + '/') || cfDir.startsWith(d + '/'));
+            if (isRelated) {
+                candidates.add(cf);
+            }
+        }
+    }
+    return { candidates, tokenWeights, fanoutFiles };
+}
+/**
+ * Identify contract/schema files in the repo based on extension and path patterns.
+ */
+function findContractFiles(files, customPatterns) {
+    const results = [];
+    for (const file of files) {
+        const ext = file.extension.toLowerCase();
+        const pathLower = file.path.toLowerCase();
+        // Match by extension
+        if (DEFAULT_CONTRACT_PATTERNS.includes(ext)) {
+            results.push(file.path);
+            continue;
+        }
+        // Match by custom patterns
+        if (customPatterns?.some((pat) => pathLower.includes(pat.toLowerCase()))) {
+            results.push(file.path);
+            continue;
+        }
+        // Match by path indicators (openapi.yaml, schema.json, etc.)
+        const basename = pathLower.split('/').pop() ?? '';
+        if (CONTRACT_PATH_INDICATORS.some((ind) => basename.startsWith(ind))) {
+            results.push(file.path);
+        }
+    }
+    return results;
+}
+function expandDependencies(seed, repoIndex, candidates, maxDepth, capPerSeed) {
+    let frontier = [seed];
+    let added = 0;
+    for (let depth = 0; depth < maxDepth && added < capPerSeed; depth++) {
+        const nextFrontier = [];
+        for (const file of frontier) {
+            // Add imports
+            const imports = repoIndex.dep_graph.imports[file] ?? [];
+            for (const dep of imports) {
+                if (!candidates.has(dep) && added < capPerSeed) {
+                    candidates.add(dep);
+                    nextFrontier.push(dep);
+                    added++;
+                }
+            }
+            // Add dependents (reverse)
+            const dependents = repoIndex.dep_graph.dependents[file] ?? [];
+            for (const dep of dependents) {
+                if (!candidates.has(dep) && added < capPerSeed) {
+                    candidates.add(dep);
+                    nextFrontier.push(dep);
+                    added++;
+                }
+            }
+        }
+        frontier = nextFrontier;
+    }
+}
+//# sourceMappingURL=candidates.js.map

package/dist/candidates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidates.js","sourceRoot":"","sources":["../src/candidates.ts"],"names":[],"mappings":"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"}

package/dist/confidence.d.ts

@@ -0,0 +1,11 @@
+import type { BundleConfidence, BundleFile } from '@codeledger/types';
+/**
+ * Assess bundle confidence based on signal quality.
+ *
+ * A high-confidence bundle has strong keyword matches, concentrated scores,
+ * and at least one file with a keyword_match reason in the top positions.
+ * A low-confidence bundle was driven by churn/centrality noise with weak
+ * keyword signal — the developer should refine their task description.
+ */
+export declare function assessConfidence(files: BundleFile[], _cumulativeScore: number, taskKeywordCount: number): BundleConfidence;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.d.ts","sourceRoot":"","sources":["../src/confidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAmB,MAAM,mBAAmB,CAAC;AAEvF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EAAE,EACnB,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM,GACvB,gBAAgB,CA+ElB"}

package/dist/confidence.js

@@ -0,0 +1,86 @@
+/**
+ * Assess bundle confidence based on signal quality.
+ *
+ * A high-confidence bundle has strong keyword matches, concentrated scores,
+ * and at least one file with a keyword_match reason in the top positions.
+ * A low-confidence bundle was driven by churn/centrality noise with weak
+ * keyword signal — the developer should refine their task description.
+ */
+export function assessConfidence(files, _cumulativeScore, taskKeywordCount) {
+    const reasons = [];
+    let score = 0;
+    if (files.length === 0) {
+        return { level: 'low', score: 0, reasons: ['Empty bundle — no files matched'] };
+    }
+    // Factor 1: Keyword coverage — do top files have keyword matches?
+    const topFiles = files.slice(0, 5);
+    const keywordHits = topFiles.filter((f) => f.reasons.includes('keyword_match'));
+    const keywordRatio = keywordHits.length / topFiles.length;
+    if (keywordRatio >= 0.6) {
+        score += 0.35;
+        reasons.push(`Strong keyword signal: ${keywordHits.length}/${topFiles.length} top files match task keywords`);
+    }
+    else if (keywordRatio > 0) {
+        score += 0.15;
+        reasons.push(`Weak keyword signal: only ${keywordHits.length}/${topFiles.length} top files match task keywords`);
+    }
+    else {
+        reasons.push('No keyword matches in top 5 files — selection driven by churn/centrality');
+    }
+    // Factor 2: Score concentration — is the top file significantly better?
+    if (files.length >= 2) {
+        const topScore = files[0].score;
+        const secondScore = files[1].score;
+        if (topScore > 0 && secondScore > 0) {
+            const gap = (topScore - secondScore) / topScore;
+            if (gap >= 0.3) {
+                score += 0.2;
+                reasons.push('Clear top-ranked file with significant score gap');
+            }
+            else {
+                score += 0.1;
+            }
+        }
+    }
+    // Factor 3: Reason diversity — files selected for multiple reasons are stronger
+    const avgReasons = files.reduce((sum, f) => sum + f.reasons.length, 0) / files.length;
+    if (avgReasons >= 2.0) {
+        score += 0.2;
+        reasons.push('Files selected for multiple independent reasons');
+    }
+    else if (avgReasons >= 1.5) {
+        score += 0.1;
+    }
+    // Factor 4: Task specificity — more keywords = more discriminating
+    if (taskKeywordCount >= 3) {
+        score += 0.15;
+    }
+    else if (taskKeywordCount >= 2) {
+        score += 0.1;
+    }
+    else {
+        reasons.push('Task description has few discriminating keywords — consider being more specific');
+    }
+    // Factor 5: Bundle isn't just test files
+    const nonTestFiles = files.filter((f) => !f.reasons.every((r) => r === 'test_relevant'));
+    if (nonTestFiles.length >= files.length * 0.5) {
+        score += 0.1;
+    }
+    // Determine level
+    let level;
+    if (score >= 0.65) {
+        level = 'high';
+    }
+    else if (score >= 0.35) {
+        level = 'medium';
+    }
+    else {
+        level = 'low';
+    }
+    return {
+        level,
+        score: Math.round(score * 100) / 100,
+        reasons,
+    };
+}
+//# sourceMappingURL=confidence.js.map