ragcode-context-engine 0.1.0

package/dist/src/semantic/openai-compatible-embedding.js

@@ -0,0 +1,75 @@
+export class OpenAICompatibleEmbeddingProvider {
+    options;
+    dimensions;
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        if (!options.apiKey)
+            throw new Error("OpenAI-compatible embedding provider requires an API key.");
+        if (!options.model)
+            throw new Error("OpenAI-compatible embedding provider requires a model.");
+        this.baseUrl = (options.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+        this.dimensions = options.dimensions;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    async embed(text) {
+        const [embedding] = await this.embedBatch([text]);
+        return embedding;
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        const payload = await this.requestEmbeddings(texts.length === 1 ? texts[0] : texts);
+        const rows = payload.data;
+        if (!rows || rows.length !== texts.length) {
+            throw new Error(`Embedding response returned ${rows?.length ?? 0} vector(s), expected ${texts.length}.`);
+        }
+        const embeddings = new Array(texts.length);
+        rows.forEach((row, position) => {
+            const index = row.index ?? position;
+            if (!Number.isInteger(index) || index < 0 || index >= texts.length) {
+                throw new Error(`Embedding response included invalid index: ${String(row.index)}.`);
+            }
+            if (!row.embedding || !row.embedding.every((value) => Number.isFinite(value))) {
+                throw new Error("Embedding response did not include a numeric embedding vector.");
+            }
+            embeddings[index] = row.embedding;
+        });
+        if (embeddings.some((embedding) => !embedding)) {
+            throw new Error("Embedding response did not include all requested vectors.");
+        }
+        return embeddings;
+    }
+    async requestEmbeddings(input) {
+        const body = {
+            model: this.options.model,
+            input
+        };
+        if (this.options.requestDimensions && this.options.dimensions) {
+            body.dimensions = this.options.dimensions;
+        }
+        const response = await this.fetchImpl(`${this.baseUrl}/embeddings`, {
+            method: "POST",
+            headers: {
+                "authorization": `Bearer ${this.options.apiKey}`,
+                "content-type": "application/json"
+            },
+            body: JSON.stringify(body)
+        });
+        if (!response.ok) {
+            let message = `Embedding request failed with HTTP ${response.status}.`;
+            try {
+                const errorPayload = await response.json();
+                if (errorPayload.error?.message)
+                    message = errorPayload.error.message;
+            }
+            catch {
+                // Non-JSON error body (e.g. a proxy HTML page); keep the HTTP status message.
+            }
+            // Attach the status so retry classification can see 429/5xx instead of guessing from text.
+            throw Object.assign(new Error(message), { status: response.status });
+        }
+        return await response.json();
+    }
+}

package/dist/src/service/service-identity.d.ts

@@ -0,0 +1,13 @@
+export type ServicePlatform = "systemd" | "launchd" | "schtasks" | "unsupported";
+export interface ServiceIdentity {
+    /** Stable per-repo identifier, e.g. "ragcode-watch-api-3f9c1a2b". */
+    serviceName: string;
+    /** Absolute, normalized repo root the service watches. */
+    repoRoot: string;
+    platform: ServicePlatform;
+}
+export declare function detectServicePlatform(platform?: NodeJS.Platform): ServicePlatform;
+export declare function serviceNameForRepo(repoRoot: string): string;
+export declare function launchdLabelForRepo(repoRoot: string): string;
+export declare function scheduledTaskNameForRepo(repoRoot: string): string;
+export declare function resolveServiceIdentity(repoRoot: string, platform?: NodeJS.Platform): ServiceIdentity;

package/dist/src/service/service-identity.js

@@ -0,0 +1,48 @@
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+export function detectServicePlatform(platform = os.platform()) {
+    switch (platform) {
+        case "linux":
+            return "systemd";
+        case "darwin":
+            return "launchd";
+        case "win32":
+            return "schtasks";
+        default:
+            return "unsupported";
+    }
+}
+function slugifyBasename(repoRoot) {
+    const base = path.basename(path.resolve(repoRoot));
+    const slug = base
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 32);
+    return slug || "repo";
+}
+function repoHash(repoRoot) {
+    // Normalize case on platforms with case-insensitive paths so the same repo always hashes the same.
+    const normalized = process.platform === "win32" ? path.resolve(repoRoot).toLowerCase() : path.resolve(repoRoot);
+    return crypto.createHash("sha256").update(normalized).digest("hex").slice(0, 8);
+}
+export function serviceNameForRepo(repoRoot) {
+    return `ragcode-watch-${slugifyBasename(repoRoot)}-${repoHash(repoRoot)}`;
+}
+// launchd labels are conventionally reverse-DNS; Task Scheduler tolerates backslashes as folders.
+// systemd uses the bare name with a .service suffix. Each accessor keeps the platform convention
+// local so the manager doesn't sprinkle platform conditionals around.
+export function launchdLabelForRepo(repoRoot) {
+    return `com.ragcode.watch.${repoHash(repoRoot)}`;
+}
+export function scheduledTaskNameForRepo(repoRoot) {
+    return `RagCode\\${serviceNameForRepo(repoRoot)}`;
+}
+export function resolveServiceIdentity(repoRoot, platform = os.platform()) {
+    return {
+        serviceName: serviceNameForRepo(repoRoot),
+        repoRoot: path.resolve(repoRoot),
+        platform: detectServicePlatform(platform)
+    };
+}

