diffdoc 0.3.0 → 0.4.1

package/.diffdocrc.example

@@ -8,6 +8,7 @@
   "cloudLlmEndpoint": "https://api.openai.com/v1",
   "cloudChatModel": "gpt-4o-mini",
   "cloudEmbedModel": "text-embedding-3-small",
+  "embedBatchSize": 25,
   "openaiApiKey": "",
   "includeGlobs": [],
   "excludeGlobs": [],

package/README.md

@@ -34,7 +34,9 @@ Package scripts can call the installed binary:
 ```json
 {
   "scripts": {
+    "diffdoc:init": "diffdoc init",
     "diffdoc:summarize": "diffdoc summarize",
+    "diffdoc:status": "diffdoc status",
     "diffdoc:embed": "diffdoc embed",
     "diffdoc:search": "diffdoc search",
     "diffdoc:query": "diffdoc query",
@@ -114,6 +116,26 @@ DiffDoc includes `diffdoc embed` as a built-in convenience path for creating a l
 
 ## Commands
 
+Initialize DiffDoc configuration for a repository:
+
+```bash
+diffdoc init
+```
+
+Use defaults without prompts:
+
+```bash
+diffdoc init --yes
+```
+
+Choose a provider and overwrite an existing config file:
+
+```bash
+diffdoc init --provider cloud --force
+```
+
+`init` creates or updates repo setup files, appends missing `.gitignore` entries, and prints next commands. It does not run `summarize` or `embed`.
+
 Summarize a repository into `./.diffdoc/manifest.json`:
 
 ```bash
@@ -138,12 +160,42 @@ Add include/exclude filters at runtime:
 diffdoc summarize --path . --mode all --include-glob "src/**/*.ts" --exclude-glob "**/*.test.ts"
 ```
 
+Emit a CI-friendly JSON summarize report:
+
+```bash
+diffdoc summarize --path . --mode delta --json
+```
+
+Inspect manifest-relative artifact freshness:
+
+```bash
+diffdoc status
+```
+
+Use a custom manifest path under `--base-dir`:
+
+```bash
+diffdoc status --manifest manifest.json
+```
+
+Emit CI-friendly JSON output:
+
+```bash
+diffdoc status --json
+```
+
 Embed the manifest into a local Vectra index at `./.diffdoc/vectra`:
 
 ```bash
 diffdoc embed
 ```
 
+Limit how many summary documents are sent per embeddings request:
+
+```bash
+diffdoc embed --embed-batch-size 20
+```
+
 Force full index rebuild:
 
 ```bash
@@ -174,12 +226,6 @@ Include retrieved code snapshots after the generated answer:
 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
@@ -259,7 +305,11 @@ Run `diffdoc summarize` and `diffdoc embed` before using the MCP server, otherwi
 - Manifest schema is currently `schemaVersion: 2`; older manifest shapes are not auto-migrated.
 - Commit `.diffdoc/manifest.json` when using delta workflows. Delta summarization reads the previous manifest state to decide which changed files need fresh summaries.
 - `summarize` requires a configured chat model.
-- `embed` requires a configured embedding model.
+- `summarize` prints run progress and final totals (`scanned`, `skipped`, `updated`, `failed`, `pruned`).
+- `summarize --json` prints a single machine-readable run report to stdout for CI parsing.
+- `status` does not require a configured chat or embedding model.
+- `status --json` prints a machine-readable report with summary and index freshness details.
+- `embed` requires a configured embedding model. Use `embedBatchSize` in `.diffdocrc`, `DIFFDOC_EMBED_BATCH_SIZE`, or `--embed-batch-size` to tune how many summary documents are sent per embeddings request.
 - `search` requires a configured embedding model and returns raw retrieval results without calling the chat 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

@@ -111,30 +111,31 @@ async function runEmbed(options, config) {
         console.log(`Index is already up to date at ${indexPath}.`);
         return;
     }
