context-slice 1.8.2

package/dist/src/workflow/preview.js

@@ -0,0 +1,220 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { estimateTokens } from "../planner/budget.js";
+import { rankSymbol } from "../planner/rank.js";
+import { renderSkeleton } from "../render/compact-context.js";
+import { composeDependencyContext, composeImportContext, composeJpaContext, composeRouteContext, composeSiblings, composeTransactionContext, } from "../planner/composition.js";
+import { WorkflowError } from "./errors.js";
+/**
+ * Composition may use at most this share of the budget, so sibling context
+ * fills spare capacity and never crowds out the target, callers or callees.
+ */
+export const COMPOSITION_BUDGET_SHARE = 0.35;
+/** Reads each distinct included file once, in full, as the "without context-slice" cost.
+ * A file that can't be read (renamed/deleted since indexing) is skipped rather than guessed —
+ * the resulting reduction then understates savings, never overstates them. */
+function wholeFileBaseline(index, included, estimatedTokens) {
+    const filePaths = new Set(included.map((item) => item.filePath));
+    let wholeFileTokens = 0;
+    for (const filePath of filePaths) {
+        try {
+            wholeFileTokens += estimateTokens(readFileSync(join(index.root, filePath), "utf8"));
+        }
+        catch {
+            // Excluded, not guessed — see doc comment above.
+        }
+    }
+    const reduction = wholeFileTokens > 0 ? Math.min(1, Math.max(0, 1 - estimatedTokens / wholeFileTokens)) : 0;
+    return { files: filePaths.size, wholeFileTokens, reduction };
+}
+function parameterCount(symbol) {
+    const parameters = symbol.signature?.match(/\(([^)]*)\)/)?.[1].trim() ?? "";
+    return parameters ? parameters.split(",").length : 0;
+}
+/** Test sources answer "how is this tested", not "how does this work". */
+const isTestPath = (filePath) => /(^|\/)tests?\//i.test(filePath) ||
+    /(^|\/)test_[^/]*$/.test(filePath) ||
+    /_test\.[^/]+$/.test(filePath) ||
+    /Tests?\.java$/.test(filePath) ||
+    /\.(test|spec)\.[jt]sx?$/.test(filePath);
+/** Keep production candidates when there are any; otherwise keep everything. */
+function preferProduction(symbols) {
+    const production = symbols.filter((symbol) => !isTestPath(symbol.filePath));
+    return production.length ? production : symbols;
+}
+function chooseTarget(index, task) {
+    const exact = index.resolveSymbol(task);
+    if (exact.length === 1)
+        return exact[0];
+    const normalized = task.toLowerCase();
+    const named = new RegExp(`\\b(${task.match(/[A-Za-z_][\w$]*/g)?.join("|") ?? ""})\\b`);
+    const exactName = preferProduction(index.symbols.filter((symbol) => (symbol.kind === "method" ||
+        symbol.kind === "constructor" ||
+        symbol.kind === "function") &&
+        normalized.includes(symbol.name.toLowerCase()) &&
+        named.test(symbol.name))).sort((a, b) => b.name.length - a.name.length ||
+        parameterCount(a) - parameterCount(b) ||
+        a.id.localeCompare(b.id));
+    if (exactName.length)
+        return exactName[0];
+    const ranked = index
+        .search(task, 10)
+        .map((result) => index.symbols.find((symbol) => symbol.id === result.id))
+        .filter((symbol) => Boolean(symbol));
+    const target = preferProduction(ranked)[0];
+    if (target)
+        return target;
+    throw new WorkflowError("SYMBOL_NOT_FOUND", `No indexed symbol matches task: ${task}`, "Run context-slice index, then use a task that names a method, type, or qualified symbol.");
+}
+function renderedSkeleton(index, symbol, relation) {
+    const calls = index.calls
+        .filter((call) => call.callerId === symbol.id)
+        .map((call) => `${call.receiverText ? `${call.receiverText}.` : ""}${call.calleeName}(…)${call.externalPackage ? ` [external: ${call.externalPackage}]` : ""}`);
+    return `// ${relation}\n${renderSkeleton(symbol, calls)}`;
+}
+function ranked(symbols, task) {
+    return [...symbols].sort((a, b) => rankSymbol(b, task, task) - rankSymbol(a, task, task) ||
+        a.id.localeCompare(b.id));
+}
+export function buildPreview(index, task, options = {}) {
+    if (!task.trim()) {
+        throw new WorkflowError("SYMBOL_NOT_FOUND", "Preview requires a non-empty developer task.", 'Pass a task such as: context-slice preview "explain retryPayment".');
+    }
+    if (!index.symbols.length) {
+        throw new WorkflowError("INDEX_STALE", "No loaded index is available for preview.", "Run context-slice index before requesting a preview.");
+    }
+    const target = chooseTarget(index, task);
+    const targetTokens = estimateTokens(target.source);
+    const budget = options.budget ?? Math.max(1200, targetTokens);
+    if (budget < targetTokens) {
+        throw new WorkflowError("BUDGET_TOO_SMALL", `Budget ${budget} cannot include target ${target.qualifiedName ?? target.name} (${targetTokens} tokens).`, `Increase --budget to at least ${targetTokens}, or select a smaller target.`);
+    }
+    const included = [];
+    const omitted = [];
+    const composition = {
+        "task target": 0,
+        "direct caller": 0,
+        "direct callee": 0,
+        "enclosing type": 0,
+        "enterprise relation": 0,
+        "file imports": 0,
+    };
+    let estimatedTokens = 0;
+    const add = (symbol, reason, rendered, explanation, extra = {}) => {
+        const tokens = estimateTokens(rendered);
+        if (estimatedTokens + tokens > budget) {
+            omitted.push({
+                symbolId: symbol.id,
+                symbol: symbol.qualifiedName ?? symbol.name,
+                reason: "context budget",
+                estimatedTokens: tokens,
+            });
+            return;
+        }
+        included.push({
+            symbolId: symbol.id,
+            symbol: symbol.qualifiedName ?? symbol.name,
+            filePath: symbol.filePath,
+            reason,
+            explanation,
+            estimatedTokens: tokens,
+            rendered,
+            ...extra,
+        });
+        estimatedTokens += tokens;
+        composition[reason] += tokens;
+    };
+    add(target, "task target", target.source, `Selected because the task names ${target.name}.`);
+    const related = [
+        ...ranked(index.callersAtDepth(target, options.depth ?? 1), task).map((symbol) => ({
+            symbol,
+            reason: "direct caller",
+            relation: "Direct caller",
+        })),
+        ...ranked(index.dependenciesAtDepth(target, options.depth ?? 1), task).map((symbol) => ({
+            symbol,
+            reason: "direct callee",
+            relation: "Direct callee",
+        })),
+    ].sort((a, b) => rankSymbol(b.symbol, task, options.intent ?? "") -
+        rankSymbol(a.symbol, task, options.intent ?? "") ||
+        a.symbol.id.localeCompare(b.symbol.id));
+    const includedIds = new Set([target.id]);
+    for (const item of related) {
+        if (includedIds.has(item.symbol.id))
+            continue;
+        includedIds.add(item.symbol.id);
+        add(item.symbol, item.reason, renderedSkeleton(index, item.symbol, item.relation), `${item.relation} of ${target.qualifiedName ?? target.name}.`);
+    }
+    const relatedFiles = new Set([...includedIds]
+        .map((id) => index.symbols.find((s) => s.id === id)?.filePath)
+        .filter((file) => Boolean(file) && file !== target.filePath));
+    // Same-enclosing-type and import-context composition run after callers and
+    // callees, so they can only use budget they left, and never replace them.
+    let compositionTokens = 0;
+    const compositionAllowance = Math.floor(budget * COMPOSITION_BUDGET_SHARE);
+    const siblings = options.composition === false
+        ? []
+        : composeSiblings(index, target, includedIds);
+    const importCandidates = options.composition === false
+        ? []
+        : composeImportContext(index, target, relatedFiles, includedIds);
+    const relatedIds = new Set([...includedIds].filter((id) => id !== target.id));
+    const routeCandidates = options.composition === false
+        ? []
+        : composeRouteContext(index, target, relatedIds, includedIds);
+    const dependencyCandidates = options.composition === false
+        ? []
+        : composeDependencyContext(index, target, relatedIds, includedIds);
+    const transactionCandidates = options.composition === false
+        ? []
+        : composeTransactionContext(index, target, relatedIds, includedIds);
+    const jpaCandidates = options.composition === false
+        ? []
+        : composeJpaContext(index, target, relatedIds, includedIds);
+    for (const candidate of [
+        ...siblings,
+        ...importCandidates,
+        ...routeCandidates,
+        ...dependencyCandidates,
+        ...transactionCandidates,
+        ...jpaCandidates,
+    ]) {
+        if (candidate.symbol && includedIds.has(candidate.symbol.id))
+            continue;
+        if (compositionTokens + candidate.estimatedTokens > compositionAllowance) {
+            omitted.push({
+                symbolId: candidate.symbol?.id,
+                symbol: candidate.label,
+                reason: "composition budget share",
+                estimatedTokens: candidate.estimatedTokens,
+                evidence: candidate.evidence,
+            });
+            continue;
+        }
+        if (candidate.symbol)
+            includedIds.add(candidate.symbol.id);
+        compositionTokens += candidate.estimatedTokens;
+        add(candidate.symbol ?? target, candidate.reason, candidate.rendered, candidate.evidence.join("; "), {
+            evidence: candidate.evidence,
+        });
+    }
+    const unresolved = index.calls
+        .filter((call) => call.callerId === target.id && !call.resolvedTargetId)
+        .map((call) => ({ calleeName: call.calleeName, evidence: call.evidence }))
+        .sort((a, b) => a.calleeName.localeCompare(b.calleeName));
+    return {
+        task,
+        target,
+        budget,
+        estimatedTokens,
+        rendered: included.map((item) => item.rendered).join("\n\n"),
+        included,
+        omitted,
+        unresolved,
+        confidence: unresolved.length ? "mixed" : "high",
+        freshness: index.inspect(),
+        composition,
+        baseline: wholeFileBaseline(index, included, estimatedTokens),
+    };
+}

