@libar-dev/architect 1.0.0-pre.3

package/dist/generators/warning-collector.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern WarningCollector
+ * @architect-status completed
+ *
+ * ## Warning Collector - Unified Warning Handling
+ *
+ * Provides a unified system for capturing, categorizing, and reporting
+ * non-fatal issues during document generation. Replaces scattered console.warn
+ * calls with structured warning handling that integrates with the Result pattern.
+ *
+ * ### When to Use
+ *
+ * - When generating documentation from source mappings
+ * - When extracting content from TypeScript or Gherkin files
+ * - When deduplicating or assembling content sections
+ *
+ * ### Key Concepts
+ *
+ * - **Warning Categories**: validation, extraction, deduplication, file-access, format
+ * - **Source Attribution**: Each warning includes source file and optional line number
+ * - **Aggregation**: Warnings collected across pipeline stages, maintaining insertion order
+ * - **Formatting**: Console, JSON, and markdown output formats
+ */
+/**
+ * Warning category for grouping and filtering
+ */
+export type WarningCategory = 'validation' | 'extraction' | 'deduplication' | 'file-access' | 'format';
+/**
+ * A captured warning with source context
+ */
+export interface Warning {
+    /** Source file path (e.g., "src/types.ts") */
+    source: string;
+    /** Optional line number within the source file */
+    line?: number;
+    /** Warning category for grouping */
+    category: WarningCategory;
+    /** Optional subcategory for finer-grained classification */
+    subcategory?: string;
+    /** Warning message describing the issue */
+    message: string;
+}
+/**
+ * Warning collector interface for capturing and querying warnings
+ */
+export interface WarningCollector {
+    /**
+     * Capture a warning
+     */
+    capture(warning: Warning): void;
+    /**
+     * Get all captured warnings in insertion order
+     */
+    getAll(): readonly Warning[];
+    /**
+     * Filter warnings by category
+     */
+    filterByCategory(category: WarningCategory): readonly Warning[];
+    /**
+     * Filter warnings by source file
+     */
+    filterBySource(source: string): readonly Warning[];
+    /**
+     * Group warnings by source file
+     */
+    groupBySource(): Map<string, readonly Warning[]>;
+    /**
+     * Get summary counts by category
+     */
+    getSummary(): Record<WarningCategory, number>;
+    /**
+     * Format warnings for console output (with colors)
+     */
+    formatForConsole(): string;
+    /**
+     * Format warnings as JSON (machine-readable)
+     */
+    formatAsJson(): string;
+    /**
+     * Format warnings as markdown (for documentation)
+     */
+    formatAsMarkdown(): string;
+    /**
+     * Check if collector has no warnings
+     */
+    isEmpty(): boolean;
+    /**
+     * Get total warning count
+     */
+    count(): number;
+}
+/**
+ * Format a warning location string
+ */
+export declare function formatWarningLocation(warning: Warning): string;
+/**
+ * Create a new warning collector
+ */
+export declare function createWarningCollector(): WarningCollector;
+/**
+ * A Result that includes warnings alongside the success/error value.
+ * Warnings are collected regardless of success or failure state.
+ */
+export type ResultWithWarnings<T, E = Error> = {
+    ok: true;
+    value: T;
+    warnings: readonly Warning[];
+} | {
+    ok: false;
+    error: E;
+    warnings: readonly Warning[];
+};
+/**
+ * Utilities for creating ResultWithWarnings values
+ */
+export declare const ResultWithWarnings: {
+    /**
+     * Create a successful result with warnings
+     */
+    ok: <T>(value: T, warnings?: readonly Warning[]) => ResultWithWarnings<T, never>;
+    /**
+     * Create an error result with warnings
+     */
+    err: <E>(error: E, warnings?: readonly Warning[]) => ResultWithWarnings<never, E>;
+    /**
+     * Check if result is successful
+     */
+    isOk: <T, E>(result: ResultWithWarnings<T, E>) => result is {
+        ok: true;
+        value: T;
+        warnings: readonly Warning[];
+    };
+    /**
+     * Check if result is an error
+     */
+    isError: <T, E>(result: ResultWithWarnings<T, E>) => result is {
+        ok: false;
+        error: E;
+        warnings: readonly Warning[];
+    };
+};
+//# sourceMappingURL=warning-collector.d.ts.map

