@thoughtflow/core 0.1.2

package/dist/contexts/context-decomposer.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextDecomposer = void 0;
+const crypto_1 = require("crypto");
+const zod_1 = require("zod");
+const structured_call_1 = require("../libs/structured-call");
+const DecompositionSchema = zod_1.z.object({
+    documents: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string(),
+        summary: zod_1.z.string(),
+        keywords: zod_1.z.array(zod_1.z.string()),
+        category: zod_1.z.enum(["architecture", "security", "domain", "conventions", "data", "other"])
+    })),
+    tools: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string(),
+        description: zod_1.z.string(),
+        category: zod_1.z.string(),
+        keywords: zod_1.z.array(zod_1.z.string())
+    }))
+});
+const SYSTEM_PROMPT = "You are a document and tool analyzer. Your job is to produce concise structured metadata about documents and tools.";
+function buildUserPrompt(docs, tools) {
+    const parts = [];
+    if (docs.length > 0) {
+        parts.push("Documents:");
+        for (const doc of docs) {
+            parts.push(`- Name: ${doc.name}`);
+            parts.push(`  Content: ${doc.content}`);
+            parts.push('');
+        }
+    }
+    else {
+        parts.push("No documents to analyze.");
+        parts.push('');
+    }
+    if (tools.length > 0) {
+        parts.push("Tools:");
+        for (const tool of tools) {
+            parts.push(`- Name: ${tool.name}`);
+            parts.push(`  Description: ${tool.description}`);
+            parts.push('');
+        }
+    }
+    else {
+        parts.push("No tools to analyze.");
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+class ContextDecomposer {
+    adapter;
+    model;
+    constructor(adapter, model) {
+        this.adapter = adapter;
+        this.model = model;
+    }
+    /**
+     * Decompose documents and tools using an LLM.
+     * Only decomposes the given docs (typically only changed ones).
+     * Tool analysis happens on every call for freshness.
+     */
+    async decompose(docs, tools) {
+        try {
+            const userPrompt = buildUserPrompt(docs, tools);
+            const { result } = await (0, structured_call_1.callStructured)(this.adapter, this.model, SYSTEM_PROMPT, userPrompt, DecompositionSchema);
+            const documents = result.documents.map(d => ({
+                name: d.name,
+                checksum: (0, crypto_1.createHash)('md5').update(docs.find(doc => doc.name === d.name)?.content ?? '').digest('hex'),
+                summary: d.summary,
+                keywords: d.keywords,
+                category: d.category,
+                decomposedAt: Date.now()
+            }));
+            const toolCapabilities = result.tools.map(t => ({
+                name: t.name,
+                description: t.description,
+                category: t.category,
+                keywords: t.keywords
+            }));
+            return {
+                documents,
+                tools: toolCapabilities,
+                generatedAt: Date.now()
+            };
+        }
+        catch (err) {
+            console.warn('ContextDecomposer.decompose failed:', err);
+            return {
+                documents: [],
+                tools: [],
+                generatedAt: Date.now()
+            };
+        }
+    }
+}
+exports.ContextDecomposer = ContextDecomposer;
+//# sourceMappingURL=context-decomposer.js.map

package/dist/contexts/context-decomposer.js.map

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

package/dist/contexts/context-document-manager.d.ts

@@ -0,0 +1,21 @@
+import type { ContextDocument, ContextDocumentCache } from '../contracts/context-document.types';
+export declare class ContextDocumentManager {
+    private readonly docs;
+    private readonly cacheDir;
+    /**
+     * @param docs     Map of document name → content (user-provided)
+     * @param cacheDir Path to cache file (e.g. ".thoughtflow/context-cache.json")
+     */
+    constructor(docs: Record<string, string>, cacheDir: string);
+    /** Load cached decomposition results from disk. Returns empty array if no cache exists. */
+    loadCache(): ContextDocumentCache[];
+    /** Compute MD5 checksum for each document. Returns Map<docName, checksumHex>. */
+    computeChecksums(): Map<string, string>;
+    /** Return documents whose checksum differs from the cache (or are new). */
+    getChangedDocs(): ContextDocument[];
+    /** Persist the given cache entries to disk as JSON. */
+    saveCache(caches: ContextDocumentCache[]): void;
+    /** Return all documents as ContextDocument[] (the raw input map). */
+    getAllDocs(): ContextDocument[];
+}
+//# sourceMappingURL=context-document-manager.d.ts.map

package/dist/contexts/context-document-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-document-manager.d.ts","sourceRoot":"","sources":["../../src/contexts/context-document-manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAA;AAEhG,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IAEjC;;;OAGG;gBACS,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM;IAK1D,2FAA2F;IAC3F,SAAS,IAAI,oBAAoB,EAAE;IAYnC,iFAAiF;IACjF,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IASvC,2EAA2E;IAC3E,cAAc,IAAI,eAAe,EAAE;IAgBnC,uDAAuD;IACvD,SAAS,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,IAAI;IAM/C,qEAAqE;IACrE,UAAU,IAAI,eAAe,EAAE;CAGhC"}

package/dist/contexts/context-document-manager.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextDocumentManager = void 0;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+class ContextDocumentManager {
+    docs;
+    cacheDir;
+    /**
+     * @param docs     Map of document name → content (user-provided)
+     * @param cacheDir Path to cache file (e.g. ".thoughtflow/context-cache.json")
+     */
+    constructor(docs, cacheDir) {
+        this.docs = docs;
+        this.cacheDir = cacheDir;
+    }
+    /** Load cached decomposition results from disk. Returns empty array if no cache exists. */
+    loadCache() {
+        try {
+            if (!(0, fs_1.existsSync)(this.cacheDir))
+                return [];
+            const raw = (0, fs_1.readFileSync)(this.cacheDir, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                return [];
+            return parsed;
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Compute MD5 checksum for each document. Returns Map<docName, checksumHex>. */
+    computeChecksums() {
+        const checksums = new Map();
+        for (const [name, content] of Object.entries(this.docs)) {
+            const hash = (0, crypto_1.createHash)('md5').update(content).digest('hex');
+            checksums.set(name, hash);
+        }
+        return checksums;
+    }
+    /** Return documents whose checksum differs from the cache (or are new). */
+    getChangedDocs() {
+        const caches = this.loadCache();
+        const checksums = this.computeChecksums();
+        const cacheByDoc = new Map(caches.map(c => [c.name, c]));
+        const changed = [];
+        for (const [name, content] of Object.entries(this.docs)) {
+            const checksum = checksums.get(name);
+            const cached = cacheByDoc.get(name);
+            if (!cached || cached.checksum !== checksum) {
+                changed.push({ name, content });
+            }
+        }
+        return changed;
+    }
+    /** Persist the given cache entries to disk as JSON. */
+    saveCache(caches) {
+        const dir = (0, path_1.dirname)(this.cacheDir);
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+        (0, fs_1.writeFileSync)(this.cacheDir, JSON.stringify(caches, null, 2), 'utf-8');
+    }
+    /** Return all documents as ContextDocument[] (the raw input map). */
+    getAllDocs() {
+        return Object.entries(this.docs).map(([name, content]) => ({ name, content }));
+    }
+}
+exports.ContextDocumentManager = ContextDocumentManager;
+//# sourceMappingURL=context-document-manager.js.map

package/dist/contexts/context-document-manager.js.map

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

package/dist/contexts/context-router.d.ts

@@ -0,0 +1,14 @@
+import type { ContextRoutingConfig, ContextDocumentCache } from '../contracts/context-document.types';
+import type { LlmAdapter } from '../contracts/llm.types';
+export declare class ContextRouter {
+    private readonly config;
+    private readonly adapter;
+    private readonly model;
+    constructor(config: ContextRoutingConfig, adapter: LlmAdapter, model: string);
+    /**
+     * Route the given prompt against cached document metadata.
+     * Returns the list of document names that are relevant.
+     */
+    route(prompt: string, documents: ContextDocumentCache[]): Promise<string[]>;
+}
+//# sourceMappingURL=context-router.d.ts.map

package/dist/contexts/context-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-router.d.ts","sourceRoot":"","sources":["../../src/contexts/context-router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAA;AACrG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAoDxD,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAFL,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,MAAM;IAGhC;;;OAGG;IACG,KAAK,CACT,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,oBAAoB,EAAE,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC;CAsDrB"}

package/dist/contexts/context-router.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextRouter = void 0;
+const structured_call_1 = require("../libs/structured-call");
+const zod_1 = require("zod");
+const STOP_WORDS = new Set([
+    'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'shall',
+    'should', 'may', 'might', 'must', 'can', 'could', 'i', 'me', 'my',
+    'we', 'our', 'you', 'your', 'he', 'she', 'it', 'they', 'them', 'this',
+    'that', 'these', 'those', 'in', 'on', 'at', 'to', 'for', 'of', 'with',
+    'by', 'from', 'and', 'or', 'not', 'but', 'if', 'so', 'no', 'yes',
+    'what', 'which', 'who', 'whom', 'when', 'where', 'why', 'how'
+]);
+function tokenize(text) {
+    return new Set(text.toLowerCase()
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(w => w.length > 0 && !STOP_WORDS.has(w)));
+}
+function computeScore(promptTokens, doc) {
+    if (doc.keywords.length === 0)
+        return 0;
+    let matches = 0;
+    for (const kw of doc.keywords) {
+        let hasMatch = false;
+        for (const t of tokenize(kw)) {
+            if (promptTokens.has(t)) {
+                hasMatch = true;
+                break;
+            }
+        }
+        if (hasMatch)
+            matches++;
+    }
+    let categoryBonus = 0;
+    if (doc.category && promptTokens.has(doc.category)) {
+        categoryBonus = 0.3;
+    }
+    return (matches / doc.keywords.length) + categoryBonus;
+}
+const routingSchema = zod_1.z.object({
+    relevant: zod_1.z.array(zod_1.z.string())
+});
+class ContextRouter {
+    config;
+    adapter;
+    model;
+    constructor(config, adapter, model) {
+        this.config = config;
+        this.adapter = adapter;
+        this.model = model;
+    }
+    /**
+     * Route the given prompt against cached document metadata.
+     * Returns the list of document names that are relevant.
+     */
+    async route(prompt, documents) {
+        const promptTokens = tokenize(prompt);
+        const strategy = this.config.strategy ?? 'hybrid';
+        const threshold = this.config.relevanceThreshold ?? 0.5;
+        // ── Step 1: keyword matching ────────────────────────────────────
+        const scored = documents.map(doc => ({
+            name: doc.name,
+            score: computeScore(promptTokens, doc)
+        }));
+        const maxScore = Math.max(...scored.map(s => s.score), 0);
+        const normalized = scored.map(s => ({
+            ...s,
+            score: maxScore > 0 ? s.score / maxScore : 0
+        }));
+        const keywordHits = normalized
+            .filter(s => s.score >= threshold)
+            .map(s => s.name);
+        if (strategy === 'keyword') {
+            return keywordHits;
+        }
+        if (strategy === 'hybrid' && keywordHits.length > 0) {
+            return keywordHits;
+        }
+        // ── Step 2: LLM routing ────────────────────────────────────────
+        if (documents.length === 0) {
+            return [];
+        }
+        const routingModel = this.config.model?.model ?? this.model;
+        const docLines = documents
+            .map(d => `- ${d.name}: ${d.summary}`)
+            .join('\n');
+        const userPrompt = `Given the user query: "${prompt}"\n\nSelect which of the following documents are relevant:\n${docLines}`;
+        const result = await (0, structured_call_1.callStructured)(this.adapter, routingModel, 'You are a document routing assistant. Select relevant documents based on the user query.', userPrompt, routingSchema);
+        return result.result.relevant;
+    }
+}
+exports.ContextRouter = ContextRouter;
+//# sourceMappingURL=context-router.js.map

package/dist/contexts/context-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-router.js","sourceRoot":"","sources":["../../src/contexts/context-router.ts"],"names":[],"mappings":";;;AAEA,6DAAwD;AACxD,6BAAuB;AAEvB,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO;IACnE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IACnE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI;IACjE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IACrE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM;IACrE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK;IAChE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK;CAC9D,CAAC,CAAA;AAEF,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,GAAG,CACZ,IAAI,CAAC,WAAW,EAAE;SACf,KAAK,CAAC,eAAe,CAAC;SACtB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CACnD,CAAA;AACH,CAAC;AAED,SAAS,YAAY,CACnB,YAAyB,EACzB,GAAyB;IAEzB,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAEvC,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QAC9B,IAAI,QAAQ,GAAG,KAAK,CAAA;QACpB,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7B,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxB,QAAQ,GAAG,IAAI,CAAA;gBACf,MAAK;YACP,CAAC;QACH,CAAC;QACD,IAAI,QAAQ;YAAE,OAAO,EAAE,CAAA;IACzB,CAAC;IAED,IAAI,aAAa,GAAG,CAAC,CAAA;IACrB,IAAI,GAAG,CAAC,QAAQ,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnD,aAAa,GAAG,GAAG,CAAA;IACrB,CAAC;IAED,OAAO,CAAC,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,aAAa,CAAA;AACxD,CAAC;AAED,MAAM,aAAa,GAAG,OAAC,CAAC,MAAM,CAAC;IAC7B,QAAQ,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;CAC9B,CAAC,CAAA;AAEF,MAAa,aAAa;IAEL;IACA;IACA;IAHnB,YACmB,MAA4B,EAC5B,OAAmB,EACnB,KAAa;QAFb,WAAM,GAAN,MAAM,CAAsB;QAC5B,YAAO,GAAP,OAAO,CAAY;QACnB,UAAK,GAAL,KAAK,CAAQ;IAC7B,CAAC;IAEJ;;;OAGG;IACH,KAAK,CAAC,KAAK,CACT,MAAc,EACd,SAAiC;QAEjC,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,QAAQ,CAAA;QACjD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,kBAAkB,IAAI,GAAG,CAAA;QAEvD,mEAAmE;QAEnE,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACnC,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,KAAK,EAAE,YAAY,CAAC,YAAY,EAAE,GAAG,CAAC;SACvC,CAAC,CAAC,CAAA;QAEH,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;QACzD,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAClC,GAAG,CAAC;YACJ,KAAK,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;SAC7C,CAAC,CAAC,CAAA;QAEH,MAAM,WAAW,GAAG,UAAU;aAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,SAAS,CAAC;aACjC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAEnB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,WAAW,CAAA;QACpB,CAAC;QAED,IAAI,QAAQ,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,OAAO,WAAW,CAAA;QACpB,CAAC;QAED,kEAAkE;QAElE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,CAAA;QACX,CAAC;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,IAAI,IAAI,CAAC,KAAK,CAAA;QAE3D,MAAM,QAAQ,GAAG,SAAS;aACvB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACrC,IAAI,CAAC,IAAI,CAAC,CAAA;QAEb,MAAM,UAAU,GAAG,0BAA0B,MAAM,+DAA+D,QAAQ,EAAE,CAAA;QAE5H,MAAM,MAAM,GAAG,MAAM,IAAA,gCAAc,EACjC,IAAI,CAAC,OAAO,EACZ,YAAY,EACZ,0FAA0F,EAC1F,UAAU,EACV,aAAa,CACd,CAAA;QAED,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAA;IAC/B,CAAC;CACF;AApED,sCAoEC"}

package/dist/contracts/codebase-analysis.types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * A dependency discovered within an analyzed range.
+ * Points to a target file (and optionally a specific range within it).
+ */
+export interface RangeDependency {
+    /** Relative path of the referenced file. */
+    targetFile: string;
+    /** Optional: specific line range in the target that needs analysis. */
+    targetRange?: LineRange;
+    /** Why this dependency exists. E.g. "imports UserEntity", "calls validateAddress()". */
+    reason: string;
+    /** Symbol name being referenced (if identifiable). */
+    symbol?: string;
+    /** Whether the target has already been analyzed at the required range. */
+    resolved: boolean;
+}
+/**
+ * A contiguous range of lines within a file that has been analyzed.
+ * Granularity: import block, class declaration, function body, etc.
+ */
+export interface AnalyzedRange {
+    /** 1-based inclusive start line. */
+    startLine: number;
+    /** 1-based inclusive end line. */
+    endLine: number;
+    /** What this range represents: "import_block", "class_declaration", "function_body", etc. */
+    purpose: string;
+    /** Symbols defined or declared in this range. */
+    symbols: string[];
+    /** Description of what this range does (business/technical purpose). */
+    description: string;
+    /** Dependencies discovered in this range. */
+    dependencies: RangeDependency[];
+    /** When this range was analyzed. */
+    analyzedAt: string;
+    /** LLM confidence in the analysis (0..1). */
+    confidence: number;
+}
+/** Simple 1-based inclusive line range. */
+export interface LineRange {
+    startLine: number;
+    endLine: number;
+}
+/** Status of a file's analysis. */
+export type FileAnalysisStatus = "pending" | "partial" | "complete" | "stale";
+/**
+ * Complete analysis state for a single file.
+ * Persisted as `{sanitized-path}.json` in the analysis store.
+ */
+export interface FileAnalysisRecord {
+    /** Relative path from project root. */
+    filePath: string;
+    /** SHA-256 of the file content at analysis time. */
+    contentHash: string;
+    /** File modification time (ms since epoch). */
+    mtime: number;
+    /** File size in bytes. */
+    sizeBytes: number;
+    /** Analyzed ranges within this file (may not cover all lines). */
+    ranges: AnalyzedRange[];
+    /** Overall analysis status. */
+    status: FileAnalysisStatus;
+    /** Timestamp of last analysis activity. */
+    lastAnalyzedAt: string;
+    /** Total lines in the file. */
+    totalLines: number;
+    /** Lines covered by ranges (sum of range sizes). */
+    analyzedLines: number;
+    /** Structural snapshot from decoder (if available). Persisted alongside LLM analysis. */
+    structuralSnapshot?: import("./structural-decoder.types").StructuralSnapshot;
+}
+/** Why a queue item was created. */
+export type QueueItemReason = "initial_scan" | "dependency" | "re_analysis" | "manual";
+/** Priority levels for queue items. */
+export type QueueItemPriority = "critical" | "high" | "normal" | "low";
+/**
+ * A work item in the analysis queue.
+ * Can target entire file or a specific range within it.
+ */
+export interface AnalysisQueueItem {
+    /** Unique ID for this queue item. */
+    id: string;
+    /** Relative path of the file to analyze. */
+    filePath: string;
+    /** Optional: analyze only this range (null = full file). */
+    targetRange: LineRange | null;
+    /** Why this item is in the queue. */
+    reason: QueueItemReason;
+    /** Priority (determines processing order). */
+    priority: QueueItemPriority;
+    /** Which file+range triggered this entry (traceability). */
+    triggeredBy?: {
+        filePath: string;
+        range?: LineRange;
+        symbol?: string;
+    };
+    /** Processing status. */
+    status: "queued" | "in_progress" | "completed" | "failed";
+    /** When added to the queue. */
+    createdAt: string;
+    /** When processing started (null if not yet started). */
+    startedAt?: string;
+    /** When processing completed. */
+    completedAt?: string;
+    /** Error message if failed. */
+    error?: string;
+    /** Number of retry attempts. */
+    retryCount: number;
+}
+/**
+ * Metadata for an entire analysis session.
+ * Tracks config, progress, and aggregate stats.
+ */
+export interface AnalysisSessionMeta {
+    /** Unique session ID. */
+    sessionId: string;
+    /** Absolute path to the project root. */
+    projectRoot: string;
+    /** Project name (from package.json or directory name). */
+    projectName: string;
+    /** LLM model used. */
+    model: string;
+    /** Context window size. */
+    numCtx: number;
+    /** When the session started. */
+    startedAt: string;
+    /** When the session completed (null if in progress). */
+    completedAt?: string;
+    /** Current phase: collect or prepare. */
+    phase: "collect" | "prepare" | "complete";
+    /** Aggregate stats. */
+    stats: AnalysisSessionStats;
+}
+export interface AnalysisSessionStats {
+    totalFiles: number;
+    analyzedFiles: number;
+    pendingFiles: number;
+    staleFiles: number;
+    totalRanges: number;
+    totalDependencies: number;
+    unresolvedDependencies: number;
+    llmCalls: number;
+    cacheHits: number;
+    totalDurationMs: number;
+}
+/**
+ * Result of analyzing a single range within a file.
+ * Returned by the LLM callback.
+ */
+export interface RangeAnalysisResult {
+    /** The range that was analyzed (may differ from requested if LLM adjusts boundaries). */
+    range: LineRange;
+    /** What this range represents. */
+    purpose: string;
+    /** Symbols found in this range. */
+    symbols: string[];
+    /** Business/technical description. */
+    description: string;
+    /** Dependencies discovered. */
+    dependencies: Array<{
+        targetFile: string;
+        targetRange?: LineRange;
+        reason: string;
+        symbol?: string;
+    }>;
+    /** LLM confidence 0..1. */
+    confidence: number;
+}
+/**
+ * Callbacks injected into IncrementalAnalyzer.
+ * The caller implements LLM integration.
+ */
+export interface IncrementalAnalyzerCallbacks {
+    /**
+     * Analyze a specific range of a file (or full file if range is null).
+     * Return structured analysis of code blocks within the range.
+     */
+    analyzeRange: (filePath: string, content: string, range: LineRange | null, context: RangeAnalysisContext) => Promise<RangeAnalysisResult[]>;
+    /** Optional progress callback. */
+    onProgress?: (message: string, stats: AnalysisSessionStats) => void;
+    /** Optional abort signal. */
+    signal?: AbortSignal;
+}
+/**
+ * Context passed to the LLM for analyzing a range.
+ * Includes known symbols and existing analysis for richer understanding.
+ */
+export interface RangeAnalysisContext {
+    /** Known business concepts from already-analyzed documentation. */
+    knownConcepts: string[];
+    /** Already-analyzed ranges in the same file (for cross-reference). */
+    analyzedRangesInFile: AnalyzedRange[];
+    /** Symbols already known from other files that import from this file. */
+    knownImporters: string[];
+    /** File extension / language hint. */
+    language: string;
+    /**
+     * Structural summary from decoder (if available).
+     * Contains class/function signatures, imports, exports — extracted
+     * deterministically without LLM. LLM should focus on semantics/business logic.
+     */
+    structuralSummary?: string;
+}
+//# sourceMappingURL=codebase-analysis.types.d.ts.map

package/dist/contracts/codebase-analysis.types.d.ts.map

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

package/dist/contracts/codebase-analysis.types.js

@@ -0,0 +1,19 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// Codebase Analysis Types — Incremental Analysis with Range Tracking
+//
+// Two-phase architecture:
+//   Phase 1 (Collect): LLM analyzes files in line-ranges, discovers
+//     dependencies, queues unresolved references. All results persisted to
+//     JSON immediately — crash-safe, resumable.
+//   Phase 2 (Prepare): Build documentation/graphs purely from collected data.
+//     No LLM needed — repeatable with different parameters.
+//
+// Key concepts:
+//   - AnalyzedRange: a contiguous block of code (class, function, imports)
+//   - RangeDependency: a link from one range to code in another file/range
+//   - FileAnalysisRecord: per-file state with content hash (incremental)
+//   - AnalysisQueue: prioritized work queue with dependency-driven entries
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=codebase-analysis.types.js.map

package/dist/contracts/codebase-analysis.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-analysis.types.js","sourceRoot":"","sources":["../../src/contracts/codebase-analysis.types.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,qEAAqE;AACrE,EAAE;AACF,0BAA0B;AAC1B,oEAAoE;AACpE,2EAA2E;AAC3E,gDAAgD;AAChD,8EAA8E;AAC9E,4DAA4D;AAC5D,EAAE;AACF,gBAAgB;AAChB,2EAA2E;AAC3E,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAC3E,gFAAgF"}

package/dist/contracts/context-document.types.d.ts

@@ -0,0 +1,82 @@
+import type { ModelRef } from "./llm.types";
+/** Raw document provided by the user for contextual injection. */
+export interface ContextDocument {
+    /** Human-readable document name (used as key in maps). */
+    name: string;
+    /** Full text content of the document. */
+    content: string;
+}
+/** Cached decomposition result for a single document (persisted across runs). */
+export interface ContextDocumentCache {
+    /** Matches the original document name. */
+    name: string;
+    /** Content checksum used to detect changes and invalidate the cache. */
+    checksum: string;
+    /** Concise summary generated by the decomposition model. */
+    summary: string;
+    /** Extracted keywords for keyword-based routing. */
+    keywords: string[];
+    /** Inferred category for filtering / routing priority. */
+    category?: "architecture" | "security" | "domain" | "conventions" | "data" | "other";
+    /** Unix-epoch timestamp when this decomposition was computed. */
+    decomposedAt: number;
+}
+/** Decomposed tool capability extracted from source code or documentation. */
+export interface ToolCapability {
+    /** Tool name (e.g. "readFile", "executeBash"). */
+    name: string;
+    /** Human-readable description of what the tool does. */
+    description: string;
+    /** Broad functional category for grouping / filtering. */
+    category: string;
+    /** Keywords used to match this tool against user queries. */
+    keywords: string[];
+}
+/** Full decomposition result containing both tool and document cache entries. */
+export interface DecompositionResult {
+    /** Tool capabilities discovered during decomposition. */
+    tools: ToolCapability[];
+    /** Cached document decompositions (one per original document). */
+    documents: ContextDocumentCache[];
+    /** Unix-epoch timestamp when this result was generated. */
+    generatedAt: number;
+}
+/** Controls where and how many context documents are injected into prompts. */
+export interface ContextInjectionConfig {
+    /** Where to inject context documents. Default: 'system-prompt'. */
+    target?: "system-prompt" | "subagent" | "all";
+    /** Maximum number of documents to inject per turn. No limit when omitted. */
+    maxDocuments?: number;
+    /** How subagents inherit context documents. Default: 'inherit-relevant'. */
+    subagentBehavior?: "inherit-all" | "inherit-relevant" | "none";
+}
+/** Configures how relevant context documents are selected for a turn. */
+export interface ContextRoutingConfig {
+    /** Routing strategy. Default: 'hybrid'. */
+    strategy?: "keyword" | "model" | "hybrid";
+    /** Confidence threshold for keyword matching (0-1). Default: 0.5. */
+    relevanceThreshold?: number;
+    /** Optional ModelRef for routing LLM. Falls back to parent when omitted. */
+    model?: ModelRef;
+}
+/** Controls document decomposition (caching, model selection, storage). */
+export interface ContextDecomposeConfig {
+    /** Whether to auto-decompose on init. Default: true when documents present. */
+    enabled?: boolean;
+    /** Optional ModelRef for decomposition LLM. Falls back to parent when omitted. */
+    model?: ModelRef;
+    /** Cache directory path. Default: '.thoughtflow/context-cache.json'. */
+    cacheDir?: string;
+}
+/** Top-level context configuration consumed by the ThoughtFlow engine. */
+export interface ContextConfig {
+    /** Map of document name to its full text content. */
+    documents?: Record<string, string>;
+    /** Decomposition settings (caching, model). */
+    decompose?: ContextDecomposeConfig;
+    /** Injection settings (where, how many, subagent behavior). */
+    injection?: ContextInjectionConfig;
+    /** Routing settings (strategy, thresholds, model). */
+    routing?: ContextRoutingConfig;
+}
+//# sourceMappingURL=context-document.types.d.ts.map

package/dist/contracts/context-document.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-document.types.d.ts","sourceRoot":"","sources":["../../src/contracts/context-document.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAY5C,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0DAA0D;IAC1D,QAAQ,CAAC,EACL,cAAc,GACd,UAAU,GACV,QAAQ,GACR,aAAa,GACb,MAAM,GACN,OAAO,CAAC;IACZ,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;CACtB;AAID,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,kEAAkE;IAClE,SAAS,EAAE,oBAAoB,EAAE,CAAC;IAClC,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,MAAM,CAAC,EAAE,eAAe,GAAG,UAAU,GAAG,KAAK,CAAC;IAC9C,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,aAAa,GAAG,kBAAkB,GAAG,MAAM,CAAC;CAChE;AAID,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC1C,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAID,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kFAAkF;IAClF,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,sDAAsD;IACtD,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC"}