@n-dx/core 0.1.0

package/packages/sourcevision/dist/analyzers/claude-cli.js

@@ -0,0 +1,137 @@
+/**
+ * Claude CLI integration — spawns the `claude` process and parses stream-json output.
+ */
+import { spawn } from "node:child_process";
+import { IDLE_TIMEOUT_MS, OVERALL_TIMEOUT_MS } from "./enrich-config.js";
+/**
+ * Module-level Claude CLI binary path. Set via `setClaudeBinary()` at CLI
+ * entry points so that all enrichment calls use the resolved path.
+ */
+let _cliBinary = "claude";
+/**
+ * Set the Claude CLI binary path for all subsequent calls.
+ * Call this at CLI entry points after loading unified config.
+ */
+export function setClaudeBinary(binary) {
+    _cliBinary = binary;
+}
+/**
+ * Get the current Claude CLI binary path.
+ */
+export function getClaudeBinary() {
+    return _cliBinary;
+}
+// ── Claude CLI call ──────────────────────────────────────────────────────────
+export async function tryCallClaude(prompt, _timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(_cliBinary, ["-p", "--output-format", "stream-json", "--verbose", "--include-partial-messages"], { stdio: ["pipe", "pipe", "pipe"] });
+        const stderrChunks = [];
+        let resultText = null;
+        let resultTokenUsage;
+        let settled = false;
+        let lastActivity = Date.now();
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearInterval(idleCheck);
+            clearTimeout(overallTimer);
+            resolve(result);
+        };
+        const kill = (reason) => {
+            child.kill("SIGTERM");
+            setTimeout(() => { if (!settled)
+                child.kill("SIGKILL"); }, 5_000);
+            finish({ ok: false, reason: "timeout", detail: reason });
+        };
+        // Idle check: no stdout activity for IDLE_TIMEOUT_MS → stuck
+        const idleCheck = setInterval(() => {
+            if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) {
+                kill(`No output for ${Math.round(IDLE_TIMEOUT_MS / 1000)}s — process appears stuck`);
+            }
+        }, 10_000);
+        // Hard overall cap
+        const overallTimer = setTimeout(() => {
+            kill(`Overall timeout after ${Math.round(OVERALL_TIMEOUT_MS / 1000)}s`);
+        }, OVERALL_TIMEOUT_MS);
+        // Buffer partial lines from stdout (stream-json is newline-delimited)
+        let lineBuf = "";
+        child.stdout.on("data", (chunk) => {
+            lastActivity = Date.now();
+            lineBuf += chunk.toString("utf-8");
+            const lines = lineBuf.split("\n");
+            lineBuf = lines.pop() ?? ""; // keep incomplete trailing line
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const obj = JSON.parse(line);
+                    if (obj.type === "result") {
+                        resultText = typeof obj.result === "string" ? obj.result : null;
+                        resultTokenUsage = parseStreamTokenUsage(obj);
+                    }
+                }
+                catch { /* skip unparseable lines */ }
+            }
+        });
+        child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+        child.on("close", (code) => {
+            const stderrStr = Buffer.concat(stderrChunks).toString("utf-8").trim();
+            if (code === 0 && resultText != null) {
+                finish({ ok: true, response: resultText.trim(), tokenUsage: resultTokenUsage });
+                return;
+            }
+            if (/auth|unauthorized|api.key|credential|login|not logged in/i.test(stderrStr)) {
+                finish({ ok: false, reason: "auth", detail: stderrStr.slice(0, 300) });
+                return;
+            }
+            if (/rate.limit|429|too many requests|overloaded/i.test(stderrStr)) {
+                finish({ ok: false, reason: "rate-limit", detail: stderrStr.slice(0, 300) });
+                return;
+            }
+            finish({ ok: false, reason: "unknown", detail: (stderrStr || `Exit code ${code}`).slice(0, 300) });
+        });
+        child.on("error", (err) => {
+            finish({ ok: false, reason: "unknown", detail: err.message.slice(0, 300) });
+        });
+        // Write prompt to stdin and close it
+        child.stdin.write(prompt, "utf-8");
+        child.stdin.end();
+    });
+}
+// ── Token usage parsing ──────────────────────────────────────────────────────
+/**
+ * Parse token usage from a stream-json result event.
+ * Claude CLI stream-json result events may include token usage at the top level
+ * or nested under a `usage` property.
+ */
+export function parseStreamTokenUsage(obj) {
+    // Try direct fields first (some CLI versions)
+    let input = obj.input_tokens ?? obj.total_input_tokens;
+    let output = obj.output_tokens ?? obj.total_output_tokens;
+    let cacheCreation = obj.cache_creation_input_tokens;
+    let cacheRead = obj.cache_read_input_tokens;
+    // Try nested usage object (stream-json format)
+    if (typeof input !== "number" && typeof output !== "number" && obj.usage && typeof obj.usage === "object") {
+        const usage = obj.usage;
+        input = usage.input_tokens ?? usage.total_input_tokens;
+        output = usage.output_tokens ?? usage.total_output_tokens;
+        cacheCreation = usage.cache_creation_input_tokens;
+        cacheRead = usage.cache_read_input_tokens;
+    }
+    if (typeof input !== "number" && typeof output !== "number") {
+        return undefined;
+    }
+    const tokenUsage = {
+        input: typeof input === "number" ? input : 0,
+        output: typeof output === "number" ? output : 0,
+    };
+    if (typeof cacheCreation === "number" && cacheCreation > 0) {
+        tokenUsage.cacheCreationInput = cacheCreation;
+    }
+    if (typeof cacheRead === "number" && cacheRead > 0) {
+        tokenUsage.cacheReadInput = cacheRead;
+    }
+    return tokenUsage;
+}
+//# sourceMappingURL=claude-cli.js.map

