specweave 1.0.593 → 2.0.3

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

@@ -1,445 +0,0 @@
----
-description: Generate documentation from TypeScript/JavaScript code, OpenAPI specs, GraphQL schemas, and SpecWeave specifications.
----
-
-# Generate Documentation from Code
-
-Generate documentation automatically from TypeScript/JavaScript code, OpenAPI specs, GraphQL schemas, and SpecWeave specifications. Creates comprehensive API docs, type references, and usage examples.
-
-## Usage
-
-```
-/docs:generate <source-type> <path> [options]
-```
-
-## Source Types
-
-### 1. TypeScript/JavaScript Code
-```bash
-/docs:docs-generate code ./src \
-  --output ./docs/api \
-  --format markdown
-```
-
-### 2. OpenAPI/Swagger Specs
-```bash
-/docs:docs-generate openapi ./api/openapi.yaml \
-  --output ./docs/api \
-  --interactive
-```
-
-### 3. GraphQL Schema
-```bash
-/docs:docs-generate graphql ./schema.graphql \
-  --output ./docs/graphql
-```
-
-### 4. SpecWeave Living Docs
-```bash
-/docs:docs-generate specweave ./.specweave/docs \
-  --output ./docs/specs \
-  --include features,modules,architecture
-```
-
-## Options
-
-### General Options
-- `--output <path>` - Output directory (default: `./docs/generated`)
-- `--format <format>` - Output format: markdown, html, json (default: markdown)
-- `--template <template>` - Custom template directory
-- `--watch` - Watch for changes and regenerate
-
-### Code Documentation Options
-- `--exclude <patterns>` - Exclude files/directories (glob patterns)
-- `--include-private` - Include private members (default: false)
-- `--include-internal` - Include @internal tagged members (default: false)
-- `--examples` - Generate usage examples (default: true)
-- `--types` - Generate type reference docs (default: true)
-
-### OpenAPI Options
-- `--interactive` - Generate interactive API playground (default: true)
-- `--group-by <field>` - Group endpoints by: tag, path, method (default: tag)
-- `--show-examples` - Include request/response examples (default: true)
-
-### SpecWeave Options
-- `--include <types>` - Comma-separated: features, modules, architecture, team
-- `--depth <number>` - Directory depth to traverse (default: unlimited)
-- `--format-adrs` - Special formatting for ADRs (default: true)
-
-## Generated Documentation
-
-### From TypeScript Code
-
-Generates comprehensive API documentation using TypeDoc:
-
-**Input**: TypeScript source files
-```typescript
-/**
- * User management service
- * @category Services
- * @example
- * ```ts
- * const service = new UserService();
- * const user = await service.getUser(123);
- * ```
- */
-export class UserService {
-  /**
-   * Retrieve user by ID
-   * @param userId - Unique user identifier
-   * @returns User object or null if not found
-   * @throws {UserNotFoundError} If user doesn't exist
-   */
-  async getUser(userId: number): Promise<User | null> {
-    // implementation
-  }
-}
-```
-
-**Output**: Markdown documentation
-```markdown
-# UserService
-
-User management service
-
-## Methods
-
-### getUser
-
-Retrieve user by ID
-
-**Parameters:**
-- `userId`: number - Unique user identifier
-
-**Returns:** `Promise<User | null>` - User object or null if not found
-
-**Throws:**
-- `UserNotFoundError` - If user doesn't exist
-
-**Example:**
-\```typescript
-const service = new UserService();
-const user = await service.getUser(123);
-\```
-```
-
-### From OpenAPI Specification
-
-Generates interactive API documentation:
-
-**Input**: OpenAPI YAML/JSON
-```yaml
-paths:
-  /users/{id}:
-    get:
-      summary: Get user by ID
-      parameters:
-        - name: id
-          in: path
-          required: true
-          schema:
-            type: integer
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/User'
-```
-
-**Output**: Interactive Markdown with API playground
-```markdown
-# GET /users/{id}
-
-Get user by ID
-
-## Parameters
-
-| Name | In   | Type    | Required | Description |
-|------|------|---------|----------|-------------|
-| id   | path | integer | Yes      | User ID     |
-
-## Responses
-
-### 200 OK
-
-Successful response
-
-**Response Schema:**
-\```json
-{
-  "id": 123,
-  "name": "John Doe",
-  "email": "john@example.com"
-}
-\```
-
-## Try it out
-
-[Interactive API Playground]
-
-\```bash
-curl -X GET https://api.example.com/users/123 \
-  -H "Authorization: Bearer YOUR_TOKEN"
-\```
-```
-
-### From SpecWeave Living Docs
-
-Generates consolidated documentation from `.specweave/docs/`:
-
-**Input**: SpecWeave directory structure
-```
-.specweave/docs/
-├── features/
-│   ├── FS-001/
-│   │   ├── feature.md
-│   │   └── user-stories/
-│   │       ├── US-001.md
-│   │       └── US-002.md
-│   └── FS-002/
-├── modules/
-│   ├── authentication/
-│   │   └── module.md
-│   └── payments/
-└── architecture/
-    ├── adr/
-    │   ├── 0001-tech-stack.md
-    │   └── 0002-database-choice.md
-    └── diagrams/
-```
-
-**Output**: Organized Docusaurus docs
-```
-docs/
-├── features/
-│   ├── fs-001-user-authentication.md
-│   ├── fs-002-payment-processing.md
-│   └── index.md
-├── modules/
-│   ├── authentication.md
-│   ├── payments.md
-│   └── index.md
-└── architecture/
-    ├── decisions/
-    │   ├── adr-0001.md
-    │   ├── adr-0002.md
-    │   └── index.md
-    └── diagrams.md
-```
-
-## Configuration
-
-### TypeDoc Configuration
-
-Create `typedoc.json`:
-```json
-{
-  "entryPoints": ["./src"],
-  "out": "./docs/api",
-  "plugin": ["typedoc-plugin-markdown"],
-  "readme": "none",
-  "excludePrivate": true,
-  "excludeInternal": true,
-  "categorizeByGroup": true,
-  "categoryOrder": ["Services", "Models", "Utils", "*"],
-  "sort": ["source-order"]
-}
-```
-
-### Custom Templates
-
-Create custom Handlebars templates:
-
-```handlebars
-{{!-- templates/class.hbs --}}
-# {{name}}
-
-{{#if comment}}
-{{comment}}
-{{/if}}
-
-## Constructor
-
-\```typescript
-new {{name}}({{#each constructorParams}}{{name}}: {{type}}{{#unless @last}}, {{/unless}}{{/each}})
-\```
-
-## Methods
-
-{{#each methods}}
-### {{name}}
-
-{{comment}}
-
-**Signature:**
-\```typescript
-{{signature}}
-\```
-{{/each}}
-```
-
-## Continuous Documentation
-
-### Watch Mode
-
-Auto-regenerate on file changes:
-```bash
-/docs:docs-generate code ./src --watch
-```
-
-### CI/CD Integration
-
-```yaml
-# .github/workflows/docs.yml
-name: Generate Documentation
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'src/**'
-      - 'api/**'
-
-jobs:
-  docs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Generate API docs
-        run: |
-          npm install
-          npx claude /docs:docs-generate code ./src
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs
-```
-
-## Use Cases
-
-### 1. API Reference Documentation
-Generate comprehensive API docs from TypeScript interfaces and JSDoc comments.
-
-### 2. OpenAPI Documentation
-Create interactive API explorers from OpenAPI/Swagger specifications.
-
-### 3. Architecture Documentation
-Consolidate ADRs, diagrams, and technical specifications into searchable docs.
-
-### 4. Living Documentation
-Auto-sync SpecWeave features, user stories, and modules to documentation site.
-
-### 5. Type Documentation
-Generate TypeScript type reference guides for library consumers.
-
-## Advanced Features
-
-### Custom Transformers
-
-```typescript
-// transformers/custom-transformer.ts
-import { DocNode } from 'typedoc';
-
-export function transformNode(node: DocNode): DocNode {
-  // Custom transformation logic
-  if (node.kind === 'method' && node.name.startsWith('_')) {
-    return null; // Skip private methods
-  }
-  return node;
-}
-```
-
-### Multi-Source Aggregation
-
-```bash
-# Generate from multiple sources
-/docs:docs-generate code ./src --output ./docs/api
-/docs:docs-generate openapi ./api/openapi.yaml --output ./docs/api
-/docs:docs-generate specweave ./.specweave/docs --output ./docs/specs
-
-# Combine all outputs
-cat ./docs/api/index.md ./docs/specs/index.md > ./docs/complete-reference.md
-```
-
-### Internationalization
-
-```bash
-# Generate docs in multiple languages
-/docs:docs-generate code ./src --output ./docs/en --lang en
-/docs:docs-generate code ./src --output ./docs/es --lang es
-/docs:docs-generate code ./src --output ./docs/fr --lang fr
-```
-
-## Examples
-
-### Generate TypeScript API Docs
-```bash
-/docs:docs-generate code ./src/api \
-  --output ./docs/api-reference \
-  --exclude "**/*.test.ts" \
-  --include-examples
-```
-
-### Generate OpenAPI Docs with Playground
-```bash
-/docs:docs-generate openapi ./api/v1/openapi.yaml \
-  --output ./docs/api/v1 \
-  --interactive \
-  --group-by tag
-```
-
-### Generate SpecWeave Architecture Docs
-```bash
-/docs:docs-generate specweave ./.specweave/docs \
-  --output ./docs/architecture \
-  --include architecture,modules \
-  --format-adrs
-```
-
-### Watch Mode for Development
-```bash
-/docs:docs-generate code ./src --watch
-```
-
-## Related Commands
-
-- `/docs:init` - Initialize Docusaurus documentation site
-- `/docs:view` - View generated documentation
-- `/docs:build` - Build static site from generated docs
-
-## Requirements
-
-- **TypeDoc**: For TypeScript/JavaScript documentation
-- **Redocly**: For OpenAPI documentation
-- **GraphQL Code Generator**: For GraphQL schema docs
-- **Node.js 18+**: Runtime requirement
-
-## Performance Tips
-
-1. **Incremental Generation**: Use `--watch` for development
-2. **Exclude Tests**: Skip test files with `--exclude "**/*.test.ts"`
-3. **Parallel Processing**: Generate different sources concurrently
-4. **Cache Results**: Reuse generated docs when source hasn't changed
-
-## Troubleshooting
-
-### Missing Dependencies
-```bash
-npm install --save-dev typedoc typedoc-plugin-markdown @redocly/cli
-```
-
-### Large Codebases
-```bash
-# Increase Node.js memory
-NODE_OPTIONS="--max-old-space-size=4096" \
-  /docs:docs-generate code ./src
-```
-
-### Broken Links in Generated Docs
-```bash
-# Validate generated docs
-npx markdown-link-check ./docs/**/*.md
-```

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

