specweave 0.23.18 → 0.24.0

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

@@ -0,0 +1,168 @@
+# /specweave-diagrams:diagrams-generate
+
+Generate Mermaid architecture diagrams following C4 Model conventions.
+
+You are an expert in creating clear, comprehensive architecture diagrams using Mermaid syntax and C4 Model principles.
+
+## Your Task
+
+Generate architecture diagrams based on the user's requirements using Mermaid.js syntax. Follow these guidelines:
+
+### 1. Diagram Types
+
+Support these diagram types:
+- **C4 Context Diagrams**: System context with external actors and systems
+- **C4 Container Diagrams**: High-level technology choices and container relationships
+- **C4 Component Diagrams**: Internal component structure
+- **Sequence Diagrams**: Interaction flows and timing
+- **ER Diagrams**: Database schema and relationships
+- **Deployment Diagrams**: Infrastructure and deployment architecture
+
+### 2. C4 Model Conventions
+
+**Context Level**:
+```mermaid
+C4Context
+    title System Context diagram for [System Name]
+
+    Person(user, "User", "End user of the system")
+    System(systemA, "System A", "Core system")
+    System_Ext(systemB, "External System", "Third-party service")
+
+    Rel(user, systemA, "Uses")
+    Rel(systemA, systemB, "Integrates with", "HTTPS")
+```
+
+**Container Level**:
+```mermaid
+C4Container
+    title Container diagram for [System Name]
+
+    Container(web, "Web Application", "React", "User interface")
+    Container(api, "API", "Node.js", "Business logic")
+    ContainerDb(db, "Database", "PostgreSQL", "Data storage")
+
+    Rel(web, api, "Calls", "HTTPS/JSON")
+    Rel(api, db, "Reads/Writes", "SQL")
+```
+
+**Component Level**:
+```mermaid
+C4Component
+    title Component diagram for [Container Name]
+
+    Component(controller, "Controller", "Express", "Handles HTTP requests")
+    Component(service, "Service", "TypeScript", "Business logic")
+    Component(repository, "Repository", "TypeORM", "Data access")
+
+    Rel(controller, service, "Uses")
+    Rel(service, repository, "Uses")
+```
+
+### 3. Sequence Diagrams
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Frontend
+    participant API
+    participant Database
+
+    User->>Frontend: Login request
+    Frontend->>API: POST /auth/login
+    API->>Database: Validate credentials
+    Database-->>API: User data
+    API-->>Frontend: JWT token
+    Frontend-->>User: Success
+```
+
+### 4. ER Diagrams
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ ORDER_ITEM : contains
+    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
+
+    USER {
+        uuid id PK
+        string email
+        string name
+        timestamp created_at
+    }
+
+    ORDER {
+        uuid id PK
+        uuid user_id FK
+        decimal total
+        timestamp created_at
+    }
+```
+
+### 5. Best Practices
+
+1. **Clear Labels**: Use descriptive names for all elements
+2. **Consistent Direction**: Top-to-bottom or left-to-right flow
+3. **Technology Stack**: Include tech choices in container/component diagrams
+4. **Relationships**: Label all connections with protocol/method
+5. **Color Coding**: Use consistent colors for similar element types
+6. **Boundaries**: Show system boundaries clearly
+
+### 6. Output Format
+
+Always wrap diagrams in proper Mermaid code blocks:
+
+\`\`\`mermaid
+[diagram code]
+\`\`\`
+
+Include:
+- Diagram title
+- Legend if needed
+- Notes for complex interactions
+- Tech stack documentation
+
+### 7. Validation
+
+Ensure diagrams:
+- Use valid Mermaid syntax
+- Follow C4 conventions
+- Are readable at default zoom
+- Include all requested elements
+- Show data flow direction clearly
+
+## Example Usage
+
+**User**: "Create a C4 context diagram for an e-commerce system"
+
+**Response**:
+```mermaid
+C4Context
+    title E-Commerce System - Context Diagram
+
+    Person(customer, "Customer", "Shops for products online")
+    Person(admin, "Admin", "Manages products and orders")
+
+    System(ecommerce, "E-Commerce Platform", "Online shopping system")
+    System_Ext(payment, "Payment Gateway", "Processes payments")
+    System_Ext(shipping, "Shipping Provider", "Handles delivery")
+    System_Ext(email, "Email Service", "Sends notifications")
+
+    Rel(customer, ecommerce, "Browses products, places orders")
+    Rel(admin, ecommerce, "Manages catalog, views analytics")
+    Rel(ecommerce, payment, "Processes payments", "HTTPS/API")
+    Rel(ecommerce, shipping, "Creates shipments", "HTTPS/API")
+    Rel(ecommerce, email, "Sends notifications", "SMTP")
+```
+
+## When to Use
+
+This command is ideal for:
+- System architecture documentation
+- Technical design reviews
+- Database schema visualization
+- API interaction flows
+- Deployment architecture
+- Component relationships
+
+Generate diagrams that are clear, comprehensive, and follow industry best practices!

package/plugins/specweave-docs/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "specweave-docs",
+  "version": "0.24.0",
+  "description": "Documentation generation and management - Docusaurus, spec-driven docs, API documentation, living documentation",
+  "author": {
+    "name": "Anton Abyzov",
+    "email": "anton.abyzov@gmail.com"
+  },
+  "hooks": {}
+}

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

@@ -0,0 +1,441 @@
+# Docs Generate - 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
+
+```
+/specweave-docs:docs-generate <source-type> <path> [options]
+```
+
+## Source Types
+
+### 1. TypeScript/JavaScript Code
+```bash
+/specweave-docs:docs-generate code ./src \
+  --output ./docs/api \
+  --format markdown
+```
+
+### 2. OpenAPI/Swagger Specs
+```bash
+/specweave-docs:docs-generate openapi ./api/openapi.yaml \
+  --output ./docs/api \
+  --interactive
+```
+
+### 3. GraphQL Schema
+```bash
+/specweave-docs:docs-generate graphql ./schema.graphql \
+  --output ./docs/graphql
+```
+
+### 4. SpecWeave Living Docs
+```bash
+/specweave-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
+/specweave-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 /specweave-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
+/specweave-docs:docs-generate code ./src --output ./docs/api
+/specweave-docs:docs-generate openapi ./api/openapi.yaml --output ./docs/api
+/specweave-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
+/specweave-docs:docs-generate code ./src --output ./docs/en --lang en
+/specweave-docs:docs-generate code ./src --output ./docs/es --lang es
+/specweave-docs:docs-generate code ./src --output ./docs/fr --lang fr
+```
+
+## Examples
+
+### Generate TypeScript API Docs
+```bash
+/specweave-docs:docs-generate code ./src/api \
+  --output ./docs/api-reference \
+  --exclude "**/*.test.ts" \
+  --include-examples
+```
+
+### Generate OpenAPI Docs with Playground
+```bash
+/specweave-docs:docs-generate openapi ./api/v1/openapi.yaml \
+  --output ./docs/api/v1 \
+  --interactive \
+  --group-by tag
+```
+
+### Generate SpecWeave Architecture Docs
+```bash
+/specweave-docs:docs-generate specweave ./.specweave/docs \
+  --output ./docs/architecture \
+  --include architecture,modules \
+  --format-adrs
+```
+
+### Watch Mode for Development
+```bash
+/specweave-docs:docs-generate code ./src --watch
+```
+
+## Related Commands
+
+- `/specweave-docs:docs-init` - Initialize Docusaurus documentation site
+- `/specweave-docs-preview:preview` - Preview generated documentation
+- `/specweave-docs-preview: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" \
+  /specweave-docs:docs-generate code ./src
+```
+
+### Broken Links in Generated Docs
+```bash
+# Validate generated docs
+npx markdown-link-check ./docs/**/*.md
+```