public/kaptan
1
Fork 0
Code Issues 24 Pull Requests Actions Packages Projects Releases Wiki Activity

improve kaptan-spec as a build library and move it to libs dir

Browse Source 
Signed-off-by: Onur Özkan <work@onurozkan.dev>
This commit is contained in:
Onur Özkan committed 2026-07-18 14:06:42 +03:00
1 parent 85559bd2d5
commit 8d9790de00
18 files changed
+237 -200
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

SPECIFICATIONS.md
+1 -87
View File
@@ -1,89 +1,3 @@
# 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.
The authoritative Kaptan specification policy is [libs/kaptan-spec/src/lib.spec.md](libs/kaptan-spec/src/lib.spec.md).