specweave 0.32.0 → 0.32.2

package/plugins/specweave-ado/lib/enhanced-ado-sync.js

@@ -0,0 +1,170 @@
+import { AdoClientV2 } from "./ado-client-v2.js";
+import { EnhancedContentBuilder } from "../../../src/core/sync/enhanced-content-builder.js";
+import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
+import { parseSpecContent } from "../../../src/core/spec-content-sync.js";
+import path from "path";
+import fs from "fs/promises";
+async function syncSpecToAdoWithEnhancedContent(options) {
+  const { specPath, organization, project, dryRun = false, verbose = false } = options;
+  try {
+    const baseSpec = await parseSpecContent(specPath);
+    if (!baseSpec) {
+      return {
+        success: false,
+        action: "error",
+        error: "Failed to parse spec content"
+      };
+    }
+    if (verbose) {
+      console.log(`\u{1F4C4} Parsed spec: ${baseSpec.identifier.compact}`);
+    }
+    const specId = baseSpec.identifier.full || baseSpec.identifier.compact;
+    const rootDir = await findSpecWeaveRoot(specPath);
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+    if (verbose) {
+      console.log(`\u{1F517} Found ${mapping.increments.length} related increments`);
+    }
+    const taskMapping = buildTaskMapping(mapping.increments, organization, project);
+    const architectureDocs = await findArchitectureDocs(rootDir, specId);
+    const enhancedSpec = {
+      ...baseSpec,
+      summary: baseSpec.description,
+      taskMapping,
+      architectureDocs
+    };
+    const builder = new EnhancedContentBuilder();
+    const description = builder.buildExternalDescription(enhancedSpec);
+    if (verbose) {
+      console.log(`\u{1F4DD} Generated description: ${description.length} characters`);
+    }
+    if (dryRun) {
+      console.log("\u{1F50D} DRY RUN - Would create/update feature with:");
+      console.log(`   Title: ${baseSpec.title}`);
+      console.log(`   Description length: ${description.length}`);
+      return {
+        success: true,
+        action: "no-change",
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+    if (!organization || !project) {
+      return {
+        success: false,
+        action: "error",
+        error: "Azure DevOps organization/project not specified"
+      };
+    }
+    const profile = {
+      provider: "ado",
+      displayName: `${organization}/${project}`,
+      config: {
+        organization,
+        project
+      },
+      timeRange: { default: "1M", max: "6M" }
+    };
+    const pat = process.env.AZURE_DEVOPS_PAT || "";
+    const client = new AdoClientV2(profile, pat);
+    const existingFeature = await findExistingFeature(client, baseSpec.identifier.compact);
+    let result;
+    if (existingFeature) {
+      await client.updateWorkItem(existingFeature.id, {
+        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        description
+      });
+      result = {
+        success: true,
+        action: "updated",
+        featureId: existingFeature.id,
+        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${existingFeature.id}`,
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    } else {
+      const feature = await client.createEpic({
+        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        description,
+        tags: ["spec", "external-tool-sync"]
+      });
+      result = {
+        success: true,
+        action: "created",
+        featureId: feature.id,
+        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${feature.id}`,
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+    if (verbose) {
+      console.log(`\u2705 ${result.action === "created" ? "Created" : "Updated"} feature #${result.featureId}`);
+    }
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      action: "error",
+      error: error.message
+    };
+  }
+}
+async function findSpecWeaveRoot(specPath) {
+  let currentDir = path.dirname(specPath);
+  while (true) {
+    const specweaveDir = path.join(currentDir, ".specweave");
+    try {
+      await fs.access(specweaveDir);
+      return currentDir;
+    } catch {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        throw new Error(".specweave directory not found");
+      }
+      currentDir = parentDir;
+    }
+  }
+}
+function buildTaskMapping(increments, organization, project) {
+  if (increments.length === 0) return void 0;
+  const firstIncrement = increments[0];
+  const tasks = firstIncrement.tasks.map((task) => ({
+    id: task.id,
+    title: task.title,
+    userStories: task.userStories
+  }));
+  return {
+    incrementId: firstIncrement.id,
+    tasks,
+    tasksUrl: `https://dev.azure.com/${organization}/${project}/_git/repo?path=/.specweave/increments/${firstIncrement.id}/tasks.md`
+  };
+}
+async function findArchitectureDocs(rootDir, specId) {
+  const docs = [];
+  const archDir = path.join(rootDir, ".specweave/docs/internal/architecture");
+  try {
+    const adrDir = path.join(archDir, "adr");
+    try {
+      const adrs = await fs.readdir(adrDir);
+      const relatedAdrs = adrs.filter((file) => file.includes(specId.replace("spec-", "")));
+      for (const adr of relatedAdrs) {
+        docs.push({
+          type: "adr",
+          path: path.join(adrDir, adr),
+          title: adr.replace(".md", "").replace(/-/g, " ")
+        });
+      }
+    } catch {
+    }
+  } catch {
+  }
+  return docs;
+}
+async function findExistingFeature(client, specId) {
+  try {
+    const features = await client.queryWorkItems(`[System.Title] Contains '[${specId}]' AND [System.WorkItemType] = 'Feature'`);
+    return features[0] || null;
+  } catch {
+    return null;
+  }
+}
+export {
+  syncSpecToAdoWithEnhancedContent
+};

package/plugins/specweave-docs/commands/build.md

@@ -1,19 +1,47 @@
 ---
 name: specweave-docs:build
-description: Build static documentation site for deployment. Auto-setup on first run. Outputs production-ready HTML/CSS/JS.
+description: Build static documentation site for deployment. Validates docs first, auto-fixes issues, auto-setup on first run. Outputs production-ready HTML/CSS/JS.
 ---
 
 # Documentation Build Command
 
 Build production-ready static documentation site for deployment to any static host.
 
+**CRITICAL**: Runs pre-flight validation to catch issues BEFORE building.
+
 ## Your Task
 
 **IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
 
-### Step 1: Ensure Docusaurus is Set Up
+### Step 1: CRITICAL - Run Pre-Flight Validation
+
+**ALWAYS validate BEFORE building to prevent cryptic webpack errors!**
+
+```typescript
+import { DocsValidator } from '../../../src/utils/docs-validator.js';
+
+const validator = new DocsValidator({
+  docsPath: '.specweave/docs/internal',
+  autoFix: true,  // Auto-fix common issues
+});
+
+console.log('\n🔍 Running pre-build validation...\n');
+const result = await validator.validate();
+
+// Show summary
+console.log(DocsValidator.formatResult(result));
+
+// If errors remain after auto-fix, STOP and report
+if (!result.valid) {
+  console.log('\n❌ Documentation has errors that must be fixed before build.');
+  console.log('   Fix the issues above, then try again.\n');
+  process.exit(1);
+}
+
+console.log('\n✅ Validation passed! Proceeding with build...\n');
+```
 
-First, ensure the cached Docusaurus installation exists:
+### Step 2: Ensure Docusaurus is Set Up
 
 ```bash
 # Check if Docusaurus is set up
@@ -26,7 +54,7 @@ fi
 
 If not set up, follow the same setup steps as `/specweave-docs:preview` (Step 3 in preview.md).
 
-### Step 2: Run Build
+### Step 3: Run Build
 
 ```bash
 cd .specweave/cache/docs-site && npm run build

package/plugins/specweave-docs/commands/preview.md

@@ -1,12 +1,14 @@
 ---
 name: specweave-docs:preview
-description: Launch Docusaurus documentation server for internal living docs. Auto-setup on first run. Port 3015.
+description: Launch Docusaurus documentation server for internal living docs. Validates docs first, auto-fixes issues, auto-setup on first run. Port 3015.
 ---
 
 # Documentation Preview Command
 
 Launch Docusaurus development server with hot reload, Mermaid diagrams, and auto-generated sidebar.
 
+**CRITICAL**: Runs pre-flight validation to catch issues BEFORE starting the server.
+
 ## Your Task
 
 **IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
@@ -22,6 +24,46 @@ ls -la .specweave/docs/internal/
 #  Run 'specweave init' first or create the folder structure."
 ```
 
+### Step 1.5: CRITICAL - Run Pre-Flight Validation
+
+**ALWAYS run validation BEFORE starting the server!**
+
+```typescript
+import { DocsValidator } from '../../../src/utils/docs-validator.js';
+
+const validator = new DocsValidator({
+  docsPath: '.specweave/docs/internal',
+  autoFix: true,  // Auto-fix common issues
+});
+
+console.log('\n🔍 Running pre-flight validation...\n');
+const result = await validator.validate();
+
+// Show summary
+console.log(DocsValidator.formatResult(result));
+
+// If errors remain after auto-fix, STOP and report
+if (!result.valid) {
+  console.log('\n❌ Documentation has errors that must be fixed before preview.');
+  console.log('   Fix the issues above, then try again.\n');
+  process.exit(1);
+}
+
+console.log('\n✅ Validation passed! Starting server...\n');
+```
+
+**What this catches:**
+- YAML frontmatter errors (unquoted colons, tabs)
+- MDX compatibility issues (unquoted attributes, unclosed tags)
+- Duplicate routes
+- Broken internal links
+
+**Auto-fixes applied:**
+- Wraps YAML values with colons in quotes
+- Quotes HTML attributes
+- Adds closing slashes to void elements (`<br>` → `<br />`)
+- Converts tabs to spaces in YAML
+
 ### Step 2: Check for Cached Installation
 
 ```bash

package/plugins/specweave-docs/commands/validate.md

@@ -0,0 +1,250 @@
+---
+name: specweave-docs:validate
+description: Validate documentation before preview/build. Catches YAML, MDX, broken links, and naming issues. Auto-fix available. Run this BEFORE preview or build to prevent cryptic webpack errors.
+---
+
+# Documentation Validation Command
+
+Validate your documentation for Docusaurus compatibility BEFORE starting the preview server or building.
+
+## Why This Matters
+
+Docusaurus compilation errors are often cryptic:
+- `Unexpected character` → unquoted HTML attribute
+- `Unterminated JSX contents` → unclosed tag
+- `Could not parse expression` → bad YAML frontmatter
+
+This validator catches these issues **before** you see webpack errors.
+
+## Usage
+
+```bash
+# Validate internal docs (default)
+/specweave-docs:validate
+
+# Validate with auto-fix
+/specweave-docs:validate --fix
+
+# Validate public docs
+/specweave-docs:validate public
+
+# Validate specific path
+/specweave-docs:validate --path .specweave/docs/internal/specs
+```
+
+## Your Task
+
+**CRITICAL**: Run validation BEFORE starting preview or build!
+
+### Step 1: Determine Docs Path
+
+```bash
+# Check which docs to validate
+DOCS_TYPE="${1:-internal}"  # internal or public
+
+if [ "$DOCS_TYPE" = "public" ]; then
+  DOCS_PATH=".specweave/docs/public"
+else
+  DOCS_PATH=".specweave/docs/internal"
+fi
+
+# Verify path exists
+if [ ! -d "$DOCS_PATH" ]; then
+  echo "❌ Documentation path not found: $DOCS_PATH"
+  exit 1
+fi
+```
+
+### Step 2: Run Validation
+
+Execute the validation using the DocsValidator:
+
+```typescript
+import { DocsValidator } from '../../../src/utils/docs-validator.js';
+import * as path from 'path';
+
+// Get options from command args
+const autoFix = process.argv.includes('--fix');
+const docsType = process.argv.find(a => a === 'public') ? 'public' : 'internal';
+const docsPath = path.resolve(`.specweave/docs/${docsType}`);
+
+// Create validator
+const validator = new DocsValidator({
+  docsPath,
+  autoFix,
+});
+
+// Run validation
+console.log(`\n📋 Validating ${docsType} documentation...`);
+console.log(`   Path: ${docsPath}\n`);
+
+const result = await validator.validate();
+
+// Display formatted result
+console.log(DocsValidator.formatResult(result));
+
+// Exit with error code if invalid (for CI integration)
+if (!result.valid && !autoFix) {
+  console.log('💡 Tip: Run with --fix to auto-repair fixable issues\n');
+  process.exit(1);
+}
+```
+
+### Step 3: Report Results
+
+Display a clear summary:
+
+```
+═══════════════════════════════════════════════════════════════
+               DOCUMENTATION VALIDATION REPORT
+═══════════════════════════════════════════════════════════════
+
+✅ Documentation is valid and ready for preview/build
+
+   Errors:   0
+   Warnings: 3
+   Info:     0
+
+═══════════════════════════════════════════════════════════════
+```
+
+Or if issues found:
+
+```
+═══════════════════════════════════════════════════════════════
+               DOCUMENTATION VALIDATION REPORT
+═══════════════════════════════════════════════════════════════
+
+❌ Documentation has issues that need to be fixed
+
+   Errors:   2
+   Warnings: 5
+   Info:     0
+
+ERRORS (must fix):
+───────────────────────────────────────────────────────────────
+  📄 specs/FS-118E/FEATURE.md
+     ❌ yaml_unquoted_colon:3: Unquoted colon in YAML value: title: Feature: External Sync [auto-fixable]
+
+  📄 architecture/diagrams/overview.md
+     ❌ mdx_compatibility: Unquoted attribute: target=_blank [auto-fixable]
+
+QUICK FIXES:
+───────────────────────────────────────────────────────────────
+  1. Run validation with auto-fix:
+     /specweave-docs:validate --fix
+
+  2. Or fix manually:
+     • YAML: Wrap values with colons in quotes
+       title: "Feature: Auth" (not title: Feature: Auth)
+     • MDX: Quote HTML attributes, close self-closing tags
+       target="_blank" (not target=_blank)
+       <br /> (not <br>)
+
+═══════════════════════════════════════════════════════════════
+```
+
+## What Gets Validated
+
+### 1. YAML Frontmatter
+- Unclosed frontmatter (`---` without closing `---`)
+- Unquoted colons in values (`title: Feature: Auth` → error)
+- Tab characters (YAML requires spaces)
+- Invalid syntax
+
+### 2. MDX/JSX Compatibility
+- Unquoted HTML attributes (`target=_blank` → needs quotes)
+- Non-self-closing void tags (`<br>` → needs `<br />`)
+- Script/style tags (not allowed in MDX)
+- Unclosed HTML comments
+
+### 3. File Issues
+- Duplicate routes (same path, different extensions)
+- Invalid filename characters
+- Spaces in filenames (URL issues)
+- Very long filenames
+
+### 4. Internal Links
+- Broken links to non-existent files
+- Links to files outside docs folder (warning)
+- Malformed link syntax
+
+## Auto-Fix Behavior
+
+With `--fix`, the validator automatically repairs:
+
+| Issue Type | Auto-Fix Action |
+|------------|-----------------|
+| `yaml_unquoted_colon` | Wraps value in quotes |
+| `yaml_tabs` | Converts tabs to spaces |
+| `mdx_compatibility` | Quotes attributes, closes tags |
+
+Issues that **cannot** be auto-fixed:
+- Broken links (need manual review)
+- Duplicate routes (need to rename/delete)
+- Invalid filenames (need manual rename)
+
+## CI/CD Integration
+
+Use in GitHub Actions to gate deployments:
+
+```yaml
+name: Validate Docs
+
+on:
+  push:
+    paths:
+      - '.specweave/docs/**'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install
+      - run: npx specweave docs:validate
+```
+
+## Troubleshooting
+
+### "yaml_unquoted_colon" errors
+```yaml
+# Wrong:
+title: Feature: External Sync
+
+# Correct:
+title: "Feature: External Sync"
+```
+
+### "mdx_compatibility" errors
+```html
+<!-- Wrong -->
+<a href="..." target=_blank>Link</a>
+<br>
+
+<!-- Correct -->
+<a href="..." target="_blank">Link</a>
+<br />
+```
+
+### Many broken link warnings
+If you see many warnings about links to `CLAUDE.md`, `README.md`, or `_archive/`:
+- These are references to files outside the docs folder
+- They're warnings, not errors
+- The docs will still render, links just won't work in preview
+
+### To suppress warnings for intentional external refs
+Add to docusaurus.config.ts:
+```typescript
+onBrokenLinks: 'warn',  // Not 'throw'
+onBrokenMarkdownLinks: 'warn',
+```
+
+## See Also
+
+- `/specweave-docs:preview` - Preview docs (runs validation first)
+- `/specweave-docs:build` - Build docs (runs validation first)
+- `/specweave-docs:health` - Full documentation health report