speckeeper 0.9.2 → 0.9.4

package/docs/design/cli-commands.md

@@ -0,0 +1,332 @@
+# CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| build | Generate human-readable (docs/) and machine-readable (specs/) artifacts from TS models |
+| lint | Validate TS model consistency and integrity |
+| drift | Detect differences between generated docs/specs/ and committed files |
+| check | Check consistency with external SSOT (OpenAPI/DDL/IaC) |
+| init | Initialize a new speckeeper project with starter templates |
+| new | Create a new element with auto-generated ID |
+| scaffold | Generate _models/ from a mermaid flowchart definition |
+| impact | Analyze the change impact scope of a specified ID |
+
+---
+
+## CMD-BUILD: build
+
+Generate human-readable (docs/) and machine-readable (specs/) artifacts from TS models
+
+### Usage
+
+```bash
+speckeeper build [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| -c, --config | option | path |  | - | Path to config file |
+| -o, --output | option | path |  | . | Output directory base path |
+| -f, --format | option | enum |  | both | Output format |
+| -w, --watch | option | boolean |  | false | Watch file changes and auto-regenerate |
+| -v, --verbose | option | boolean |  | false | Show detailed output |
+
+### Examples
+
+```bash
+speckeeper build
+speckeeper build --output ./dist
+speckeeper build --format markdown
+speckeeper build --watch
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Success |
+| 1 | Generation error |
+
+---
+
+## CMD-LINT: lint
+
+Validate TS model consistency and integrity
+
+### Usage
+
+```bash
+speckeeper lint [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| -c, --config | option | path |  | - | Path to config file |
+| -p, --phase | option | enum |  | - | Phase gate (prohibit TBD at specified phase) |
+| -s, --strict | option | boolean |  | false | Strict mode (treat warnings as errors) |
+| --fix | option | boolean |  | false | Fix auto-fixable issues |
+| -f, --format | option | enum |  | text | Output format |
+
+### Examples
+
+```bash
+speckeeper lint
+speckeeper lint --phase LLD
+speckeeper lint --strict
+speckeeper lint --format json
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | No issues |
+| 1 | Errors found |
+| 2 | Warnings found (in strict mode) |
+
+---
+
+## CMD-DRIFT: drift
+
+Detect differences between generated docs/specs/ and committed files
+
+### Usage
+
+```bash
+speckeeper drift [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| -c, --config | option | path |  | - | Path to config file |
+| -u, --update | option | boolean |  | false | Auto-update if differences exist |
+| -f, --format | option | enum |  | text | Output format |
+
+### Examples
+
+```bash
+speckeeper drift
+speckeeper drift --update
+speckeeper drift --format diff
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | No differences |
+| 1 | Differences found (manual edits detected) |
+
+---
+
+## CMD-CHECK: check
+
+Check consistency with external SSOT (OpenAPI/DDL/IaC)
+
+### Usage
+
+```bash
+speckeeper check <subcommand> [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| <type> | argument | string |  | - | Type of check: external-ssot, openapi, ddl, iac, custom, all, test |
+| -c, --config | option | path |  | - | Path to config file |
+| --strict | option | boolean |  | false | Treat warnings as errors |
+| -v, --verbose | option | boolean |  | false | Show detailed output |
+| --coverage | option | boolean |  | false | Check if all testable acceptance criteria are covered by TestRefs |
+
+### Subcommands
+
+#### openapi
+
+Check consistency with OpenAPI specification
+
+#### ddl
+
+Check consistency with DDL/Schema
+
+#### iac
+
+Check consistency with IaC (CloudFormation/Terraform)
+
+#### external-ssot
+
+Check consistency with all external SSOTs
+
+#### test
+
+Check consistency between test files and requirements
+
+#### contract
+
+Check consistency between implementation and contract (type definitions/schema)
+
+### Examples
+
+```bash
+speckeeper check openapi
+speckeeper check ddl
+speckeeper check iac
+speckeeper check external-ssot
+speckeeper check contract
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Consistency OK |
+| 1 | Consistency error |
+| 2 | External SSOT file not found |
+
+---
+
+## CMD-INIT: init
+
+Initialize a new speckeeper project with starter templates
+
+### Usage
+
+```bash
+speckeeper init [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| -f, --force | option | boolean |  | false | Overwrite existing files |
+
+### Examples
+
+```bash
+speckeeper init
+speckeeper init --force
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Initialization successful |
+| 1 | Initialization error |
+
+---
+
+## CMD-NEW: new
+
+Create a new element with auto-generated ID
+
+### Usage
+
+```bash
+speckeeper new [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| <type> | argument | string | ✓ | - | Type: requirement, usecase, entity, component, screen, flow, error-case, term |
+| -k, --kind | option | string |  | - | Sub-kind (e.g., functional, non-functional for requirements) |
+| -n, --name | option | string |  | - | Name of the element |
+| -o, --output | option | path |  | - | Output directory path |
+| -t, --template | option | path |  | - | Path to template file |
+
+### Examples
+
+```bash
+speckeeper new requirement --kind functional --name "User Login"
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Element created |
+| 1 | Creation error |
+
+---
+
+## CMD-SCAFFOLD: scaffold
+
+Generate _models/ from a mermaid flowchart definition
+
+### Usage
+
+```bash
+speckeeper scaffold [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| -s, --source | option | path | ✓ | - | Path to Markdown file containing mermaid flowchart |
+| -o, --output | option | path |  | design/ | Output directory |
+| -f, --force | option | boolean |  | false | Overwrite existing files |
+| --dry-run | option | boolean |  | false | Preview generated files without writing |
+
+### Examples
+
+```bash
+speckeeper scaffold --source requirements.md
+speckeeper scaffold -s spec.md --dry-run
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Scaffold successful |
+| 1 | Scaffold error |
+
+---
+
+## CMD-IMPACT: impact
+
+Analyze the change impact scope of a specified ID
+
+### Usage
+
+```bash
+speckeeper impact [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| <id> | argument | string | ✓ | - | ID to analyze |
+| -c, --config | option | path |  | - | Path to config file |
+| -d, --depth | option | number |  | 3 | Analysis depth (reference tracking level) |
+| --direction | option | enum |  | both | Analysis direction |
+| -f, --format | option | enum |  | text | Output format |
+
+### Examples
+
+```bash
+speckeeper impact REQ-001
+speckeeper impact ENT-ORDER --depth 5
+speckeeper impact COMP-API --direction downstream
+speckeeper impact UC-001 --format mermaid
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Analysis successful |
+| 1 | Target ID not found |
+
+---

