feat(core): add adapter compliance test harness (#288)

* feat(core): add adapter compliance test harness

Introduce a reusable behavioural-contract test suite that every `Adapter`
must satisfy: schema consistency, CRUD round-trip, list / filter, search,
optional links, and standard error cases.

The harness is exposed via the `test-utils` feature for out-of-tree
adapters and is always available inside the crate's own tests. The
`adapter_compliance_tests!` macro emits one `#[test]` per category so each
case shows up individually in `cargo test` output; `run_compliance_suite`
runs every case sequentially against a single adapter instance.

`MarkdownAdapter` wires the full suite via a fresh-tempdir factory; all
six categories pass. `GitHubAdapter` wires `check_schema_consistency` into
its mock unit tests and `run_compliance_suite` into its (feature-gated,
`#[ignore]`d) real-API integration tests.

Two markdown adapter bugs surfaced and were fixed in the process:
`update()` and `delete()` on a nonexistent id now return
`AdapterError::NotFound` instead of `AdapterError::IoError`, matching the
contract every adapter is now held to.

Closes #260

https://claude.ai/code/session_01CZJP9d8gzWqQHgz2UJKyhu

* refactor(core): tighten compliance harness from review feedback

- `check_schema_consistency` now cross-checks `ComplianceOptions` against
  the schema (status_key, content_key, and link_type when
  `supports_links`) so a misconfigured adapter fails here with a clear
  diagnostic instead of deep inside CRUD.
- `check_crud_roundtrip` now requires the content field to be present on
  `get()` after a `create()` that set it — silent absence no longer
  passes.
- `check_list_filter`, `check_search`, and `check_links` always delete
  the items they create so persistent backends (real GitHub API in
  particular) don't accumulate fixtures across runs. Archive-specific
  post-delete assertions remain gated on `delete_is_archive`.
- The `adapter_compliance_tests!` macro binds `let opts = $opts;` once
  per generated test so a `$opts` expression like a function call is
  evaluated once and the reference is to a named local, not a temporary.

https://claude.ai/code/session_01CZJP9d8gzWqQHgz2UJKyhu

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: tikazyq

rust/leanspec-core/Cargo.toml

@@ -46,6 +46,9 @@ github = ["dep:reqwest", "reqwest/blocking", "reqwest/json", "reqwest/default-tl
 # Requires `GITHUB_TOKEN`, `TEST_GITHUB_OWNER`, `TEST_GITHUB_REPO` env vars.
 github-integration-tests = ["github"]
 storage = ["tokio", "dirs", "uuid"]
+# Expose the adapter compliance test harness for use by out-of-tree
+# adapter implementations. Always available within this crate's own tests.
+test-utils = []
 
 [dev-dependencies]
 mockito = "1.5"

rust/leanspec-core/src/adapters/github/mod.rs

@@ -1102,6 +1102,21 @@ mod tests {
         );
     }
 
+    #[test]
+    fn passes_schema_compliance_check() {
+        use crate::adapters::test_harness::{check_schema_consistency, ComplianceOptions};
+        let s = mockito::Server::new();
+        let a = adapter(&s);
+        let opts = ComplianceOptions {
+            status_active: "open".into(),
+            status_alt: "closed".into(),
+            delete_is_archive: true,
+            supports_links: false,
+            ..ComplianceOptions::default()
+        };
+        check_schema_consistency(&a, &opts);
+    }
+
     #[test]
     fn capabilities_match_spec() {
         let s = mockito::Server::new();
@@ -1831,13 +1846,33 @@ mod tests {
 #[cfg(all(test, feature = "github-integration-tests"))]
 mod integration {
     use super::*;
+    use crate::adapters::test_harness::{run_compliance_suite, ComplianceOptions};
 
     fn live_adapter() -> Option<GitHubAdapter> {
         let owner = std::env::var("TEST_GITHUB_OWNER").ok()?;
         let repo = std::env::var("TEST_GITHUB_REPO").ok()?;
         GitHubAdapter::new(owner, repo, "GITHUB_TOKEN").ok()
     }
 
+    fn github_compliance_options() -> ComplianceOptions {
+        ComplianceOptions {
+            status_active: "open".into(),
+            status_alt: "closed".into(),
+            delete_is_archive: true,
+            supports_links: false,
+            ..ComplianceOptions::default()
+        }
+    }
+
+    #[test]
+    #[ignore = "hits real GitHub API; requires GITHUB_TOKEN + TEST_GITHUB_OWNER + TEST_GITHUB_REPO"]
+    fn integration_compliance_suite() {
+        let Some(adapter) = live_adapter() else {
+            return;
+        };
+        run_compliance_suite(&adapter, &github_compliance_options());
+    }
+
     #[test]
     #[ignore = "hits real GitHub API; requires GITHUB_TOKEN + TEST_GITHUB_OWNER + TEST_GITHUB_REPO"]
     fn integration_create_get_update_close_roundtrip() {

rust/leanspec-core/src/adapters/markdown/mod.rs

@@ -670,7 +670,10 @@ impl Adapter for MarkdownAdapter {
 
         writer
             .update_metadata(id, meta_update)
-            .map_err(|e| AdapterError::IoError(std::io::Error::other(e.to_string())))?;
+            .map_err(|e| match e {
+                writer::WriteError::NotFound(p) => AdapterError::NotFound(p),
+                other => AdapterError::IoError(std::io::Error::other(other.to_string())),
+            })?;
 
         // Second pass: title, content body, and extended frontmatter fields
         // (reviewer, issue, pr, epic, breaking, due) rewrite the file directly.
@@ -769,7 +772,10 @@ impl Adapter for MarkdownAdapter {
     fn delete(&self, id: &str) -> Result<(), AdapterError> {
         SpecArchiver::new(&self.specs_dir)
             .archive(id)
-            .map_err(|e| AdapterError::IoError(std::io::Error::other(e.to_string())))
+            .map_err(|e| match e {
+                archiver::ArchiveError::NotFound(p) => AdapterError::NotFound(p),
+                other => AdapterError::IoError(std::io::Error::other(other.to_string())),
+            })
     }
 
     fn search(&self, query: &str, opts: &SearchOptions) -> Result<Vec<SearchHit>, AdapterError> {
@@ -1211,3 +1217,33 @@ mod tests {
         assert!(hits.iter().any(|h| h.id == "001-auth"));
     }
 }
+
+#[cfg(test)]
+mod compliance {
+    use super::*;
+    use crate::adapter_compliance_tests;
+    use crate::adapters::test_harness::ComplianceOptions;
+    use tempfile::TempDir;
+
+    fn make_markdown_adapter() -> (MarkdownAdapter, TempDir) {
+        let dir = TempDir::new().expect("tempdir");
+        let specs = dir.path().join("specs");
+        std::fs::create_dir_all(&specs).expect("create specs dir");
+        let adapter = MarkdownAdapter::new(specs);
+        (adapter, dir)
+    }
+
+    fn markdown_options() -> ComplianceOptions {
+        ComplianceOptions {
+            status_active: "planned".into(),
+            status_alt: "in-progress".into(),
+            delete_is_archive: true,
+            supports_links: true,
+            link_type: link::DEPENDS_ON.into(),
+            link_target: "001-foundation".into(),
+            ..ComplianceOptions::default()
+        }
+    }
+
+    adapter_compliance_tests!(make_markdown_adapter, markdown_options());
+}

rust/leanspec-core/src/adapters/mod.rs

@@ -20,6 +20,9 @@ pub mod jira;
 pub mod markdown;
 pub mod registry;
 
+#[cfg(any(test, feature = "test-utils"))]
+pub mod test_harness;
+
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;