@hyperfrontend/versioning 0.1.0 → 0.2.0

package/flow/executor/index.esm.js

@@ -1,8 +1,8 @@
 import 'node:util';
-import { join, normalize, sep, isAbsolute as isAbsolute$1, relative, resolve, dirname } from 'node:path';
-import { existsSync, mkdirSync, statSync, lstatSync, readdirSync, readFileSync, readlinkSync, unlinkSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
+import { join as join$1, normalize, sep, isAbsolute as isAbsolute$1, relative, resolve, dirname, parse as parse$1, basename } from 'node:path';
+import { existsSync, readFileSync, mkdirSync, statSync, lstatSync, readdirSync, readlinkSync, unlinkSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
 import 'node:os';
-import { execSync } from 'node:child_process';
+import { execFileSync, execSync } from 'node:child_process';
 
 /**
  * Safe copies of Date built-in via factory function and static methods.
@@ -115,6 +115,10 @@ const keys = _Object.keys;
  * (Safe copy) Returns an array of key/values of the enumerable own properties of an object.
  */
 const entries = _Object.entries;
+/**
+ * (Safe copy) Returns an array of values of the enumerable own properties of an object.
+ */
+const values = _Object.values;
 /**
  * (Safe copy) Adds one or more properties to an object, and/or modifies attributes of existing properties.
  */
@@ -572,7 +576,7 @@ function createScopedLogger(namespace, options = {}) {
  */
 createScopedLogger('project-scope');
 
-createScopedLogger('project-scope:fs');
+const fsLogger = createScopedLogger('project-scope:fs');
 /**
  * Create a file system error with code and context.
  *
@@ -589,6 +593,71 @@ function createFileSystemError(message, code, context) {
     });
     return error;
 }
+/**
+ * Read file contents as string.
+ *
+ * @param filePath - Path to file
+ * @param encoding - File encoding (default: utf-8)
+ * @returns File contents as string
+ * @throws {Error} If file doesn't exist or can't be read
+ *
+ * @example
+ * ```typescript
+ * import { readFileContent } from '@hyperfrontend/project-scope'
+ *
+ * const content = readFileContent('./package.json')
+ * console.log(content) // JSON string
+ * ```
+ */
+function readFileContent(filePath, encoding = 'utf-8') {
+    if (!existsSync(filePath)) {
+        fsLogger.debug('File not found', { path: filePath });
+        throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
+    }
+    try {
+        return readFileSync(filePath, { encoding });
+    }
+    catch (error) {
+        fsLogger.warn('Failed to read file', { path: filePath });
+        throw createFileSystemError(`Failed to read file: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read', cause: error });
+    }
+}
+/**
+ * Read file if exists, return null otherwise.
+ *
+ * @param filePath - Path to file
+ * @param encoding - File encoding (default: utf-8)
+ * @returns File contents or null if file doesn't exist
+ */
+function readFileIfExists(filePath, encoding = 'utf-8') {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return readFileSync(filePath, { encoding });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read and parse JSON file if exists, return null otherwise.
+ *
+ * @param filePath - Path to JSON file
+ * @returns Parsed JSON object or null if file doesn't exist or is invalid
+ */
+function readJsonFileIfExists(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(filePath, { encoding: 'utf-8' });
+        return parse(content);
+    }
+    catch {
+        return null;
+    }
+}
 
 const fsWriteLogger = createScopedLogger('project-scope:fs:write');
 /**
@@ -694,7 +763,7 @@ function readDirectory(dirPath) {
         fsDirLogger.debug('Directory read complete', { path: dirPath, entryCount: entries.length });
         return entries.map((entry) => ({
             name: entry.name,
-            path: join(dirPath, entry.name),
+            path: join$1(dirPath, entry.name),
             isFile: entry.isFile(),
             isDirectory: entry.isDirectory(),
             isSymlink: entry.isSymbolicLink(),
@@ -710,6 +779,17 @@ function readDirectory(dirPath) {
     }
 }
 
+/**
+ * Join path segments.
+ * Uses platform-specific separators (e.g., / or \).
+ *
+ * @param paths - Path segments to join
+ * @returns Joined path
+ */
+function join(...paths) {
+    return join$1(...paths);
+}
+
 /**
  * Normalize path separators to forward slashes.
  *
@@ -763,7 +843,7 @@ function relativePath(from, to) {
  * @returns Joined path with normalized separators
  */
 function joinPath(...segments) {
-    return normalizePath(join(...segments));
+    return normalizePath(join$1(...segments));
 }
 /**
  * Check if path is absolute.
@@ -785,9 +865,223 @@ function getDirname(filePath) {
     return normalizePath(dirname(filePath));
 }
 
-createScopedLogger('project-scope:fs:traversal');
+const fsTraversalLogger = createScopedLogger('project-scope:fs:traversal');
+/**
+ * Generic upward directory traversal.
+ * Name avoids similarity to fs.readdir/fs.readdirSync.
+ *
+ * @param startPath - Starting directory
+ * @param predicate - Function to test each directory
+ * @returns First matching directory or null
+ */
+function traverseUpward(startPath, predicate) {
+    fsTraversalLogger.debug('Starting upward traversal', { startPath });
+    let currentPath = resolve(startPath);
+    const rootPath = parse$1(currentPath).root;
+    while (currentPath !== rootPath) {
+        if (predicate(currentPath)) {
+            fsTraversalLogger.debug('Upward traversal found match', { startPath, foundPath: currentPath });
+            return currentPath;
+        }
+        currentPath = dirname(currentPath);
+    }
+    // Check root directory
+    if (predicate(rootPath)) {
+        fsTraversalLogger.debug('Upward traversal found match at root', { startPath, foundPath: rootPath });
+        return rootPath;
+    }
+    fsTraversalLogger.debug('Upward traversal found no match', { startPath });
+    return null;
+}
+/**
+ * Find directory containing any of the specified marker files.
+ *
+ * @param startPath - Starting directory
+ * @param markers - Array of marker file names to search for
+ * @returns First directory containing any marker, or null
+ */
+function locateByMarkers(startPath, markers) {
+    fsTraversalLogger.debug('Locating by markers', { startPath, markers });
+    const result = traverseUpward(startPath, (dir) => markers.some((marker) => exists(join(dir, marker))));
+    if (result) {
+        fsTraversalLogger.debug('Found directory with marker', { startPath, foundPath: result });
+    }
+    return result;
+}
+/**
+ * Find directory where predicate returns true, starting from given path.
+ *
+ * @param startPath - Starting directory
+ * @param test - Function to test if directory matches criteria
+ * @returns Matching directory path or null
+ */
+function findUpwardWhere(startPath, test) {
+    fsTraversalLogger.debug('Finding upward where condition met', { startPath });
+    return traverseUpward(startPath, test);
+}
+
+/**
+ * Create a structured error with code and optional context.
+ *
+ * @param message - The human-readable error message
+ * @param code - The machine-readable error code for programmatic handling
+ * @param context - Additional contextual information about the error
+ * @returns Structured error instance with code and context properties
+ *
+ * @example
+ * ```typescript
+ * import { createStructuredError } from '@hyperfrontend/project-scope'
+ *
+ * throw createStructuredError(
+ *   'Configuration file not found',
+ *   'CONFIG_NOT_FOUND',
+ *   { path: './config.json', searched: ['./config.json', './settings.json'] }
+ * )
+ * ```
+ */
+function createStructuredError(message, code, context) {
+    const error = createError(message);
+    error.code = code;
+    error.context = context ?? {};
+    return error;
+}
+/**
+ * Create a configuration-related error.
+ *
+ * @param message - The human-readable error message
+ * @param code - The machine-readable error code for programmatic handling
+ * @param context - Additional contextual information (e.g., file path, config key)
+ * @returns Structured error instance tagged with type 'config'
+ */
+function createConfigError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'config' });
+}
 
-createScopedLogger('project-scope:project:package');
+const packageLogger = createScopedLogger('project-scope:project:package');
+/**
+ * Verifies that a value is an object with only string values,
+ * used for validating dependency maps and script definitions.
+ *
+ * @param value - Value to check
+ * @returns True if value is a record of strings
+ */
+function isStringRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return values(value).every((v) => typeof v === 'string');
+}
+/**
+ * Extracts and normalizes the workspaces field from package.json,
+ * supporting both array format and object with packages array.
+ *
+ * @param value - Raw workspaces value from package.json
+ * @returns Normalized workspace patterns or undefined if invalid
+ */
+function parseWorkspaces(value) {
+    if (isArray(value) && value.every((v) => typeof v === 'string')) {
+        return value;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const obj = value;
+        if (isArray(obj['packages'])) {
+            return { packages: obj['packages'] };
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate and normalize package.json data.
+ *
+ * @param data - Raw parsed data
+ * @returns Validated package.json
+ */
+function validatePackageJson(data) {
+    if (typeof data !== 'object' || data === null) {
+        throw createError('package.json must be an object');
+    }
+    const pkg = data;
+    return {
+        name: typeof pkg['name'] === 'string' ? pkg['name'] : undefined,
+        version: typeof pkg['version'] === 'string' ? pkg['version'] : undefined,
+        description: typeof pkg['description'] === 'string' ? pkg['description'] : undefined,
+        main: typeof pkg['main'] === 'string' ? pkg['main'] : undefined,
+        module: typeof pkg['module'] === 'string' ? pkg['module'] : undefined,
+        browser: typeof pkg['browser'] === 'string' ? pkg['browser'] : undefined,
+        types: typeof pkg['types'] === 'string' ? pkg['types'] : undefined,
+        bin: typeof pkg['bin'] === 'string' || isStringRecord(pkg['bin']) ? pkg['bin'] : undefined,
+        scripts: isStringRecord(pkg['scripts']) ? pkg['scripts'] : undefined,
+        dependencies: isStringRecord(pkg['dependencies']) ? pkg['dependencies'] : undefined,
+        devDependencies: isStringRecord(pkg['devDependencies']) ? pkg['devDependencies'] : undefined,
+        peerDependencies: isStringRecord(pkg['peerDependencies']) ? pkg['peerDependencies'] : undefined,
+        optionalDependencies: isStringRecord(pkg['optionalDependencies']) ? pkg['optionalDependencies'] : undefined,
+        workspaces: parseWorkspaces(pkg['workspaces']),
+        exports: typeof pkg['exports'] === 'object' ? pkg['exports'] : undefined,
+        engines: isStringRecord(pkg['engines']) ? pkg['engines'] : undefined,
+        ...pkg,
+    };
+}
+/**
+ * Reads and parses package.json from a directory, validating
+ * the structure and normalizing fields to the PackageJson interface.
+ *
+ * @param projectPath - Project directory path or path to package.json
+ * @returns Parsed package.json
+ * @throws {Error} Error if file doesn't exist or is invalid
+ */
+function readPackageJson(projectPath) {
+    const packageJsonPath = projectPath.endsWith('package.json') ? projectPath : join$1(projectPath, 'package.json');
+    packageLogger.debug('Reading package.json', { path: packageJsonPath });
+    const content = readFileContent(packageJsonPath);
+    try {
+        const data = parse(content);
+        const validated = validatePackageJson(data);
+        packageLogger.debug('Package.json read successfully', { path: packageJsonPath, name: validated.name });
+        return validated;
+    }
+    catch (error) {
+        packageLogger.warn('Failed to parse package.json', {
+            path: packageJsonPath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw createConfigError(`Failed to parse package.json: ${packageJsonPath}`, 'CONFIG_PARSE_ERROR', {
+            filePath: packageJsonPath,
+            cause: error,
+        });
+    }
+}
+/**
+ * Attempts to read and parse package.json if it exists,
+ * returning null on missing file or parse failure.
+ *
+ * @param projectPath - Project directory path or path to package.json
+ * @returns Parsed package.json or null if not found
+ */
+function readPackageJsonIfExists(projectPath) {
+    const packageJsonPath = projectPath.endsWith('package.json') ? projectPath : join$1(projectPath, 'package.json');
+    const content = readFileIfExists(packageJsonPath);
+    if (!content) {
+        packageLogger.debug('Package.json not found', { path: packageJsonPath });
+        return null;
+    }
+    try {
+        const validated = validatePackageJson(parse(content));
+        packageLogger.debug('Package.json loaded', { path: packageJsonPath, name: validated.name });
+        return validated;
+    }
+    catch {
+        packageLogger.debug('Failed to parse package.json, returning null', { path: packageJsonPath });
+        return null;
+    }
+}
+/**
+ * Find nearest package.json by walking up the directory tree.
+ *
+ * @param startPath - Starting path
+ * @returns Path to directory containing package.json, or null if not found
+ */
+function findNearestPackageJson(startPath) {
+    return locateByMarkers(startPath, ['package.json']);
+}
 
 createScopedLogger('project-scope:heuristics:deps');
 
@@ -923,9 +1217,410 @@ function createCache$1(options) {
     return freeze(cache);
 }
 
-createScopedLogger('project-scope:project:walk');
+/**
+ * Pattern matching utilities with ReDoS protection.
+ * Uses character-by-character matching instead of regex where possible.
+ */
+/**
+ * Match path against glob pattern using safe character iteration.
+ * Avoids regex to prevent ReDoS attacks.
+ *
+ * Supported patterns:
+ * - * matches any characters except /
+ * - ** matches any characters including /
+ * - ? matches exactly one character except /
+ * - {a,b,c} matches any of the alternatives
+ *
+ * @param path - The filesystem path to test against the pattern
+ * @param pattern - The glob pattern to match against
+ * @returns True if path matches pattern
+ *
+ * @example
+ * ```typescript
+ * import { matchGlobPattern } from '@hyperfrontend/project-scope'
+ *
+ * matchGlobPattern('src/utils/helper.ts', '\*\*\/*.ts')     // true
+ * matchGlobPattern('test.spec.ts', '\*.spec.ts')          // true
+ * matchGlobPattern('config.json', '\*.{json,yaml}')       // true
+ * matchGlobPattern('src/index.ts', 'src/\*.ts')           // true
+ * ```
+ */
+function matchGlobPattern(path, pattern) {
+    return matchSegments(path.split('/'), pattern.split('/'), 0, 0);
+}
+/**
+ * Internal recursive function to match path segments against pattern segments.
+ *
+ * @param pathParts - Array of path segments split by '/'
+ * @param patternParts - Array of pattern segments split by '/'
+ * @param pathIdx - Current index in pathParts being examined
+ * @param patternIdx - Current index in patternParts being examined
+ * @returns True if remaining segments match
+ */
+function matchSegments(pathParts, patternParts, pathIdx, patternIdx) {
+    // Base cases
+    if (pathIdx === pathParts.length && patternIdx === patternParts.length) {
+        return true; // Both exhausted = match
+    }
+    if (patternIdx >= patternParts.length) {
+        return false; // Pattern exhausted but path remains
+    }
+    const patternPart = patternParts[patternIdx];
+    // Handle ** (globstar) - matches zero or more directories
+    if (patternPart === '**') {
+        // Try matching rest of pattern against current position and all future positions
+        for (let i = pathIdx; i <= pathParts.length; i++) {
+            if (matchSegments(pathParts, patternParts, i, patternIdx + 1)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    if (pathIdx >= pathParts.length) {
+        return false; // Path exhausted but pattern remains (and it's not **)
+    }
+    const pathPart = pathParts[pathIdx];
+    // Match current segment
+    if (matchSegment(pathPart, patternPart)) {
+        return matchSegments(pathParts, patternParts, pathIdx + 1, patternIdx + 1);
+    }
+    return false;
+}
+/**
+ * Match a single path segment against a pattern segment.
+ * Handles *, ?, and {a,b,c} patterns.
+ *
+ * @param text - The path segment text to match
+ * @param pattern - The pattern segment to match against
+ * @returns True if the text matches the pattern
+ */
+function matchSegment(text, pattern) {
+    let textIdx = 0;
+    let patternIdx = 0;
+    while (patternIdx < pattern.length) {
+        const char = pattern[patternIdx];
+        if (char === '*') {
+            // * matches zero or more characters
+            patternIdx++;
+            if (patternIdx === pattern.length) {
+                return true; // * at end matches rest of string
+            }
+            // Try matching rest of pattern at each position in text
+            for (let i = textIdx; i <= text.length; i++) {
+                if (matchSegmentFrom(text, i, pattern, patternIdx)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        else if (char === '?') {
+            // ? matches exactly one character
+            if (textIdx >= text.length) {
+                return false;
+            }
+            textIdx++;
+            patternIdx++;
+        }
+        else if (char === '{') {
+            // {a,b,c} matches any alternative
+            const closeIdx = findClosingBrace(pattern, patternIdx);
+            if (closeIdx === -1) {
+                // Unmatched brace, treat as literal
+                if (textIdx >= text.length || text[textIdx] !== char) {
+                    return false;
+                }
+                textIdx++;
+                patternIdx++;
+            }
+            else {
+                const alternatives = extractAlternatives(pattern.slice(patternIdx + 1, closeIdx));
+                for (const alt of alternatives) {
+                    if (matchSegmentFrom(text, textIdx, text.slice(0, textIdx) + alt + pattern.slice(closeIdx + 1), textIdx)) {
+                        return true;
+                    }
+                }
+                return false;
+            }
+        }
+        else {
+            // Literal character
+            if (textIdx >= text.length || text[textIdx] !== char) {
+                return false;
+            }
+            textIdx++;
+            patternIdx++;
+        }
+    }
+    return textIdx === text.length;
+}
+/**
+ * Helper to match from a specific position.
+ *
+ * @param text - The full text being matched
+ * @param textIdx - The starting index in text to match from
+ * @param pattern - The full pattern being matched
+ * @param patternIdx - The starting index in pattern to match from
+ * @returns True if the text matches the pattern from the given positions
+ */
+function matchSegmentFrom(text, textIdx, pattern, patternIdx) {
+    const remainingText = text.slice(textIdx);
+    const remainingPattern = pattern.slice(patternIdx);
+    return matchSegment(remainingText, remainingPattern);
+}
+/**
+ * Find closing brace for {a,b,c} pattern.
+ *
+ * @param pattern - The pattern string to search within
+ * @param startIdx - The index of the opening brace
+ * @returns The index of the matching closing brace, or -1 if not found
+ */
+function findClosingBrace(pattern, startIdx) {
+    let depth = 0;
+    for (let i = startIdx; i < pattern.length; i++) {
+        if (pattern[i] === '{') {
+            depth++;
+        }
+        else if (pattern[i] === '}') {
+            depth--;
+            if (depth === 0) {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Extract alternatives from {a,b,c} pattern content.
+ *
+ * @param content - The content between braces (without the braces themselves)
+ * @returns Array of alternative strings split by commas at depth 0
+ */
+function extractAlternatives(content) {
+    const alternatives = [];
+    let current = '';
+    let depth = 0;
+    for (let i = 0; i < content.length; i++) {
+        const char = content[i];
+        if (char === '{') {
+            depth++;
+            current += char;
+        }
+        else if (char === '}') {
+            depth--;
+            current += char;
+        }
+        else if (char === ',' && depth === 0) {
+            alternatives.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current) {
+        alternatives.push(current);
+    }
+    return alternatives;
+}
 
-createScopedLogger('project-scope:project:search');
+const walkLogger = createScopedLogger('project-scope:project:walk');
+/**
+ * Reads .gitignore file from the given directory and extracts
+ * non-comment patterns for use in file traversal filtering.
+ *
+ * @param startPath - Directory containing the .gitignore file
+ * @returns Array of gitignore patterns
+ */
+function loadGitignorePatterns(startPath) {
+    const patterns = [];
+    const gitignorePath = join$1(startPath, '.gitignore');
+    const content = readFileIfExists(gitignorePath);
+    if (content) {
+        const lines = content.split('\n');
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed && !trimmed.startsWith('#')) {
+                patterns.push(trimmed);
+            }
+        }
+    }
+    return patterns;
+}
+/**
+ * Evaluates whether a relative path should be ignored based on
+ * a list of gitignore-style patterns.
+ *
+ * @param relativePath - Path relative to the root directory
+ * @param patterns - Array of gitignore-style patterns to test
+ * @returns True if the path matches any ignore pattern
+ */
+function matchesIgnorePattern(relativePath, patterns) {
+    for (const pattern of patterns) {
+        if (matchPattern(relativePath, pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Tests if the given path matches a gitignore-style pattern,
+ * supporting negation patterns with '!' prefix.
+ * Uses safe character-by-character matching to prevent ReDoS attacks.
+ *
+ * @param path - File or directory path to test
+ * @param pattern - Gitignore-style pattern (may include wildcards)
+ * @returns True if the path matches the pattern (or doesn't match if negated)
+ */
+function matchPattern(path, pattern) {
+    const normalizedPattern = pattern.startsWith('/') ? pattern.slice(1) : pattern;
+    const isNegation = normalizedPattern.startsWith('!');
+    const actualPattern = isNegation ? normalizedPattern.slice(1) : normalizedPattern;
+    const matchesFullPath = matchGlobPattern(path, actualPattern) || matchGlobPattern(path, `**/${actualPattern}`);
+    const matchesSegment = path.split('/').some((segment) => matchGlobPattern(segment, actualPattern));
+    const matches = matchesFullPath || matchesSegment;
+    return isNegation ? !matches : matches;
+}
+/**
+ * Traverses a directory tree synchronously, calling a visitor function
+ * for each file and directory encountered. Supports depth limiting,
+ * hidden file filtering, and gitignore pattern matching.
+ *
+ * @param startPath - Root directory to begin traversal
+ * @param visitor - Callback function invoked for each file system entry
+ * @param options - Configuration for traversal behavior
+ */
+function walkDirectory(startPath, visitor, options) {
+    walkLogger.debug('Starting directory walk', {
+        startPath,
+        maxDepth: options?.maxDepth ?? -1,
+        includeHidden: options?.includeHidden ?? false,
+        respectGitignore: options?.respectGitignore ?? true,
+        ignorePatterns: options?.ignorePatterns?.length ?? 0,
+    });
+    const maxDepth = options?.maxDepth ?? -1;
+    const includeHidden = options?.includeHidden ?? false;
+    const ignorePatterns = options?.ignorePatterns ?? [];
+    const respectGitignore = options?.respectGitignore ?? true;
+    const gitignorePatterns = respectGitignore ? loadGitignorePatterns(startPath) : [];
+    const allIgnorePatterns = [...ignorePatterns, ...gitignorePatterns];
+    if (gitignorePatterns.length > 0) {
+        walkLogger.debug('Loaded gitignore patterns', { count: gitignorePatterns.length });
+    }
+    /**
+     * Recursively walks directory entries, applying visitor to each.
+     *
+     * @param currentPath - Absolute path to current directory
+     * @param relativePath - Path relative to the starting directory
+     * @param depth - Current recursion depth
+     * @returns False to stop walking, true to continue
+     */
+    function walk(currentPath, relativePath, depth) {
+        if (maxDepth !== -1 && depth > maxDepth) {
+            return true;
+        }
+        let entries;
+        try {
+            entries = readDirectory(currentPath);
+        }
+        catch {
+            return true;
+        }
+        for (const entry of entries) {
+            if (!includeHidden && entry.name.startsWith('.')) {
+                continue;
+            }
+            const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+            if (matchesIgnorePattern(entryRelativePath, allIgnorePatterns)) {
+                continue;
+            }
+            const walkEntry = {
+                name: entry.name,
+                path: entry.path,
+                relativePath: entryRelativePath,
+                isFile: entry.isFile,
+                isDirectory: entry.isDirectory,
+                isSymlink: entry.isSymlink,
+                depth,
+            };
+            const result = visitor(walkEntry);
+            if (result === 'stop') {
+                return false;
+            }
+            if (result === 'skip') {
+                continue;
+            }
+            if (entry.isDirectory) {
+                const shouldContinue = walk(entry.path, entryRelativePath, depth + 1);
+                if (!shouldContinue) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    walk(startPath, '', 0);
+    walkLogger.debug('Directory walk complete', { startPath });
+}
+
+const searchLogger = createScopedLogger('project-scope:project:search');
+/**
+ * Tests if a path matches at least one pattern from an array of globs,
+ * enabling flexible multi-pattern file filtering.
+ * Uses safe character-by-character matching to prevent ReDoS attacks.
+ *
+ * @param path - File path to test
+ * @param patterns - Array of glob patterns
+ * @returns True if path matches any pattern
+ */
+function matchesPatterns(path, patterns) {
+    return patterns.some((pattern) => matchGlobPattern(path, pattern));
+}
+/**
+ * Searches a directory tree for files matching one or more glob patterns,
+ * returning relative or absolute paths based on options.
+ *
+ * @param startPath - Root directory to begin the search
+ * @param patterns - Glob patterns (e.g., '*.ts', '**\/*.json') to filter files
+ * @param options - Configuration for search behavior
+ * @returns List of relative file paths that match the patterns
+ *
+ * @example
+ * ```typescript
+ * import { findFiles } from '@hyperfrontend/project-scope'
+ *
+ * // Find all TypeScript files
+ * const tsFiles = findFiles('./src', '\*\*\/*.ts')
+ *
+ * // Find multiple file types
+ * const configFiles = findFiles('./', ['\*.json', '\*.yaml', '\*.yml'])
+ *
+ * // Limit results and get absolute paths
+ * const first10 = findFiles('./src', '\*\*\/*.ts', {
+ *   maxResults: 10,
+ *   absolutePaths: true
+ * })
+ * ```
+ */
+function findFiles(startPath, patterns, options) {
+    const normalizedPatterns = isArray(patterns) ? patterns : [patterns];
+    searchLogger.debug('Finding files', { startPath, patterns: normalizedPatterns, maxResults: options?.maxResults });
+    const results = [];
+    const maxResults = options?.maxResults ?? Infinity;
+    walkDirectory(startPath, (entry) => {
+        if (results.length >= maxResults) {
+            return 'stop';
+        }
+        if (!entry.isFile) {
+            return undefined;
+        }
+        if (matchesPatterns(entry.relativePath, normalizedPatterns)) {
+            results.push(options?.absolutePaths ? entry.path : entry.relativePath);
+        }
+        return undefined;
+    }, options);
+    searchLogger.debug('File search complete', { startPath, matchCount: results.length });
+    return results;
+}
 
 createScopedLogger('project-scope:heuristics:entry-points');
 /**
@@ -936,20 +1631,341 @@ createCache$1({ ttl: 60000, maxSize: 50 });
 
 createScopedLogger('project-scope:tech');
 /**
- * Cache for tech detection results.
- * TTL: 60 seconds (tech stack can change during active development)
+ * Cache for tech detection results.
+ * TTL: 60 seconds (tech stack can change during active development)
+ */
+createCache$1({ ttl: 60000, maxSize: 50 });
+
+createScopedLogger('project-scope:heuristics:project-type');
+
+const rootLogger = createScopedLogger('project-scope:root');
+/**
+ * Files indicating workspace/monorepo root.
+ */
+const WORKSPACE_MARKERS = ['nx.json', 'turbo.json', 'lerna.json', 'pnpm-workspace.yaml', 'rush.json'];
+/**
+ * Find workspace root (monorepo root).
+ * Searches up for workspace markers like nx.json, turbo.json, etc.
+ *
+ * @param startPath - Starting path
+ * @returns Workspace root path or null
+ *
+ * @example
+ * ```typescript
+ * import { findWorkspaceRoot } from '@hyperfrontend/project-scope'
+ *
+ * const root = findWorkspaceRoot('./libs/my-lib')
+ * if (root) {
+ *   console.log('Monorepo root:', root) // e.g., '/home/user/my-monorepo'
+ * }
+ * ```
+ */
+function findWorkspaceRoot(startPath) {
+    rootLogger.debug('Finding workspace root', { startPath });
+    const byMarker = locateByMarkers(startPath, WORKSPACE_MARKERS);
+    if (byMarker) {
+        rootLogger.debug('Found workspace root by marker', { root: byMarker });
+        return byMarker;
+    }
+    const byWorkspaces = findUpwardWhere(startPath, (dir) => {
+        const pkg = readPackageJsonIfExists(dir);
+        return pkg?.workspaces !== undefined;
+    });
+    if (byWorkspaces) {
+        rootLogger.debug('Found workspace root by workspaces field', { root: byWorkspaces });
+        return byWorkspaces;
+    }
+    const byPackage = findNearestPackageJson(startPath);
+    if (byPackage) {
+        rootLogger.debug('Found workspace root by package.json', { root: byPackage });
+    }
+    else {
+        rootLogger.debug('Workspace root not found');
+    }
+    return byPackage;
+}
+
+const nxLogger = createScopedLogger('project-scope:nx');
+/**
+ * Files indicating NX workspace root.
+ */
+const NX_CONFIG_FILES = ['nx.json', 'workspace.json'];
+/**
+ * NX-specific project file.
+ */
+const NX_PROJECT_FILE = 'project.json';
+/**
+ * Check if directory is an NX workspace root.
+ *
+ * @param path - Directory path to check
+ * @returns True if the directory contains nx.json or workspace.json
+ *
+ * @example
+ * ```typescript
+ * import { isNxWorkspace } from '@hyperfrontend/project-scope'
+ *
+ * if (isNxWorkspace('./my-project')) {
+ *   console.log('This is an NX monorepo')
+ * }
+ * ```
+ */
+function isNxWorkspace(path) {
+    for (const configFile of NX_CONFIG_FILES) {
+        if (exists(join$1(path, configFile))) {
+            nxLogger.debug('NX workspace detected', { path, configFile });
+            return true;
+        }
+    }
+    nxLogger.debug('Not an NX workspace', { path });
+    return false;
+}
+/**
+ * Check if directory is an NX project.
+ *
+ * @param path - Directory path to check
+ * @returns True if the directory contains project.json
+ */
+function isNxProject(path) {
+    const isProject = exists(join$1(path, NX_PROJECT_FILE));
+    nxLogger.debug('NX project check', { path, isProject });
+    return isProject;
+}
+/**
+ * Detect NX version from package.json dependencies.
+ *
+ * @param workspacePath - Workspace root path
+ * @returns NX version string (without semver range) or null
+ */
+function detectNxVersion(workspacePath) {
+    const packageJson = readPackageJsonIfExists(workspacePath);
+    if (packageJson) {
+        const nxVersion = packageJson.devDependencies?.['nx'] ?? packageJson.dependencies?.['nx'];
+        if (nxVersion) {
+            // Strip semver range characters (^, ~, >=, etc.)
+            return nxVersion.replace(/^[\^~>=<]+/, '');
+        }
+    }
+    return null;
+}
+/**
+ * Check if workspace is integrated (not standalone).
+ * Integrated repos typically have workspaceLayout, namedInputs, or targetDefaults.
+ *
+ * @param nxJson - Parsed nx.json configuration
+ * @returns True if the workspace is integrated
+ */
+function isIntegratedRepo(nxJson) {
+    return nxJson.workspaceLayout !== undefined || nxJson.namedInputs !== undefined || nxJson.targetDefaults !== undefined;
+}
+/**
+ * Get comprehensive NX workspace information.
+ *
+ * @param workspacePath - Workspace root path
+ * @returns Workspace info or null if not an NX workspace
+ */
+function getNxWorkspaceInfo(workspacePath) {
+    nxLogger.debug('Getting NX workspace info', { workspacePath });
+    if (!isNxWorkspace(workspacePath)) {
+        return null;
+    }
+    const nxJson = readJsonFileIfExists(join$1(workspacePath, 'nx.json'));
+    if (!nxJson) {
+        // Check for workspace.json as fallback (older NX)
+        const workspaceJson = readJsonFileIfExists(join$1(workspacePath, 'workspace.json'));
+        if (!workspaceJson) {
+            nxLogger.debug('No nx.json or workspace.json found', { workspacePath });
+            return null;
+        }
+        nxLogger.debug('Using legacy workspace.json', { workspacePath });
+        // Create minimal nx.json from workspace.json
+        return {
+            root: workspacePath,
+            version: detectNxVersion(workspacePath),
+            nxJson: {},
+            isIntegrated: true,
+            workspaceLayout: {
+                appsDir: 'apps',
+                libsDir: 'libs',
+            },
+        };
+    }
+    const info = {
+        root: workspacePath,
+        version: detectNxVersion(workspacePath),
+        nxJson,
+        isIntegrated: isIntegratedRepo(nxJson),
+        defaultProject: nxJson.defaultProject,
+        workspaceLayout: {
+            appsDir: nxJson.workspaceLayout?.appsDir ?? 'apps',
+            libsDir: nxJson.workspaceLayout?.libsDir ?? 'libs',
+        },
+    };
+    nxLogger.debug('NX workspace info retrieved', {
+        workspacePath,
+        version: info.version,
+        isIntegrated: info.isIntegrated,
+        defaultProject: info.defaultProject,
+    });
+    return info;
+}
+
+createScopedLogger('project-scope:nx:devkit');
+
+const nxConfigLogger = createScopedLogger('project-scope:nx:config');
+/**
+ * Read project.json for an NX project.
+ *
+ * @param projectPath - Project directory path
+ * @returns Parsed project.json or null if not found
+ */
+function readProjectJson(projectPath) {
+    const projectJsonPath = join$1(projectPath, NX_PROJECT_FILE);
+    nxConfigLogger.debug('Reading project.json', { path: projectJsonPath });
+    const result = readJsonFileIfExists(projectJsonPath);
+    if (result) {
+        nxConfigLogger.debug('Project.json loaded', { path: projectJsonPath, name: result.name });
+    }
+    else {
+        nxConfigLogger.debug('Project.json not found', { path: projectJsonPath });
+    }
+    return result;
+}
+/**
+ * Get project configuration from project.json or package.json nx field.
+ *
+ * @param projectPath - Project directory path
+ * @param workspacePath - Workspace root path (for relative path calculation)
+ * @returns Project configuration or null if not found
+ */
+function getProjectConfig(projectPath, workspacePath) {
+    nxConfigLogger.debug('Getting project config', { projectPath, workspacePath });
+    // Try project.json first
+    const projectJson = readProjectJson(projectPath);
+    if (projectJson) {
+        nxConfigLogger.debug('Using project.json config', { projectPath, name: projectJson.name });
+        return {
+            ...projectJson,
+            root: projectJson.root ?? relative(workspacePath, projectPath),
+        };
+    }
+    // Try to infer from package.json nx field
+    const packageJson = readPackageJsonIfExists(projectPath);
+    if (packageJson && typeof packageJson['nx'] === 'object') {
+        nxConfigLogger.debug('Using package.json nx field', { projectPath, name: packageJson.name });
+        const nxConfig = packageJson['nx'];
+        return {
+            name: packageJson.name,
+            root: relative(workspacePath, projectPath),
+            ...nxConfig,
+        };
+    }
+    nxConfigLogger.debug('No project config found', { projectPath });
+    return null;
+}
+/**
+ * Recursively scan directory for project.json files.
+ *
+ * @param dirPath - Directory to scan
+ * @param workspacePath - Workspace root path
+ * @param projects - Map to add discovered projects to
+ * @param maxDepth - Maximum recursion depth
+ * @param currentDepth - Current recursion depth
  */
-createCache$1({ ttl: 60000, maxSize: 50 });
-
-createScopedLogger('project-scope:heuristics:project-type');
-
-createScopedLogger('project-scope:root');
-
-createScopedLogger('project-scope:nx');
-
-createScopedLogger('project-scope:nx:devkit');
-
-createScopedLogger('project-scope:nx:config');
+function scanForProjects(dirPath, workspacePath, projects, maxDepth, currentDepth = 0) {
+    if (currentDepth > maxDepth)
+        return;
+    try {
+        const entries = readDirectory(dirPath);
+        for (const entry of entries) {
+            // Skip node_modules and hidden directories
+            if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist') {
+                continue;
+            }
+            const fullPath = join$1(dirPath, entry.name);
+            if (entry.isDirectory) {
+                // Check if this directory is an NX project
+                if (isNxProject(fullPath)) {
+                    const config = getProjectConfig(fullPath, workspacePath);
+                    if (config) {
+                        const name = config.name || relative(workspacePath, fullPath).replace(/[\\/]/g, '-');
+                        projects.set(name, {
+                            ...config,
+                            name,
+                            root: relative(workspacePath, fullPath),
+                        });
+                    }
+                }
+                // Recursively scan subdirectories
+                scanForProjects(fullPath, workspacePath, projects, maxDepth, currentDepth + 1);
+            }
+        }
+    }
+    catch {
+        // Directory not readable, skip
+    }
+}
+/**
+ * Discover all NX projects in workspace.
+ * Supports both workspace.json (older format) and project.json (newer format).
+ *
+ * @param workspacePath - Workspace root path
+ * @returns Map of project name to configuration
+ */
+function discoverNxProjects(workspacePath) {
+    const projects = createMap();
+    // Check for workspace.json (older NX format)
+    const workspaceJson = readJsonFileIfExists(join$1(workspacePath, 'workspace.json'));
+    if (workspaceJson?.projects) {
+        for (const [name, config] of entries(workspaceJson.projects)) {
+            if (typeof config === 'string') {
+                // Path reference to project directory
+                const projectPath = join$1(workspacePath, config);
+                const projectConfig = getProjectConfig(projectPath, workspacePath);
+                if (projectConfig) {
+                    projects.set(name, { ...projectConfig, name });
+                }
+            }
+            else if (typeof config === 'object' && config !== null) {
+                // Inline config
+                projects.set(name, { name, ...config });
+            }
+        }
+        return projects;
+    }
+    // Scan for project.json files (newer NX format)
+    const workspaceInfo = getNxWorkspaceInfo(workspacePath);
+    const appsDir = workspaceInfo?.workspaceLayout.appsDir ?? 'apps';
+    const libsDir = workspaceInfo?.workspaceLayout.libsDir ?? 'libs';
+    const searchDirs = [appsDir, libsDir];
+    // Also check packages directory (common in some setups)
+    if (exists(join$1(workspacePath, 'packages'))) {
+        searchDirs.push('packages');
+    }
+    for (const dir of searchDirs) {
+        const dirPath = join$1(workspacePath, dir);
+        if (exists(dirPath) && isDirectory(dirPath)) {
+            try {
+                scanForProjects(dirPath, workspacePath, projects, 3);
+            }
+            catch {
+                // Directory not accessible
+            }
+        }
+    }
+    // Also check root-level projects (standalone projects in monorepo root)
+    if (isNxProject(workspacePath)) {
+        const config = readProjectJson(workspacePath);
+        if (config) {
+            const name = config.name || basename(workspacePath);
+            projects.set(name, {
+                ...config,
+                name,
+                root: '.',
+            });
+        }
+    }
+    return projects;
+}
 
 createScopedLogger('project-scope:config');
 /**
@@ -1454,7 +2470,7 @@ function commitChanges(tree, options) {
         return order[a.type] - order[b.type];
     });
     for (const change of sortedChanges) {
-        const absPath = join(tree.root, change.path);
+        const absPath = join$1(tree.root, change.path);
         try {
             switch (change.type) {
                 case 'CREATE':
@@ -1821,6 +2837,45 @@ function commitExists(hash, options = {}) {
         return false;
     }
 }
+/**
+ * Checks if a commit is reachable from HEAD (i.e., is an ancestor of HEAD).
+ *
+ * A commit may exist in the repository but be orphaned (not in current branch history).
+ * This function verifies that the commit is actually in the history of the current HEAD.
+ *
+ * Common use cases:
+ * - Verify an external commit reference before using it for range queries
+ * - Detect if history was rewritten (rebase/force push) after a reference was recorded
+ *
+ * @param hash - Commit hash to check
+ * @param options - Additional options
+ * @returns True if the commit is an ancestor of HEAD
+ *
+ * @example
+ * if (commitReachableFromHead(baseCommit)) {
+ *   // Safe to use for commit range queries
+ *   const commits = getCommitsSince(baseCommit)
+ * } else {
+ *   // Commit not in current history, need fallback strategy
+ * }
+ */
+function commitReachableFromHead(hash, options = {}) {
+    const safeHash = escapeGitRef(hash);
+    try {
+        // git merge-base --is-ancestor exits with 0 if commit is ancestor of HEAD
+        execFileSync('git', ['merge-base', '--is-ancestor', safeHash, 'HEAD'], {
+            encoding: 'utf-8',
+            cwd: options.cwd,
+            timeout: options.timeout ?? 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        // Exit code 1 means not an ancestor, other errors also return false
+        return false;
+    }
+}
 /**
  * Parses raw git log output into GitCommit objects.
  *
@@ -3463,6 +4518,7 @@ function createGitClient(config = {}) {
         getCommitsSince: (since, options) => getCommitsSince(since, { ...opts, ...options }),
         getCommit: (hash) => getCommit(hash, opts),
         commitExists: (hash) => commitExists(hash, opts),
+        commitReachableFromHead: (hash) => commitReachableFromHead(hash, opts),
         // Tag operations
         getTags: (options) => getTags({ ...opts, ...options }),
         getTag: (name) => getTag(name, opts),
@@ -3506,6 +4562,7 @@ function createGitClient(config = {}) {
         fetch: (remote, options) => fetch(opts, remote, options),
         pull: (remote, branch) => pull(opts, remote, branch),
         push: (remote, branch, options) => push(opts, remote, branch, options),
+        getRemoteUrl: (remoteName) => getRemoteUrl(opts, remoteName),
     };
 }
 // ============================================================================
@@ -3676,6 +4733,29 @@ function push(options, remote = 'origin', branch, pushOptions) {
         return false;
     }
 }
+/**
+ * Gets the URL of a remote.
+ *
+ * @param options - Configuration object containing cwd and timeout
+ * @param options.cwd - Working directory for the git command
+ * @param options.timeout - Command timeout in milliseconds
+ * @param remoteName - Name of the remote (defaults to 'origin')
+ * @returns The remote URL, or null if not found
+ */
+function getRemoteUrl(options, remoteName = 'origin') {
+    try {
+        const output = execFileSync('git', ['remote', 'get-url', remoteName], {
+            encoding: 'utf-8',
+            cwd: options.cwd,
+            timeout: options.timeout,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return output.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
 
 /**
  * Creates a new cache instance.
@@ -3881,6 +4961,7 @@ async function getVersionInfo(state, packageName, version) {
             engines: data.engines,
             nodeVersion: data._nodeVersion,
             npmVersion: data._npmVersion,
+            gitHead: data.gitHead,
         };
         state.cache.set(cacheKey, info);
         return info;
@@ -3919,9 +5000,6 @@ async function listVersions(state, packageName) {
         return [];
     }
 }
-// ============================================================================
-// Security helpers - character-by-character validation (no regex)
-// ============================================================================
 /**
  * Maximum allowed package name length (npm limit).
  */
@@ -4045,6 +5123,422 @@ function createRegistry(type = 'npm', config = {}) {
     }
 }
 
+/**
+ * Project Model
+ *
+ * Represents a single project/package within a workspace.
+ * Contains package.json data, paths, and dependency information.
+ */
+/**
+ * Creates a new Project object.
+ *
+ * @param options - Project properties
+ * @returns A new Project object
+ */
+function createProject(options) {
+    const isPrivate = options.packageJson['private'] === true;
+    const publishable = !isPrivate && options.name !== undefined && options.version !== undefined;
+    return {
+        name: options.name,
+        version: options.version,
+        path: options.path,
+        packageJsonPath: options.packageJsonPath,
+        packageJson: options.packageJson,
+        changelogPath: options.changelogPath ?? null,
+        internalDependencies: options.internalDependencies ?? [],
+        internalDependents: options.internalDependents ?? [],
+        publishable,
+        private: isPrivate,
+    };
+}
+
+/**
+ * Workspace Model
+ *
+ * Represents a monorepo workspace with multiple projects.
+ * Used for package discovery, dependency tracking, and coordinated versioning.
+ */
+/**
+ * Default workspace discovery patterns.
+ */
+const DEFAULT_PATTERNS = [
+    'libs/*/package.json',
+    'apps/*/package.json',
+    'packages/*/package.json',
+    'tools/*/package.json',
+    'plugins/*/package.json',
+];
+/**
+ * Default exclusion patterns.
+ */
+const DEFAULT_EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/coverage/**', '**/.git/**'];
+/**
+ * Default workspace configuration.
+ */
+const DEFAULT_WORKSPACE_CONFIG = {
+    patterns: DEFAULT_PATTERNS,
+    exclude: DEFAULT_EXCLUDE,
+    includeChangelogs: true,
+    trackDependencies: true,
+};
+
+/**
+ * Dependency Graph
+ *
+ * Builds and analyzes dependency relationships between workspace projects.
+ * Provides functions for traversing the dependency graph and determining
+ * build/release order.
+ */
+/**
+ * Finds internal dependencies in a package.json.
+ * Returns names of workspace packages that this package depends on.
+ *
+ * @param packageJson - Parsed package.json content
+ * @param workspacePackageNames - Set of all package names in the workspace
+ * @returns Array of internal dependency names
+ *
+ * @example
+ * ```typescript
+ * const internalDeps = findInternalDependencies(packageJson, allPackageNames)
+ * // ['@scope/lib-a', '@scope/lib-b']
+ * ```
+ */
+function findInternalDependencies(packageJson, workspacePackageNames) {
+    const internal = [];
+    const allDeps = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
+        ...packageJson.peerDependencies,
+        ...packageJson.optionalDependencies,
+    };
+    for (const depName of keys(allDeps)) {
+        if (workspacePackageNames.has(depName)) {
+            internal.push(depName);
+        }
+    }
+    return internal;
+}
+
+/**
+ * Changelog Discovery
+ *
+ * Discovers CHANGELOG.md files within workspace projects.
+ */
+/**
+ * Common changelog file names in priority order.
+ */
+const CHANGELOG_NAMES = ['CHANGELOG.md', 'Changelog.md', 'changelog.md', 'HISTORY.md', 'CHANGES.md'];
+/**
+ * Finds changelog files for a list of packages.
+ * Returns a map of project path to changelog absolute path.
+ *
+ * @param workspaceRoot - Workspace root path
+ * @param packages - List of packages to find changelogs for
+ * @returns Map of project path to changelog path
+ */
+function findChangelogs(workspaceRoot, packages) {
+    const result = createMap();
+    for (const pkg of packages) {
+        const changelogPath = findProjectChangelog(pkg.path);
+        if (changelogPath) {
+            result.set(pkg.path, changelogPath);
+        }
+    }
+    return result;
+}
+/**
+ * Finds the changelog file for a single project.
+ * Checks for common changelog names in order of priority.
+ *
+ * @param projectPath - Path to project directory
+ * @returns Absolute path to changelog or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { findProjectChangelog } from '@hyperfrontend/versioning'
+ *
+ * const changelogPath = findProjectChangelog('./libs/my-lib')
+ * if (changelogPath) {
+ *   console.log('Found changelog:', changelogPath)
+ * }
+ * ```
+ */
+function findProjectChangelog(projectPath) {
+    for (const name of CHANGELOG_NAMES) {
+        const changelogPath = join$1(projectPath, name);
+        if (exists(changelogPath)) {
+            return changelogPath;
+        }
+    }
+    return null;
+}
+
+/**
+ * Discovers all packages within a workspace.
+ * Finds package.json files, parses them, and optionally discovers
+ * changelogs and internal dependencies.
+ *
+ * @param options - Discovery options
+ * @returns Discovery result with all found packages
+ * @throws {Error} If workspace root cannot be found
+ *
+ * @example
+ * ```typescript
+ * import { discoverPackages } from '@hyperfrontend/versioning'
+ *
+ * // Discover all packages in current workspace
+ * const result = discoverPackages()
+ *
+ * // Discover with custom patterns
+ * const result = discoverPackages({
+ *   patterns: ['packages/*\/package.json'],
+ *   includeChangelogs: true
+ * })
+ *
+ * // Access discovered projects
+ * for (const project of result.projects) {
+ *   console.log(`${project.name}@${project.version}`)
+ * }
+ * ```
+ */
+function discoverPackages(options = {}) {
+    // Resolve workspace root
+    const workspaceRoot = options.workspaceRoot ?? findWorkspaceRoot(process.cwd());
+    if (!workspaceRoot) {
+        throw createError('Could not find workspace root. Ensure you are in a monorepo with nx.json, turbo.json, or workspaces field.');
+    }
+    // Build configuration
+    const config = {
+        patterns: options.patterns ?? DEFAULT_WORKSPACE_CONFIG.patterns,
+        exclude: options.exclude ?? DEFAULT_WORKSPACE_CONFIG.exclude,
+        includeChangelogs: options.includeChangelogs ?? DEFAULT_WORKSPACE_CONFIG.includeChangelogs,
+        trackDependencies: options.trackDependencies ?? DEFAULT_WORKSPACE_CONFIG.trackDependencies,
+    };
+    // Find all package.json files
+    const packageJsonPaths = findPackageJsonFiles(workspaceRoot, config);
+    // Parse package.json files
+    const rawPackages = parsePackageJsonFiles(workspaceRoot, packageJsonPaths);
+    // Collect all package names for internal dependency detection
+    const packageNames = createSet(rawPackages.map((p) => p.name));
+    // Find changelogs if requested
+    const changelogMap = config.includeChangelogs ? findChangelogs(workspaceRoot, rawPackages) : createMap();
+    // Build projects with changelog paths
+    const rawWithChangelogs = rawPackages.map((pkg) => ({
+        ...pkg,
+        changelogPath: changelogMap.get(pkg.path) ?? null,
+    }));
+    // Calculate internal dependencies
+    const projects = config.trackDependencies
+        ? buildProjectsWithDependencies(rawWithChangelogs, packageNames)
+        : rawWithChangelogs.map((pkg) => createProject(pkg));
+    // Build project map
+    const projectMap = createMap();
+    for (const project of projects) {
+        projectMap.set(project.name, project);
+    }
+    return {
+        projects,
+        projectMap,
+        packageNames,
+        workspaceRoot,
+        config,
+    };
+}
+/**
+ * Finds all package.json files matching the configured patterns.
+ *
+ * @param workspaceRoot - Root directory to search from
+ * @param config - Workspace configuration
+ * @returns Array of relative paths to package.json files
+ */
+function findPackageJsonFiles(workspaceRoot, config) {
+    const patterns = [...config.patterns];
+    const excludePatterns = [...config.exclude];
+    return findFiles(workspaceRoot, patterns, {
+        ignorePatterns: excludePatterns,
+    });
+}
+/**
+ * Parses package.json files and extracts metadata.
+ *
+ * @param workspaceRoot - Workspace root path
+ * @param packageJsonPaths - Relative paths to package.json files
+ * @returns Array of raw package info objects
+ */
+function parsePackageJsonFiles(workspaceRoot, packageJsonPaths) {
+    const packages = [];
+    for (const relativePath of packageJsonPaths) {
+        const absolutePath = join$1(workspaceRoot, relativePath);
+        const projectPath = dirname(absolutePath);
+        try {
+            const packageJson = readPackageJson(absolutePath);
+            // Skip packages without a name
+            if (!packageJson.name) {
+                continue;
+            }
+            packages.push({
+                name: packageJson.name,
+                version: packageJson.version ?? '0.0.0',
+                path: projectPath,
+                packageJsonPath: absolutePath,
+                packageJson,
+                changelogPath: null,
+            });
+        }
+        catch {
+            // Skip packages that can't be parsed
+            continue;
+        }
+    }
+    return packages;
+}
+/**
+ * Builds projects with internal dependency information.
+ *
+ * @param rawPackages - Raw package info objects
+ * @param packageNames - Set of all package names
+ * @returns Array of Project objects with dependencies populated
+ */
+function buildProjectsWithDependencies(rawPackages, packageNames) {
+    // First pass: create projects with dependencies
+    const projectsWithDeps = [];
+    for (const pkg of rawPackages) {
+        const internalDeps = findInternalDependencies(pkg.packageJson, packageNames);
+        projectsWithDeps.push({
+            ...pkg,
+            internalDependencies: internalDeps,
+        });
+    }
+    // Build dependency -> dependents map
+    const dependentsMap = createMap();
+    for (const pkg of projectsWithDeps) {
+        for (const dep of pkg.internalDependencies) {
+            const existing = dependentsMap.get(dep) ?? [];
+            existing.push(pkg.name);
+            dependentsMap.set(dep, existing);
+        }
+    }
+    // Second pass: add dependents to each project
+    return projectsWithDeps.map((pkg) => {
+        const dependents = dependentsMap.get(pkg.name) ?? [];
+        return createProject({
+            ...pkg,
+            internalDependents: dependents,
+        });
+    });
+}
+/**
+ * Discovers a project by name within a workspace.
+ *
+ * @param projectName - Name of the project to find
+ * @param options - Discovery options
+ * @returns The project or null if not found
+ */
+function discoverProjectByName(projectName, options = {}) {
+    const result = discoverPackages(options);
+    return result.projectMap.get(projectName) ?? null;
+}
+
+/**
+ * Default scopes to exclude from changelogs.
+ *
+ * These represent repository-level or infrastructure changes
+ * that typically don't belong in individual project changelogs.
+ */
+const DEFAULT_EXCLUDE_SCOPES = ['release', 'deps', 'workspace', 'root', 'repo', 'ci', 'build'];
+
+/**
+ * Creates a matcher that checks if commit scope matches any of the given scopes.
+ *
+ * @param scopes - Scopes to match against (case-insensitive)
+ * @returns Matcher that returns true if scope matches
+ *
+ * @example
+ * const matcher = scopeMatcher(['ci', 'build', 'tooling'])
+ * matcher({ scope: 'CI', ... }) // true
+ * matcher({ scope: 'feat', ... }) // false
+ */
+function scopeMatcher(scopes) {
+    const normalizedScopes = createSet(scopes.map((s) => s.toLowerCase()));
+    return (ctx) => {
+        if (!ctx.scope)
+            return false;
+        return normalizedScopes.has(ctx.scope.toLowerCase());
+    };
+}
+/**
+ * Creates a matcher that checks if commit scope starts with any of the given prefixes.
+ *
+ * @param prefixes - Scope prefixes to match (case-insensitive)
+ * @returns Matcher that returns true if scope starts with any prefix
+ *
+ * @example
+ * const matcher = scopePrefixMatcher(['tool-', 'infra-'])
+ * matcher({ scope: 'tool-package', ... }) // true
+ * matcher({ scope: 'lib-utils', ... }) // false
+ */
+function scopePrefixMatcher(prefixes) {
+    const normalizedPrefixes = prefixes.map((p) => p.toLowerCase());
+    return (ctx) => {
+        if (!ctx.scope)
+            return false;
+        const normalizedScope = ctx.scope.toLowerCase();
+        return normalizedPrefixes.some((prefix) => normalizedScope.startsWith(prefix));
+    };
+}
+/**
+ * Combines matchers with OR logic - returns true if ANY matcher matches.
+ *
+ * @param matchers - Matchers to combine
+ * @returns Combined matcher
+ *
+ * @example
+ * const combined = anyOf(
+ *   scopeMatcher(['ci', 'build']),
+ *   messageMatcher(['[infra]']),
+ *   custom((ctx) => ctx.scope?.startsWith('tool-'))
+ * )
+ */
+function anyOf(...matchers) {
+    return (ctx) => matchers.some((matcher) => matcher(ctx));
+}
+/**
+ * Matches common CI/CD scopes.
+ *
+ * Matches: ci, cd, build, pipeline, workflow, actions
+ */
+const CI_SCOPE_MATCHER = scopeMatcher(['ci', 'cd', 'build', 'pipeline', 'workflow', 'actions']);
+/**
+ * Matches common tooling/workspace scopes.
+ *
+ * Matches: tooling, workspace, monorepo, nx, root
+ */
+const TOOLING_SCOPE_MATCHER = scopeMatcher(['tooling', 'workspace', 'monorepo', 'nx', 'root']);
+/**
+ * Matches tool-prefixed scopes (e.g., tool-package, tool-scripts).
+ */
+const TOOL_PREFIX_MATCHER = scopePrefixMatcher(['tool-']);
+/**
+ * Combined matcher for common infrastructure patterns.
+ *
+ * Combines CI, tooling, and tool-prefix matchers.
+ */
+anyOf(CI_SCOPE_MATCHER, TOOLING_SCOPE_MATCHER, TOOL_PREFIX_MATCHER);
+
+/**
+ * Default scope filtering configuration.
+ *
+ * Uses DEFAULT_EXCLUDE_SCOPES from commits/classify to ensure consistency
+ * between flow-level filtering and commit classification.
+ */
+const DEFAULT_SCOPE_FILTERING_CONFIG = {
+    strategy: 'hybrid',
+    includeScopes: [],
+    excludeScopes: DEFAULT_EXCLUDE_SCOPES,
+    trackDependencyChanges: false,
+    infrastructure: undefined,
+    infrastructureMatcher: undefined,
+};
 /**
  * Default flow configuration values.
  */
@@ -4065,50 +5559,90 @@ const DEFAULT_FLOW_CONFIG = {
     allowPrerelease: false,
     prereleaseId: 'alpha',
     releaseAs: undefined,
+    repository: undefined,
+    scopeFiltering: DEFAULT_SCOPE_FILTERING_CONFIG,
 };
 
 /**
- * Resolves the project root path from workspace root and project name.
+ * Discovers project root using multiple strategies.
  *
- * For now, uses a simple convention: libs/{projectName} or apps/{projectName}
- * In a real implementation, this would query the workspace configuration.
+ * Resolution order:
+ * 1. Explicit `projectRoot` option (from Nx executor)
+ * 2. Nx project discovery via `discoverNxProjects` (if in Nx workspace)
+ * 3. Workspace discovery via `discoverProjectByName`
  *
  * @param workspaceRoot - Workspace root path
  * @param projectName - Project name (e.g., 'lib-versioning')
- * @returns Absolute path to project root
- */
-function resolveProjectRoot(workspaceRoot, projectName) {
-    // Remove 'lib-' or 'app-' prefix to get the folder name
-    let folderName = projectName;
-    let prefix = 'libs';
-    if (projectName.startsWith('lib-')) {
-        folderName = projectName.slice(4);
-        prefix = 'libs';
+ * @param providedRoot - Explicitly provided project root (optional)
+ * @param logger - Logger instance
+ * @returns Resolution result with path and source, or null if not found
+ */
+function discoverProjectRoot(workspaceRoot, projectName, providedRoot, logger) {
+    // 1. Explicit projectRoot provided (preferred - from Nx executor)
+    if (providedRoot) {
+        const projectRoot = providedRoot.startsWith(workspaceRoot) ? providedRoot : `${workspaceRoot}/${providedRoot}`;
+        logger.debug(`Using provided project root: ${providedRoot}`);
+        return { projectRoot, source: 'provided' };
+    }
+    // 2. Try Nx project discovery (fast, if we're in an Nx workspace)
+    if (isNxWorkspace(workspaceRoot)) {
+        logger.debug('Nx workspace detected, attempting Nx project discovery');
+        try {
+            const nxProjects = discoverNxProjects(workspaceRoot);
+            const nxConfig = nxProjects.get(projectName);
+            if (nxConfig?.root) {
+                const projectRoot = `${workspaceRoot}/${nxConfig.root}`;
+                logger.debug(`Discovered project root via Nx: ${nxConfig.root}`);
+                return { projectRoot, source: 'nx-discovery' };
+            }
+            logger.debug(`Project "${projectName}" not found in Nx project graph`);
+        }
+        catch (error) {
+            logger.debug(`Nx project discovery failed: ${error}`);
+        }
+    }
+    // 3. Try workspace discovery (handles any monorepo structure)
+    logger.debug('Attempting workspace discovery via discoverProjectByName');
+    try {
+        const project = discoverProjectByName(projectName, { workspaceRoot });
+        if (project) {
+            logger.debug(`Discovered project root via workspace discovery: ${project.path}`);
+            return { projectRoot: project.path, source: 'workspace-discovery' };
+        }
+        logger.debug(`Project "${projectName}" not found via workspace discovery`);
     }
-    else if (projectName.startsWith('app-')) {
-        folderName = projectName.slice(4);
-        prefix = 'apps';
+    catch (error) {
+        logger.debug(`Workspace discovery failed: ${error}`);
     }
-    return `${workspaceRoot}/${prefix}/${folderName}`;
+    // All discovery methods failed
+    logger.error(`Could not discover project "${projectName}" in workspace "${workspaceRoot}". ` +
+        `Ensure the project exists and has a valid package.json, or pass projectRoot explicitly.`);
+    return null;
 }
 /**
  * Resolves the package name from the project root.
  *
  * @param tree - Virtual file system tree
  * @param projectRoot - Project root path
+ * @param logger - Logger instance for diagnostics
  * @returns Package name from package.json
  */
-function resolvePackageName(tree, projectRoot) {
+function resolvePackageName(tree, projectRoot, logger) {
     const packageJsonPath = `${projectRoot}/package.json`;
     try {
         const content = tree.read(packageJsonPath, 'utf-8');
         if (!content) {
+            logger.debug(`package.json is empty or not found at ${packageJsonPath}`);
             return 'unknown';
         }
         const pkg = parse(content);
+        if (!pkg.name) {
+            logger.debug(`package.json at ${packageJsonPath} has no name field`);
+        }
         return pkg.name ?? 'unknown';
     }
-    catch {
+    catch (error) {
+        logger.debug(`Failed to read package.json at ${packageJsonPath}: ${error}`);
         return 'unknown';
     }
 }
@@ -4185,9 +5719,37 @@ async function executeFlow(flow, projectName, workspaceRoot, options = {}) {
     const tree = options.tree ?? createTree(workspaceRoot);
     const registry = options.registry ?? createRegistry('npm');
     const git = options.git ?? createGitClient({ ...DEFAULT_GIT_CLIENT_CONFIG, cwd: workspaceRoot });
-    // Resolve paths
-    const projectRoot = resolveProjectRoot(workspaceRoot, projectName);
-    const packageName = resolvePackageName(tree, projectRoot);
+    // Resolve project root with smart discovery
+    const resolution = discoverProjectRoot(workspaceRoot, projectName, options.projectRoot, flowLogger);
+    // Fail early if project cannot be discovered
+    if (!resolution) {
+        return {
+            status: 'failed',
+            steps: [],
+            state: {},
+            duration: dateNow() - startTime,
+            summary: `Project "${projectName}" not found in workspace`,
+        };
+    }
+    const { projectRoot, source: projectRootSource } = resolution;
+    // Early validation: ensure project root is valid
+    const packageJsonPath = `${projectRoot}/package.json`;
+    if (!tree.exists(packageJsonPath)) {
+        const errorMsg = `Project root validation failed: ${packageJsonPath} does not exist. ` +
+            `Resolved projectRoot="${projectRoot}" (source: ${projectRootSource}) from projectName="${projectName}".`;
+        flowLogger.error(errorMsg);
+        return {
+            status: 'failed',
+            steps: [],
+            state: {},
+            duration: dateNow() - startTime,
+            summary: `Invalid project root: ${projectRoot}`,
+        };
+    }
+    const packageName = resolvePackageName(tree, projectRoot, flowLogger);
+    if (packageName === 'unknown') {
+        flowLogger.warn(`Could not read package name from ${packageJsonPath}`);
+    }
     // Initialize context
     const context = {
         workspaceRoot,