agent-bober 0.12.0 → 0.17.0

package/dist/graph/onboarding-composer.js

@@ -0,0 +1,275 @@
+/**
+ * OnboardingComposer — pure renderer for .bober/onboarding/ markdown artifacts.
+ *
+ * Key design invariants:
+ * - render() is PURE. No I/O. Same inputs → same outputs.
+ * - writeAll() is the ONLY method that touches disk.
+ * - Marker convention guards human edits from being overwritten.
+ * - All markdown output is GFM-compatible (no extensions).
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+// ── Marker ─────────────────────────────────────────────────────────
+const MARKER = "<!-- generated by agent-bober — DO NOT EDIT below this line -->";
+// ── Pure renderer ─────────────────────────────────────────────────
+export class OnboardingComposer {
+    /**
+     * Pure renderer. Takes typed inputs, returns 5 markdown strings.
+     * No I/O. No side effects. Deterministic.
+     */
+    render(inputs) {
+        return {
+            readme: renderReadme(inputs),
+            architectureOverview: renderArchitectureOverview(inputs),
+            hotspots: renderHotspots(inputs),
+            knowledgeGaps: renderKnowledgeGaps(inputs),
+            communities: renderCommunities(inputs),
+        };
+    }
+    /**
+     * Write all 5 artifacts to `dir`, creating it if necessary.
+     *
+     * Marker convention:
+     * - File absent → write `${MARKER}\n\n${content}`.
+     * - File with marker → preserve everything above, replace below with `${MARKER}\n\n${content}`.
+     * - File without marker → throw with clear error (refuse to clobber user content).
+     *
+     * @param artifacts Result of render()
+     * @param dir       Target directory (created if missing)
+     */
+    async writeAll(artifacts, dir) {
+        if (!dir || dir.trim() === "") {
+            throw new Error("writeAll: dir argument must be a non-empty path.");
+        }
+        await mkdir(dir, { recursive: true });
+        const files = [
+            ["README.md", artifacts.readme],
+            ["architecture-overview.md", artifacts.architectureOverview],
+            ["hotspots.md", artifacts.hotspots],
+            ["knowledge-gaps.md", artifacts.knowledgeGaps],
+            ["communities.md", artifacts.communities],
+        ];
+        for (const [filename, content] of files) {
+            await writeWithMarker(join(dir, filename), content);
+        }
+    }
+}
+// ── File write helper ─────────────────────────────────────────────
+async function writeWithMarker(filePath, content) {
+    let existing = null;
+    try {
+        existing = await readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        // File doesn't exist — proceed with fresh write
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    if (existing === null) {
+        // File doesn't exist — write with marker
+        await writeFile(filePath, `${MARKER}\n\n${content}`, "utf-8");
+        return;
+    }
+    const markerIndex = existing.indexOf(MARKER);
+    if (markerIndex === -1) {
+        // File exists but has no marker — refuse to overwrite
+        const file = filePath.split("/").pop() ?? filePath;
+        throw new Error(`Refusing to overwrite ${file}: missing generation marker. Add the marker manually or delete the file.`);
+    }
+    // File has marker — preserve above, replace below
+    const above = existing.slice(0, markerIndex);
+    await writeFile(filePath, `${above}${MARKER}\n\n${content}`, "utf-8");
+}
+// ── README.md renderer ────────────────────────────────────────────
+function renderReadme(inputs) {
+    const generatedAt = new Date().toISOString();
+    const { tokensaveVersion, indexedFileCount } = inputs.status;
+    const lines = [];
+    lines.push("# Onboarding — agent-bober graph");
+    lines.push("");
+    lines.push(`_Generated at: ${generatedAt}_`);
+    lines.push("");
+    lines.push(`This codebase is indexed with agent-bober graph v${tokensaveVersion}. ` +
+        `The graph currently covers ${indexedFileCount} ${indexedFileCount === 1 ? "file" : "files"}. ` +
+        `Use the documents below to quickly orient yourself to the architecture, locate high-complexity areas, ` +
+        `identify potentially unused code, and understand how modules are grouped into communities.`);
+    lines.push("");
+    lines.push("## Where to look");
+    lines.push("");
+    lines.push("- [Architecture Overview](./architecture-overview.md) — public API per module");
+    lines.push("- [Hotspots](./hotspots.md) — high-complexity symbols worth reviewing");
+    lines.push("- [Knowledge Gaps](./knowledge-gaps.md) — dead code and uncalled public APIs");
+    lines.push("- [Communities](./communities.md) — module groupings");
+    lines.push("- [README](./README.md) — this file");
+    return lines.join("\n") + "\n";
+}
+// ── architecture-overview.md renderer ────────────────────────────
+function renderArchitectureOverview(inputs) {
+    const lines = [];
+    lines.push("# Architecture Overview");
+    lines.push("");
+    // Dedup modules: if duplicates exist, merge their symbols
+    const merged = mergeModuleApis(inputs.moduleApis);
+    // Sort alphabetically by module name
+    const sorted = merged.slice().sort((a, b) => a.module.localeCompare(b.module));
+    if (sorted.length === 0) {
+        lines.push("_No modules found._");
+        return lines.join("\n") + "\n";
+    }
+    for (const mod of sorted) {
+        lines.push(`## ${escapeMarkdown(mod.module)}`);
+        lines.push("");
+        if (mod.symbols.length === 0) {
+            lines.push("_No public API symbols._");
+        }
+        else {
+            for (const sym of mod.symbols) {
+                lines.push(`- \`${sym.name}\` — ${sym.file}:${sym.line}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+// ── hotspots.md renderer ──────────────────────────────────────────
+function renderHotspots(inputs) {
+    const lines = [];
+    lines.push("# Hotspots");
+    lines.push("");
+    if (inputs.hotspots.length === 0) {
+        lines.push("No hotspots detected in this codebase.");
+        return lines.join("\n") + "\n";
+    }
+    // Separate valid scores from NaN scores; sort valid desc, NaN last
+    const withScore = inputs.hotspots.filter((h) => !isNaN(h.score));
+    const nanEntries = inputs.hotspots.filter((h) => isNaN(h.score));
+    const sorted = [
+        ...withScore.slice().sort((a, b) => b.score - a.score),
+        ...nanEntries,
+    ].slice(0, 20);
+    lines.push("| Symbol | File:Line | Complexity Score | Why it matters |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const h of sorted) {
+        const symbol = escapePipe(h.symbol);
+        const fileLine = escapePipe(`${h.file}:${h.line}`);
+        const score = isNaN(h.score) ? "score unavailable" : String(h.score);
+        const reason = escapePipe(h.reason ?? "");
+        lines.push(`| ${symbol} | ${fileLine} | ${score} | ${reason} |`);
+    }
+    return lines.join("\n") + "\n";
+}
+// ── knowledge-gaps.md renderer ────────────────────────────────────
+function renderKnowledgeGaps(inputs) {
+    const lines = [];
+    lines.push("# Knowledge Gaps");
+    lines.push("");
+    // Dead code section
+    lines.push("## Potentially unused (dead code)");
+    lines.push("");
+    if (inputs.deadCode.length === 0) {
+        lines.push("No dead code detected.");
+    }
+    else {
+        for (const dc of inputs.deadCode) {
+            lines.push(`- \`${dc.symbol}\` — ${dc.file}:${dc.line}`);
+        }
+    }
+    lines.push("");
+    // Public APIs without internal callers
+    const uncalledSymbols = [];
+    for (const mod of inputs.moduleApis) {
+        for (const sym of mod.symbols) {
+            if (!sym.hasInternalCallers) {
+                uncalledSymbols.push({ module: mod.module, name: sym.name, file: sym.file, line: sym.line });
+            }
+        }
+    }
+    lines.push("## Public APIs without internal callers");
+    lines.push("");
+    if (uncalledSymbols.length === 0) {
+        lines.push("All public APIs have internal callers.");
+    }
+    else {
+        for (const sym of uncalledSymbols) {
+            lines.push(`- \`${sym.name}\` (${sym.module}) — ${sym.file}:${sym.line}`);
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+// ── communities.md renderer ───────────────────────────────────────
+function renderCommunities(inputs) {
+    const lines = [];
+    lines.push("# Communities");
+    lines.push("");
+    // Group merged modules by community field
+    const merged = mergeModuleApis(inputs.moduleApis);
+    const communityMap = new Map();
+    for (const mod of merged) {
+        const community = mod.community ?? "uncategorized";
+        if (!communityMap.has(community)) {
+            communityMap.set(community, []);
+        }
+        communityMap.get(community).push(mod);
+    }
+    if (communityMap.size === 0) {
+        lines.push("_No communities found._");
+        return lines.join("\n") + "\n";
+    }
+    // Sort communities alphabetically
+    const sortedCommunities = Array.from(communityMap.entries()).sort(([a], [b]) => a.localeCompare(b));
+    for (const [community, mods] of sortedCommunities) {
+        const totalSymbols = mods.reduce((sum, m) => sum + m.symbols.length, 0);
+        lines.push(`## ${escapeMarkdown(community)}`);
+        lines.push("");
+        lines.push(`Module group with ${mods.length} ${mods.length === 1 ? "module" : "modules"} and ${totalSymbols} ${totalSymbols === 1 ? "symbol" : "symbols"}.`);
+        lines.push("");
+        for (const mod of mods.slice().sort((a, b) => a.module.localeCompare(b.module))) {
+            lines.push(`- ${escapeMarkdown(mod.module)}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+/**
+ * Merge duplicate module names. If the same module name appears more than once,
+ * merge their symbols (dedup by name+file+line). Community: use first non-undefined value.
+ */
+function mergeModuleApis(moduleApis) {
+    const seen = new Map();
+    for (const mod of moduleApis) {
+        const existing = seen.get(mod.module);
+        if (!existing) {
+            seen.set(mod.module, {
+                module: mod.module,
+                community: mod.community,
+                symbols: [...mod.symbols],
+            });
+        }
+        else {
+            // Merge symbols
+            const symKeys = new Set(existing.symbols.map((s) => `${s.name}:${s.file}:${s.line}`));
+            for (const sym of mod.symbols) {
+                const key = `${sym.name}:${sym.file}:${sym.line}`;
+                if (!symKeys.has(key)) {
+                    symKeys.add(key);
+                    existing.symbols.push(sym);
+                }
+            }
+            // Preserve community from first entry with a defined value
+            if (existing.community === undefined && mod.community !== undefined) {
+                existing.community = mod.community;
+            }
+        }
+    }
+    return Array.from(seen.values());
+}
+/** Escape pipe characters inside GFM table cells. */
+function escapePipe(s) {
+    return s.replace(/\|/g, "\\|");
+}
+/** Minimal markdown escaping for headings — escapes leading `#` in symbol names. */
+function escapeMarkdown(s) {
+    return s.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+//# sourceMappingURL=onboarding-composer.js.map

package/dist/graph/onboarding-composer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-composer.js","sourceRoot":"","sources":["../../src/graph/onboarding-composer.ts"],"names":[],"mappings":"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"}

package/dist/graph/pipeline-lifecycle.d.ts

@@ -0,0 +1,95 @@
+/**
+ * GraphPipelineLifecycle — singleton that owns the tokensave serve subprocess
+ * for the duration of a single `agent-bober run` pipeline invocation.
+ *
+ * Module-level export guarantees one instance per Node process (ESM singleton).
+ * Importers receive the same object regardless of how many times they import.
+ *
+ * Responsibilities:
+ *   - Read bober.config.json graph section.
+ *   - Run prereq check before spawning.
+ *   - Orphan cleanup via PID file (`.bober/graph/.serve.pid`).
+ *   - SIGTERM/SIGINT handlers for graceful shutdown.
+ *   - Idempotent start() and stop().
+ */
+import type { BoberConfig } from "../config/schema.js";
+import { type EngineHealth } from "./mcp-client.js";
+import { GraphClient } from "./client.js";
+import { GraphFallback } from "./fallback.js";
+declare class GraphPipelineLifecycleImpl {
+    private started;
+    private stopping;
+    private healthOverride;
+    private mcpClient;
+    private store;
+    private incidents;
+    private hookHandler;
+    private projectRoot;
+    private pidPath;
+    private sigHandler;
+    /**
+     * Start the lifecycle.
+     *
+     * - When graph.enabled is false (or graph section is absent): no-op; health = 'disabled'.
+     * - Otherwise: prereq check → orphan cleanup → spawn serve → write PID file → register signals.
+     * - Idempotent: calling start() twice is safe (second call is a no-op).
+     */
+    start(projectRoot: string, config: BoberConfig): Promise<void>;
+    /**
+     * Gracefully stop the lifecycle.
+     * SIGTERM → wait 2000ms (inside mcpClient.stop()) → SIGKILL fallback.
+     * Idempotent.
+     */
+    stop(): Promise<void>;
+    engineHealth(): string;
+    /**
+     * Project root of the active pipeline, or null when not started.
+     *
+     * Used by PreflightContextInjector to resolve a telemetry sink when the
+     * injector was constructed without an explicit projectRoot (the common case
+     * at most agent call sites). Lets graph-preflight telemetry fire for every
+     * role with zero changes to the call sites.
+     */
+    projectRootOrNull(): string | null;
+    /**
+     * Lazy accessor for the GraphClient instance.
+     * Returns null if the engine is not 'ready'.
+     * Caches the constructed client on first call.
+     */
+    private _graphClient;
+    getGraphClient(): GraphClient | null;
+    /**
+     * Returns {client, fallback} when engine is 'ready', null otherwise.
+     * Used by resolveRoleTools to construct gated tool sets.
+     */
+    getGraphDeps(): {
+        client: GraphClient;
+        fallback: GraphFallback;
+    } | null;
+    /**
+     * Reset internal state so tests can call start() again on the same instance.
+     * NOT intended for production use.
+     */
+    _reset(): void;
+    private handleOrphan;
+    private writePidFile;
+    private removePidFile;
+    private registerSignalHandlers;
+    private unregisterSignalHandlers;
+}
+/**
+ * The one and only GraphPipelineLifecycle instance per Node process.
+ *
+ * ESM module caching guarantees this is the same object for all importers
+ * in the same realm — even if imported from multiple modules simultaneously.
+ *
+ * Usage:
+ *   import { graphPipelineLifecycle } from './pipeline-lifecycle.js';
+ *   await graphPipelineLifecycle.start(projectRoot, config);
+ *   // ... pipeline runs ...
+ *   await graphPipelineLifecycle.stop();
+ */
+export declare const graphPipelineLifecycle: GraphPipelineLifecycleImpl;
+export { GraphPipelineLifecycleImpl };
+export type { EngineHealth };
+//# sourceMappingURL=pipeline-lifecycle.d.ts.map

package/dist/graph/pipeline-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-lifecycle.d.ts","sourceRoot":"","sources":["../../src/graph/pipeline-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAKvD,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAExE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAc9C,cAAM,0BAA0B;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAA2B;IACjD,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,UAAU,CAA6B;IAI/C;;;;;;OAMG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkFpE;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC3B,YAAY,IAAI,MAAM;IAQtB;;;;;;;OAOG;IACH,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAMlC;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAA4B;IAEhD,cAAc,IAAI,WAAW,GAAG,IAAI;IAuCpC;;;OAGG;IACH,YAAY,IAAI;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAUvE;;;OAGG;IACH,MAAM,IAAI,IAAI;YAiBA,YAAY;YAyDZ,YAAY;YAaZ,aAAa;IAS3B,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,wBAAwB;CAMjC;AAID;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,4BAAmC,CAAC;AAGvE,OAAO,EAAE,0BAA0B,EAAE,CAAC;AACtC,YAAY,EAAE,YAAY,EAAE,CAAC"}