89 lines
2.6 KiB
Markdown
89 lines
2.6 KiB
Markdown
# Specifications
|
|
|
|
Formal Kaptan specifications live next to the file-backed module they govern.
|
|
|
|
Examples:
|
|
|
|
- `kaptan-runtime/src/runtime.rs`
|
|
- `kaptan-runtime/src/runtime.spec.md`
|
|
- `kaptan-runtime/src/scheduler.rs`
|
|
- `kaptan-runtime/src/scheduler.spec.md`
|
|
|
|
## Automatic Sidecar Checks
|
|
|
|
Kaptan build checks require a same-name `.spec.md` sidecar for every file-backed Rust module under a checked crate's `src/` tree.
|
|
|
|
For example, `control_loop.rs` requires `control_loop.spec.md` in the same directory. A checked module must have exactly one of:
|
|
|
|
- its sidecar specification; or
|
|
- a top-level `no_spec!("reason");` declaration.
|
|
|
|
`no_spec!` is only for module files that intentionally have no formal specification, such as a crate root that only declares child modules. It must provide a non-empty reason and must not be used for types, functions, or individual items.
|
|
|
|
Example for a crate root without standalone runtime behavior:
|
|
|
|
```rust
|
|
use kaptan_spec::no_spec;
|
|
|
|
no_spec!("Crate root declares child modules only.");
|
|
```
|
|
|
|
The build fails if a required sidecar is missing or a module contains both a sidecar and `no_spec!(...)`.
|
|
|
|
## Spec Format
|
|
|
|
Formal spec files are append-only records for one governed module or package.
|
|
|
|
Each file may contain one or more spec entries. Each entry starts with a version heading, followed by YAML frontmatter and a Markdown body.
|
|
|
|
Use this exact heading form for each entry:
|
|
|
|
```markdown
|
|
# --- version: 0.1.0 ---
|
|
```
|
|
|
|
Each spec entry must then declare these keys in YAML frontmatter:
|
|
|
|
- `title`
|
|
- `status`
|
|
- `owners`
|
|
|
|
Allowed statuses are:
|
|
|
|
- `in-progress`
|
|
- `implemented`
|
|
- `deprecated`
|
|
|
|
Owner entries must use full name and email address in this format:
|
|
|
|
```text
|
|
- Full Name <name@example.com>
|
|
```
|
|
|
|
The spec path is the identifier for linkage and traceability.
|
|
|
|
- The code path plus the `#[spec("...")]` reference identifies the governing spec.
|
|
- The spec file path identifies the governed module or package.
|
|
- Individual spec revisions are identified by the version heading.
|
|
- A single spec file can carry multiple revisions for the same governed module.
|
|
- New revisions should be appended as new spec entries in the same file instead of creating new filenames.
|
|
- Within the body of a spec entry, `#` is reserved for version headings. Spec content should start at `##` and below.
|
|
|
|
## Template
|
|
|
|
Use this starter when creating a colocated spec entry:
|
|
|
|
```markdown
|
|
# --- version: 0.1.0 ---
|
|
|
|
---
|
|
title: Replace with title
|
|
status: deprecated
|
|
owners:
|
|
- Full Name <name@example.com>
|
|
---
|
|
|
|
## TODO
|
|
```
|
|
|
|
When the spec evolves, append another entry in the same shape with a new version heading. |