diffdoc 0.1.0 → 0.1.1

package/README.md

@@ -36,6 +36,7 @@ Package scripts can call the installed binary:
   "scripts": {
     "diffdoc:summarize": "diffdoc summarize",
     "diffdoc:embed": "diffdoc embed",
+    "diffdoc:search": "diffdoc search",
     "diffdoc:query": "diffdoc query"
   }
 }
@@ -76,6 +77,29 @@ Example config with all supported keys:
 
 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`.
 
+## Manifest-First Design
+
+DiffDoc separates summarization from embedding. The `summarize` command writes all generated file summaries to `manifest.json` under `baseDir`, usually `./.diffdoc/manifest.json`.
+
+The manifest is plain JSON and contains one entry per tracked file:
+
+```json
+{
+  "lastSyncedCommit": "string-hash",
+  "files": {
+    "src/example.ts": {
+      "hash": "md5-string",
+      "summaryText": "Plain-English explanation text here.",
+      "rawCodeSnapshot": "Full code text here..."
+    }
+  }
+}
+```
+
+Because the summaries are stored independently, users do not have to embed immediately. They can review, archive, transform, or embed the manifest later using their preferred vectorization model and storage solution.
+
+DiffDoc includes `diffdoc embed` as a built-in convenience path for creating a local Vectra index, but the manifest can also be consumed by other tools such as custom OpenAI-compatible embedding pipelines, hosted vector databases, local search systems, or internal documentation workflows.
+
 ## Commands
 
 Summarize a repository into `./.diffdoc/manifest.json`:
@@ -96,13 +120,25 @@ Embed the manifest into a local Vectra index at `./.diffdoc/vectra`:
 diffdoc embed
 ```
 
-Ask a question using retrieved embedded context:
+Search the local Vectra index and print raw matches:
+
+```bash
+diffdoc search "How does this project process changed files?"
+```
+
+Include retrieved code snapshots in search results:
+
+```bash
+diffdoc search "How does embedding work?" --top 3 --code
+```
+
+Ask a question and have the configured chat model answer using retrieved embedded context:
 
 ```bash
 diffdoc query "How does this project process changed files?"
 ```
 
-Include retrieved code snapshots after the answer:
+Include retrieved code snapshots after the generated answer:
 
 ```bash
 diffdoc query "How does embedding work?" --top 3 --code
@@ -133,6 +169,7 @@ Typical usage is:
 ```bash
 diffdoc summarize --path . --mode all
 diffdoc embed
+diffdoc search "What files explain the summarization flow?"
 diffdoc query "What business behavior does this repository implement?"
 ```
 
@@ -146,8 +183,10 @@ diffdoc embed
 ## Notes
 
 - Node.js `>=22` is required because Vectra requires it.
-- `.diffdoc/` and `.diffdocrc` are ignored by git by default.
+- This repository ignores `.diffdoc/vectra` and `.diffdocrc`; add similar entries to your project's `.gitignore` if you do not want generated indexes or local config committed. The manifest at `.diffdoc/manifest.json` is not ignored by this repository.
+- 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.
+- `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/query.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runQuery = runQuery;
+exports.runSearch = runSearch;
 const vectra_1 = require("vectra");
 const llm_1 = require("../utils/llm");
 const embed_1 = require("./embed");
@@ -67,3 +68,29 @@ async function runQuery(message, options, config) {
         }
     }
 }
+async function runSearch(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;
+    }
+    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/index.js

@@ -70,7 +70,7 @@ addChatOptions(addBaseOptions(program
 });
 addEmbeddingOptions(addChatOptions(addBaseOptions(program
     .command("query"))))
-    .description("Search the local Vectra index with a natural-language question")
+    .description("Answer a question using retrieved local Vectra context")
     .argument("<message...>", "question or search text")
     .option("--top <count>", "number of matches to return", "5")
     .option("--code", "include code snapshots in results", false)
@@ -84,6 +84,22 @@ addEmbeddingOptions(addChatOptions(addBaseOptions(program
         process.exit(1);
     }
 });
+addCloudEndpointAndKeyOptions(addEmbeddingOptions(addBaseOptions(program
+    .command("search"))))
+    .description("Search the local Vectra index and print raw matches")
+    .argument("<message...>", "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, { embeddings: true });
+        await (0, query_1.runSearch)(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")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffdoc",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Translate repository code shifts into plain-English business context",
   "license": "MIT",
   "author": "Christopher Sullivan",