package/docs/design/constraints.md

@@ -0,0 +1,66 @@
+# Requirements
+
+## Constraints
+
+| ID | Name | Priority | Category |
+|----|------|----------|----------|
+| CR-001 | Minimize External Dependencies | should | technical |
+| CR-002 | Zero-config Startup | should | usability |
+| CR-003 | No Implementation Code Generation | must | scope |
+| CR-004 | Respect External SSOT | must | scope |
+
+---
+
+## CR-001: Minimize External Dependencies
+
+**Type**: constraint | **Priority**: should | **Category**: technical
+
+Limit external dependencies to stable libraries like Zod, Commander, Chalk
+
+### Acceptance Criteria
+
+- **CR-001-01**: Keep dependency package count under 20 [inspection]
+- **CR-001-02**: Use only packages with stable major versions [review]
+
+---
+
+## CR-002: Zero-config Startup
+
+**Type**: constraint | **Priority**: should | **Category**: usability
+
+Basic functionality works without config file
+
+### Acceptance Criteria
+
+- **CR-002-01**: build/lint/drift works without speckeeper.config.ts [test]
+- **CR-002-02**: Default settings cover typical use cases [review]
+
+---
+
+## CR-003: No Implementation Code Generation
+
+**Type**: constraint | **Priority**: must | **Category**: scope
+
+speckeeper does not generate implementation code. API contracts and DB connection code are handled by external tools
+
+### Acceptance Criteria
+
+- **CR-003-01**: speckeeper does not generate or modify code under src/ [review]
+- **CR-003-02**: API contracts (TypeScript types, routes, clients) generated by external tools from OpenAPI [review]
+- **CR-003-03**: DB connections (Entity types, repositories) generated by ORM/DDL tools from DDL/schema [review]
+- **CR-003-04**: speckeeper only handles requirement definition and external SSOT consistency checks [review]
+
+---
+
+## CR-004: Respect External SSOT
+
+**Type**: constraint | **Priority**: must | **Category**: scope
+
+Treat API specs, DB definitions, IaC definitions as external SSOT, speckeeper only references and verifies
+
+### Acceptance Criteria
+
+- **CR-004-01**: Do not directly generate or modify OpenAPI files [review]
+- **CR-004-02**: Do not directly generate or modify DDL/Prisma schemas [review]
+- **CR-004-03**: Do not directly generate or modify CloudFormation/Terraform [review]
+- **CR-004-04**: Principle is to fix speckeeper side when consistency check fails [review]