package/dist/src/service/service-manager.d.ts

@@ -0,0 +1,29 @@
+import { type ServicePlatform } from "./service-identity.js";
+export interface ServiceManagerOptions {
+    /** Node/bun executable to launch the watcher with. Defaults to process.execPath. */
+    execPath?: string;
+    /** Resolved ragcode CLI entry. Defaults to the built dist CLI next to this module. */
+    cliEntry?: string;
+    /** Extra args appended to `watch <repoRoot>`, e.g. ["--poll"]. */
+    extraArgs?: string[];
+    home?: string;
+    platform?: NodeJS.Platform;
+}
+export interface ServiceActionResult {
+    ok: boolean;
+    platform: ServicePlatform;
+    serviceName: string;
+    repoRoot: string;
+    message: string;
+    /** Path of the unit/plist written, when applicable. */
+    unitPath?: string;
+}
+export interface ServiceStatusResult extends ServiceActionResult {
+    installed: boolean;
+}
+export declare class UnsupportedPlatformError extends Error {
+    constructor(platform: NodeJS.Platform);
+}
+export declare function installWatcherService(repoRoot: string, options?: ServiceManagerOptions): Promise<ServiceActionResult>;
+export declare function uninstallWatcherService(repoRoot: string, options?: ServiceManagerOptions): Promise<ServiceActionResult>;
+export declare function watcherServiceStatus(repoRoot: string, options?: ServiceManagerOptions): Promise<ServiceStatusResult>;

package/dist/src/service/service-manager.js

