@ninjaxtools/slopdex 0.8.0 → 0.10.0

package/dist/cli.js

@@ -346,6 +346,13 @@ function pythonIsMethod(node) {
   const definition = node.parent?.type === "decorated_definition" ? node.parent : node;
   return definition.parent?.parent?.type === "class_definition";
 }
+function pythonDocstring(body, content) {
+  const statement = body?.namedChildren[0];
+  if (statement?.type !== "expression_statement") return null;
+  const value = statement.namedChildren[0];
+  if (value?.type !== "string" && value?.type !== "concatenated_string") return null;
+  return content.slice(value.startIndex, value.endIndex);
+}
 function goReceiver(node) {
   let type = node.childForFieldName("receiver")?.namedChildren[0]?.childForFieldName("type");
   while (type?.type === "pointer_type") type = type.namedChildren[0] ?? null;
@@ -359,12 +366,14 @@ function collectNativeCallables(root, content, language) {
     if ((!body || body.isMissing) && !node.hasError) return false;
     const sourceNode = language === "python" && node.parent?.type === "decorated_definition" ? node.parent : node;
     const header = content.slice(node.startIndex, body?.startIndex ?? node.endIndex).trimEnd();
+    const documentation = language === "python" && body ? pythonDocstring(body, content) : null;
     candidates.push({
       node: sourceNode,
       name,
       kind,
       scope,
-      signature: bound ? `${name} = ${header}` : header
+      signature: bound ? `${name} = ${header}` : header,
+      ...documentation ? { documentation } : {}
     });
     if (body) walk2(body, [...scope, name]);
     return true;
@@ -789,7 +798,7 @@ function extractCallables(relativePath, content) {
   const errors = parseDiagnostics(tree.rootNode, content, relativePath, language, candidates);
   const occurrences = /* @__PURE__ */ new Map();
   const callables = [];
-  for (const { node, name, kind, scope, signature: candidateSignature } of candidates) {
+  for (const { node, name, kind, scope, signature: candidateSignature, documentation } of candidates) {
     const qualifiedName = [...scope, name].join(".");
     const baseIdentity = `${relativePath}\0${qualifiedName}\0${kind}`;
     const occurrence = occurrences.get(baseIdentity) ?? 0;
@@ -804,6 +813,8 @@ function extractCallables(relativePath, content) {
         `kind: ${kind}`,
         `symbol: ${qualifiedName}`,
         signature ? `signature: ${signature}` : null,
+        documentation ? `documentation:
+${documentation}` : null,
         "source:",
         source
       ].filter((value) => value !== null).join("\n");
@@ -1105,6 +1116,13 @@ var IndexDatabase = class {
       this.#setMetadata("generation", String(expectedGeneration + 1));
     });
   }
+  disableSummaries() {
+    if (!this.summariesEnabled()) return;
+    this.#transaction(() => {
+      this.#setMetadata("summaries_enabled", "false");
+      this.#setMetadata("generation", String(this.getGeneration() + 1));
+    });
+  }
   getWorkingTreeFiles() {
     return this.#db.prepare(`
       SELECT path, previous_path AS previousPath
@@ -1988,7 +2006,7 @@ var CodeIndex = class {
   async #attachEmbeddings(files, signal) {
     if (this.#database.summariesEnabled()) {
       if (JSON.stringify(this.#database.summaryProfile()) !== JSON.stringify(this.summaryProvider.profile)) {
-        throw new CodeIndexError("Summary provider or model differs from this index; run use-summaries (useSummaries() in the library) with the new provider first.");
+        throw new CodeIndexError("Summary provider or model differs from this index; run summaries enable (useSummaries() in the library) with the new provider first.");
       }
       await this.#attachSummaries(files, signal);
     }
@@ -2087,8 +2105,12 @@ var CodeIndex = class {
     }))), this.summaryProvider.profile, generation);
     return { summariesCreated, summariesEnabled: true };
   }
