mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
af273b8e0b
* proposal: add artifact graph core query system
Add OpenSpec change proposal for Slice 1 of the artifact POC - the core
"What's Ready?" query system. This implements:
- ArtifactGraph class for DAG-based dependency modeling
- Filesystem-based state detection (file existence = completion)
- Topological sort for build order calculation
- Ready/blocked artifact queries
This is a parallel module that will coexist with the current system.
* docs: specify Zod for schema validation in artifact graph proposal
- Add decision section for Zod schema validation in design.md
- Update data structures to show Zod schemas with z.infer<> types
- Update tasks to specify Zod usage for type definitions and parsing
* docs: add 2-level schema resolution and built-in schemas
- Add decision for global → built-in schema resolution pattern
- Add resolver.ts for schema lookup logic
- Add built-in schemas directory (spec-driven.yaml, tdd.yaml)
- Add schema resolution tests
- Follows ESLint/Prettier/Git patterns (defaults baked in package)
* experiment: add vertical slice version of artifact graph change
Creates add-artifact-graph-core-v2 with requirements organized as
vertical slices - each requirement file contains its spec, design
decisions, and tasks bundled together for comparison.
* feat(core): add getGlobalDataDir for XDG-compliant data directory
Add getGlobalDataDir() function following XDG Base Directory Specification
for storing user data like schema overrides:
- XDG_DATA_HOME takes precedence on all platforms
- Unix/macOS fallback: ~/.local/share/openspec/
- Windows fallback: %LOCALAPPDATA%/openspec/
* feat(artifact-graph): add core dependency graph module
Implement Slice 1 ("What's Ready?") of the artifact graph system:
- types.ts: Zod schemas for artifact definitions with derived TypeScript types
- schema.ts: YAML parsing with validation for duplicates, invalid refs, cycles
- graph.ts: ArtifactGraph class with Kahn's algorithm for topological sort
- state.ts: Filesystem-based completion detection with glob pattern support
- resolver.ts: Two-level schema resolution (global override → built-in)
- builtin-schemas.ts: spec-driven and tdd workflow definitions
Key design decisions:
- Filesystem as database (stateless, git-friendly)
- Cycle errors show full path (e.g., "A → B → C → A")
- Deterministic ordering via sorted queues
* test(artifact-graph): add comprehensive test suite
52 tests covering all artifact-graph functionality:
- schema.test.ts: Parsing, validation errors, cycle detection
- graph.test.ts: Build order, ready artifacts, blocked queries
- state.test.ts: File existence, glob patterns, missing directories
- resolver.test.ts: Schema resolution with global overrides
* docs(openspec): archive add-artifact-graph-core change
Archive completed change proposal and create artifact-graph spec with
6 requirements covering schema loading, build order, state detection,
ready queries, completion checks, and blocked queries.
* chore: remove experimental artifact-graph-core-v2 folder
Clean up experimental vertical slice proposal that is no longer needed.
* feat(artifact-graph): validate global schema overrides
Global schema overrides are now validated through the same pipeline as
built-in schemas, catching invalid schemas, cyclic dependencies, and
invalid requires references at load time. Added SchemaLoadError for
better error context with file paths.
* test(artifact-graph): add workflow integration tests
Add end-to-end integration tests that exercise the full artifact-graph
pipeline: resolveSchema → ArtifactGraph → detectCompleted → queries.
Tests cover:
- Complete spec-driven and tdd workflow progressions
- Out-of-order file creation handling
- Glob pattern matching with multiple files
- Build order consistency
- Edge cases (empty/missing directories, non-matching files)
* refactor(artifact-graph): adopt zod v4 error message format
Update custom error messages from string format to zod v4 object format
using `{ error: 'message' }` convention.
* fix(test): prevent hanging vitest threads after test runs
- Add teardownTimeout (3s) to vitest config for forced cleanup
- Add global teardown function to vitest.setup.ts
- Call child.unref() to prevent child processes from blocking event loop
- Explicitly destroy stdio streams on process close/error
4.1 KiB
4.1 KiB
artifact-graph Specification
Purpose
TBD - created by archiving change add-artifact-graph-core. Update Purpose after archive.
Requirements
Requirement: Schema Loading
The system SHALL load artifact graph definitions from YAML schema files.
Scenario: Valid schema loaded
- WHEN a valid schema YAML file is provided
- THEN the system returns an ArtifactGraph with all artifacts and dependencies
Scenario: Invalid schema rejected
- WHEN a schema YAML file is missing required fields
- THEN the system throws an error with a descriptive message
Scenario: Cyclic dependencies detected
- WHEN a schema contains cyclic artifact dependencies
- THEN the system throws an error listing the artifact IDs in the cycle
Scenario: Invalid dependency reference
- WHEN an artifact's
requiresarray references a non-existent artifact ID - THEN the system throws an error identifying the invalid reference
Scenario: Duplicate artifact IDs rejected
- WHEN a schema contains multiple artifacts with the same ID
- THEN the system throws an error identifying the duplicate
Requirement: Build Order Calculation
The system SHALL compute a valid topological build order for artifacts.
Scenario: Linear dependency chain
- WHEN artifacts form a linear chain (A → B → C)
- THEN getBuildOrder() returns [A, B, C]
Scenario: Diamond dependency
- WHEN artifacts form a diamond (A → B, A → C, B → D, C → D)
- THEN getBuildOrder() returns A before B and C, and D last
Scenario: Independent artifacts
- WHEN artifacts have no dependencies
- THEN getBuildOrder() returns them in a stable order
Requirement: State Detection
The system SHALL detect artifact completion state by scanning the filesystem.
Scenario: Simple file exists
- WHEN an artifact generates "proposal.md" and the file exists
- THEN the artifact is marked as completed
Scenario: Simple file missing
- WHEN an artifact generates "proposal.md" and the file does not exist
- THEN the artifact is not marked as completed
Scenario: Glob pattern with files
- WHEN an artifact generates "specs/*.md" and the specs/ directory contains .md files
- THEN the artifact is marked as completed
Scenario: Glob pattern empty
- WHEN an artifact generates "specs/*.md" and the specs/ directory is empty or missing
- THEN the artifact is not marked as completed
Scenario: Missing change directory
- WHEN the change directory does not exist
- THEN all artifacts are marked as not completed (empty state)
Requirement: Ready Artifact Query
The system SHALL identify which artifacts are ready to be created based on dependency completion.
Scenario: Root artifacts ready initially
- WHEN no artifacts are completed
- THEN getNextArtifacts() returns artifacts with no dependencies
Scenario: Dependent artifact becomes ready
- WHEN an artifact's dependencies are all completed
- THEN getNextArtifacts() includes that artifact
Scenario: Blocked artifacts excluded
- WHEN an artifact has uncompleted dependencies
- THEN getNextArtifacts() does not include that artifact
Requirement: Completion Check
The system SHALL determine when all artifacts in a graph are complete.
Scenario: All complete
- WHEN all artifacts in the graph are in the completed set
- THEN isComplete() returns true
Scenario: Partially complete
- WHEN some artifacts in the graph are not completed
- THEN isComplete() returns false
Requirement: Blocked Query
The system SHALL identify which artifacts are blocked and return all their unmet dependencies.
Scenario: Artifact blocked by single dependency
- WHEN artifact B requires artifact A and A is not complete
- THEN getBlocked() returns
{ B: ['A'] }
Scenario: Artifact blocked by multiple dependencies
- WHEN artifact C requires A and B, and only A is complete
- THEN getBlocked() returns
{ C: ['B'] }
Scenario: Artifact blocked by all dependencies
- WHEN artifact C requires A and B, and neither is complete
- THEN getBlocked() returns
{ C: ['A', 'B'] }