knodin 0.12.1 → 0.13.0

package/dist/src/class-consumer-contract.js

@@ -0,0 +1,18 @@
+/** Matches SQLite TEXT COLLATE BINARY for canonical UTF-8 paths and ASCII role names. */
+export function compareClassConsumerKeys(left, right) {
+    return (Buffer.compare(Buffer.from(left.file), Buffer.from(right.file)) ||
+        left.startByte - right.startByte ||
+        left.endByte - right.endByte ||
+        Buffer.compare(Buffer.from(left.kind), Buffer.from(right.kind)));
+}
+/** Adapters translate these typed failures; never manufacture a successful target identity. */
+export class ClassConsumerQueryError extends Error {
+    code;
+    candidates;
+    constructor(code, message, candidates = []) {
+        super(message);
+        this.code = code;
+        this.candidates = candidates;
+        this.name = "ClassConsumerQueryError";
+    }
+}

package/dist/src/class-consumer-cursor.js

@@ -0,0 +1,91 @@
+import { signAuthenticatedCursor, verifyAuthenticatedCursor } from "./authenticated-cursor.js";
+import { canonicalCoveragePath } from "./engine/index-coverage.js";
+const PREFIX = "cc1";
+const DIGEST = /^[a-f0-9]{64}$/;
+const KINDS = [
+    "static_field_read",
+    "constructor",
+    "variable_type",
+    "cast",
+    "class_literal",
+    "parameter_type",
+    "generic_parameter_type",
+    "loop_variable_type",
+    "generic_type_argument",
+];
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function exactKeys(value, keys) {
+    return (Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key)));
+}
+function validPayload(value) {
+    if (!record(value) || !exactKeys(value, ["v", "type", "queryDigest", "snapshotDigest", "after"]))
+        return false;
+    if (value.v !== 1 ||
+        value.type !== "class-consumers" ||
+        typeof value.queryDigest !== "string" ||
+        !DIGEST.test(value.queryDigest) ||
+        typeof value.snapshotDigest !== "string" ||
+        !DIGEST.test(value.snapshotDigest))
+        return false;
+    const key = value.after;
+    return (record(key) &&
+        exactKeys(key, ["file", "startByte", "endByte", "kind"]) &&
+        typeof key.file === "string" &&
+        canonicalCoveragePath(key.file) &&
+        Buffer.from(key.file).toString("utf8") === key.file &&
+        typeof key.startByte === "number" &&
+        Number.isSafeInteger(key.startByte) &&
+        key.startByte >= 0 &&
+        typeof key.endByte === "number" &&
+        Number.isSafeInteger(key.endByte) &&
+        key.endByte > key.startByte &&
+        typeof key.kind === "string" &&
+        KINDS.includes(key.kind));
+}
+function invalid() {
+    return new Error("invalid class-consumer continuation; restart the query without continuation");
+}
+/** Only call after the final wire envelope is fitted, using its last delivered site key. */
+export function signClassConsumerCursor(payload, secret) {
+    if (!validPayload(payload))
+        throw invalid();
+    // Copy validated fields explicitly: signing never invokes a caller-provided toJSON hook.
+    return signAuthenticatedCursor({
+        v: 1,
+        type: "class-consumers",
+        queryDigest: payload.queryDigest,
+        snapshotDigest: payload.snapshotDigest,
+        after: {
+            file: payload.after.file,
+            startByte: payload.after.startByte,
+            endByte: payload.after.endByte,
+            kind: payload.after.kind,
+        },
+    }, secret, PREFIX);
+}
+/** Authenticates and validates shape. Backend must still bind both digests to its current lease. */
+export function readClassConsumerCursor(cursor, secret) {
+    let payload;
+    try {
+        payload = verifyAuthenticatedCursor(cursor, secret, PREFIX);
+    }
+    catch {
+        throw invalid();
+    }
+    if (!validPayload(payload))
+        throw invalid();
+    return payload;
+}
+export function assertClassConsumerCursorBinding(cursor, queryDigest, snapshotDigest) {
+    if (!validPayload(cursor) || !DIGEST.test(queryDigest) || !DIGEST.test(snapshotDigest))
+        throw invalid();
+    if (cursor.queryDigest !== queryDigest)
+        throw new Error("class-consumer continuation belongs to another query; restart without continuation");
+    if (cursor.snapshotDigest !== snapshotDigest)
+        throw new Error("class-consumer evidence changed; restart the query without continuation");
+}

