test(sync): guard docs against code drift with sync tests

Add two compile-enforced anti-rot tests:

- `supported_languages_doc_lists_each_primary_extension` (in
  `src/lang.rs`) fails if a language's primary extension disappears from
  `docs/supported-languages.md`.
- `ffi_markers_are_documented` (in `src/ffi/sync_tests.rs`) fails if an
  FFI marker or name prefix in the `SPECS` registry is absent from
  `docs/ffi-support-matrix.md`.

Both tests require the doc to be updated in the same PR as the code,
making the "hand-maintained" caveat enforced rather than advisory.

To support the first test, expose `Language::ALL` (exhaustive slice of
every variant, guarded by `all_is_exhaustive`) and `Language::extensions`
(per-variant primary + alternate extensions). `from_extension` is
re-derived from `extensions()` to keep the mapping single-sourced.

Update `docs/ffi-support-matrix.md` and `CONTRIBUTING.md` to reflect
that the docs are now test-backed rather than purely hand-maintained.

Author: farhan-syah

CONTRIBUTING.md

@@ -90,7 +90,7 @@ Every public-facing file starts with `// SPDX-License-Identifier: Apache-2.0`.
 
 This is the most common contribution and it's mechanical once a grammar exists. The resolver is language-agnostic, so **cross-file edges work for free** once extraction emits correct facts.
 
