specweave 0.32.0 → 0.32.2

package/dist/src/utils/docs-validator.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Documentation Pre-Render Validator
+ *
+ * Validates markdown/MDX files BEFORE Docusaurus server starts.
+ * Catches issues proactively so users don't see cryptic webpack errors.
+ *
+ * Validates:
+ * 1. YAML frontmatter syntax
+ * 2. MDX/JSX compatibility (unquoted attrs, self-closing tags)
+ * 3. Broken internal links
+ * 4. Duplicate files/routes
+ * 5. Invalid file names
+ *
+ * @module utils/docs-validator
+ */
+import { Logger } from './logger.js';
+/**
+ * Issue severity levels
+ */
+export type IssueSeverity = 'error' | 'warning' | 'info';
+/**
+ * Single validation issue
+ */
+export interface ValidationIssue {
+    file: string;
+    line?: number;
+    severity: IssueSeverity;
+    type: string;
+    message: string;
+    autoFixable: boolean;
+    fix?: () => void;
+}
+/**
+ * Validation result summary
+ */
+export interface ValidationResult {
+    valid: boolean;
+    totalFiles: number;
+    errors: number;
+    warnings: number;
+    infos: number;
+    issues: ValidationIssue[];
+    fixedCount: number;
+}
+/**
+ * Validator options
+ */
+export interface DocsValidatorOptions {
+    docsPath: string;
+    autoFix?: boolean;
+    logger?: Logger;
+    /** File extensions to validate */
+    extensions?: string[];
+    /** Paths to ignore (relative to docsPath) */
+    ignorePaths?: string[];
+}
+/**
+ * Documentation Pre-Render Validator
+ *
+ * Use before starting Docusaurus to catch issues early.
+ *
+ * @example
+ * ```typescript
+ * const validator = new DocsValidator({
+ *   docsPath: '.specweave/docs/internal',
+ *   autoFix: true
+ * });
+ * const result = await validator.validate();
+ * if (!result.valid) {
+ *   console.log('Fix issues before starting docs server');
+ * }
+ * ```
+ */
+export declare class DocsValidator {
+    private docsPath;
+    private autoFix;
+    private logger;
+    private extensions;
+    private ignorePaths;
+    private issues;
+    private fixedCount;
+    constructor(options: DocsValidatorOptions);
+    /**
+     * Run all validations
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * Collect all markdown files recursively
+     */
+    private collectFiles;
+    /**
+     * Validate a single file
+     */
+    private validateFile;
+    /**
+     * Validate YAML frontmatter syntax
+     */
+    private validateFrontmatter;
+    /**
+     * Validate MDX/JSX compatibility
+     */
+    private validateMdxContent;
+    /**
+     * Check for duplicate routes (same normalized path)
+     */
+    private checkDuplicateRoutes;
+    /**
+     * Validate file naming conventions
+     */
+    private validateFileName;
+    /**
+     * Validate internal links between documents
+     */
+    private validateInternalLinks;
+    /**
+     * Build the validation result
+     */
+    private buildResult;
+    /**
+     * Format validation result for display
+     */
+    static formatResult(result: ValidationResult): string;
+}
+/**
+ * Quick validation function for scripts
+ */
+export declare function validateDocs(docsPath: string, options?: {
+    autoFix?: boolean;
+    logger?: Logger;
+}): Promise<ValidationResult>;
+//# sourceMappingURL=docs-validator.d.ts.map

package/dist/src/utils/docs-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-validator.d.ts","sourceRoot":"","sources":["../../../src/utils/docs-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAC;AAGpD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAW;IAC7B,OAAO,CAAC,WAAW,CAAW;IAC9B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,UAAU,CAAK;gBAEX,OAAO,EAAE,oBAAoB;IAQzC;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAkC3C;;OAEG;IACH,OAAO,CAAC,YAAY;IAuBpB;;OAEG;YACW,YAAY;IAiC1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAwE3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA2D1B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAqCxB;;OAEG;YACW,qBAAqB;IAmGnC;;OAEG;IACH,OAAO,CAAC,WAAW;IA8BnB;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM;CA6GtD;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,OAAO,CAAC,gBAAgB,CAAC,CAO3B"}

