@windagency/valora 2.0.1

package/data/templates/DOC_COMPONENT_QUICK.md

@@ -0,0 +1,180 @@
+# Component Documentation: [ComponentName]
+
+| Attribute        | Value                                        |
+| ---------------- | -------------------------------------------- |
+| **Type**         | Atom / Molecule / Organism / Template / Page |
+| **Path**         | `src/components/[path]/[ComponentName].tsx`  |
+| **Last Updated** | [YYYY-MM-DD]                                 |
+
+---
+
+## Overview
+
+[Brief description of the component's purpose and usage]
+
+---
+
+## Props
+
+| Prop       | Type                       | Required | Default     | Description          |
+| ---------- | -------------------------- | -------- | ----------- | -------------------- |
+| `variant`  | `'primary' \| 'secondary'` | No       | `'primary'` | Visual variant       |
+| `size`     | `'sm' \| 'md' \| 'lg'`     | No       | `'md'`      | Size of component    |
+| `disabled` | `boolean`                  | No       | `false`     | Disable interactions |
+| `onClick`  | `() => void`               | No       | -           | Click handler        |
+| `children` | `ReactNode`                | Yes      | -           | Content to render    |
+
+---
+
+## Usage
+
+### Basic
+
+```tsx
+import { ComponentName } from 'src/components/ComponentName';
+
+<ComponentName>Content here</ComponentName>;
+```
+
+### With Variants
+
+```tsx
+<ComponentName variant="primary" size="lg">
+  Primary Large
+</ComponentName>
+
+<ComponentName variant="secondary" size="sm">
+  Secondary Small
+</ComponentName>
+```
+
+### With Event Handler
+
+```tsx
+<ComponentName onClick={() => console.log('Clicked!')}>Click Me</ComponentName>
+```
+
+---
+
+## Styling
+
+### CSS Variables
+
+| Variable             | Default   | Description       |
+| -------------------- | --------- | ----------------- |
+| `--component-bg`     | `#ffffff` | Background colour |
+| `--component-text`   | `#000000` | Text colour       |
+| `--component-border` | `#e0e0e0` | Border colour     |
+
+### Tailwind Classes
+
+```tsx
+// Base classes
+'rounded-lg border shadow-sm';
+
+// Variant: primary
+'bg-primary text-white hover:bg-primary-dark';
+
+// Variant: secondary
+'bg-secondary text-gray-900 hover:bg-secondary-dark';
+
+// Size: sm
+'px-2 py-1 text-sm';
+
+// Size: md
+'px-4 py-2 text-base';
+
+// Size: lg
+'px-6 py-3 text-lg';
+```
+
+---
+
+## States
+
+| State    | Appearance            | Trigger           |
+| -------- | --------------------- | ----------------- |
+| Default  | Normal styling        | Initial render    |
+| Hover    | Slightly darker       | Mouse over        |
+| Active   | Pressed appearance    | Mouse down        |
+| Focus    | Focus ring            | Keyboard focus    |
+| Disabled | Greyed out, no cursor | `disabled={true}` |
+| Loading  | Spinner, disabled     | `loading={true}`  |
+
+---
+
+## Accessibility
+
+| Feature             | Implementation                    |
+| ------------------- | --------------------------------- |
+| Keyboard Navigation | Focusable with Tab                |
+| Screen Reader       | Uses semantic HTML                |
+| ARIA Labels         | `aria-label` for icons            |
+| Focus Visible       | Visible focus ring                |
+| Reduced Motion      | Respects `prefers-reduced-motion` |
+
+### ARIA Attributes
+
+```tsx
+<ComponentName aria-label="Action description" aria-disabled={disabled} role="button" />
+```
+
+---
+
+## Testing
+
+### Unit Tests
+
+```tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ComponentName } from './ComponentName';
+
+describe('ComponentName', () => {
+	it('renders children', () => {
+		render(<ComponentName>Test Content</ComponentName>);
+		expect(screen.getByText('Test Content')).toBeInTheDocument();
+	});
+
+	it('calls onClick when clicked', () => {
+		const handleClick = vi.fn();
+		render(<ComponentName onClick={handleClick}>Click</ComponentName>);
+		fireEvent.click(screen.getByText('Click'));
+		expect(handleClick).toHaveBeenCalledTimes(1);
+	});
+
+	it('is disabled when disabled prop is true', () => {
+		render(<ComponentName disabled>Disabled</ComponentName>);
+		expect(screen.getByRole('button')).toBeDisabled();
+	});
+});
+```
+
+### Accessibility Tests
+
+```tsx
+import { axe } from 'vitest-axe';
+
+it('has no accessibility violations', async () => {
+	const { container } = render(<ComponentName>Accessible</ComponentName>);
+	const results = await axe(container);
+	expect(results).toHaveNoViolations();
+});
+```
+
+---
+
+## Related Components
+
+| Component     | Relationship | Description             |
+| ------------- | ------------ | ----------------------- |
+| `Button`      | Similar      | Base button component   |
+| `IconButton`  | Variant      | Icon-only version       |
+| `ButtonGroup` | Parent       | Groups multiple buttons |
+
+---
+
+## Changelog
+
+| Version | Date         | Changes                |
+| ------- | ------------ | ---------------------- |
+| 1.0.0   | [YYYY-MM-DD] | Initial implementation |

package/data/templates/DOC_EXTRACTION_CHECKLIST.md

@@ -0,0 +1,284 @@
+# Documentation Extraction Checklist
+
+**Project**: [Project Name]
+**Date**: [YYYY-MM-DD]
+**Extractor**: [Agent/Human]
+
+---
+
+## Instructions
+
+Use this checklist to systematically extract documentation from existing code and specifications. Mark each item as extracted (Y) or not found (N). Target completion: ~10 minutes for quick extraction.
+
+---
+
+## 1. API Endpoints (from routes/controllers)
+
+### Automated Extraction Commands
+
+```bash
+# Find all route definitions
+grep -rn "router\.\|app\.\(get\|post\|put\|patch\|delete\)" src/ --include="*.ts"
+
+# Find all controller methods
+grep -rn "@Get\|@Post\|@Put\|@Patch\|@Delete" src/ --include="*.ts"
+
+# Find OpenAPI decorators
+grep -rn "@Api\|@ApiOperation\|@ApiResponse" src/ --include="*.ts"
+```
+
+### Endpoints Found
+
+| Method | Path                   | Handler   | Auth          | Description |
+| ------ | ---------------------- | --------- | ------------- | ----------- |
+| GET    | /api/v1/[resource]     | [handler] | [ ] Y / [ ] N |             |
+| POST   | /api/v1/[resource]     | [handler] | [ ] Y / [ ] N |             |
+| PUT    | /api/v1/[resource]/:id | [handler] | [ ] Y / [ ] N |             |
+| DELETE | /api/v1/[resource]/:id | [handler] | [ ] Y / [ ] N |             |
+
+---
+
+## 2. Data Models (from schemas/models)
+
+### Automated Extraction Commands
+
+```bash
+# Find all interfaces/types
+grep -rn "^export interface\|^export type" src/ --include="*.ts"
+
+# Find Zod schemas
+grep -rn "z\.object\|z\.string\|z\.number" src/ --include="*.ts"
+
+# Find Prisma models
+grep -n "^model " prisma/schema.prisma
+
+# Find TypeORM entities
+grep -rn "@Entity\|@Column\|@PrimaryColumn" src/ --include="*.ts"
+```
+
+### Models Found
+
+| Model Name | File   | Type                   | Fields | Relationships |
+| ---------- | ------ | ---------------------- | ------ | ------------- |
+| [Model]    | [path] | interface/class/schema | [N]    | [relations]   |
+
+---
+
+## 3. Services (from services/)
+
+### Automated Extraction Commands
+
+```bash
+# Find all service classes
+grep -rn "^export class.*Service" src/ --include="*.ts"
+
+# Find service methods
+grep -rn "async.*(" src/services/ --include="*.ts"
+
+# Find dependency injections
+grep -rn "constructor(" src/services/ --include="*.ts"
+```
+
+### Services Found
+
+| Service       | File   | Methods     | Dependencies |
+| ------------- | ------ | ----------- | ------------ |
+| [ServiceName] | [path] | [N] methods | [deps]       |
+
+---
+
+## 4. Configuration (from config/)
+
+### Automated Extraction Commands
+
+```bash
+# Find environment variables
+grep -rn "process\.env\." src/ --include="*.ts"
+
+# Find config files
+ls -la src/config/ .env.example
+
+# Find Zod config schemas
+grep -rn "configSchema\|ConfigSchema" src/ --include="*.ts"
+```
+
+### Configuration Found
+
+| Variable   | Type                  | Default   | Required      | Description |
+| ---------- | --------------------- | --------- | ------------- | ----------- |
+| [VAR_NAME] | string/number/boolean | [default] | [ ] Y / [ ] N |             |
+
+---
+
+## 5. Error Handling (from errors/)
+
+### Automated Extraction Commands
+
+```bash
+# Find custom error classes
+grep -rn "extends Error\|extends BaseError" src/ --include="*.ts"
+
+# Find error codes
+grep -rn "ErrorCode\|ERROR_" src/ --include="*.ts"
+
+# Find error handlers
+grep -rn "errorHandler\|handleError" src/ --include="*.ts"
+```
+
+### Errors Found
+
+| Error Class  | HTTP Status | Code   | Description |
+| ------------ | ----------- | ------ | ----------- |
+| [ErrorClass] | [4xx/5xx]   | [CODE] |             |
+
+---
+
+## 6. Middleware (from middleware/)
+
+### Automated Extraction Commands
+
+```bash
+# Find middleware files
+ls -la src/middleware/
+
+# Find middleware functions
+grep -rn "export.*middleware\|export function.*req.*res.*next" src/ --include="*.ts"
+
+# Find applied middleware
+grep -rn "app\.use\|router\.use" src/ --include="*.ts"
+```
+
+### Middleware Found
+
+| Name             | File   | Purpose   | Applied To      |
+| ---------------- | ------ | --------- | --------------- |
+| [MiddlewareName] | [path] | [purpose] | [routes/global] |
+
+---
+
+## 7. Tests (from tests/)
+
+### Automated Extraction Commands
+
+```bash
+# Count test files
+find . -name "*.test.ts" -o -name "*.spec.ts" | wc -l
+
+# Find test suites
+grep -rn "describe\(" tests/ --include="*.ts"
+
+# Find test coverage
+cat coverage/coverage-summary.json 2>/dev/null || echo "Run pnpm test:coverage"
+```
+
+### Test Summary
+
+| Category    | Files | Tests | Coverage |
+| ----------- | ----- | ----- | -------- |
+| Unit        | [N]   | [N]   | [%]      |
+| Integration | [N]   | [N]   | [%]      |
+| E2E         | [N]   | [N]   | [%]      |
+
+---
+
+## 8. Dependencies (from package.json)
+
+### Automated Extraction Commands
+
+```bash
+# List production dependencies
+cat package.json | jq '.dependencies'
+
+# List dev dependencies
+cat package.json | jq '.devDependencies'
+
+# Check for outdated
+pnpm outdated
+```
+
+### Key Dependencies
+
+| Package   | Version | Purpose   | Category         |
+| --------- | ------- | --------- | ---------------- |
+| [package] | [x.x.x] | [purpose] | runtime/dev/test |
+
+---
+
+## 9. Infrastructure (from docker/k8s)
+
+### Automated Extraction Commands
+
+```bash
+# Find Dockerfiles
+find . -name "Dockerfile*"
+
+# Find docker-compose
+find . -name "docker-compose*.yml"
+
+# Find k8s manifests
+find . -name "*.yaml" -path "*/k8s/*"
+```
+
+### Infrastructure Found
+
+| Component   | File   | Type                   | Description |
+| ----------- | ------ | ---------------------- | ----------- |
+| [component] | [path] | Dockerfile/compose/k8s |             |
+
+---
+
+## 10. Scripts (from package.json)
+
+### Automated Extraction Commands
+
+```bash
+# List all scripts
+cat package.json | jq '.scripts'
+```
+
+### Scripts Found
+
+| Script  | Command   | Purpose              |
+| ------- | --------- | -------------------- |
+| `dev`   | [command] | Development server   |
+| `build` | [command] | Build for production |
+| `test`  | [command] | Run tests            |
+| `lint`  | [command] | Lint code            |
+
+---
+
+## Extraction Summary
+
+| Category          | Items Found | Status       |
+| ----------------- | ----------- | ------------ |
+| 1. API Endpoints  | [N]         | [ ] Complete |
+| 2. Data Models    | [N]         | [ ] Complete |
+| 3. Services       | [N]         | [ ] Complete |
+| 4. Configuration  | [N]         | [ ] Complete |
+| 5. Error Handling | [N]         | [ ] Complete |
+| 6. Middleware     | [N]         | [ ] Complete |
+| 7. Tests          | [N]         | [ ] Complete |
+| 8. Dependencies   | [N]         | [ ] Complete |
+| 9. Infrastructure | [N]         | [ ] Complete |
+| 10. Scripts       | [N]         | [ ] Complete |
+
+---
+
+## Generated Documentation Artifacts
+
+Based on extraction, generate:
+
+| Document        | Source Categories | Template              |
+| --------------- | ----------------- | --------------------- |
+| API.md          | 1, 4, 5, 6        | DOC_API_TEMPLATE.md   |
+| ARCHITECTURE.md | 2, 3, 6           | BACKEND_DOC.md        |
+| DATA.md         | 2                 | BACKEND_DOC.md        |
+| TESTING.md      | 7                 | BACKEND_DOC.md        |
+| DEPLOYMENT.md   | 9, 10             | INFRASTRUCTURE_DOC.md |
+
+---
+
+## Next Step
+
+- If extraction complete: Generate documentation using templates
+- If gaps found: Manual review of source code required

package/data/templates/FRONTEND_DOC.md

@@ -0,0 +1,253 @@
+# [Document Title]
+
+| Attribute        | Value                       |
+| ---------------- | --------------------------- |
+| **Purpose**      | [Brief purpose description] |
+| **Version**      | 1.0.0                       |
+| **Author**       | AI Documentation Generator  |
+| **Created**      | [YYYY-MM-DD]                |
+| **Last Updated** | [YYYY-MM-DD]                |
+| **Status**       | Draft                       |
+
+---
+
+## Overview
+
+[High-level overview of the document scope and content. Use British English for prose.]
+
+---
+
+## Component Architecture
+
+```mermaid
+flowchart TB
+    subgraph App["Application Root"]
+        Layout[Layout]
+        Router[Router]
+    end
+
+    subgraph Pages["Pages"]
+        Home[HomePage]
+        Dashboard[DashboardPage]
+        Settings[SettingsPage]
+    end
+
+    subgraph Components["Shared Components"]
+        Header[Header]
+        Sidebar[Sidebar]
+        Footer[Footer]
+    end
+
+    subgraph UI["UI Components"]
+        Button[Button]
+        Input[Input]
+        Modal[Modal]
+    end
+
+    App --> Layout
+    Layout --> Router
+    Layout --> Header
+    Layout --> Sidebar
+    Router --> Pages
+    Pages --> Components
+    Components --> UI
+```
+
+---
+
+## [Main Section 1]
+
+[Content for main section. Use British English for prose.]
+
+### [Subsection 1.1]
+
+[Detailed content with code examples using American English for code]
+
+```tsx
+// Example component implementation
+import { type FC, type PropsWithChildren } from 'react';
+import styles from './ExampleComponent.module.css';
+
+interface ExampleComponentProps {
+	/** Brief description of prop */
+	title: string;
+	/** Optional callback for action */
+	onAction?: () => void;
+}
+
+/**
+ * ExampleComponent - Brief component description
+ *
+ * @example
+ * <ExampleComponent title="Hello" onAction={() => console.log('clicked')} />
+ */
+export const ExampleComponent: FC<PropsWithChildren<ExampleComponentProps>> = ({ title, onAction, children }) => {
+	return (
+		<div className={styles.container}>
+			<h2 className={styles.title}>{title}</h2>
+			{children}
+			{onAction && (
+				<button onClick={onAction} className={styles.button}>
+					Action
+				</button>
+			)}
+		</div>
+	);
+};
+```
+
+### [Subsection 1.2]
+
+[Detailed content]
+
+---
+
+## Design Tokens
+
+### Colour Palette
+
+| Name          | Hex       | Usage                  |
+| ------------- | --------- | ---------------------- |
+| Primary       | `#3B82F6` | Primary actions, links |
+| Primary Dark  | `#2563EB` | Hover states           |
+| Primary Light | `#60A5FA` | Backgrounds            |
+| Success       | `#10B981` | Success states         |
+| Warning       | `#F59E0B` | Warnings               |
+| Error         | `#EF4444` | Errors                 |
+
+### Typography
+
+| Name    | Size     | Weight | Usage               |
+| ------- | -------- | ------ | ------------------- |
+| `h1`    | 2.25rem  | 700    | Page titles         |
+| `h2`    | 1.875rem | 600    | Section headings    |
+| `h3`    | 1.5rem   | 600    | Subsection headings |
+| `body`  | 1rem     | 400    | Body text           |
+| `small` | 0.875rem | 400    | Captions            |
+
+### Spacing
+
+| Token | Value   | Usage            |
+| ----- | ------- | ---------------- |
+| `xs`  | 0.25rem | Minimal spacing  |
+| `sm`  | 0.5rem  | Tight spacing    |
+| `md`  | 1rem    | Default spacing  |
+| `lg`  | 1.5rem  | Generous spacing |
+| `xl`  | 2rem    | Section spacing  |
+
+---
+
+## Component Library
+
+### Button
+
+**Description**: Primary interaction element for user actions.
+
+**Variants**:
+
+| Variant       | Usage               |
+| ------------- | ------------------- |
+| `primary`     | Primary actions     |
+| `secondary`   | Secondary actions   |
+| `outline`     | Tertiary actions    |
+| `ghost`       | Minimal emphasis    |
+| `destructive` | Destructive actions |
+
+**Props**:
+
+| Prop       | Type                   | Default     | Description    |
+| ---------- | ---------------------- | ----------- | -------------- |
+| `variant`  | `string`               | `'primary'` | Button style   |
+| `size`     | `'sm' \| 'md' \| 'lg'` | `'md'`      | Button size    |
+| `disabled` | `boolean`              | `false`     | Disabled state |
+| `loading`  | `boolean`              | `false`     | Loading state  |
+
+**Accessibility**:
+
+- Must have accessible label
+- Focus state visible
+- Minimum touch target 44x44px
+
+---
+
+## State Management
+
+```mermaid
+flowchart LR
+    Component -->|dispatch| Action
+    Action -->|update| Store
+    Store -->|select| Selector
+    Selector -->|render| Component
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue                   | Symptoms                 | Resolution                                |
+| ----------------------- | ------------------------ | ----------------------------------------- |
+| Component not rendering | Blank area in UI         | Check React DevTools for errors           |
+| State not updating      | UI shows stale data      | Verify state mutations, check selectors   |
+| Styling issues          | Incorrect layout/colours | Check CSS specificity, verify class names |
+
+### Diagnostic Steps
+
+1. Open browser DevTools Console
+2. Check React DevTools for component tree
+3. Verify Network tab for API failures
+4. Check Redux DevTools for state changes (if applicable)
+
+### Escalation Path
+
+1. Check browser console for errors
+2. Verify component props
+3. Check API responses in Network tab
+4. Contact frontend team if issue persists
+
+---
+
+## Best Practices
+
+### Do
+
+- Use TypeScript for type safety
+- Implement proper error boundaries
+- Follow component composition patterns
+- Write accessible components (ARIA, keyboard nav)
+- Use semantic HTML elements
+
+### Don't
+
+- Use `any` type in TypeScript
+- Mutate state directly
+- Ignore accessibility requirements
+- Create deeply nested component hierarchies
+- Skip loading and error states
+
+### Checklist
+
+- [ ] Component has TypeScript types
+- [ ] Accessibility tested (keyboard, screen reader)
+- [ ] Responsive design verified
+- [ ] Loading states implemented
+- [ ] Error boundaries in place
+
+---
+
+## Related Documentation
+
+| Document                            | Relationship | Description      |
+| ----------------------------------- | ------------ | ---------------- |
+| [DESIGN.md](./DESIGN.md)            | Related      | Design system    |
+| [TESTING.md](./TESTING.md)          | Related      | Testing strategy |
+| [Backend API.md](../backend/API.md) | See Also     | API integration  |
+
+---
+
+## Changelog
+
+| Version | Date         | Author                     | Changes               |
+| ------- | ------------ | -------------------------- | --------------------- |
+| 1.0.0   | [YYYY-MM-DD] | AI Documentation Generator | Initial documentation |