specsync 2.2.0

Bidirectional spec-to-code validation — language-agnostic, blazing fast
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

---
module: generator
version: 1
status: stable
files:
  - src/generator.rs
db_tables: []
depends_on:
  - specs/types/types.spec.md
  - specs/ai/ai.spec.md
  - specs/exports/exports.spec.md
---

# Generator

## Purpose

Scaffolds spec files and companion files (tasks.md, context.md) for unspecced modules. Supports both template-based generation (using a default or custom `_template.spec.md`) and AI-powered generation that reads source code and calls an LLM to produce meaningful specs.

## Public API

### Exported Functions

| Function | Parameters | Returns | Description |
|----------|-----------|---------|-------------|
| `generate_specs_for_unspecced_modules` | `root, report, config, provider` | `usize` | Generate specs for all unspecced modules, returning count of generated specs |
| `generate_specs_for_unspecced_modules_paths` | `root, report, config, provider` | `Vec<String>` | Generate specs for all unspecced modules, returning paths of generated files |
| `generate_companion_files_for_spec` | `spec_dir, module_name` | `()` | Generate tasks.md and context.md companion files alongside a spec |

## Invariants

1. Specs are never overwritten — if a `module.spec.md` already exists, it is skipped
2. Custom templates at `specs/_template.spec.md` take precedence over the built-in default
3. Template generation fills in module name, version (1), status (draft), and discovered source files
4. Module title is derived from the module name with dashes converted to title case (e.g. "api-gateway" -> "Api Gateway")
5. Companion files (tasks.md, context.md) are only created if they don't already exist
6. AI generation falls back to template on failure (with a warning to stderr)
7. Source file paths in frontmatter are relative to the project root
8. Module source files are discovered by checking subdirectory-based modules first, then flat files

## Behavioral Examples

### Scenario: Generate spec for unspecced module

- **Given** a module "auth" with source files in `src/auth/` and no existing spec
- **When** `generate_specs_for_unspecced_modules` is called
- **Then** creates `specs/auth/auth.spec.md`, `specs/auth/tasks.md`, and `specs/auth/context.md`

### Scenario: Skip existing spec

- **Given** a module "auth" that already has `specs/auth/auth.spec.md`
- **When** `generate_specs_for_unspecced_modules` is called
- **Then** skips the module, returns 0

### Scenario: AI generation fallback

- **Given** an AI provider that fails with an error
- **When** generating a spec for module "auth"
- **Then** falls back to template-based generation and prints a warning

## Error Cases

| Condition | Behavior |
|-----------|----------|
| Cannot create spec directory | Prints error to stderr, skips module |
| Cannot write spec file | Prints error to stderr, skips module |
| AI generation fails | Falls back to template, prints warning |
| No source files found for module | Skips module entirely |

## Dependencies

### Consumes

| Module | What is used |
|--------|-------------|
| ai | `generate_spec_with_ai`, `ResolvedProvider` |
| exports | `has_extension`, `is_test_file` |
| types | `CoverageReport`, `SpecSyncConfig` |

### Consumed By

| Module | What is used |
|--------|-------------|
| main | `generate_specs_for_unspecced_modules`, `generate_companion_files_for_spec` |
| mcp | `generate_specs_for_unspecced_modules_paths` |

## Change Log

| Date | Change |
|------|--------|
| 2026-03-25 | Initial spec |