knodin 0.7.6 → 0.8.2

package/dist/src/docs-sections.js

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const DOCS_SECTIONS = {
+    quickstart: `# Quickstart Guide
+
+knodin — source-evidenced local code intelligence with known bounds. It builds a semantic and syntactic knowledge graph of your repository and exposes five primary operations through its MCP tool gateway or CLI:
+
+1. **context**: Orient on a repository. Returns high-level statistics, key subsystems/hubs/flows, a heuristic next-operation recommendation, and a diff-based risk score if changes are detected.
+2. **explain**: Understand a specific symbol (function, class, or file). Returns edit-ready source code, inbound/outbound call paths, and blast radius (transitive callers).
+3. **review**: Analyze local modifications. Displays risk-scored changes, affected execution flows, and missing test coverage before you commit or create a PR.
+4. **map**: Visualize subsystem boundaries. Partitions the code into cohesive modular communities using Louvain community detection.
+5. **search**: Fuzzy semantic and keyword lookup to find symbols when you do not know their exact name.
+
+### Command Usage (CLI)
+\`\`\`bash
+knodin context "explore auth"
+knodin explain login
+knodin map
+\`\`\``,
+    "query-patterns": `# Structured Query Patterns
+
+The \`query\` operation lets you ask precise, structured questions about your code using a variety of built-in graph patterns:
+
+- **callers_of <target>**: Who invokes this symbol (transitive/direct).
+- **callees_of <target>**: What other symbols does this symbol invoke.
+- **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.
+- **impact <symbol>**: Directional, depth-bounded symbol reach with stable selectors, relation/confidence/test filters, edge evidence, and heuristic summaries. Use \`impactMode: "file"\` explicitly for a distinctly labeled changed-file blast radius.
+- **dead_code**: Surface exported or unexported symbols with zero references.
+- **large_functions / large_files**: Spot complex "god" functions and files exceeding size thresholds.
+- **traverse <symbol>**: Perform a bounded BFS neighborhood walk. Use \`direction\` (\`upstream|downstream|both\`), \`relationKinds\`, and optional \`includeDataFlow\`; every discovered hop carries its exact kind, direction, confidence, provenance, source line, and files. Call arguments are labeled heuristic source evidence, never runtime proof.
+- **knowledge_gaps**: Report repo-health weaknesses like thin communities (<3 symbols) and untested hubs/bridges.
+- **surprising_connections**: Score and rank coupling that crosses community, language, or test boundaries.
+- **suggested_questions**: prioritizes human-readable review prompts based on untested hotspots and high-surprise edges.
+- **architecture_overview**: Formats community cohesion and coupling plus independently selectable \`architectureFacets\`: packages, layers, boundaries, hotspots, entryPoints, and languages. \`path\` scopes every facet consistently.`,
+    federation: `# Cross-Repository Composition
+
+Federation is knodin's internal query-composition mechanism, not the primary
+user-facing model. Use \`knodin repos\` for operational checkout management and
+\`knodin system\` with commit-ready \`knodin.yaml\` stable identities for
+cooperating components. Sibling directory placement and shared search matches
+never establish system membership.
+
+Legacy \`.knodin/federation.json\` remains a compatibility input and is not
+silently discarded. Migrate it to \`knodin.yaml\` plus personal XDG checkout
+paths. The \`federated_repos\` query remains available for inspecting the
+engine's currently composed repository paths; it does not prove those
+repositories form one system.`,
+    "rename-safety": `# Rename Safety and Refactoring
+
+knodin provides an AST-backed, type-safe refactoring pipeline for renaming symbols.
+
+### Two-Step Pipeline
+1. **Dry-Run (default)**: Returns every edit site (definitions, references, imports) and generates a unified diff. Refuses to make changes if there's an ambiguity or conflict.
+2. **Apply (\`apply: true\` or \`--apply\`)**: Atomically writes line-scoped word-boundary edits to disk and triggers an automatic reindexing of touched files.
+
+### Safety Guards
+The engine refuses to write to disk and rolls back any changes if:
+- **Ambiguity**: The old symbol name resolves to more than one definition file.
+- **Collision**: The new name already exists as a symbol in any of the edit-site files.
+- **Out of Scope**: The edit targets files outside the repository.
+- **Type Errors**: If verification is enabled (default), it verifies the workspace compiles successfully using \`tsc\` (or equivalent) after applying the edit, and automatically rolls back if compilation fails.`,
+    "language-support": `# Language and Metadata Support
+
+knodin is multi-language, not language-universal.
+
+### Native syntax
+TypeScript (\`.ts/.tsx/.mts/.cts\`), JavaScript (\`.js/.jsx/.mjs/.cjs\`), Python, Java, C#, Salesforce Apex, SQL/PLSQL, Prisma, and XML-backed formats.
+
+### Domain-specific structure
+Salesforce LWC, Aura, Visualforce, Experience Cloud, and selected Salesforce DX metadata/automations; Terraform/HCL; Dockerfiles; dbt manifests; and Workday Studio XML.
+
+### Imported graph
+LSIF can import symbols and relationships produced by a compatible language server. This is not native parsing.
+
+Go, Rust, PHP, Ruby, Kotlin, Swift, Perl, PowerShell, Bash, and MuleSoft/RAML are known native-parser gaps. Coverage differs by language, and static dead-code candidates must be corroborated when runtime or platform configuration can invoke code dynamically. Salesforce candidates should be checked against deployed-org and platform dependency data before deletion.`,
+    troubleshooting: `# Troubleshooting and Recovery
+
+### Index health and surgical repair
+
+Run \`knodin status\` (or MCP \`operation: "status"\`) to inspect the local schema/model/version, file and symbol coverage, orphaned or missing records, and the last successful reconciliation. Its repair steps are actionable. Run \`knodin repair\` (or MCP \`operation: "repair"\`) to rebuild only missing/damaged rows and verify health; healthy indexed files are not deleted or rebuilt.
+
+The MCP \`telemetry\` operation reads process-local metadata-only measurements: actual response bytes and \`gpt-tokenizer@3.4.0:o200k_base\` tokens, executed baselines where available, negative or positive savings, latency, RSS, schema cost, truncation, and detail mode. It never contains source or file paths and does not change existing operation response shapes. Telemetry is not persisted by default. Set MCP \`persistTelemetry: true\` to append metadata-only JSONL to the repo-root \`.knodin-telemetry.jsonl\`; knodin never sends it over the network. Use \`telemetryAction: "report"\` or \`knodin telemetry report\` for a static repository-local HTML report.
+
+Common issues and how to resolve them when using knodin:
+
+### Corrupt Embedding Row
+If you see warnings like \`Skipping corrupt embedding... dimension mismatch\`, your index database contains malformed embeddings.
+- **Fix**: Force a clean re-index of the repository to rebuild the vector store.
+\`\`\`bash
+# Prefer surgical local repair; it preserves healthy state
+knodin repair
+\`\`\`
+
+### Missing 'gh' CLI Dependency
+The \`prs\` triage operation requires the official GitHub CLI (\`gh\`) to be installed, in your PATH, and authenticated.
+- **Fix**: Run \`gh auth login\` to authenticate locally.
+
+### Legacy federation configuration
+If legacy federation configuration fails, validate
+\`.knodin/federation.json\`, then migrate stable identities to \`knodin.yaml\`
+and local paths to XDG configuration. Do not infer membership from siblings.`,
+};
+const DOC_TOPIC_FILES = {
+    installation: "INSTALLATION.md",
+    mcp: "MCP.md",
+    repositories: "REPOSITORIES-AND-WORKTREES.md",
+    systems: "SYSTEMS-AND-RELATIONSHIPS.md",
+    provenance: "INDEXING-POLICY-AND-PROVENANCE.md",
+    "dead-code": "DEAD-CODE-AND-IMPACT.md",
+    doctor: "DOCTOR-AND-UPDATES.md",
+    compression: "COMMAND-OUTPUT-COMPRESSION.md",
+};
+function packageRoot() {
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (!fs.existsSync(path.join(current, "package.json")) &&
+        current !== path.parse(current).root) {
+        current = path.dirname(current);
+    }
+    return current;
+}
+export function listDocTopics() {
+    return [...new Set([...Object.keys(DOCS_SECTIONS), ...Object.keys(DOC_TOPIC_FILES)])].sort((left, right) => left.localeCompare(right));
+}
+/** Read canonical long-form guides directly so CLI and MCP cannot drift from Markdown. */
+export function getDocSection(topic) {
+    const file = DOC_TOPIC_FILES[topic];
+    if (file) {
+        try {
+            return fs.readFileSync(path.join(packageRoot(), "docs", file), "utf-8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    return DOCS_SECTIONS[topic];
+}

package/dist/src/doctor.js

@@ -0,0 +1,382 @@
+import child_process from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { detectSupportedAgents } from "./agent-integration.js";
+import { inspectLifecycleHealth } from "./lifecycle-health.js";
+import { trustedUpdateStatus } from "./update-policy.js";
+function defaultRun(command, args, options = {}) {
+    const result = child_process.spawnSync(command, args, {
+        encoding: "utf-8",
+        input: options.input,
+        timeout: 5_000,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? result.error?.message ?? "",
+    };
+}
+function managerEvidence(executable, env) {
+    const explicit = [
+        ["mise", env.MISE_DATA_DIR ?? env.MISE_ENV, "MISE_DATA_DIR or MISE_ENV is set"],
+        ["volta", env.VOLTA_HOME, "VOLTA_HOME is set"],
+        ["nvm", env.NVM_BIN ?? env.NVM_DIR, "NVM_BIN or NVM_DIR is set"],
+        ["fnm", env.FNM_DIR ?? env.FNM_MULTISHELL_PATH, "FNM_DIR or FNM_MULTISHELL_PATH is set"],
+        ["asdf", env.ASDF_DIR ?? env.ASDF_DATA_DIR, "ASDF_DIR or ASDF_DATA_DIR is set"],
+        ["homebrew", env.HOMEBREW_PREFIX, "HOMEBREW_PREFIX is set"],
+    ];
+    for (const [name, value, evidence] of explicit) {
+        if (value)
+            return { name, confidence: "high", evidence: [evidence] };
+    }
+    const lower = executable.toLowerCase();
+    for (const [needle, name] of [
+        ["/.local/share/mise/", "mise"],
+        ["/.volta/", "volta"],
+        ["/.nvm/", "nvm"],
+        ["/fnm", "fnm"],
+        ["/.asdf/", "asdf"],
+        ["/homebrew/", "homebrew"],
+    ]) {
+        if (lower.includes(needle)) {
+            return {
+                name,
+                confidence: "medium",
+                evidence: [`resolved executable path contains ${needle}; path heuristic only`],
+            };
+        }
+    }
+    return {
+        name: "unknown",
+        confidence: "low",
+        evidence: ["no manager-owned environment evidence; executable path alone is inconclusive"],
+    };
+}
+function symlinkChain(executable) {
+    const chain = [path.resolve(executable)];
+    for (let count = 0; count < 16; count++) {
+        const current = chain.at(-1);
+        if (!current)
+            break;
+        try {
+            if (!fs.lstatSync(current).isSymbolicLink()) {
+                const canonical = fs.realpathSync(current);
+                if (canonical !== current)
+                    chain.push(canonical);
+                break;
+            }
+            const target = fs.readlinkSync(current);
+            const resolved = path.resolve(path.dirname(current), target);
+            if (chain.includes(resolved))
+                break;
+            chain.push(resolved);
+        }
+        catch {
+            break;
+        }
+    }
+    return chain;
+}
+function executableCandidates(env) {
+    const candidates = [];
+    for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+        if (!directory)
+            continue;
+        const candidate = path.join(directory, process.platform === "win32" ? "knodin.cmd" : "knodin");
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            const resolved = fs.realpathSync(candidate);
+            if (!candidates.includes(resolved))
+                candidates.push(resolved);
+        }
+        catch {
+            // Not an executable candidate.
+        }
+    }
+    return candidates;
+}
+function runtimeTarget(command) {
+    const [executable, ...arguments_] = command;
+    if (!executable)
+        return "";
+    const basename = path.basename(executable).toLowerCase();
+    if (basename === "node" ||
+        basename === "node.exe" ||
+        basename === "bun" ||
+        basename === "tsx" ||
+        basename === "tsx.cmd") {
+        const valueFlags = new Set([
+            "--import",
+            "--loader",
+            "--experimental-loader",
+            "--require",
+            "-r",
+        ]);
+        for (let index = 0; index < arguments_.length; index++) {
+            const argument = arguments_[index];
+            if (valueFlags.has(argument)) {
+                index++;
+                continue;
+            }
+            if (argument.startsWith("-"))
+                continue;
+            return argument;
+        }
+    }
+    return executable;
+}
+function sanitizeRegistry(raw) {
+    const value = raw.trim();
+    try {
+        const parsed = new URL(value);
+        parsed.username = "";
+        parsed.password = "";
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString();
+    }
+    catch {
+        return "unknown";
+    }
+}
+function readAgentConfig(agent, file) {
+    try {
+        const content = fs.readFileSync(file, "utf-8");
+        if (agent === "claude" && path.basename(file) === ".claude.json") {
+            const present = content.includes('"knodin"');
+            return { agent, file, present, command: present ? "knodin" : null, args: ["serve"] };
+        }
+        if (file.endsWith(".toml")) {
+            const sectionStart = content.indexOf('[mcp_servers."knodin"]');
+            const sectionTail = sectionStart >= 0 ? content.slice(sectionStart) : "";
+            const nextSection = sectionTail.indexOf("\n[", 1);
+            const block = nextSection >= 0 ? sectionTail.slice(0, nextSection) : sectionTail;
+            const command = /^[ \t]*command[ \t]*=[ \t]*"([^"\r\n]+)"/m.exec(block)?.[1];
+            const args = /^[ \t]*args[ \t]*=[ \t]*\[([^\]]*)\]/m
+                .exec(block)?.[1]
+                ?.split(",")
+                .map((value) => value.trim().replace(/^"|"$/g, ""))
+                .filter(Boolean);
+            return {
+                agent,
+                file,
+                present: sectionStart >= 0,
+                command: command ?? null,
+                args: args ?? [],
+            };
+        }
+        const document = JSON.parse(content);
+        const registration = document.mcpServers?.knodin ?? document.servers?.knodin;
+        return {
+            agent,
+            file,
+            present: registration !== undefined,
+            command: typeof registration?.command === "string" ? registration.command : null,
+            args: Array.isArray(registration?.args)
+                ? registration.args.filter((value) => typeof value === "string")
+                : [],
+        };
+    }
+    catch {
+        return { agent, file, present: false, command: null, args: [] };
+    }
+}
+function configuredAgentCommands(repo) {
+    const candidates = [
+        { agent: "claude", file: ".mcp.json" },
+        { agent: "codex", file: ".codex/config.toml" },
+        { agent: "gemini", file: ".gemini/settings.json" },
+        { agent: "copilot", file: ".vscode/mcp.json" },
+        { agent: "antigravity", file: ".agents/mcp_config.json" },
+    ];
+    return candidates.map(({ agent, file }) => readAgentConfig(agent, path.join(repo, file)));
+}
+function personalAgentCommands(homeDir) {
+    return [
+        readAgentConfig("claude", path.join(homeDir, ".claude.json")),
+        readAgentConfig("codex", path.join(homeDir, ".codex", "config.toml")),
+        readAgentConfig("gemini", path.join(homeDir, ".gemini", "settings.json")),
+        readAgentConfig("copilot", path.join(homeDir, "Library", "Application Support", "Code", "User", "mcp.json")),
+        readAgentConfig("antigravity", path.join(homeDir, ".agents", "mcp_config.json")),
+    ];
+}
+function installedPackageVersion(executable) {
+    let directory = path.dirname(executable);
+    for (let depth = 0; depth < 6; depth++) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(directory, "package.json"), "utf-8"));
+            if (manifest.name === "knodin" && typeof manifest.version === "string")
+                return manifest.version;
+        }
+        catch {
+            // Continue toward the package root.
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return "unknown";
+}
+function managerRemediation(manager, version) {
+    if (manager === "mise")
+        return `mise use --global npm:knodin@${version}`;
+    if (manager === "volta")
+        return `volta install knodin@${version}`;
+    if (manager === "homebrew")
+        return "brew update && brew upgrade knodin";
+    if (manager === "nvm")
+        return `nvm use 24 && npm install --global --ignore-scripts knodin@${version}`;
+    if (manager === "fnm")
+        return `fnm use 24 && npm install --global --ignore-scripts knodin@${version}`;
+    if (manager === "asdf")
+        return `asdf set nodejs 24 && npm install --global --ignore-scripts knodin@${version}`;
+    return `npm install --global --ignore-scripts knodin@${version}`;
+}
+function parseMcp(output) {
+    const messages = output
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+    const initialize = messages.find(({ id }) => id === 1);
+    const tools = messages.find(({ id }) => id === 2);
+    const initializeResult = initialize?.result;
+    const toolsResult = tools?.result;
+    const names = (toolsResult?.tools ?? []).flatMap(({ name }) => typeof name === "string" ? [name] : []);
+    return {
+        initialize: initializeResult?.serverInfo ? "ok" : "failed",
+        toolsList: names.length > 0 ? "ok" : "failed",
+        serverVersion: typeof initializeResult?.serverInfo?.version === "string"
+            ? initializeResult.serverInfo.version
+            : undefined,
+        toolNames: names,
+    };
+}
+function mcpProbe(command, run) {
+    const input = [
+        JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-11-25",
+                capabilities: {},
+                clientInfo: { name: "knodin-doctor", version: "1" },
+            },
+        }),
+        JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }),
+        JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }),
+        "",
+    ].join("\n");
+    const [executable, ...args] = command;
+    if (!executable)
+        return { initialize: "failed", toolsList: "failed", toolNames: [], stderr: "no command" };
+    const result = run(executable, args, { input });
+    return { ...parseMcp(result.stdout), stderr: result.status === 0 ? undefined : result.stderr };
+}
+export async function diagnoseInstallation(repoPath, options) {
+    const repo = path.resolve(repoPath);
+    const env = options.env ?? process.env;
+    const run = options.run ?? defaultRun;
+    const executable = runtimeTarget(options.runtimeCommand);
+    const chain = symlinkChain(executable);
+    const candidates = executableCandidates(env);
+    const npmPrefix = run("npm", ["config", "get", "prefix"]);
+    const npmRegistry = run("npm", ["config", "get", "registry"]);
+    const mcp = mcpProbe(options.runtimeCommand, run);
+    const runtimeVersion = mcp.serverVersion;
+    const lifecycle = inspectLifecycleHealth(repo);
+    const detectedAgents = detectSupportedAgents();
+    const repositoryCommands = configuredAgentCommands(repo);
+    const personalCommands = personalAgentCommands(options.homeDir ?? os.homedir());
+    const clients = repositoryCommands
+        .filter(({ agent }) => options.client === undefined || options.client === agent)
+        .map((repository) => {
+        const personal = personalCommands.find(({ agent }) => agent === repository.agent);
+        const configured = repository.present || personal?.present === true;
+        return {
+            client: repository.agent,
+            detected: detectedAgents.includes(repository.agent),
+            repository,
+            personal,
+            server: {
+                initialize: mcp.initialize,
+                toolsList: mcp.toolsList,
+                toolNames: mcp.toolNames,
+            },
+            activeSessionExposure: "unknown",
+            note: repository.agent === "claude"
+                ? ".mcp.json is Claude project configuration, not a universal MCP registration."
+                : "Configuration presence does not prove that the active client session loaded it.",
+            remediation: configured
+                ? "Restart or reload the client, then verify its active tools list."
+                : `Run \`knodin configure --scope personal\` or \`knodin configure --scope team\` for ${repository.agent}.`,
+        };
+    });
+    const manager = managerEvidence(chain.at(-1) ?? executable, env);
+    const packageVersion = installedPackageVersion(chain.at(-1) ?? executable);
+    return {
+        schemaVersion: 1,
+        status: options.graph.status === "healthy" &&
+            mcp.initialize === "ok" &&
+            mcp.toolsList === "ok" &&
+            candidates.length <= 1
+            ? "healthy"
+            : "attention-required",
+        versions: {
+            package: packageVersion,
+            cli: runtimeVersion ?? "unknown",
+            source: options.currentVersion,
+            agree: runtimeVersion === options.currentVersion &&
+                (packageVersion === "unknown" || packageVersion === options.currentVersion),
+        },
+        runtime: {
+            node: process.version,
+            platform: process.platform,
+            arch: process.arch,
+        },
+        npm: {
+            prefix: npmPrefix.status === 0 ? npmPrefix.stdout.trim() : "unknown",
+            registry: npmRegistry.status === 0 ? sanitizeRegistry(npmRegistry.stdout) : "unknown",
+        },
+        manager,
+        executable: {
+            resolved: chain.at(-1) ?? executable,
+            chain,
+            candidates,
+            conflicts: candidates.filter((candidate) => candidate !== chain.at(-1)),
+        },
+        agents: {
+            detected: detectedAgents,
+            configuredCommands: repositoryCommands,
+            clients,
+        },
+        mcp,
+        lifecycle,
+        graph: options.graph,
+        update: trustedUpdateStatus({
+            currentVersion: options.currentVersion,
+            stateHome: options.cacheHome,
+            installMethod: manager.name,
+            env,
+        }),
+        remediation: {
+            manager: managerRemediation(manager.name, options.currentVersion),
+            duplicates: candidates.length > 1
+                ? "Remove only the unintended manager-owned installation, then rerun `knodin doctor`."
+                : null,
+            graph: options.graph.status === "healthy"
+                ? null
+                : "Run `knodin repair`, then `knodin status --deep`.",
+        },
+    };
+}