package/dist/generators/warning-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warning-collector.d.ts","sourceRoot":"","sources":["../../src/generators/warning-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,aAAa,GACb,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IAEf,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,oCAAoC;IACpC,QAAQ,EAAE,eAAe,CAAC;IAE1B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAEhC;;OAEG;IACH,MAAM,IAAI,SAAS,OAAO,EAAE,CAAC;IAE7B;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,OAAO,EAAE,CAAC;IAEhE;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAAC;IAEnD;;OAEG;IACH,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC,CAAC;IAEjD;;OAEG;IACH,UAAU,IAAI,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAE9C;;OAEG;IACH,gBAAgB,IAAI,MAAM,CAAC;IAE3B;;OAEG;IACH,YAAY,IAAI,MAAM,CAAC;IAEvB;;OAEG;IACH,gBAAgB,IAAI,MAAM,CAAC;IAE3B;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC;IAEnB;;OAEG;IACH,KAAK,IAAI,MAAM,CAAC;CACjB;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAK9D;AAcD;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAyGzD;AAMD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,IACvC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,GACpD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,kBAAkB;IAC7B;;OAEG;SACE,CAAC,SAAS,CAAC,aAAY,SAAS,OAAO,EAAE,KAAQ,kBAAkB,CAAC,CAAC,EAAE,KAAK,CAAC;IAMlF;;OAEG;UACG,CAAC,SAAS,CAAC,aAAY,SAAS,OAAO,EAAE,KAAQ,kBAAkB,CAAC,KAAK,EAAE,CAAC,CAAC;IAMnF;;OAEG;WACI,CAAC,EAAE,CAAC,UACD,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,KAC/B,MAAM,IAAI;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;KAAE;IAEjE;;OAEG;cACO,CAAC,EAAE,CAAC,UACJ,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,KAC/B,MAAM,IAAI;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;KAAE;CACnE,CAAC"}

package/dist/generators/warning-collector.js

