ai-spector 0.9.21 → 0.9.24

package/contracts/bootstrap/scripts/migrate-entity-registry.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Migrate legacy path-keyed docops artifacts to entity registry (ID-keyed).
+# Run from repository root. Requires Node.js (npx ai-spector).
+#
+# Usage:
+#   migrate-entity-registry.sh [--dry-run] [--skip-screen-map] [--skip-comments] [--skip-review]
+#
+set -euo pipefail
+
+DRY_RUN=""
+SKIP_SCREEN_MAP=""
+SKIP_COMMENTS=""
+SKIP_REVIEW=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN="--dry-run" ;;
+    --skip-screen-map) SKIP_SCREEN_MAP="--skip-screen-map" ;;
+    --skip-comments) SKIP_COMMENTS=1 ;;
+    --skip-review) SKIP_REVIEW=1 ;;
+    -h|--help)
+      sed -n '2,8p' "$0"
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $arg" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if ! command -v npx >/dev/null 2>&1; then
+  echo "npx is required (Node.js)." >&2
+  exit 1
+fi
+
+if [[ ! -f .docops/docops.config.json ]]; then
+  echo "Missing .docops/docops.config.json — complete contract migration first (see MIGRATION.md)." >&2
+  exit 1
+fi
+
+echo "==> docops registry sync"
+npx ai-spector docops registry sync $DRY_RUN $SKIP_SCREEN_MAP
+
+if [[ -z "${SKIP_COMMENTS}" ]]; then
+  echo "==> docops comments migrate"
+  npx ai-spector docops comments migrate $DRY_RUN
+fi
+
+if [[ -z "${SKIP_REVIEW}" ]]; then
+  echo "==> docops review-registry migrate"
+  npx ai-spector docops review-registry migrate $DRY_RUN
+fi
+
+echo "Done. See ENTITY_REGISTRY_MIGRATION.md for verification steps."

package/contracts/bootstrap/templates/basic-design/db-design-template.md