-    const embeddings = toUpsert.length > 0
-        ? await (0, llm_1.generateEmbeddings)(toUpsert.map((item) => item.document), config.embeddings)
-        : [];
     await index.beginUpdate();
     try {
-        for (let i = 0; i < toUpsert.length; i += 1) {
-            const item = toUpsert[i];
-            const metadata = item.rawCodeSnapshot
-                ? {
-                    filePath: item.filePath,
-                    hash: item.hash,
-                    summaryText: item.summaryText,
-                    rawCodeSnapshot: item.rawCodeSnapshot
-                }
-                : {
-                    filePath: item.filePath,
-                    hash: item.hash,
-                    summaryText: item.summaryText
-                };
-            await index.upsertItem({
-                id: item.filePath,
-                vector: embeddings[i],
-                metadata
-            });
+        for (let start = 0; start < toUpsert.length; start += config.embeddings.batchSize) {
+            const batch = toUpsert.slice(start, start + config.embeddings.batchSize);
+            const embeddings = await (0, llm_1.generateEmbeddings)(batch.map((item) => item.document), config.embeddings);
+            for (let i = 0; i < batch.length; i += 1) {
+                const item = batch[i];
+                const metadata = item.rawCodeSnapshot
+                    ? {
+                        filePath: item.filePath,
+                        hash: item.hash,
+                        summaryText: item.summaryText,
+                        rawCodeSnapshot: item.rawCodeSnapshot
+                    }
+                    : {
+                        filePath: item.filePath,
+                        hash: item.hash,
+                        summaryText: item.summaryText
+                    };
+                await index.upsertItem({
+                    id: item.filePath,
+                    vector: embeddings[i],
+                    metadata
+                });
+            }
         }
         for (const itemId of toDelete) {
             await index.deleteItem(itemId);

package/dist/commands/init.js

@@ -0,0 +1,221 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const promises_2 = require("node:readline/promises");
+const node_process_1 = require("node:process");
+const DEFAULT_CONFIG = {
+    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: "",
+    includeGlobs: [],
+    excludeGlobs: [],
+    ignoreFile: ".diffdocignore"
+};
+function parseProvider(value, fallback) {
+    const provider = value || fallback;
+    if (provider !== "local" && provider !== "cloud") {
+        throw new Error('Invalid init provider. Expected "local" or "cloud".');
+    }
+    return provider;
+}
+function parseCsv(value) {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function toDisplayPath(filePath) {
+    return filePath.split(node_path_1.default.sep).join("/");
+}
+function resolveRepoPath(filePath) {
+    return node_path_1.default.resolve(process.cwd(), filePath);
+}
+function relativeToRepo(absolutePath) {
+    const relative = node_path_1.default.relative(process.cwd(), absolutePath) || ".";
+    return toDisplayPath(relative);
+}
+function normalizeRepoPattern(value) {
+    return toDisplayPath(value.trim())
+        .replace(/^\.\//, "")
+        .replace(/\/+/g, "/")
+        .replace(/\/$/, "");
+}
+async function fileExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readExistingConfig(configPath) {
+    try {
+        const parsed = JSON.parse(await promises_1.default.readFile(configPath, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+}
+async function promptText(rl, question, fallback) {
+    const suffix = fallback ? ` (${fallback})` : "";
+    const answer = (await rl.question(`${question}${suffix}: `)).trim();
+    return answer || fallback;
+}
+async function promptBoolean(rl, question, fallback) {
+    const suffix = fallback ? "Y/n" : "y/N";
+    const answer = (await rl.question(`${question} (${suffix}): `)).trim().toLowerCase();
+    if (!answer)
+        return fallback;
+    return answer === "y" || answer === "yes";
+}
+async function buildInteractiveConfig(options, existing) {
+    const rl = (0, promises_2.createInterface)({ input: node_process_1.stdin, output: node_process_1.stdout });
+    try {
+        const fallbackProvider = parseProvider(existing.aiProvider, "local");
+        const provider = parseProvider(options.provider || await promptText(rl, "AI provider: local or cloud", fallbackProvider), fallbackProvider);
+        const baseDir = options.baseDir || await promptText(rl, "DiffDoc artifact directory", existing.baseDir || DEFAULT_CONFIG.baseDir);
+        const ignoreFile = await promptText(rl, "Ignore file path", existing.ignoreFile || DEFAULT_CONFIG.ignoreFile);
+        const includeGlobs = parseCsv(await promptText(rl, "Include globs, comma-separated", (existing.includeGlobs || []).join(",")));
+        const excludeGlobs = parseCsv(await promptText(rl, "Exclude globs, comma-separated", (existing.excludeGlobs || []).join(",")));
+        const config = {
+            ...DEFAULT_CONFIG,
+            ...existing,
+            baseDir,
+            aiProvider: provider,
+            ignoreFile,
+            includeGlobs,
+            excludeGlobs
+        };
+        if (provider === "local") {
+            config.localLlmEndpoint = await promptText(rl, "Local chat endpoint", config.localLlmEndpoint || DEFAULT_CONFIG.localLlmEndpoint);
+            config.localChatModel = await promptText(rl, "Local chat model", config.localChatModel || DEFAULT_CONFIG.localChatModel);
+            config.localEmbedEndpoint = await promptText(rl, "Local embedding endpoint", config.localEmbedEndpoint || DEFAULT_CONFIG.localEmbedEndpoint);
+            config.localEmbedModel = await promptText(rl, "Local embedding model", config.localEmbedModel || DEFAULT_CONFIG.localEmbedModel);
+        }
+        else {
+            config.cloudLlmEndpoint = await promptText(rl, "Cloud OpenAI-compatible endpoint", config.cloudLlmEndpoint || DEFAULT_CONFIG.cloudLlmEndpoint);
+            config.cloudChatModel = await promptText(rl, "Cloud chat model", config.cloudChatModel || DEFAULT_CONFIG.cloudChatModel);
+            config.cloudEmbedModel = await promptText(rl, "Cloud embedding model", config.cloudEmbedModel || DEFAULT_CONFIG.cloudEmbedModel);
+            if (await promptBoolean(rl, "Store OPENAI_API_KEY in config file", false)) {
+                config.openaiApiKey = await promptText(rl, "OpenAI-compatible API key", config.openaiApiKey || "");
+            }
+            else {
+                config.openaiApiKey = "";
+            }
+        }
+        return config;
+    }
+    finally {
+        rl.close();
+    }
+}
+function buildYesConfig(options, existing) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...existing,
+        baseDir: options.baseDir || existing.baseDir || DEFAULT_CONFIG.baseDir,
+        aiProvider: parseProvider(options.provider || existing.aiProvider, "local"),
+        openaiApiKey: ""
+    };
+}
+async function writeJsonFile(filePath, value, summary, force) {
+    const exists = await fileExists(filePath);
+    if (exists && !force) {
+        summary.skipped.push(relativeToRepo(filePath));
+        summary.warnings.push(`${relativeToRepo(filePath)} already exists; pass --force to overwrite.`);
+        return;
+    }
+    await promises_1.default.mkdir(node_path_1.default.dirname(filePath), { recursive: true });
+    await promises_1.default.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    (exists ? summary.updated : summary.created).push(relativeToRepo(filePath));
+}
+function buildStarterIgnore(baseDir) {
+    const normalizedBaseDir = normalizeRepoPattern(baseDir);
+    return [
+        "# DiffDoc ignore patterns",
+        "node_modules/**",
+        ".git/**",
+        `${normalizedBaseDir}/**`,
+        "dist/**",
+        ""
+    ].join("\n");
+}
+async function createIgnoreFile(ignorePath, config, summary) {
+    if (await fileExists(ignorePath)) {
+        summary.skipped.push(relativeToRepo(ignorePath));
+        return;
+    }
+    await promises_1.default.writeFile(ignorePath, buildStarterIgnore(config.baseDir), "utf8");
+    summary.created.push(relativeToRepo(ignorePath));
+}
+function buildGitignoreEntries(configPath, config) {
+    const configRelative = normalizeRepoPattern(relativeToRepo(configPath));
+    const baseDir = normalizeRepoPattern(config.baseDir);
+    return [`${baseDir}/vectra/`, configRelative];
+}
+async function updateGitignore(configPath, config, summary) {
+    const gitignorePath = resolveRepoPath(".gitignore");
+    const entries = buildGitignoreEntries(configPath, config);
+    let existing = "";
+    let exists = false;
+    try {
+        existing = await promises_1.default.readFile(gitignorePath, "utf8");
+        exists = true;
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code !== "ENOENT")
+            throw error;
+    }
+    const existingLines = new Set(existing.split(/\r?\n/).map(normalizeRepoPattern).filter(Boolean));
+    const missing = entries.filter((entry) => !existingLines.has(normalizeRepoPattern(entry)));
+    if (missing.length === 0) {
+        summary.skipped.push(".gitignore");
+        return;
+    }
+    const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
+    await promises_1.default.writeFile(gitignorePath, `${existing}${prefix}${missing.join("\n")}\n`, "utf8");
+    (exists ? summary.updated : summary.created).push(".gitignore");
+}
+function printList(label, values) {
+    console.log(`${label}: ${values.length > 0 ? values.join(", ") : "none"}`);
+}
+async function runInit(options) {
+    const summary = { created: [], updated: [], skipped: [], warnings: [] };
+    const configPath = resolveRepoPath(options.config || ".diffdocrc");
+    const existingConfig = await readExistingConfig(configPath);
+    const config = options.yes
+        ? buildYesConfig(options, existingConfig)
+        : await buildInteractiveConfig(options, existingConfig);
+    const ignorePath = resolveRepoPath(config.ignoreFile || ".diffdocignore");
+    await writeJsonFile(configPath, config, summary, options.force);
+    await createIgnoreFile(ignorePath, config, summary);
+    await updateGitignore(configPath, config, summary);
+    console.log("DiffDoc init complete.");
+    console.log("");
+    console.log("Init changes:");
+    printList("Created", summary.created);
+    printList("Updated", summary.updated);
+    printList("Skipped", summary.skipped);
+    printList("Warnings", summary.warnings);
+    console.log("");
+    console.log("Next commands:");
+    console.log("1. diffdoc summarize --path . --mode all");
+    console.log("2. diffdoc embed");
+    console.log("3. diffdoc status");
+}

package/dist/commands/status.js

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStatus = runStatus;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const vectra_1 = require("vectra");
+const embed_1 = require("./embed");
+const artifacts_1 = require("../types/artifacts");
+const paths_1 = require("../utils/paths");
+function getSummaryDir(manifestPath) {
+    return node_path_1.default.resolve(node_path_1.default.dirname(manifestPath), "summaries");
+}
+async function readManifest(manifestPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await promises_1.default.readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === "ENOENT") {
+            throw new Error(`Manifest not found: ${manifestPath}. Run \"diffdoc summarize\" first.`);
+        }
+        throw error;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Invalid manifest JSON in ${manifestPath}. Expected an object.`);
+    }
+    const manifest = parsed;
+    if (manifest.schemaVersion !== artifacts_1.MANIFEST_SCHEMA_VERSION) {
+        throw new Error(`Unsupported manifest schema in ${manifestPath}. Expected schemaVersion ${artifacts_1.MANIFEST_SCHEMA_VERSION}.`);
+    }
+    return {
+        schemaVersion: artifacts_1.MANIFEST_SCHEMA_VERSION,
+        lastSyncedCommit: typeof manifest.lastSyncedCommit === "string" ? manifest.lastSyncedCommit : "",
+        files: manifest.files && typeof manifest.files === "object" ? manifest.files : {}
+    };
+}
+async function getSummaryStats(manifestPath, manifest) {
+    const summaryDir = getSummaryDir(manifestPath);
+    let entries = [];
+    try {
+        entries = await promises_1.default.readdir(summaryDir);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    const summaryHashes = new Set(entries.filter((entry) => entry.endsWith(".json")).map((entry) => entry.slice(0, -5)));
+    const manifestHashes = new Set(Object.values(manifest.files));
+    let orphanCount = 0;
+    for (const hash of summaryHashes) {
+        if (!manifestHashes.has(hash)) {
+            orphanCount += 1;
+        }
+    }
+    let missingFromManifestCount = 0;
+    for (const hash of manifestHashes) {
+        if (!summaryHashes.has(hash)) {
+            missingFromManifestCount += 1;
+        }
+    }
+    return {
+        summaryFileCount: summaryHashes.size,
+        orphanCount,
+        missingFromManifestCount
+    };
+}
+async function getIndexFreshness(manifest, config) {
+    const indexPath = (0, embed_1.getVectraIndexPath)(config);
+    const index = new vectra_1.LocalIndex(indexPath);
+    const exists = await index.isIndexCreated();
+    if (!exists) {
+        return {
+            status: "missing",
+            missing: 0,
+            mismatched: 0,
+            extra: 0
+        };
+    }
+    const items = await index.listItems();
+    const indexHashesByPath = new Map();
+    for (const item of items) {
+        if (!item.id || typeof item.id !== "string") {
+            continue;
+        }
+        const hash = item.metadata && typeof item.metadata.hash === "string"
+            ? item.metadata.hash
+            : "";
+        indexHashesByPath.set(item.id, hash);
+    }
+    let missing = 0;
+    let mismatched = 0;
+    for (const [filePath, manifestHash] of Object.entries(manifest.files)) {
+        const indexedHash = indexHashesByPath.get(filePath);
+        if (indexedHash === undefined) {
+            missing += 1;
+            continue;
+        }
+        if (indexedHash !== manifestHash) {
+            mismatched += 1;
+        }
+    }
+    const manifestPathSet = new Set(Object.keys(manifest.files));
+    let extra = 0;
+    for (const filePath of indexHashesByPath.keys()) {
+        if (!manifestPathSet.has(filePath)) {
+            extra += 1;
+        }
+    }
+    return {
+        status: missing === 0 && mismatched === 0 && extra === 0 ? "fresh" : "stale",
+        missing,
+        mismatched,
+        extra
+    };
+}
+function formatSummaryFreshness(stats) {
+    if (stats.missingFromManifestCount === 0) {
+        return "fresh";
+    }
+    return `stale (missing: ${stats.missingFromManifestCount})`;
+}
+function buildStatusReport(manifest, summaryStats, indexFreshness) {
+    return {
+        manifestSchema: manifest.schemaVersion,
+        trackedFileCount: Object.keys(manifest.files).length,
+        summaryFileCount: summaryStats.summaryFileCount,
+        orphanCount: summaryStats.orphanCount,
+        summaryFreshness: {
+            status: summaryStats.missingFromManifestCount === 0 ? "fresh" : "stale",
+            missing: summaryStats.missingFromManifestCount
+        },
+        indexFreshness
+    };
+}
+function formatIndexFreshness(freshness) {
+    if (freshness.status === "missing") {
+        return "missing";
+    }
+    if (freshness.status === "fresh") {
+        return "fresh";
+    }
+    return `stale (missing: ${freshness.missing}, mismatched: ${freshness.mismatched}, extra: ${freshness.extra})`;
+}
+async function runStatus(options, config) {
+    const manifestPath = (0, paths_1.resolveDiffdocArtifactPath)(options.manifest, config.baseDir);
+    const manifest = await readManifest(manifestPath);
+    const summaryStats = await getSummaryStats(manifestPath, manifest);
+    const indexFreshness = await getIndexFreshness(manifest, config);
+    const report = buildStatusReport(manifest, summaryStats, indexFreshness);
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(`manifest schema: ${report.manifestSchema}`);
+    console.log(`tracked files: ${report.trackedFileCount}`);
+    console.log(`summary files: ${report.summaryFileCount}`);
+    console.log(`orphans: ${report.orphanCount}`);
+    console.log(`summary freshness: ${formatSummaryFreshness(summaryStats)}`);
+    console.log(`index freshness: ${formatIndexFreshness(indexFreshness)}`);
+}

package/dist/commands/summarize.js

@@ -182,7 +182,7 @@ async function deleteSummaryIfUnreferenced(summaryDir, hash, refs) {
 async function setManifestPathHash(filePath, newHash, manifest, manifestPath, summaryDir, refs) {
     const previousHash = manifest.files[filePath];
     if (previousHash === newHash) {
-        return;
+        return false;
     }
     if (previousHash) {
         refs.set(previousHash, Math.max((refs.get(previousHash) || 1) - 1, 0));
@@ -193,16 +193,18 @@ async function setManifestPathHash(filePath, newHash, manifest, manifestPath, su
     if (previousHash) {
         await deleteSummaryIfUnreferenced(summaryDir, previousHash, refs);
     }
+    return true;
 }
 async function removeManifestPath(filePath, manifest, manifestPath, summaryDir, refs) {
     const previousHash = manifest.files[filePath];
     if (!previousHash) {
-        return;
+        return false;
     }
     delete manifest.files[filePath];
     refs.set(previousHash, Math.max((refs.get(previousHash) || 1) - 1, 0));
     await writeManifest(manifestPath, manifest);
     await deleteSummaryIfUnreferenced(summaryDir, previousHash, refs);
+    return true;
 }
 async function ensureSummaryAsset(summaryDir, hash, summaryText, rawCodeSnapshot, includeCodeSnapshot) {
     const summaryPath = getSummaryPath(summaryDir, hash);
@@ -245,6 +247,7 @@ async function runSummarize(options, config) {
     if (options.mode !== "all" && options.mode !== "delta") {
         throw new Error('Invalid summarize mode. Expected "all" or "delta".');
     }
+    const startedAt = new Date();
     const commandCwd = process.cwd();
     const repoPath = node_path_1.default.resolve(commandCwd, options.path);
     const manifestPath = (0, paths_1.resolveDiffdocArtifactPath)(options.out, config.baseDir);
@@ -259,13 +262,29 @@ async function runSummarize(options, config) {
         : config.summarize.excludeGlobs.map(normalizeGlobPattern));
     const ignoreFile = options.ignoreFile || config.summarize.ignoreFile;
     const ignorePatterns = compileGlobs(await readIgnorePatterns(repoPath, ignoreFile));
+    const totals = { scanned: 0, skipped: 0, updated: 0, failed: 0, pruned: 0 };
     const failures = [];
+    const isJson = options.json;
+    if (!isJson) {
+        console.log(`Starting summarize run`);
+        console.log(`Mode: ${options.mode}`);
+        console.log(`Repo: ${repoPath}`);
+        console.log(`Manifest: ${manifestPath}`);
+        console.log(`Summaries: ${summaryDir}`);
+        console.log("---");
+    }
     if (options.mode === "all") {
         manifest.files = {};
         refs.clear();
         await writeManifest(manifestPath, manifest);
         const files = await walkCodeFiles(repoPath, includePatterns, excludePatterns, ignorePatterns);
-        for (const filePath of files) {
+        const totalFiles = files.length;
+        if (!isJson) {
+            console.log(`Candidates: ${totalFiles}`);
+        }
+        for (let i = 0; i < files.length; i += 1) {
+            const filePath = files[i];
+            totals.scanned += 1;
             try {
                 const absolutePath = node_path_1.default.join(repoPath, filePath);
                 const rawCodeSnapshot = await promises_1.default.readFile(absolutePath, "utf8");
@@ -278,25 +297,51 @@ async function runSummarize(options, config) {
                 manifest.files[filePath] = hash;
                 refs.set(hash, (refs.get(hash) || 0) + 1);
                 await writeManifest(manifestPath, manifest);
-                console.log(`Summarized ${filePath}`);
+                totals.updated += 1;
+                if (!isJson) {
+                    console.log(`[${i + 1}/${totalFiles}] summarized ${filePath}`);
+                }
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 failures.push({ filePath, message });
-                console.error(`Failed ${filePath}: ${message}`);
+                totals.failed += 1;
+                if (!isJson) {
+                    console.error(`[${i + 1}/${totalFiles}] failed ${filePath}: ${message}`);
+                }
             }
         }
     }
     else {
         const deltas = await (0, git_1.getGitDeltas)(repoPath, manifest.lastSyncedCommit);
+        const totalCandidates = deltas.modifiedOrAdded.length + deltas.deleted.length;
+        if (!isJson) {
+            console.log(`Candidates: ${totalCandidates} (${deltas.modifiedOrAdded.length} modified/added, ${deltas.deleted.length} deleted)`);
+        }
         for (const deletedPath of deltas.deleted) {
-            await removeManifestPath(deletedPath, manifest, manifestPath, summaryDir, refs);
-            console.log(`Pruned ${deletedPath}`);
+            const removed = await removeManifestPath(deletedPath, manifest, manifestPath, summaryDir, refs);
+            if (removed) {
+                totals.pruned += 1;
+            }
+            if (!isJson) {
+                console.log(`pruned ${deletedPath}`);
+            }
         }
-        for (const filePath of deltas.modifiedOrAdded) {
+        for (let i = 0; i < deltas.modifiedOrAdded.length; i += 1) {
+            const filePath = deltas.modifiedOrAdded[i];
+            totals.scanned += 1;
             try {
                 if (!shouldIncludeFile(filePath, includePatterns, excludePatterns, ignorePatterns)) {
-                    await removeManifestPath(filePath, manifest, manifestPath, summaryDir, refs);
+                    const removed = await removeManifestPath(filePath, manifest, manifestPath, summaryDir, refs);
+                    if (removed) {
+                        totals.pruned += 1;
+                    }
+                    else {
+                        totals.skipped += 1;
+                    }
+                    if (!isJson) {
+                        console.log(`[${i + 1}/${deltas.modifiedOrAdded.length}] excluded ${filePath}`);
+                    }
                     continue;
                 }
                 const previousHash = manifest.files[filePath];
@@ -304,6 +349,10 @@ async function runSummarize(options, config) {
                 const rawCodeSnapshot = await promises_1.default.readFile(absolutePath, "utf8");
                 const hash = (0, hashing_1.hashFileContent)(rawCodeSnapshot);
                 if (previousHash === hash) {
+                    totals.skipped += 1;
+                    if (!isJson) {
+                        console.log(`[${i + 1}/${deltas.modifiedOrAdded.length}] unchanged ${filePath}`);
+                    }
                     continue;
                 }
                 const summaryPath = getSummaryPath(summaryDir, hash);
@@ -311,29 +360,77 @@ async function runSummarize(options, config) {
                     const summaryText = await (0, llm_1.generateFunctionalSummary)(filePath, rawCodeSnapshot, config.chat);
                     await ensureSummaryAsset(summaryDir, hash, summaryText, rawCodeSnapshot, options.includeCodeSnapshot);
                 }
-                await setManifestPathHash(filePath, hash, manifest, manifestPath, summaryDir, refs);
-                console.log(`Updated ${filePath}`);
+                const changed = await setManifestPathHash(filePath, hash, manifest, manifestPath, summaryDir, refs);
+                if (changed) {
+                    totals.updated += 1;
+                }
+                else {
+                    totals.skipped += 1;
+                }
+                if (!isJson) {
+                    console.log(`[${i + 1}/${deltas.modifiedOrAdded.length}] updated ${filePath}`);
+                }
             }
             catch (error) {
                 const nodeError = error;
                 if (nodeError.code === "ENOENT") {
-                    await removeManifestPath(filePath, manifest, manifestPath, summaryDir, refs);
+                    const removed = await removeManifestPath(filePath, manifest, manifestPath, summaryDir, refs);
+                    if (removed) {
+                        totals.pruned += 1;
+                    }
+                    else {
+                        totals.skipped += 1;
+                    }
+                    if (!isJson) {
+                        console.log(`[${i + 1}/${deltas.modifiedOrAdded.length}] missing ${filePath}`);
+                    }
                     continue;
                 }
                 const message = error instanceof Error ? error.message : String(error);
                 failures.push({ filePath, message });
-                console.error(`Failed ${filePath}: ${message}`);
+                totals.failed += 1;
+                if (!isJson) {
+                    console.error(`[${i + 1}/${deltas.modifiedOrAdded.length}] failed ${filePath}: ${message}`);
+                }
             }
         }
     }
     manifest.lastSyncedCommit = await (0, git_1.getCurrentCommit)(repoPath);
     await writeManifest(manifestPath, manifest);
     await pruneOrphanedSummaries(summaryDir, manifest);
-    console.log(`Wrote manifest to ${manifestPath}`);
+    const finishedAt = new Date();
+    const durationMs = finishedAt.getTime() - startedAt.getTime();
+    const report = {
+        mode: options.mode,
+        repoPath,
+        manifestPath,
+        summaryDir,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs,
+        totals,
+        failures
+    };
+    if (isJson) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log("---");
+        console.log(`Summarize complete`);
+        console.log(`Scanned: ${totals.scanned}`);
+        console.log(`Updated: ${totals.updated}`);
+        console.log(`Skipped: ${totals.skipped}`);
+        console.log(`Pruned: ${totals.pruned}`);
+        console.log(`Failed: ${totals.failed}`);
+        console.log(`Duration: ${(durationMs / 1000).toFixed(2)}s`);
+        console.log(`Manifest: ${manifestPath}`);
+    }
     if (failures.length > 0) {
-        console.error(`\n${failures.length} file(s) failed during summarization:`);
-        for (const failure of failures) {
-            console.error(`- ${failure.filePath}: ${failure.message}`);
+        if (!isJson) {
+            console.error(`\n${failures.length} file(s) failed during summarization:`);
+            for (const failure of failures) {
+                console.error(`- ${failure.filePath}: ${failure.message}`);
+            }
         }
         throw new Error("Summarization completed with failures.");
     }

package/dist/config.js

@@ -25,6 +25,17 @@ function readListOption(value, envName, fallback = []) {
     }
     return fallback;
 }
+function readPositiveIntegerOption(value, envName, fallback) {
+    const rawValue = value ?? process.env[envName];
+    if (rawValue === undefined || rawValue === "") {
+        return fallback;
+    }
+    const parsed = typeof rawValue === "number" ? rawValue : Number.parseInt(rawValue, 10);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`Invalid ${envName}. Expected a positive integer.`);
+    }
+    return parsed;
+}
 function loadRcFile(configPath) {
     const resolvedPath = node_path_1.default.resolve(process.cwd(), configPath || ".diffdocrc");
     if (!node_fs_1.default.existsSync(resolvedPath)) {
@@ -57,6 +68,7 @@ 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 embedBatchSize = readPositiveIntegerOption(mergedOptions.embedBatchSize, "DIFFDOC_EMBED_BATCH_SIZE", 25);
     const includeGlobs = readListOption(mergedOptions.includeGlobs, "DIFFDOC_INCLUDE_GLOBS");
     const excludeGlobs = readListOption(mergedOptions.excludeGlobs, "DIFFDOC_EXCLUDE_GLOBS");
     const ignoreFile = readOption(mergedOptions.ignoreFile, "DIFFDOC_IGNORE_FILE", ".diffdocignore");
@@ -98,7 +110,8 @@ function buildRuntimeConfig(options, needs = { chat: true, embeddings: true }) {
         embeddings: {
             apiKey,
             baseURL: embedBaseURL,
-            model: embedModel
+            model: embedModel,
+            batchSize: embedBatchSize
         },
         summarize: {
             includeGlobs,

package/dist/index.js

@@ -4,9 +4,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const config_1 = require("./config");
 const embed_1 = require("./commands/embed");
+const init_1 = require("./commands/init");
 const query_1 = require("./commands/query");
+const status_1 = require("./commands/status");
 const summarize_1 = require("./commands/summarize");
-const llm_1 = require("./utils/llm");
 const program = new commander_1.Command();
 function collectOption(value, previous) {
     previous.push(value);
@@ -30,7 +31,8 @@ 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");
+        .option("--cloud-embed-model <model>", "cloud embedding model name")
+        .option("--embed-batch-size <count>", "number of summary documents to send per embeddings request");
 }
 function addCloudEndpointAndKeyOptions(command) {
     return command
@@ -40,7 +42,24 @@ function addCloudEndpointAndKeyOptions(command) {
 program
     .name("diffdoc")
     .description("Translate repository code shifts into plain-English business context")
-    .version("0.1.0");
+    .version("0.4.1");
+program
+    .command("init")
+    .description("Initialize DiffDoc configuration for this repository")
+    .option("--yes", "use defaults without prompting", false)
+    .option("--provider <provider>", "AI provider: local or cloud")
+    .option("--config <path>", "path to .diffdocrc JSON config file")
+    .option("--base-dir <path>", "DiffDoc artifact directory")
+    .option("--force", "overwrite existing config file", false)
+    .action(async (options) => {
+    try {
+        await (0, init_1.runInit)(options);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 addChatOptions(addBaseOptions(program
     .command("summarize")))
     .description("Summarize repository code into a portable JSON manifest")
@@ -48,6 +67,7 @@ addChatOptions(addBaseOptions(program
     .option("--out <path>", "manifest output path under --base-dir", "manifest.json")
     .option("--mode <mode>", "summarization mode: all or delta", "all")
     .option("--include-code-snapshot", "store raw code in summary assets", false)
+    .option("--json", "print summarize report as JSON for CI", false)
     .option("--include-glob <pattern>", "include glob pattern (repeatable)", collectOption, [])
     .option("--exclude-glob <pattern>", "exclude glob pattern (repeatable)", collectOption, [])
     .option("--ignore-file <path>", "path to ignore pattern file relative to --path")
@@ -59,6 +79,7 @@ addChatOptions(addBaseOptions(program
             out: options.out,
             mode: options.mode,
             includeCodeSnapshot: options.includeCodeSnapshot,
+            json: options.json,
             includeGlobs: options.includeGlob,
             excludeGlobs: options.excludeGlob,
             ignoreFile: options.ignoreFile
@@ -69,21 +90,6 @@ addChatOptions(addBaseOptions(program
         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("Answer a question using retrieved local Vectra context")
@@ -131,6 +137,21 @@ addCloudEndpointAndKeyOptions(addEmbeddingOptions(addBaseOptions(program
         process.exit(1);
     }
 });
+addBaseOptions(program
+    .command("status"))
+    .description("Show manifest and index sync status")
+    .option("--manifest <path>", "manifest input path under --base-dir", "manifest.json")
+    .option("--json", "print status as JSON for CI", false)
+    .action(async (options) => {
+    try {
+        const config = (0, config_1.buildRuntimeConfig)(options, { embeddings: false, chat: false });
+        await (0, status_1.runStatus)({ manifest: options.manifest, json: options.json }, 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/services/retrieval.js

@@ -67,7 +67,7 @@ async function answerFromIndex(question, topK, config) {
             results: []
         };
     }
-    const answer = await (0, llm_1.promptLlm)(buildAnswerPrompt(question, results), config.chat);
+    const answer = await (0, llm_1.generateAnswer)(buildAnswerPrompt(question, results), config.chat);
     return {
         answer,
         sources: results.map((result) => ({ filePath: result.filePath, score: result.score })),

package/dist/utils/llm.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateFunctionalSummary = generateFunctionalSummary;
-exports.promptLlm = promptLlm;
+exports.generateAnswer = generateAnswer;
 exports.generateEmbeddings = generateEmbeddings;
 const openai_1 = __importDefault(require("openai"));
 function createClient(config) {
@@ -31,7 +31,7 @@ async function generateFunctionalSummary(fileName, codeContent, config) {
     });
     return response.choices[0]?.message?.content?.trim() || "No business behavior summary was returned.";
 }
-async function promptLlm(prompt, config) {
+async function generateAnswer(prompt, config) {
     const { client, model } = createClient(config);
     const response = await client.chat.completions.create({
         model,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffdoc",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Translate repository code shifts into plain-English business context",
   "license": "MIT",
   "author": "Christopher Sullivan",
@@ -15,8 +15,8 @@
   "type": "commonjs",
   "main": "dist/index.js",
   "bin": {
-    "diffdoc": "./dist/index.js",
-    "diffdoc-mcp": "./dist/mcp.js"
+    "diffdoc": "dist/index.js",
+    "diffdoc-mcp": "dist/mcp.js"
   },
   "files": [
     "dist",