package/dist/src/workflow/repository.js

@@ -0,0 +1,56 @@
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { adapterFor, ignoredDirectories } from "../languages/adapter.js";
+import "../languages/java.js";
+import "../languages/typescript/index.js";
+import "../languages/javascript/index.js";
+import "../languages/python/index.js";
+import "../languages/go/index.js";
+import { WorkflowError } from "./errors.js";
+const ignored = new Set([
+    ".git",
+    "node_modules",
+    "target",
+    "build",
+    "dist",
+    "out",
+    ".gradle",
+    ".idea",
+    ".vscode",
+    ".context-slice",
+    ...ignoredDirectories(),
+]);
+function hasSupportedSource(directory) {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        if (ignored.has(entry.name))
+            continue;
+        const path = resolve(directory, entry.name);
+        if (entry.isFile() && adapterFor(entry.name))
+            return true;
+        if (entry.isDirectory() && hasSupportedSource(path))
+            return true;
+    }
+    return false;
+}
+function nearestGitRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(resolve(current, ".git")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+export function resolveRepositoryRoot(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const root = options.repository
+        ? resolve(options.repository)
+        : (nearestGitRoot(cwd) ?? cwd);
+    if (!existsSync(root))
+        throw new WorkflowError("REPOSITORY_NOT_FOUND", `Repository not found: ${root}`, "Pass an existing directory with --repo.");
+    if (!hasSupportedSource(root))
+        throw new WorkflowError("NO_SUPPORTED_SOURCE", `No supported source found in: ${root}`, "Run ContextSlice in a Java or TypeScript repository, or pass --repo.");
+    return root;
+}

package/mcp.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "context-slice": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/dist/src/server/mcp-server.js"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "context-slice",
+  "version": "1.8.2",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nvxtien/context-slice.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nvxtien/context-slice/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/src",
+    "queries",
+    "skills",
+    "plugin.json",
+    "mcp.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "context-slice": "dist/src/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "start": "node dist/src/server/mcp-server.js",
+    "cli": "tsx src/cli.ts",
+    "package-smoke": "tsx scripts/package-smoke-test.ts",
+    "release:rc": "tsx scripts/clean-room-rc.ts",
+    "test": "tsx --test tests/**/*.test.ts",
+    "benchmark": "tsx benchmarks/benchmark.ts",
+    "benchmark:checkouts": "tsx benchmarks/fetch-checkouts.ts",
+    "benchmark:v03": "npm run benchmark:checkouts && tsx benchmarks/v0.3-real-repositories.ts",
+    "benchmark:v04": "npm run benchmark:v03 && tsx benchmarks/v0.4-symbol-index-hardening.ts",
+    "benchmark:v05": "npm run benchmark:v04 && tsx benchmarks/v0.5-semantic-call-resolution.ts",
+    "benchmark:v06": "npm run benchmark:v05 && tsx benchmarks/v0.6-developer-context-efficiency.ts",
+    "benchmark:v07": "tsx benchmarks/v0.7-developer-workflow.ts",
+    "benchmark:v08": "npm run package-smoke",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "benchmark:v11": "npm run benchmark:checkouts && tsx benchmarks/v1.1-typescript-support.ts",
+    "benchmark:v12": "npm run benchmark:checkouts && tsx benchmarks/v1.2-context-composition.ts",
+    "benchmark:v13": "npm run benchmark:checkouts && tsx benchmarks/v1.3-python-support.ts",
+    "benchmark:v16": "npm run benchmark:checkouts && tsx benchmarks/v1.6-go-support.ts",
+    "benchmark:v17": "npm run benchmark:checkouts && tsx benchmarks/v1.7-javascript-support.ts",
+    "benchmark:v15-phase1": "npm run benchmark:checkouts && tsx benchmarks/v1.5-rust-real-repositories.ts",
+    "benchmark:v15-phase3": "npm run benchmark:checkouts && tsx benchmarks/v1.5-rust-tasks.ts",
+    "benchmark:v14-phase1": "npm run benchmark:checkouts && tsx benchmarks/v1.4-phase1-spring-mvc.ts",
+    "benchmark:v14-phase2": "npm run benchmark:checkouts && tsx benchmarks/v1.4-phase2-dependency-injection.ts",
+    "benchmark:v14-phase3": "npm run benchmark:checkouts && tsx benchmarks/v1.4-phase3-transactions.ts",
+    "benchmark:v14-phase4": "npm run benchmark:checkouts && tsx benchmarks/v1.4-phase4-jpa-spring-data.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "better-sqlite3": "^11.8.1",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-go": "^0.23.4",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-rust": "0.21.0",
+    "tree-sitter-typescript": "^0.23.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.15.21",
+    "prettier": "^3.9.8",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}

