@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/code-documenter/steering/api-docs-fastapi-django.md

@@ -0,0 +1,169 @@
+# API Documentation: FastAPI & Django
+
+> Reference for: Code Documenter
+> Load when: Documenting Python API frameworks
+
+## FastAPI (Auto-generates from types)
+
+FastAPI automatically generates OpenAPI documentation from type hints and docstrings.
+
+### Endpoint Documentation
+
+```python
+from fastapi import FastAPI, HTTPException, status
+from pydantic import BaseModel, Field
+
+class UserCreate(BaseModel):
+    """User creation request body."""
+
+    name: str = Field(..., min_length=1, max_length=100, example="John Doe")
+    email: str = Field(..., example="john@example.com")
+
+class UserResponse(BaseModel):
+    """User response with generated ID."""
+
+    id: int = Field(..., example=1)
+    name: str
+    email: str
+
+@app.post(
+    "/users",
+    response_model=UserResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new user",
+    tags=["Users"],
+)
+async def create_user(user: UserCreate) -> UserResponse:
+    """Create a new user account.
+
+    Args:
+        user: User creation data including name and email.
+
+    Returns:
+        Created user with generated ID.
+
+    Raises:
+        HTTPException: 400 if email already exists.
+    """
+```
+
+### Router with Tags
+
+```python
+from fastapi import APIRouter
+
+router = APIRouter(
+    prefix="/users",
+    tags=["Users"],
+    responses={404: {"description": "Not found"}},
+)
+
+@router.get(
+    "/{user_id}",
+    response_model=UserResponse,
+    summary="Get user by ID",
+)
+async def get_user(user_id: int) -> UserResponse:
+    """Retrieve a user by their unique identifier."""
+```
+
+## Django REST Framework (drf-spectacular)
+
+### ViewSet Documentation
+
+```python
+from rest_framework import viewsets, status
+from rest_framework.decorators import action
+from drf_spectacular.utils import extend_schema, OpenApiParameter
+
+class UserViewSet(viewsets.ModelViewSet):
+    """
+    ViewSet for managing user accounts.
+
+    list: Get all users with pagination.
+    create: Create a new user account.
+    retrieve: Get a specific user by ID.
+    update: Update all user fields.
+    partial_update: Update specific user fields.
+    destroy: Delete a user account.
+    """
+
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
+
+    @extend_schema(
+        summary="Get current user",
+        description="Returns the authenticated user's profile",
+        responses={200: UserSerializer},
+    )
+    @action(detail=False, methods=["get"])
+    def me(self, request):
+        """Get the authenticated user's profile."""
+        serializer = self.get_serializer(request.user)
+        return Response(serializer.data)
+```
+
+### Serializer Documentation
+
+```python
+from rest_framework import serializers
+
+class UserSerializer(serializers.ModelSerializer):
+    """Serializer for user model with validation."""
+
+    class Meta:
+        model = User
+        fields = ["id", "name", "email", "created_at"]
+        read_only_fields = ["id", "created_at"]
+
+    name = serializers.CharField(
+        help_text="User's display name",
+        max_length=100,
+    )
+    email = serializers.EmailField(
+        help_text="User's email address (unique)",
+    )
+```
+
+### Custom Schema
+
+```python
+from drf_spectacular.utils import extend_schema, OpenApiExample
+
+@extend_schema(
+    request=UserCreateSerializer,
+    responses={
+        201: UserSerializer,
+        400: OpenApiTypes.OBJECT,
+    },
+    examples=[
+        OpenApiExample(
+            "Valid request",
+            value={"name": "John", "email": "john@example.com"},
+        ),
+    ],
+)
+def create(self, request):
+    """Create a new user."""
+```
+
+## Quick Reference
+
+| Framework | Documentation Source | Output |
+|-----------|---------------------|--------|
+| FastAPI | Type hints + docstrings | Auto Swagger UI |
+| DRF | Serializers + drf-spectacular | Auto Swagger UI |
+
+| FastAPI Decorator | Purpose |
+|-------------------|---------|
+| `summary` | Short endpoint description |
+| `description` | Detailed description |
+| `tags` | Group endpoints |
+| `response_model` | Response schema |
+| `responses` | Additional response codes |
+
+| DRF Decorator | Purpose |
+|---------------|---------|
+| `@extend_schema` | Customize schema |
+| `OpenApiParameter` | Query/path params |
+| `OpenApiExample` | Request examples |