package/packages/sourcevision/dist/analyzers/claude-cli.js.map

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

package/packages/sourcevision/dist/analyzers/claude-client.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sourcevision LLM bridge — uses @n-dx/llm-client for vendor-aware access.
+ */
+import type { ClaudeConfig, ClaudeClient, AuthMode, LLMConfig, LLMVendor } from "@n-dx/llm-client";
+import type { TokenUsage } from "../schema/index.js";
+export { ClaudeClientError } from "@n-dx/llm-client";
+export declare const DEFAULT_MODEL = "claude-sonnet-4-6";
+export declare const DEFAULT_CODEX_MODEL = "gpt-5-codex";
+/**
+ * Set the module-level LLM configuration.
+ * Call this at CLI entry points before any LLM operations.
+ * Resets the cached client so the next call creates a fresh one.
+ */
+export declare function setLLMConfig(config: LLMConfig): void;
+/**
+ * Legacy compatibility setter for call-sites still passing only claude config.
+ */
+export declare function setClaudeConfig(config: ClaudeConfig): void;
+/**
+ * Set the module-level LLM client explicitly. This is useful when a
+ * client has already been created at the CLI entry point, or for testing.
+ */
+export declare function setLLMClient(client: ClaudeClient): void;
+/** Legacy compatibility alias. */
+export declare function setClaudeClient(client: ClaudeClient): void;
+/**
+ * Get the current authentication mode being used for LLM calls.
+ * Returns "api" when using direct API key authentication, "cli" when
+ * using CLI execution. Returns undefined if no config has been set yet.
+ */
+export declare function getAuthMode(): AuthMode | undefined;
+/** Return the active LLM vendor for enrichment/classification calls. */
+export declare function getLLMVendor(): LLMVendor | undefined;
+export interface CallClaudeResult {
+    text: string;
+    tokenUsage?: TokenUsage;
+}
+/**
+ * Send a prompt to Claude using the unified client abstraction.
+ * Throws ClaudeClientError on failure instead of returning a result object.
+ *
+ * @param prompt  The prompt to send to Claude
+ * @param model   The model to use (defaults to DEFAULT_MODEL)
+ */
+export declare function callClaude(prompt: string, model?: string): Promise<CallClaudeResult>;
+/** Vendor-neutral alias for call sites migrating away from Claude naming. */
+export declare const callLLM: typeof callClaude;