@@ -0,0 +1,177 @@
+# Database Design: <Project Name>
+
+> This document explains the database structure and purpose of each table, helping developers, QA, and DBAs understand data relationships and design rationale.
+
+**Source Requirements:** SRS Section 5 (Data Requirements)
+
+---
+
+## 1. Overview
+
+**Database Management System:** <PostgreSQL/MySQL/Other>
+
+**Purpose:**
+> Describe the main purpose of the database and what business flows it supports.
+
+**Source Requirements:**
+> Reference SRS sections that informed this design.
+- SRS Section 4: <Functional Requirements>
+- SRS Section 5: <Data Requirements>
+- SRS Section 7: <Quality Attributes>
+
+---
+
+## 2. Entity-Relationship Diagram
+
+> Provide a visual representation of tables and their relationships.
+
+```mermaid
+erDiagram
+    ENTITY1 ||--o{ ENTITY2 : "relationship"
+    ENTITY1 {
+        int id PK
+        string name
+        datetime created_at
+    }
+    ENTITY2 {
+        int id PK
+        int entity1_id FK
+        string description
+    }
+```
+
+---
+
+## 3. Table List and Roles
+
+| Table Name | Purpose | Main Relationships |
+|------------|---------|-------------------|
+| `<table_name>` | <Purpose description> | <Relationship description> |
+| `<table_name>` | <Purpose description> | <Relationship description> |
+
+---
+
+## 4. Detailed Table Descriptions
+
+### 4.1 `<table_name>`
+
+**Purpose:**
+> Describe what this table stores and its role in the system.
+
+**Primary Key:** `<field_name>` (<data_type>)
+
+**Key Fields:**
+
+| Field Name | Data Type | Constraints | Description |
+|------------|-----------|-------------|-------------|
+| `<field_name>` | `<type>` | `<UNIQUE/NOT NULL/CHECK>` | <Description> |
+| `<field_name>` | `<type>` | `<constraints>` | <Description> |
+
+**Important Design Decisions:**
+- <Decision 1 and rationale>
+- <Decision 2 and rationale>
+
+**Foreign Keys:**
+- `<field_name>` → `<referenced_table>.<referenced_field>` (<relationship description>)
+
+**Indexes:**
+- `<index_name>` on `<field_name>` (<purpose>)
+
+**Business Rules:**
+- <Business rule 1>
+- <Business rule 2>
+
+---
+
+### 4.2 `<table_name>`
+
+**Purpose:**
+> Describe what this table stores.
+
+**Primary Key:** `<field_name>` (<data_type>)
+
+**Key Fields:**
+
+| Field Name | Data Type | Constraints | Description |
+|------------|-----------|-------------|-------------|
+| `<field_name>` | `<type>` | `<constraints>` | <Description> |
+
+**Foreign Keys:**
+- `<field_name>` → `<referenced_table>.<referenced_field>`
+
+**Indexes:**
+- `<index_name>` on `<field_name>`
+
+---
+
+## 5. Relationships Summary
+
+> Document all relationships between tables.
+
+| From Table | Relationship Type | To Table | Description |
+|------------|-------------------|----------|-------------|
+| `<table1>` | One-to-Many | `<table2>` | <Description> |
+| `<table1>` | Many-to-Many | `<table2>` | <Description> |
+
+---
+
+## 6. Data Integrity Rules
+
+**Constraints:**
+- <Constraint 1>
+- <Constraint 2>
+
+**Validation Rules:**
+- <Validation rule 1>
+- <Validation rule 2>
+
+**Referential Integrity:**
+- <Cascade/restrict/set null behavior>
+
+---
+
+## 7. Performance Considerations
+
+**Indexes:**
+> List indexes for query optimization.
+
+| Index Name | Table | Fields | Purpose |
+|------------|-------|--------|---------|
+| `<index_name>` | `<table>` | `<fields>` | <Purpose> |
+
+**Query Optimization Notes:**
+- <Note 1>
+- <Note 2>
+
+---
+
+## 8. Security Considerations
+
+**Access Control:**
+- <Access control requirement 1>
+- <Access control requirement 2>
+
+**Data Protection:**
+- <Protection measure 1>
+- <Protection measure 2>
+
+---
+
+## 9. Future Extensions
+
+> Document potential future enhancements or changes.
+
+- <Extension 1>
+- <Extension 2>
+
+---
+
+## 10. Notes
+
+**Migration Strategy:**
+> Reference migration tool or approach (e.g., Flyway, Liquibase).
+
+**Testing Considerations:**
+- <Testing note 1>
+- <Testing note 2>
+

package/contracts/bootstrap/templates/basic-design/detail-api-template.md