package/dist/src/class-consumer-delivery.js

@@ -0,0 +1,22 @@
+import { ClassConsumerQueryError, } from "./class-consumer-contract.js";
+/**
+ * Run once after the captured post-read health probe and before page packing.
+ * Revalidates the backend facts/coverage lease, not only freshness timestamps.
+ * Never replace the original page's rows or freshness with the validation read.
+ * Current seam repeats a limit-one raw read; measure before optimizing it into
+ * a dedicated lease check. Do not call it per candidate in the packing loop.
+ */
+export async function validateClassConsumerDelivery(page, request, read) {
+    const checked = await read({
+        ...request,
+        limit: 1,
+        expectedQueryDigest: page.queryDigest,
+        expectedSnapshotDigest: page.snapshotDigest,
+    });
+    if (checked.queryDigest !== page.queryDigest ||
+        checked.targetIdentity !== page.targetIdentity ||
+        checked.targetKind !== page.targetKind)
+        throw new ClassConsumerQueryError("CLASS_CONSUMER_QUERY_MISMATCH", "The class-consumer query changed before delivery.");
+    if (checked.snapshotDigest !== page.snapshotDigest)
+        throw new ClassConsumerQueryError("CLASS_CONSUMER_STALE_CURSOR", "The class-consumer evidence changed before delivery; restart the query.");
+}

package/dist/src/class-consumer-page.js