package/packages/sourcevision/dist/analyzers/claude-client.js

@@ -0,0 +1,112 @@
+/**
+ * Sourcevision LLM bridge — uses @n-dx/llm-client for vendor-aware access.
+ */
+import { createLLMClient, detectLLMAuthMode, } from "@n-dx/llm-client";
+export { ClaudeClientError } from "@n-dx/llm-client";
+export const DEFAULT_MODEL = "claude-sonnet-4-6";
+export const DEFAULT_CODEX_MODEL = "gpt-5-codex";
+// ── Module-level state ────────────────────────────────────────────────────────
+let _llmConfig;
+let _llmClient;
+function resolveVendor() {
+    return _llmConfig?.vendor ?? "claude";
+}
+function resolveModel(override) {
+    if (override)
+        return override;
+    const vendor = resolveVendor();
+    if (vendor === "codex") {
+        return _llmConfig?.codex?.model ?? DEFAULT_CODEX_MODEL;
+    }
+    return _llmConfig?.claude?.model ?? DEFAULT_MODEL;
+}
+/**
+ * Set the module-level LLM configuration.
+ * Call this at CLI entry points before any LLM operations.
+ * Resets the cached client so the next call creates a fresh one.
+ */
+export function setLLMConfig(config) {
+    _llmConfig = config;
+    _llmClient = undefined;
+}
+/**
+ * Legacy compatibility setter for call-sites still passing only claude config.
+ */
+export function setClaudeConfig(config) {
+    _llmConfig = {
+        ...(_llmConfig ?? {}),
+        claude: config,
+        vendor: _llmConfig?.vendor ?? "claude",
+    };
+    _llmClient = undefined;
+}
+/**
+ * Set the module-level LLM client explicitly. This is useful when a
+ * client has already been created at the CLI entry point, or for testing.
+ */
+export function setLLMClient(client) {
+    _llmClient = client;
+}
+/** Legacy compatibility alias. */
+export function setClaudeClient(client) {
+    setLLMClient(client);
+}
+/**
+ * Get the current authentication mode being used for LLM calls.
+ * Returns "api" when using direct API key authentication, "cli" when
+ * using CLI execution. Returns undefined if no config has been set yet.
+ */
+export function getAuthMode() {
+    if (_llmClient)
+        return _llmClient.mode;
+    if (_llmConfig) {
+        return detectLLMAuthMode({
+            vendor: resolveVendor(),
+            llmConfig: _llmConfig,
+        });
+    }
+    return undefined;
+}
+/** Return the active LLM vendor for enrichment/classification calls. */
+export function getLLMVendor() {
+    if (_llmClient)
+        return resolveVendor();
+    if (_llmConfig)
+        return resolveVendor();
+    return undefined;
+}
+/**
+ * Get or lazily create the module-level LLM client.
+ * Falls back to Claude CLI mode when no configuration is available.
+ */
+function getClient() {
+    if (_llmClient)
+        return _llmClient;
+    const llmConfig = _llmConfig ?? {};
+    _llmClient = createLLMClient({
+        vendor: resolveVendor(),
+        llmConfig,
+    });
+    return _llmClient;
+}
+/**
+ * Send a prompt to Claude using the unified client abstraction.
+ * Throws ClaudeClientError on failure instead of returning a result object.
+ *
+ * @param prompt  The prompt to send to Claude
+ * @param model   The model to use (defaults to DEFAULT_MODEL)
+ */
+export async function callClaude(prompt, model) {
+    const client = getClient();
+    const result = await client.complete({
+        prompt,
+        model: resolveModel(model),
+    });
+    return {
+        text: result.text,
+        tokenUsage: result.tokenUsage,
+    };
+}
+/** Vendor-neutral alias for call sites migrating away from Claude naming. */
+export const callLLM = callClaude;
+//# sourceMappingURL=claude-client.js.map

