diffdoc 0.1.0

package/.diffdocrc.example

@@ -0,0 +1,12 @@
+{
+  "baseDir": "./.diffdoc",
+  "aiProvider": "local",
+  "localLlmEndpoint": "http://localhost:11434/v1",
+  "localEmbedEndpoint": "http://localhost:11434/v1/embeddings",
+  "localChatModel": "qwen2.5-coder:7b",
+  "localEmbedModel": "nomic-embed-code",
+  "cloudLlmEndpoint": "https://api.openai.com/v1",
+  "cloudChatModel": "gpt-4o-mini",
+  "cloudEmbedModel": "text-embedding-3-small",
+  "openaiApiKey": ""
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Sullivan
+
+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,153 @@
+# DiffDoc
+
+## Project Description
+
+DiffDoc turns source code into searchable, plain-English project context. It scans repository files, asks an OpenAI-compatible chat model to summarize the business behavior in each file, stores those summaries in a portable JSON manifest, embeds the manifest into a local Vectra index, and answers questions using the indexed results as retrieval context.
+
+The project is designed for teams that need fast codebase comprehension without requiring every stakeholder to read implementation details. It can run against local model servers such as Ollama, LM Studio, or vLLM, or against cloud OpenAI-compatible APIs.
+
+## Installation
+
+Run from this repository:
+
+```bash
+npm install
+npm run build
+node dist/index.js --help
+```
+
+Run after publishing:
+
+```bash
+npx diffdoc --help
+```
+
+Use as a project dev dependency:
+
+```bash
+npm install --save-dev diffdoc
+npx diffdoc --help
+```
+
+Package scripts can call the installed binary:
+
+```json
+{
+  "scripts": {
+    "diffdoc:summarize": "diffdoc summarize",
+    "diffdoc:embed": "diffdoc embed",
+    "diffdoc:query": "diffdoc query"
+  }
+}
+```
+
+## Configuration
+
+DiffDoc accepts runtime flags on each command. It also loads a JSON `.diffdocrc` file from the current working directory when present, or from a custom path with `--config <path>`.
+
+Precedence:
+
+1. CLI flags
+2. `.diffdocrc`
+3. Environment variable fallbacks
+
+Create a local config from the example:
+
+```bash
+cp .diffdocrc.example .diffdocrc
+```
+
+Example config with all supported keys:
+
+```json
+{
+  "baseDir": "./.diffdoc",
+  "aiProvider": "local",
+  "localLlmEndpoint": "http://localhost:11434/v1",
+  "localEmbedEndpoint": "http://localhost:11434/v1/embeddings",
+  "localChatModel": "qwen2.5-coder:7b",
+  "localEmbedModel": "nomic-embed-code",
+  "cloudLlmEndpoint": "https://api.openai.com/v1",
+  "cloudChatModel": "gpt-4o-mini",
+  "cloudEmbedModel": "text-embedding-3-small",
+  "openaiApiKey": ""
+}
+```
+
+Supported environment fallbacks use the uppercase names for the same settings, including `AI_PROVIDER`, `DIFFDOC_BASE_DIR`, `LOCAL_LLM_ENDPOINT`, `LOCAL_EMBED_ENDPOINT`, `LOCAL_CHAT_MODEL`, `LOCAL_EMBED_MODEL`, `CLOUD_LLM_ENDPOINT`, `CLOUD_CHAT_MODEL`, `CLOUD_EMBED_MODEL`, and `OPENAI_API_KEY`.
+
+## Commands
+
+Summarize a repository into `./.diffdoc/manifest.json`:
+
+```bash
+diffdoc summarize --path . --mode all
+```
+
+Summarize only changed Git files using the existing manifest state:
+
+```bash
+diffdoc summarize --path . --mode delta
+```
+
+Embed the manifest into a local Vectra index at `./.diffdoc/vectra`:
+
+```bash
+diffdoc embed
+```
+
+Ask a question using retrieved embedded context:
+
+```bash
+diffdoc query "How does this project process changed files?"
+```
+
+Include retrieved code snapshots after the answer:
+
+```bash
+diffdoc query "How does embedding work?" --top 3 --code
+```
+
+Prompt the configured chat model directly:
+
+```bash
+diffdoc prompt "Confirm the configured model is reachable."
+```
+
+Use a custom config file:
+
+```bash
+diffdoc query "How does embedding work?" --config ./config/diffdoc.local.json
+```
+
+Override a config value at runtime:
+
+```bash
+diffdoc embed --config ./.diffdocrc --base-dir ./tmp-diffdoc
+```
+
+## Workflow
+
+Typical usage is:
+
+```bash
+diffdoc summarize --path . --mode all
+diffdoc embed
+diffdoc query "What business behavior does this repository implement?"
+```
+
+After the initial run, use delta mode to refresh changed files:
+
+```bash
+diffdoc summarize --path . --mode delta
+diffdoc embed
+```
+
+## Notes
+
+- Node.js `>=22` is required because Vectra requires it.
+- `.diffdoc/` and `.diffdocrc` are ignored by git by default.
+- `summarize` requires a configured chat model.
+- `embed` requires a configured embedding model.
+- `query` requires both a configured chat model and embedding model.
+- For code-oriented embedding models such as `nomic-embed-code`, DiffDoc prefixes query embeddings with `Represent this query for searching relevant code:`.

package/dist/commands/embed.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVectraIndexPath = getVectraIndexPath;
+exports.runEmbed = runEmbed;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const vectra_1 = require("vectra");
+const llm_1 = require("../utils/llm");
+const paths_1 = require("../utils/paths");
+const VECTRA_INDEX_DIR = "vectra";
+function getVectraIndexPath(config) {
+    return node_path_1.default.resolve((0, paths_1.getDiffdocBaseDir)(config.baseDir), VECTRA_INDEX_DIR);
+}
+function buildDocument(filePath, summaryText, rawCodeSnapshot) {
+    return `File: ${filePath}\n` +
+        `Summary: ${summaryText}\n\n` +
+        `Code Snapshot:\n\`\`\`\n${rawCodeSnapshot}\n\`\`\``;
+}
+async function runEmbed(options, config) {
+    const manifestPath = (0, paths_1.resolveDiffdocArtifactPath)(options.manifest, config.baseDir);
+    const manifest = JSON.parse(await promises_1.default.readFile(manifestPath, "utf8"));
+    const entries = Object.entries(manifest.files);
+    const indexPath = getVectraIndexPath(config);
+    const index = new vectra_1.LocalIndex(indexPath);
+    await index.createIndex({
+        version: 1,
+        deleteIfExists: true,
+        metadata_config: {
+            indexed: ["filePath", "hash"]
+        }
+    });
+    if (entries.length === 0) {
+        console.log(`Created empty Vectra index at ${indexPath}.`);
+        return;
+    }
+    const documents = entries.map(([filePath, file]) => buildDocument(filePath, file.summaryText, file.rawCodeSnapshot));
+    const embeddings = await (0, llm_1.generateEmbeddings)(documents, config.embeddings);
+    await index.beginUpdate();
+    try {
+        for (let i = 0; i < entries.length; i += 1) {
+            const [filePath, file] = entries[i];
+            await index.upsertItem({
+                id: filePath,
+                vector: embeddings[i],
+                metadata: {
+                    filePath,
+                    hash: file.hash,
+                    summaryText: file.summaryText,
+                    rawCodeSnapshot: file.rawCodeSnapshot
+                }
+            });
+        }
+        await index.endUpdate();
+    }
+    catch (error) {
+        index.cancelUpdate();
+        throw error;
+    }
+    console.log(`Embedded ${entries.length} summaries into Vectra index at ${indexPath}.`);
+}

package/dist/commands/query.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runQuery = runQuery;
+const vectra_1 = require("vectra");
+const llm_1 = require("../utils/llm");
+const embed_1 = require("./embed");
+const CODE_QUERY_PREFIX = "Represent this query for searching relevant code: ";
+function parseTopK(value) {
+    const topK = Number.parseInt(value, 10);
+    if (!Number.isInteger(topK) || topK < 1) {
+        throw new Error("Invalid --top value. Expected a positive integer.");
+    }
+    return topK;
+}
+function trimForDisplay(text, maxLength) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return `${text.slice(0, maxLength).trimEnd()}...`;
+}
+function buildAnswerPrompt(question, results) {
+    const context = results.map((result, indexPosition) => {
+        const metadata = result.item.metadata;
+        return [
+            `Result ${indexPosition + 1}`,
+            `File: ${metadata.filePath}`,
+            `Score: ${result.score}`,
+            `Summary:\n${metadata.summaryText}`,
+            `Code Snapshot:\n${metadata.rawCodeSnapshot}`
+        ].join("\n");
+    }).join("\n\n---\n\n");
+    return `Answer the user's question using only the retrieved DiffDoc results below. If the results do not contain enough information, say what is missing. Prefer a direct answer first, then cite the relevant file paths. Keep the explanation appropriate to the question: summarize when asked for a summary, explain implementation details when asked how something works, and avoid unsupported claims.\n\nUser question:\n${question}\n\nRetrieved results:\n${context}`;
+}
+async function runQuery(message, options, config) {
+    const topK = parseTopK(options.top);
+    const indexPath = (0, embed_1.getVectraIndexPath)(config);
+    const index = new vectra_1.LocalIndex(indexPath);
+    if (!await index.isIndexCreated()) {
+        throw new Error(`No Vectra index found at ${indexPath}. Run "diffdoc embed" first.`);
+    }
+    const [queryVector] = await (0, llm_1.generateEmbeddings)([`${CODE_QUERY_PREFIX}${message}`], config.embeddings);
+    const results = await index.queryItems(queryVector, message, topK);
+    if (results.length === 0) {
+        console.log("No matching embedded summaries found.");
+        return;
+    }
+    const answer = await (0, llm_1.promptLlm)(buildAnswerPrompt(message, results), config.chat);
+    console.log(answer);
+    console.log("\nSources:");
+    for (const [indexPosition, result] of results.entries()) {
+        const metadata = result.item.metadata;
+        console.log(`${indexPosition + 1}. ${metadata.filePath} (${result.score.toFixed(4)})`);
+    }
+    if (!options.code) {
+        return;
+    }
+    for (const [indexPosition, result] of results.entries()) {
+        const metadata = result.item.metadata;
+        console.log(`\n#${indexPosition + 1} ${metadata.filePath}`);
+        console.log(`Score: ${result.score.toFixed(4)}`);
+        console.log(`Hash: ${metadata.hash}`);
+        console.log("Summary:");
+        console.log(trimForDisplay(metadata.summaryText, 1200));
+        if (options.code) {
+            console.log("Code Snapshot:");
+            console.log(trimForDisplay(metadata.rawCodeSnapshot, 2000));
+        }
+    }
+}