@@ -0,0 +1,148 @@
+import { isDeepStrictEqual } from "node:util";
+import { compareClassConsumerKeys, } from "./class-consumer-contract.js";
+import { signClassConsumerCursor } from "./class-consumer-cursor.js";
+const positiveInt = (value, fallback) => value == null || !Number.isFinite(value) ? fallback : Math.max(1, Math.trunc(value));
+const size = (value) => Buffer.byteLength(JSON.stringify(value));
+const invalid = () => new Error("invalid class-consumer page contract");
+function validatePage(page) {
+    if ((page.targetKind !== "class" && page.targetKind !== "interface") ||
+        page.returnedCount !== page.results.length ||
+        !Number.isSafeInteger(page.count) ||
+        page.count < page.results.length ||
+        !Number.isSafeInteger(page.consumerFileCount) ||
+        page.consumerFileCount < page.files.length ||
+        (page.hasMore && page.results.length === 0))
+        throw invalid();
+    const files = new Map(page.files.map((file) => [file.file, file]));
+    if (files.size !== page.files.length)
+        throw invalid();
+    const counts = new Map();
+    for (let index = 0; index < page.results.length; index++) {
+        const row = page.results[index];
+        if (row.file !== row.key.file ||
+            row.start.byte !== row.key.startByte ||
+            row.end.byte !== row.key.endByte ||
+            row.kind !== row.key.kind ||
+            (index > 0 && compareClassConsumerKeys(page.results[index - 1].key, row.key) >= 0))
+            throw invalid();
+        const file = files.get(row.file);
+        if (!file || file.isTest !== row.isTest)
+            throw invalid();
+        counts.set(row.file, (counts.get(row.file) ?? 0) + 1);
+    }
+    for (const file of files.values()) {
+        const count = counts.get(file.file);
+        if (count === undefined ||
+            file.returnedSiteCount !== count ||
+            !Number.isSafeInteger(file.siteCount) ||
+            file.siteCount < count)
+            throw invalid();
+    }
+}
+/**
+ * Fits complete rows and all qualifications, never truncating evidence fields.
+ * The caller must return this result unchanged: no later generic budget reduction.
+ * Backend lease checks precede this pure step; continuation always names the last
+ * actually delivered key, not the last row fetched from storage.
+ */
+export function finalizeClassConsumerPage(page, options) {
+    validatePage(page);
+    const request = options.budget ?? {};
+    const tokenLimit = positiveInt(request.tokens, 16384);
+    const byteLimit = Math.min(positiveInt(request.bytes, 65536), tokenLimit * 4);
+    const itemLimit = positiveInt(request.items, 100);
+    if (byteLimit < 256)
+        throw new Error("class-consumer response budget must be at least 256 bytes");
+    let maxRows = Math.min(page.results.length, itemLimit);
+    const minimumRows = page.results.length ? 1 : 0;
+    // Protected rows alone are a strict lower bound on the complete wire size.
+    // Skip impossible prefixes without cloning/decorating/serializing the entire
+    // page for each one. Do not assume complete candidate sizes are monotonic:
+    // the last-key cursor can get shorter when crossing a filename boundary.
+    let rowArrayBytes = 2;
+    for (let index = 0; index < maxRows; index++) {
+        rowArrayBytes += size(page.results[index]) + (index > 0 ? 1 : 0);
+        if (rowArrayBytes > byteLimit) {
+            maxRows = Math.max(minimumRows, index);
+            break;
+        }
+    }
+    let requiredBytes = 0;
+    for (let length = maxRows; length >= minimumRows; length--) {
+        const results = page.results.slice(0, length);
+        const counts = new Map();
+        for (const row of results)
+            counts.set(row.file, (counts.get(row.file) ?? 0) + 1);
+        const hasMore = page.hasMore || length < page.results.length;
+        const last = results.at(-1);
+        const continuation = hasMore && last
+            ? signClassConsumerCursor({
+                v: 1,
+                type: "class-consumers",
+                queryDigest: page.queryDigest,
+                snapshotDigest: page.snapshotDigest,
+                after: last.key,
+            }, options.secret)
+            : null;
+        const metadata = {
+            byteLimit,
+            tokenLimit,
+            itemLimit,
+            serializedBytes: 0,
+            estimatedTokens: 0,
+            truncated: hasMore,
+            totals: { "$/results": page.count, "$/files": page.consumerFileCount },
+        };
+        const candidate = structuredClone({
+            pattern: "class_consumers",
+            targetIdentity: page.targetIdentity,
+            targetKind: page.targetKind,
+            count: page.count,
+            consumerFileCount: page.consumerFileCount,
+            returnedCount: length,
+            results,
+            files: page.files
+                .filter((file) => counts.has(file.file))
+                .map((file) => ({
+                ...file,
+                returnedSiteCount: counts.get(file.file),
+            })),
+            hasMore,
+            continuation,
+            classConsumerAnalysis: page.analysis,
+            indexCoverage: page.indexCoverage,
+            freshness: page.freshness,
+            responseBudget: metadata,
+        });
+        const output = options.decorate ? options.decorate(structuredClone(candidate)) : candidate;
+        if (!output || Array.isArray(output) || typeof output !== "object")
+            throw invalid();
+        if (output.available === false ||
+            (output.availability &&
+                typeof output.availability === "object" &&
+                ["unavailable", "repair-needed"].includes(String(output.availability.state))))
+            throw new Error("class-consumer evidence became unavailable; restart the query");
+        for (const key of Object.keys(candidate)) {
+            if (!isDeepStrictEqual(candidate[key], output[key]))
+                throw new Error("class-consumer decoration changed protected evidence");
+        }
+        output.responseBudget = metadata;
+        // Metadata changes its own serialized size. Recompute until the byte/token digits stabilize.
+        let stable = false;
+        for (let attempt = 0; attempt < 16; attempt++) {
+            const actual = size(output), tokens = Math.ceil(actual / 4);
+            if (metadata.serializedBytes === actual && metadata.estimatedTokens === tokens) {
+                stable = true;
+                break;
+            }
+            metadata.serializedBytes = actual;
+            metadata.estimatedTokens = tokens;
+        }
+        if (!stable)
+            throw new Error("class-consumer response serialization did not stabilize");
+        requiredBytes = metadata.serializedBytes;
+        if (requiredBytes <= byteLimit)
+            return output;
+    }
+    throw new Error(`class-consumer response budget ${byteLimit} cannot preserve qualifications and one complete page item; use at least ${requiredBytes} bytes and ${Math.ceil(requiredBytes / 4)} estimated tokens or narrow the query`);
+}

