contextdiet-cli 0.1.0

package/dist/core/graph/index.js

@@ -0,0 +1,195 @@
+/**
+ * DependencyGraphResolver (Task 2.0).
+ *
+ * Builds a {@link DependencyGraph} for a codebase by:
+ *   1. enumerating source files under the root (skipping `node_modules`/dotdirs),
+ *   2. parsing each with the {@link Parser} to get symbols + dependency specifiers,
+ *   3. resolving each specifier to an absolute file path (or marking it external).
+ *
+ * Cycle safety: the graph is built by filesystem enumeration + per-file edge
+ * resolution — NOT by recursively following imports. Import cycles therefore
+ * cannot cause infinite loops or stack overflow at build time; they simply appear
+ * as cycles in the adjacency data. Consumers that walk the graph must use a
+ * visited set — see {@link collectReachable}.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { AstGrepperParser } from '../parser/index.js';
+import { ParseError } from '../parser/types.js';
+/** Extensions we treat as parseable source. */
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+/** JS-family extensions an ESM specifier may use to point at a TS-family file. */
+const JS_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs']);
+const TS_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts'];
+/** Directory names never descended into. */
+const IGNORED_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage']);
+export class DependencyGraphResolver {
+    parser;
+    constructor(parser = new AstGrepperParser()) {
+        this.parser = parser;
+    }
+    async buildGraph(rootDir) {
+        const root = path.resolve(rootDir);
+        const files = await collectSourceFiles(root);
+        files.sort();
+        const nodes = new Map();
+        for (const filePath of files) {
+            nodes.set(filePath, await this.buildNode(root, filePath));
+        }
+        // Derive the traversable adjacency list: first-party edges only, deduped,
+        // and only pointing at files that are actually nodes in this graph.
+        const adjacency = new Map();
+        for (const [filePath, node] of nodes) {
+            const seen = new Set();
+            const neighbours = [];
+            for (const edge of node.dependencies) {
+                const target = edge.resolvedPath;
+                if (target !== null && nodes.has(target) && !seen.has(target)) {
+                    seen.add(target);
+                    neighbours.push(target);
+                }
+            }
+            adjacency.set(filePath, neighbours);
+        }
+        return { rootDir: root, nodes, adjacency };
+    }
+    async buildNode(root, filePath) {
+        const source = await fs.readFile(filePath, 'utf8');
+        let symbols = [];
+        let dependencies = [];
+        try {
+            symbols = await this.parser.extractSymbols(source, filePath);
+            const refs = await this.parser.extractDependencies(source, filePath);
+            dependencies = await Promise.all(refs.map(async (ref) => {
+                const resolvedPath = await resolveSpecifier(ref.source, path.dirname(filePath));
+                return {
+                    kind: ref.kind,
+                    specifier: ref.source,
+                    resolvedPath,
+                    external: resolvedPath === null,
+                };
+            }));
+        }
+        catch (error) {
+            // A single unparseable file must not sink the whole graph: record it as a
+            // node with no symbols/edges so the rest of the codebase still maps.
+            if (!(error instanceof ParseError))
+                throw error;
+        }
+        return {
+            filePath,
+            relativePath: path.relative(root, filePath),
+            symbols,
+            dependencies,
+        };
+    }
+}
+/**
+ * Iteratively collect every node reachable from `startPath` (inclusive), up to
+ * `maxHops` edges away. Uses a visited set + explicit queue, so cycles terminate
+ * and deep graphs never overflow the call stack.
+ */
+export function collectReachable(graph, startPath, maxHops = Number.POSITIVE_INFINITY) {
+    const start = path.resolve(startPath);
+    const visited = new Set();
+    if (!graph.nodes.has(start))
+        return visited;
+    visited.add(start);
+    let frontier = [start];
+    let depth = 0;
+    while (frontier.length > 0 && depth < maxHops) {
+        const next = [];
+        for (const current of frontier) {
+            for (const neighbour of graph.adjacency.get(current) ?? []) {
+                if (!visited.has(neighbour)) {
+                    visited.add(neighbour);
+                    next.push(neighbour);
+                }
+            }
+        }
+        frontier = next;
+        depth += 1;
+    }
+    return visited;
+}
+// --- module-private helpers -----------------------------------------------
+/** Depth-limited-free directory walk (over the acyclic dir tree) for source files. */
+async function collectSourceFiles(root) {
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // unreadable dir (e.g. permissions) — skip, don't crash the build
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            // `isDirectory()` is false for symlinks, so symlinked dirs are skipped —
+            // another reason the walk can't cycle.
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                    continue;
+                stack.push(full);
+            }
+            else if (entry.isFile() && SOURCE_EXTENSIONS.includes(path.extname(entry.name))) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Resolve a module specifier to an absolute file path, or `null` if it is
+ * external (bare package, `node:` builtin) or cannot be found on disk.
+ *
+ * Only relative specifiers (`.`/`..`) are ever resolved — everything else is,
+ * by definition, beyond the `node_modules` boundary.
+ */
+async function resolveSpecifier(specifier, importerDir) {
+    if (!specifier.startsWith('.'))
+        return null; // bare / node: / absolute-package → external
+    const base = path.resolve(importerDir, specifier);
+    for (const candidate of candidatePaths(base)) {
+        if (await isFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** Ordered candidate paths for a resolved base (extension + index resolution). */
+function candidatePaths(base) {
+    const candidates = [];
+    const ext = path.extname(base);
+    if (ext !== '') {
+        candidates.push(base); // e.g. './x.ts' written explicitly
+        if (JS_EXTENSIONS.has(ext)) {
+            // ESM-style './x.js' specifier that actually targets a TS source file.
+            const stem = base.slice(0, -ext.length);
+            for (const tsExt of TS_EXTENSIONS)
+                candidates.push(stem + tsExt);
+        }
+    }
+    else {
+        for (const sourceExt of SOURCE_EXTENSIONS)
+            candidates.push(base + sourceExt);
+    }
+    // Directory import: `./dir` → `./dir/index.*`
+    for (const sourceExt of SOURCE_EXTENSIONS) {
+        candidates.push(path.join(base, `index${sourceExt}`));
+    }
+    return candidates;
+}
+async function isFile(candidate) {
+    try {
+        return (await fs.stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/core/graph/index.js.map

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

package/dist/core/graph/selector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * GraphSelector (Task 3.0).
+ *
+ * Bridges the ranker's seeds to a concrete "keep set". Given `SeedNode[]` (the
+ * symbols most relevant to a focus query) and the {@link DependencyGraph}, it
+ * walks dependency edges N hops out from each seed's file and returns exactly
+ * which symbols in which files are allowed to survive.
+ *
+ * Granularity note (see ADR-011): the dependency graph is file-level, so
+ * selection keeps *whole reachable files* — every top-level symbol of a file the
+ * seeds transitively depend on. The result is nonetheless expressed at symbol
+ * granularity (`Map<filePath, Set<symbolName>>`) so the pruner and a future
+ * symbol-level call graph need no interface change.
+ */
+import type { DependencyGraph } from './types.js';
+import type { SeedNode } from '../ranker/types.js';
+/** file abs path → the set of top-level symbol names permitted to survive. */
+export type Selection = ReadonlyMap<string, ReadonlySet<string>>;
+export interface SelectionOptions {
+    /** Dependency-graph traversal depth from each seed file. Default `2`. */
+    readonly hops?: number;
+}
+export interface Selector {
+    select(seeds: readonly SeedNode[], graph: DependencyGraph, options?: SelectionOptions): Selection;
+}
+export declare class GraphSelector implements Selector {
+    select(seeds: readonly SeedNode[], graph: DependencyGraph, options?: SelectionOptions): Selection;
+}
+//# sourceMappingURL=selector.d.ts.map

package/dist/core/graph/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../../src/core/graph/selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;AAEjE,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACnG;AAID,qBAAa,aAAc,YAAW,QAAQ;IAC5C,MAAM,CACJ,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CA6BX;CACF"}

package/dist/core/graph/selector.js

@@ -0,0 +1,49 @@
+/**
+ * GraphSelector (Task 3.0).
+ *
+ * Bridges the ranker's seeds to a concrete "keep set". Given `SeedNode[]` (the
+ * symbols most relevant to a focus query) and the {@link DependencyGraph}, it
+ * walks dependency edges N hops out from each seed's file and returns exactly
+ * which symbols in which files are allowed to survive.
+ *
+ * Granularity note (see ADR-011): the dependency graph is file-level, so
+ * selection keeps *whole reachable files* — every top-level symbol of a file the
+ * seeds transitively depend on. The result is nonetheless expressed at symbol
+ * granularity (`Map<filePath, Set<symbolName>>`) so the pruner and a future
+ * symbol-level call graph need no interface change.
+ */
+import * as path from 'node:path';
+import { collectReachable } from './index.js';
+const DEFAULT_HOPS = 2;
+export class GraphSelector {
+    select(seeds, graph, options = {}) {
+        const hops = options.hops ?? DEFAULT_HOPS;
+        const keep = new Map();
+        if (seeds.length === 0)
+            return keep;
+        // 1. Files that directly contain a seed symbol (that are actually in the graph).
+        const seedFiles = new Set();
+        for (const seed of seeds) {
+            const file = path.resolve(seed.symbol.filePath);
+            if (graph.nodes.has(file))
+                seedFiles.add(file);
+        }
+        // 2. Expand each seed file N hops along dependency edges. `collectReachable`
+        //    is cycle-safe, so import cycles among reachable files terminate cleanly.
+        const keepFiles = new Set();
+        for (const file of seedFiles) {
+            for (const reached of collectReachable(graph, file, hops)) {
+                keepFiles.add(reached);
+            }
+        }
+        // 3. Whole-file granularity: every top-level symbol of each kept file survives.
+        for (const file of keepFiles) {
+            const node = graph.nodes.get(file);
+            if (node === undefined)
+                continue;
+            keep.set(file, new Set(node.symbols.map((s) => s.name)));
+        }
+        return keep;
+    }
+}
+//# sourceMappingURL=selector.js.map

package/dist/core/graph/selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../../../src/core/graph/selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAgB9C,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB,MAAM,OAAO,aAAa;IACxB,MAAM,CACJ,KAA0B,EAC1B,KAAsB,EACtB,OAAO,GAAqB,EAAE;QAE9B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,YAAY,CAAC;QAC1C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAC;QAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpC,iFAAiF;QACjF,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;QACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAChD,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjD,CAAC;QAED,6EAA6E;QAC7E,8EAA8E;QAC9E,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;QACpC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,KAAK,MAAM,OAAO,IAAI,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC1D,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,gFAAgF;QAChF,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,IAAI,KAAK,SAAS;gBAAE,SAAS;YACjC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3D,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/core/graph/symbol-selector.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ReferenceClosureSelector — symbol-level selection (Task 7 / ADR-016).
+ *
+ * Upgrades whole-file selection (ADR-011) to precise, per-symbol selection. It
+ * walks the *reference closure* of the seed symbols and keeps only what is
+ * actually reachable, so the pruner (already symbol-level) can drop internal
+ * helpers no kept symbol touches.
+ *
+ * Correctness rule — kept code must never dangle on a same-file symbol:
+ *   - intra-file references are followed UNBOUNDED (a kept symbol's same-file
+ *     helpers are always kept), guaranteeing each emitted file is self-consistent;
+ *   - cross-file references are followed only within the `--hops` file horizon
+ *     (identical boundary to the file-level selector), so context stays bounded;
+ *   - namespace/default imports keep the whole target module (we cannot tell
+ *     which members are used through a `*`/default binding).
+ *
+ * Composes {@link GraphSelector} to compute the horizon, then refines within it.
+ */
+import type { DependencyGraph } from './types.js';
+import type { Selection, SelectionOptions } from './selector.js';
+import type { SeedNode } from '../ranker/types.js';
+import type { Parser } from '../parser/types.js';
+export interface SymbolSelector {
+    select(seeds: readonly SeedNode[], graph: DependencyGraph, sources: ReadonlyMap<string, string>, options?: SelectionOptions): Promise<Selection>;
+}
+export declare class ReferenceClosureSelector implements SymbolSelector {
+    private readonly parser;
+    constructor(parser?: Parser);
+    select(seeds: readonly SeedNode[], graph: DependencyGraph, sources: ReadonlyMap<string, string>, options?: SelectionOptions): Promise<Selection>;
+}
+//# sourceMappingURL=symbol-selector.d.ts.map

package/dist/core/graph/symbol-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-selector.d.ts","sourceRoot":"","sources":["../../../src/core/graph/symbol-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAc,MAAM,EAAc,MAAM,oBAAoB,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,MAAM,CACJ,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,SAAS,CAAC,CAAC;CACvB;AAED,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YAAY,MAAM,GAAE,MAA+B,EAElD;IAEK,MAAM,CACV,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,SAAS,CAAC,CAsGpB;CACF"}

package/dist/core/graph/symbol-selector.js.map

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

package/dist/core/graph/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Dependency-graph contracts for ContextDiet (Task 2.0).
+ *
+ * The graph is the map the Selector (Task 3.0) walks to decide which code to keep
+ * for a given `--focus`. It is a pure data structure: nodes (files) plus an
+ * adjacency list of first-party edges. Cycles are represented directly — the graph
+ * never resolves them away, so consumers must traverse with a visited set
+ * (see `collectReachable`).
+ */
+import type { DependencyRefKind, SymbolNode } from '../parser/types.js';
+/**
+ * A single resolved outward edge from a file to a module it depends on.
+ *
+ * `resolvedPath` is the absolute path of the target file when the specifier
+ * points at first-party source; it is `null` for anything beyond the project
+ * boundary (bare package specifiers, `node:` builtins, unresolvable paths), in
+ * which case `external` is `true`. External edges are recorded but never
+ * traversed — the `node_modules` boundary is strict.
+ */
+export interface DependencyEdge {
+    readonly kind: DependencyRefKind;
+    /** The specifier exactly as written in source (e.g. `./b`, `node:fs`, `express`). */
+    readonly specifier: string;
+    /** Absolute path of the target file, or `null` if external/unresolvable. */
+    readonly resolvedPath: string | null;
+    /** True when the edge crosses the project boundary (not traversed). */
+    readonly external: boolean;
+}
+/** One file in the graph: its identity, its symbols, and its outward edges. */
+export interface GraphNode {
+    /** Absolute path of this file (also its key in {@link DependencyGraph.nodes}). */
+    readonly filePath: string;
+    /** Path relative to the graph root — stable and display-friendly. */
+    readonly relativePath: string;
+    /** Top-level declarations in this file (from the parser). */
+    readonly symbols: readonly SymbolNode[];
+    /** Every outward dependency (imports + re-exports), resolved to disk. */
+    readonly dependencies: readonly DependencyEdge[];
+}
+/**
+ * The whole codebase as a directed graph.
+ *
+ * `adjacency` is the derived, deduped view used for traversal: it contains only
+ * first-party edges (external dependencies excluded). It may contain cycles.
+ */
+export interface DependencyGraph {
+    /** Absolute root the graph was built from. */
+    readonly rootDir: string;
+    /** All file nodes, keyed by absolute path. */
+    readonly nodes: ReadonlyMap<string, GraphNode>;
+    /** file abs path → abs paths of the first-party files it depends on (deduped). */
+    readonly adjacency: ReadonlyMap<string, readonly string[]>;
+}
+/** Builds a {@link DependencyGraph} for a codebase rooted at `rootDir`. */
+export interface GraphResolver {
+    buildGraph(rootDir: string): Promise<DependencyGraph>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/graph/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAExE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,SAAS,cAAc,EAAE,CAAC;CAClD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC/C,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CAC5D;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACvD"}

package/dist/core/graph/types.js

@@ -0,0 +1,11 @@
+/**
+ * Dependency-graph contracts for ContextDiet (Task 2.0).
+ *
+ * The graph is the map the Selector (Task 3.0) walks to decide which code to keep
+ * for a given `--focus`. It is a pure data structure: nodes (files) plus an
+ * adjacency list of first-party edges. Cycles are represented directly — the graph
+ * never resolves them away, so consumers must traverse with a visited set
+ * (see `collectReachable`).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/graph/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/core/metrics/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Metrics — Task 5.0 (efficiency tracking).
+ *
+ * Proves the headline claim: >80% token reduction. We compare the baseline
+ * codebase against the pruned bundle on two axes:
+ *   - raw bytes (UTF-8), an exact, dependency-free ground truth, and
+ *   - estimated tokens, since LLM cost is billed per token, not per byte.
+ *
+ * Token estimation is a local heuristic — zero network, zero heavy deps. We do
+ * NOT bundle a full BPE vocabulary; instead we approximate how tokenizers split
+ * text (words, sub-words, punctuation, whitespace runs) which lands within a few
+ * percent of real tiktoken counts on source code, and is fully deterministic.
+ */
+/** Result of comparing a baseline against a pruned/compressed variant. */
+export interface ReductionMetrics {
+    /** UTF-8 byte length of the original, unpruned input. */
+    readonly rawBytes: number;
+    /** UTF-8 byte length of the pruned bundle. */
+    readonly compressedBytes: number;
+    /** Estimated token count of the original input. */
+    readonly rawTokens: number;
+    /** Estimated token count of the pruned bundle. */
+    readonly compressedTokens: number;
+    /**
+     * Percentage reduction in estimated tokens, `[0, 100]`, rounded to two
+     * decimals. `(rawTokens - compressedTokens) / rawTokens * 100`.
+     */
+    readonly tokenReductionPercentage: number;
+    /** Percentage reduction in raw bytes, `[0, 100]`, rounded to two decimals. */
+    readonly byteReductionPercentage: number;
+}
+/** UTF-8 byte length of a string, without allocating a Buffer per call path. */
+export declare function byteLength(text: string): number;
+/**
+ * Estimate the number of tokens a BPE tokenizer would produce for `text`.
+ *
+ * Strategy: split into atomic pieces the way real tokenizers tend to — runs of
+ * word characters, individual punctuation/symbols, and whitespace runs — then
+ * further split long word-runs into ~4-char sub-word chunks (BPE rarely emits a
+ * token longer than that for code identifiers like `authMiddleware`). We blend
+ * this with the classic chars/4 heuristic and take the max, so we never wildly
+ * under-count dense text.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Compute the byte/token reduction between an original codebase string and its
+ * pruned bundle. `original` is the concatenation of the baseline files;
+ * `pruned` is the bundler output (or pruned concatenation).
+ */
+export declare function computeReduction(original: string, pruned: string): ReductionMetrics;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/metrics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/metrics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,8EAA8E;IAC9E,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;CAC1C;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAWD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAsBnD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAcnF"}

package/dist/core/metrics/index.js

@@ -0,0 +1,91 @@
+/**
+ * Metrics — Task 5.0 (efficiency tracking).
+ *
+ * Proves the headline claim: >80% token reduction. We compare the baseline
+ * codebase against the pruned bundle on two axes:
+ *   - raw bytes (UTF-8), an exact, dependency-free ground truth, and
+ *   - estimated tokens, since LLM cost is billed per token, not per byte.
+ *
+ * Token estimation is a local heuristic — zero network, zero heavy deps. We do
+ * NOT bundle a full BPE vocabulary; instead we approximate how tokenizers split
+ * text (words, sub-words, punctuation, whitespace runs) which lands within a few
+ * percent of real tiktoken counts on source code, and is fully deterministic.
+ */
+/** UTF-8 byte length of a string, without allocating a Buffer per call path. */
+export function byteLength(text) {
+    // TextEncoder is a Web/Node global and counts real UTF-8 bytes (multi-byte
+    // aware), unlike `string.length` which counts UTF-16 code units.
+    return TEXT_ENCODER.encode(text).length;
+}
+const TEXT_ENCODER = new TextEncoder();
+/**
+ * Average characters-per-token observed for source code with common BPE
+ * tokenizers (cl100k/o200k). Used only as a sanity fallback; the primary
+ * estimate is structural (see {@link estimateTokens}).
+ */
+const CHARS_PER_TOKEN_FALLBACK = 4;
+/**
+ * Estimate the number of tokens a BPE tokenizer would produce for `text`.
+ *
+ * Strategy: split into atomic pieces the way real tokenizers tend to — runs of
+ * word characters, individual punctuation/symbols, and whitespace runs — then
+ * further split long word-runs into ~4-char sub-word chunks (BPE rarely emits a
+ * token longer than that for code identifiers like `authMiddleware`). We blend
+ * this with the classic chars/4 heuristic and take the max, so we never wildly
+ * under-count dense text.
+ */
+export function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    let structural = 0;
+    const pieces = text.match(/[A-Za-z0-9]+|\s+|[^A-Za-z0-9\s]/g) ?? [];
+    for (const piece of pieces) {
+        if (/^\s+$/.test(piece)) {
+            // Whitespace: newlines and indentation usually cost ~1 token per run,
+            // but very long runs get chunked.
+            structural += Math.max(1, Math.ceil(piece.length / 8));
+        }
+        else if (/^[A-Za-z0-9]+$/.test(piece)) {
+            // Word/identifier run: ~4 chars per sub-word token, min 1.
+            structural += Math.max(1, Math.ceil(piece.length / 4));
+        }
+        else {
+            // A single punctuation/symbol char is almost always its own token.
+            structural += 1;
+        }
+    }
+    const fallback = Math.ceil(text.length / CHARS_PER_TOKEN_FALLBACK);
+    return Math.max(structural, fallback);
+}
+/**
+ * Compute the byte/token reduction between an original codebase string and its
+ * pruned bundle. `original` is the concatenation of the baseline files;
+ * `pruned` is the bundler output (or pruned concatenation).
+ */
+export function computeReduction(original, pruned) {
+    const rawBytes = byteLength(original);
+    const compressedBytes = byteLength(pruned);
+    const rawTokens = estimateTokens(original);
+    const compressedTokens = estimateTokens(pruned);
+    return {
+        rawBytes,
+        compressedBytes,
+        rawTokens,
+        compressedTokens,
+        tokenReductionPercentage: percentDrop(rawTokens, compressedTokens),
+        byteReductionPercentage: percentDrop(rawBytes, compressedBytes),
+    };
+}
+/**
+ * Percentage drop from `before` to `after`, clamped to `[0, 100]` and rounded
+ * to two decimals. Returns 0 when `before` is 0 (nothing to reduce) and never
+ * reports a negative reduction if the "pruned" text somehow grew.
+ */
+function percentDrop(before, after) {
+    if (before <= 0)
+        return 0;
+    const drop = ((before - after) / before) * 100;
+    const clamped = Math.min(100, Math.max(0, drop));
+    return Math.round(clamped * 100) / 100;
+}
+//# sourceMappingURL=index.js.map

package/dist/core/metrics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/metrics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAqBH,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,2EAA2E;IAC3E,iEAAiE;IACjE,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AAC1C,CAAC;AAED,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAC;AAEvC;;;;GAIG;AACH,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAEnC;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEhC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,kCAAkC,CAAC,IAAI,EAAE,CAAC;IAEpE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,sEAAsE;YACtE,kCAAkC;YAClC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QACzD,CAAC;aAAM,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACxC,2DAA2D;YAC3D,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QACzD,CAAC;aAAM,CAAC;YACN,mEAAmE;YACnE,UAAU,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,wBAAwB,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,MAAc;IAC/D,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,eAAe,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,gBAAgB,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAEhD,OAAO;QACL,QAAQ;QACR,eAAe;QACf,SAAS;QACT,gBAAgB;QAChB,wBAAwB,EAAE,WAAW,CAAC,SAAS,EAAE,gBAAgB,CAAC;QAClE,uBAAuB,EAAE,WAAW,CAAC,QAAQ,EAAE,eAAe,CAAC;KAChE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,MAAc,EAAE,KAAa;IAChD,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,MAAM,CAAC,GAAG,GAAG,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACzC,CAAC"}

package/dist/core/parser/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ast-grep–backed implementation of the {@link Parser} contract (Task 1.0).
+ *
+ * Uses `@ast-grep/napi` to parse TypeScript into a concrete syntax tree, then
+ * walks it to extract import bindings and top-level symbols. All node access is
+ * defensive: tree-sitter is error-tolerant, so we validate the tree for ERROR
+ * nodes up front and translate failures into {@link ParseError}.
+ */
+import type { DependencyRef, ImportNode, ImportStatement, Parser, Range, SymbolNode } from './types.js';
+export declare class AstGrepperParser implements Parser {
+    extractImports(source: string, filePath: string): Promise<ImportNode[]>;
+    extractSymbols(source: string, filePath: string): Promise<SymbolNode[]>;
+    extractDependencies(source: string, filePath: string): Promise<DependencyRef[]>;
+    extractImportStatements(source: string, filePath: string): Promise<ImportStatement[]>;
+    collectReferences(source: string, filePath: string, ranges: readonly Range[]): Promise<Set<string>>;
+    sliceNode(source: string, range: Range): string;
+    /** Parse to a root node, translating any syntax error into a {@link ParseError}. */
+    private parseOrThrow;
+    /** Translate one child of an `import_clause` into zero or more bindings. */
+    private collectClauseBindings;
+    private makeImport;
+    /**
+     * Turn one top-level declaration into zero or more symbols.
+     *
+     * `exported` and `exportStatement` come from the caller's position in the tree
+     * (whether this declaration sat inside an `export_statement`). For exported
+     * declarations the range widens to the whole `export …` statement so a slice
+     * reproduces a self-contained, re-emittable chunk (with the `export` keyword).
+     */
+    private collectDeclaration;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/core/parser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/parser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EAEV,eAAe,EACf,MAAM,EACN,KAAK,EAEL,UAAU,EACX,MAAM,YAAY,CAAC;AAmBpB,qBAAa,gBAAiB,YAAW,MAAM;IACvC,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAkB5E;IAEK,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAkB5E;IAEK,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CA+BpF;IAEK,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAiB1F;IAEK,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,KAAK,EAAE,GACvB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAwBtB;IAED,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAE9C;IAID,oFAAoF;IACpF,OAAO,CAAC,YAAY;IAapB,4EAA4E;IAC5E,OAAO,CAAC,qBAAqB;IAuC7B,OAAO,CAAC,UAAU;IAWlB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;CA2B3B"}