@@ -0,0 +1,278 @@
+# API Detail: <METHOD /path>
+
+> **One endpoint per file** under `docs/basic-design/api/<slug>.md` (slug from method + path, e.g. `post-checkout.md`). For the endpoint list and overview, see `docs/basic-design/api-list.md`.
+
+**Source Requirements:** SRS Section 4 (System Features), Section 6.2 (Software Interfaces)
+
+---
+
+## 1. Detailed Endpoint Specifications
+
+### 1.1 `POST /resource`
+
+**Summary:** <Brief description>
+
+**Operation ID:** `createResource`
+
+**Source Requirement:** SRS Section <X.X> - <Feature Name>
+
+**Authentication:** Required
+
+**Request:**
+
+**Headers:**
+```
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Body Schema:**
+```json
+{
+  "field1": "<type>",
+  "field2": "<type>",
+  "field3": "<type>"
+}
+```
+
+**Field Descriptions:**
+
+| Field | Type | Required | Validation | Description |
+|-------|------|----------|------------|-------------|
+| `field1` | `<type>` | Yes | <Validation rules> | <Description> |
+| `field2` | `<type>` | No | <Validation rules> | <Description> |
+
+**Example Request:**
+```json
+{
+  "field1": "value1",
+  "field2": "value2"
+}
+```
+
+**Responses:**
+
+**201 Created:**
+```json
+{
+  "id": 123,
+  "status": "success",
+  "message": "<Message>"
+}
+```
+
+**400 Bad Request:**
+```json
+{
+  "error": "validation_error",
+  "message": "<Error message>",
+  "details": [
+    {
+      "field": "field1",
+      "message": "<Field-specific error>"
+    }
+  ]
+}
+```
+
+**401 Unauthorized:**
+```json
+{
+  "error": "unauthorized",
+  "message": "Authentication required"
+}
+```
+
+**500 Internal Server Error:**
+```json
+{
+  "error": "internal_error",
+  "message": "<Error message>"
+}
+```
+
+---
+
+### 1.2 `GET /resource/{id}`
+
+**Summary:** <Brief description>
+
+**Operation ID:** `getResource`
+
+**Source Requirement:** SRS Section <X.X>
+
+**Authentication:** Required
+
+**Path Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | integer | Yes | Resource identifier |
+
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `include` | string | No | Related resources to include |
+| `fields` | string | No | Fields to return |
+
+**Responses:**
+
+**200 OK:**
+```json
+{
+  "id": 123,
+  "field1": "value1",
+  "field2": "value2",
+  "created_at": "2025-01-01T00:00:00Z"
+}
+```
+
+**404 Not Found:**
+```json
+{
+  "error": "not_found",
+  "message": "Resource not found"
+}
+```
+
+---
+
+### 1.3 `PUT /resource/{id}`
+
+**Summary:** <Brief description>
+
+**Operation ID:** `updateResource`
+
+**Authentication:** Required
+
+**Path Parameters:**
+- `id`: Resource identifier
+
+**Request Body:**
+> Similar structure to POST
+
+**Responses:**
+> Similar structure to GET/POST
+
+---
+
+### 1.4 `DELETE /resource/{id}`
+
+**Summary:** <Brief description>
+
+**Operation ID:** `deleteResource`
+
+**Authentication:** Required
+
+**Path Parameters:**
+- `id`: Resource identifier
+
+**Responses:**
+
+**204 No Content:**
+> Success response with no body
+
+**404 Not Found:**
+> Error response
+
+---
+
+## 2. Data Models
+
+### 2.1 Resource Model
+
+**Description:** <Description of the data model>
+
+**Schema:**
+```json
+{
+  "id": "integer",
+  "field1": "string",
+  "field2": "integer",
+  "created_at": "datetime",
+  "updated_at": "datetime"
+}
+```
+
+**Field Details:**
+
+| Field | Type | Description | Constraints |
+|-------|------|-------------|-------------|
+| `id` | integer | Unique identifier | Auto-generated |
+| `field1` | string | <Description> | Max 255 chars |
+| `field2` | integer | <Description> | Min 0, Max 100 |
+
+---
+
+## 3. Error Handling
+
+**Standard Error Response Format:**
+```json
+{
+  "error": "<error_code>",
+  "message": "<Human-readable message>",
+  "details": {
+    "<additional_info>": "<value>"
+  }
+}
+```
+
+**Error Codes:**
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `validation_error` | 400 | Request validation failed |
+| `unauthorized` | 401 | Authentication required |
+| `forbidden` | 403 | Insufficient permissions |
+| `not_found` | 404 | Resource not found |
+| `conflict` | 409 | Resource conflict |
+| `internal_error` | 500 | Server error |
+
+---
+
+## 4. Rate Limiting
+
+**Limits:**
+- <Limit description>
+
+**Headers:**
+```
+X-RateLimit-Limit: <number>
+X-RateLimit-Remaining: <number>
+X-RateLimit-Reset: <timestamp>
+```
+
+**Response when limit exceeded:**
+```json
+{
+  "error": "rate_limit_exceeded",
+  "message": "Too many requests",
+  "retry_after": 60
+}
+```
+
+---
+
+## 5. Webhooks (if applicable)
+
+**Events:**
+- `<event_name>`: <Description>
+
+**Payload Format:**
+```json
+{
+  "event": "<event_name>",
+  "timestamp": "<ISO 8601>",
+  "data": {
+    "<resource_data>": "..."
+  }
+}
+```
+
+---
+
+## 6. Future Enhancements
+
+- <Enhancement 1>
+- <Enhancement 2>