package/packages/sourcevision/dist/analyzers/claude-client.js.map

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

package/packages/sourcevision/dist/analyzers/completion-reader.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Rex PRD completion status reader — extracts completion state, timestamps,
+ * and metadata from the rex PRD for branch work tracking.
+ *
+ * ## Architecture
+ *
+ * Like `branch-work-collector`, this module reads `.rex/prd.json` directly
+ * from the filesystem using lightweight local type definitions. No runtime
+ * import from rex exists here — the domain isolation boundary is preserved.
+ *
+ * ## Purpose
+ *
+ * While the collector focuses on *which* items were completed on a branch,
+ * the completion reader provides a richer view of the *completion state*:
+ *
+ * - Per-item completion metadata (status, timestamps, duration)
+ * - Aggregate completion statistics (by level, overall percentage)
+ * - Chronological completion timeline
+ * - Data integrity checks (inconsistent timestamps/statuses)
+ *
+ * ## Graceful degradation
+ *
+ * Missing files, corrupted JSON, and invalid data are handled without
+ * throwing. Non-fatal errors are collected in an `errors` array on the
+ * result, and partial results are returned wherever possible.
+ *
+ * @module sourcevision/analyzers/completion-reader
+ */
+/**
+ * Minimal PRDItem shape needed for completion reading.
+ *
+ * Mirrors the collector's PRDItemShape exactly so that values returned
+ * by `parsePRDDocument` are directly assignable without casting.
+ */
+interface PRDItemShape {
+    id: string;
+    title: string;
+    status: string;
+    level: string;
+    description?: string;
+    acceptanceCriteria?: string[];
+    startedAt?: string;
+    completedAt?: string;
+    priority?: string;
+    tags?: string[];
+    children?: PRDItemShape[];
+}
+/** Reference to an ancestor in the PRD hierarchy. */
+export interface ParentRef {
+    id: string;
+    title: string;
+    level: string;
+}
+/** Completion state for a single PRD item. */
+export interface CompletionState {
+    /** Unique PRD item ID. */
+    id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Current item status. */
+    status: string;
+    /** PRD hierarchy level. */
+    level: string;
+    /** ISO timestamp when work started (first in_progress transition). */
+    startedAt?: string;
+    /** ISO timestamp when the item was marked completed. */
+    completedAt?: string;
+    /**
+     * Duration from startedAt to completedAt in milliseconds.
+     * Null when either timestamp is missing or invalid.
+     */
+    durationMs: number | null;
+    /** Item priority. */
+    priority?: string;
+    /** Free-form tags. */
+    tags?: string[];
+    /** Ancestor chain from root to parent (excludes the item itself). */
+    parentChain: ParentRef[];
+}
+/** Per-level completion counts. */
+export interface LevelCount {
+    total: number;
+    completed: number;
+}
+/** Aggregate completion statistics across the PRD tree. */
+export interface CompletionStats {
+    /**
+     * Total work items (tasks + subtasks only, excluding deleted).
+     * Matches rex's convention where epics/features are containers,
+     * not work units.
+     */
+    total: number;
+    /** Number of completed work items (tasks + subtasks). */
+    completed: number;
+    /** Number of in-progress work items. */
+    inProgress: number;
+    /** Number of pending work items. */
+    pending: number;
+    /** Number of failing work items. */
+    failing: number;
+    /** Number of deferred work items. */
+    deferred: number;
+    /** Number of blocked work items. */
+    blocked: number;
+    /** Number of deleted work items (excluded from total). */
+    deleted: number;
+    /** Completion percentage (0–100). 0 when total is 0. */
+    percentComplete: number;
+    /** Counts broken down by hierarchy level (all levels, not just work items). */
+    byLevel: Record<string, LevelCount>;
+}
+/** A single entry in the completion timeline. */
+export interface TimelineEntry {
+    id: string;
+    title: string;
+    level: string;
+    completedAt?: string;
+}
+/** Ordered timeline of completed items. */
+export interface CompletionTimeline {
+    /** Completed items sorted by completedAt ascending. */
+    entries: TimelineEntry[];
+    /** Earliest completedAt timestamp (undefined when no entries). */
+    earliest?: string;
+    /** Latest completedAt timestamp (undefined when no entries). */
+    latest?: string;
+}
+/** Type of data inconsistency detected. */
+export type InconsistencyType = "missing_completed_at" | "stale_completed_at" | "completed_before_started";
+/** A detected inconsistency in PRD completion data. */
+export interface CompletionInconsistency {
+    /** Item ID with the issue. */
+    itemId: string;
+    /** Item title for human-readable context. */
+    itemTitle: string;
+    /** Category of inconsistency. */
+    type: InconsistencyType;
+    /** Human-readable description of the issue. */
+    message: string;
+}
+/** Full result from the completion status reader. */
+export interface CompletionStatusResult {
+    /** PRD document title. */
+    prdTitle?: string;
+    /** ISO timestamp when the read was performed. */
+    readAt: string;
+    /** Completion state for each item (optionally filtered by itemIds). */
+    items: CompletionState[];
+    /** Aggregate completion statistics. */
+    stats: CompletionStats;
+    /** Chronological timeline of completed items. */
+    timeline: CompletionTimeline;
+    /** Data integrity issues detected. */
+    inconsistencies: CompletionInconsistency[];
+    /** Non-fatal errors encountered during reading. */
+    errors?: string[];
+}
+/** Options for the completion status reader. */
+export interface CompletionReaderOptions {
+    /** Project root directory. */
+    dir: string;
+    /** Optional set of item IDs to restrict results to. */
+    itemIds?: Set<string>;
+}
+/**
+ * Extract completion state for a single PRD item.
+ *
+ * @param item    - PRD item to extract completion state from
+ * @param parents - Optional ancestor chain (from root to parent)
+ */
+export declare function extractItemCompletion(item: PRDItemShape, parents?: ParentRef[]): CompletionState;
+/**
+ * Compute aggregate completion statistics for a PRD tree.
+ *
+ * Follows rex's convention: `total` counts only tasks and subtasks
+ * (epics and features are containers, not work units). Deleted items
+ * are tracked separately and excluded from the total.
+ *
+ * @param items - Top-level PRD items (with nested children)
+ */
+export declare function computeCompletionStats(items: PRDItemShape[]): CompletionStats;
+/**
+ * Detect data inconsistencies in completion timestamps and statuses.
+ *
+ * Checks for:
+ * - `missing_completed_at`: item has status "completed" but no completedAt
+ * - `stale_completed_at`: item has completedAt but status is not "completed"
+ * - `completed_before_started`: completedAt is earlier than startedAt
+ *
+ * @param items - Top-level PRD items (with nested children)
+ */
+export declare function detectInconsistencies(items: PRDItemShape[]): CompletionInconsistency[];
+/**
+ * Build a chronological timeline of completed items.
+ *
+ * Items are sorted by `completedAt` ascending. Items without a
+ * `completedAt` timestamp are placed at the end of the timeline.
+ *
+ * @param items - Top-level PRD items (with nested children)
+ */
+export declare function computeCompletionTimeline(items: PRDItemShape[]): CompletionTimeline;
+/**
+ * Read completion status from the rex PRD file.
+ *
+ * This is the primary entry point for extracting completion metadata
+ * from `.rex/prd.json`. It composes the pure helper functions above
+ * into a single read-only operation.
+ *
+ * Gracefully handles:
+ * - Missing `.rex/prd.json` (returns empty result)
+ * - Corrupted PRD JSON (returns empty result with error)
+ * - Invalid timestamps (flags inconsistencies)
+ *
+ * @param options - Reader configuration
+ * @returns Full completion status result
+ */
+export declare function readCompletionStatus(options: CompletionReaderOptions): Promise<CompletionStatusResult>;
+export {};