@@ -0,0 +1,166 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern WarningCollector
+ * @architect-status completed
+ *
+ * ## Warning Collector - Unified Warning Handling
+ *
+ * Provides a unified system for capturing, categorizing, and reporting
+ * non-fatal issues during document generation. Replaces scattered console.warn
+ * calls with structured warning handling that integrates with the Result pattern.
+ *
+ * ### When to Use
+ *
+ * - When generating documentation from source mappings
+ * - When extracting content from TypeScript or Gherkin files
+ * - When deduplicating or assembling content sections
+ *
+ * ### Key Concepts
+ *
+ * - **Warning Categories**: validation, extraction, deduplication, file-access, format
+ * - **Source Attribution**: Each warning includes source file and optional line number
+ * - **Aggregation**: Warnings collected across pipeline stages, maintaining insertion order
+ * - **Formatting**: Console, JSON, and markdown output formats
+ */
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Format a warning location string
+ */
+export function formatWarningLocation(warning) {
+    if (warning.line !== undefined) {
+        return `${warning.source}:${warning.line}`;
+    }
+    return warning.source;
+}
+/**
+ * ANSI color codes for console output
+ */
+const ANSI = {
+    yellow: '\x1b[33m',
+    reset: '\x1b[0m',
+};
+// =============================================================================
+// Implementation
+// =============================================================================
+/**
+ * Create a new warning collector
+ */
+export function createWarningCollector() {
+    const warnings = [];
+    return {
+        capture(warning) {
+            warnings.push(warning);
+        },
+        getAll() {
+            // Return a copy to prevent external mutation of internal state
+            return [...warnings];
+        },
+        filterByCategory(category) {
+            return warnings.filter((w) => w.category === category);
+        },
+        filterBySource(source) {
+            return warnings.filter((w) => w.source === source);
+        },
+        groupBySource() {
+            const groups = new Map();
+            for (const warning of warnings) {
+                const existing = groups.get(warning.source);
+                if (existing) {
+                    existing.push(warning);
+                }
+                else {
+                    groups.set(warning.source, [warning]);
+                }
+            }
+            return groups;
+        },
+        getSummary() {
+            const summary = {
+                validation: 0,
+                extraction: 0,
+                deduplication: 0,
+                'file-access': 0,
+                format: 0,
+            };
+            for (const warning of warnings) {
+                summary[warning.category]++;
+            }
+            return summary;
+        },
+        formatForConsole() {
+            if (warnings.length === 0) {
+                return '';
+            }
+            return warnings
+                .map((w) => {
+                const location = formatWarningLocation(w);
+                return `${ANSI.yellow}\u26a0 ${location} - ${w.message}${ANSI.reset}`;
+            })
+                .join('\n');
+        },
+        formatAsJson() {
+            return JSON.stringify(warnings.map((w) => ({
+                source: w.source,
+                line: w.line,
+                category: w.category,
+                subcategory: w.subcategory,
+                message: w.message,
+            })), null, 2);
+        },
+        formatAsMarkdown() {
+            if (warnings.length === 0) {
+                return '';
+            }
+            const lines = ['## Warnings', ''];
+            const groups = this.groupBySource();
+            for (const [source, sourceWarnings] of groups) {
+                lines.push(`### ${source}`, '');
+                for (const w of sourceWarnings) {
+                    const location = w.line !== undefined ? `:${w.line}` : '';
+                    lines.push(`- ${w.message}${location}`);
+                }
+                lines.push('');
+            }
+            return lines.join('\n');
+        },
+        isEmpty() {
+            return warnings.length === 0;
+        },
+        count() {
+            return warnings.length;
+        },
+    };
+}
+/**
+ * Utilities for creating ResultWithWarnings values
+ */
+export const ResultWithWarnings = {
+    /**
+     * Create a successful result with warnings
+     */
+    ok: (value, warnings = []) => ({
+        ok: true,
+        value,
+        warnings,
+    }),
+    /**
+     * Create an error result with warnings
+     */
+    err: (error, warnings = []) => ({
+        ok: false,
+        error,
+        warnings,
+    }),
+    /**
+     * Check if result is successful
+     */
+    isOk: (result) => result.ok,
+    /**
+     * Check if result is an error
+     */
+    isError: (result) => !result.ok,
+};
+//# sourceMappingURL=warning-collector.js.map

package/dist/generators/warning-collector.js.map

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

package/dist/git/branch-diff.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @architect
+ * @architect-pattern GitBranchDiff
+ * @architect-status active
+ * @architect-arch-role utility
+ * @architect-arch-context generator
+ * @architect-arch-layer infrastructure
+ * @architect-used-by Orchestrator
+ *
+ * ## GitBranchDiff - Pure Git Change Detection
+ *
+ * Provides lightweight git diff operations for determining which files changed
+ * relative to a base branch. This module exists to decouple the generators
+ * layer from the lint layer — the orchestrator needs file change lists for
+ * PR-scoped generation, but should not depend on Process Guard's domain-specific
+ * change detection (status transitions, deliverable changes).
+ *
+ * ### When to Use
+ *
+ * - When you need a list of changed files relative to a base branch
+ * - When orchestrating generation for only changed patterns
+ *
+ * ### When NOT to Use
+ *
+ * - For Process Guard validation — use detectBranchChanges from lint/process-guard
+ * - For status transition detection — use detectStagedChanges/detectBranchChanges
+ */
+import type { Result } from '../types/index.js';
+/**
+ * Get all files changed relative to a base branch (excludes deleted files).
+ *
+ * This is a lightweight alternative to detectBranchChanges from lint/process-guard
+ * that returns only the file list without domain-specific parsing (status transitions,
+ * deliverable changes). Used by the orchestrator for PR-scoped generation.
+ *
+ * Deleted files are excluded because the consumer (orchestrator) uses this list
+ * to scope generation to files that still exist on the current branch.
+ *
+ * @param baseDir - Repository base directory
+ * @param baseBranch - Branch to compare against (default: main)
+ * @returns Result containing array of changed file paths (modified + added), or error
+ */
+export declare function getChangedFilesList(baseDir: string, baseBranch?: string): Result<readonly string[]>;
+//# sourceMappingURL=branch-diff.d.ts.map

