@n-dx/core 0.1.0

package/packages/sourcevision/dist/analyzers/branch-work-filter.js

@@ -0,0 +1,285 @@
+/**
+ * Branch-scoped work item filter — identifies which rex work items are
+ * relevant to the current branch based on git branch metadata and work
+ * item timestamps.
+ *
+ * ## Architecture
+ *
+ * Follows the same patterns as the sibling modules (`branch-work-collector`,
+ * `branch-work-classifier`):
+ *
+ * - **Pure functions** for filtering logic (no I/O, no side effects)
+ * - **Git helper** for detecting branch lifecycle metadata
+ * - **Graceful degradation** when git is unavailable or timestamps are missing
+ *
+ * ## Filtering Strategy
+ *
+ * 1. Determine the branch lifecycle: creation timestamp (via `git merge-base`),
+ *    branch naming pattern, and base branch.
+ * 2. Filter work items by timestamp: only items completed *on or after* the
+ *    branch creation time are considered relevant to the branch.
+ * 3. Exclude items when on main/master (no branch work on the base branch).
+ * 4. When the branch creation timestamp is unavailable, include all items
+ *    (graceful degradation).
+ *
+ * ## Branch pattern support
+ *
+ * Recognizes standard Git Flow and trunk-based patterns:
+ * - `feature/`, `feat/` → feature
+ * - `hotfix/` → hotfix
+ * - `bugfix/`, `fix/` → bugfix
+ * - `release/` → release
+ * - `main`, `master` → main
+ *
+ * @module sourcevision/analyzers/branch-work-filter
+ */
+import { execFileSync } from "node:child_process";
+import { getCurrentBranch } from "@n-dx/llm-client";
+// ---------------------------------------------------------------------------
+// Branch pattern classification
+// ---------------------------------------------------------------------------
+/**
+ * Classify a branch name into a recognized pattern.
+ *
+ * Case-insensitive matching against common Git Flow and trunk-based
+ * conventions.
+ *
+ * @param branchName - Git branch name (e.g. "feature/add-auth")
+ * @returns The classified pattern
+ */
+export function classifyBranchPattern(branchName) {
+    if (!branchName)
+        return "other";
+    const lower = branchName.toLowerCase();
+    // Main/master branches
+    if (lower === "main" || lower === "master")
+        return "main";
+    // Feature branches: feature/, feat/
+    if (/^feat(?:ure)?[/-]/.test(lower))
+        return "feature";
+    // Hotfix branches: hotfix/
+    if (/^hotfix[/-]/.test(lower))
+        return "hotfix";
+    // Bugfix branches: bugfix/, fix/
+    if (/^(?:bug)?fix[/-]/.test(lower))
+        return "bugfix";
+    // Release branches: release/
+    if (/^release[/-]/.test(lower))
+        return "release";
+    return "other";
+}
+// ---------------------------------------------------------------------------
+// Timestamp comparison
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether a work item's completion timestamp falls within the
+ * branch lifecycle (on or after branch creation).
+ *
+ * Graceful degradation:
+ * - When `branchCreatedAt` is null or invalid → returns true (include the item)
+ * - When `completedAt` is empty or invalid → returns false (exclude the item)
+ *
+ * @param completedAt      - ISO timestamp of item completion
+ * @param branchCreatedAt  - ISO timestamp of branch creation (null if unknown)
+ */
+export function isWithinBranchLifecycle(completedAt, branchCreatedAt) {
+    // No branch creation info — include everything (graceful degradation)
+    if (branchCreatedAt === null)
+        return true;
+    // Invalid or empty completedAt — exclude
+    if (!completedAt)
+        return false;
+    const completedMs = new Date(completedAt).getTime();
+    if (Number.isNaN(completedMs))
+        return false;
+    // Invalid branchCreatedAt — include everything (graceful degradation)
+    const createdMs = new Date(branchCreatedAt).getTime();
+    if (Number.isNaN(createdMs))
+        return true;
+    // Item must be completed on or after the branch creation point
+    return completedMs >= createdMs;
+}
+// ---------------------------------------------------------------------------
+// Core filter
+// ---------------------------------------------------------------------------
+/**
+ * Filter work items to only those relevant to the given branch lifecycle.
+ *
+ * Pure function — no I/O, no side effects. Does not mutate input arrays.
+ *
+ * Rules:
+ * 1. If the branch pattern is "main", all items are excluded (no branch work
+ *    on the base branch itself).
+ * 2. Items with completedAt on or after the branch creation are included.
+ * 3. Items with completedAt before branch creation are excluded.
+ * 4. Items with invalid timestamps are excluded.
+ * 5. When branch creation time is unknown, all items are included.
+ *
+ * @param items     - Work items to filter
+ * @param lifecycle - Branch lifecycle metadata
+ */
+export function filterItemsByBranchScope(items, lifecycle) {
+    const included = [];
+    const excluded = [];
+    // Main branch: no branch-scoped work
+    if (lifecycle.pattern === "main") {
+        for (const item of items) {
+            excluded.push({
+                id: item.id,
+                title: item.title,
+                reason: "on_main_branch",
+            });
+        }
+        return { included, excluded, lifecycle };
+    }
+    for (const item of items) {
+        // Validate the completedAt timestamp first
+        if (!item.completedAt || Number.isNaN(new Date(item.completedAt).getTime())) {
+            excluded.push({
+                id: item.id,
+                title: item.title,
+                reason: "invalid_timestamp",
+            });
+            continue;
+        }
+        if (isWithinBranchLifecycle(item.completedAt, lifecycle.createdAt)) {
+            included.push(item);
+        }
+        else {
+            excluded.push({
+                id: item.id,
+                title: item.title,
+                reason: "before_branch_creation",
+            });
+        }
+    }
+    return { included, excluded, lifecycle };
+}
+// ---------------------------------------------------------------------------
+// Git helpers (internal)
+// ---------------------------------------------------------------------------
+/**
+ * Check whether this directory is inside a git repository.
+ */
+function isGitRepo(dir) {
+    try {
+        execFileSync("git", ["rev-parse", "--git-dir"], {
+            cwd: dir,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check whether a git branch exists locally.
+ */
+function branchExists(dir, branch) {
+    try {
+        execFileSync("git", ["rev-parse", "--verify", branch], {
+            cwd: dir,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Auto-detect the base branch: prefers "main", falls back to "master".
+ * Returns "main" as default when neither exists.
+ */
+function detectBaseBranch(dir) {
+    if (branchExists(dir, "main"))
+        return "main";
+    if (branchExists(dir, "master"))
+        return "master";
+    return "main";
+}
+/**
+ * Get the merge-base commit between HEAD and the base branch.
+ * Returns null if the merge-base cannot be determined.
+ */
+function getMergeBase(dir, baseBranch) {
+    try {
+        const sha = execFileSync("git", ["merge-base", "HEAD", baseBranch], {
+            cwd: dir,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        return sha || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the author date of a specific commit as an ISO string.
+ * Returns null if the commit cannot be read.
+ */
+function getCommitDate(dir, sha) {
+    try {
+        const date = execFileSync("git", ["log", "-1", "--format=%aI", sha], {
+            cwd: dir,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        // Validate it's a parseable date
+        if (date && !Number.isNaN(new Date(date).getTime())) {
+            return new Date(date).toISOString();
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Branch lifecycle detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect the lifecycle metadata for the current branch.
+ *
+ * Reads git metadata to determine:
+ * - Current branch name
+ * - Base branch (main or master)
+ * - Branch creation timestamp (from merge-base commit)
+ * - Branch naming pattern classification
+ *
+ * Gracefully handles:
+ * - Non-git directories (returns lifecycle with null createdAt)
+ * - Detached HEAD (returns "unknown" branch name)
+ * - Missing base branch (returns null createdAt)
+ *
+ * @param options - Detection configuration
+ * @returns Branch lifecycle metadata
+ * @internal Not part of the public API — used only within this module
+ */
+function detectBranchLifecycle(options) {
+    const { dir } = options;
+    // Non-git directory — graceful degradation
+    if (!isGitRepo(dir)) {
+        const branchName = "unknown";
+        return {
+            branchName,
+            baseBranch: options.baseBranch ?? "main",
+            createdAt: null,
+            pattern: classifyBranchPattern(branchName),
+        };
+    }
+    const branchName = getCurrentBranch(dir) ?? "unknown";
+    const baseBranch = options.baseBranch ?? detectBaseBranch(dir);
+    const pattern = classifyBranchPattern(branchName);
+    // On the base branch itself — no branch creation point
+    if (branchName === baseBranch || pattern === "main") {
+        return { branchName, baseBranch, createdAt: null, pattern };
+    }
+    // Find the branch creation point via merge-base
+    const mergeBaseSha = getMergeBase(dir, baseBranch);
+    const createdAt = mergeBaseSha ? getCommitDate(dir, mergeBaseSha) : null;
+    return { branchName, baseBranch, createdAt, pattern };
+}
+//# sourceMappingURL=branch-work-filter.js.map

package/packages/sourcevision/dist/analyzers/branch-work-filter.js.map

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

package/packages/sourcevision/dist/analyzers/branch-work-store.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Branch work record storage — persistent JSON files for tracking
+ * completed PRD items on a per-branch basis.
+ *
+ * ## File layout
+ *
+ * Records are stored under `.sourcevision/` with branch-specific names:
+ *
+ * ```
+ * .sourcevision/
+ *   branch-work-feature-add-auth.json
+ *   branch-work-release-v2.0.json
+ * ```
+ *
+ * ## Validation
+ *
+ * All reads and writes are validated against `BranchWorkRecordSchema`
+ * (Zod). Invalid data is rejected on write; corrupted files return `null`
+ * on read — the same graceful degradation pattern used by the collector.
+ *
+ * @module sourcevision/analyzers/branch-work-store
+ */
+import type { BranchWorkRecord } from "../schema/v1.js";
+/**
+ * Sanitize a branch name for use in a filename.
+ *
+ * Replaces characters that are problematic in filenames (slashes, `@`, spaces,
+ * colons, tildes, carets, question marks, asterisks, brackets) with dashes,
+ * collapses consecutive dashes, and trims leading/trailing dashes.
+ *
+ * @example
+ * sanitizeBranchName("feature/add-auth")  // → "feature-add-auth"
+ * sanitizeBranchName("release/v2.0@rc1")  // → "release-v2.0-rc1"
+ */
+export declare function sanitizeBranchName(branch: string): string;
+/**
+ * Compute the file path for a branch work record.
+ *
+ * @param projectDir - Project root directory
+ * @param branch     - Git branch name (will be sanitized)
+ * @returns Absolute path to the record file
+ */
+export declare function branchWorkRecordPath(projectDir: string, branch: string): string;
+/**
+ * Save a branch work record to disk.
+ *
+ * - Validates the record against the Zod schema before writing.
+ * - Creates the `.sourcevision/` directory if it does not exist.
+ * - Updates the `updatedAt` timestamp to the current time.
+ * - Writes pretty-printed JSON with a trailing newline.
+ *
+ * @throws If the record fails schema validation
+ */
+export declare function saveBranchWorkRecord(projectDir: string, record: BranchWorkRecord): Promise<void>;
+/**
+ * Load a branch work record from disk.
+ *
+ * Returns `null` when the file does not exist, cannot be parsed as JSON,
+ * or fails schema validation. This mirrors the graceful degradation
+ * pattern used by the branch work collector.
+ *
+ * @param projectDir - Project root directory
+ * @param branch     - Git branch name
+ */
+export declare function loadBranchWorkRecord(projectDir: string, branch: string): Promise<BranchWorkRecord | null>;

package/packages/sourcevision/dist/analyzers/branch-work-store.js

@@ -0,0 +1,127 @@
+/**
+ * Branch work record storage — persistent JSON files for tracking
+ * completed PRD items on a per-branch basis.
+ *
+ * ## File layout
+ *
+ * Records are stored under `.sourcevision/` with branch-specific names:
+ *
+ * ```
+ * .sourcevision/
+ *   branch-work-feature-add-auth.json
+ *   branch-work-release-v2.0.json
+ * ```
+ *
+ * ## Validation
+ *
+ * All reads and writes are validated against `BranchWorkRecordSchema`
+ * (Zod). Invalid data is rejected on write; corrupted files return `null`
+ * on read — the same graceful degradation pattern used by the collector.
+ *
+ * @module sourcevision/analyzers/branch-work-store
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { PROJECT_DIRS } from "@n-dx/llm-client";
+import { BranchWorkRecordSchema } from "../schema/validate.js";
+// ---------------------------------------------------------------------------
+// Branch name sanitization
+// ---------------------------------------------------------------------------
+/**
+ * Sanitize a branch name for use in a filename.
+ *
+ * Replaces characters that are problematic in filenames (slashes, `@`, spaces,
+ * colons, tildes, carets, question marks, asterisks, brackets) with dashes,
+ * collapses consecutive dashes, and trims leading/trailing dashes.
+ *
+ * @example
+ * sanitizeBranchName("feature/add-auth")  // → "feature-add-auth"
+ * sanitizeBranchName("release/v2.0@rc1")  // → "release-v2.0-rc1"
+ */
+export function sanitizeBranchName(branch) {
+    return branch
+        .replace(/[/@:~^?*[\]\\]/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/**
+ * Compute the file path for a branch work record.
+ *
+ * @param projectDir - Project root directory
+ * @param branch     - Git branch name (will be sanitized)
+ * @returns Absolute path to the record file
+ */
+export function branchWorkRecordPath(projectDir, branch) {
+    const sanitized = sanitizeBranchName(branch);
+    return join(projectDir, PROJECT_DIRS.SOURCEVISION, `branch-work-${sanitized}.json`);
+}
+// ---------------------------------------------------------------------------
+// Save
+// ---------------------------------------------------------------------------
+/**
+ * Save a branch work record to disk.
+ *
+ * - Validates the record against the Zod schema before writing.
+ * - Creates the `.sourcevision/` directory if it does not exist.
+ * - Updates the `updatedAt` timestamp to the current time.
+ * - Writes pretty-printed JSON with a trailing newline.
+ *
+ * @throws If the record fails schema validation
+ */
+export async function saveBranchWorkRecord(projectDir, record) {
+    // Update the timestamp before validation
+    const toSave = {
+        ...record,
+        updatedAt: new Date().toISOString(),
+    };
+    // Validate before writing — fail fast on bad data
+    const result = BranchWorkRecordSchema.safeParse(toSave);
+    if (!result.success) {
+        const messages = result.error.issues
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ");
+        throw new Error(`Invalid branch work record: ${messages}`);
+    }
+    // Ensure directory exists
+    const svDir = join(projectDir, PROJECT_DIRS.SOURCEVISION);
+    if (!existsSync(svDir)) {
+        await mkdir(svDir, { recursive: true });
+    }
+    const filePath = branchWorkRecordPath(projectDir, record.branch);
+    const json = JSON.stringify(toSave, null, 2) + "\n";
+    await writeFile(filePath, json, "utf-8");
+}
+// ---------------------------------------------------------------------------
+// Load
+// ---------------------------------------------------------------------------
+/**
+ * Load a branch work record from disk.
+ *
+ * Returns `null` when the file does not exist, cannot be parsed as JSON,
+ * or fails schema validation. This mirrors the graceful degradation
+ * pattern used by the branch work collector.
+ *
+ * @param projectDir - Project root directory
+ * @param branch     - Git branch name
+ */
+export async function loadBranchWorkRecord(projectDir, branch) {
+    const filePath = branchWorkRecordPath(projectDir, branch);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const result = BranchWorkRecordSchema.safeParse(parsed);
+        if (!result.success)
+            return null;
+        return result.data;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=branch-work-store.js.map

package/packages/sourcevision/dist/analyzers/branch-work-store.js.map

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

package/packages/sourcevision/dist/analyzers/callgraph-findings.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Generate deterministic architectural findings from call graph data.
+ *
+ * Analyzes call graph patterns to identify:
+ * - God functions (excessive outgoing calls)
+ * - Tightly coupled modules (dense cross-file call patterns)
+ * - Potentially dead code (exported functions with no incoming calls)
+ * - Refactoring suggestions (hub functions, fan-in hotspots)
+ *
+ * All findings are deterministic (pass 0) — no AI invocation.
+ */
+import type { CallGraph, Finding, Inventory, ImportEdge, Classifications } from "../schema/index.js";
+export interface CallGraphFindingsOptions {
+    /** Inventory for file role detection (skip test files, identify entry points). */
+    inventory?: Inventory;
+    /** Import edges for re-export detection (skip exports consumed by re-export chains). */
+    importEdges?: ImportEdge[];
+    /** Classifications for archetype-based file role detection. When provided, archetype
+     *  lookups replace hard-coded path patterns for utility/entrypoint/types detection. */
+    classifications?: Classifications;
+}
+/**
+ * Generate architectural findings from call graph data.
+ * Returns deterministic `Finding[]` objects at pass 0 (structural).
+ */
+export declare function generateCallGraphFindings(callGraph: CallGraph, options?: CallGraphFindingsOptions): Finding[];