package/dist/src/cli-model.js

@@ -122,7 +122,10 @@ function addRepositoryCommands(program, capture) {
         .option("--dry-run", "report actions without mutation");
 }
 function addGraphCommands(program, capture) {
-    leaf(program, "context <task> [base]", "build compact task orientation", capture);
+    leaf(program, "context <task> [base]", "build compact task orientation or a target investigation", capture)
+        .option("--symbol <name>", "investigate a target's source, change sites, impact and tests")
+        .option("--implementations", "rank possible implementations for the task; do not select a target")
+        .addOption(option("--offset <count>", "implementation candidate page offset", "integer"));
     leaf(program, "explain <symbol> [detail]", "explain one ambiguity-safe symbol", capture);
     leaf(program, "review [base] [detail]", "review an explicit Git diff scope", capture)
         .option("--scope <scope>", "unstaged, staged, all, or compare")
@@ -165,7 +168,8 @@ function addGraphCommands(program, capture) {
         .option("--kinds <values>", "comma-separated symbol kinds")
         .option("--path <prefix>", "repo-relative path prefix")
         .option("--base <ref>", "compare file_metrics with the merge-base of this Git ref")
-        .option("--test-scope <scope>", "file_metrics scope: all, test, or production")
+        .option("--test-scope <scope>", "file_metrics/class_consumers: all, test, or production")
+        .option("--continuation <handle>", "class_consumers: resume the same target and filters")
         .option("--format <format>", "file_metrics machine output format; currently json")
         .option("--variable <name>", "flow-analysis variable")
         .option("--facets <values>", "comma-separated architecture facets")
@@ -199,7 +203,9 @@ function addBackupCommands(program, capture) {
     leaf(retention, "run", "run the installed retention policy", capture);
 }
 function addArtifactCommands(program, capture) {
-    leaf(program, "evidence <level> <file>", "deliver progressive source evidence", capture)
+    leaf(program, "evidence <level> [file]", "deliver progressive source evidence", capture)
+        .option("--files <paths>", "comma-separated bundle files; evidence or expand level")
+        .option("--already-present <handles>", "comma-separated verified bundle file handles")
         .option("--continuation <handle>", "resume an exact prior response")
         .option("--baseline-hash <sha256>", "complete baseline SHA-256")
         .addOption(option("--baseline-bytes <count>", "complete baseline UTF-8 bytes", "integer"))

package/dist/src/docs-sections.js

@@ -24,6 +24,7 @@ The \`query\` operation lets you ask precise, structured questions about your co
 
 - **callers_of <target>**: Who invokes this symbol (transitive/direct).
 - **callees_of <target>**: What other symbols does this symbol invoke.
+- **class_consumers <target>**: Direct, typed Apex class-use sites, separate from method callers and Java configuration consumers. Count means observed sites; consumerFileCount means distinct files. All tests are included by default; testScope can select test or production files. Use limit (1–1000 sites), canonical path prefix, and signed continuation with the same target/filters. Pages preserve full site ranges, source-owner identities and scope/extraction qualifications; stale continuations are rejected. Nine supported syntax roles only, not complete class-use or runtime reachability proof.
 - **tests_for <target>**: Find test files that cover this symbol.
 - **file_summary <target>**: Lists all symbols defined in a file.
 - **shortest_path <from> <to>**: Find the call-graph chain connecting two symbols.

package/dist/src/doctor.js

@@ -171,15 +171,68 @@ function managedConfigurationRemediation(repo, run) {
                 paths.push(relative);
         }
     }
+    // One `ls-files` and one `diff` for every managed path together: the previous
+    // per-path pair spawned ~2 git processes per entry, and each `git diff` must
+    // load and refresh the repository index — seconds apiece on a 900k-file
+    // checkout, for identical answers (KNODIN-39).
+    const trackedResult = run("git", ["-C", repo, "ls-files", "-z", "--", ...paths]);
+    const trackedFiles = trackedResult.status === 0 ? trackedResult.stdout.split("\0").filter(Boolean) : [];
+    // A managed DIRECTORY (a receipted skill dir) never appears in ls-files
+    // output itself — only files under it do — so membership alone would read
+    // every tracked skill dir as untracked, matching neither the old
+    // `--error-unmatch` semantics nor reality (review on KNODIN-39). The output
+    // is already limited to the managed pathspecs, so the prefix scan is tiny.
+    const isTrackedManaged = (relative) => trackedFiles.includes(relative) || trackedFiles.some((file) => file.startsWith(`${relative}/`));
+    const trackedManaged = paths.filter(isTrackedManaged);
+    // Ignored paths need no "add to .git/info/exclude" advice: the instruction
+    // previously fired for every present, untracked, knodin-looking file whether
+    // or not the exclude entry already existed (KNODIN-40). One batched
+    // check-ignore answers for all of them; a non-zero status just means none
+    // are ignored.
+    const ignoredPaths = new Set();
+    const untrackedPresent = paths.filter((relative) => !isTrackedManaged(relative) && fs.existsSync(path.join(repo, relative)));
+    if (untrackedPresent.length > 0) {
+        const checkIgnore = run("git", ["-C", repo, "check-ignore", "-z", "--stdin"], {
+            input: `${untrackedPresent.join("\0")}\0`,
+        });
+        for (const relative of checkIgnore.stdout.split("\0").filter(Boolean))
+            ignoredPaths.add(relative);
+    }
+    // Guarding on trackedManaged (not the raw ls-files output) matters: with no
+    // tracked managed paths, `git diff --` with an empty pathspec list would
+    // diff the entire repository (review on KNODIN-39).
+    const diffSections = [];
+    if (trackedManaged.length > 0) {
+        const batchedDiff = run("git", [
+            "-C",
+            repo,
+            "diff",
+            "--no-ext-diff",
+            "--unified=3",
+            "--",
+            ...trackedManaged,
+        ]);
+        if (batchedDiff.status === 0 && batchedDiff.stdout) {
+            for (const section of batchedDiff.stdout.split(/^(?=diff --git )/m)) {
+                const header = /^diff --git a\/(.+) b\//.exec(section);
+                if (header?.[1])
+                    diffSections.push({ file: header[1], section });
+            }
+        }
+    }
+    // A managed directory owns every section for files beneath it; a managed
+    // file owns only its own. This mirrors what the old per-path `git diff -- p`
+    // returned for each shape.
+    const diffFor = (relative) => diffSections
+        .filter(({ file }) => file === relative || file.startsWith(`${relative}/`))
+        .map(({ section }) => section)
+        .join("");
     return paths
         .map((relative) => {
         const absolute = path.join(repo, relative);
         const present = fs.existsSync(absolute);
-        const trackedResult = run("git", ["-C", repo, "ls-files", "--error-unmatch", "--", relative]);
-        const tracked = trackedResult.status === 0;
-        const diffResult = tracked
-            ? run("git", ["-C", repo, "diff", "--no-ext-diff", "--unified=3", "--", relative])
-            : { status: 0, stdout: "", stderr: "" };
+        const tracked = isTrackedManaged(relative);
+        const diffResult = { status: 0, stdout: diffFor(relative), stderr: "" };
         const receipted = fs.existsSync(path.join(absolute, ".knodin-managed.json"));
         let entryOwned = false;
         if (present && !receipted) {
@@ -195,7 +248,7 @@ function managedConfigurationRemediation(repo, run) {
             instructions.push(`Review the diff, then restore manually with: git restore --source=HEAD -- ${relative}`);
         if (!tracked && receipted)
             instructions.push(`Review the Knodin receipt, then remove manually if unwanted: ${relative}`);
-        if (!tracked && present && (receipted || entryOwned))
+        if (!tracked && present && (receipted || entryOwned) && !ignoredPaths.has(relative))
             instructions.push(`To retain it locally without committing, add ${relative} to .git/info/exclude manually.`);
         return {
             path: relative,