speckeeper 0.9.1 → 0.9.3

package/docs/design/glossary.md

@@ -0,0 +1,242 @@
+# Glossary
+
+- **API**: Application programming interface
+- **C4**: Software architecture visualization model
+- **CLI**: Command line interface
+- **Concretization Slot**: Items to be filled in subsequent phases (allows TBD while having a deadline phase)
+- **DDL**: Data definition language. A language for defining database schemas
+- **Design Artifact**: Design artifacts to satisfy requirements such as monitoring, Runbook, Dashboard, data schema, etc.
+- **Drift**: A state where docs//specs/ that should have been generated from TS have differences due to manual edits, etc.
+- **DSL**: Domain-specific language. A programming language specialized for a particular domain
+- **DTO**: Data transfer object. A structure for passing data between systems
+- **ER**: Entity relationship. A data modeling technique
+- **External SSOT**: Artifacts managed by existing tools/formats (OpenAPI, DDL, IaC, etc.). This framework does not generate them but checks consistency against them
+- **External SSOT Reference**: Minimal interface for referencing external SSOT from TS models (ID, path, correspondence, etc.)
+- **IaC**: Infrastructure definition through code
+- **ID Linkage**: A mechanism that ensures componentId/entityId/requirementId from TS models appear in external SSOT, generated artifacts, implementation, and IaC to connect design and implementation
+- **Model**: A unit of design information defined in TypeScript. Inherits from Model base class and has schema, lint rules, renderers, etc.
+- **Reconciliation**: Checks to bridge gaps between design and external SSOT/implementation (design consistency, external SSOT consistency, implementation existence verification)
+- **SSOT**: The single authoritative source of information. The canonical location for data and design
+- **TS**: Statically typed JavaScript developed by Microsoft
+- **TS-SSOT**: A policy where TypeScript is the source of truth and generated artifacts are regeneratable derivatives
+- **User-defined Model**: Project-specific models defined by users inheriting from the Model base class. The standard way to use speckeeper
+
+---
+
+## TERM-A005: API
+
+**Category**: acronym
+**Abbreviation**: API
+**Expanded Form**: Application Programming Interface
+
+### Definition
+
+Application programming interface
+
+---
+
+## TERM-A010: C4
+
+**Category**: acronym
+**Abbreviation**: C4
+**Expanded Form**: Context, Container, Component, Code
+
+### Definition
+
+Software architecture visualization model
+
+---
+
+## TERM-A004: CLI
+
+**Category**: acronym
+**Abbreviation**: CLI
+**Expanded Form**: Command Line Interface
+
+### Definition
+
+Command line interface
+
+---
+
+## TERM-011: Concretization Slot
+
+**Category**: core
+
+### Definition
+
+Items to be filled in subsequent phases (allows TBD while having a deadline phase)
+
+---
+
+## TERM-A006: DDL
+
+**Category**: acronym
+**Abbreviation**: DDL
+**Expanded Form**: Data Definition Language
+
+### Definition
+
+Data definition language. A language for defining database schemas
+
+---
+
+## TERM-010: Design Artifact
+
+**Category**: core
+
+### Definition
+
+Design artifacts to satisfy requirements such as monitoring, Runbook, Dashboard, data schema, etc.
+
+---
+
+## TERM-013: Drift
+
+**Category**: process
+
+### Definition
+
+A state where docs//specs/ that should have been generated from TS have differences due to manual edits, etc.
+
+---
+
+## TERM-A003: DSL
+
+**Category**: acronym
+**Abbreviation**: DSL
+**Expanded Form**: Domain Specific Language
+
+### Definition
+
+Domain-specific language. A programming language specialized for a particular domain
+
+---
+
+## TERM-A008: DTO
+
+**Category**: acronym
+**Abbreviation**: DTO
+**Expanded Form**: Data Transfer Object
+
+### Definition
+
+Data transfer object. A structure for passing data between systems
+
+---
+
+## TERM-A009: ER
+
+**Category**: acronym
+**Abbreviation**: ER
+**Expanded Form**: Entity Relationship
+
+### Definition
+
+Entity relationship. A data modeling technique
+
+---
+
+## TERM-002: External SSOT
+
+**Category**: core
+
+### Definition
+
+Artifacts managed by existing tools/formats (OpenAPI, DDL, IaC, etc.). This framework does not generate them but checks consistency against them
+
+---
+
+## TERM-003: External SSOT Reference
+
+**Category**: core
+
+### Definition
+
+Minimal interface for referencing external SSOT from TS models (ID, path, correspondence, etc.)
+
+---
+
+## TERM-A007: IaC
+
+**Category**: acronym
+**Abbreviation**: IaC
+**Expanded Form**: Infrastructure as Code
+
+### Definition
+
+Infrastructure definition through code
+
+---
+
+## TERM-012: ID Linkage
+
+**Category**: core
+
+### Definition
+
+A mechanism that ensures componentId/entityId/requirementId from TS models appear in external SSOT, generated artifacts, implementation, and IaC to connect design and implementation
+
+---
+
+## TERM-004: Model
+
+**Category**: core
+
+### Definition
+
+A unit of design information defined in TypeScript. Inherits from Model base class and has schema, lint rules, renderers, etc.
+
+---
+
+## TERM-014: Reconciliation
+
+**Category**: process
+
+### Definition
+
+Checks to bridge gaps between design and external SSOT/implementation (design consistency, external SSOT consistency, implementation existence verification)
+
+---
+
+## TERM-A001: SSOT
+
+**Category**: acronym
+**Abbreviation**: SSOT
+**Expanded Form**: Single Source of Truth
+
+### Definition
+
+The single authoritative source of information. The canonical location for data and design
+
+---
+
+## TERM-A002: TS
+
+**Category**: acronym
+**Abbreviation**: TS
+**Expanded Form**: TypeScript
+
+### Definition
+
+Statically typed JavaScript developed by Microsoft
+
+---
+
+## TERM-001: TS-SSOT
+
+**Category**: core
+
+### Definition
+
+A policy where TypeScript is the source of truth and generated artifacts are regeneratable derivatives
+
+---
+
+## TERM-015: User-defined Model
+
+**Category**: core
+
+### Definition
+
+Project-specific models defined by users inheriting from the Model base class. The standard way to use speckeeper