package/docs/design/containers.md

@@ -0,0 +1,86 @@
+# Components
+
+| ID | Name | Type | Description |
+|----|------|------|-------------|
+| CONT-001 | CLI | container | Command line interface |
+| CONT-002 | Types | container | Type definitions with Zod schemas |
+| CONT-003 | DSL | container | Builder functions and checker factories |
+| CONT-004 | Generators | container | Markdown, Mermaid, JSON Schema generation engine |
+| CONT-005 | Validators | container | Validation and lint rule execution engine |
+| CONT-006 | Checkers | container | External SSOT consistency checker |
+| CONT-007 | Utils | container | Utilities for file I/O, config loading, ID generation, etc. |
+| CONT-008 | Scaffold | container | Mermaid flowchart-based project scaffold generator |
+
+---
+
+## CONT-001: CLI
+
+**Type**: container
+**Technology**: TypeScript + Commander
+
+Command line interface
+
+---
+
+## CONT-002: Types
+
+**Type**: container
+**Technology**: TypeScript + Zod
+
+Type definitions with Zod schemas
+
+---
+
+## CONT-003: DSL
+
+**Type**: container
+**Technology**: TypeScript
+
+Builder functions and checker factories
+
+---
+
+## CONT-004: Generators
+
+**Type**: container
+**Technology**: TypeScript
+
+Markdown, Mermaid, JSON Schema generation engine
+
+---
+
+## CONT-005: Validators
+
+**Type**: container
+**Technology**: TypeScript
+
+Validation and lint rule execution engine
+
+---
+
+## CONT-006: Checkers
+
+**Type**: container
+**Technology**: TypeScript
+
+External SSOT consistency checker
+
+---
+
+## CONT-007: Utils
+
+**Type**: container
+**Technology**: TypeScript
+
+Utilities for file I/O, config loading, ID generation, etc.
+
+---
+
+## CONT-008: Scaffold
+
+**Type**: container
+**Technology**: TypeScript
+
+Mermaid flowchart-based project scaffold generator
+
+---

package/docs/design/entities.md