@@ -0,0 +1,231 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { detectServicePlatform, launchdLabelForRepo, resolveServiceIdentity, scheduledTaskNameForRepo, serviceNameForRepo } from "./service-identity.js";
+import { launchdPlistPath, renderLaunchdPlist, renderSystemdUnit, schtasksCreateArgv, schtasksDeleteArgv, schtasksQueryArgv, systemdUserUnitPath } from "./service-templates.js";
+const execFileAsync = promisify(execFile);
+export class UnsupportedPlatformError extends Error {
+    constructor(platform) {
+        super(`Background watcher services are not supported on this platform (${platform}). Run \`ragcode watch <repo>\` manually or under your own process manager.`);
+        this.name = "UnsupportedPlatformError";
+    }
+}
+function resolveCliEntry(options) {
+    if (options.cliEntry)
+        return options.cliEntry;
+    // This module lives at dist/src/service/service-manager.js once built; the CLI entry is one
+    // directory over at dist/src/cli/index.js. fileURLToPath (not .pathname) is required for correct
+    // Windows paths — .pathname yields "/D:/..." which path.resolve mangles.
+    return fileURLToPath(new URL("../cli/index.js", import.meta.url));
+}
+function buildSpec(repoRoot, options) {
+    return {
+        execPath: options.execPath ?? process.execPath,
+        cliEntry: resolveCliEntry(options),
+        repoRoot: path.resolve(repoRoot),
+        serviceName: serviceNameForRepo(repoRoot),
+        extraArgs: options.extraArgs
+    };
+}
+// `systemctl --user` and `launchctl` exit non-zero for benign "not loaded"/"already loaded" cases;
+// callers decide whether a non-zero exit is fatal. We capture rather than throw so status can report.
+async function run(file, args) {
+    try {
+        const { stdout, stderr } = await execFileAsync(file, args);
+        return { ok: true, stdout, stderr, code: 0 };
+    }
+    catch (error) {
+        const err = error;
+        const code = typeof err.code === "number" ? err.code : 1;
+        return { ok: false, stdout: err.stdout ?? "", stderr: err.stderr ?? err.message ?? "", code };
+    }
+}
+export async function installWatcherService(repoRoot, options = {}) {
+    const platform = options.platform ?? os.platform();
+    const kind = detectServicePlatform(platform);
+    const identity = resolveServiceIdentity(repoRoot, platform);
+    const spec = buildSpec(repoRoot, options);
+    const home = options.home ?? os.homedir();
+    switch (kind) {
+        case "systemd": {
+            const unitPath = systemdUserUnitPath(identity.serviceName, home);
+            await fs.mkdir(path.dirname(unitPath), { recursive: true });
+            await fs.writeFile(unitPath, renderSystemdUnit(spec), "utf8");
+            await run("systemctl", ["--user", "daemon-reload"]);
+            const enable = await run("systemctl", ["--user", "enable", "--now", `${identity.serviceName}.service`]);
+            return {
+                ok: enable.ok,
+                platform: kind,
+                serviceName: identity.serviceName,
+                repoRoot: identity.repoRoot,
+                unitPath,
+                message: enable.ok
+                    ? `Installed and started systemd user service ${identity.serviceName}. It will restart on login. (Enable lingering with \`loginctl enable-linger\` to keep it running while logged out.)`
+                    : `Wrote unit to ${unitPath} but \`systemctl --user enable --now\` failed: ${enable.stderr.trim()}`
+            };
+        }
+        case "launchd": {
+            const label = launchdLabelForRepo(repoRoot);
+            const plistPath = launchdPlistPath(label, home);
+            await fs.mkdir(path.dirname(plistPath), { recursive: true });
+            await fs.writeFile(plistPath, renderLaunchdPlist(spec, label), "utf8");
+            // bootout any prior instance so re-install picks up a changed plist, then bootstrap fresh.
+            const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+            await run("launchctl", ["bootout", `gui/${uid}/${label}`]);
+            const load = await run("launchctl", ["bootstrap", `gui/${uid}`, plistPath]);
+            return {
+                ok: load.ok,
+                platform: kind,
+                serviceName: label,
+                repoRoot: identity.repoRoot,
+                unitPath: plistPath,
+                message: load.ok
+                    ? `Installed and loaded launchd agent ${label}. It will start on login and restart on crash.`
+                    : `Wrote plist to ${plistPath} but \`launchctl bootstrap\` failed: ${load.stderr.trim()}`
+            };
+        }
+        case "schtasks": {
+            const taskName = scheduledTaskNameForRepo(repoRoot);
+            const create = await run("schtasks", schtasksCreateArgv(spec, taskName));
+            // schtasks creates the task but doesn't run it immediately for onlogon; kick it once now.
+            if (create.ok)
+                await run("schtasks", ["/run", "/tn", taskName]);
+            return {
+                ok: create.ok,
+                platform: kind,
+                serviceName: identity.serviceName,
+                repoRoot: identity.repoRoot,
+                message: create.ok
+                    ? `Registered scheduled task ${taskName}. It runs on logon and relaunches every few minutes as a liveness backstop (the per-repo lock makes redundant launches no-ops).`
+                    : `\`schtasks /create\` failed: ${create.stderr.trim() || create.stdout.trim()}`
+            };
+        }
+        default:
+            throw new UnsupportedPlatformError(platform);
+    }
+}
+export async function uninstallWatcherService(repoRoot, options = {}) {
+    const platform = options.platform ?? os.platform();
+    const kind = detectServicePlatform(platform);
+    const identity = resolveServiceIdentity(repoRoot, platform);
+    const home = options.home ?? os.homedir();
+    switch (kind) {
+        case "systemd": {
+            const unitPath = systemdUserUnitPath(identity.serviceName, home);
+            await run("systemctl", ["--user", "disable", "--now", `${identity.serviceName}.service`]);
+            await fs.rm(unitPath, { force: true }).catch(() => undefined);
+            await run("systemctl", ["--user", "daemon-reload"]);
+            return {
+                ok: true,
+                platform: kind,
+                serviceName: identity.serviceName,
+                repoRoot: identity.repoRoot,
+                unitPath,
+                message: `Removed systemd user service ${identity.serviceName}.`
+            };
+        }
+        case "launchd": {
+            const label = launchdLabelForRepo(repoRoot);
+            const plistPath = launchdPlistPath(label, home);
+            const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+            await run("launchctl", ["bootout", `gui/${uid}/${label}`]);
+            await fs.rm(plistPath, { force: true }).catch(() => undefined);
+            return {
+                ok: true,
+                platform: kind,
+                serviceName: label,
+                repoRoot: identity.repoRoot,
+                unitPath: plistPath,
+                message: `Removed launchd agent ${label}.`
+            };
+        }
+        case "schtasks": {
+            const taskName = scheduledTaskNameForRepo(repoRoot);
+            const del = await run("schtasks", schtasksDeleteArgv(taskName));
+            return {
+                ok: del.ok,
+                platform: kind,
+                serviceName: identity.serviceName,
+                repoRoot: identity.repoRoot,
+                message: del.ok ? `Removed scheduled task ${taskName}.` : `\`schtasks /delete\` failed (it may not exist): ${del.stderr.trim() || del.stdout.trim()}`
+            };
+        }
+        default:
+            throw new UnsupportedPlatformError(platform);
+    }
+}
+// Whether the OS registrar knows about the service. This is the registration check (is a unit
+// installed?), distinct from runtime liveness (is the watcher process actually alive and
+// heartbeating?), which readWatcherLiveness answers. doctor/status report both.
+export async function watcherServiceStatus(repoRoot, options = {}) {
+    const platform = options.platform ?? os.platform();
+    const kind = detectServicePlatform(platform);
+    const identity = resolveServiceIdentity(repoRoot, platform);
+    const home = options.home ?? os.homedir();
+    switch (kind) {
+        case "systemd": {
+            const unitPath = systemdUserUnitPath(identity.serviceName, home);
+            const exists = await fileExists(unitPath);
+            const active = exists ? await run("systemctl", ["--user", "is-active", `${identity.serviceName}.service`]) : undefined;
+            const state = active ? active.stdout.trim() || active.stderr.trim() : "not-installed";
+            return {
+                ok: true,
+                installed: exists,
+                platform: kind,
+                serviceName: identity.serviceName,
+                repoRoot: identity.repoRoot,
+                unitPath,
+                message: exists ? `systemd user service ${identity.serviceName}: ${state}` : `No systemd user service installed for ${identity.repoRoot}.`
+            };
+        }
+        case "launchd": {
+            const label = launchdLabelForRepo(repoRoot);
+            const plistPath = launchdPlistPath(label, home);
+            const exists = await fileExists(plistPath);
+            const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+            const print = exists ? await run("launchctl", ["print", `gui/${uid}/${label}`]) : undefined;
+            return {
+                ok: true,
+                installed: exists,
+                platform: kind,
+                serviceName: label,
+                repoRoot: identity.repoRoot,
+                unitPath: plistPath,
+                message: exists ? `launchd agent ${label}: ${print?.ok ? "loaded" : "installed but not loaded"}` : `No launchd agent installed for ${identity.repoRoot}.`
+            };
+        }
+        case "schtasks": {
+            const taskName = scheduledTaskNameForRepo(repoRoot);
+            const query = await run("schtasks", schtasksQueryArgv(taskName));
+            return {
+                ok: true,
+                installed: query.ok,
+                platform: kind,
+                serviceName: identity.serviceName,
+                repoRoot: identity.repoRoot,
+                message: query.ok ? `Scheduled task ${taskName} is registered.` : `No scheduled task registered for ${identity.repoRoot}.`
+            };
+        }
+        default:
+            return {
+                ok: false,
+                installed: false,
+                platform: "unsupported",
+                serviceName: identity.serviceName,
+                repoRoot: identity.repoRoot,
+                message: new UnsupportedPlatformError(platform).message
+            };
+    }
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/service/service-templates.d.ts

@@ -0,0 +1,22 @@
+export interface ServiceLaunchSpec {
+    /** Absolute path to the node/bun executable that runs the CLI. */
+    execPath: string;
+    /** Absolute path to the ragcode CLI entry (dist/src/cli/index.js) or a resolvable bin name. */
+    cliEntry: string;
+    repoRoot: string;
+    serviceName: string;
+    /** Extra args appended after `watch <repoRoot>`, e.g. ["--poll"]. */
+    extraArgs?: string[];
+}
+export declare function watchArgv(spec: ServiceLaunchSpec): string[];
+export declare function renderSystemdUnit(spec: ServiceLaunchSpec): string;
+export declare function systemdUserUnitPath(serviceName: string, home?: string): string;
+export declare function renderLaunchdPlist(spec: ServiceLaunchSpec, label: string): string;
+export declare function launchdPlistPath(label: string, home?: string): string;
+export interface SchtasksCreateOptions {
+    /** Minutes between liveness relaunch attempts. Defaults to 5. */
+    restartIntervalMinutes?: number;
+}
+export declare function schtasksCreateArgv(spec: ServiceLaunchSpec, taskName: string, options?: SchtasksCreateOptions): string[];
+export declare function schtasksDeleteArgv(taskName: string): string[];
+export declare function schtasksQueryArgv(taskName: string): string[];

package/dist/src/service/service-templates.js

@@ -0,0 +1,101 @@
+import os from "node:os";
+import path from "node:path";
+export function watchArgv(spec) {
+    return [spec.cliEntry, "watch", spec.repoRoot, "--no-index-on-start", ...(spec.extraArgs ?? [])];
+}
+// ---------------------------------------------------------------------------
+// systemd (Linux) — user unit, no root. Restart=always survives crashes; the OS user session
+// manager (re)starts it on login when enabled. WorkingDirectory pins relative config resolution.
+// ---------------------------------------------------------------------------
+export function renderSystemdUnit(spec) {
+    const execStart = [spec.execPath, ...watchArgv(spec)].map(systemdQuote).join(" ");
+    return `[Unit]
+Description=RagCode background watcher for ${spec.repoRoot}
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=${execStart}
+WorkingDirectory=${spec.repoRoot}
+Restart=always
+RestartSec=5
+# Avoid a crash-loop hammering CPU if the repo is broken; give up after repeated fast failures
+# and let the user re-enable via 'ragcode service install'.
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+[Install]
+WantedBy=default.target
+`;
+}
+// systemd ExecStart tokens are space-split; wrap tokens containing spaces in double quotes.
+function systemdQuote(token) {
+    return /\s/.test(token) ? `"${token.replace(/"/g, '\\"')}"` : token;
+}
+export function systemdUserUnitPath(serviceName, home = os.homedir()) {
+    return path.join(home, ".config", "systemd", "user", `${serviceName}.service`);
+}
+// ---------------------------------------------------------------------------
+// launchd (macOS) — LaunchAgent plist. KeepAlive restarts on crash; RunAtLoad starts on login.
+// ---------------------------------------------------------------------------
+export function renderLaunchdPlist(spec, label) {
+    const programArgs = [spec.execPath, ...watchArgv(spec)]
+        .map((arg) => `    <string>${escapeXml(arg)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${programArgs}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(spec.repoRoot)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
+</dict>
+</plist>
+`;
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+export function launchdPlistPath(label, home = os.homedir()) {
+    return path.join(home, "Library", "LaunchAgents", `${label}.plist`);
+}
+export function schtasksCreateArgv(spec, taskName, options = {}) {
+    // schtasks /tr takes a single string; quote each token so paths with spaces survive.
+    const command = [spec.execPath, ...watchArgv(spec)].map(windowsQuote).join(" ");
+    const interval = options.restartIntervalMinutes ?? 5;
+    return [
+        "/create",
+        "/tn", taskName,
+        "/tr", command,
+        "/sc", "onlogon",
+        "/rl", "limited",
+        // Keep the task alive: repeat every N minutes indefinitely. The lock makes redundant launches no-ops.
+        "/ri", String(interval),
+        "/du", "9999:59",
+        "/f"
+    ];
+}
+export function schtasksDeleteArgv(taskName) {
+    return ["/delete", "/tn", taskName, "/f"];
+}
+export function schtasksQueryArgv(taskName) {
+    return ["/query", "/tn", taskName];
+}
+// schtasks /tr is a single command string; wrap tokens with spaces in double quotes.
+function windowsQuote(token) {
+    return /\s/.test(token) ? `"${token}"` : token;
+}

package/dist/src/subgraph/impact-explainer.d.ts

@@ -0,0 +1,2 @@
+import type { ExplainImpactReport, VerifiedCodeSubgraph } from "../core/types.js";
+export declare function buildExplainImpactReport(target: string, subgraph: VerifiedCodeSubgraph): ExplainImpactReport;

package/dist/src/subgraph/impact-explainer.js

@@ -0,0 +1,54 @@
+export function buildExplainImpactReport(target, subgraph) {
+    const callerCount = subgraph.nodes.filter((node) => node.role === "caller").length;
+    const routeCount = subgraph.nodes.filter((node) => node.role === "route").length;
+    const testCount = subgraph.nodes.filter((node) => node.role === "test").length;
+    const exportedTargets = subgraph.nodes.filter((node) => node.role === "target" && node.exported).length;
+    const unresolvedCount = subgraph.edges.filter((edge) => edge.confidence === "low" || edge.source === "heuristic").length;
+    const truncated = subgraph.coverage.some((signal) => signal.name === "budget_truncated" && signal.status === "fail");
+    const noPrimaryOwner = subgraph.coverage.some((signal) => signal.name === "primary_owner_found" && signal.status === "fail");
+    let riskScore = 0;
+    riskScore += callerCount * 2;
+    riskScore += routeCount * 2;
+    riskScore += exportedTargets * 3;
+    riskScore += unresolvedCount * 3;
+    if (testCount === 0)
+        riskScore += 2;
+    if (truncated)
+        riskScore += 2;
+    if (noPrimaryOwner)
+        riskScore += 5;
+    const riskReasons = [];
+    if (callerCount > 0)
+        riskReasons.push(`${callerCount} caller node(s) are in the blast radius.`);
+    if (routeCount > 0)
+        riskReasons.push(`${routeCount} route/API node(s) are in the blast radius.`);
+    if (exportedTargets > 0)
+        riskReasons.push(`${exportedTargets} exported target node(s) may be public API surface.`);
+    if (testCount === 0)
+        riskReasons.push("No explicit tested_by edge was found for the selected target.");
+    if (unresolvedCount > 0)
+        riskReasons.push(`${unresolvedCount} unresolved or heuristic edge(s) need manual verification.`);
+    if (truncated)
+        riskReasons.push("The impact subgraph was truncated by budget.");
+    if (noPrimaryOwner)
+        riskReasons.push("No primary indexed owner matched the impact target.");
+    if (riskReasons.length === 0)
+        riskReasons.push("Impact is limited to a small verified internal subgraph with test evidence.");
+    const riskLevel = riskScore >= 9 ? "high" : riskScore >= 4 ? "medium" : "low";
+    const editReadiness = readinessFor(subgraph, riskLevel, noPrimaryOwner, unresolvedCount);
+    return {
+        target,
+        riskLevel,
+        riskScore,
+        riskReasons,
+        editReadiness,
+        subgraph
+    };
+}
+function readinessFor(subgraph, riskLevel, noPrimaryOwner, unresolvedCount) {
+    if (subgraph.coverageSummary.verdict === "not_enough_context" || !subgraph.answerable || noPrimaryOwner)
+        return "not_enough_context";
+    if (riskLevel === "high" || unresolvedCount > 0)
+        return "investigate_only";
+    return subgraph.coverageSummary.verdict;
+}

package/dist/src/subgraph/node-expander.d.ts

@@ -0,0 +1,13 @@
+import type { CodeChunk, ExpandNodeResult, ExpansionLevel, SymbolNode } from "../core/types.js";
+export interface ExpandNodeBuildInput {
+    nodeRef: string;
+    chunks: CodeChunk[];
+    symbols: SymbolNode[];
+    expansionLevel?: ExpansionLevel;
+    budgetChars?: number;
+}
+export declare function expandNode(input: ExpandNodeBuildInput): ExpandNodeResult;
+export declare function parseNodeRef(nodeRef: string): {
+    filePath: string;
+    symbolName?: string;
+};