package/dist/git/branch-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-diff.d.ts","sourceRoot":"","sources":["../../src/git/branch-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAKhD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,SAAS,GAClB,MAAM,CAAC,SAAS,MAAM,EAAE,CAAC,CAU3B"}

package/dist/git/branch-diff.js

@@ -0,0 +1,57 @@
+/**
+ * @architect
+ * @architect-pattern GitBranchDiff
+ * @architect-status active
+ * @architect-arch-role utility
+ * @architect-arch-context generator
+ * @architect-arch-layer infrastructure
+ * @architect-used-by Orchestrator
+ *
+ * ## GitBranchDiff - Pure Git Change Detection
+ *
+ * Provides lightweight git diff operations for determining which files changed
+ * relative to a base branch. This module exists to decouple the generators
+ * layer from the lint layer — the orchestrator needs file change lists for
+ * PR-scoped generation, but should not depend on Process Guard's domain-specific
+ * change detection (status transitions, deliverable changes).
+ *
+ * ### When to Use
+ *
+ * - When you need a list of changed files relative to a base branch
+ * - When orchestrating generation for only changed patterns
+ *
+ * ### When NOT to Use
+ *
+ * - For Process Guard validation — use detectBranchChanges from lint/process-guard
+ * - For status transition detection — use detectStagedChanges/detectBranchChanges
+ */
+import { Result as R } from '../types/index.js';
+import { execGitSafe, sanitizeBranchName } from './helpers.js';
+import { parseGitNameStatus } from './name-status.js';
+/**
+ * Get all files changed relative to a base branch (excludes deleted files).
+ *
+ * This is a lightweight alternative to detectBranchChanges from lint/process-guard
+ * that returns only the file list without domain-specific parsing (status transitions,
+ * deliverable changes). Used by the orchestrator for PR-scoped generation.
+ *
+ * Deleted files are excluded because the consumer (orchestrator) uses this list
+ * to scope generation to files that still exist on the current branch.
+ *
+ * @param baseDir - Repository base directory
+ * @param baseBranch - Branch to compare against (default: main)
+ * @returns Result containing array of changed file paths (modified + added), or error
+ */
+export function getChangedFilesList(baseDir, baseBranch = 'main') {
+    try {
+        const safeBranch = sanitizeBranchName(baseBranch);
+        const mergeBase = execGitSafe('merge-base', [safeBranch, 'HEAD'], baseDir).trim();
+        const nameStatus = execGitSafe('diff', ['--name-status', '-z', mergeBase], baseDir);
+        const { modified, added } = parseGitNameStatus(nameStatus);
+        return R.ok([...modified, ...added]);
+    }
+    catch (error) {
+        return R.err(error instanceof Error ? error : new Error(String(error)));
+    }
+}
+//# sourceMappingURL=branch-diff.js.map

package/dist/git/branch-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-diff.js","sourceRoot":"","sources":["../../src/git/branch-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,UAAU,GAAG,MAAM;IAEnB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAClD,MAAM,SAAS,GAAG,WAAW,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAClF,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;QACpF,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAC3D,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,CAAC,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}