package/dist/src/utils/docs-validator.js

@@ -0,0 +1,529 @@
+/**
+ * Documentation Pre-Render Validator
+ *
+ * Validates markdown/MDX files BEFORE Docusaurus server starts.
+ * Catches issues proactively so users don't see cryptic webpack errors.
+ *
+ * Validates:
+ * 1. YAML frontmatter syntax
+ * 2. MDX/JSX compatibility (unquoted attrs, self-closing tags)
+ * 3. Broken internal links
+ * 4. Duplicate files/routes
+ * 5. Invalid file names
+ *
+ * @module utils/docs-validator
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { consoleLogger } from './logger.js';
+import { sanitizeHtmlForMdx, validateMdxCompatibility } from './html-to-mdx.js';
+/**
+ * Documentation Pre-Render Validator
+ *
+ * Use before starting Docusaurus to catch issues early.
+ *
+ * @example
+ * ```typescript
+ * const validator = new DocsValidator({
+ *   docsPath: '.specweave/docs/internal',
+ *   autoFix: true
+ * });
+ * const result = await validator.validate();
+ * if (!result.valid) {
+ *   console.log('Fix issues before starting docs server');
+ * }
+ * ```
+ */
+export class DocsValidator {
+    constructor(options) {
+        this.issues = [];
+        this.fixedCount = 0;
+        this.docsPath = path.resolve(options.docsPath);
+        this.autoFix = options.autoFix ?? false;
+        this.logger = options.logger ?? consoleLogger;
+        this.extensions = options.extensions ?? ['.md', '.mdx'];
+        this.ignorePaths = options.ignorePaths ?? ['node_modules', '.git', '_archive'];
+    }
+    /**
+     * Run all validations
+     */
+    async validate() {
+        this.issues = [];
+        this.fixedCount = 0;
+        // Check docs path exists
+        if (!fs.existsSync(this.docsPath)) {
+            this.issues.push({
+                file: this.docsPath,
+                severity: 'error',
+                type: 'missing_docs_path',
+                message: `Documentation path does not exist: ${this.docsPath}`,
+                autoFixable: false,
+            });
+            return this.buildResult();
+        }
+        // Collect all markdown files
+        const files = this.collectFiles(this.docsPath);
+        this.logger.info(`Validating ${files.length} documentation files...`);
+        // Track seen routes for duplicate detection
+        const seenRoutes = new Map();
+        // Validate each file
+        for (const file of files) {
+            await this.validateFile(file, seenRoutes);
+        }
+        // Check for broken internal links
+        await this.validateInternalLinks(files);
+        return this.buildResult();
+    }
+    /**
+     * Collect all markdown files recursively
+     */
+    collectFiles(dir) {
+        const files = [];
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const relativePath = path.relative(this.docsPath, fullPath);
+            // Skip ignored paths
+            if (this.ignorePaths.some((p) => relativePath.startsWith(p) || entry.name === p)) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                files.push(...this.collectFiles(fullPath));
+            }
+            else if (this.extensions.some((ext) => entry.name.endsWith(ext))) {
+                files.push(fullPath);
+            }
+        }
+        return files;
+    }
+    /**
+     * Validate a single file
+     */
+    async validateFile(filePath, seenRoutes) {
+        const relativePath = path.relative(this.docsPath, filePath);
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        }
+        catch (err) {
+            this.issues.push({
+                file: relativePath,
+                severity: 'error',
+                type: 'read_error',
+                message: `Cannot read file: ${err.message}`,
+                autoFixable: false,
+            });
+            return;
+        }
+        // 1. Validate YAML frontmatter
+        this.validateFrontmatter(relativePath, content, filePath);
+        // 2. Validate MDX compatibility
+        this.validateMdxContent(relativePath, content, filePath);
+        // 3. Check for duplicate routes
+        this.checkDuplicateRoutes(relativePath, seenRoutes);
+        // 4. Validate file naming
+        this.validateFileName(relativePath);
+    }
+    /**
+     * Validate YAML frontmatter syntax
+     */
+    validateFrontmatter(relativePath, content, filePath) {
+        // Check if file has frontmatter
+        if (!content.startsWith('---')) {
+            // No frontmatter is OK for some files
+            return;
+        }
+        // Find closing ---
+        const endMatch = content.indexOf('\n---', 3);
+        if (endMatch === -1) {
+            this.issues.push({
+                file: relativePath,
+                severity: 'error',
+                type: 'invalid_frontmatter',
+                message: 'YAML frontmatter not closed (missing closing ---)',
+                autoFixable: false,
+            });
+            return;
+        }
+        const frontmatter = content.substring(4, endMatch);
+        // Check for common YAML issues
+        const lines = frontmatter.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const lineNum = i + 2; // +2 for opening --- and 0-index
+            // Check for unquoted colons in values (common issue)
+            // e.g., title: Feature: Something → should be title: "Feature: Something"
+            const colonMatch = line.match(/^(\s*)([a-zA-Z_-]+):\s*([^"'\n]*:[^"'\n]*)$/);
+            if (colonMatch && !line.includes('#')) {
+                const [, indent, key, value] = colonMatch;
+                this.issues.push({
+                    file: relativePath,
+                    line: lineNum,
+                    severity: 'error',
+                    type: 'yaml_unquoted_colon',
+                    message: `Unquoted colon in YAML value: ${key}: ${value.trim()} (wrap in quotes)`,
+                    autoFixable: true,
+                    fix: () => {
+                        const fixedLine = `${indent}${key}: "${value.trim()}"`;
+                        const newContent = content.replace(line, fixedLine);
+                        fs.writeFileSync(filePath, newContent);
+                        this.fixedCount++;
+                    },
+                });
+            }
+            // Check for tabs (YAML doesn't allow tabs for indentation)
+            if (line.includes('\t')) {
+                this.issues.push({
+                    file: relativePath,
+                    line: lineNum,
+                    severity: 'error',
+                    type: 'yaml_tabs',
+                    message: 'YAML frontmatter contains tabs (use spaces)',
+                    autoFixable: true,
+                    fix: () => {
+                        const newContent = content.replace(/\t/g, '  ');
+                        fs.writeFileSync(filePath, newContent);
+                        this.fixedCount++;
+                    },
+                });
+            }
+        }
+    }
+    /**
+     * Validate MDX/JSX compatibility
+     */
+    validateMdxContent(relativePath, content, filePath) {
+        const mdxIssues = validateMdxCompatibility(content);
+        for (const issue of mdxIssues) {
+            this.issues.push({
+                file: relativePath,
+                severity: 'error',
+                type: 'mdx_compatibility',
+                message: issue,
+                autoFixable: true,
+                fix: () => {
+                    const fixedContent = sanitizeHtmlForMdx(content);
+                    fs.writeFileSync(filePath, fixedContent);
+                    this.fixedCount++;
+                },
+            });
+        }
+        // Check for JSX-in-markdown issues
+        // Curly braces without escape can break MDX
+        const curlyBraceMatch = content.match(/(?<!\\)\{[^}]*\}/g);
+        if (curlyBraceMatch) {
+            for (const match of curlyBraceMatch) {
+                // Skip valid code blocks and inline code
+                if (content.includes('```') || content.includes('`' + match + '`')) {
+                    continue;
+                }
+                // Check if it's a valid JSX expression or needs escaping
+                if (!match.match(/^\{[a-zA-Z_$][a-zA-Z0-9_$]*\}$/)) {
+                    // Not a simple variable reference, might cause issues
+                    // Only warn, don't error - some valid cases
+                }
+            }
+        }
+        // Check for common problematic patterns
+        const problematicPatterns = [
+            { pattern: /<script/i, message: 'Script tags not allowed in MDX' },
+            { pattern: /<style(?!\s)/i, message: 'Style tags may cause issues (use CSS modules)' },
+            { pattern: /<!--(?!.*-->)/s, message: 'Unclosed HTML comment' },
+        ];
+        for (const { pattern, message } of problematicPatterns) {
+            if (pattern.test(content)) {
+                this.issues.push({
+                    file: relativePath,
+                    severity: 'warning',
+                    type: 'mdx_problematic_content',
+                    message,
+                    autoFixable: false,
+                });
+            }
+        }
+    }
+    /**
+     * Check for duplicate routes (same normalized path)
+     */
+    checkDuplicateRoutes(relativePath, seenRoutes) {
+        // Normalize route: remove extension, lowercase, normalize separators
+        const route = relativePath
+            .replace(/\.(md|mdx)$/, '')
+            .toLowerCase()
+            .replace(/\\/g, '/');
+        if (seenRoutes.has(route)) {
+            this.issues.push({
+                file: relativePath,
+                severity: 'error',
+                type: 'duplicate_route',
+                message: `Duplicate route: conflicts with ${seenRoutes.get(route)}`,
+                autoFixable: false,
+            });
+        }
+        else {
+            seenRoutes.set(route, relativePath);
+        }
+    }
+    /**
+     * Validate file naming conventions
+     */
+    validateFileName(relativePath) {
+        const fileName = path.basename(relativePath);
+        // Check for spaces in filename
+        if (fileName.includes(' ')) {
+            this.issues.push({
+                file: relativePath,
+                severity: 'warning',
+                type: 'filename_spaces',
+                message: 'Filename contains spaces (may cause URL issues)',
+                autoFixable: false,
+            });
+        }
+        // Check for special characters
+        if (/[<>:"|?*]/.test(fileName)) {
+            this.issues.push({
+                file: relativePath,
+                severity: 'error',
+                type: 'filename_invalid_chars',
+                message: 'Filename contains invalid characters',
+                autoFixable: false,
+            });
+        }
+        // Check for very long filenames
+        if (fileName.length > 100) {
+            this.issues.push({
+                file: relativePath,
+                severity: 'warning',
+                type: 'filename_too_long',
+                message: `Filename too long (${fileName.length} chars, max recommended: 100)`,
+                autoFixable: false,
+            });
+        }
+    }
+    /**
+     * Validate internal links between documents
+     */
+    async validateInternalLinks(files) {
+        const fileSet = new Set(files.map((f) => path.relative(this.docsPath, f).replace(/\\/g, '/')));
+        for (const file of files) {
+            const relativePath = path.relative(this.docsPath, file).replace(/\\/g, '/');
+            let content;
+            try {
+                content = fs.readFileSync(file, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            // Find markdown links: [text](path)
+            const linkRegex = /\[([^\]]*)\]\(([^)]+)\)/g;
+            let match;
+            while ((match = linkRegex.exec(content)) !== null) {
+                const [, , linkPath] = match;
+                // Skip external links
+                if (linkPath.startsWith('http://') || linkPath.startsWith('https://')) {
+                    continue;
+                }
+                // Skip anchors
+                if (linkPath.startsWith('#')) {
+                    continue;
+                }
+                // Skip mailto and tel
+                if (linkPath.startsWith('mailto:') || linkPath.startsWith('tel:')) {
+                    continue;
+                }
+                // Resolve relative path
+                const linkPathClean = linkPath.split('#')[0].split('?')[0];
+                if (!linkPathClean)
+                    continue;
+                const fileDir = path.dirname(relativePath);
+                let resolvedPath;
+                if (linkPathClean.startsWith('/')) {
+                    resolvedPath = linkPathClean.substring(1);
+                }
+                else if (linkPathClean.startsWith('./')) {
+                    resolvedPath = path.join(fileDir, linkPathClean.substring(2));
+                }
+                else if (linkPathClean.startsWith('../')) {
+                    resolvedPath = path.join(fileDir, linkPathClean);
+                }
+                else {
+                    resolvedPath = path.join(fileDir, linkPathClean);
+                }
+                // Normalize
+                resolvedPath = resolvedPath.replace(/\\/g, '/');
+                // Check if link points to existing file
+                const possiblePaths = [
+                    resolvedPath,
+                    resolvedPath + '.md',
+                    resolvedPath + '.mdx',
+                    resolvedPath + '/index.md',
+                    resolvedPath + '/README.md',
+                ];
+                const exists = possiblePaths.some((p) => fileSet.has(p) || fileSet.has(p.replace(/\\/g, '/')));
+                // Check if it's an external file (outside docs)
+                const fullResolvedPath = path.resolve(this.docsPath, resolvedPath);
+                const externalExists = fs.existsSync(fullResolvedPath) ||
+                    fs.existsSync(fullResolvedPath + '.md');
+                if (!exists && !externalExists) {
+                    // Broken links are warnings, not errors - Docusaurus is configured with
+                    // onBrokenLinks: 'warn' and won't crash, just show console warnings
+                    // Check if it might be pointing outside docs intentionally
+                    const isOutsideDocsRef = linkPathClean.includes('CLAUDE.md') ||
+                        linkPathClean.includes('README.md') ||
+                        linkPathClean.includes('increments/') ||
+                        linkPathClean.includes('_archive/') ||
+                        linkPathClean.includes('_features/') ||
+                        linkPathClean.includes('plugins/') ||
+                        linkPathClean.includes('src/');
+                    this.issues.push({
+                        file: relativePath,
+                        severity: 'warning', // Always warning - Docusaurus won't crash on broken links
+                        type: 'broken_link',
+                        message: `Broken link: ${linkPath}${isOutsideDocsRef ? ' (external reference)' : ''}`,
+                        autoFixable: false,
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Build the validation result
+     */
+    buildResult() {
+        // Apply auto-fixes if enabled
+        if (this.autoFix) {
+            for (const issue of this.issues) {
+                if (issue.autoFixable && issue.fix) {
+                    try {
+                        issue.fix();
+                        this.logger.info(`✓ Fixed: ${issue.file} - ${issue.message}`);
+                    }
+                    catch (err) {
+                        this.logger.warn(`Failed to fix ${issue.file}: ${err.message}`);
+                    }
+                }
+            }
+        }
+        const errors = this.issues.filter((i) => i.severity === 'error').length;
+        const warnings = this.issues.filter((i) => i.severity === 'warning').length;
+        const infos = this.issues.filter((i) => i.severity === 'info').length;
+        return {
+            valid: errors === 0,
+            totalFiles: this.issues.length > 0 ? this.issues.length : 0,
+            errors,
+            warnings,
+            infos,
+            issues: this.issues,
+            fixedCount: this.fixedCount,
+        };
+    }
+    /**
+     * Format validation result for display
+     */
+    static formatResult(result) {
+        const lines = [];
+        lines.push('');
+        lines.push('═══════════════════════════════════════════════════════════════');
+        lines.push('               DOCUMENTATION VALIDATION REPORT                  ');
+        lines.push('═══════════════════════════════════════════════════════════════');
+        lines.push('');
+        if (result.valid) {
+            lines.push('✅ Documentation is valid and ready for preview/build');
+        }
+        else {
+            lines.push('❌ Documentation has issues that need to be fixed');
+        }
+        lines.push('');
+        lines.push(`   Errors:   ${result.errors}`);
+        lines.push(`   Warnings: ${result.warnings}`);
+        lines.push(`   Info:     ${result.infos}`);
+        if (result.fixedCount > 0) {
+            lines.push(`   Fixed:    ${result.fixedCount} (auto-fix applied)`);
+        }
+        lines.push('');
+        // Group issues by file
+        const issuesByFile = new Map();
+        for (const issue of result.issues) {
+            const existing = issuesByFile.get(issue.file) ?? [];
+            existing.push(issue);
+            issuesByFile.set(issue.file, existing);
+        }
+        // Show errors first
+        const errorFiles = Array.from(issuesByFile.entries())
+            .filter(([, issues]) => issues.some((i) => i.severity === 'error'));
+        if (errorFiles.length > 0) {
+            lines.push('ERRORS (must fix):');
+            lines.push('───────────────────────────────────────────────────────────────');
+            for (const [file, issues] of errorFiles) {
+                const errors = issues.filter((i) => i.severity === 'error');
+                lines.push(`  📄 ${file}`);
+                for (const issue of errors) {
+                    const line = issue.line ? `:${issue.line}` : '';
+                    const fix = issue.autoFixable ? ' [auto-fixable]' : '';
+                    lines.push(`     ❌ ${issue.type}${line}: ${issue.message}${fix}`);
+                }
+            }
+            lines.push('');
+        }
+        // Show warnings
+        const warningFiles = Array.from(issuesByFile.entries())
+            .filter(([, issues]) => issues.some((i) => i.severity === 'warning'));
+        if (warningFiles.length > 0 && warningFiles.length <= 10) {
+            lines.push('WARNINGS (recommended to fix):');
+            lines.push('───────────────────────────────────────────────────────────────');
+            for (const [file, issues] of warningFiles) {
+                const warnings = issues.filter((i) => i.severity === 'warning');
+                lines.push(`  📄 ${file}`);
+                for (const issue of warnings) {
+                    lines.push(`     ⚠️  ${issue.message}`);
+                }
+            }
+            lines.push('');
+        }
+        else if (warningFiles.length > 10) {
+            lines.push(`WARNINGS: ${result.warnings} (showing summary only)`);
+            lines.push('───────────────────────────────────────────────────────────────');
+            lines.push(`  Run with --verbose to see all warnings`);
+            lines.push('');
+        }
+        // Suggestions
+        if (!result.valid) {
+            lines.push('QUICK FIXES:');
+            lines.push('───────────────────────────────────────────────────────────────');
+            lines.push('  1. Run validation with auto-fix:');
+            lines.push('     /specweave-docs:validate --fix');
+            lines.push('');
+            lines.push('  2. Or fix manually:');
+            const hasYamlIssues = result.issues.some((i) => i.type.startsWith('yaml_'));
+            const hasMdxIssues = result.issues.some((i) => i.type.startsWith('mdx_'));
+            const hasBrokenLinks = result.issues.some((i) => i.type === 'broken_link');
+            if (hasYamlIssues) {
+                lines.push('     • YAML: Wrap values with colons in quotes');
+                lines.push('       title: "Feature: Auth" (not title: Feature: Auth)');
+            }
+            if (hasMdxIssues) {
+                lines.push('     • MDX: Quote HTML attributes, close self-closing tags');
+                lines.push('       target="_blank" (not target=_blank)');
+                lines.push('       <br /> (not <br>)');
+            }
+            if (hasBrokenLinks) {
+                lines.push('     • Links: Update or remove broken internal links');
+            }
+            lines.push('');
+        }
+        lines.push('═══════════════════════════════════════════════════════════════');
+        return lines.join('\n');
+    }
+}
+/**
+ * Quick validation function for scripts
+ */
+export async function validateDocs(docsPath, options) {
+    const validator = new DocsValidator({
+        docsPath,
+        autoFix: options?.autoFix,
+        logger: options?.logger,
+    });
+    return validator.validate();
+}
+//# sourceMappingURL=docs-validator.js.map