contextdiet-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rizzhab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+<div align="center">
+
+# ContextDiet
+
+### An AST-based token optimizer that slashes AI agent context bloat — up to **99% measured token reduction**, with **$0 network overhead**.
+
+[![CI](https://github.com/risshabs22-quantified/contextDiet/actions/workflows/ci.yml/badge.svg)](https://github.com/risshabs22-quantified/contextDiet/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-ff69b4.svg)](#-contributing)
+
+**Stop paying to send dead code to your LLM.**
+
+</div>
+
+---
+
+## The 30-Second Pitch
+
+Your AI agent doesn't need your entire repo to fix a JWT bug. It needs the token-handling middleware, `verifyToken` underneath it, and the crypto util they both depend on — and **nothing else**.
+
+Naive context packers dump every byte they can find. ContextDiet parses your code into an **Abstract Syntax Tree**, builds a real **dependency graph**, ranks the symbols that match your task, and keeps *only the reachable code paths*. The result is a dense, surgical Markdown bundle that fits your intent — not your file count.
+
+```bash
+npx contextdiet-cli trim ./src --focus "verify the token signature"
+```
+
+The **Markdown bundle streams to stdout** (pipe it straight into a file, your clipboard, or an LLM), while a human-readable summary dashboard is printed to **stderr** — so redirecting stdout gives you a pristine bundle:
+
+```bash
+npx contextdiet-cli trim ./src --focus "verify the token signature" > context.md
+```
+
+Here's a **real, reproducible run** — ContextDiet trimming its own source (`npm run build && node bin/contextdiet.js trim ./src --focus "malformed syntax ParseError"`):
+
+```
+  ContextDiet · trim
+  ────────────────────────────────────────────────────
+  focus      malformed syntax ParseError
+  root       ./src  (ContextDiet's own engine)
+  seeds      2 matched   ·   kept 2/14 files
+  ────────────────────────────────────────────────────
+  original     62.6 KB   ~30,472 tok
+  pruned         616 B      ~302 tok
+  ────────────────────────────────────────────────────
+  reduction  99.0% tokens   ✓ >80% target met
+             99.0% bytes
+  output     (stdout)
+```
+
+> Compression scales with how precisely your task maps to code: narrow, single-symbol tasks measure up to **99.0%**; broader tasks that legitimately touch more code measure less (e.g. **68.2%** on our auth-monolith fixture — see the example below). All numbers are measured runs, logged in `PROJECT_STATUS.md`.
+
+---
+
+## Why ContextDiet?
+
+Most "repo-to-prompt" tools (think `repomix`, `gitingest`, and friends) are **text dumpers**. They walk your filesystem, concatenate files, and maybe strip comments. That's it. They have no idea what your code *means*, so they send everything and let you (and your wallet) sort it out.
+
+That's expensive in three ways:
+
+| | Naive text packers | **ContextDiet** |
+|---|---|---|
+| **Unit of understanding** | Files & bytes | AST symbols & call graph |
+| **What gets included** | Everything it can glob | Only code reachable from your task |
+| **Dead code** | Shipped to the model | Sliced away |
+| **Cost model** | You pay for the whole repo | You pay for the relevant slice |
+| **Circular imports** | Duplicated / mangled | Cycle-safe graph traversal |
+| **Re-exports & aliases** | Often broken by regex | Resolved via real AST |
+| **Network / API calls** | Sometimes (embeddings) | **Zero. Fully local.** |
+| **Determinism** | Order-dependent | Byte-identical every run |
+
+> **The core insight:** LLM cost is billed per token, and most tokens in a naive dump are *irrelevant*. A billing module, a PDF generator, and an analytics service have **zero structural connection** to your auth bug — so why pay to send them? ContextDiet answers "what does the model actually need to see?" with graph theory, not guesswork.
+
+---
+
+## Quick Start
+
+```bash
+# Zero install — run it directly
+npx contextdiet-cli trim ./src --focus "verify the token signature"
+
+# Or install globally (the installed command keeps the short name)
+npm install -g contextdiet-cli
+contextdiet trim ./src --focus "add rate limiting to the login route"
+```
+
+**`contextdiet trim <path> [options]`**
+
+| Flag | Description | Default |
+|---|---|---|
+| `<path>` | Root directory to analyze. | *(required)* |
+| `-f, --focus <query>` | Natural-language description of your task. Drives seed selection. | *(required)* |
+| `--hops <n>` | Dependency-graph traversal depth from the seed nodes. | `2` |
+| `-o, --output <file>` | Write the bundle to a file instead of stdout. | *(stdout)* |
+
+> The bundle is written to **stdout** and the summary dashboard to **stderr**, so `contextdiet trim … > bundle.md` yields a clean file with no dashboard noise mixed in.
+
+---
+
+## How It Works
+
+ContextDiet is a five-stage pipeline. Each stage is a pure, independently testable module — source in, data out, no hidden state.
+
+```
+                         ┌───────────────────────────────────────────────┐
+   ./src  ──────────────▶│                  ContextDiet                   │
+   --focus "verify…"     └───────────────────────────────────────────────┘
+                                              │
+        ┌─────────────────────────────────────┼─────────────────────────────────────┐
+        ▼                                      ▼                                      ▼
+┌───────────────┐   symbols +   ┌───────────────────┐   graph    ┌──────────────────────┐
+│  1. PARSER    │   imports     │ 2. DEPENDENCY     │   nodes    │  3. LEXICAL SEED     │
+│               │──────────────▶│    GRAPH          │───────────▶│     RANKER           │
+│  AST via      │               │                   │            │                      │
+│  ast-grep     │               │ resolves imports, │            │ tokenizes the focus  │
+│  → functions, │               │ re-exports,       │            │ string, scores it    │
+│  classes,     │               │ aliases; handles  │            │ against symbol names │
+│  vars, types  │               │ circular deps     │            │ → seed nodes         │
+└───────────────┘               └───────────────────┘            └──────────────────────┘
+                                                                             │
+        ┌────────────────────────────────────────────────────────────────────┘
+        ▼                                            ▼
+┌───────────────────────┐   kept code    ┌──────────────────────────┐
+│  4. SELECT + PRUNE    │───────────────▶│   5. MARKDOWN BUNDLER    │─────▶  stdout  (→ pipe to file)
+│                       │                │                          │        + metrics → stderr
+│ walks the graph from  │                │ fences each kept file    │
+│ the seeds (reference  │                │ with START/END delimiters│        Raw:         30,472 tok
+│ closure), keeps only  │                │ optimized for LLM        │        Compressed:      302 tok
+│ reachable declarations│                │ context parsing          │        Reduction:       99.0%
+└───────────────────────┘                └──────────────────────────┘
+```
+
+| Stage | Module | Responsibility |
+|---|---|---|
+| **1. Parser** | `src/core/parser` | Extracts imports & top-level symbols from each file via a real AST (ast-grep). Never returns a silently-wrong partial tree — surfaces a catchable `ParseError`. |
+| **2. Dependency Graph** | `src/core/graph` | Resolves the import/export edges between symbols. Cycle-safe (`a → b → a` won't loop). |
+| **3. Lexical Seed Ranker** | `src/core/ranker` | Turns your `--focus` string into weighted seed nodes. Strips stop words, splits camelCase, scores overlap. **$0, deterministic, local.** |
+| **4. Selector + Pruner** | `src/core/graph` · `src/core/pruner` | Walks the dependency graph from the seed symbols (symbol-level reference closure — same-file helpers always follow, so nothing dangles), then re-emits only the surviving declarations, verbatim. |
+| **5. Markdown Bundler** | `src/core/bundler` | Serializes the survivors into a dense, delimiter-fenced stream — plus a `metrics` report proving the reduction. |
+
+---
+
+## Example: The Monolith Auth App
+
+Given a backend where `index.ts` boots Express and mounts **auth**, **billing**, and **analytics** routes:
+
+```
+src/
+├── index.ts                  ← 🔴 sliced  (entry point — a dependent, not a dependency)
+├── routes/auth.ts            ← 🔴 sliced  (calls the token code; not needed to understand it)
+├── middleware/authMiddleware ← 🟢 kept    (its token handlers match the focus)
+├── utils/jwtUtils.ts         ← 🟢 kept    (verifyToken and friends)
+├── utils/crypto.ts           ← 🟢 kept    (jwtUtils depends on it)
+├── routes/billing.ts         ← 🔴 sliced
+├── utils/pdfGenerator.ts     ← 🔴 sliced
+└── services/analytics.ts     ← 🔴 sliced
+```
+
+Running `--focus "verify the token signature"` seeds the symbols that match the task (the middleware's token handlers, `verifyToken`) and keeps their **dependency closure**: `authMiddleware → jwtUtils → crypto` — 3 of 8 files, measured at **9,386 → 2,985 estimated tokens (68.2%)**.
+
+Note the direction: ContextDiet keeps what your focused code **depends on**, never what merely *calls into it*. The entry point and the auth route import the JWT code, but the model doesn't need them to reason about token verification — and billing, the PDF generator, and analytics have zero structural connection to the token path, so they never stand a chance.
+
+Narrower focus, deeper cuts: on ContextDiet's own repo, `--focus "malformed syntax ParseError"` maps to two leaf symbols and measures **99.0%** (30,472 → 302 tokens).
+
+---
+
+## Local Development
+
+```bash
+git clone https://github.com/risshabs22-quantified/contextDiet.git
+cd contextDiet
+npm install
+
+npm run typecheck   # tsc --noEmit, strict mode
+npm test            # full Vitest suite
+npm run build       # compile to dist/
+```
+
+**Requirements:** Node.js `>= 20`.
+
+---
+
+## Contributing
+
+Contributions are welcome and appreciated — ContextDiet is built to be extended.
+
+1. **Fork** the repo and create a feature branch (`git checkout -b feat/my-improvement`).
+2. **Keep it strict.** All code must pass `npm run typecheck` (strict TypeScript, no implicit `any`) and `npm test`.
+3. **Test first.** Every new capability ships with Vitest coverage — see `tests/unit` for the style.
+4. **Stay modular.** Each pipeline stage is a pure module; new backends (tree-sitter, SWC) should slot in behind the existing interfaces without touching callers.
+5. **Open a PR.** CI runs typecheck + the full test suite on every push and pull request. Green check = ready for review.
+
+Good first issues: additional language parsers, a smarter ranker (embeddings-optional), and richer bundle formats (JSON, XML).
+
+---
+
+## License
+
+Released under the **[MIT License](./LICENSE)**. Use it, fork it, ship it, sell it — no strings attached. Copyright © 2026 the ContextDiet contributors.
+
+<div align="center">
+
+**If ContextDiet saves you tokens, [give it a ⭐](https://github.com/risshabs22-quantified/contextDiet) — it genuinely helps.**
+
+</div>

package/bin/contextdiet.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Executable shim for the published package. Delegates to the compiled CLI.
+// For development: `npm run build && node bin/contextdiet.js …` (emits dist/).
+import './../dist/cli/index.js';

package/dist/cli/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ContextDiet CLI (Task 5.0).
+ *
+ *   contextdiet trim <path> --focus "<query>" [--hops <n>] [-o <file>]
+ *
+ * Contract: the Markdown bundle is the ONLY thing written to stdout (so it pipes
+ * cleanly into an LLM / clipboard / file). The human-facing summary dashboard is
+ * written to stderr, so `contextdiet trim … > bundle.md` yields a pristine file.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/cli/index.js

@@ -0,0 +1,104 @@
+/**
+ * ContextDiet CLI (Task 5.0).
+ *
+ *   contextdiet trim <path> --focus "<query>" [--hops <n>] [-o <file>]
+ *
+ * Contract: the Markdown bundle is the ONLY thing written to stdout (so it pipes
+ * cleanly into an LLM / clipboard / file). The human-facing summary dashboard is
+ * written to stderr, so `contextdiet trim … > bundle.md` yields a pristine file.
+ */
+import { Command } from 'commander';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { trim } from '../core/pipeline.js';
+const program = new Command();
+program
+    .name('contextdiet')
+    .description('AST-based token optimizer — trim a codebase to just what an AI agent needs.')
+    .version('0.1.0');
+program
+    .command('trim')
+    .description('Trim a codebase to the code relevant to a focus task, as one dense Markdown stream.')
+    .argument('<path>', 'root directory to analyze')
+    .requiredOption('-f, --focus <query>', 'natural-language task to focus on')
+    .option('--hops <n>', 'dependency-graph traversal depth from seeds', '2')
+    .option('-o, --output <file>', 'write the bundle to a file instead of stdout')
+    .action(async (targetPath, options) => {
+    try {
+        const hops = Number.parseInt(options.hops, 10);
+        if (!Number.isFinite(hops) || hops < 0) {
+            throw new Error(`--hops must be a non-negative integer (got "${options.hops}")`);
+        }
+        const root = path.resolve(targetPath);
+        const result = await trim(root, options.focus, { hops });
+        if (result.totalFiles === 0) {
+            process.stderr.write(`\n  contextdiet: no source files found under ${root}\n\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const outputPath = options.output === undefined ? null : path.resolve(options.output);
+        if (outputPath !== null) {
+            await fs.writeFile(outputPath, ensureTrailingNewline(result.bundle), 'utf8');
+        }
+        else {
+            process.stdout.write(ensureTrailingNewline(result.bundle));
+        }
+        printDashboard(result, outputPath);
+    }
+    catch (error) {
+        process.stderr.write(`\n  contextdiet: ${error.message}\n\n`);
+        process.exitCode = 1;
+    }
+});
+program.parseAsync(process.argv).catch((error) => {
+    process.stderr.write(`\n  contextdiet: ${error.message}\n\n`);
+    process.exitCode = 1;
+});
+// --- presentation ---------------------------------------------------------
+const useColor = Boolean(process.stderr.isTTY) && process.env.NO_COLOR === undefined;
+const paint = (code, text) => useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+const bold = (t) => paint('1', t);
+const dim = (t) => paint('2', t);
+const cyan = (t) => paint('36', t);
+const green = (t) => paint('32', t);
+const yellow = (t) => paint('33', t);
+function printDashboard(result, outputPath) {
+    const m = result.metrics;
+    const hitTarget = m.tokenReductionPercentage >= 80;
+    const pct = `${m.tokenReductionPercentage.toFixed(1)}%`;
+    const pctText = hitTarget ? green(bold(pct)) : yellow(bold(pct));
+    const targetText = hitTarget ? green('✓ >80% target met') : yellow('⚠ below >80% target');
+    const rule = dim('─'.repeat(52));
+    const label = (t) => dim(t.padEnd(11));
+    const lines = [
+        '',
+        `  ${bold(cyan('ContextDiet'))} ${dim('· trim')}`,
+        `  ${rule}`,
+        `  ${label('focus')}${result.focus}`,
+        `  ${label('root')}${result.rootDir}`,
+        `  ${label('seeds')}${bold(String(result.seedCount))} matched   ${dim('·')}   kept ${bold(`${result.keptFiles.length}/${result.totalFiles}`)} files`,
+        `  ${rule}`,
+        `  ${label('original')}${humanBytes(m.rawBytes).padStart(9)}   ${dim(`~${grouped(m.rawTokens)} tok`)}`,
+        `  ${label('pruned')}${humanBytes(m.compressedBytes).padStart(9)}   ${dim(`~${grouped(m.compressedTokens)} tok`)}`,
+        `  ${rule}`,
+        `  ${label('reduction')}${pctText} ${dim('tokens')}   ${targetText}`,
+        `  ${dim(''.padEnd(11))}${dim(`${m.byteReductionPercentage.toFixed(1)}% bytes`)}`,
+        `  ${label('output')}${outputPath === null ? dim('(stdout)') : outputPath}`,
+        '',
+    ];
+    process.stderr.write(lines.join('\n') + '\n');
+}
+function ensureTrailingNewline(text) {
+    return text.endsWith('\n') ? text : `${text}\n`;
+}
+function humanBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function grouped(n) {
+    return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

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

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

@@ -0,0 +1,49 @@
+/**
+ * MarkdownBundler — Task 5.0 (output delivery).
+ *
+ * The final stage of the pipeline: take the pruned files and serialize them
+ * into one hyper-dense, LLM-friendly stream. The format is deliberately plain
+ * (explicit START/END delimiters rather than triple-backtick fences) because:
+ *   - it survives nested code that itself contains ``` fences without escaping,
+ *   - the path appears on both boundaries so a model can attribute every line,
+ *   - it costs almost no extra tokens per file.
+ *
+ * Pure and deterministic: same input files always produce byte-identical output.
+ * No I/O, no network.
+ */
+/** A single file to include in the bundle. */
+export interface BundleFile {
+    /** Path shown in the delimiters — should be repo-relative for readability. */
+    readonly path: string;
+    /** The (already pruned) file contents. */
+    readonly content: string;
+}
+/** Tunables for how the stream is assembled. */
+export interface BundlerOptions {
+    /**
+     * Blank line(s) inserted between consecutive file blocks. Defaults to `1`.
+     * Purely cosmetic; does not affect a block's own delimiters.
+     */
+    readonly blockSeparation?: number;
+    /**
+     * Sort files by path before emitting, for stable output regardless of input
+     * order. Defaults to `false` (preserve caller order, typically graph order).
+     */
+    readonly sortByPath?: boolean;
+}
+/**
+ * Wrap a single file's content in the START/END delimiters. Exported so callers
+ * (and tests) can format one block in isolation.
+ */
+export declare function formatFileBlock(file: BundleFile): string;
+export declare class MarkdownBundler {
+    private readonly blockSeparation;
+    private readonly sortByPath;
+    constructor(options?: BundlerOptions);
+    /**
+     * Combine all files into a single Markdown stream. Returns an empty string for
+     * an empty file list.
+     */
+    bundle(files: readonly BundleFile[]): string;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/bundler/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAOxD;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IAErC,YAAY,OAAO,GAAE,cAAmB,EAGvC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAS3C;CACF"}

package/dist/core/bundler/index.js

@@ -0,0 +1,57 @@
+/**
+ * MarkdownBundler — Task 5.0 (output delivery).
+ *
+ * The final stage of the pipeline: take the pruned files and serialize them
+ * into one hyper-dense, LLM-friendly stream. The format is deliberately plain
+ * (explicit START/END delimiters rather than triple-backtick fences) because:
+ *   - it survives nested code that itself contains ``` fences without escaping,
+ *   - the path appears on both boundaries so a model can attribute every line,
+ *   - it costs almost no extra tokens per file.
+ *
+ * Pure and deterministic: same input files always produce byte-identical output.
+ * No I/O, no network.
+ */
+const START_PREFIX = '--- START FILE: ';
+const END_PREFIX = '--- END FILE: ';
+const DELIM_SUFFIX = ' ---';
+/**
+ * Wrap a single file's content in the START/END delimiters. Exported so callers
+ * (and tests) can format one block in isolation.
+ */
+export function formatFileBlock(file) {
+    const header = `${START_PREFIX}${file.path}${DELIM_SUFFIX}`;
+    const footer = `${END_PREFIX}${file.path}${DELIM_SUFFIX}`;
+    // Preserve content verbatim; only guarantee the delimiters sit on their own
+    // lines by trimming a single trailing newline so the footer never doubles up.
+    const body = stripSingleTrailingNewline(file.content);
+    return `${header}\n${body}\n${footer}`;
+}
+export class MarkdownBundler {
+    blockSeparation;
+    sortByPath;
+    constructor(options = {}) {
+        this.blockSeparation = Math.max(0, options.blockSeparation ?? 1);
+        this.sortByPath = options.sortByPath ?? false;
+    }
+    /**
+     * Combine all files into a single Markdown stream. Returns an empty string for
+     * an empty file list.
+     */
+    bundle(files) {
+        if (files.length === 0)
+            return '';
+        const ordered = this.sortByPath
+            ? [...files].sort((a, b) => a.path.localeCompare(b.path))
+            : files;
+        const separator = '\n'.repeat(this.blockSeparation + 1);
+        return ordered.map(formatFileBlock).join(separator);
+    }
+}
+function stripSingleTrailingNewline(content) {
+    if (content.endsWith('\r\n'))
+        return content.slice(0, -2);
+    if (content.endsWith('\n'))
+        return content.slice(0, -1);
+    return content;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/bundler/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwBH,MAAM,YAAY,GAAG,kBAAkB,CAAC;AACxC,MAAM,UAAU,GAAG,gBAAgB,CAAC;AACpC,MAAM,YAAY,GAAG,MAAM,CAAC;AAE5B;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAgB;IAC9C,MAAM,MAAM,GAAG,GAAG,YAAY,GAAG,IAAI,CAAC,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5D,MAAM,MAAM,GAAG,GAAG,UAAU,GAAG,IAAI,CAAC,IAAI,GAAG,YAAY,EAAE,CAAC;IAC1D,4EAA4E;IAC5E,8EAA8E;IAC9E,MAAM,IAAI,GAAG,0BAA0B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtD,OAAO,GAAG,MAAM,KAAK,IAAI,KAAK,MAAM,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,OAAO,eAAe;IACT,eAAe,CAAS;IACxB,UAAU,CAAU;IAErC,YAAY,OAAO,GAAmB,EAAE;QACtC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,eAAe,IAAI,CAAC,CAAC,CAAC;QACjE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC;IAChD,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAA4B;QACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAElC,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU;YAC7B,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACzD,CAAC,CAAC,KAAK,CAAC;QAEV,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC;QACxD,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACtD,CAAC;CACF;AAED,SAAS,0BAA0B,CAAC,OAAe;IACjD,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1D,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,OAAO,CAAC;AACjB,CAAC"}

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

@@ -0,0 +1,29 @@
+/**
+ * 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 type { Parser } from '../parser/types.js';
+import type { DependencyGraph, GraphResolver } from './types.js';
+export declare class DependencyGraphResolver implements GraphResolver {
+    private readonly parser;
+    constructor(parser?: Parser);
+    buildGraph(rootDir: string): Promise<DependencyGraph>;
+    private buildNode;
+}
+/**
+ * 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 declare function collectReachable(graph: DependencyGraph, startPath: string, maxHops?: number): Set<string>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/graph/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAEV,eAAe,EAEf,aAAa,EACd,MAAM,YAAY,CAAC;AAUpB,qBAAa,uBAAwB,YAAW,aAAa;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YAAY,MAAM,GAAE,MAA+B,EAElD;IAEK,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA2B1D;YAEa,SAAS;CAgCxB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,MAAiC,GACzC,GAAG,CAAC,MAAM,CAAC,CAwBb"}