@@ -1,267 +0,0 @@
----
-description: Documentation health report - analyzes docs for freshness, coverage, naming violations, duplicates, and provides recommendations.
----
-
-# Documentation Health Report
-
-Analyze your documentation for health issues including freshness, coverage, naming violations, duplicates, and spec-code mismatches.
-
-## Usage
-
-```bash
-# Full health report
-/docs:health
-
-# Include archived documents
-/docs:health --include-archived
-
-# Output as JSON
-/docs:health --format json
-
-# Save report to file
-/docs:health --output health-report.md
-```
-
-## Your Task
-
-Execute the enterprise documentation analyzer:
-
-```typescript
-import { EnterpriseDocAnalyzer, generateEnterpriseReport } from '../../src/living-docs/enterprise-analyzer.js';
-import * as fs from 'fs';
-import * as path from 'path';
-
-const projectPath = process.cwd();
-
-// Create analyzer
-const analyzer = new EnterpriseDocAnalyzer({
-  projectPath,
-  includeArchived: false, // Set true to include archived docs
-});
-
-// Run analysis
-console.log('\nAnalyzing Documentation Health...\n');
-const report = await analyzer.analyze();
-
-// Generate markdown report
-const markdownReport = generateEnterpriseReport(report);
-
-// Display summary
-console.log(`
-DOCUMENTATION HEALTH REPORT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Overall Score: ${report.healthScore.overall}% (Grade: ${report.healthScore.grade})
-
-Metrics:
-  Freshness: ${report.healthScore.freshness}%
-  Coverage:  ${report.healthScore.coverage}%
-  Accuracy:  ${report.healthScore.accuracy}%
-
-Categories: ${report.categories.length}
-Total Documents: ${report.totalDocuments}
-
-Issues Found:
-  Spec-Code Mismatches: ${report.mismatches.length}
-  Naming Violations: ${report.namingViolations.length}
-  Duplicates: ${report.duplicates.length}
-  Discrepancies: ${report.discrepancies.length}
-
-Recommendations: ${report.recommendations.length}
-`);
-
-// Show recommendations
-if (report.recommendations.length > 0) {
-  console.log('RECOMMENDATIONS');
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
-  for (const rec of report.recommendations) {
-    console.log(`• ${rec}`);
-  }
-}
-
-// Optionally save full report
-const outputPath = path.join(projectPath, '.specweave/docs/ENTERPRISE-HEALTH.md');
-fs.writeFileSync(outputPath, markdownReport);
-console.log(`\nFull report saved to: ${outputPath}`);
-```
-
-## Health Metrics
-
-### Overall Score (0-100%)
-
-Weighted combination of:
-- **Freshness** (20%): Documents updated in last 30 days
-- **Coverage** (30%): Documents with acceptance criteria
-- **Accuracy** (50%): ACs without spec-code mismatches + naming compliance
-
-### Grade Scale
-
-| Grade | Score Range | Meaning |
-|-------|-------------|---------|
-| A | 90-100% | Excellent documentation health |
-| B | 80-89% | Good, minor improvements needed |
-| C | 70-79% | Acceptable, several issues |
-| D | 60-69% | Below standard, action required |
-| F | <60% | Critical issues, immediate attention |
-
-## Issue Types
-
-### Spec-Code Mismatches
-
-| Type | Description |
-|------|-------------|
-| `ghost_completion` | AC marked complete but no code evidence found |
-| `partial_implementation` | Very little code evidence (<10 lines) |
-| `undocumented_code` | Code exists without corresponding spec |
-| `spec_drift` | Spec and code have diverged |
-
-### Naming Violations
-
-| Type | Severity | Example |
-|------|----------|---------|
-| `all_caps` | Warning | `CIRCUIT-BREAKER.md` |
-| `mixed_case` | Warning | `CircuitBreaker.md` |
-| `date_suffix` | Info | `feature-2025-11-24.md` |
-| `no_extension` | Error | `readme` (missing .md) |
-
-### Duplicates
-
-| Type | Description |
-|------|-------------|
-| `exact` | Identical content |
-| `near_duplicate` | Very similar content (>90%) |
-| `same_title` | Same normalized title |
-
-### Discrepancies
-
-| Type | Description |
-|------|-------------|
-| `broken_link` | Link to non-existent file |
-| `orphaned_reference` | Reference to deleted increment |
-| `outdated_version` | Old version numbers (v0.x) |
-| `conflicting_info` | Contradictory information |
-
-## Report Sections
-
-### 1. Health Score Summary
-
-```
-| Metric | Score | Grade |
-|--------|-------|-------|
-| Overall | 85% | B |
-| Freshness | 72% | - |
-| Coverage | 65% | - |
-| Accuracy | 92% | - |
-```
-
-### 2. Documentation Categories
-
-```
-| Category | Documents | Last Updated |
-|----------|-----------|--------------|
-| Feature Specs | 45 | 12/3/2025 |
-| Architecture | 148 | 12/3/2025 |
-| ADRs | 147 | 12/3/2025 |
-```
-
-### 3. Spec-Code Mismatches
-
-```
-| AC ID | Type | Confidence | File |
-|-------|------|------------|------|
-| AC-US1-01 | ghost_completion | 70% | spec-0045.md |
-```
-
-### 4. Naming Violations
-
-```
-| File | Type | Severity | Expected |
-|------|------|----------|----------|
-| CIRCUIT-BREAKER.md | all_caps | Warning | lowercase-kebab.md |
-```
-
-### 5. Recommendations
-
-Actionable suggestions based on analysis:
-- Update stale documentation
-- Add acceptance criteria
-- Fix naming conventions
-- Consolidate duplicates
-- Run `/docs:organize` for large folders
-
-## Output Example
-
-```
-DOCUMENTATION HEALTH REPORT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Overall Score: 78% (Grade: C)
-
-Metrics:
-  Freshness: 65%
-  Coverage:  42%
-  Accuracy:  89%
-
-Categories: 6
-Total Documents: 708
-
-Issues Found:
-  Spec-Code Mismatches: 12
-  Naming Violations: 8
-  Duplicates: 3
-  Discrepancies: 15
-
-Recommendations: 5
-
-RECOMMENDATIONS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-• Documentation freshness is low. Consider reviewing docs over 30 days old.
-• Documentation coverage is limited. Add acceptance criteria to more documents.
-• 8 files use ALL CAPS naming. Rename to lowercase-kebab-case.
-• 3 sets of duplicate documents detected. Consider consolidating.
-• "ADRs" has 147 files. Run /docs:organize to generate themed indexes.
-
-Full report saved to: .specweave/docs/ENTERPRISE-HEALTH.md
-```
-
-## Integrations
-
-### CI/CD Health Check
-
-```yaml
-# .github/workflows/docs-health.yml
-name: Documentation Health
-
-on:
-  push:
-    paths:
-      - '.specweave/docs/**'
-
-jobs:
-  health-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Check Documentation Health
-        run: |
-          npx specweave docs:health --format json > health.json
-          SCORE=$(jq '.healthScore.overall' health.json)
-          if [ $SCORE -lt 70 ]; then
-            echo "Documentation health below threshold: $SCORE%"
-            exit 1
-          fi
-```
-
-### Scheduled Reports
-
-```bash
-# Run weekly health check
-0 9 * * 1 cd /project && npx specweave docs:health --output weekly-health.md
-```
-
-## See Also
-
-- `/docs:organize` - Organize large folders with themed indexes
-- `/docs:view` - View documentation with Docusaurus
-- `/docs:generate` - Generate docs from code