-> **Before you start:** check [`docs/supported-languages.md`](docs/supported-languages.md) for what's already covered (plus the candidate, not-feasible, and out-of-scope lists), and [`docs/ffi-support-matrix.md`](docs/ffi-support-matrix.md) for cross-language FFI boundaries. Both are hand-maintained against the code (`src/lang.rs` is the canonical language set) — update them in the same PR when you add a language or an FFI boundary.
+> **Before you start:** check [`docs/supported-languages.md`](docs/supported-languages.md) for what's already covered (plus the candidate, not-feasible, and out-of-scope lists), and [`docs/ffi-support-matrix.md`](docs/ffi-support-matrix.md) for cross-language FFI boundaries. Both are guarded by sync tests — `supported-languages.md` against the `Language` enum in `src/lang.rs`, and `ffi-support-matrix.md` against the per-ABI `SPECS` registry in `src/ffi/` — so adding a language or an FFI boundary without updating the matching doc in the same PR fails the test.
 
 > **First: is there a usable grammar?** code2graph pins `tree-sitter` to `>=0.24, <0.27`. A grammar crate must be compatible with that range. If no compatible grammar exists, read [When a language has no usable grammar](#when-a-language-has-no-usable-grammar) before writing any code.
 

docs/ffi-support-matrix.md

@@ -3,9 +3,10 @@
 Which cross-language (cross-runtime) call boundaries code2graph bridges today — honestly, with what
 is **not yet** covered.
 
-> The canonical source is `FfiAbi` + `FfiAbi::consumers()` in [`src/graph/types.rs`](../src/graph/types.rs)
-> and the export markers in the per-language extractors. This page is hand-maintained; if it
-> disagrees with the code, the code wins.
+> The canonical source is the per-ABI registry in [`src/ffi/`](../src/ffi/) — one `AbiSpec` per ABI
+> (the `SPECS` table), carrying its consumer languages and export markers — plus the `FfiAbi` enum in
+> [`src/graph/types.rs`](../src/graph/types.rs). A sync test (`ffi_markers_are_documented`) fails if a
+> marker on this page drifts from `SPECS`; if the page still disagrees with the code, the code wins.
 
 ## What an FFI bridge is
 
@@ -16,7 +17,8 @@ one language to a definition in another, **deterministically**:
 - The **export** side is grounded in a real syntactic marker (e.g. Rust `#[no_mangle]`), recorded as
   a neutral `FfiExport { symbol, abi, export_name }`.
 - The **consumer** side is matched by the exported ABI name, and only in a language that actually
-  consumes that ABI (`FfiAbi::consumers()`), so a C call never binds to a Python-only export.
+  consumes that ABI (its `consumers` in the [`src/ffi/`](../src/ffi/) registry), so a C call never
+  binds to a Python-only export.
 - Same-language use is _not_ a bridge (that's an ordinary call).
 - Every bridge edge carries `Provenance::FfiBridge` and an honest `Confidence`: `Scoped` when the
   export is unique, `NameOnly` when several share the name. Never dressed up as precise.
@@ -97,8 +99,10 @@ the edges of the map; ranked roughly by how common the boundary is.
   (`lib.foo()`, `C.foo()`), a different call shape than the bare-name match used today.
 - **WebAssembly component model / WIT imports** (beyond `wasm-bindgen` exports).
 
-The architecture extends cleanly: each new boundary is one `FfiAbi` variant + a marker recognised in
-the relevant extractor + an entry in `consumers()`. The resolver itself is generic.
+The architecture extends cleanly: a new boundary is one `FfiAbi` variant + one `src/ffi/<abi>.rs` spec
+file (its consumer languages + export markers) + one line in the `SPECS` registry. The producer
+extractor keeps its syntactic walk and calls into `ffi::` to classify the marker; the resolver is
+generic — no growing match and no inline per-ABI block to extend.
 
 ## See also
 

src/ffi/mod.rs

@@ -10,4 +10,7 @@ mod python;
 mod spec;
 mod wasm;
 
+#[cfg(test)]
+mod sync_tests;
+
 pub(crate) use spec::{c_name_export_abi, consumers, rust_exports};

src/ffi/sync_tests.rs

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+//! Anti-rot: every FFI marker/prefix in `SPECS` must be named in the matrix doc.
+use super::spec::SPECS;
+
+fn read_doc(rel: &str) -> String {
+    let path = format!("{}/{}", env!("CARGO_MANIFEST_DIR"), rel);
+    std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("cannot read {path}: {e}"))
+}
+
+#[test]
+fn ffi_markers_are_documented() {
+    let doc = read_doc("docs/ffi-support-matrix.md");
+    for spec in SPECS {
+        for marker in spec.rust_attr_markers {
+            assert!(
+                doc.contains(marker),
+                "FFI marker `{marker}` (abi {:?}) is missing from \
+                 docs/ffi-support-matrix.md — document it there",
+                spec.abi,
+            );
+        }
+        if let Some(prefix) = spec.name_prefix {
+            assert!(
+                doc.contains(prefix),
+                "FFI name prefix `{prefix}` (abi {:?}) is missing from \
+                 docs/ffi-support-matrix.md — document the `{prefix}*` rule there",
+                spec.abi,
+            );
+        }
+    }
+}

src/lang.rs

@@ -34,6 +34,64 @@ pub enum Language {
 }
 
 impl Language {
+    /// Every `Language` variant. Kept exhaustive by the `all_is_exhaustive` test.
+    pub const ALL: &[Language] = &[
+        Language::Rust,
+        Language::TypeScript,
+        Language::JavaScript,
+        Language::Python,
+        Language::Go,
+        Language::Shell,
+        Language::C,
+        Language::Cpp,
+        Language::Java,
+        Language::Ruby,
+        Language::Php,
+        Language::Swift,
+        Language::Kotlin,
+        Language::Solidity,
+        Language::Sql,
+        Language::Hcl,
+        Language::CSharp,
+        Language::Scala,
+        Language::Dart,
+        Language::Lua,
+        Language::Luau,
+        Language::Pascal,
+        Language::Svelte,
+    ];
+
+    /// This variant's file extensions (without the leading dot); the first entry
+    /// is the primary/canonical extension. Single source of truth for
+    /// `from_extension` — keep in sync with the extensions accepted there.
+    pub fn extensions(self) -> &'static [&'static str] {
+        match self {
+            Language::Rust => &["rs"],
+            Language::TypeScript => &["ts", "tsx"],
+            Language::JavaScript => &["js", "jsx", "mjs", "cjs"],
+            Language::Python => &["py", "pyi"],
+            Language::Go => &["go"],
+            Language::Shell => &["sh", "bash", "zsh"],
+            Language::C => &["c", "h"],
+            Language::Cpp => &["cc", "cpp", "cxx", "hh", "hpp", "hxx"],
+            Language::Java => &["java"],
+            Language::Ruby => &["rb"],
+            Language::Php => &["php"],
+            Language::Swift => &["swift"],
+            Language::Kotlin => &["kt", "kts"],
+            Language::Solidity => &["sol"],
+            Language::Sql => &["sql"],
+            Language::Hcl => &["tf", "hcl", "tfvars"],
+            Language::CSharp => &["cs"],
+            Language::Scala => &["scala", "sc"],
+            Language::Dart => &["dart"],
+            Language::Lua => &["lua"],
+            Language::Luau => &["luau"],
+            Language::Pascal => &["pas", "dpr", "dpk", "lpr"],
+            Language::Svelte => &["svelte"],
+        }
+    }
+
     /// Canonical lowercase language tag (stable; used in `SymbolKey.lang`).
     pub fn as_str(self) -> &'static str {
         match self {
@@ -64,33 +122,12 @@ impl Language {
     }
 
     /// Map a lowercase file extension to a `Language`, or `None` if unknown.
+    /// Derives from `extensions()` so the mapping has a single source of truth.
     pub fn from_extension(ext: &str) -> Option<Self> {
-        match ext {
-            "rs" => Some(Self::Rust),
-            "ts" | "tsx" => Some(Self::TypeScript),
-            "js" | "jsx" | "mjs" | "cjs" => Some(Self::JavaScript),
-            "py" | "pyi" => Some(Self::Python),
-            "go" => Some(Self::Go),
-            "sh" | "bash" | "zsh" => Some(Self::Shell),
-            "c" | "h" => Some(Self::C),
-            "cc" | "cpp" | "cxx" | "hh" | "hpp" | "hxx" => Some(Self::Cpp),
-            "java" => Some(Self::Java),
-            "rb" => Some(Self::Ruby),
-            "php" => Some(Self::Php),
-            "swift" => Some(Self::Swift),
-            "kt" | "kts" => Some(Self::Kotlin),
-            "sol" => Some(Self::Solidity),
-            "sql" => Some(Self::Sql),
-            "tf" | "hcl" | "tfvars" => Some(Self::Hcl),
-            "cs" => Some(Self::CSharp),
-            "scala" | "sc" => Some(Self::Scala),
-            "dart" => Some(Self::Dart),
-            "lua" => Some(Self::Lua),
-            "luau" => Some(Self::Luau),
-            "pas" | "dpr" | "dpk" | "lpr" => Some(Self::Pascal),
-            "svelte" => Some(Self::Svelte),
-            _ => None,
-        }
+        Language::ALL
+            .iter()
+            .copied()
+            .find(|l| l.extensions().contains(&ext))
     }
 
     /// Map a file path to a `Language` via its extension.
@@ -116,4 +153,62 @@ mod tests {
     fn tag_is_stable_lowercase() {
         assert_eq!(Language::TypeScript.as_str(), "typescript");
     }
+
+    /// Compile-time guard: a new `Language` variant forces a new arm here (no
+    /// wildcard), where the contributor is reminded to also add it to `Language::ALL`.
+    fn assert_variant_in_all(l: Language) -> bool {
+        let listed = match l {
+            // EVERY variant must be listed here AND in `Language::ALL`.
+            Language::Rust
+            | Language::TypeScript
+            | Language::JavaScript
+            | Language::Python
+            | Language::Go
+            | Language::Shell
+            | Language::C
+            | Language::Cpp
+            | Language::Java
+            | Language::Ruby
+            | Language::Php
+            | Language::Swift
+            | Language::Kotlin
+            | Language::Solidity
+            | Language::Sql
+            | Language::Hcl
+            | Language::CSharp
+            | Language::Scala
+            | Language::Dart
+            | Language::Lua
+            | Language::Luau
+            | Language::Pascal
+            | Language::Svelte => true,
+        };
+        listed && Language::ALL.contains(&l)
+    }
+
+    #[test]
+    fn all_is_exhaustive() {
+        for &l in Language::ALL {
+            assert!(
+                assert_variant_in_all(l),
+                "variant missing from Language::ALL"
+            );
+        }
+    }
+
+    #[test]
+    fn supported_languages_doc_lists_each_primary_extension() {
+        let path = format!("{}/docs/supported-languages.md", env!("CARGO_MANIFEST_DIR"));
+        let doc =
+            std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("cannot read {path}: {e}"));
+        for &lang in Language::ALL {
+            let primary = lang.extensions()[0];
+            let token = format!("`.{primary}`"); // doc cells are backticked: `.rs`
+            assert!(
+                doc.contains(&token),
+                "language {lang:?} (primary ext .{primary}) is not listed in \
+                 docs/supported-languages.md — add its row and update the doc",
+            );
+        }
+    }
 }