@lumenflow/core 2.2.2 → 2.3.2

package/dist/git-context-extractor.js

@@ -0,0 +1,559 @@
+/**
+ * Git Context Extractor Module (WU-1190)
+ *
+ * Extracts git history insights for LLM context enrichment:
+ * - Co-occurrence: files frequently changed together
+ * - Ownership: primary contributors to file/directory
+ * - Churn: change frequency metrics (hotspots)
+ *
+ * These signals help the LLM understand codebase relationships
+ * without algorithmic clustering - the LLM interprets the patterns.
+ */
+import { execSync } from 'node:child_process';
+// Constants
+const DEFAULT_MAX_COMMITS = 500;
+const DEFAULT_MAX_RESULTS = 20;
+const CHARS_PER_TOKEN = 4; // Rough approximation
+const DEFAULT_EXCLUDE_PATTERNS = ['*.lock', '*.yaml', '*.yml', '*.json', '*.md', 'pnpm-lock.yaml'];
+// Pre-compiled regex patterns for performance
+// Note: Using atomic groups or possessive quantifiers isn't supported in JS,
+// so some patterns are implemented as functions to avoid backtracking
+const NUMSTAT_LINE_REGEX = /^(\d+|-)\t(\d+|-)\t(.+)$/;
+const DANGEROUS_CHARS_REGEX = /[;&|`$]/;
+/**
+ * Parse shortlog line: "   10\tName <email>"
+ * Manual parsing to avoid slow regex backtracking
+ */
+function parseShortlogFormat(line) {
+    // Skip leading whitespace
+    let i = 0;
+    while (i < line.length && (line[i] === ' ' || line[i] === '\t')) {
+        i++;
+    }
+    // Parse digits
+    const digitStart = i;
+    while (i < line.length && line[i] >= '0' && line[i] <= '9') {
+        i++;
+    }
+    if (i === digitStart)
+        return null; // No digits found
+    const count = parseInt(line.slice(digitStart, i), 10);
+    // Skip whitespace after digits
+    while (i < line.length && (line[i] === ' ' || line[i] === '\t')) {
+        i++;
+    }
+    // Rest is the name
+    const name = line.slice(i).trim();
+    if (!name)
+        return null;
+    return { count, name };
+}
+/**
+ * Check if a string is a git commit hash (40 hex chars)
+ * Uses character-by-character check to avoid slow regex backtracking
+ */
+function isCommitHash(str) {
+    if (str.length !== 40)
+        return false;
+    for (const char of str) {
+        if (!((char >= '0' && char <= '9') || (char >= 'a' && char <= 'f'))) {
+            return false;
+        }
+    }
+    return true;
+}
+const SOURCE_FILE_EXCLUDE_PATTERNS = [
+    /\.lock$/,
+    /lock\.ya?ml$/,
+    /package-lock\.json$/,
+    /yarn\.lock$/,
+    /\.gitignore$/,
+    /\.env/,
+    /node_modules/,
+    /dist\//,
+    /build\//,
+    /\.min\./,
+];
+/**
+ * Execute a git command safely, returning empty string on error.
+ *
+ * SECURITY: Commands are constructed from static arguments (no user input) to prevent injection.
+ * The args array is joined into a command string for execSync.
+ * All callers pass only internally-constructed arguments.
+ */
+function safeGitExec(args, cwd) {
+    try {
+        // Join args into a command string
+        // SECURITY: all args are constructed internally (no user input)
+        const cmd = ['git', ...args].join(' ');
+        // SECURITY: execSync is safe here because:
+        // 1. 'git' is a fixed command from PATH (trusted)
+        // 2. args are internally constructed, not from user input
+        // 3. cwd is validated by the caller (projectRoot from CLI)
+        // eslint-disable-next-line sonarjs/os-command -- safe: git is trusted, args are static
+        const result = execSync(cmd, {
+            cwd,
+            encoding: 'utf-8',
+            maxBuffer: 10 * 1024 * 1024, // 10MB
+            timeout: 30000, // 30 seconds
+        });
+        return result;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Check if commit count indicates limited history
+ */
+function hasLimitedCommitCount(projectRoot) {
+    const commitCountStr = safeGitExec(['rev-list', '--count', 'HEAD'], projectRoot).trim();
+    const count = parseInt(commitCountStr, 10) || 0;
+    return { limited: count < 10, count };
+}
+/**
+ * Extract complete git context from a repository
+ */
+export function extractGitContext(projectRoot, options = {}) {
+    const result = {
+        coOccurrences: [],
+        ownership: [],
+        churn: [],
+        hasLimitedHistory: false,
+    };
+    try {
+        // Check if this is a git repo using execSync directly
+        // SECURITY: This is a static command with no user input
+        // eslint-disable-next-line sonarjs/no-os-command-from-path -- safe: static command
+        execSync('git rev-parse --is-inside-work-tree', {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+        });
+        const { limited, count } = hasLimitedCommitCount(projectRoot);
+        if (limited) {
+            result.hasLimitedHistory = true;
+            result.error = `Repository has fewer than 10 commits (found ${count})`;
+            return result;
+        }
+        // Extract co-occurrences
+        result.coOccurrences = getFileCoOccurrence(projectRoot, {
+            maxCommits: options.maxCommits ?? DEFAULT_MAX_COMMITS,
+            since: options.since,
+        });
+        // Get top-level directories for ownership analysis
+        const topDirs = getTopLevelDirs(projectRoot);
+        result.ownership = getOwnershipSignals(projectRoot, topDirs);
+        // Extract churn metrics
+        result.churn = getChurnMetrics(projectRoot, {
+            maxCommits: options.maxCommits ?? DEFAULT_MAX_COMMITS,
+            since: options.since,
+        });
+    }
+    catch (error) {
+        handleExtractionError(result, error);
+    }
+    return result;
+}
+/**
+ * Handle extraction errors and set appropriate error messages
+ */
+function handleExtractionError(result, error) {
+    result.hasLimitedHistory = true;
+    if (error instanceof Error) {
+        if (error.message.includes('not a git repository')) {
+            result.error = 'not a git repository';
+        }
+        else if (error.message.includes('does not have any commits')) {
+            result.error = 'no commits in repository';
+        }
+        else {
+            result.error = error.message;
+        }
+    }
+}
+/**
+ * Get top-level directories for ownership analysis
+ */
+function getTopLevelDirs(projectRoot) {
+    const output = safeGitExec(['ls-tree', '-d', '--name-only', 'HEAD'], projectRoot);
+    return output
+        .split('\n')
+        .filter((d) => d.trim() && !d.startsWith('.'))
+        .slice(0, 20); // Limit to first 20 directories
+}
+/**
+ * Parse git log output into commits with their files
+ */
+function parseCommitsFromLog(output) {
+    const commits = [];
+    let currentFiles = [];
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            if (currentFiles.length > 0) {
+                commits.push([...currentFiles]);
+                currentFiles = [];
+            }
+            continue;
+        }
+        // Skip commit hashes (40 hex chars)
+        if (isCommitHash(trimmed)) {
+            if (currentFiles.length > 0) {
+                commits.push([...currentFiles]);
+                currentFiles = [];
+            }
+            continue;
+        }
+        // Only track source files
+        if (isSourceFile(trimmed)) {
+            currentFiles.push(trimmed);
+        }
+    }
+    if (currentFiles.length > 0) {
+        commits.push(currentFiles);
+    }
+    return commits;
+}
+/**
+ * Count file pair co-occurrences from commits
+ */
+function countFilePairs(commits) {
+    const pairCounts = new Map();
+    for (const files of commits) {
+        if (files.length < 2)
+            continue;
+        // Generate all pairs
+        for (let i = 0; i < files.length; i++) {
+            for (let j = i + 1; j < files.length; j++) {
+                const pair = [files[i], files[j]]
+                    .slice()
+                    .sort((a, b) => a.localeCompare(b))
+                    .join('::');
+                pairCounts.set(pair, (pairCounts.get(pair) ?? 0) + 1);
+            }
+        }
+    }
+    return pairCounts;
+}
+/**
+ * Extract file co-occurrence patterns from git history
+ */
+export function getFileCoOccurrence(projectRoot, options = {}) {
+    const maxCommits = options.maxCommits ?? DEFAULT_MAX_COMMITS;
+    const maxResults = options.maxResults ?? DEFAULT_MAX_RESULTS;
+    // Build git log args array (safe - no user input in paths)
+    const args = ['log', `-n`, String(maxCommits)];
+    if (options.since) {
+        args.push(`--since=${options.since}`);
+    }
+    args.push('--name-only', '--pretty=format:%H', '--diff-filter=ACMRT');
+    const output = safeGitExec(args, projectRoot);
+    if (!output.trim()) {
+        return [];
+    }
+    const commits = parseCommitsFromLog(output);
+    const pairCounts = countFilePairs(commits);
+    // Convert to array and filter
+    const coOccurrences = [];
+    for (const [pair, count] of pairCounts.entries()) {
+        if (count >= 2) {
+            // Only include pairs that co-occurred at least twice
+            const [file1, file2] = pair.split('::');
+            coOccurrences.push({ file1, file2, count });
+        }
+    }
+    // Sort by count descending and limit results (use toSorted to avoid mutation)
+    return coOccurrences
+        .slice()
+        .sort((a, b) => b.count - a.count)
+        .slice(0, maxResults);
+}
+/**
+ * Check if a file is a source file (not config, lock, etc.)
+ */
+function isSourceFile(filePath) {
+    return !SOURCE_FILE_EXCLUDE_PATTERNS.some((pattern) => pattern.test(filePath));
+}
+/**
+ * Parse a single contributor line from shortlog output
+ */
+function parseShortlogLine(line) {
+    const result = parseShortlogFormat(line);
+    if (!result)
+        return null;
+    return {
+        count: result.count,
+        name: result.name,
+    };
+}
+/**
+ * Extract ownership signal for a single path
+ */
+function extractOwnershipForPath(projectRoot, targetPath) {
+    // Validate path doesn't contain dangerous characters
+    if (DANGEROUS_CHARS_REGEX.test(targetPath)) {
+        return {
+            path: targetPath,
+            primaryOwner: null,
+            contributors: [],
+            commitCount: 0,
+        };
+    }
+    // Use array form for safety
+    const args = ['shortlog', '-sne', '--all', '--', targetPath];
+    const output = safeGitExec(args, projectRoot);
+    if (!output.trim()) {
+        return {
+            path: targetPath,
+            primaryOwner: null,
+            contributors: [],
+            commitCount: 0,
+        };
+    }
+    // Parse shortlog output
+    const contributors = [];
+    let totalCommits = 0;
+    for (const line of output.split('\n')) {
+        const parsed = parseShortlogLine(line);
+        if (parsed) {
+            contributors.push(parsed);
+            totalCommits += parsed.count;
+        }
+    }
+    // Sort by commit count descending (use toSorted to avoid mutation)
+    const sorted = contributors.slice().sort((a, b) => b.count - a.count);
+    return {
+        path: targetPath,
+        primaryOwner: sorted[0]?.name ?? null,
+        contributors: sorted.map((c) => c.name),
+        commitCount: totalCommits,
+    };
+}
+/**
+ * Extract ownership signals for specified paths.
+ * Note: paths are validated internally and not derived from user input.
+ */
+export function getOwnershipSignals(projectRoot, paths) {
+    return paths.map((path) => extractOwnershipForPath(projectRoot, path));
+}
+/**
+ * Parse a single numstat line from git log output
+ */
+function parseNumstatLine(line) {
+    const match = NUMSTAT_LINE_REGEX.exec(line);
+    if (!match)
+        return null;
+    return {
+        additions: match[1] === '-' ? 0 : parseInt(match[1], 10),
+        deletions: match[2] === '-' ? 0 : parseInt(match[2], 10),
+        filePath: match[3],
+    };
+}
+/**
+ * Check if a file matches any exclude pattern using simple glob matching
+ */
+function matchesExcludePattern(filePath, patterns) {
+    return patterns.some((pattern) => {
+        // Simple glob matching using a state machine approach
+        // Avoids control characters and dynamic regex construction
+        return globMatch(filePath, pattern);
+    });
+}
+/**
+ * Simple glob matching without regex
+ * Supports * (match any) and ? (match single char)
+ */
+function globMatch(str, pattern) {
+    let si = 0; // string index
+    let pi = 0; // pattern index
+    let starIdx = -1;
+    let matchIdx = 0;
+    while (si < str.length) {
+        if (pi < pattern.length && (pattern[pi] === '?' || pattern[pi] === str[si])) {
+            // Character match or ? wildcard
+            si++;
+            pi++;
+        }
+        else if (pi < pattern.length && pattern[pi] === '*') {
+            // Star found, mark position
+            starIdx = pi;
+            matchIdx = si;
+            pi++;
+        }
+        else if (starIdx !== -1) {
+            // Mismatch after star, backtrack
+            pi = starIdx + 1;
+            matchIdx++;
+            si = matchIdx;
+        }
+        else {
+            // Mismatch without star
+            return false;
+        }
+    }
+    // Skip trailing stars
+    while (pi < pattern.length && pattern[pi] === '*') {
+        pi++;
+    }
+    return pi === pattern.length;
+}
+/**
+ * Aggregate file statistics from numstat output
+ */
+function aggregateFileStats(output, excludePatterns) {
+    const fileStats = new Map();
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const parsed = parseNumstatLine(trimmed);
+        if (!parsed)
+            continue;
+        // Skip excluded patterns
+        if (matchesExcludePattern(parsed.filePath, excludePatterns))
+            continue;
+        // Skip non-source files
+        if (!isSourceFile(parsed.filePath))
+            continue;
+        const existing = fileStats.get(parsed.filePath) ?? { additions: 0, deletions: 0, commits: 0 };
+        fileStats.set(parsed.filePath, {
+            additions: existing.additions + parsed.additions,
+            deletions: existing.deletions + parsed.deletions,
+            commits: existing.commits + 1,
+        });
+    }
+    return fileStats;
+}
+/**
+ * Extract churn metrics for the repository
+ */
+export function getChurnMetrics(projectRoot, options = {}) {
+    const maxCommits = options.maxCommits ?? DEFAULT_MAX_COMMITS;
+    const maxResults = options.maxResults ?? DEFAULT_MAX_RESULTS;
+    const excludePatterns = options.excludePatterns ?? DEFAULT_EXCLUDE_PATTERNS;
+    // Build git log args array
+    const args = ['log', `-n`, String(maxCommits)];
+    if (options.since) {
+        args.push(`--since=${options.since}`);
+    }
+    args.push('--numstat', '--pretty=format:');
+    let output;
+    try {
+        /// SECURITY: all args are constructed internally (no user input)
+        const cmd = ['git', ...args].join(' ');
+        // eslint-disable-next-line sonarjs/os-command -- safe: git is trusted, args are static
+        output = execSync(cmd, {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            maxBuffer: 10 * 1024 * 1024,
+            timeout: 30000,
+        });
+    }
+    catch {
+        return [];
+    }
+    if (!output.trim()) {
+        return [];
+    }
+    const fileStats = aggregateFileStats(output, excludePatterns);
+    // Convert to array with churn scores
+    const metrics = [];
+    for (const [filePath, stats] of fileStats.entries()) {
+        metrics.push({
+            filePath,
+            additions: stats.additions,
+            deletions: stats.deletions,
+            churnScore: stats.additions + stats.deletions,
+            commitCount: stats.commits,
+        });
+    }
+    // Sort by churn score descending and limit results (use toSorted to avoid mutation)
+    return metrics
+        .slice()
+        .sort((a, b) => b.churnScore - a.churnScore)
+        .slice(0, maxResults);
+}
+/**
+ * Build co-occurrence section for summary
+ */
+function buildCoOccurrenceSection(coOccurrences) {
+    const lines = ['## Co-occurrence Patterns', 'Files frequently changed together:'];
+    for (const co of coOccurrences.slice(0, 10)) {
+        lines.push(`- ${co.file1} <-> ${co.file2} (${co.count} commits)`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Build ownership section for summary
+ */
+function buildOwnershipSection(ownership) {
+    const lines = ['## Ownership Signals', 'Primary contributors by area:'];
+    for (const own of ownership.filter((o) => o.primaryOwner)) {
+        const ownerName = own.primaryOwner?.split(' <')[0] ?? 'unknown';
+        lines.push(`- ${own.path}: ${ownerName} (${own.commitCount} commits)`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Build churn section for summary
+ */
+function buildChurnSection(churn) {
+    const lines = ['## Churn Hotspots', 'High-change files (potential complexity):'];
+    for (const ch of churn.slice(0, 10)) {
+        lines.push(`- ${ch.filePath}: ${ch.churnScore} lines changed across ${ch.commitCount} commits`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Truncate a section to fit within character limit
+ */
+function truncateSection(section, maxChars) {
+    if (section.length <= maxChars)
+        return section;
+    const lines = section.split('\n');
+    const header = lines.slice(0, 2).join('\n');
+    const items = lines.slice(2);
+    const availableChars = maxChars - header.length - 20;
+    const truncatedItems = [];
+    let currentChars = 0;
+    for (const item of items) {
+        if (currentChars + item.length > availableChars)
+            break;
+        truncatedItems.push(item);
+        currentChars += item.length + 1;
+    }
+    return [header, ...truncatedItems, '(truncated)'].join('\n');
+}
+/**
+ * Summarize git context for LLM prompt inclusion
+ *
+ * Produces a token-efficient summary that fits within specified limits.
+ */
+export function summarizeGitContext(context, options = {}) {
+    const maxTokens = options.maxTokens ?? 500;
+    const maxChars = maxTokens * CHARS_PER_TOKEN;
+    // Handle limited history case
+    if (context.hasLimitedHistory) {
+        return context.error
+            ? `Git history analysis limited: ${context.error}`
+            : 'Git history analysis limited due to sparse commit history.';
+    }
+    const sections = [];
+    if (context.coOccurrences.length > 0) {
+        sections.push(buildCoOccurrenceSection(context.coOccurrences));
+    }
+    if (context.ownership.length > 0) {
+        sections.push(buildOwnershipSection(context.ownership));
+    }
+    if (context.churn.length > 0) {
+        sections.push(buildChurnSection(context.churn));
+    }
+    let result = sections.join('\n\n');
+    // Truncate if needed
+    if (result.length > maxChars && sections.length > 0) {
+        const charsPerSection = Math.floor(maxChars / sections.length) - 20;
+        const truncatedSections = sections.map((s) => truncateSection(s, charsPerSection));
+        result = truncatedSections.join('\n\n');
+    }
+    return result || 'Git history analysis limited due to sparse commit history.';
+}

package/dist/hardcoded-strings.d.ts

@@ -50,7 +50,7 @@ export interface FindHardcodedPathViolationsOptions {
  */
 export declare function findHardcodedPathViolations(line: any, options?: FindHardcodedPathViolationsOptions): any[];
 /**
- * Legacy function for backwards compatibility with gates-pre-commit.mjs
+ * Legacy function for backwards compatibility with gates-pre-commit.ts
  * Detects all hardcoded string patterns (not just paths)
  *
  * @deprecated Use findHardcodedPathViolations for path-specific detection

package/dist/hardcoded-strings.js

@@ -249,7 +249,7 @@ export function findHardcodedPathViolations(line, options = {}) {
     return violations;
 }
 /**
- * Legacy function for backwards compatibility with gates-pre-commit.mjs
+ * Legacy function for backwards compatibility with gates-pre-commit.ts
  * Detects all hardcoded string patterns (not just paths)
  *
  * @deprecated Use findHardcodedPathViolations for path-specific detection

package/dist/incremental-lint.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file incremental-lint.mjs
+ * @file incremental-lint.ts
  * @description Incremental linting utilities for gates
  * WU-1304: Optimise ESLint gates performance
  *

package/dist/incremental-lint.js

@@ -1,5 +1,5 @@
 /**
- * @file incremental-lint.mjs
+ * @file incremental-lint.ts
  * @description Incremental linting utilities for gates
  * WU-1304: Optimise ESLint gates performance
  *
@@ -15,7 +15,7 @@ import { STRING_LITERALS } from './wu-constants.js';
 export const LINTABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.js'];
 /**
  * Directory patterns that should be ignored
- * Matches ESLint ignores in apps/web/eslint.config.mjs
+ * Matches ESLint ignores in apps/web/eslint.config.ts
  * @type {string[]}
  */
 const IGNORED_DIRECTORIES = [

package/dist/incremental-test.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file incremental-test.mjs
+ * @file incremental-test.ts
  * @description Helpers for Vitest --changed execution
  *
  * WU-1920: Add incremental test execution to gates

package/dist/incremental-test.js

@@ -1,5 +1,5 @@
 /**
- * @file incremental-test.mjs
+ * @file incremental-test.ts
  * @description Helpers for Vitest --changed execution
  *
  * WU-1920: Add incremental test execution to gates

package/dist/index.d.ts

@@ -44,12 +44,17 @@ export * from './dependency-guard.js';
 export * from './stamp-utils.js';
 export * from './lumenflow-config.js';
 export * from './lumenflow-config-schema.js';
+export * from './wu-events-cleanup.js';
+export * from './state-cleanup-core.js';
+export * from './state-doctor-core.js';
 export * from './gates-config.js';
 export * from './branch-check.js';
 export * from './agent-patterns-registry.js';
 export * from './lumenflow-home.js';
 export * from './force-bypass-audit.js';
 export { LUMENFLOW_PATHS, BEACON_PATHS } from './wu-constants.js';
+export { STREAM_ERRORS, EXIT_CODES } from './wu-constants.js';
+export * from './stream-error-handler.js';
 export * from './color-support.js';
 export * from './context/index.js';
 export * from './validation/index.js';
@@ -69,4 +74,12 @@ export { VALIDATION_ERROR_CODE_VALUES, ValidationErrorCodeSchema, PREDICATE_SEVE
 export { RECOVERY_ISSUE_CODE_VALUES, RecoveryIssueCodeSchema, RECOVERY_ACTION_TYPE_VALUES, RecoveryActionTypeSchema, RecoveryIssueSchema, RecoveryActionSchema, RecoveryAnalysisSchema, } from './domain/recovery.schemas.js';
 export { SimpleGitLocationAdapter, SimpleGitStateAdapter, FileSystemWuStateAdapter, CommandRegistryAdapter, RecoveryAnalyzerAdapter, } from './adapters/index.js';
 export { ComputeContextUseCase, type ComputeContextOptions, ValidateCommandUseCase, AnalyzeRecoveryUseCase, } from './usecases/index.js';
+export * from './lane-suggest-prompt.js';
+export * from './git-context-extractor.js';
 export { createContextAdapters, createValidationAdapters, createRecoveryAdapters, createComputeContextUseCase, createValidateCommandUseCase, createAnalyzeRecoveryUseCase, computeWuContext, validateCommand, analyzeRecoveryIssues, type ContextAdapters, type ValidationAdapters, type RecoveryAdapters, type CreateComputeContextOptions, type CreateValidateCommandOptions, type CreateAnalyzeRecoveryOptions, } from './context-di.js';
+export * from './wu-id-generator.js';
+export * from './test-baseline.js';
+export { loadManifest, loadTemplate, loadTemplatesWithOverrides, assembleTemplates, replaceTokens, evaluateCondition, type TemplateFrontmatter, type LoadedTemplate, type ManifestEntry, type TemplateManifest, type TemplateContext, } from './template-loader.js';
+export { tryAssembleSpawnTemplates, buildTemplateContext } from './wu-spawn.js';
+export * from './patrol-loop.js';
+export { resolvePolicy, getDefaultPolicy, MethodologyConfigSchema, MethodologyOverridesSchema, TestingMethodologySchema, ArchitectureMethodologySchema, CoverageModeSchema, TESTING_METHODOLOGY, ARCHITECTURE_METHODOLOGY, COVERAGE_MODE, type ResolvedPolicy, type ResolvePolicyOptions, type MethodologyConfig, type MethodologyOverrides, type TestingMethodology, type ArchitectureMethodology, type CoverageMode, } from './resolve-policy.js';