specweave 0.33.5 → 0.34.0

package/dist/src/core/project/project-resolution.d.ts

@@ -0,0 +1,229 @@
+/**
+ * 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-0140):
+ * - 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<ResolvedProject>;
+    /**
+     * 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<ResolvedProject>;
+    /**
+     * 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<string[]>;
+    /**
+     * 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<string[]>;
+    /**
+     * 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

package/dist/src/core/project/project-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-resolution.d.ts","sourceRoot":"","sources":["../../../../src/core/project/project-resolution.ts"],"names":[],"mappings":"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"}