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

Signed-off-by: Onur Özkan <work@onurozkan.dev>

libs/kaptan-spec/src/lib.rs

@@ -0,0 +1,128 @@
+//! Kaptan formal-specification infrastructure.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+#[cfg(feature = "std")]
+use std::{env, fs, path::Path};
+
+#[cfg(feature = "std")]
+use syn::Item;
+
+/// Returns whether an exception explanation contains a non-whitespace byte.
+#[doc(hidden)]
+pub const fn has_non_whitespace(value: &str) -> bool {
+    let bytes = value.as_bytes();
+    let mut index = 0;
+
+    while index < bytes.len() {
+        if !bytes[index].is_ascii_whitespace() {
+            return true;
+        }
+
+        index += 1;
+    }
+
+    false
+}
+
+/// Declares that the containing module intentionally has no sidecar spec.
+#[macro_export]
+macro_rules! no_spec {
+    () => {
+        compile_error!("missing no-spec explanation; use no_spec!(\"reason\");");
+    };
+    ($reason:literal) => {
+        const _: &str = $reason;
+        const _: () = assert!(
+            $crate::has_non_whitespace($reason),
+            "no-spec explanation must not be empty; use no_spec!(\"reason\");"
+        );
+    };
+    ($($invalid:tt)+) => {
+        compile_error!("invalid no-spec invocation; use no_spec!(\"reason\");");
+    };
+}
+
+/// Validates the Rust modules in the package identified by Cargo's build-script
+/// environment.
+///
+/// Every file-backed module under `src/` must have exactly one of a same-name
+/// `.spec.md` sidecar or a top-level `no_spec!("reason");` declaration.
+#[cfg(feature = "std")]
+pub fn validate_package() {
+    let source_directory =
+        Path::new(&env::var("CARGO_MANIFEST_DIR").expect("manifest directory")).join("src");
+    let mut violations = Vec::new();
+
+    check_directory(&source_directory, &mut violations);
+
+    if !violations.is_empty() {
+        panic!(
+            "Kaptan module specification check failed:\n{}",
+            violations.join("\n")
+        );
+    }
+}
+
+#[cfg(feature = "std")]
+fn check_directory(directory: &Path, violations: &mut Vec<String>) {
+    let entries = fs::read_dir(directory).unwrap_or_else(|error| {
+        panic!(
+            "could not read module directory {}: {error}",
+            directory.display()
+        )
+    });
+
+    for entry in entries {
+        let path = entry
+            .unwrap_or_else(|error| panic!("could not read module entry: {error}"))
+            .path();
+
+        if path.is_dir() {
+            check_directory(&path, violations);
+        } else if path.extension().is_some_and(|extension| extension == "rs") {
+            check_module_file(&path, violations);
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+fn check_module_file(module_path: &Path, violations: &mut Vec<String>) {
+    println!("cargo:rerun-if-changed={}", module_path.display());
+
+    let source = fs::read_to_string(module_path)
+        .unwrap_or_else(|error| panic!("could not read module {}: {error}", module_path.display()));
+    let module = syn::parse_file(&source).unwrap_or_else(|error| {
+        panic!("could not parse module {}: {error}", module_path.display())
+    });
+    let sidecar_path = module_path.with_extension("spec.md");
+    let has_sidecar = sidecar_path.is_file();
+    let has_no_spec = module.items.iter().any(
+        |item| matches!(item, Item::Macro(item_macro) if is_no_spec_macro(&item_macro.mac.path)),
+    );
+
+    if has_sidecar {
+        println!("cargo:rerun-if-changed={}", sidecar_path.display());
+    }
+
+    match (has_sidecar, has_no_spec) {
+        (false, false) => violations.push(format!(
+            "- {} is missing {}; add the sidecar or no_spec!(\"reason\").",
+            module_path.display(),
+            sidecar_path.display()
+        )),
+        (true, true) => violations.push(format!(
+            "- {} has both {} and no_spec!(...); keep exactly one declaration.",
+            module_path.display(),
+            sidecar_path.display()
+        )),
+        _ => {}
+    }
+}
+
+#[cfg(feature = "std")]
+fn is_no_spec_macro(path: &syn::Path) -> bool {
+    path.segments
+        .last()
+        .is_some_and(|segment| segment.ident == "no_spec")
+}

libs/kaptan-spec/src/lib.spec.md

@@ -0,0 +1,75 @@
+# --- version: 0.1.0 ---
+
+---
+title: Specification validation library
+status: in-progress
+owners:
+  - Onur Özkan <work@onurozkan.dev>
+---
+
+## Scope
+
+This module defines Kaptan's reusable package build-time validation of formal-specification sidecars and the no_std `no_spec!` exception macro.
+
+Formal Kaptan specifications live next to the file-backed module they govern. For example, `control_loop.rs` is governed by `control_loop.spec.md` in the same directory.
+
+## Sidecar Requirements
+
+Every file-backed Rust module under a validated package's `src/` tree must have exactly one same-name `.spec.md` sidecar or one top-level `no_spec!("reason");` declaration. Missing and duplicate declarations fail the package build.
+
+A package build script invokes `kaptan_spec::validate_package()` with the `std` feature enabled. The validator emits Cargo change-tracking directives for every checked source module and existing sidecar.
+
+`kaptan-spec` is the bootstrap exception because it cannot use itself as a build dependency. Every other Kaptan package must invoke the validator from its build script.
+
+## No-Spec Exceptions
+
+`no_spec!("reason");` is only for a file-backed module that intentionally has no standalone formal specification, such as a crate root that only declares child modules. It applies at module scope, not to types, functions, or individual items.
+
+The exception requires one non-empty, non-whitespace string literal explanation. It expands to compile-time constants and has no runtime cost. A module must not contain both a sidecar and `no_spec!(...)`.
+
+## Specification Record Format
+
+Each sidecar is an append-only record for one governed module or package. An entry starts with this exact version heading:
+
+```markdown
+# --- version: 0.1.0 ---
+```
+
+The heading is followed by YAML frontmatter containing these required keys:
+
+- `title`
+- `status`
+- `owners`
+
+Allowed statuses are:
+
+- `in-progress`
+- `implemented`
+- `deprecated`
+
+Each owner entry uses a full name and email address:
+
+```text
+- Full Name <name@example.com>
+```
+
+## Traceability and Revisions
+
+The sidecar path identifies the governed module or package. Individual revisions are identified by their version heading. New revisions append a complete new entry to the stable sidecar file; they do not create a new filename.
+
+Within a record entry, `#` is reserved for version headings. Content headings start at `##` or below.
+
+## Entry Template
+
+```markdown
+# --- version: 0.1.0 ---
+
+---
+title: Replace with title
+status: deprecated
+owners:
+  - Full Name <name@example.com>
+---
+
+## TODO
+```