knodin 0.10.1 → 0.10.3

package/dist/bin/cli.js

@@ -27,7 +27,7 @@ import { exportContext, grepPackedArtifact, readPackedArtifact } from "../src/co
 import { clearDiagnostics, collectDiagnostics, diagnosticsStatus, disableDiagnostics, enableDiagnostics, inspectDiagnosticsBundle, persistDiagnosticsPreview, recordDiagnosticFailure, } from "../src/diagnostics.js";
 import { getDocSection, listDocTopics } from "../src/docs-sections.js";
 import { diagnoseInstallation } from "../src/doctor.js";
-import { createEngine, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PATTERNS, } from "../src/engine/index.js";
+import { createEngine, describeThrown, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PATTERNS, } from "../src/engine/index.js";
 import { runSeal } from "../src/engine/seal-command.js";
 import { runSealedQuery } from "../src/engine/sealed-query.js";
 import { resolveDbPath } from "../src/engine/state-paths.js";
@@ -138,16 +138,29 @@ function formatRepairHuman(result) {
     const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
     return `Repair finished with ${outstanding.toLocaleString()} remaining issue(s).${detail} Run \`knodin status --deep\` for details.\n`;
 }
+/**
+ * The semantic gap, stated rather than left to be discovered.
+ *
+ * An index that deferred embeddings leaves `search` returning a short list, and
+ * a short list is indistinguishable from a thorough search that found little.
+ * Saying nothing here is what turns a deliberate deferral into a silent one.
+ */
+function formatSemanticGap(readiness) {
+    if (readiness === undefined || readiness === "ready")
+        return "";
+    return ` Semantic coverage is ${readiness}: \`search\` will under-return until \`knodin index\` completes embeddings.`;
+}
 function formatIndexHuman(result) {
+    const semantic = formatSemanticGap(result.semanticReadiness);
     if (result.indexed.length === 0 && result.unchanged.length > 0) {
         const noun = result.unchanged.length === 1 ? "file" : "files";
-        return `Graph already current: ${result.unchanged.length.toLocaleString()} requested ${noun} needed no work; health verified.\n`;
+        return `Graph already current: ${result.unchanged.length.toLocaleString()} requested ${noun} needed no work; health verified.${semantic}\n`;
     }
     const unchanged = result.unchanged.length > 0
         ? `; ${result.unchanged.length.toLocaleString()} already current`
         : "";
     const noun = result.indexed.length === 1 ? "file" : "files";
-    return `Index complete: ${result.indexed.length.toLocaleString()} ${noun} indexed${unchanged}; graph health verified.\n`;
+    return `Index complete: ${result.indexed.length.toLocaleString()} ${noun} indexed${unchanged}; graph health verified.${semantic}\n`;
 }
 function formatIndexVerificationError(result) {
     const firstIssue = result.verification.missing.files[0] ?? result.verification.missing.records[0];
@@ -199,10 +212,16 @@ function formatCoverageGaps(skipped) {
     if (byExtension)
         clauses.push(`not indexed: ${byExtension}`);
     const unparsed = formatTally(skipped.unparsedByExtension);
+    // "not parsed", not "parsed but empty". Nothing in this tally was parsed:
+    // it collects files with no tree-sitter grammar, minified sources, and files
+    // whose indexing threw. Calling that "parsed but empty" asserts the parser
+    // looked and found nothing, which is the one thing it did not do — and it
+    // made a real outage unreadable, since a dead wasm module dumped thousands
+    // of never-parsed files into this bucket under a label saying they were fine.
     if (unparsed)
-        clauses.push(`parsed but empty: ${unparsed}`);
+        clauses.push(`not parsed: ${unparsed}`);
     if (skipped.unparsedUnknown)
-        clauses.push("parsed-but-empty tally unavailable — run a full index; this is a lower bound");
+        clauses.push("not-parsed tally unavailable — run a full index; this is a lower bound");
     const count = skipped.unparsedUnknown ? `${skipped.total}+` : `${skipped.total}`;
     return `. Not in graph: ${count} files (${clauses.join("; ")})`;
 }
@@ -2124,17 +2143,27 @@ async function main() {
             const agents = scope === "team" ? [] : integrationAgents(repo);
             const paths = await initializeRepository(repo, {
                 command: runtimeCommand,
-                index: indexOrSeed(engine, KNODIN_SCHEMA_VERSION),
+                // Not `indexOrSeed`: seeding exists for a worktree with no database,
+                // and this command has already refused to run without one. Indexing
+                // the written files directly is the whole point of the narrow scope.
+                index: (target, indexOptions, files) => engine.index(target, files, false, indexOptions),
+                indexScope: "configuration",
                 scope,
                 agents,
                 allowTrackedTransition: true,
                 auditConfigurationChanges: true,
                 configureIntegration: true,
             });
+            const indexed = paths.scopedIndexPaths ?? [];
             result = {
                 status: "success",
                 message: `knodin agent integration changed to ${scope}.`,
-                graphInitialization: "refreshed",
+                // Say what happened. Claiming "refreshed" after touching a few
+                // configuration files misdescribes the graph's state, and did so most
+                // misleadingly on a repository whose graph was in fact empty.
+                graphInitialization: indexed.length === 0
+                    ? "unchanged — no configuration files needed indexing"
+                    : `configuration files indexed (${indexed.length})`,
                 nextAction: "run `knodin status` and reload the configured client",
                 paths,
             };
@@ -2152,6 +2181,8 @@ async function main() {
                 process.exit(1);
             }
             const clean = rest.includes("--clean") || rest.includes("--force");
+            const skipEmbeddings = rest.includes("--skip-embeddings");
+            const under = selectorValue("--under");
             const scipPath = selectorValue("--scip");
             const sarifPath = selectorValue("--sarif");
             // A bound the operator cannot move is just a failure, so every import
@@ -2182,6 +2213,8 @@ async function main() {
             let indexResult;
             try {
                 indexResult = await engine.index(plan.repo, plan.files, clean, {
+                    skipEmbeddings,
+                    ...(under !== undefined ? { under } : {}),
                     scip: scipPath
                         ? {
                             path: scipPath,
@@ -2888,6 +2921,17 @@ async function main() {
         process.exitCode = finalExitCode;
         return;
     }
+    // `search` has no human formatter — results fall through to the generic JSON
+    // emitter — so a semantically incomplete graph produced a short list with
+    // nothing saying why. The list looks like a thorough answer, which is the
+    // whole failure. Printed to stderr so it annotates without corrupting output
+    // anyone is piping.
+    if (cmd === "search" && !jsonOutput) {
+        const readiness = result.semanticReadiness;
+        const gap = formatSemanticGap(readiness);
+        if (gap)
+            process.stderr.write(`${gap.trim()}\n`);
+    }
     if (cmd === "status" && !jsonOutput) {
         process.stdout.write(formatStatusHuman(boundedResult));
         process.exitCode = finalExitCode;
@@ -2985,7 +3029,7 @@ catch (err) {
             error: err,
         });
         const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
-        console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
+        console.error(`${describeThrown(err)}${correlation}`);
         process.exit(1);
     }
 }

package/dist/src/cli-args.js

@@ -36,6 +36,10 @@ const GLOBAL_BOOLEAN_FLAGS = new Set(["--exclude-tests", "--data-flow", "--json"
  * not to index the log as a source file.
  */
 const COMMAND_VALUE_FLAGS = new Set([
+    // Takes a directory. Without this its argument reads as a positional, and
+    // `knodin index --under src` would be rejected as "a directory positional"
+    // by the very rule that exists to stop people scoping this way by accident.
+    "--under",
     "--scip",
     "--scip-max-bytes",
     "--scip-max-files",

package/dist/src/cli-model.js

@@ -288,6 +288,8 @@ function createCliProgram(capture = () => { }) {
     leaf(program, "index [files...]", "index a repository or selected files", capture)
         .option("--clean", "rebuild selected index state")
         .option("--force", "force clean indexing")
+        .option("--skip-embeddings", "build structure only and defer semantic embeddings; `search` under-returns until a later `knodin index` completes them")
+        .option("--under <dir>", "rebuild only the files under a repository-relative directory; coverage is then reported as a lower bound until a full index runs")
         .option("--scip <file>", "opt in to a bounded local SCIP protobuf import")
         .addOption(option("--scip-max-bytes <count>", "raise the SCIP input size ceiling", "integer"))
         .addOption(option("--scip-max-files <count>", "raise the SCIP document ceiling", "integer"))

package/dist/src/engine/candidate-database.js

@@ -66,6 +66,59 @@ export function candidateRoot(repo) {
 export function promotionMarkerPath(repo) {
     return path.join(resolveStateDir(repo), PROMOTION_MARKER);
 }
+/**
+ * Candidates left on disk for this repository, newest first.
+ *
+ * A clean index discards its candidate on failure, but a killed process runs no
+ * discard — so survivors are exactly the runs that were interrupted rather than
+ * the ones that failed. Listing them is what lets the next run continue instead
+ * of repeating hours of work.
+ *
+ * Returns descriptors only. Whether any of them is safe to resume is decided by
+ * the caller from the database's own contents, not from the fact it exists.
+ */
+export function listCandidates(repo) {
+    const resolvedRepo = path.resolve(repo);
+    const root = candidateRoot(resolvedRepo);
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith("candidate-"))
+            continue;
+        const databasePath = path.join(root, entry.name, "db.sqlite");
+        let modifiedMs;
+        try {
+            modifiedMs = fs.statSync(databasePath).mtimeMs;
+        }
+        catch {
+            // A directory with no database is a half-created candidate, not a
+            // resumable one.
+            continue;
+        }
+        found.push({
+            candidate: {
+                schemaVersion: 1,
+                id: entry.name,
+                repo: resolvedRepo,
+                databasePath,
+                createdAt: new Date(modifiedMs).toISOString(),
+            },
+            modifiedMs,
+        });
+    }
+    // Sorted as its own statement rather than mid-chain: an in-place `sort`
+    // inside an expression mutates the array being read, which is harmless for
+    // this local but reads as a side effect at a glance. (`toSorted` would be
+    // the nicer form but needs a newer `lib` than this project targets.)
+    found.sort((a, b) => b.modifiedMs - a.modifiedMs);
+    return found.map((item) => item.candidate);
+}
 export function allocateCandidate(repo) {
     const resolvedRepo = path.resolve(repo);
     const root = candidateRoot(resolvedRepo);