package/Ai Agent Workflow/powers/code-documenter/steering/api-docs-nestjs-express.md

@@ -0,0 +1,223 @@
+# API Documentation: NestJS & Express
+
+> Reference for: Code Documenter
+> Load when: Documenting Node.js API frameworks
+
+## NestJS (@nestjs/swagger)
+
+NestJS requires explicit decorators for OpenAPI documentation.
+
+### Controller Documentation
+
+```typescript
+import { Controller, Post, Body, Get, Param } from '@nestjs/common';
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiParam,
+  ApiBearerAuth,
+} from '@nestjs/swagger';
+
+@ApiTags('Users')
+@ApiBearerAuth()
+@Controller('users')
+export class UsersController {
+  @Post()
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiResponse({
+    status: 201,
+    description: 'User created successfully',
+    type: UserDto,
+  })
+  @ApiResponse({
+    status: 400,
+    description: 'Invalid input data',
+  })
+  async create(@Body() dto: CreateUserDto): Promise<UserDto> {
+    return this.usersService.create(dto);
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get user by ID' })
+  @ApiParam({
+    name: 'id',
+    description: 'User unique identifier',
+    example: '123',
+  })
+  @ApiResponse({ status: 200, type: UserDto })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  async findOne(@Param('id') id: string): Promise<UserDto> {
+    return this.usersService.findOne(id);
+  }
+}
+```
+
+### DTO Documentation
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEmail, IsString, MinLength } from 'class-validator';
+
+export class CreateUserDto {
+  @ApiProperty({
+    description: "User's display name",
+    example: 'John Doe',
+    minLength: 1,
+    maxLength: 100,
+  })
+  @IsString()
+  @MinLength(1)
+  name: string;
+
+  @ApiProperty({
+    description: "User's email address",
+    example: 'john@example.com',
+  })
+  @IsEmail()
+  email: string;
+
+  @ApiPropertyOptional({
+    description: 'Profile picture URL',
+    example: 'https://example.com/avatar.jpg',
+  })
+  avatarUrl?: string;
+}
+```
+
+## Express (swagger-jsdoc)
+
+Express uses JSDoc comments with swagger annotations.
+
+### Setup
+
+```javascript
+const swaggerJsdoc = require('swagger-jsdoc');
+const swaggerUi = require('swagger-ui-express');
+
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'API Documentation',
+      version: '1.0.0',
+    },
+  },
+  apis: ['./routes/*.js'],
+};
+
+const specs = swaggerJsdoc(options);
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
+```
+
+### Route Documentation
+
+```javascript
+/**
+ * @swagger
+ * /users:
+ *   post:
+ *     summary: Create a new user
+ *     tags: [Users]
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/CreateUser'
+ *     responses:
+ *       201:
+ *         description: User created successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/User'
+ *       400:
+ *         description: Invalid input
+ */
+router.post('/users', createUser);
+
+/**
+ * @swagger
+ * /users/{id}:
+ *   get:
+ *     summary: Get user by ID
+ *     tags: [Users]
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: User ID
+ *     responses:
+ *       200:
+ *         description: User found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/User'
+ *       404:
+ *         description: User not found
+ */
+router.get('/users/:id', getUser);
+```
+
+### Schema Documentation
+
+```javascript
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     CreateUser:
+ *       type: object
+ *       required:
+ *         - name
+ *         - email
+ *       properties:
+ *         name:
+ *           type: string
+ *           description: User's display name
+ *           example: John Doe
+ *         email:
+ *           type: string
+ *           format: email
+ *           description: User's email address
+ *           example: john@example.com
+ *     User:
+ *       allOf:
+ *         - $ref: '#/components/schemas/CreateUser'
+ *         - type: object
+ *           properties:
+ *             id:
+ *               type: string
+ *               description: Unique identifier
+ *             createdAt:
+ *               type: string
+ *               format: date-time
+ */
+```
+
+## Quick Reference
+
+| NestJS Decorator | Purpose |
+|------------------|---------|
+| `@ApiTags()` | Group endpoints |
+| `@ApiOperation()` | Endpoint summary |
+| `@ApiResponse()` | Response documentation |
+| `@ApiParam()` | Path parameter |
+| `@ApiQuery()` | Query parameter |
+| `@ApiBody()` | Request body |
+| `@ApiBearerAuth()` | Auth requirement |
+| `@ApiProperty()` | DTO property |
+
+| Express swagger-jsdoc | Purpose |
+|-----------------------|---------|
+| `@swagger` | Start swagger block |
+| `tags` | Group endpoints |
+| `summary` | Short description |
+| `parameters` | Path/query params |
+| `requestBody` | Request body schema |
+| `responses` | Response schemas |
+| `$ref` | Reference schema |

package/Ai Agent Workflow/powers/code-documenter/steering/coverage-reports.md

@@ -0,0 +1,128 @@
+# Coverage Reports
+
+> Reference for: Code Documenter
+> Load when: Generating documentation reports
+
+## Documentation Coverage Report Template
+
+```markdown
+# Documentation Report: {project_name}
+
+## Summary
+- **Files analyzed**: 45
+- **Functions documented**: 120/150 (80%)
+- **Classes documented**: 25/25 (100%)
+- **API endpoints documented**: 30/30 (100%)
+
+## Coverage Before/After
+- Before: 45%
+- After: 92%
+
+## Files Modified
+
+| File | Functions Added | Notes |
+|------|-----------------|-------|
+| src/services/user.ts | 8 | All public methods |
+| src/services/auth.ts | 5 | Added examples |
+| src/controllers/users.ts | 6 | Added @Api decorators |
+| src/dto/user.dto.ts | 4 | Added @ApiProperty |
+
+## API Documentation
+
+- **Framework**: NestJS
+- **Strategy**: @nestjs/swagger decorators
+- **Swagger UI**: /api/docs
+- **OpenAPI spec**: /api-json
+
+## Documentation Style
+
+- **Python**: Google style docstrings
+- **TypeScript**: JSDoc with @param, @returns
+- **API**: OpenAPI 3.0 via decorators
+
+## Next Steps
+
+### Recommendations
+1. Run `npm run docs:lint` to validate JSDoc
+2. Add `eslint-plugin-jsdoc` to enforce documentation
+3. Consider adding examples for complex functions
+4. Set up documentation CI checks
+
+### Missing Documentation
+| File | Missing | Priority |
+|------|---------|----------|
+| src/utils/crypto.ts | 3 functions | High |
+| src/helpers/date.ts | 2 functions | Medium |
+
+### CI Integration
+```yaml
+# Add to CI pipeline
+- name: Check documentation
+  run: npm run docs:check
+
+- name: Generate API docs
+  run: npm run docs:generate
+```
+```
+
+## Checklist During Documentation
+
+```markdown
+## Documentation Checklist
+
+### Before Starting
+- [ ] Confirmed format preference (Google/JSDoc/etc.)
+- [ ] Identified files to exclude (tests, generated)
+- [ ] Detected framework for API docs
+
+### Functions/Methods
+- [ ] All public functions documented
+- [ ] Parameters described with types
+- [ ] Return values documented
+- [ ] Exceptions/errors documented
+- [ ] Examples added for complex functions
+
+### Classes
+- [ ] Class purpose described
+- [ ] Constructor parameters documented
+- [ ] Public methods documented
+- [ ] Important attributes explained
+
+### API Endpoints
+- [ ] All endpoints have summaries
+- [ ] Request bodies documented
+- [ ] Response schemas defined
+- [ ] Error responses documented
+- [ ] Authentication requirements noted
+
+### Final Checks
+- [ ] Ran documentation linter
+- [ ] Verified Swagger UI renders correctly
+- [ ] No inaccurate documentation
+- [ ] Coverage report generated
+```
+
+## Framework-Specific Linting
+
+```bash
+# JavaScript/TypeScript - ESLint
+npm install eslint-plugin-jsdoc --save-dev
+# Add to .eslintrc: "plugins": ["jsdoc"]
+
+# Python - pydocstyle
+pip install pydocstyle
+pydocstyle --convention=google src/
+
+# Python - interrogate (coverage)
+pip install interrogate
+interrogate -v src/
+```
+
+## Quick Reference
+
+| Metric | Good | Acceptable | Poor |
+|--------|------|------------|------|
+| Function coverage | >90% | 70-90% | <70% |
+| Class coverage | 100% | >90% | <90% |
+| API endpoint coverage | 100% | 100% | <100% |
+| Example coverage | >50% | 30-50% | <30% |