+  disableSummaries() {
+    this.#database.disableSummaries();
+    return { summariesCreated: 0, summariesEnabled: false };
+  }
   async searchSummary(options) {
-    if (!this.#database.summariesEnabled()) throw new CodeIndexError("Summaries are not enabled; run use-summaries first.");
+    if (!this.#database.summariesEnabled()) throw new CodeIndexError("Summaries are not enabled; run summaries enable first.");
     if (!options.query.trim()) throw new CodeIndexError("query must not be empty.");
     const limit = options.limit ?? 10;
     assertPositiveInteger(limit, "limit");
@@ -2225,7 +2247,7 @@ function normalizeProfile(profile) {
     provider: profile.provider,
     model: profile.model,
     dimensions: profile.dimensions,
-    strategyVersion: profile.strategyVersion ?? "callable-v1"
+    strategyVersion: profile.strategyVersion ?? "callable-v2"
   };
 }
 function emptyStats(checkpoint) {
@@ -2602,7 +2624,7 @@ var JinaEmbeddingProvider = class {
       provider: "jina",
       model,
       dimensions,
-      strategyVersion: "callable-v1:code-query-passage"
+      strategyVersion: "callable-v2:code-query-passage"
     };
     this.#url = options.baseUrl ?? "https://api.jina.ai/v1/embeddings";
   }
@@ -2652,7 +2674,7 @@ var OpenAIEmbeddingProvider = class {
     const model = options.model ?? "text-embedding-3-large";
     const dimensions = options.dimensions ?? 3072;
     if (!Number.isInteger(dimensions) || dimensions < 1) throw new Error("dimensions must be a positive integer.");
-    this.profile = { provider: "openai", model, dimensions, strategyVersion: "callable-v1" };
+    this.profile = { provider: "openai", model, dimensions, strategyVersion: "callable-v2" };
     this.#url = `${(options.baseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "")}/embeddings`;
   }
   embedDocuments(inputs, options) {
@@ -2907,6 +2929,7 @@ var parsed = (() => {
         "force-reindex": { type: "boolean", default: false },
         "no-reindex": { type: "boolean", default: false },
         "ignore-errors": { type: "boolean", default: false },
+        version: { type: "boolean", default: false },
         help: { type: "boolean", short: "h", default: false }
       }
     });
@@ -2917,6 +2940,13 @@ var parsed = (() => {
   }
 })();
 var [command, ...positionals] = parsed.positionals;
+var summariesAction = command === "summaries" ? positionals[0] : void 0;
+if (parsed.values.version) {
+  const version = true ? "0.10.0" : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  process.stdout.write(`${version}
+`);
+  process.exit(0);
+}
 var diagnosticIndexes = /* @__PURE__ */ new Set();
 process.on("exit", () => {
   if (parsed.values["ignore-errors"]) return;
@@ -2955,7 +2985,7 @@ async function main() {
   if (command === "index-errors") {
     const indexPath = path10.resolve(parsed.values.index ?? config.indexPath ?? path10.join(rootDir, ".slopdex/index.sqlite"));
     const errors = existsSync(indexPath) ? readIndexErrors(indexPath) : [];
-    if (outputFormat("json") === "summary") {
+    if (outputFormat("summary") === "summary") {
       process.stdout.write(errors.length === 0 ? "No indexing errors.\n" : `${errors.map(
         (error) => `${error.path}${error.startLine === null ? "" : `:${error.startLine}:${error.startColumn}`} ${error.qualifiedName ? `:: ${error.qualifiedName} ` : ""}[${error.code}]
   ${error.message}`
@@ -2981,12 +3011,15 @@ async function main() {
   const updateTarget = command === "update-git" ? parsed.values.target ?? "HEAD" : "HEAD";
   const { summaryProvider: _summaryProvider, ...refreshOptions } = indexOptions;
   const updateStats = await ensureIndexUpdated(
-    command === "use-summaries" ? refreshOptions : indexOptions,
+    command === "summaries" && summariesAction === "enable" ? refreshOptions : indexOptions,
     "index",
     updateTarget,
     parsed.values["rebuild-on-divergence"],
     parsed.values["force-reindex"],
-    parsed.values["no-reindex"]
+    parsed.values["no-reindex"],
+    command === "summaries" && summariesAction === "disable" ? (refreshIndex2) => {
+      refreshIndex2.disableSummaries();
+    } : void 0
   );
   const index = new CodeIndex(indexOptions);
   try {
@@ -3006,22 +3039,23 @@ async function main() {
         printJson(updateStats);
         break;
       }
-      case "use-summaries":
-        printJson(await index.useSummaries());
+      case "summaries":
+        printJson(summariesAction === "enable" ? await index.useSummaries() : index.disableSummaries());
         break;
       case "search":
       case "search-summary": {
         const query = positionals.join(" ").trim();
         if (!query) throw new CodeIndexError(`${command} requires a query.`);
         const threshold = similarityThreshold();
+        const nameRegex = qualifiedNameRegex();
         const results = await (command === "search-summary" ? index.searchSummary.bind(index) : index.similaritySearch.bind(index))({
           query,
-          ...parsed.values.regexp !== void 0 ? { nameRegex: parsed.values.regexp } : {},
+          ...nameRegex !== void 0 ? { nameRegex } : {},
           limit: numberOption(parsed.values.limit, 10, "limit"),
           minSimilarity: threshold.min,
           ...threshold.max !== void 0 ? { maxSimilarity: threshold.max } : {}
         });
-        const format = outputFormat("json");
+        const format = outputFormat("summary");
         if (format === "clusters") throw new CodeIndexError("clusters format is only available for cross-search.");
         if (format === "summary") {
           process.stdout.write(`${command === "search-summary" ? results.map((match) => `${formatSimilaritySummary([match])}
@@ -3042,10 +3076,9 @@ async function main() {
           limit: positiveIntegerOption(parsed.values.limit, 50, "limit"),
           minSimilarity: threshold.min,
           ...threshold.max !== void 0 ? { maxSimilarity: threshold.max } : {},
-          minLines: minimumLines(),
-          ...parsed.values.regex !== void 0 ? { nameRegex: parsed.values.regex } : {}
+          minLines: minimumLines()
         });
-        const format = outputFormat("json");
+        const format = outputFormat("summary");
         if (format === "clusters") throw new CodeIndexError("clusters format is only available for cross-search.");
         if (format === "summary") process.stdout.write(`${formatCohesionSummary(report)}
 `);
@@ -3102,8 +3135,7 @@ async function runCrossSearch(source, sourceOptions, provider) {
     ...threshold.max !== void 0 ? { maxSimilarity: threshold.max } : {},
     includeSymmetricDuplicates: parsed.values["include-symmetric-duplicates"],
     crossFileOnly: parsed.values["cross-file-only"],
-    minLines: minimumLines(),
-    ...parsed.values.regex !== void 0 ? { nameRegex: parsed.values.regex } : {}
+    minLines: minimumLines()
   };
   try {
     if (format === "clusters") {
@@ -3130,13 +3162,14 @@ async function runCrossSearch(source, sourceOptions, provider) {
     target?.close();
   }
 }
-async function ensureIndexUpdated(options, label, target, rebuildOnDivergence, forceRebuild, noReindex) {
+async function ensureIndexUpdated(options, label, target, rebuildOnDivergence, forceRebuild, noReindex, beforeRefresh) {
   diagnosticIndexes.add(resolveIndexPath(options));
   const initialized = await initializeMissingIndex(options, label, target, noReindex);
   if (initialized) return initialized;
   try {
     const index = new CodeIndex(options);
     try {
+      beforeRefresh?.(index);
       return await refreshIndex(index, label, target, rebuildOnDivergence, noReindex);
     } finally {
       index.close();
@@ -3267,19 +3300,24 @@ function numberOption(value, defaultValue, name) {
   return parsedValue;
 }
 function validateInvocation() {
-  if (parsed.values.regexp !== void 0) {
+  const nameRegex = qualifiedNameRegex();
+  if (nameRegex !== void 0) {
     if (!["search", "search-summary", "cross-search", "cohesion"].includes(command)) {
-      throw new CodeIndexError("-e/--regexp is only available for search, search-summary, cross-search, and cohesion.");
+      throw new CodeIndexError("-e/--regexp/--regex is only available for search, search-summary, cross-search, and cohesion.");
     }
-    compileNameRegex(parsed.values.regexp, "-e/--regexp value");
+    compileNameRegex(nameRegex, parsed.values.regex !== void 0 ? "--regex value" : "-e/--regexp value");
   }
   switch (command) {
     case "index-errors":
-      if (outputFormat("json") === "clusters") throw new CodeIndexError("clusters format is only available for cross-search.");
+      if (outputFormat("summary") === "clusters") throw new CodeIndexError("clusters format is only available for cross-search.");
       return;
     case "status":
     case "update-git":
-    case "use-summaries":
+      return;
+    case "summaries":
+      if (positionals.length !== 1 || summariesAction !== "enable" && summariesAction !== "disable") {
+        throw new CodeIndexError("summaries requires enable or disable.");
+      }
       return;
     case "update-files":
       if (positionals.length === 0) throw new CodeIndexError("update-files requires at least one path.");
@@ -3292,7 +3330,7 @@ function validateInvocation() {
       if (!positionals.join(" ").trim()) throw new CodeIndexError(`${command} requires a query.`);
       validateLimit(10);
       similarityThreshold();
-      if (outputFormat("json") === "clusters") throw new CodeIndexError("clusters format is only available for cross-search.");
+      if (outputFormat("summary") === "clusters") throw new CodeIndexError("clusters format is only available for cross-search.");
       return;
     }
     case "cross-search":
@@ -3306,16 +3344,14 @@ function validateInvocation() {
       similarityThreshold();
       outputFormat("clusters");
       minimumLines();
-      functionNameRegex();
       crossSearchSourceFilter();
       return;
     case "cohesion":
       positiveIntegerOption(parsed.values.limit, 50, "limit");
       positiveIntegerOption(parsed.values.neighbors, 20, "neighbors");
       cohesionThreshold();
-      if (outputFormat("json") === "clusters") throw new CodeIndexError("clusters format is only available for cross-search.");
+      if (outputFormat("summary") === "clusters") throw new CodeIndexError("clusters format is only available for cross-search.");
       minimumLines();
-      functionNameRegex();
       crossSearchSourceFilter();
       return;
     default:
@@ -3361,15 +3397,19 @@ function minimumLines() {
   if (!Number.isInteger(value) || value < 1) throw new CodeIndexError("min-lines must be a positive integer.");
   return value;
 }
-function functionNameRegex() {
-  return compileNameRegex(parsed.values.regex, "--regex value");
+function qualifiedNameRegex() {
+  if (parsed.values.regexp !== void 0 && parsed.values.regex !== void 0 && parsed.values.regexp !== parsed.values.regex) {
+    throw new CodeIndexError("-e/--regexp and --regex are aliases and cannot use different values.");
+  }
+  return parsed.values.regexp ?? parsed.values.regex;
 }
 function crossSearchSourceFilter() {
   const changedSince = parsed.values["changed-since"];
   const uncommitted = parsed.values.uncommitted;
+  const nameRegex = qualifiedNameRegex();
   const restrictions = {
     ...parsed.values["source-path"] ? { path: parsed.values["source-path"] } : {},
-    ...parsed.values.regexp !== void 0 ? { nameRegex: parsed.values.regexp } : {}
+    ...nameRegex !== void 0 ? { nameRegex } : {}
   };
   if (changedSince) return { type: "changed-since", commit: changedSince, ...uncommitted ? { uncommitted: true } : {}, ...restrictions };
   if (uncommitted) return { type: "uncommitted", ...restrictions };
@@ -3432,7 +3472,7 @@ Commands:
   delete-files <path...>              Remove specific files from the index
   update-git                          Index a Git snapshot plus working-tree changes
   search <query>                      Search functions by semantic similarity
-  use-summaries                       Generate purpose summaries and enable automatic updates
+  summaries <enable|disable>          Enable or disable automatic purpose summaries
   search-summary <query>              Search functions using summary embeddings
   cross-search                        Find nearest functions for each source function
   cohesion                            Rank related functions separated across the repository
@@ -3520,6 +3560,7 @@ Reading Analysis Output:
                        Higher means more of a file's related affinity lies outside its folder
 
 Options:
+  --version                           Show the package version
   --root <path>                       Repository root (default: current directory)
   --config <path>                     Config file (default: .slopdex/config.json)
   --index <path>                      SQLite index path
@@ -3535,13 +3576,13 @@ Options:
   --limit <number>                    Search result limit
   --neighbors <number>                Semantic neighbors per function for cohesion (default: 20)
   --threshold <number|range>          Show similarities at/above a value or within a range
-  --format <json|summary|clusters>    Output format (search: json; cross-search: clusters)
+  --format <json|summary|clusters>    Output format (default: summary; cross-search: clusters)
   --include-source                    Include function source in cohesion JSON
   --include-symmetric-duplicates      Show both directions of same-index matches
   --cross-file-only                   Exclude matches from the source file
   --min-lines <number>               Minimum callable length for cross-search (default: 2)
   -e, --regexp <regex>               Filter qualified symbols (analysis: sources only)
-  --regex <regex>                    Filter both analysis sources and matching candidates
+  --regex <regex>                    Alias for -e/--regexp
   --changed-since <commit>            Search added, modified, or moved functions
   --uncommitted                       Search functions from uncommitted files
   --source-path <path>                Restrict cross-search sources to a file or directory
@@ -3569,7 +3610,7 @@ Other Examples:
     slopdex search "validate an authenticated session" --limit 10
 
   Enable purpose summaries, then search by their meaning:
-    slopdex use-summaries
+    slopdex summaries enable
     slopdex search-summary "maintain the repository index" --format summary
 
   Review functions under a path against the whole codebase:
@@ -3584,10 +3625,10 @@ Other Examples:
   Filter semantic search results by qualified symbol before applying the limit:
     slopdex search "validate session" -e '^Session\\.' --limit 10
 
-  -e/--regexp uses a case-sensitive JavaScript regex on qualified names. For cross-search
+  -e/--regexp/--regex uses a case-sensitive JavaScript regex on qualified names. For cross-search
   and cohesion it filters sources only; targets keep their normal eligibility rules.
   With --changed-since and --uncommitted, sources must be changed since the commit and
-  belong to an uncommitted file. --source-path and -e further narrow that intersection.
+  belong to an uncommitted file. --source-path and the regex filter further narrow that intersection.
 `);
 }
 //# sourceMappingURL=cli.js.map