package/docs/design/nonfunctional-requirements.md

@@ -0,0 +1,242 @@
+# Requirements
+
+## Non-Functional Requirements
+
+| ID | Name | Priority | Category |
+|----|------|----------|----------|
+| NFR-001 | Command Execution Time | should | performance |
+| NFR-002 | Node.js Compatibility | must | portability |
+| NFR-003 | Multi-OS Support | must | portability |
+| NFR-004 | User-defined Models | must | extensibility |
+| NFR-005 | Input Format Diversity | should | extensibility |
+| NFR-006 | Rule Extensibility | should | extensibility |
+| NFR-007 | Error Message Clarity | must | transparency |
+| NFR-008 | TypeScript Compatibility | must | compatibility |
+| NFR-009 | ESM Support | must | compatibility |
+| NFR-010 | npm Distribution | must | deployability |
+| NFR-011 | CLI Test Infrastructure | must | testability |
+| NFR-012 | CLI Command Test Coverage | must | testability |
+| NFR-013 | Test-Specification Traceability | must | testability |
+| NFR-014 | CLI Definition-Implementation Consistency | must | testability |
+| NFR-015 | CLI Backward Compatibility | must | testability |
+
+---
+
+## NFR-001: Command Execution Time
+
+**Type**: non-functional | **Priority**: should | **Category**: performance
+
+lint/build/drift within 1 minute for typical requirement scale (~500 items), check within 2 minutes (depends on file count)
+
+### Acceptance Criteria
+
+- **NFR-001-01**: lint/build/drift within 60 seconds for 500 requirements scale [test]
+- **NFR-001-02**: check within 120 seconds for 1000 files scale [test]
+- **NFR-001-03**: build within 5 seconds for 1000 requirements, 100 entities, 50 screens [test]
+
+---
+
+## NFR-002: Node.js Compatibility
+
+**Type**: non-functional | **Priority**: must | **Category**: portability
+
+Works on Node.js (LTS)
+
+### Acceptance Criteria
+
+- **NFR-002-01**: Verified on Node.js 18 LTS [test]
+- **NFR-002-02**: Verified on Node.js 20 LTS [test]
+- **NFR-002-03**: Verified on Node.js 22 LTS [test]
+
+---
+
+## NFR-003: Multi-OS Support
+
+**Type**: non-functional | **Priority**: must | **Category**: portability
+
+Avoid OS dependencies and work on Linux/macOS/Windows
+
+### Acceptance Criteria
+
+- **NFR-003-01**: Verified on Linux (Ubuntu) [test]
+- **NFR-003-02**: Verified on macOS [test]
+- **NFR-003-03**: Verified on Windows (PowerShell) [test]
+- **NFR-003-04**: Eliminate OS-dependent code such as path separators [review]
+
+---
+
+## NFR-004: User-defined Models
+
+**Type**: non-functional | **Priority**: must | **Category**: extensibility
+
+Users can define custom models by inheriting from Model base class
+
+### Acceptance Criteria
+
+- **NFR-004-01**: Can define new models by inheriting from Model base class [test]
+- **NFR-004-02**: Can define model-specific schema, lint rules, and renderers [test]
+- **NFR-004-03**: Models registered in speckeeper.config.ts become targets of lint/build/check [test]
+
+---
+
+## NFR-005: Input Format Diversity
+
+**Type**: non-functional | **Priority**: should | **Category**: extensibility
+
+Allow YAML/JSON input to lower participation barriers for non-developers
+
+### Acceptance Criteria
+
+- **NFR-005-01**: Support TypeScript DSL input [test]
+- **NFR-005-02**: Support YAML format input [demo]
+- **NFR-005-03**: Support JSON format input [demo]
+
+---
+
+## NFR-006: Rule Extensibility
+
+**Type**: non-functional | **Priority**: should | **Category**: extensibility
+
+Allow adding lint and check rules via plugin mechanism
+
+### Acceptance Criteria
+
+- **NFR-006-01**: Custom lint rules can be added [demo]
+- **NFR-006-02**: Custom check rules (external SSOT verification) can be added [demo]
+- **NFR-006-03**: Rules are defined under Model._models/ [review]
+
+---
+
+## NFR-007: Error Message Clarity
+
+**Type**: non-functional | **Priority**: must | **Category**: transparency
+
+Output errors showing requirement ID, file, and field name, providing messages that clearly show "why it failed"
+
+### Acceptance Criteria
+
+- **NFR-007-01**: Errors include requirement ID/specification ID [test]
+- **NFR-007-02**: Errors include file path and line number (when possible) [test]
+- **NFR-007-03**: Errors include problematic field name [test]
+- **NFR-007-04**: Provide hints for fixes [review]
+
+---
+
+## NFR-008: TypeScript Compatibility
+
+**Type**: non-functional | **Priority**: must | **Category**: compatibility
+
+Type checking passes on TypeScript 5.0+
+
+### Acceptance Criteria
+
+- **NFR-008-01**: Compiles successfully on TypeScript 5.0 [test]
+- **NFR-008-02**: No type errors in strict mode [test]
+
+---
+
+## NFR-009: ESM Support
+
+**Type**: non-functional | **Priority**: must | **Category**: compatibility
+
+Provided in ES Modules format
+
+### Acceptance Criteria
+
+- **NFR-009-01**: Can be imported via import statement [test]
+- **NFR-009-02**: Tree-shaking works [inspection]
+
+---
+
+## NFR-010: npm Distribution
+
+**Type**: non-functional | **Priority**: must | **Category**: deployability
+
+Can be distributed as npm package
+
+### Acceptance Criteria
+
+- **NFR-010-01**: Can publish package via npm publish [demo]
+- **NFR-010-02**: Can install via npm install speckeeper [demo]
+
+---
+
+## NFR-011: CLI Test Infrastructure
+
+**Type**: non-functional | **Priority**: must | **Category**: testability
+
+All CLI commands have comprehensive test coverage with traceability to specifications
+
+### Acceptance Criteria
+
+- **NFR-011-01**: All child requirements (NFR-012~NFR-015) are satisfied [review]
+
+---
+
+## NFR-012: CLI Command Test Coverage
+
+**Type**: non-functional | **Priority**: must | **Category**: testability
+
+Each CLI command (lint, check, build, impact, drift, new) has a corresponding test file in test/cli/ with requirement ID references
+
+### Rationale
+
+To prevent regression bugs in CLI commands that directly affect all users and CI pipelines
+
+### Acceptance Criteria
+
+- **NFR-012-01**: Test files exist in test/cli/ for each CLI command (lint, check, build, impact, drift, new) [test]
+- **NFR-012-02**: describe/it block names contain corresponding requirement IDs (FR-xxx) [test]
+- **NFR-012-03**: CLI module statement coverage reaches 60% or above (from 0%) [test]
+
+---
+
+## NFR-013: Test-Specification Traceability
+
+**Type**: non-functional | **Priority**: must | **Category**: testability
+
+TestRef definitions in design/test-refs.ts provide bidirectional traceability between tests and specifications
+
+### Rationale
+
+To ensure all acceptance criteria are covered by test cases and maintain spec-test traceability
+
+### Acceptance Criteria
+
+- **NFR-013-01**: TestRef definitions (TEST-020~025) exist in design/test-refs.ts for each CLI test file [test]
+- **NFR-013-02**: TestRefs are linked to corresponding command IDs via implementsCommand [test]
+- **NFR-013-03**: speckeeper check test succeeds for all TestRefs [test]
+- **NFR-013-04**: speckeeper check test --coverage achieves 100% for target acceptance criteria [test]
+
+---
+
+## NFR-014: CLI Definition-Implementation Consistency
+
+**Type**: non-functional | **Priority**: must | **Category**: testability
+
+CLI command definitions in design/cli-commands.ts match actual implementation in src/cli/index.ts
+
+### Rationale
+
+To ensure specification and implementation stay synchronized (e.g., no missing --config parameters)
+
+### Acceptance Criteria
+
+- **NFR-014-01**: All command definitions in design/cli-commands.ts match implementation (parameters, subcommands, exit codes) [test]
+
+---
+
+## NFR-015: CLI Backward Compatibility
+
+**Type**: non-functional | **Priority**: must | **Category**: testability
+
+Existing public APIs and CLI behavior are not changed by test additions
+
+### Rationale
+
+To ensure test strengthening does not introduce regressions
+
+### Acceptance Criteria
+
+- **NFR-015-01**: All existing tests continue to pass (no regression) [test]
+- **NFR-015-02**: No changes to existing public API or CLI behavior [review]