/** * ProjectResolutionService - Centralized project resolution for SpecWeave * * Provides authoritative project resolution with priority-based fallback chain: * 1. Per-US **Project**: fields (primary source of truth) * 2. Config project.name (single-project mode fallback) * 3. Intelligent keyword detection (multi-project mode) * 4. Ultimate fallback ("default") * * Key Architecture Decision (ADR-0195): * - Frontmatter project: field REMOVED as source * - Per-US fields are now the single source of truth * - This service centralizes all project resolution logic * * @module core/project/project-resolution */ import { ConfigManager } from '../config/config-manager.js'; import { Logger } from '../../utils/logger.js'; import { ProjectRegistry } from './project-registry.js'; /** * Resolved project result with confidence and source tracking */ export interface ResolvedProject { /** Resolved project identifier */ projectId: string; /** Confidence level of resolution */ confidence: 'high' | 'medium' | 'low'; /** Source of resolution for debugging */ source: 'per-us' | 'config' | 'detection' | 'fallback'; /** Detailed reasoning for the resolution */ reasoning: string[]; } /** * Options for ProjectResolutionService constructor */ export interface ProjectResolutionOptions { /** Logger instance for debugging */ logger?: Logger; /** ConfigManager instance (default: created from projectRoot) */ configManager?: ConfigManager; /** ProjectRegistry instance (default: created from projectRoot) */ registry?: ProjectRegistry; } /** * Centralized project resolution service * * Replaces fragmented frontmatter.project access throughout codebase * with a single, consistent resolution mechanism. */ export declare class ProjectResolutionService { private cache; private configManager; private registry; private logger; private projectRoot; /** * Create a new ProjectResolutionService * * @param projectRoot - Path to project root * @param options - Configuration options */ constructor(projectRoot: string, options?: ProjectResolutionOptions); /** * Resolve project for an increment with priority-based fallback * * Resolution Priority: * 1. Per-US **Project**: fields in spec.md (high confidence) * 2. Config project.name in single-project mode (high confidence) * 3. Intelligent keyword detection (medium/low confidence) * 4. Ultimate fallback to "default" (low confidence) * * @param incrementId - Increment folder name (e.g., "0001-feature-name") * @returns Resolved project with confidence and source */ resolveProjectForIncrement(incrementId: string): Promise; /** * Resolve project for spec content directly (without increment ID) * * Useful when spec content is already loaded and increment ID is not available. * * @param specContent - Raw spec.md content * @returns Resolved project with confidence and source */ resolveProjectFromContent(specContent: string): Promise; /** * Create a ResolvedProject from extracted US field projects */ private createResolvedProjectFromUSFields; /** * Priority 1: Extract from per-US **Project**: fields * * Scans spec.md for **Project**: field patterns in user stories. * This is the primary and preferred source of truth. */ private resolveFromPerUSFields; /** * Priority 2: Use config.project.name (single-project mode) * * Only applies when multiProject.enabled !== true. * In single-project mode, config.project.name is authoritative. */ private resolveFromConfig; /** * Priority 3: Intelligent detection from increment content * * Scores each available project based on keyword matching. * Only used in multi-project mode when per-US fields are missing. */ private resolveFromIntelligentDetection; /** * Priority 4: Ultimate fallback - "default" project * * This should rarely happen in practice. Indicates missing configuration. */ private resolveFallback; /** * Extract project IDs from **Project**: fields in spec.md * * Pattern: **Project**: project-id (case-insensitive, kebab-case) * * @param content - Spec content to scan * @returns Unique project IDs found */ extractProjectsFromUSFields(content: string): string[]; /** * Extract keywords from spec content for intelligent matching * * Filters out short words and common stopwords. */ private extractKeywords; /** * Get available projects from config * * Handles both single-project and multi-project modes. */ private getAvailableProjects; /** * Clear cache (useful for testing and after config changes) */ clearCache(): void; /** * Get cache statistics for debugging */ getCacheStats(): { size: number; keys: string[]; }; /** * Validate resolved project against the project registry * * Checks if the project exists in the registry and provides suggestions if not. * This integration supports AC-US9-01 through AC-US9-04 for Living Docs integration. * * @param projectId - Project ID to validate * @returns Validation result with suggestions if project not found */ validateAgainstRegistry(projectId: string): Promise<{ valid: boolean; projectId: string; inRegistry: boolean; suggestions?: string[]; techStack?: string[]; team?: string; }>; /** * Get project metadata from registry (techStack, team, etc.) * * Useful for enriching living docs with project context. * * @param projectId - Project ID to look up * @returns Project metadata or null if not found */ getProjectMetadata(projectId: string): Promise<{ techStack?: string[]; team?: string; description?: string; keywords?: string[]; } | null>; /** * Get the project registry instance * * Allows external code to interact with the registry directly. */ getRegistry(): ProjectRegistry; /** * Get all unique projects from an increment's user stories * * Useful for cross-project increment handling. * * @param incrementId - Increment folder name * @returns Array of unique project IDs */ getAllProjectsForIncrement(incrementId: string): Promise; /** * CRITICAL: Validate a project ID before folder creation * * This is the primary guard against folder pollution from example/invalid projects. * Called before any ensureDir() or mkdirSync() that creates project folders. * * Validation rules (STRICT - returns false if ANY rule fails): * 1. Must be a valid project format (kebab-case, alphanumeric) * 2. Must NOT be an obvious example/placeholder name * 3. In single-project mode: must match config.project.name * 4. In multi-project mode: must exist in config.multiProject.projects * * @param projectId - Project ID to validate * @returns Validation result with reason for rejection */ validateProjectForFolderCreation(projectId: string): Promise<{ valid: boolean; projectId: string; reason: string; allowedProjects: string[]; }>; /** * Filter project IDs extracted from spec.md to only valid projects * * This prevents example User Stories from polluting the specs folder. * Should be called after extractProjectsFromUSFields() to filter results. * * @param projectIds - Raw project IDs from spec.md * @returns Only valid, configured project IDs */ filterValidProjects(projectIds: string[]): Promise; /** * Synchronous check for common example project names * * Fast path for pre-tool-use hooks that can't be async. * Returns true if the project name looks like an example. */ static isExampleProjectName(projectId: string): boolean; } //# sourceMappingURL=project-resolution.d.ts.map