knodin 0.8.2 → 0.8.4

package/dist/src/resource-reachability.js

@@ -0,0 +1,456 @@
+import crypto from "node:crypto";
+const MAX_DEPTH = 6;
+const MAX_PATHS = 100;
+function language(file) {
+    if (/\.(?:ts|tsx)$/.test(file))
+        return "typescript";
+    if (/\.(?:js|jsx|mjs|cjs)$/.test(file))
+        return "javascript";
+    return undefined;
+}
+function evidence(file, line, excerpt) {
+    return { file, line, excerpt: excerpt.trim().slice(0, 240) };
+}
+export function resourceFingerprint(files) {
+    const hash = crypto.createHash("sha256");
+    for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path)))
+        hash.update(file.path).update("\0").update(file.content).update("\0");
+    return hash.digest("hex");
+}
+function maskSourceLines(lines) {
+    let blockComment = false;
+    return lines.map((line) => {
+        let quote;
+        let escaped = false;
+        let output = "";
+        for (let index = 0; index < line.length; index++) {
+            const char = line[index];
+            const next = line[index + 1];
+            if (blockComment) {
+                output += " ";
+                if (char === "*" && next === "/") {
+                    output += " ";
+                    index++;
+                    blockComment = false;
+                }
+                continue;
+            }
+            if (quote) {
+                output += " ";
+                if (!escaped && char === quote)
+                    quote = undefined;
+                escaped = !escaped && char === "\\";
+                if (char !== "\\")
+                    escaped = false;
+                continue;
+            }
+            if (char === "/" && next === "/")
+                return output.padEnd(line.length, " ");
+            if (char === "/" && next === "*") {
+                output += "  ";
+                index++;
+                blockComment = true;
+                continue;
+            }
+            if (char === "'" || char === '"' || char === "`") {
+                quote = char;
+                output += " ";
+                continue;
+            }
+            output += char;
+        }
+        return output;
+    });
+}
+function sourceFromExpression(file, line, text) {
+    const code = maskSourceLines([text])[0];
+    const env = /^\s*process\.env\.([A-Za-z_$][\w$]*)\s*;?\s*$/.exec(code);
+    if (env) {
+        const at = evidence(file, line, text);
+        return {
+            class: "environment",
+            resource: env[1],
+            evidence: at,
+            steps: [{ relation: "read", evidence: at }],
+        };
+    }
+    const localCall = /^\s*fs\.readFileSync\s*\(/.exec(code);
+    const local = localCall ? /(?<![\w$.])fs\.readFileSync\(\s*["']([^"']+)["']/.exec(text) : null;
+    if (local) {
+        const at = evidence(file, line, text);
+        return {
+            class: "local_config",
+            resource: local[1],
+            evidence: at,
+            steps: [{ relation: "read", evidence: at }],
+        };
+    }
+    return undefined;
+}
+function functions(lines, codeLines) {
+    const result = new Map();
+    let index = 0;
+    while (index < lines.length) {
+        const match = /\bfunction\s+([A-Za-z_$][\w$]*)\s*\(([^)]*)\)/.exec(codeLines[index]);
+        if (!match) {
+            index++;
+            continue;
+        }
+        let balance = 0;
+        let end = index;
+        for (; end < lines.length; end++) {
+            balance += (codeLines[end].match(/{/g) ?? []).length;
+            balance -= (codeLines[end].match(/}/g) ?? []).length;
+            if (balance === 0)
+                break;
+        }
+        result.set(match[1], {
+            name: match[1],
+            params: match[2]
+                .split(",")
+                .map((value) => /^([A-Za-z_$][\w$]*)/.exec(value.trim())?.[1])
+                .filter((value) => Boolean(value)),
+            start: index,
+            end,
+            lines: lines.slice(index, end + 1),
+            code: codeLines.slice(index, end + 1),
+        });
+        index = end + 1;
+    }
+    return result;
+}
+function sinkOn(line) {
+    if (/(?<![\w$.])console\.log\s*\(/.test(line))
+        return "logging";
+    if (/(?<![\w$.])fetch\s*\(/.test(line))
+        return "network";
+    if (/(?<![\w$.])db\.query\s*\(/.test(line))
+        return "database";
+    return undefined;
+}
+function sinkExpression(line, sink) {
+    const callee = sink === "logging" ? "console\\.log" : sink === "network" ? "fetch" : "db\\.query";
+    const match = new RegExp(`(?<![\\w$.])${callee}\\s*\\(`).exec(line);
+    if (!match)
+        return "";
+    const open = match.index + match[0].lastIndexOf("(");
+    let depth = 0;
+    for (let index = open; index < line.length; index++) {
+        if (line[index] === "(")
+            depth++;
+        else if (line[index] === ")" && --depth === 0)
+            return line.slice(open + 1, index);
+    }
+    return "";
+}
+function callArguments(text, name) {
+    // A local summary named `forward` must not be applied to `obj.forward(...)`.
+    // Member dispatch is dynamic and outside this deliberately bounded heuristic.
+    const match = new RegExp(`(?<![\\w$.])${name}\\s*\\((.*)\\)`).exec(text);
+    return match?.[1].split(",").map((part) => part.trim());
+}
+export function analyzeResourceReachability(files, options = {}) {
+    const maxItems = Math.min(options.maxItems ?? MAX_PATHS, MAX_PATHS);
+    const maxBytes = options.maxBytes ?? 65_536;
+    const maxTokens = options.maxTokens ?? 16_384;
+    const offset = options.offset ?? 0;
+    const fingerprint = resourceFingerprint(files);
+    const stale = Boolean(options.expectedFingerprint && options.expectedFingerprint !== fingerprint);
+    const coverage = {
+        languages: ["typescript", "javascript"],
+        registry: {
+            environment: ["process.env.LITERAL"],
+            local_config: ["fs.readFileSync(LITERAL)"],
+            logging: ["console.log"],
+            network: ["fetch"],
+            database: ["db.query"],
+        },
+        maxDepth: MAX_DEPTH,
+        maxPaths: MAX_PATHS,
+    };
+    const candidates = [];
+    const omissions = [];
+    const sourceByPath = new Map(files.map((file) => [file.path, file.content.split(/\r?\n/)]));
+    const addPath = (file, taint, sink, line, text) => {
+        const sinkEvidence = evidence(file, line, text);
+        const normalizedSink = sinkExpression(maskSourceLines([text])[0], sink)
+            .replace(/\s+/g, " ")
+            .trim();
+        const occurrence = (sourceByPath.get(file) ?? []).slice(0, line).filter((candidate) => {
+            const masked = maskSourceLines([candidate])[0];
+            return (sinkOn(masked) === sink &&
+                sinkExpression(masked, sink).replace(/\s+/g, " ").trim() === normalizedSink);
+        }).length;
+        const sinkKey = crypto.createHash("sha256").update(normalizedSink).digest("hex").slice(0, 16);
+        const identity = `${sink}:${file}:${sinkKey}:${occurrence}`;
+        const id = crypto
+            .createHash("sha256")
+            .update(`${taint.class}:${taint.resource}\0${identity}\0${taint.steps.map((s) => s.relation).join("|")}`)
+            .digest("hex")
+            .slice(0, 24);
+        candidates.push({
+            id,
+            source: {
+                identity: `${taint.class}:${taint.resource}`,
+                class: taint.class,
+                resource: taint.resource,
+                evidence: taint.evidence,
+            },
+            sink: { identity, class: sink, evidence: sinkEvidence },
+            relationKind: "static_resource_flow",
+            path: [...taint.steps, { relation: "write", evidence: sinkEvidence }],
+            provenance: "knodin-resource-reachability-v1",
+            confidence: "heuristic",
+            staticOnly: true,
+        });
+    };
+    for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+        if (!language(file.path)) {
+            omissions.push({
+                file: file.path,
+                line: 1,
+                kind: "unsupported_language",
+                reason: "No verified resource registry for this language",
+            });
+            continue;
+        }
+        const lines = file.content.split(/\r?\n/);
+        const codeLines = maskSourceLines(lines);
+        const summaries = functions(lines, codeLines);
+        const scopes = [new Map()];
+        const lookup = (name) => {
+            for (let index = scopes.length - 1; index >= 0; index--)
+                if (scopes[index].has(name))
+                    return scopes[index].get(name) ?? undefined;
+            return undefined;
+        };
+        const evaluate = (expression, line, bindings = new Map(), depth = 0, stack = new Set()) => {
+            for (const summary of summaries.values()) {
+                const args = callArguments(expression, summary.name);
+                if (!args)
+                    continue;
+                if (depth >= MAX_DEPTH) {
+                    omissions.push({
+                        file: file.path,
+                        line,
+                        kind: "depth_bound",
+                        reason: `Call depth exceeds ${MAX_DEPTH}`,
+                    });
+                    return undefined;
+                }
+                if (stack.has(summary.name)) {
+                    omissions.push({
+                        file: file.path,
+                        line,
+                        kind: "recursion_cycle",
+                        reason: "Cycle terminated at the bounded call summary",
+                    });
+                    // Continue scanning this function's base returns; never recurse again.
+                }
+                const nextBindings = new Map();
+                for (const [index, parameter] of summary.params.entries()) {
+                    const value = evaluate(args[index] ?? "", line, bindings, depth + 1, stack);
+                    if (value)
+                        nextBindings.set(parameter, {
+                            ...value,
+                            steps: [
+                                ...value.steps,
+                                {
+                                    relation: "argument",
+                                    evidence: evidence(file.path, line, lines[line - 1] ?? expression),
+                                },
+                            ],
+                        });
+                }
+                const nextStack = new Set(stack).add(summary.name);
+                for (let inner = 0; inner < summary.lines.length; inner++) {
+                    const actualLine = summary.start + inner + 1;
+                    const bodyLine = summary.lines[inner];
+                    const bodyCode = summary.code[inner];
+                    const sink = sinkOn(bodyCode);
+                    if (sink) {
+                        const written = sinkExpression(bodyCode, sink);
+                        for (const [parameter, taint] of nextBindings)
+                            if (new RegExp(`\\b${parameter}\\b`).test(written))
+                                addPath(file.path, taint, sink, actualLine, bodyLine);
+                    }
+                    const returned = /\breturn\s+(.+?);?\s*}/.exec(bodyCode)?.[1] ??
+                        /\breturn\s+(.+?);?\s*$/.exec(bodyCode)?.[1];
+                    if (returned) {
+                        // Conditional recursion is conservatively reduced to its non-recursive source arm.
+                        const arms = returned.split(":").reverse();
+                        for (const arm of arms) {
+                            if (stack.has(summary.name) && new RegExp(`\\b${summary.name}\\s*\\(`).test(arm))
+                                continue;
+                            const value = evaluate(arm.replace(/^.*\?/, "").trim(), actualLine, nextBindings, depth + 1, nextStack);
+                            if (value)
+                                return {
+                                    ...value,
+                                    steps: [
+                                        ...value.steps,
+                                        { relation: "return", evidence: evidence(file.path, actualLine, bodyLine) },
+                                    ],
+                                };
+                        }
+                    }
+                }
+            }
+            const direct = sourceFromExpression(file.path, line, expression);
+            if (direct)
+                return direct;
+            const identifier = /^([A-Za-z_$][\w$]*)$/.exec(expression.trim())?.[1];
+            if (identifier)
+                return bindings.get(identifier) ?? lookup(identifier);
+            return undefined;
+        };
+        for (const summary of summaries.values()) {
+            if (summary.code.some((body, index) => index > 0 && new RegExp(`\\b${summary.name}\\s*\\(`).test(body)))
+                omissions.push({
+                    file: file.path,
+                    line: summary.start + 1,
+                    kind: "recursion_cycle",
+                    reason: "Recursive summary is cycle-guarded at depth 6",
+                });
+        }
+        for (let index = 0; index < lines.length; index++) {
+            const text = lines[index];
+            const code = codeLines[index];
+            const line = index + 1;
+            if (/process\.env\s*\[/.test(code))
+                omissions.push({
+                    file: file.path,
+                    line,
+                    kind: "dynamic_resource_name",
+                    reason: "Computed environment names are intentionally unsupported",
+                });
+            if (/Reflection|Reflect\.|loadSecretWithReflection/.test(code))
+                omissions.push({
+                    file: file.path,
+                    line,
+                    kind: "unsupported_reflection",
+                    reason: "Reflective calls are intentionally unsupported",
+                });
+            if (/\b(?:this|globalThis|window)\s*\[/.test(code))
+                omissions.push({
+                    file: file.path,
+                    line,
+                    kind: "unsupported_alias",
+                    reason: "Computed aliases are intentionally unsupported",
+                });
+            if (/\b(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*(?:console\.log|fetch|db\.query|fs\.readFileSync|process\.env(?!\.))\b/.test(code) ||
+                /\b(?:const|let|var)\s*{[^}]+}\s*=\s*(?:console|db|fs|process\.env)\b/.test(code))
+                omissions.push({
+                    file: file.path,
+                    line,
+                    kind: "unsupported_alias",
+                    reason: "Aliased source or sink registries are intentionally unsupported",
+                });
+            if (code.trim().startsWith("}") && scopes.length > 1)
+                scopes.pop();
+            if (code.trim() === "{")
+                scopes.push(new Map());
+            const assignment = /\b(const|let|var)?\s*([A-Za-z_$][\w$]*)\s*=\s*(.+?);?\s*$/.exec(code);
+            if (assignment) {
+                const equals = text.indexOf("=", assignment.index);
+                const rawExpression = equals >= 0 ? text.slice(equals + 1).replace(/;\s*$/, "") : assignment[3];
+                const taint = evaluate(rawExpression, line);
+                const value = taint
+                    ? {
+                        ...taint,
+                        steps: [
+                            ...taint.steps,
+                            { relation: "assignment", evidence: evidence(file.path, line, text) },
+                        ],
+                    }
+                    : null;
+                if (assignment[1])
+                    scopes.at(-1)?.set(assignment[2], value);
+                else {
+                    for (let scope = scopes.length - 1; scope >= 0; scope--)
+                        if (scopes[scope].has(assignment[2])) {
+                            scopes[scope].set(assignment[2], value);
+                            break;
+                        }
+                }
+            }
+            const sink = sinkOn(code);
+            if (sink) {
+                const expression = sinkExpression(code, sink);
+                const direct = evaluate(expression, line);
+                if (direct)
+                    addPath(file.path, direct, sink, line, text);
+                for (const name of new Set([...expression.matchAll(/\b([A-Za-z_$][\w$]*)\b/g)].map((match) => match[1]))) {
+                    const taint = lookup(name);
+                    if (taint)
+                        addPath(file.path, taint, sink, line, text);
+                }
+            }
+            // Calls whose callee contains a sink produce their paths as a side effect.
+            for (const summary of summaries.values())
+                if (callArguments(code, summary.name))
+                    evaluate(code, line);
+        }
+    }
+    const uniquePaths = [...new Map(candidates.map((row) => [row.id, row])).values()].sort((a, b) => a.id.localeCompare(b.id));
+    const uniqueOmissions = [
+        ...new Map(omissions.map((row) => [`${row.file}:${row.line}:${row.kind}`, row])).values(),
+    ].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.kind.localeCompare(b.kind));
+    const entries = [
+        ...uniquePaths.map((value) => ({ kind: "path", value })),
+        ...uniqueOmissions.map((value) => ({ kind: "omission", value })),
+    ];
+    const selectedPaths = [];
+    const selectedOmissions = [];
+    let truncated = false;
+    const finalize = () => {
+        let responseBytes = 0;
+        let result;
+        for (let attempt = 0; attempt < 8; attempt++) {
+            result = {
+                paths: stale ? [] : selectedPaths,
+                omissions: stale ? [] : selectedOmissions,
+                coverage,
+                budget: { maxItems, maxBytes, maxTokens, responseBytes },
+                truncated: stale ? false : truncated,
+                ...(!stale && truncated
+                    ? { continuation: { offset: offset + selectedPaths.length + selectedOmissions.length } }
+                    : {}),
+                freshness: { fingerprint, state: stale ? "stale-rejected" : "fresh" },
+            };
+            const measured = Buffer.byteLength(JSON.stringify(result));
+            if (measured === responseBytes)
+                break;
+            responseBytes = measured;
+        }
+        return result;
+    };
+    const empty = finalize();
+    if (empty.budget.responseBytes > maxBytes ||
+        Math.ceil(empty.budget.responseBytes / 4) > maxTokens)
+        throw new Error("resource_reachability budget cannot encode the minimum response envelope");
+    if (stale)
+        return empty;
+    for (const entry of entries.slice(offset)) {
+        const itemCount = selectedPaths.length + selectedOmissions.length;
+        if (itemCount >= maxItems) {
+            truncated = true;
+            break;
+        }
+        if (entry.kind === "path")
+            selectedPaths.push(entry.value);
+        else
+            selectedOmissions.push(entry.value);
+        const measured = finalize().budget.responseBytes;
+        if (measured > maxBytes || Math.ceil(measured / 4) > maxTokens) {
+            if (entry.kind === "path")
+                selectedPaths.pop();
+            else
+                selectedOmissions.pop();
+            truncated = true;
+            break;
+        }
+    }
+    if (offset + selectedPaths.length + selectedOmissions.length < entries.length)
+        truncated = true;
+    return finalize();
+}

package/dist/src/response-budget.js

@@ -48,6 +48,71 @@ const PROTECTED_CONTRACT_KEYS = new Set([
 function isTruncatableDetail(entry) {
     return typeof entry.key !== "string" || !PROTECTED_CONTRACT_KEYS.has(entry.key);
 }
+function synchronizeNestedCapabilityBudget(root, metadata, operation) {
+    const cross = root.crossSubstratePath;
+    if (!cross)
+        return;
+    if (metadata.truncated) {
+        cross.truncated = true;
+        cross.continuation = `Repeat ${operation} with a larger byte/token budget to recover complete source evidence.`;
+        const omission = "Flow or Apex source evidence was shortened by the response budget.";
+        cross.omissions ??= [];
+        if (!cross.omissions.includes(omission))
+            cross.omissions.push(omission);
+    }
+    const measuredBudget = {
+        byteLimit: metadata.byteLimit,
+        tokenLimit: metadata.tokenLimit,
+        itemLimit: metadata.itemLimit,
+        serializedBytes: 0,
+        estimatedTokens: 0,
+    };
+    cross.budget = cross.budget ? { ...cross.budget, ...measuredBudget } : measuredBudget;
+    for (let iteration = 0; iteration < 4; iteration++) {
+        const serializedBytes = bytes(cross);
+        const estimatedTokens = Math.ceil(serializedBytes / 4);
+        if (cross.budget.serializedBytes === serializedBytes &&
+            cross.budget.estimatedTokens === estimatedTokens)
+            break;
+        cross.budget.serializedBytes = serializedBytes;
+        cross.budget.estimatedTokens = estimatedTokens;
+    }
+}
+function truncatePayloadToBytes(root, byteLimit) {
+    let truncated = false;
+    while (bytes(root) > byteLimit) {
+        const candidate = collectStrings(root)
+            .filter((entry) => !entry.path.startsWith("$/responseBudget") &&
+            entry.value.length > 0 &&
+            isTruncatableDetail(entry))
+            .sort((a, b) => b.value.length - a.value.length)[0];
+        if (!candidate)
+            break;
+        const marker = "\n… [truncated]";
+        if (candidate.value.length <= marker.length + 1) {
+            if (Array.isArray(candidate.parent))
+                candidate.parent.splice(candidate.key, 1);
+            else
+                delete candidate.parent[candidate.key];
+        }
+        else {
+            const keep = Math.max(0, Math.floor((candidate.value.length - marker.length) / 2));
+            candidate.parent[candidate.key] =
+                `${candidate.value.slice(0, keep)}${marker}`;
+        }
+        truncated = true;
+    }
+    while (bytes(root) > byteLimit) {
+        const candidate = collectArrays(root)
+            .filter((entry) => !entry.path.startsWith("$/responseBudget") && entry.value.length > 0)
+            .sort((a, b) => bytes(b.value) - bytes(a.value))[0];
+        if (!candidate)
+            break;
+        candidate.value.pop();
+        truncated = true;
+    }
+    return truncated;
+}
 /**
  * Applies limits to the value that is actually JSON-serialized. Token accounting
  * intentionally uses the deterministic local estimate of four UTF-8 bytes/token;
@@ -98,38 +163,7 @@ export function applyResponseBudget(value, operation, request, defaults) {
     root.responseBudget = metadata;
     // Preserve collection contracts and identifiers where possible: large source,
     // artifact and diagnostic strings are the first expendable detail.
-    while (bytes(root) > byteLimit) {
-        const candidate = collectStrings(root)
-            .filter((entry) => !entry.path.startsWith("$/responseBudget") &&
-            entry.value.length > 0 &&
-            isTruncatableDetail(entry))
-            .sort((a, b) => b.value.length - a.value.length)[0];
-        if (!candidate)
-            break;
-        const marker = "\n… [truncated]";
-        if (candidate.value.length <= marker.length + 1) {
-            if (Array.isArray(candidate.parent))
-                candidate.parent.splice(candidate.key, 1);
-            else
-                delete candidate.parent[candidate.key];
-            truncated = true;
-            continue;
-        }
-        const keep = Math.max(0, Math.floor((candidate.value.length - marker.length) / 2));
-        candidate.parent[candidate.key] =
-            `${candidate.value.slice(0, keep)}${marker}`;
-        truncated = true;
-    }
-    // Only drop tail items after scalar detail has been exhausted.
-    while (bytes(root) > byteLimit) {
-        const candidate = collectArrays(root)
-            .filter((entry) => !entry.path.startsWith("$/responseBudget") && entry.value.length > 0)
-            .sort((a, b) => bytes(b.value) - bytes(a.value))[0];
-        if (!candidate)
-            break;
-        candidate.value.pop();
-        truncated = true;
-    }
+    truncated = truncatePayloadToBytes(root, byteLimit) || truncated;
     metadata.truncated = truncated;
     if (truncated) {
         metadata.continuation = {
@@ -138,6 +172,7 @@ export function applyResponseBudget(value, operation, request, defaults) {
             instruction: `Repeat ${operation} with a narrower selector, larger budget, or query drill-down.`,
         };
     }
+    synchronizeNestedCapabilityBudget(root, metadata, operation);
     // Metadata changes the byte count, so converge after setting it. The reserve
     // above is normally enough; this final pass handles unusually long paths.
     metadata.serializedBytes = bytes(root);
@@ -147,42 +182,11 @@ export function applyResponseBudget(value, operation, request, defaults) {
         metadata.serializedBytes = bytes(root);
         metadata.estimatedTokens = Math.ceil(metadata.serializedBytes / 4);
     }
-    while (bytes(root) > byteLimit) {
-        const candidate = collectStrings(root)
-            .filter((entry) => !entry.path.startsWith("$/responseBudget") &&
-            entry.value.length > 0 &&
-            isTruncatableDetail(entry))
-            .sort((a, b) => b.value.length - a.value.length)[0];
-        if (!candidate)
-            break;
-        const marker = "\n… [truncated]";
-        if (candidate.value.length <= marker.length + 1) {
-            if (Array.isArray(candidate.parent))
-                candidate.parent.splice(candidate.key, 1);
-            else
-                delete candidate.parent[candidate.key];
-        }
-        else {
-            const keep = Math.max(0, Math.floor((candidate.value.length - marker.length) / 2));
-            candidate.parent[candidate.key] =
-                `${candidate.value.slice(0, keep)}${marker}`;
-        }
-        metadata.truncated = true;
-    }
+    metadata.truncated = truncatePayloadToBytes(root, byteLimit) || metadata.truncated;
     metadata.serializedBytes = bytes(root);
     metadata.estimatedTokens = Math.ceil(metadata.serializedBytes / 4);
-    while (bytes(root) > byteLimit) {
-        const candidate = collectArrays(root)
-            .filter((entry) => !entry.path.startsWith("$/responseBudget") && entry.value.length > 0)
-            .sort((a, b) => bytes(b.value) - bytes(a.value))[0];
-        if (!candidate)
-            break;
-        candidate.value.pop();
-        metadata.truncated = true;
-        metadata.serializedBytes = bytes(root);
-        metadata.estimatedTokens = Math.ceil(metadata.serializedBytes / 4);
-    }
     for (let iteration = 0; iteration < 8; iteration++) {
+        synchronizeNestedCapabilityBudget(root, metadata, operation);
         const actual = bytes(root);
         const tokens = Math.ceil(actual / 4);
         if (metadata.serializedBytes === actual && metadata.estimatedTokens === tokens)