@eddacraft/anvil-aps 0.1.0

package/dist/validator/index.js

@@ -0,0 +1,611 @@
+/**
+ * Validator module - Validation rules for APS planning documents
+ *
+ * Provides validation for:
+ * - Required sections (Index: ## Modules, Leaf: ## Tasks)
+ * - Task format (ID, Intent required)
+ * - Duplicate task IDs across plan graph
+ * - Broken module links
+ * - Scope mismatches (warning)
+ * - Missing Confidence (warning)
+ * - Missing Expected Outcome (warning)
+ * - Missing Validation/Test (warning)
+ * - Orphan leaf specs (warning)
+ * - Circular module dependencies
+ */
+import { promises as fs, accessSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import { visit } from 'unist-util-visit';
+import { TASK_ID_REGEX } from '../types/index.js';
+import { loadPlan, detectCycles, resolvePath } from '../loader/index.js';
+/**
+ * Validate an APS planning document
+ *
+ * @param filePath - Path to the planning document (index or leaf spec)
+ * @param options - Validation options
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = await validatePlanningDoc('docs/planning/APS.md');
+ * if (!result.valid) {
+ *   for (const error of result.errors) {
+ *     console.error(`${error.path}:${error.lineNumber}: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export async function validatePlanningDoc(filePath, options = {}) {
+    const absolutePath = isAbsolute(filePath) ? filePath : resolve(filePath);
+    const baseDir = options.baseDir ?? dirname(absolutePath);
+    const recursive = options.recursive ?? true;
+    const skipRules = new Set(options.skipRules ?? []);
+    const issues = [];
+    // Read the file content
+    let content;
+    try {
+        content = await fs.readFile(absolutePath, 'utf-8');
+    }
+    catch (error) {
+        issues.push({
+            severity: 'error',
+            message: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
+            rule: 'file-readable',
+            path: absolutePath,
+        });
+        return createResult(issues);
+    }
+    // Determine document type and validate structure
+    const isIndex = detectIndexFile(content);
+    if (isIndex) {
+        // Validate index file structure
+        if (!skipRules.has('required-sections')) {
+            await validateIndexStructure(content, absolutePath, issues);
+        }
+        // Validate module links
+        if (!skipRules.has('broken-links') && recursive) {
+            await validateModuleLinks(content, absolutePath, baseDir, issues);
+        }
+    }
+    else {
+        // Validate leaf spec structure
+        if (!skipRules.has('required-sections')) {
+            validateLeafStructure(content, absolutePath, issues);
+        }
+        // Validate tasks
+        if (!skipRules.has('task-format')) {
+            validateTaskFormat(content, absolutePath, issues, skipRules);
+        }
+    }
+    // Load the full plan for cross-document validation
+    if (recursive) {
+        try {
+            const plan = await loadPlan(absolutePath, { baseDir, recursive: true });
+            // Check for duplicate task IDs
+            if (!skipRules.has('duplicate-ids')) {
+                validateDuplicateTaskIds(plan, issues);
+            }
+            // Check for circular dependencies
+            if (!skipRules.has('circular-dependencies')) {
+                validateCircularDependencies(plan, issues);
+            }
+            // Check scope mismatches
+            if (!skipRules.has('scope-mismatch')) {
+                validateScopeMismatches(plan, issues);
+            }
+            // Check for orphan modules (only if index file)
+            if (isIndex && !skipRules.has('orphan-modules')) {
+                await validateOrphanModules(absolutePath, baseDir, plan, issues);
+            }
+        }
+        catch (error) {
+            // If we can't load the plan, the earlier validation errors should explain why
+            if (issues.length === 0) {
+                issues.push({
+                    severity: 'error',
+                    message: `Failed to load plan: ${error instanceof Error ? error.message : String(error)}`,
+                    rule: 'plan-loadable',
+                    path: absolutePath,
+                });
+            }
+        }
+    }
+    return createResult(issues);
+}
+/**
+ * Detect if content is an index file (has ## Modules section)
+ */
+function detectIndexFile(content) {
+    const processor = unified().use(remarkParse);
+    const ast = processor.parse(content);
+    let hasModulesSection = false;
+    visit(ast, 'heading', (node) => {
+        if (node.depth === 2) {
+            let text = '';
+            visit(node, 'text', (textNode) => {
+                text += textNode.value;
+            });
+            const normalizedText = text.trim().toLowerCase();
+            if (normalizedText === 'modules' || normalizedText.startsWith('modules')) {
+                hasModulesSection = true;
+            }
+        }
+    });
+    return hasModulesSection;
+}
+/**
+ * Validate index file structure
+ */
+async function validateIndexStructure(content, filePath, issues) {
+    const processor = unified().use(remarkParse);
+    const ast = processor.parse(content);
+    let hasH1 = false;
+    let hasModulesSection = false;
+    let modulesLineNumber = 0;
+    let hasModuleEntries = false;
+    visit(ast, 'heading', (node) => {
+        if (node.depth === 1) {
+            hasH1 = true;
+        }
+        if (node.depth === 2) {
+            let text = '';
+            visit(node, 'text', (textNode) => {
+                text += textNode.value;
+            });
+            const normalizedText = text.trim().toLowerCase();
+            if (normalizedText === 'modules' || normalizedText.startsWith('modules')) {
+                hasModulesSection = true;
+                modulesLineNumber = node.position?.start.line ?? 0;
+            }
+        }
+        if (node.depth === 3 && hasModulesSection) {
+            hasModuleEntries = true;
+        }
+    });
+    if (!hasH1) {
+        issues.push({
+            severity: 'error',
+            message: 'Index file must have an H1 title',
+            rule: 'required-sections',
+            path: filePath,
+            lineNumber: 1,
+        });
+    }
+    if (!hasModulesSection) {
+        issues.push({
+            severity: 'error',
+            message: 'Index file must have a "## Modules" section',
+            rule: 'required-sections',
+            path: filePath,
+        });
+    }
+    else if (!hasModuleEntries) {
+        issues.push({
+            severity: 'warning',
+            message: '"## Modules" section has no module entries (H3 headings)',
+            rule: 'required-sections',
+            path: filePath,
+            lineNumber: modulesLineNumber,
+        });
+    }
+}
+/**
+ * Validate leaf spec structure
+ */
+function validateLeafStructure(content, filePath, issues) {
+    const processor = unified().use(remarkParse);
+    const ast = processor.parse(content);
+    let hasH1 = false;
+    let hasTasksSection = false;
+    let tasksLineNumber = 0;
+    let hasTaskEntries = false;
+    visit(ast, 'heading', (node) => {
+        if (node.depth === 1) {
+            hasH1 = true;
+        }
+        if (node.depth === 2) {
+            let text = '';
+            visit(node, 'text', (textNode) => {
+                text += textNode.value;
+            });
+            if (text.trim().toLowerCase() === 'tasks') {
+                hasTasksSection = true;
+                tasksLineNumber = node.position?.start.line ?? 0;
+            }
+        }
+        if (node.depth === 3 && hasTasksSection) {
+            hasTaskEntries = true;
+        }
+    });
+    if (!hasH1) {
+        issues.push({
+            severity: 'error',
+            message: 'Leaf spec must have an H1 title',
+            rule: 'required-sections',
+            path: filePath,
+            lineNumber: 1,
+        });
+    }
+    if (!hasTasksSection) {
+        issues.push({
+            severity: 'error',
+            message: 'Leaf spec must have a "## Tasks" section',
+            rule: 'required-sections',
+            path: filePath,
+        });
+    }
+    else if (!hasTaskEntries) {
+        issues.push({
+            severity: 'warning',
+            message: '"## Tasks" section has no task entries (H3 headings)',
+            rule: 'required-sections',
+            path: filePath,
+            lineNumber: tasksLineNumber,
+        });
+    }
+}
+/**
+ * Validate module links in an index file
+ */
+async function validateModuleLinks(content, filePath, baseDir, issues) {
+    const processor = unified().use(remarkParse);
+    const ast = processor.parse(content);
+    let inModulesSection = false;
+    let currentModuleId = null;
+    visit(ast, (node) => {
+        if (node.type === 'heading') {
+            const heading = node;
+            if (heading.depth === 2) {
+                let text = '';
+                visit(heading, 'text', (textNode) => {
+                    text += textNode.value;
+                });
+                const normalizedText = text.trim().toLowerCase();
+                inModulesSection = normalizedText === 'modules' || normalizedText.startsWith('modules');
+            }
+            if (heading.depth === 3 && inModulesSection) {
+                let text = '';
+                visit(heading, 'text', (textNode) => {
+                    text += textNode.value;
+                });
+                currentModuleId = text.trim();
+            }
+        }
+        // Check for Path links in list items
+        if (node.type === 'paragraph' && inModulesSection && currentModuleId) {
+            const para = node;
+            let hasPathField = false;
+            let linkUrl = null;
+            const linkLine = para.position?.start.line ?? 0;
+            for (const child of para.children) {
+                if (child.type === 'strong') {
+                    let strongText = '';
+                    visit(child, 'text', (textNode) => {
+                        strongText += textNode.value;
+                    });
+                    if (strongText === 'Path:') {
+                        hasPathField = true;
+                    }
+                }
+                if (child.type === 'link' && hasPathField) {
+                    linkUrl = child.url;
+                }
+            }
+            if (hasPathField && linkUrl) {
+                // Validate the link exists
+                const resolvedPath = resolvePath(linkUrl, baseDir);
+                validateFileExists(resolvedPath, filePath, linkLine, currentModuleId, issues);
+            }
+        }
+    });
+}
+/**
+ * Validate that a file exists (async check queued for later)
+ */
+function validateFileExists(targetPath, sourcePath, lineNumber, moduleId, issues) {
+    // Use sync check for simplicity (file system is fast for existence checks)
+    try {
+        accessSync(targetPath);
+    }
+    catch {
+        issues.push({
+            severity: 'error',
+            message: `Broken link: module "${moduleId}" links to non-existent file "${targetPath}"`,
+            rule: 'broken-links',
+            path: sourcePath,
+            lineNumber,
+            context: `Module: ${moduleId}`,
+        });
+    }
+}
+/**
+ * Validate task format in a leaf spec
+ */
+function validateTaskFormat(content, filePath, issues, skipRules) {
+    const processor = unified().use(remarkParse);
+    const ast = processor.parse(content);
+    let inTasksSection = false;
+    let currentTaskHeading = null;
+    let currentTaskContent = [];
+    visit(ast, (node) => {
+        if (node.type === 'heading') {
+            const heading = node;
+            if (heading.depth === 2) {
+                // Check for section change
+                if (currentTaskHeading) {
+                    validateTaskContent(currentTaskHeading, currentTaskContent, filePath, issues, skipRules);
+                    currentTaskHeading = null;
+                    currentTaskContent = [];
+                }
+                let text = '';
+                visit(heading, 'text', (textNode) => {
+                    text += textNode.value;
+                });
+                inTasksSection = text.trim().toLowerCase() === 'tasks';
+            }
+            if (heading.depth === 3 && inTasksSection) {
+                // Save previous task
+                if (currentTaskHeading) {
+                    validateTaskContent(currentTaskHeading, currentTaskContent, filePath, issues, skipRules);
+                }
+                // Parse task heading
+                let text = '';
+                visit(heading, 'text', (textNode) => {
+                    text += textNode.value;
+                });
+                const lineNumber = heading.position?.start.line ?? 0;
+                const match = text.match(/^([A-Z0-9]+-\d+):\s*(.*)$/);
+                if (!match) {
+                    issues.push({
+                        severity: 'error',
+                        message: `Invalid task heading format: "${text}". Expected "ID: Title" (e.g., "AUTH-001: Implement login")`,
+                        rule: 'task-format',
+                        path: filePath,
+                        lineNumber,
+                    });
+                    currentTaskHeading = null;
+                }
+                else {
+                    const [, id, title] = match;
+                    // Validate task ID format
+                    if (!TASK_ID_REGEX.test(id)) {
+                        issues.push({
+                            severity: 'error',
+                            message: `Invalid task ID format: "${id}". Expected 1-10 alphanumeric scope + hyphen + 3-digit number (e.g., AUTH-001)`,
+                            rule: 'task-format',
+                            path: filePath,
+                            lineNumber,
+                        });
+                    }
+                    currentTaskHeading = { id, title, line: lineNumber };
+                    currentTaskContent = [];
+                }
+            }
+        }
+        // Collect task content
+        if (currentTaskHeading && node.type === 'paragraph') {
+            let text = '';
+            visit(node, 'text', (textNode) => {
+                text += textNode.value;
+            });
+            visit(node, 'strong', (strongNode) => {
+                visit(strongNode, 'text', (textNode) => {
+                    text += textNode.value;
+                });
+            });
+            currentTaskContent.push(text);
+        }
+    });
+    // Validate last task
+    if (currentTaskHeading) {
+        validateTaskContent(currentTaskHeading, currentTaskContent, filePath, issues, skipRules);
+    }
+}
+/**
+ * Validate task content (Intent required, Confidence/Validation/ExpectedOutcome warnings)
+ */
+function validateTaskContent(task, content, filePath, issues, skipRules) {
+    const fullContent = content.join(' ');
+    // Check for Intent (required)
+    if (!skipRules.has('task-intent') && !fullContent.includes('Intent:')) {
+        issues.push({
+            severity: 'error',
+            message: `Task "${task.id}" is missing required **Intent:** field`,
+            rule: 'task-intent',
+            path: filePath,
+            lineNumber: task.line,
+        });
+    }
+    // Check for Expected Outcome (warning per APS spec)
+    if (!skipRules.has('missing-expected-outcome') &&
+        !fullContent.includes('Expected Outcome:') &&
+        !fullContent.includes('ExpectedOutcome:')) {
+        issues.push({
+            severity: 'warning',
+            message: `Task "${task.id}" is missing **Expected Outcome:** field (recommended for testability)`,
+            rule: 'missing-expected-outcome',
+            path: filePath,
+            lineNumber: task.line,
+        });
+    }
+    // Check for Validation/Test (warning per APS spec)
+    if (!skipRules.has('missing-validation') &&
+        !fullContent.includes('Validation:') &&
+        !fullContent.includes('Test:')) {
+        issues.push({
+            severity: 'warning',
+            message: `Task "${task.id}" is missing **Validation:** or **Test:** field (recommended for verification)`,
+            rule: 'missing-validation',
+            path: filePath,
+            lineNumber: task.line,
+        });
+    }
+    // Check for Confidence (warning)
+    if (!skipRules.has('missing-confidence') && !fullContent.includes('Confidence:')) {
+        issues.push({
+            severity: 'warning',
+            message: `Task "${task.id}" is missing **Confidence:** field (defaults to "medium")`,
+            rule: 'missing-confidence',
+            path: filePath,
+            lineNumber: task.line,
+        });
+    }
+}
+/**
+ * Validate duplicate task IDs across the plan
+ */
+function validateDuplicateTaskIds(plan, issues) {
+    const taskLocations = new Map();
+    for (const task of plan.allTasks) {
+        const locations = taskLocations.get(task.id) ?? [];
+        locations.push({
+            path: task.sourcePath ?? 'unknown',
+            line: task.sourceLineNumber,
+        });
+        taskLocations.set(task.id, locations);
+    }
+    for (const [taskId, locations] of taskLocations) {
+        if (locations.length > 1) {
+            const locationStrings = locations
+                .map((loc) => `${loc.path}${loc.line ? `:${loc.line}` : ''}`)
+                .join(', ');
+            issues.push({
+                severity: 'error',
+                message: `Duplicate task ID "${taskId}" found in: ${locationStrings}`,
+                rule: 'duplicate-ids',
+                path: locations[0].path,
+                lineNumber: locations[0].line,
+                context: `Also found at: ${locations
+                    .slice(1)
+                    .map((l) => `${l.path}:${l.line}`)
+                    .join(', ')}`,
+            });
+        }
+    }
+}
+/**
+ * Validate circular module dependencies
+ */
+function validateCircularDependencies(plan, issues) {
+    const cycles = detectCycles(plan);
+    for (const cycle of cycles) {
+        const cycleStr = cycle.join(' -> ');
+        issues.push({
+            severity: 'error',
+            message: `Circular dependency detected: ${cycleStr}`,
+            rule: 'circular-dependencies',
+            path: plan.rootPath,
+            context: `Cycle: ${cycleStr}`,
+        });
+    }
+}
+/**
+ * Validate scope mismatches (task ID prefix vs module scope)
+ */
+function validateScopeMismatches(plan, issues) {
+    for (const module of plan.modules.values()) {
+        const moduleScope = module.metadata.scope?.toUpperCase();
+        for (const task of module.tasks) {
+            const taskScope = task.id.split('-')[0];
+            if (moduleScope && taskScope !== moduleScope) {
+                issues.push({
+                    severity: 'warning',
+                    message: `Task "${task.id}" has scope prefix "${taskScope}" but belongs to module with scope "${moduleScope}"`,
+                    rule: 'scope-mismatch',
+                    path: task.sourcePath,
+                    lineNumber: task.sourceLineNumber,
+                    context: `Module scope: ${moduleScope}`,
+                });
+            }
+        }
+    }
+}
+/**
+ * Validate for orphan modules (leaf specs in directory not linked from index)
+ */
+async function validateOrphanModules(indexPath, baseDir, plan, issues) {
+    // Get all linked module paths
+    const linkedPaths = new Set();
+    for (const module of plan.modules.values()) {
+        linkedPaths.add(module.resolvedPath);
+    }
+    // Scan the directory for .aps.md files
+    try {
+        const { readdir, stat } = await import('node:fs/promises');
+        const { join } = await import('node:path');
+        async function scanDir(dir) {
+            const files = [];
+            try {
+                const entries = await readdir(dir);
+                for (const entry of entries) {
+                    const fullPath = join(dir, entry);
+                    const stats = await stat(fullPath);
+                    if (stats.isDirectory()) {
+                        files.push(...(await scanDir(fullPath)));
+                    }
+                    else if (entry.endsWith('.aps.md') && fullPath !== indexPath) {
+                        files.push(fullPath);
+                    }
+                }
+            }
+            catch {
+                // Ignore errors (permission denied, etc.)
+            }
+            return files;
+        }
+        const allApsFiles = await scanDir(baseDir);
+        for (const file of allApsFiles) {
+            if (!linkedPaths.has(file)) {
+                issues.push({
+                    severity: 'warning',
+                    message: `Orphan leaf spec found: "${file}" is not linked from the index file`,
+                    rule: 'orphan-modules',
+                    path: file,
+                });
+            }
+        }
+    }
+    catch {
+        // Ignore directory scanning errors
+    }
+}
+/**
+ * Create a ValidationResult from issues
+ */
+function createResult(issues) {
+    const errors = issues.filter((i) => i.severity === 'error');
+    const warnings = issues.filter((i) => i.severity === 'warning');
+    return {
+        valid: errors.length === 0,
+        issues,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Format validation issues for display
+ */
+export function formatValidationIssues(result) {
+    if (result.issues.length === 0) {
+        return 'No issues found.';
+    }
+    const lines = [];
+    for (const issue of result.issues) {
+        const severity = issue.severity === 'error' ? 'ERROR' : 'WARN';
+        const location = issue.path
+            ? issue.lineNumber
+                ? `${issue.path}:${issue.lineNumber}`
+                : issue.path
+            : '';
+        const prefix = location ? `${location}: ` : '';
+        lines.push(`[${severity}] ${prefix}${issue.message}`);
+        if (issue.context) {
+            lines.push(`         ${issue.context}`);
+        }
+    }
+    const summary = `\n${result.errors.length} error(s), ${result.warnings.length} warning(s)`;
+    lines.push(summary);
+    return lines.join('\n');
+}