package/dist/git/helpers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @architect
+ * @architect-pattern GitHelpers
+ * @architect-status active
+ * @architect-arch-role utility
+ * @architect-arch-context generator
+ * @architect-arch-layer infrastructure
+ * @architect-used-by GitBranchDiff, DetectChanges
+ *
+ * ## GitHelpers - Shared Git Command Utilities
+ *
+ * Low-level helpers for safe git command execution and input sanitization.
+ * Used by both the generators layer (branch-diff) and the lint layer
+ * (detect-changes) to avoid duplicating security-critical code.
+ */
+/**
+ * Maximum buffer size for git command output (50MB).
+ * Large enough to handle staging entire dist/ folders with source maps.
+ * Prevents ENOBUFS errors when diff output exceeds Node.js default (~1MB).
+ */
+export declare const GIT_MAX_BUFFER: number;
+/**
+ * Execute a git subcommand safely using execFileSync (no shell interpolation).
+ *
+ * Uses execFileSync to bypass shell interpretation entirely, preventing
+ * metacharacter injection vulnerabilities.
+ *
+ * @param subcommand - Git subcommand (e.g., 'merge-base', 'diff', 'ls-files')
+ * @param args - Array of arguments (never interpolated into a shell command)
+ * @param cwd - Working directory
+ * @returns Command output as string
+ */
+export declare function execGitSafe(subcommand: string, args: readonly string[], cwd: string): string;
+/**
+ * Validate and sanitize a git branch name to prevent command injection.
+ *
+ * Allows only alphanumeric characters, dots, hyphens, underscores, and forward slashes.
+ * This matches the valid git branch name character set per git-check-ref-format.
+ * Excludes shell metacharacters: ; | & $ ` ( ) { } [ ] < > ! ~ ^ * ? " ' \
+ *
+ * @param branch - Branch name to validate
+ * @returns The validated branch name (unchanged if valid)
+ * @throws Error if branch name contains invalid characters or path traversal
+ */
+export declare function sanitizeBranchName(branch: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/git/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/git/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAmB,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAO5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAazD"}

package/dist/git/helpers.js

@@ -0,0 +1,67 @@
+/**
+ * @architect
+ * @architect-pattern GitHelpers
+ * @architect-status active
+ * @architect-arch-role utility
+ * @architect-arch-context generator
+ * @architect-arch-layer infrastructure
+ * @architect-used-by GitBranchDiff, DetectChanges
+ *
+ * ## GitHelpers - Shared Git Command Utilities
+ *
+ * Low-level helpers for safe git command execution and input sanitization.
+ * Used by both the generators layer (branch-diff) and the lint layer
+ * (detect-changes) to avoid duplicating security-critical code.
+ */
+import { execFileSync } from 'child_process';
+/**
+ * Maximum buffer size for git command output (50MB).
+ * Large enough to handle staging entire dist/ folders with source maps.
+ * Prevents ENOBUFS errors when diff output exceeds Node.js default (~1MB).
+ */
+export const GIT_MAX_BUFFER = 50 * 1024 * 1024;
+/**
+ * Execute a git subcommand safely using execFileSync (no shell interpolation).
+ *
+ * Uses execFileSync to bypass shell interpretation entirely, preventing
+ * metacharacter injection vulnerabilities.
+ *
+ * @param subcommand - Git subcommand (e.g., 'merge-base', 'diff', 'ls-files')
+ * @param args - Array of arguments (never interpolated into a shell command)
+ * @param cwd - Working directory
+ * @returns Command output as string
+ */
+export function execGitSafe(subcommand, args, cwd) {
+    return execFileSync('git', [subcommand, ...args], {
+        cwd,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        maxBuffer: GIT_MAX_BUFFER,
+    });
+}
+/**
+ * Validate and sanitize a git branch name to prevent command injection.
+ *
+ * Allows only alphanumeric characters, dots, hyphens, underscores, and forward slashes.
+ * This matches the valid git branch name character set per git-check-ref-format.
+ * Excludes shell metacharacters: ; | & $ ` ( ) { } [ ] < > ! ~ ^ * ? " ' \
+ *
+ * @param branch - Branch name to validate
+ * @returns The validated branch name (unchanged if valid)
+ * @throws Error if branch name contains invalid characters or path traversal
+ */
+export function sanitizeBranchName(branch) {
+    // Reject leading hyphens to prevent git option injection (e.g., --help, -c)
+    if (branch.startsWith('-')) {
+        throw new Error(`Invalid branch name (starts with hyphen): ${branch}`);
+    }
+    if (!/^[a-zA-Z0-9._\-/]+$/.test(branch)) {
+        throw new Error(`Invalid branch name: ${branch}`);
+    }
+    // Prevent path traversal attempts in branch names
+    if (branch.includes('..')) {
+        throw new Error(`Invalid branch name (contains ..): ${branch}`);
+    }
+    return branch;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/git/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/git/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,UAAkB,EAAE,IAAuB,EAAE,GAAW;IAClF,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,EAAE;QAChD,GAAG;QACH,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;QAC/B,SAAS,EAAE,cAAc;KAC1B,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,4EAA4E;IAC5E,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,6CAA6C,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,kDAAkD;IAClD,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,sCAAsC,MAAM,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/git/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @architect
+ * @architect-pattern GitModule
+ * @architect-status active
+ * @architect-arch-role barrel
+ * @architect-arch-context generator
+ * @architect-arch-layer infrastructure
+ * @architect-uses GitBranchDiff, GitHelpers
+ *
+ * ## Git Module - Pure Git Operations
+ *
+ * Shared git utilities used by both generators and lint layers.
+ * Decouples orchestrator from Process Guard's domain-specific change detection.
+ */
+export { getChangedFilesList } from './branch-diff.js';
+export { parseGitNameStatus, type ParsedGitNameStatus } from './name-status.js';
+export { execGitSafe, sanitizeBranchName, GIT_MAX_BUFFER } from './helpers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/git/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/git/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/git/index.js

@@ -0,0 +1,18 @@
+/**
+ * @architect
+ * @architect-pattern GitModule
+ * @architect-status active
+ * @architect-arch-role barrel
+ * @architect-arch-context generator
+ * @architect-arch-layer infrastructure
+ * @architect-uses GitBranchDiff, GitHelpers
+ *
+ * ## Git Module - Pure Git Operations
+ *
+ * Shared git utilities used by both generators and lint layers.
+ * Decouples orchestrator from Process Guard's domain-specific change detection.
+ */
+export { getChangedFilesList } from './branch-diff.js';
+export { parseGitNameStatus } from './name-status.js';
+export { execGitSafe, sanitizeBranchName, GIT_MAX_BUFFER } from './helpers.js';
+//# sourceMappingURL=index.js.map

package/dist/git/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/git/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAA4B,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/git/name-status.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @architect
+ * @architect-pattern GitNameStatusParser
+ * @architect-status active
+ * @architect-arch-role utility
+ * @architect-arch-context generator
+ * @architect-arch-layer infrastructure
+ * @architect-used-by GitBranchDiff, DetectChanges
+ *
+ * ## GitNameStatusParser - Shared Parsing for `git diff --name-status -z`
+ *
+ * Parses NUL-delimited git name-status output into categorized file lists.
+ * Using `-z` preserves filenames with spaces and rename/copy pairs without
+ * relying on whitespace splitting.
+ */
+export interface ParsedGitNameStatus {
+    readonly modified: string[];
+    readonly added: string[];
+    readonly deleted: string[];
+}
+/**
+ * Parse NUL-delimited `git diff --name-status -z` output.
+ *
+ * Git emits records as:
+ * - `M\0path\0`
+ * - `A\0path\0`
+ * - `D\0path\0`
+ * - `R100\0old_path\0new_path\0`
+ * - `C087\0source_path\0copy_path\0`
+ */
+export declare function parseGitNameStatus(output: string): ParsedGitNameStatus;
+//# sourceMappingURL=name-status.d.ts.map

package/dist/git/name-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name-status.d.ts","sourceRoot":"","sources":["../../src/git/name-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CA0CtE"}