modular-studio 1.0.5 → 1.1.0

package/dist-server/src/graph/extractors/markdown.js

@@ -0,0 +1,224 @@
+/**
+ * Markdown Relation Extractor
+ *
+ * Extracts: links_to, references, supersedes, continues, defined_in, depends_on
+ */
+// ── Link Patterns ─────────────────────────────────────────────────────────────
+const MD_LINK_RE = /\[([^\]]*)\]\(([^)]+)\)/g;
+const WIKI_LINK_RE = /\[\[([^\]]+)\]\]/g;
+// ── Supersedes / Continues Patterns ───────────────────────────────────────────
+const SUPERSEDES_RE = /(?:superseded|replaced|deprecated|updated)\s+(?:by|in)\s*:?\s*\[?([^\]\n]+)\]?/gi;
+const CONTINUES_RE = /(?:continued\s+from|part\s+\d+\s+of|follows\s+from)\s*:?\s*\[?([^\]\n]+)\]?/gi;
+// ── Dependency Patterns ───────────────────────────────────────────────────────
+const DEPENDS_RE = /(?:prerequisites?|depends?\s+on|requires?|see\s+also|before\s+reading)\s*:?\s*\[?([^\]\n]+)\]?/gi;
+// ── Definition Patterns ───────────────────────────────────────────────────────
+const BOLD_DEF_RE = /^\*\*([^*]+)\*\*\s*[:—–-]\s*(.+)$/gm;
+/**
+ * Resolve a relative markdown link to a file path.
+ */
+function resolveMarkdownLink(href, sourceDir) {
+    // Skip external links, anchors-only, mailto, etc.
+    if (/^(https?:|mailto:|#|data:)/.test(href))
+        return null;
+    if (href.startsWith('/'))
+        return null; // Absolute paths — skip
+    const [pathPart, anchor] = href.split('#');
+    if (!pathPart)
+        return anchor ? { path: '', anchor } : null;
+    const parts = sourceDir.split('/').filter(Boolean);
+    for (const segment of pathPart.split('/')) {
+        if (segment === '.')
+            continue;
+        if (segment === '..') {
+            parts.pop();
+            continue;
+        }
+        parts.push(segment);
+    }
+    return { path: parts.join('/'), anchor };
+}
+/**
+ * Find a FileNode by path (with fuzzy matching for extensions).
+ */
+function findNodeByPath(path, allNodes) {
+    // Exact match
+    let match = allNodes.find(n => n.path === path);
+    if (match)
+        return match;
+    // Try with .md extension
+    if (!path.endsWith('.md')) {
+        match = allNodes.find(n => n.path === path + '.md');
+        if (match)
+            return match;
+    }
+    // Try filename match (for wiki-links)
+    const fileName = path.split('/').pop()?.toLowerCase() ?? '';
+    return allNodes.find(n => {
+        const nodeName = n.path.split('/').pop()?.toLowerCase() ?? '';
+        return nodeName === fileName || nodeName === fileName + '.md';
+    });
+}
+/**
+ * Collect all defined terms across markdown files.
+ * Returns: Map<term (lowercase), { file, originalTerm }>
+ */
+export function collectDefinedTerms(mdNodes) {
+    const terms = new Map();
+    for (const node of mdNodes) {
+        if (node.language !== 'markdown')
+            continue;
+        // Headings become linkable terms
+        for (const sym of node.symbols) {
+            if (sym.kind === 'heading' && sym.name.length > 3) {
+                terms.set(sym.name.toLowerCase(), { file: node, term: sym.name });
+            }
+            if (sym.kind === 'definition') {
+                terms.set(sym.name.toLowerCase(), { file: node, term: sym.name });
+            }
+        }
+    }
+    return terms;
+}
+/**
+ * Extract all relations from a markdown file.
+ */
+export function extractMarkdownRelations(file, allNodes, content) {
+    if (file.language !== 'markdown')
+        return [];
+    const relations = [];
+    const sourceDir = file.path.split('/').slice(0, -1).join('/');
+    // ── Explicit links: [text](path.md) ─────────────────────────────────────
+    MD_LINK_RE.lastIndex = 0;
+    let match;
+    while ((match = MD_LINK_RE.exec(content)) !== null) {
+        const href = match[2];
+        const resolved = resolveMarkdownLink(href, sourceDir);
+        if (!resolved || !resolved.path)
+            continue;
+        const target = findNodeByPath(resolved.path, allNodes);
+        if (target && target.id !== file.id) {
+            relations.push({
+                sourceFile: file.id,
+                targetFile: target.id,
+                targetSymbol: resolved.anchor,
+                kind: 'links_to',
+                weight: 1.0,
+            });
+        }
+    }
+    // ── Wiki links: [[page-name]] ────────────────────────────────────────────
+    WIKI_LINK_RE.lastIndex = 0;
+    while ((match = WIKI_LINK_RE.exec(content)) !== null) {
+        const linkName = match[1].trim();
+        const target = findNodeByPath(linkName, allNodes);
+        if (target && target.id !== file.id) {
+            relations.push({
+                sourceFile: file.id,
+                targetFile: target.id,
+                kind: 'links_to',
+                weight: 1.0,
+            });
+        }
+    }
+    // ── Supersedes ───────────────────────────────────────────────────────────
+    SUPERSEDES_RE.lastIndex = 0;
+    while ((match = SUPERSEDES_RE.exec(content)) !== null) {
+        const ref = match[1].trim().replace(/\[|\]/g, '');
+        const target = findNodeByPath(ref, allNodes);
+        if (target && target.id !== file.id) {
+            relations.push({
+                sourceFile: file.id,
+                targetFile: target.id,
+                kind: 'supersedes',
+                weight: 0.9,
+            });
+        }
+    }
+    // ── Continues ────────────────────────────────────────────────────────────
+    CONTINUES_RE.lastIndex = 0;
+    while ((match = CONTINUES_RE.exec(content)) !== null) {
+        const ref = match[1].trim().replace(/\[|\]/g, '');
+        const target = findNodeByPath(ref, allNodes);
+        if (target && target.id !== file.id) {
+            relations.push({
+                sourceFile: file.id,
+                targetFile: target.id,
+                kind: 'continues',
+                weight: 0.8,
+            });
+        }
+    }
+    // ── Depends on / Prerequisites ───────────────────────────────────────────
+    DEPENDS_RE.lastIndex = 0;
+    while ((match = DEPENDS_RE.exec(content)) !== null) {
+        const ref = match[1].trim().replace(/\[|\]/g, '');
+        const target = findNodeByPath(ref, allNodes);
+        if (target && target.id !== file.id) {
+            relations.push({
+                sourceFile: file.id,
+                targetFile: target.id,
+                kind: 'depends_on',
+                weight: 0.8,
+            });
+        }
+    }
+    // ── Cross-document term references ───────────────────────────────────────
+    const definedTerms = collectDefinedTerms(allNodes.filter(n => n.id !== file.id));
+    for (const [termLower, { file: defFile, term }] of definedTerms) {
+        // Only match multi-word terms (> 2 words) or long single words (> 8 chars)
+        const wordCount = term.split(/\s+/).length;
+        if (wordCount < 2 && term.length <= 8)
+            continue;
+        // Word-boundary match, case-insensitive
+        const escaped = termLower.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const re = new RegExp(`\\b${escaped}\\b`, 'i');
+        if (re.test(content)) {
+            // Don't duplicate if we already have a links_to for this file
+            const alreadyLinked = relations.some(r => r.targetFile === defFile.id && (r.kind === 'links_to' || r.kind === 'references'));
+            if (!alreadyLinked) {
+                relations.push({
+                    sourceFile: file.id,
+                    targetFile: defFile.id,
+                    targetSymbol: term,
+                    kind: 'references',
+                    weight: 0.6,
+                });
+            }
+        }
+    }
+    return relations;
+}
+/**
+ * Extract markdown symbols (headings + defined terms) for FileNode.symbols.
+ */
+export function extractMarkdownSymbols(content) {
+    const symbols = [];
+    const lines = content.split('\n');
+    // Headings
+    for (let i = 0; i < lines.length; i++) {
+        const hMatch = /^(#{1,6})\s+(.+)$/.exec(lines[i]);
+        if (hMatch) {
+            symbols.push({
+                name: hMatch[2].trim(),
+                kind: 'heading',
+                lineStart: i + 1,
+                lineEnd: i + 1,
+                isExported: true,
+            });
+        }
+    }
+    // Bold definitions: **Term**: definition
+    BOLD_DEF_RE.lastIndex = 0;
+    let defMatch;
+    while ((defMatch = BOLD_DEF_RE.exec(content)) !== null) {
+        const lineNum = content.substring(0, defMatch.index).split('\n').length;
+        symbols.push({
+            name: defMatch[1].trim(),
+            kind: 'definition',
+            lineStart: lineNum,
+            lineEnd: lineNum,
+            isExported: true,
+        });
+    }
+    return symbols;
+}

package/dist-server/src/graph/extractors/yaml.d.ts

@@ -0,0 +1,15 @@
+/**
+ * YAML / JSON Relation Extractor
+ *
+ * Extracts: configured_by
+ * Scans config files for path-like string values that reference known source files.
+ */
+import type { FileNode, Relation } from '../types.js';
+/**
+ * Extract relations from a YAML or JSON config file.
+ *
+ * Creates 'configured_by' relations from the referenced code file TO the config.
+ * Weight: 0.8 for explicit path references, 0.6 for inferred ($schema).
+ */
+export declare function extractYamlRelations(node: FileNode, allNodes: FileNode[], content: string): Relation[];
+//# sourceMappingURL=yaml.d.ts.map

package/dist-server/src/graph/extractors/yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../../../../src/graph/extractors/yaml.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA0CtD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,QAAQ,EAAE,EACpB,OAAO,EAAE,MAAM,GACd,QAAQ,EAAE,CAyDZ"}

package/dist-server/src/graph/extractors/yaml.js

@@ -0,0 +1,104 @@
+/**
+ * YAML / JSON Relation Extractor
+ *
+ * Extracts: configured_by
+ * Scans config files for path-like string values that reference known source files.
+ */
+// ── Path Detection Patterns ───────────────────────────────────────────────────
+// Quoted string values ending in code/doc extensions
+const QUOTED_PATH_RE = /["']([^"'\n\r]+\.(?:ts|tsx|js|jsx|py|md))["']/g;
+// Unquoted YAML values: `key: ./src/foo.ts`
+const YAML_UNQUOTED_PATH_RE = /:\s+([^\s'"{\[,\n\r]+\.(?:ts|tsx|js|jsx|py|md))(?:\s*$|\s*#)/gm;
+// JSON Schema self-reference: "$schema": "./path/to/schema.json"
+const JSON_SCHEMA_KEY_RE = /['"]\$schema['"]\s*:\s*["']([^"']+\.json)["']/g;
+// ── Path Normalization ────────────────────────────────────────────────────────
+/**
+ * Normalize a raw path reference from config content to a repo-relative path.
+ * Resolves relative segments (./ and ../) against the config file's directory.
+ */
+function normalizePath(raw, configDir) {
+    let ref = raw.trim();
+    if (ref.startsWith('./'))
+        ref = ref.slice(2);
+    if (ref.startsWith('../')) {
+        const parts = configDir.split('/').filter(Boolean);
+        for (const seg of ref.split('/')) {
+            if (seg === '.')
+                continue;
+            if (seg === '..') {
+                parts.pop();
+                continue;
+            }
+            parts.push(seg);
+        }
+        return parts.join('/');
+    }
+    return ref;
+}
+function findNodeByNormalizedPath(normalized, allNodes) {
+    return allNodes.find(n => n.path === normalized || n.path.endsWith('/' + normalized));
+}
+// ── Main Extractor ────────────────────────────────────────────────────────────
+/**
+ * Extract relations from a YAML or JSON config file.
+ *
+ * Creates 'configured_by' relations from the referenced code file TO the config.
+ * Weight: 0.8 for explicit path references, 0.6 for inferred ($schema).
+ */
+export function extractYamlRelations(node, allNodes, content) {
+    if (node.language !== 'yaml' && node.language !== 'json')
+        return [];
+    const relations = [];
+    const configDir = node.path.split('/').slice(0, -1).join('/');
+    const seen = new Set();
+    // ── Explicit path references ──────────────────────────────────────────────
+    const pathPatterns = [QUOTED_PATH_RE, YAML_UNQUOTED_PATH_RE];
+    for (const re of pathPatterns) {
+        re.lastIndex = 0;
+        let match;
+        while ((match = re.exec(content)) !== null) {
+            const raw = match[1];
+            if (!raw)
+                continue;
+            const normalized = normalizePath(raw, configDir);
+            const target = findNodeByNormalizedPath(normalized, allNodes);
+            if (!target || target.id === node.id)
+                continue;
+            // Relation: referenced code file is configured_by this config file
+            const key = `${target.id}→${node.id}:configured_by`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            relations.push({
+                sourceFile: target.id,
+                targetFile: node.id,
+                kind: 'configured_by',
+                weight: 0.8,
+            });
+        }
+    }
+    // ── JSON Schema cross-references ($schema key) ────────────────────────────
+    JSON_SCHEMA_KEY_RE.lastIndex = 0;
+    let schemaMatch;
+    while ((schemaMatch = JSON_SCHEMA_KEY_RE.exec(content)) !== null) {
+        const raw = schemaMatch[1];
+        if (!raw)
+            continue;
+        const normalized = normalizePath(raw, configDir);
+        const target = findNodeByNormalizedPath(normalized, allNodes);
+        if (!target || target.id === node.id)
+            continue;
+        // Relation: this config is configured_by (validated against) the schema
+        const key = `${node.id}→${target.id}:configured_by`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        relations.push({
+            sourceFile: node.id,
+            targetFile: target.id,
+            kind: 'configured_by',
+            weight: 0.6,
+        });
+    }
+    return relations;
+}

package/dist-server/src/graph/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Context Graph — Public API
+ *
+ * Unified interface: scan → query → pack.
+ */
+export { GraphDB } from './db.js';
+export { fullScan, updateFiles, buildFileNode, shouldIndex, fileId, hashContent } from './scanner.js';
+export { resolveEntryPoints } from './resolver.js';
+export { traverseGraph, traverseForTask } from './traverser.js';
+export { packContext } from './packer.js';
+export { extractCodeRelations } from './extractors/code.js';
+export { extractMarkdownRelations, extractMarkdownSymbols, collectDefinedTerms } from './extractors/markdown.js';
+export { extractYamlRelations } from './extractors/yaml.js';
+export { extractCrossTypeRelations } from './extractors/cross-type.js';
+export { detectTaskType, TRAVERSAL_PRESETS } from './types.js';
+export type { FileNode, FileLanguage, SymbolDef, SymbolKind, Relation, RelationKind, ContextGraph, TraversalConfig, TraversalResult, TraversalFile, EntryPoint, PackedContext, PackedItem, UpdateResult, ScanResult, TaskType, } from './types.js';
+import { GraphDB } from './db.js';
+import type { PackedContext, ScanResult, UpdateResult, TaskType } from './types.js';
+/**
+ * High-level: scan files → build graph → query → get packed context.
+ */
+export declare class ContextGraphEngine {
+    private db;
+    private rootPath;
+    /**
+     * Full scan from a list of files.
+     */
+    scan(rootPath: string, files: Array<{
+        path: string;
+        content: string;
+        mtime?: number;
+    }>): ScanResult;
+    /**
+     * Incremental update for changed files.
+     */
+    update(changedFiles: Array<{
+        path: string;
+        content: string;
+        mtime?: number;
+    }>): UpdateResult;
+    /**
+     * Query: natural language → packed context.
+     */
+    query(query: string, tokenBudget?: number, taskType?: TaskType): PackedContext;
+    /**
+     * Get graph stats.
+     */
+    getStats(): {
+        nodes: number;
+        symbols: number;
+        relations: number;
+    };
+    /**
+     * Get the full graph for visualization.
+     */
+    getGraph(): import("./types.js").ContextGraph;
+    /**
+     * Get DB instance for direct access.
+     */
+    getDB(): GraphDB;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist-server/src/graph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/graph/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACtG,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACjH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/D,YAAY,EACV,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAC7C,QAAQ,EAAE,YAAY,EACtB,YAAY,EACZ,eAAe,EAAE,eAAe,EAAE,aAAa,EAC/C,UAAU,EACV,aAAa,EAAE,UAAU,EACzB,YAAY,EAAE,UAAU,EACxB,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAKlC,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpF;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,QAAQ,CAAM;IAEtB;;OAEG;IACH,IAAI,CACF,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAC9D,UAAU;IAKb;;OAEG;IACH,MAAM,CACJ,YAAY,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACrE,YAAY;IAIf;;OAEG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,WAAW,GAAE,MAAe,EAC5B,QAAQ,CAAC,EAAE,QAAQ,GAClB,aAAa;IAOhB;;OAEG;IACH,QAAQ;;;;;IAIR;;OAEG;IACH,QAAQ;IAIR;;OAEG;IACH,KAAK;CAGN"}

package/dist-server/src/graph/index.js

@@ -0,0 +1,67 @@
+/**
+ * Context Graph — Public API
+ *
+ * Unified interface: scan → query → pack.
+ */
+export { GraphDB } from './db.js';
+export { fullScan, updateFiles, buildFileNode, shouldIndex, fileId, hashContent } from './scanner.js';
+export { resolveEntryPoints } from './resolver.js';
+export { traverseGraph, traverseForTask } from './traverser.js';
+export { packContext } from './packer.js';
+export { extractCodeRelations } from './extractors/code.js';
+export { extractMarkdownRelations, extractMarkdownSymbols, collectDefinedTerms } from './extractors/markdown.js';
+export { extractYamlRelations } from './extractors/yaml.js';
+export { extractCrossTypeRelations } from './extractors/cross-type.js';
+export { detectTaskType, TRAVERSAL_PRESETS } from './types.js';
+import { GraphDB } from './db.js';
+import { fullScan, updateFiles } from './scanner.js';
+import { resolveEntryPoints } from './resolver.js';
+import { traverseForTask } from './traverser.js';
+import { packContext } from './packer.js';
+/**
+ * High-level: scan files → build graph → query → get packed context.
+ */
+export class ContextGraphEngine {
+    db = new GraphDB();
+    rootPath = '';
+    /**
+     * Full scan from a list of files.
+     */
+    scan(rootPath, files) {
+        this.rootPath = rootPath;
+        return fullScan(files, this.db);
+    }
+    /**
+     * Incremental update for changed files.
+     */
+    update(changedFiles) {
+        return updateFiles(changedFiles, this.db);
+    }
+    /**
+     * Query: natural language → packed context.
+     */
+    query(query, tokenBudget = 100000, taskType) {
+        const graph = this.db.toContextGraph(this.rootPath);
+        const entryPoints = resolveEntryPoints(query, graph);
+        const traversal = traverseForTask(query, entryPoints, graph, taskType);
+        return packContext(traversal, tokenBudget);
+    }
+    /**
+     * Get graph stats.
+     */
+    getStats() {
+        return this.db.getStats();
+    }
+    /**
+     * Get the full graph for visualization.
+     */
+    getGraph() {
+        return this.db.toContextGraph(this.rootPath);
+    }
+    /**
+     * Get DB instance for direct access.
+     */
+    getDB() {
+        return this.db;
+    }
+}

package/dist-server/src/graph/packer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Budget Packer — Relevance-weighted depth allocation
+ *
+ * Given traversal results and a token budget, decide how much of each file
+ * to include using existing depthFilter depth levels:
+ *   0 = Full, 1 = Detail, 2 = Summary, 3 = Headlines, 4 = Mention
+ */
+import type { TraversalResult, PackedContext } from './types.js';
+/**
+ * Pack traversal results into a context budget.
+ *
+ * Strategy:
+ * 1. Assign initial depth based on relevance
+ * 2. If budget exceeded, demote lowest-relevance files to higher depth
+ * 3. If budget still exceeded, drop lowest-relevance files
+ * 4. If budget has room, promote highest-relevance files to lower depth
+ */
+export declare function packContext(traversalResult: TraversalResult, tokenBudget: number): PackedContext;
+//# sourceMappingURL=packer.d.ts.map

package/dist-server/src/graph/packer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packer.d.ts","sourceRoot":"","sources":["../../../src/graph/packer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAwB,MAAM,YAAY,CAAC;AAmEvF;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,eAAe,EAAE,eAAe,EAChC,WAAW,EAAE,MAAM,GAClB,aAAa,CAgFf"}

package/dist-server/src/graph/packer.js

@@ -0,0 +1,134 @@
+/**
+ * Budget Packer — Relevance-weighted depth allocation
+ *
+ * Given traversal results and a token budget, decide how much of each file
+ * to include using existing depthFilter depth levels:
+ *   0 = Full, 1 = Detail, 2 = Summary, 3 = Headlines, 4 = Mention
+ */
+// Approximate token costs per depth level (as fraction of full)
+const DEPTH_COST_RATIOS = {
+    0: 1.0, // Full
+    1: 0.75, // Detail: signatures + docstrings
+    2: 0.50, // Summary: signatures only
+    3: 0.25, // Headlines: section names
+    4: 0.10, // Mention: file purpose only
+};
+/**
+ * Estimate token cost at a given depth level.
+ */
+function estimateAtDepth(fileTokens, depth) {
+    const ratio = DEPTH_COST_RATIOS[depth] ?? 0.1;
+    return Math.max(10, Math.ceil(fileTokens * ratio));
+}
+/**
+ * Generate content stub at a given depth level.
+ * In production, this would call depthFilter.ts — here we generate a summary.
+ */
+function contentAtDepth(file, depth) {
+    const symbols = file.symbols;
+    switch (depth) {
+        case 0: // Full — would return full file content
+            return `[Full content of ${file.path}]\n` +
+                symbols.map(s => `${s.kind} ${s.name}${s.signature ? s.signature : ''}`).join('\n');
+        case 1: // Detail — signatures + docstrings
+            return `// ${file.path} (detail)\n` +
+                symbols.map(s => `${s.isExported ? 'export ' : ''}${s.kind} ${s.name}${s.signature ?? ''}${s.docstring ? ` // ${s.docstring}` : ''}`).join('\n');
+        case 2: // Summary — signatures only
+            return `// ${file.path} (summary)\n` +
+                symbols.filter(s => s.isExported).map(s => `${s.kind} ${s.name}${s.signature ?? ''}`).join('\n');
+        case 3: // Headlines — section/symbol names
+            return `// ${file.path}: ` +
+                symbols.filter(s => s.isExported).map(s => s.name).join(', ');
+        case 4: // Mention — file purpose
+            return `// ${file.path} (${file.language}, ${file.tokens} tokens)`;
+        default:
+            return `// ${file.path}`;
+    }
+}
+/**
+ * Determine depth level based on relevance score.
+ */
+function relevanceToDepth(relevance) {
+    if (relevance >= 0.8)
+        return 0; // Full
+    if (relevance >= 0.6)
+        return 1; // Detail
+    if (relevance >= 0.4)
+        return 2; // Summary
+    if (relevance >= 0.2)
+        return 3; // Headlines
+    return 4; // Mention
+}
+/**
+ * Pack traversal results into a context budget.
+ *
+ * Strategy:
+ * 1. Assign initial depth based on relevance
+ * 2. If budget exceeded, demote lowest-relevance files to higher depth
+ * 3. If budget still exceeded, drop lowest-relevance files
+ * 4. If budget has room, promote highest-relevance files to lower depth
+ */
+export function packContext(traversalResult, tokenBudget) {
+    const { files } = traversalResult;
+    if (files.length === 0) {
+        return { items: [], totalTokens: 0, budgetUtilization: 0 };
+    }
+    // Sort by relevance descending
+    const sorted = [...files].sort((a, b) => b.relevance - a.relevance);
+    const items = sorted.map(f => {
+        const depth = relevanceToDepth(f.relevance);
+        return {
+            file: f.node,
+            relevance: f.relevance,
+            depth,
+            tokens: estimateAtDepth(f.node.tokens, depth),
+        };
+    });
+    // Phase 2: Fit within budget — demote from bottom up
+    let totalTokens = items.reduce((sum, it) => sum + it.tokens, 0);
+    if (totalTokens > tokenBudget) {
+        // Demote least relevant files first
+        for (let i = items.length - 1; i >= 0 && totalTokens > tokenBudget; i--) {
+            const item = items[i];
+            while (item.depth < 4 && totalTokens > tokenBudget) {
+                const oldTokens = item.tokens;
+                item.depth++;
+                item.tokens = estimateAtDepth(item.file.tokens, item.depth);
+                totalTokens -= (oldTokens - item.tokens);
+            }
+        }
+        // If still over budget, drop from bottom
+        while (items.length > 0 && totalTokens > tokenBudget) {
+            const removed = items.pop();
+            totalTokens -= removed.tokens;
+        }
+    }
+    // Phase 3: If budget has room, promote top files
+    if (totalTokens < tokenBudget * 0.8) {
+        for (let i = 0; i < items.length && totalTokens < tokenBudget * 0.9; i++) {
+            const item = items[i];
+            if (item.depth > 0) {
+                const newTokens = estimateAtDepth(item.file.tokens, item.depth - 1);
+                const delta = newTokens - item.tokens;
+                if (totalTokens + delta <= tokenBudget) {
+                    item.depth--;
+                    item.tokens = newTokens;
+                    totalTokens += delta;
+                }
+            }
+        }
+    }
+    // Build final output
+    const packed = items.map(it => ({
+        file: it.file,
+        content: contentAtDepth(it.file, it.depth),
+        depth: it.depth,
+        tokens: it.tokens,
+        relevance: it.relevance,
+    }));
+    return {
+        items: packed,
+        totalTokens,
+        budgetUtilization: totalTokens / tokenBudget,
+    };
+}

package/dist-server/src/graph/resolver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Entry Point Resolver
+ *
+ * From a natural language query, find entry points into the context graph.
+ * Three strategies: symbol match, filename match, semantic match (fallback).
+ */
+import type { ContextGraph, EntryPoint } from './types.js';
+/**
+ * Resolve entry points from a query against the graph.
+ */
+export declare function resolveEntryPoints(query: string, graph: ContextGraph): EntryPoint[];
+//# sourceMappingURL=resolver.d.ts.map

package/dist-server/src/graph/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../../src/graph/resolver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,YAAY,GAClB,UAAU,EAAE,CA4Ed"}