package/dist/commands/summarize.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSummarize = runSummarize;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const git_1 = require("../utils/git");
+const hashing_1 = require("../utils/hashing");
+const llm_1 = require("../utils/llm");
+const paths_1 = require("../utils/paths");
+const TARGET_EXTENSIONS = new Set([".ts", ".js", ".cs", ".py"]);
+const IGNORED_DIRECTORIES = new Set([".git", "node_modules", "dist"]);
+const IGNORED_FILES = new Set(["package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb"]);
+function normalizeRelativePath(filePath) {
+    return filePath.split(node_path_1.default.sep).join("/");
+}
+function isTargetCodeFile(filePath) {
+    return TARGET_EXTENSIONS.has(node_path_1.default.extname(filePath)) && !IGNORED_FILES.has(node_path_1.default.basename(filePath));
+}
+async function readManifest(manifestPath) {
+    try {
+        return JSON.parse(await promises_1.default.readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === "ENOENT") {
+            return { lastSyncedCommit: "", files: {} };
+        }
+        throw error;
+    }
+}
+async function writeManifest(manifestPath, manifest) {
+    await promises_1.default.mkdir(node_path_1.default.dirname(manifestPath), { recursive: true });
+    await promises_1.default.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+async function walkCodeFiles(rootPath, currentPath = rootPath) {
+    const entries = await promises_1.default.readdir(currentPath, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const entryPath = node_path_1.default.join(currentPath, entry.name);
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRECTORIES.has(entry.name)) {
+                files.push(...await walkCodeFiles(rootPath, entryPath));
+            }
+            continue;
+        }
+        if (entry.isFile() && isTargetCodeFile(entry.name)) {
+            files.push(normalizeRelativePath(node_path_1.default.relative(rootPath, entryPath)));
+        }
+    }
+    return files.sort();
+}
+async function summarizeFile(rootPath, relativePath, config) {
+    const absolutePath = node_path_1.default.join(rootPath, relativePath);
+    const rawCodeSnapshot = await promises_1.default.readFile(absolutePath, "utf8");
+    return {
+        hash: (0, hashing_1.hashFileContent)(rawCodeSnapshot),
+        summaryText: await (0, llm_1.generateFunctionalSummary)(relativePath, rawCodeSnapshot, config.chat),
+        rawCodeSnapshot
+    };
+}
+async function runSummarize(options, config) {
+    if (options.mode !== "all" && options.mode !== "delta") {
+        throw new Error('Invalid summarize mode. Expected "all" or "delta".');
+    }
+    const commandCwd = process.cwd();
+    const repoPath = node_path_1.default.resolve(commandCwd, options.path);
+    const manifestPath = (0, paths_1.resolveDiffdocArtifactPath)(options.out, config.baseDir);
+    const manifest = options.mode === "delta" ? await readManifest(manifestPath) : { lastSyncedCommit: "", files: {} };
+    if (options.mode === "all") {
+        const files = await walkCodeFiles(repoPath);
+        manifest.files = {};
+        for (const filePath of files) {
+            manifest.files[filePath] = await summarizeFile(repoPath, filePath, config);
+            console.log(`Summarized ${filePath}`);
+        }
+    }
+    else {
+        const deltas = await (0, git_1.getGitDeltas)(repoPath, manifest.lastSyncedCommit);
+        for (const deletedPath of deltas.deleted) {
+            delete manifest.files[deletedPath];
+            console.log(`Pruned ${deletedPath}`);
+        }
+        for (const filePath of deltas.modifiedOrAdded) {
+            const absolutePath = node_path_1.default.join(repoPath, filePath);
+            try {
+                const rawCodeSnapshot = await promises_1.default.readFile(absolutePath, "utf8");
+                const hash = (0, hashing_1.hashFileContent)(rawCodeSnapshot);
+                if (manifest.files[filePath]?.hash === hash)
+                    continue;
+                manifest.files[filePath] = {
+                    hash,
+                    summaryText: await (0, llm_1.generateFunctionalSummary)(filePath, rawCodeSnapshot, config.chat),
+                    rawCodeSnapshot
+                };
+                console.log(`Updated ${filePath}`);
+            }
+            catch (error) {
+                const nodeError = error;
+                if (nodeError.code === "ENOENT") {
+                    delete manifest.files[filePath];
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    manifest.lastSyncedCommit = await (0, git_1.getCurrentCommit)(repoPath);
+    await writeManifest(manifestPath, manifest);
+    console.log(`Wrote manifest to ${manifestPath}`);
+}

package/dist/config.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRuntimeConfig = buildRuntimeConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function readOption(value, envName, fallback = "") {
+    return value || process.env[envName] || fallback;
+}
+function loadRcFile(configPath) {
+    const resolvedPath = node_path_1.default.resolve(process.cwd(), configPath || ".diffdocrc");
+    if (!node_fs_1.default.existsSync(resolvedPath)) {
+        if (configPath) {
+            throw new Error(`Config file not found: ${resolvedPath}`);
+        }
+        return {};
+    }
+    const parsed = JSON.parse(node_fs_1.default.readFileSync(resolvedPath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Config file must contain a JSON object: ${resolvedPath}`);
+    }
+    return parsed;
+}
+function mergeConfigOptions(options) {
+    const rcOptions = loadRcFile(options.config);
+    return {
+        ...rcOptions,
+        ...options
+    };
+}
+function readProvider(value) {
+    const provider = readOption(value, "AI_PROVIDER", "local");
+    if (provider !== "local" && provider !== "cloud") {
+        throw new Error('Invalid AI provider. Expected "local" or "cloud".');
+    }
+    return provider;
+}
+function buildRuntimeConfig(options, needs = { chat: true, embeddings: true }) {
+    const mergedOptions = mergeConfigOptions(options);
+    const provider = readProvider(mergedOptions.aiProvider);
+    const apiKey = readOption(mergedOptions.openaiApiKey, "OPENAI_API_KEY", provider === "local" ? "local-key" : "");
+    const chatBaseURL = provider === "cloud"
+        ? readOption(mergedOptions.cloudLlmEndpoint, "CLOUD_LLM_ENDPOINT", "https://api.openai.com/v1")
+        : readOption(mergedOptions.localLlmEndpoint, "LOCAL_LLM_ENDPOINT");
+    const chatModel = provider === "cloud"
+        ? readOption(mergedOptions.cloudChatModel, "CLOUD_CHAT_MODEL", "gpt-4o-mini")
+        : readOption(mergedOptions.localChatModel, "LOCAL_CHAT_MODEL");
+    const embedBaseURL = provider === "cloud"
+        ? readOption(mergedOptions.cloudLlmEndpoint, "CLOUD_LLM_ENDPOINT", "https://api.openai.com/v1")
+        : readOption(mergedOptions.localEmbedEndpoint, "LOCAL_EMBED_ENDPOINT");
+    const embedModel = provider === "cloud"
+        ? readOption(mergedOptions.cloudEmbedModel, "CLOUD_EMBED_MODEL", "text-embedding-3-small")
+        : readOption(mergedOptions.localEmbedModel, "LOCAL_EMBED_MODEL");
+    if (needs.chat && !chatBaseURL) {
+        throw new Error(`Missing ${provider === "cloud" ? "cloud" : "local"} chat endpoint. Pass the runtime option or set ${provider === "cloud" ? "CLOUD_LLM_ENDPOINT" : "LOCAL_LLM_ENDPOINT"}.`);
+    }
+    if (needs.chat && !chatModel) {
+        throw new Error(`Missing ${provider === "cloud" ? "cloud" : "local"} chat model. Pass the runtime option or set ${provider === "cloud" ? "CLOUD_CHAT_MODEL" : "LOCAL_CHAT_MODEL"}.`);
+    }
+    if (needs.embeddings && !embedBaseURL) {
+        throw new Error(`Missing ${provider === "cloud" ? "cloud" : "local"} embedding endpoint. Pass the runtime option or set ${provider === "cloud" ? "CLOUD_LLM_ENDPOINT" : "LOCAL_EMBED_ENDPOINT"}.`);
+    }
+    if (needs.embeddings && !embedModel) {
+        throw new Error(`Missing ${provider === "cloud" ? "cloud" : "local"} embedding model. Pass the runtime option or set ${provider === "cloud" ? "CLOUD_EMBED_MODEL" : "LOCAL_EMBED_MODEL"}.`);
+    }
+    if (provider === "cloud" && (needs.chat || needs.embeddings) && !apiKey) {
+        throw new Error("Missing OpenAI API key. Pass --openai-api-key or set OPENAI_API_KEY.");
+    }
+    return {
+        baseDir: readOption(mergedOptions.baseDir, "DIFFDOC_BASE_DIR", "./.diffdoc"),
+        provider,
+        chat: {
+            apiKey,
+            baseURL: chatBaseURL,
+            model: chatModel
+        },
+        embeddings: {
+            apiKey,
+            baseURL: embedBaseURL,
+            model: embedModel
+        }
+    };
+}

package/dist/index.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const config_1 = require("./config");
+const embed_1 = require("./commands/embed");
+const query_1 = require("./commands/query");
+const summarize_1 = require("./commands/summarize");
+const llm_1 = require("./utils/llm");
+const program = new commander_1.Command();
+function addBaseOptions(command) {
+    return command
+        .option("--config <path>", "path to .diffdocrc JSON config file")
+        .option("--base-dir <path>", "DiffDoc artifact directory")
+        .option("--ai-provider <provider>", "AI provider: local or cloud");
+}
+function addChatOptions(command) {
+    return command
+        .option("--local-llm-endpoint <url>", "local OpenAI-compatible chat endpoint")
+        .option("--local-chat-model <model>", "local chat model name")
+        .option("--cloud-llm-endpoint <url>", "cloud OpenAI-compatible chat endpoint")
+        .option("--cloud-chat-model <model>", "cloud chat model name")
+        .option("--openai-api-key <key>", "OpenAI-compatible API key; falls back to OPENAI_API_KEY");
+}
+function addEmbeddingOptions(command) {
+    return command
+        .option("--local-embed-endpoint <url>", "local OpenAI-compatible embeddings endpoint")
+        .option("--local-embed-model <model>", "local embedding model name")
+        .option("--cloud-embed-model <model>", "cloud embedding model name");
+}
+function addCloudEndpointAndKeyOptions(command) {
+    return command
+        .option("--cloud-llm-endpoint <url>", "cloud OpenAI-compatible endpoint")
+        .option("--openai-api-key <key>", "OpenAI-compatible API key; falls back to OPENAI_API_KEY");
+}
+program
+    .name("diffdoc")
+    .description("Translate repository code shifts into plain-English business context")
+    .version("0.1.0");
+addChatOptions(addBaseOptions(program
+    .command("summarize")))
+    .description("Summarize repository code into a portable JSON manifest")
+    .option("--path <path>", "repository or code path to scan", ".")
+    .option("--out <path>", "manifest output path under --base-dir", "manifest.json")
+    .option("--mode <mode>", "summarization mode: all or delta", "all")
+    .action(async (options) => {
+    try {
+        const config = (0, config_1.buildRuntimeConfig)(options, { chat: true });
+        await (0, summarize_1.runSummarize)({ path: options.path, out: options.out, mode: options.mode }, config);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+addChatOptions(addBaseOptions(program
+    .command("prompt")))
+    .description("Send a plain prompt to the configured LLM")
+    .argument("<message...>", "prompt text to send")
+    .action(async (messageParts, options) => {
+    try {
+        const config = (0, config_1.buildRuntimeConfig)(options, { chat: true });
+        const response = await (0, llm_1.promptLlm)(messageParts.join(" "), config.chat);
+        console.log(response);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+addEmbeddingOptions(addChatOptions(addBaseOptions(program
+    .command("query"))))
+    .description("Search the local Vectra index with a natural-language question")
+    .argument("<message...>", "question or search text")
+    .option("--top <count>", "number of matches to return", "5")
+    .option("--code", "include code snapshots in results", false)
+    .action(async (messageParts, options) => {
+    try {
+        const config = (0, config_1.buildRuntimeConfig)(options, { chat: true, embeddings: true });
+        await (0, query_1.runQuery)(messageParts.join(" "), options, config);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+addCloudEndpointAndKeyOptions(addEmbeddingOptions(addBaseOptions(program
+    .command("embed"))))
+    .description("Embed manifest summaries into a local Vectra index")
+    .option("--manifest <path>", "manifest input path under --base-dir", "manifest.json")
+    .action(async (options) => {
+    try {
+        const config = (0, config_1.buildRuntimeConfig)(options, { embeddings: true });
+        await (0, embed_1.runEmbed)({ manifest: options.manifest }, config);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+program.parseAsync(process.argv).catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/utils/git.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGitDeltas = getGitDeltas;
+exports.getCurrentCommit = getCurrentCommit;
+const node_path_1 = __importDefault(require("node:path"));
+const simple_git_1 = __importDefault(require("simple-git"));
+const TARGET_EXTENSIONS = new Set([".ts", ".js", ".cs", ".py"]);
+function normalizePath(filePath) {
+    return filePath.split(node_path_1.default.sep).join("/");
+}
+function isTargetCodeFile(filePath) {
+    return TARGET_EXTENSIONS.has(node_path_1.default.extname(filePath));
+}
+function addUnique(target, filePath) {
+    const normalized = normalizePath(filePath.trim());
+    if (normalized && isTargetCodeFile(normalized)) {
+        target.add(normalized);
+    }
+}
+async function getGitDeltas(repoPath, sinceRef) {
+    const git = (0, simple_git_1.default)(repoPath);
+    const modifiedOrAdded = new Set();
+    const deleted = new Set();
+    if (sinceRef) {
+        const output = await git.raw(["diff", "--name-status", `${sinceRef}..HEAD`]);
+        for (const line of output.split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            const [status, ...rest] = line.split(/\s+/);
+            const filePath = rest[rest.length - 1];
+            if (status.startsWith("D")) {
+                addUnique(deleted, filePath);
+            }
+            else {
+                addUnique(modifiedOrAdded, filePath);
+            }
+        }
+    }
+    const status = await git.status();
+    for (const filePath of [...status.created, ...status.modified, ...status.renamed.map((item) => item.to)]) {
+        addUnique(modifiedOrAdded, filePath);
+    }
+    for (const filePath of status.deleted) {
+        addUnique(deleted, filePath);
+    }
+    return {
+        modifiedOrAdded: [...modifiedOrAdded].sort(),
+        deleted: [...deleted].sort()
+    };
+}
+async function getCurrentCommit(repoPath) {
+    const git = (0, simple_git_1.default)(repoPath);
+    try {
+        return (await git.revparse(["HEAD"])).trim();
+    }
+    catch {
+        return "uncommitted";
+    }
+}

package/dist/utils/hashing.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashFileContent = hashFileContent;
+const node_crypto_1 = require("node:crypto");
+function hashFileContent(fileContent) {
+    return (0, node_crypto_1.createHash)("md5").update(fileContent, "utf8").digest("hex");
+}

package/dist/utils/llm.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateFunctionalSummary = generateFunctionalSummary;
+exports.promptLlm = promptLlm;
+exports.generateEmbeddings = generateEmbeddings;
+const openai_1 = __importDefault(require("openai"));
+function createClient(config) {
+    return {
+        client: new openai_1.default({ apiKey: config.apiKey, baseURL: config.baseURL }),
+        model: config.model
+    };
+}
+async function generateFunctionalSummary(fileName, codeContent, config) {
+    const { client, model } = createClient(config);
+    const response = await client.chat.completions.create({
+        model,
+        temperature: 0.2,
+        messages: [
+            {
+                role: "system",
+                content: "Explain what this code does for non-technical stakeholders. Focus on business behavior, user impact, rules, data movement, and visible outcomes. Use plain English, avoid jargon, and provide zero conversational preamble."
+            },
+            {
+                role: "user",
+                content: `File: ${fileName}\n\nCode:\n${codeContent}`
+            }
+        ]
+    });
+    return response.choices[0]?.message?.content?.trim() || "No business behavior summary was returned.";
+}
+async function promptLlm(prompt, config) {
+    const { client, model } = createClient(config);
+    const response = await client.chat.completions.create({
+        model,
+        temperature: 0.2,
+        messages: [
+            {
+                role: "user",
+                content: prompt
+            }
+        ]
+    });
+    return response.choices[0]?.message?.content?.trim() || "No response was returned.";
+}
+async function generateEmbeddings(texts, config) {
+    const baseURL = config.baseURL.replace(/\/embeddings\/?$/, "");
+    const client = new openai_1.default({ apiKey: config.apiKey, baseURL });
+    const response = await client.embeddings.create({
+        model: config.model,
+        input: texts
+    });
+    return response.data.map((item) => item.embedding);
+}

package/dist/utils/paths.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDiffdocBaseDir = getDiffdocBaseDir;
+exports.resolveDiffdocArtifactPath = resolveDiffdocArtifactPath;
+const node_path_1 = __importDefault(require("node:path"));
+function getDiffdocBaseDir(baseDir) {
+    return node_path_1.default.resolve(process.cwd(), baseDir);
+}
+function resolveDiffdocArtifactPath(filePath, baseDir) {
+    if (node_path_1.default.isAbsolute(filePath)) {
+        return filePath;
+    }
+    return node_path_1.default.resolve(getDiffdocBaseDir(baseDir), filePath);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "diffdoc",
+  "version": "0.1.0",
+  "description": "Translate repository code shifts into plain-English business context",
+  "license": "MIT",
+  "author": "Christopher Sullivan",
+  "homepage": "https://github.com/sullyTheDev/diffdoc#readme",
+  "bugs": {
+    "url": "https://github.com/sullyTheDev/diffdoc/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sullyTheDev/diffdoc.git"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "bin": {
+    "diffdoc": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    ".diffdocrc.example"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "start": "tsc && node ./dist/index.js",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "openai": "^4.28.0",
+    "simple-git": "^3.24.0",
+    "vectra": "^0.14.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "typescript": "^5.3.3"
+  }
+}