package/plugin.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "context-slice",
+  "version": "1.8.2",
+  "description": "Structural code-context slicing for Java, TypeScript/TSX, JavaScript, Python, Rust, and Go. Serves a budget-bounded, relevance-ranked slice of a repository instead of whole files.",
+  "skills": "./skills/",
+  "mcpServers": "./mcp.json",
+  "author": {
+    "name": "tien.nguyen"
+  },
+  "homepage": "https://github.com/nvxtien/context-slice",
+  "repository": "https://github.com/nvxtien/context-slice",
+  "license": "MIT",
+  "keywords": ["context", "code-search", "mcp", "tree-sitter", "context-window"]
+}

package/queries/java/annotations.scm

@@ -0,0 +1 @@
+(annotation) @annotation

package/queries/java/calls.scm

@@ -0,0 +1 @@
+(method_invocation name: (identifier) @call.name)

package/queries/java/imports.scm

@@ -0,0 +1 @@
+(import_declaration) @import

package/queries/java/symbols.scm

@@ -0,0 +1,2 @@
+(class_declaration name: (identifier) @class.name)
+(method_declaration name: (identifier) @method.name)

package/skills/context-slice/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: context-slice
+description: Use before reading source files to understand, implement, or explain something in a Java, TypeScript/TSX, JavaScript, Python, Rust, or Go repository. Serves a budget-bounded, relevance-ranked slice of the codebase (target symbol plus ranked callers/callees) through MCP tools instead of whole-file reads, shrinking how much context window the task consumes.
+---
+
+# Context Slice
+
+Context Slice is an MCP server that indexes a repository's symbols and call
+graph (via Tree-sitter, no LLM involved) and serves a compact, explainable
+slice of it — not whole files. Prefer its tools over `Read`/`Grep` on source
+files whenever the task is about a specific symbol, function, class, or
+behavior in a supported repository, so the model spends tokens on the
+relevant code instead of re-reading entire files to find it.
+
+**Supported languages:** Java, TypeScript, TSX, JavaScript, Python, Rust, Go.
+For any other language, or a question with no clear target symbol (e.g.
+"what does this project do overall"), fall back to normal file reading.
+
+## Workflow
+
+1. **Start with `context.preview`** for any implementation or explanation
+   task: `{ task: "<the task in the user's own words>" }`. It returns a
+   selected target symbol, its rendered body, ranked direct callers/callees
+   included under the token budget, inclusion/omission explanations, and any
+   unresolved calls. Read the explanations — they say *why* each piece was
+   included, and what was left out and why.
+2. **Do not assume an unresolved call has a concrete implementation.**
+   Tree-sitter analysis cannot prove runtime dispatch (reflection, DI
+   proxies, framework-generated code, Python/Go dynamic dispatch). An
+   unresolved call in the result means exactly that — unresolved, not
+   "has no implementation."
+3. **Drill in with the other tools once you know the target symbol's id or
+   name:**
+   - `context.symbol` — read one symbol as `signature` / `skeleton` / `body`
+     / `full` source. Use the smallest `detail` level that answers the
+     question; only use `full` when the exact source text matters.
+   - `context.callers` — bounded-depth callers of a symbol (`depth` 1-5).
+   - `context.slice` — a strict-budget slice centered on one symbol instead
+     of a task description.
+   - `context.search` — find candidate symbols by name/text when you don't
+     yet know the exact target.
+   - `context.diff` — a `git diff` under a strict token budget, when the
+     task is about recent changes.
+4. **Only fall back to `Read`/`Grep` on raw source files** when: the
+   language isn't supported, the repository has no index yet and a quick
+   one-off answer is needed, or a tool result's explanation says the
+   information isn't in the index (e.g. a file outside the checked-out
+   source, or an unresolved dynamic call you must manually verify).
+
+## Notes
+
+- The index lives in `.context-slice/` inside the target repository and
+  refreshes automatically on every tool call — changed files are never
+  served stale, and there is no separate "build the index" step to run
+  first.
+- Every tool call targets the project Claude Code currently has open
+  (`CONTEXT_SLICE_ROOT`), not the context-slice plugin's own source.
+- All tool output is structural (symbols, call edges, source text) derived
+  from the repository itself — never benchmark answers, expected results, or
+  anything from outside the checked-out source.