@@ -0,0 +1,161 @@
+# Entities
+
+| ID | Name | Description |
+|----|------|-------------|
+| E-001 | Requirement | Entity representing requirements. Base for functional requirements, non-functional requirements, and constraints |
+| E-010 | Component | Architecture component (system, container, component, person) |
+| E-011 | Boundary | Architecture boundary (system boundary, subsystem boundary, etc.) |
+| E-012 | Layer | Architecture layer (presentation, business, data, etc.) |
+| E-020 | Entity | Concept model entity |
+| E-030 | Screen | Screen definition |
+| E-040 | APIRef | Reference to external API (OpenAPI) |
+| E-041 | TableRef | Reference to external table definition (DDL/Prisma) |
+| E-050 | Artifact | Artifact classification. Manages human-readable/machine-readable artifacts generated from SSOT |
+
+---
+
+## E-001: Requirement
+
+Entity representing requirements. Base for functional requirements, non-functional requirements, and constraints
+
+### Attributes
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | Unique ID (FR-001, etc.) |
+| name | string | Yes | Requirement name |
+| description | string | Yes | Detailed description of requirement |
+| rationale | string | No | Reason/background for requirement |
+| priority | enum | Yes | Priority |
+| status | enum | No | Status |
+
+---
+
+## E-010: Component
+
+Architecture component (system, container, component, person)
+
+### Attributes
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | Unique ID (COMP-001, etc.) |
+| name | string | Yes | Component name |
+| description | string | Yes | Description |
+| type | enum | Yes | Component type |
+| external | boolean | No | Whether external component |
+| layerId | string | No | Belonging layer ID |
+| boundaryId | string | No | Belonging boundary ID |
+
+---
+
+## E-011: Boundary
+
+Architecture boundary (system boundary, subsystem boundary, etc.)
+
+### Attributes
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | Unique ID |
+| name | string | Yes | Boundary name |
+| description | string | No | Description |
+| type | enum | No | Boundary type |
+
+---
+
+## E-012: Layer
+
+Architecture layer (presentation, business, data, etc.)
+
+### Attributes
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | Unique ID |
+| name | string | Yes | Layer name |
+| order | integer | Yes | Layer order (higher is more upper) |
+
+---
+
+## E-020: Entity
+
+Concept model entity
+
+### Attributes
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | Unique ID (ENT-001, etc.) |
+| name | string | Yes | Entity name |
+| description | string | Yes | Description |
+| isAggregate | boolean | No | Whether aggregate root |
+| boundaryId | string | No | Belonging boundary ID |
+
+---
+
+## E-030: Screen
+
+Screen definition
+
+### Attributes
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | Unique ID (SCR-001, etc.) |
+| name | string | Yes | Screen name |
+| description | string | Yes | Description |
+| type | enum | No | Screen type |
+| url | string | No | URL path |
+| authRequired | boolean | No | Whether authentication required |
+
+---
+
+## E-040: APIRef
+
+Reference to external API (OpenAPI)
+
+### Attributes
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | Unique ID |
+| specPath | string | Yes | OpenAPI file path |
+| operationId | string | Yes | Operation ID |
+| componentId | string | No | Related component ID |
+
+---
+
+## E-041: TableRef
+
+Reference to external table definition (DDL/Prisma)
+
+### Attributes
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | Unique ID |
+| tableName | string | Yes | Table name |
+| sourceType | enum | No | Source type |
+| sourcePath | string | Yes | Source file path |
+| entityId | string | No | Corresponding concept entity ID |
+
+---
+
+## E-050: Artifact
+
+Artifact classification. Manages human-readable/machine-readable artifacts generated from SSOT
+
+### Attributes
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | Unique ID |
+| name | string | Yes | Artifact name |
+| category | enum | Yes | Classification (SSOT/human-readable/machine-readable/implementation code) |
+| location | string | Yes | Directory path (design/, docs/, specs/, src/) |
+| purpose | string | Yes | Purpose |
+| driftTarget | boolean | No | Whether drift detection target |
+| generatedFrom | string | No | Source (SSOT ID) |
+
+---

package/docs/design/external-systems.md

@@ -0,0 +1,42 @@
+# Components
+
+| ID | Name | Type | Description |
+|----|------|------|-------------|
+| EXT-001 | OpenAPI Specification | system | External SSOT managing API specifications. speckeeper references via APIRef |
+| EXT-002 | Database Schema | system | External SSOT managing DB definitions via DDL/Prisma. speckeeper references via TableRef |
+| EXT-003 | Infrastructure as Code | system | IaC definitions like Terraform/CloudFormation. speckeeper references via IaCRef |
+| EXT-004 | GitHub/GitLab | system | Repository managing source code and documentation |
+
+---
+
+## EXT-001: OpenAPI Specification
+
+**Type**: system
+
+External SSOT managing API specifications. speckeeper references via APIRef
+
+---
+
+## EXT-002: Database Schema
+
+**Type**: system
+
+External SSOT managing DB definitions via DDL/Prisma. speckeeper references via TableRef
+
+---
+
+## EXT-003: Infrastructure as Code
+
+**Type**: system
+
+IaC definitions like Terraform/CloudFormation. speckeeper references via IaCRef
+
+---
+
+## EXT-004: GitHub/GitLab
+
+**Type**: system
+
+Repository managing source code and documentation
+
+---