axis-synome 0.1.0.dev34__tar.gz → 0.1.0.dev35__tar.gz

{axis_synome-0.1.0.dev34 → axis_synome-0.1.0.dev35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev34
+Version: 0.1.0.dev35
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT

{axis_synome-0.1.0.dev34 → axis_synome-0.1.0.dev35}/WRITING_SPECS.md

@@ -14,6 +14,9 @@ This is to facilitate the following goals, paraphrased from the [Axis Synome Tec
 
 ## Core Principles
 
+> If you change this section, also update the distilled review bullets in
+> `.github/instructions/axis-synome.instructions.md`.
+
 Specs encode Atlas calculation rules directly in typed Python.
 They are declarative, deterministic, side‑effect‑free computations; no I/O or mutable state.
 
@@ -48,6 +51,9 @@ Relations are traversable: clients and tooling can evaluate predicates across th
 
 ### Documentation and Provenance
 
+> If you change this section, also update the distilled review bullets in
+> `.github/instructions/axis-synome.instructions.md`.
+
 - Prefer function docstrings for descriptive text. Put the human‑readable description of what a formula does into the function’s docstring. Docstrings are code‑adjacent, IDE/hover friendly, and can be used to generate documentation.
 - As functions are also math formulas and documentation from docstrs will also be used for the mathematical exposition, avoid Python specific terminology.
 - Avoid duplicating long‑form descriptions in metadata.

{axis_synome-0.1.0.dev34 → axis_synome-0.1.0.dev35}/pyproject.toml

@@ -74,3 +74,8 @@ select = [
     "PGH004",
 ]
 ignore = ["E402", "E501"]
+
+# Prefer inline suppressions over a [tool.ruff.lint.per-file-ignores] table:
+# put `# ruff: noqa: <CODE>` (file-level) or `# noqa: <CODE>` (line-level) in
+# the source file itself, with a short reason. Keeps the rationale next to the
+# code it justifies and avoids a central table that drifts as files move.

{axis_synome-0.1.0.dev34 → axis_synome-0.1.0.dev35}/src/axis_synome/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0.dev34'
-__version_tuple__ = version_tuple = (0, 1, 0, 'dev34')
+__version__ = version = '0.1.0.dev35'
+__version_tuple__ = version_tuple = (0, 1, 0, 'dev35')
 
 __commit_id__ = commit_id = None

axis_synome-0.1.0.dev35/src/axis_synome/spec_validator/check_source_uuids.py

@@ -0,0 +1,378 @@
+"""Verify each ``:source_uuid:`` in spec docstrings resolves to an ``id`` in the
+Atlas ``content/`` tree (one ``document.md`` per Atlas section, with YAML
+frontmatter carrying ``id: <uuid>``).
+"""
+
+# ruff: noqa: T201 -- CLI entry point legitimately prints to stdout/stderr.
+
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import re
+import sys
+from collections import defaultdict
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+# Canonical 8-4-4-4-12 hex UUID. Case-insensitive; we lowercase before compare.
+_UUID_RE = re.compile(
+    r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
+)
+
+# Generic reST field at the start of a docstring line: ``:name: value``.
+# ``name`` is restricted to identifier-shaped tokens so we don't match URLs etc.
+_FIELD_LINE_RE = re.compile(r"^:([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$")
+
+# Allowlist of recognised docstring field names. Anything else triggers a
+# warning so typos and unintended drift surface early.
+ALLOWED_DOCSTRING_FIELDS: frozenset[str] = frozenset({"source_uuid"})
+
+# YAML frontmatter ``id:`` field. We don't pull in a YAML parser for one line;
+# the field is always emitted as ``id: <uuid>`` by the Atlas decompose tool.
+_FRONTMATTER_ID_RE = re.compile(r"^id:\s+(" + _UUID_RE.pattern + r")\s*$")
+
+# Defaults derived from this file's location so the CLI works from any cwd.
+# `parents` indices: [0]=spec_validator, [1]=axis_synome (under src),
+# [2]=src, [3]=axis_synome (package dir), [4]=python, [5]=repo root.
+_HERE = Path(__file__).resolve()
+DEFAULT_SPEC_ROOT: Path = _HERE.parents[1] / "spec"
+DEFAULT_CONTENT_ROOT: Path = _HERE.parents[5] / "content"
+
+
+@dataclass(frozen=True)
+class SpecRef:
+    """A single ``:source_uuid:`` reference extracted from a spec file."""
+
+    path: Path
+    lineno: int
+    symbol: str
+    uuid: str  # lowercased
+
+
+@dataclass(frozen=True)
+class FieldWarning:
+    """A non-fatal issue extracted alongside the spec references."""
+
+    path: Path
+    lineno: int
+    message: str
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    spec_refs: list[SpecRef]
+    atlas_uuids: frozenset[str]  # lowercased
+    missing: dict[str, list[SpecRef]]  # uuid -> refs that point at it
+    warnings: list[FieldWarning]
+
+
+# --------------------------------------------------------------------------- #
+# Spec-side extraction
+# --------------------------------------------------------------------------- #
+
+
+def _iter_spec_files(spec_root: Path) -> Iterator[Path]:
+    yield from sorted(p for p in spec_root.rglob("*.py") if "__pycache__" not in p.parts)
+
+
+def _process_docstring(
+    docstring: str,
+    *,
+    path: Path,
+    base_lineno: int,
+    symbol: str,
+) -> tuple[list[SpecRef], list[FieldWarning]]:
+    """Extract every reST ``:name: value`` field from a docstring.
+
+    For ``:source_uuid:`` we yield a :class:`SpecRef` (with a malformed-UUID
+    warning if the value isn't canonical 8-4-4-4-12 hex). For any other field
+    name we yield an "unknown field" warning so the allowlist in
+    :data:`ALLOWED_DOCSTRING_FIELDS` stays the single point of truth.
+    """
+    refs: list[SpecRef] = []
+    warnings: list[FieldWarning] = []
+    for offset, raw in enumerate(docstring.splitlines()):
+        line = raw.strip()
+        match = _FIELD_LINE_RE.match(line)
+        if not match:
+            continue
+        name = match.group(1)
+        value = match.group(2).strip()
+        lineno = base_lineno + offset
+
+        if name == "source_uuid":
+            uuid_match = _UUID_RE.fullmatch(value)
+            if uuid_match is None:
+                warnings.append(
+                    FieldWarning(
+                        path=path,
+                        lineno=lineno,
+                        message=(
+                            f"':source_uuid:' value is not a canonical 8-4-4-4-12 "
+                            f"hex UUID: {value!r}"
+                        ),
+                    )
+                )
+                continue
+            refs.append(
+                SpecRef(
+                    path=path,
+                    lineno=lineno,
+                    symbol=symbol,
+                    uuid=value.lower(),
+                )
+            )
+            continue
+
+        if name not in ALLOWED_DOCSTRING_FIELDS:
+            warnings.append(
+                FieldWarning(
+                    path=path,
+                    lineno=lineno,
+                    message=(
+                        f"unknown docstring field ':{name}:' — "
+                        f"allowed fields: {sorted(ALLOWED_DOCSTRING_FIELDS)}"
+                    ),
+                )
+            )
+
+    return refs, warnings
+
+
+def _docstring_node(body: list[ast.stmt]) -> tuple[str, int] | None:
+    """Return ``(docstring, lineno)`` if first stmt is a bare string-literal Expr."""
+    if not body:
+        return None
+    first = body[0]
+    if (
+        isinstance(first, ast.Expr)
+        and isinstance(first.value, ast.Constant)
+        and isinstance(first.value.value, str)
+    ):
+        return first.value.value, first.value.lineno
+    return None
+
+
+def _trailing_const_docstrings(body: list[ast.stmt]) -> Iterator[tuple[str, str, int]]:
+    """Yield ``(target_name, docstring, lineno)`` for ``X: Final[...] = v`` followed by ``\"\"\"...\"\"\"``.
+
+    Mirrors :class:`SpecChecker._validate_constant_docstrings` but only needs
+    the ``(name, docstring)`` pairs — we don't enforce structure here.
+    """
+    for prev, curr in zip(body, body[1:], strict=False):
+        if not (
+            isinstance(curr, ast.Expr)
+            and isinstance(curr.value, ast.Constant)
+            and isinstance(curr.value.value, str)
+        ):
+            continue
+        target_name: str | None = None
+        if isinstance(prev, ast.AnnAssign) and isinstance(prev.target, ast.Name):
+            target_name = prev.target.id
+        elif (
+            isinstance(prev, ast.Assign)
+            and len(prev.targets) == 1
+            and isinstance(prev.targets[0], ast.Name)
+        ):
+            target_name = prev.targets[0].id
+        if target_name is not None:
+            yield target_name, curr.value.value, curr.value.lineno
+
+
+def extract_spec_refs(path: Path) -> tuple[list[SpecRef], list[FieldWarning]]:
+    """Extract every ``:source_uuid:`` reference (and field warnings) from one spec file."""
+    source = path.read_text(encoding="utf-8")
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError as exc:
+        return [], [
+            FieldWarning(path=path, lineno=exc.lineno or 0, message=f"syntax error: {exc.msg}")
+        ]
+
+    refs: list[SpecRef] = []
+    warnings: list[FieldWarning] = []
+
+    module_doc = _docstring_node(tree.body)
+    if module_doc is not None:
+        text, lineno = module_doc
+        r, w = _process_docstring(text, path=path, base_lineno=lineno, symbol="<module>")
+        refs.extend(r)
+        warnings.extend(w)
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            doc = _docstring_node(node.body)
+            if doc is not None:
+                text, lineno = doc
+                r, w = _process_docstring(text, path=path, base_lineno=lineno, symbol=node.name)
+                refs.extend(r)
+                warnings.extend(w)
+        if isinstance(node, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            for name, text, lineno in _trailing_const_docstrings(list(node.body)):
+                r, w = _process_docstring(text, path=path, base_lineno=lineno, symbol=name)
+                refs.extend(r)
+                warnings.extend(w)
+
+    return refs, warnings
+
+
+# --------------------------------------------------------------------------- #
+# Atlas-side extraction
+# --------------------------------------------------------------------------- #
+
+
+def extract_atlas_uuids(content_root: Path) -> frozenset[str]:
+    """Extract ``id`` UUIDs from YAML frontmatter of every ``document.md`` under
+    ``content_root``. ``_index.md`` files (navigation only) are skipped.
+    """
+    uuids: set[str] = set()
+    for path in sorted(content_root.rglob("document.md")):
+        with path.open(encoding="utf-8") as fh:
+            if fh.readline().rstrip("\r\n") != "---":
+                continue
+            for raw in fh:
+                line = raw.rstrip("\r\n")
+                if line == "---":
+                    break
+                match = _FRONTMATTER_ID_RE.match(line)
+                if match:
+                    uuids.add(match.group(1).lower())
+                    break
+    return frozenset(uuids)
+
+
+# --------------------------------------------------------------------------- #
+# Orchestration
+# --------------------------------------------------------------------------- #
+
+
+def check(
+    spec_root: Path,
+    content_root: Path | None,
+) -> CheckResult:
+    """Run extraction on both sides and compute the missing / warning sets.
+
+    If ``content_root`` is ``None`` the Atlas side is treated as empty and no
+    "missing" entries are produced — callers decide whether that's an error.
+    """
+    spec_refs: list[SpecRef] = []
+    warnings: list[FieldWarning] = []
+    for path in _iter_spec_files(spec_root):
+        r, w = extract_spec_refs(path)
+        spec_refs.extend(r)
+        warnings.extend(w)
+
+    by_uuid: dict[str, list[SpecRef]] = defaultdict(list)
+    for ref in spec_refs:
+        by_uuid[ref.uuid].append(ref)
+
+    # Duplicate-UUID across distinct *files* → warning. Multiple symbols in
+    # the same module pointing at the same Atlas section is the natural pattern
+    # (e.g. an arithmetic formula and its boolean predicate variant); only
+    # cross-file reuse is suspicious enough to surface.
+    for uuid, refs in by_uuid.items():
+        files = {r.path for r in refs}
+        if len(files) > 1:
+            sample = refs[0]
+            others = [r for r in refs if r.path != sample.path]
+            other_locations = ", ".join(f"{r.path}:{r.lineno}" for r in others)
+            warnings.append(
+                FieldWarning(
+                    path=sample.path,
+                    lineno=sample.lineno,
+                    message=(
+                        f"UUID {uuid} reused across distinct files (also at {other_locations})"
+                    ),
+                )
+            )
+
+    if content_root is None:
+        atlas_uuids: frozenset[str] = frozenset()
+        missing: dict[str, list[SpecRef]] = {}
+    else:
+        atlas_uuids = extract_atlas_uuids(content_root)
+        missing = {uuid: refs for uuid, refs in by_uuid.items() if uuid not in atlas_uuids}
+
+    return CheckResult(
+        spec_refs=spec_refs,
+        atlas_uuids=atlas_uuids,
+        missing=missing,
+        warnings=warnings,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# CLI
+# --------------------------------------------------------------------------- #
+
+
+def _format_missing(missing: dict[str, list[SpecRef]]) -> str:
+    lines = ["ERROR: spec :source_uuid: values not found in the Atlas content tree:"]
+    for uuid in sorted(missing):
+        refs = missing[uuid]
+        lines.append(f"  {uuid}")
+        for ref in refs:
+            lines.append(f"    {ref.path}:{ref.lineno} ({ref.symbol})")
+    return "\n".join(lines)
+
+
+def _emit_map(result: CheckResult, path: Path) -> None:
+    payload = {
+        "spec_to_atlas": [
+            {
+                "uuid": ref.uuid,
+                "spec_path": str(ref.path),
+                "lineno": ref.lineno,
+                "symbol": ref.symbol,
+            }
+            for ref in sorted(result.spec_refs, key=lambda r: (str(r.path), r.lineno))
+        ],
+    }
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="check-source-uuids",
+        description="Verify spec :source_uuid: references resolve to UUIDs in the Atlas content tree.",
+    )
+    parser.add_argument(
+        "--emit-map",
+        type=Path,
+        default=None,
+        help="Optional path to write a JSON spec↔atlas map.",
+    )
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    if not DEFAULT_SPEC_ROOT.is_dir():
+        print(f"ERROR: spec root not found: {DEFAULT_SPEC_ROOT}", file=sys.stderr)
+        return 2
+    if not DEFAULT_CONTENT_ROOT.is_dir():
+        print(f"ERROR: Atlas content tree not found: {DEFAULT_CONTENT_ROOT}", file=sys.stderr)
+        return 2
+
+    result = check(DEFAULT_SPEC_ROOT, DEFAULT_CONTENT_ROOT)
+
+    for warn in result.warnings:
+        print(f"WARN: {warn.path}:{warn.lineno}: {warn.message}", file=sys.stderr)
+
+    if args.emit_map is not None:
+        _emit_map(result, args.emit_map)
+
+    if result.missing:
+        print(_format_missing(result.missing), file=sys.stderr)
+        return 1
+
+    print(
+        f"OK: all {len(result.spec_refs)} spec :source_uuid: values "
+        f"({len({r.uuid for r in result.spec_refs})} unique) "
+        f"resolve to documents under {DEFAULT_CONTENT_ROOT}."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{axis_synome-0.1.0.dev34 → axis_synome-0.1.0.dev35}/src/axis_synome.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev34
+Version: 0.1.0.dev35
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT

{axis_synome-0.1.0.dev34 → axis_synome-0.1.0.dev35}/src/axis_synome.egg-info/SOURCES.txt

@@ -55,6 +55,7 @@ src/axis_synome/spec_support/runtime/base.py
 src/axis_synome/spec_support/runtime/math.py
 src/axis_synome/spec_support/runtime/reference.py
 src/axis_synome/spec_validator/__init__.py
+src/axis_synome/spec_validator/check_source_uuids.py
 src/axis_synome/spec_validator/checker.py
 src/axis_synome/spec_validator/flake8_plugin.py
 src/axis_synome/spec_validator/python_subset.py
@@ -80,6 +81,7 @@ tests/axis_synome/spec_support/__init__.py
 tests/axis_synome/spec_support/runtime/__init__.py
 tests/axis_synome/spec_support/runtime/test_base.py
 tests/axis_synome/spec_support/runtime/test_math.py
+tests/axis_synome/spec_validator/test_check_source_uuids.py
 tests/axis_synome/spec_validator/test_checker.py
 tests/axis_synome/spec_validator/test_flake8_plugin.py
 tests/axis_synome/suraf/__init__.py

axis_synome-0.1.0.dev35/tests/axis_synome/spec_validator/test_check_source_uuids.py

@@ -0,0 +1,376 @@
+"""Tests for :mod:`axis_synome.spec_validator.check_source_uuids`."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from axis_synome.spec_validator import check_source_uuids as mod
+from axis_synome.spec_validator.check_source_uuids import (
+    ALLOWED_DOCSTRING_FIELDS,
+    check,
+    extract_atlas_uuids,
+    extract_spec_refs,
+    main,
+)
+
+
+def _write(p: Path, text: str) -> Path:
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(text, encoding="utf-8")
+    return p
+
+
+def _write_doc(content_root: Path, doc_no: str, uuid: str) -> Path:
+    """Write a minimal Atlas content document with the given frontmatter id."""
+    return _write(
+        content_root / doc_no / "document.md",
+        f"---\nid: {uuid}\ndocNo: {doc_no}\n---\n\n# {doc_no}\n",
+    )
+
+
+def _write_content_tree(content_root: Path, uuids: list[str]) -> Path:
+    """Lay out a fake Atlas content/ tree with one document per uuid."""
+    for i, uuid in enumerate(uuids):
+        _write_doc(content_root, f"X/{i}", uuid)
+    return content_root
+
+
+# --------------------------------------------------------------------------- #
+# extract_spec_refs
+# --------------------------------------------------------------------------- #
+
+
+def test_extract_function_docstring_uuid(tmp_path: Path) -> None:
+    spec = _write(
+        tmp_path / "f.py",
+        '''def foo() -> int:
+    """Summary.
+
+    :source_uuid: 11111111-2222-3333-4444-555555555555
+    """
+    return 1
+''',
+    )
+    refs, warnings = extract_spec_refs(spec)
+    assert warnings == []
+    assert len(refs) == 1
+    ref = refs[0]
+    assert ref.uuid == "11111111-2222-3333-4444-555555555555"
+    assert ref.symbol == "foo"
+    assert ref.path == spec
+    # Line number is the docstring line containing :source_uuid:
+    assert ref.lineno == 4
+
+
+def test_extract_module_and_class_docstrings(tmp_path: Path) -> None:
+    spec = _write(
+        tmp_path / "f.py",
+        '''"""Module doc.
+
+:source_uuid: AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE
+"""
+
+class C:
+    """Class doc.
+
+    :source_uuid: 11111111-1111-1111-1111-111111111111
+    """
+    pass
+''',
+    )
+    refs, warnings = extract_spec_refs(spec)
+    assert warnings == []
+    by_symbol = {r.symbol: r for r in refs}
+    # Case-insensitive: extracted lowercased
+    assert by_symbol["<module>"].uuid == "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+    assert by_symbol["C"].uuid == "11111111-1111-1111-1111-111111111111"
+
+
+def test_extract_final_parameter_docstring(tmp_path: Path) -> None:
+    spec = _write(
+        tmp_path / "f.py",
+        '''from typing import Final
+
+BETA: Final[float] = 0.3
+""":source_uuid: 22222222-3333-4444-5555-666666666666"""
+''',
+    )
+    refs, warnings = extract_spec_refs(spec)
+    assert warnings == []
+    assert len(refs) == 1
+    assert refs[0].symbol == "BETA"
+    assert refs[0].uuid == "22222222-3333-4444-5555-666666666666"
+
+
+def test_unknown_field_warns(tmp_path: Path) -> None:
+    spec = _write(
+        tmp_path / "f.py",
+        '''def foo() -> int:
+    """Summary.
+
+    :source_uid: 11111111-2222-3333-4444-555555555555
+    :returns: nothing important
+    """
+    return 1
+''',
+    )
+    refs, warnings = extract_spec_refs(spec)
+    assert refs == []
+    field_names = sorted(
+        w.message.split("'")[1] for w in warnings if "unknown docstring field" in w.message
+    )
+    assert field_names == [":returns:", ":source_uid:"]
+    # Allowlist sanity: source_uuid is the only currently-permitted field.
+    assert frozenset({"source_uuid"}) == ALLOWED_DOCSTRING_FIELDS
+
+
+def test_malformed_uuid_warns(tmp_path: Path) -> None:
+    spec = _write(
+        tmp_path / "f.py",
+        '''def foo() -> int:
+    """:source_uuid: not-a-uuid-but-36-chars-long-aaaaaaa"""
+    return 1
+''',
+    )
+    refs, warnings = extract_spec_refs(spec)
+    assert refs == []
+    assert len(warnings) == 1
+    assert "not a canonical" in warnings[0].message
+
+
+def test_uuid_outside_docstring_ignored(tmp_path: Path) -> None:
+    spec = _write(
+        tmp_path / "f.py",
+        """# :source_uuid: 11111111-2222-3333-4444-555555555555
+X = 1  # :source_uuid: 11111111-2222-3333-4444-555555555555
+""",
+    )
+    refs, warnings = extract_spec_refs(spec)
+    assert refs == []
+    assert warnings == []
+
+
+def test_pycache_skipped(tmp_path: Path) -> None:
+    _write(
+        tmp_path / "__pycache__" / "x.py",
+        '''def f():\n    """:source_uuid: 11111111-2222-3333-4444-555555555555"""\n    pass\n''',
+    )
+    result = check(tmp_path, content_root=None)
+    assert result.spec_refs == []
+
+
+# --------------------------------------------------------------------------- #
+# extract_atlas_uuids
+# --------------------------------------------------------------------------- #
+
+
+def test_atlas_extracts_id_from_document_frontmatter(tmp_path: Path) -> None:
+    content_root = tmp_path / "content"
+    _write_doc(content_root, "A/1", "11111111-2222-3333-4444-555555555555")
+    _write_doc(content_root, "NR/2", "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE")
+    # _index.md files lack `id:` and should be ignored even if walked.
+    _write(content_root / "A" / "_index.md", "---\ntype: index\n---\n")
+    # Body-text mention of `id: <uuid>` outside frontmatter must not match.
+    _write_doc(content_root, "A/2", "22222222-2222-3333-4444-555555555555")
+    body_with_fake_id = (
+        "---\nid: 33333333-3333-3333-4444-555555555555\n---\n\n"
+        "Some prose mentioning id: 99999999-9999-9999-9999-999999999999 in body.\n"
+    )
+    _write(content_root / "A" / "3" / "document.md", body_with_fake_id)
+
+    uuids = extract_atlas_uuids(content_root)
+    assert uuids == frozenset({
+        "11111111-2222-3333-4444-555555555555",
+        "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+        "22222222-2222-3333-4444-555555555555",
+        "33333333-3333-3333-4444-555555555555",
+    })
+
+
+# --------------------------------------------------------------------------- #
+# check() — end-to-end behavior
+# --------------------------------------------------------------------------- #
+
+
+def _fixture_pair(
+    tmp_path: Path, *, atlas_uuids: list[str], spec_uuids: list[str]
+) -> tuple[Path, Path]:
+    spec_root = tmp_path / "spec"
+    for i, uuid in enumerate(spec_uuids):
+        _write(
+            spec_root / f"f_{i}.py",
+            f'''def f_{i}() -> int:
+    """:source_uuid: {uuid}"""
+    return {i}
+''',
+        )
+    content_root = _write_content_tree(tmp_path / "content", atlas_uuids)
+    return spec_root, content_root
+
+
+def test_check_happy_path(tmp_path: Path) -> None:
+    spec_root, content_root = _fixture_pair(
+        tmp_path,
+        atlas_uuids=["11111111-2222-3333-4444-555555555555"],
+        spec_uuids=["11111111-2222-3333-4444-555555555555"],
+    )
+    result = check(spec_root, content_root)
+    assert result.missing == {}
+    assert result.warnings == []
+
+
+def test_check_missing_uuid_reports(tmp_path: Path) -> None:
+    spec_root, content_root = _fixture_pair(
+        tmp_path,
+        atlas_uuids=["11111111-2222-3333-4444-555555555555"],
+        spec_uuids=["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"],
+    )
+    result = check(spec_root, content_root)
+    assert list(result.missing) == ["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"]
+    refs = result.missing["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"]
+    assert len(refs) == 1
+    assert refs[0].symbol == "f_0"
+
+
+def test_check_case_insensitive(tmp_path: Path) -> None:
+    spec_root, content_root = _fixture_pair(
+        tmp_path,
+        atlas_uuids=["AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"],
+        spec_uuids=["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"],
+    )
+    result = check(spec_root, content_root)
+    assert result.missing == {}
+
+
+def test_check_duplicate_uuid_warns_only_across_distinct_files(tmp_path: Path) -> None:
+    spec_root = tmp_path / "spec"
+    # Two functions in different files share a UUID → cross-file → warn.
+    _write(
+        spec_root / "a.py",
+        '''def fa() -> int:
+    """:source_uuid: 11111111-2222-3333-4444-555555555555"""
+    return 1
+''',
+    )
+    _write(
+        spec_root / "b.py",
+        '''def fb() -> int:
+    """:source_uuid: 11111111-2222-3333-4444-555555555555"""
+    return 2
+''',
+    )
+    content_root = _write_content_tree(
+        tmp_path / "content", ["11111111-2222-3333-4444-555555555555"]
+    )
+    result = check(spec_root, content_root)
+    assert result.missing == {}
+    dup = [w for w in result.warnings if "reused across distinct files" in w.message]
+    assert len(dup) == 1
+
+
+def test_check_same_file_repeating_uuid_no_warning(tmp_path: Path) -> None:
+    # Same Atlas UUID across multiple functions in the same module is the
+    # natural pattern (e.g. an arithmetic formula and its boolean predicate
+    # variant); should not warn.
+    spec_root = tmp_path / "spec"
+    _write(
+        spec_root / "a.py",
+        '''def f1() -> int:
+    """:source_uuid: 11111111-2222-3333-4444-555555555555"""
+    return 1
+
+
+def f2() -> int:
+    """:source_uuid: 11111111-2222-3333-4444-555555555555"""
+    return 2
+''',
+    )
+    content_root = _write_content_tree(
+        tmp_path / "content", ["11111111-2222-3333-4444-555555555555"]
+    )
+    result = check(spec_root, content_root)
+    dup = [w for w in result.warnings if "reused across distinct" in w.message]
+    assert dup == []
+
+
+# --------------------------------------------------------------------------- #
+# CLI / main()
+# --------------------------------------------------------------------------- #
+
+
+def test_main_ok(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    spec_root, content_root = _fixture_pair(
+        tmp_path,
+        atlas_uuids=["11111111-2222-3333-4444-555555555555"],
+        spec_uuids=["11111111-2222-3333-4444-555555555555"],
+    )
+    monkeypatch.setattr(mod, "DEFAULT_SPEC_ROOT", spec_root)
+    monkeypatch.setattr(mod, "DEFAULT_CONTENT_ROOT", content_root)
+    rc = main([])
+    assert rc == 0
+    assert "OK:" in capsys.readouterr().out
+
+
+def test_main_missing_returns_1(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    spec_root, content_root = _fixture_pair(
+        tmp_path,
+        atlas_uuids=[],
+        spec_uuids=["11111111-2222-3333-4444-555555555555"],
+    )
+    # Empty content/ wouldn't exist on disk after _write_content_tree([]); make
+    # sure the directory exists so the existence check passes.
+    content_root.mkdir(exist_ok=True)
+    monkeypatch.setattr(mod, "DEFAULT_SPEC_ROOT", spec_root)
+    monkeypatch.setattr(mod, "DEFAULT_CONTENT_ROOT", content_root)
+    rc = main([])
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "11111111-2222-3333-4444-555555555555" in err
+    assert "f_0" in err  # symbol is reported
+
+
+def test_main_missing_content_root_returns_2(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    spec_root = tmp_path / "spec"
+    spec_root.mkdir()
+    monkeypatch.setattr(mod, "DEFAULT_SPEC_ROOT", spec_root)
+    monkeypatch.setattr(mod, "DEFAULT_CONTENT_ROOT", tmp_path / "missing-content")
+    rc = main([])
+    assert rc == 2
+    assert "not found" in capsys.readouterr().err
+
+
+def test_main_emit_map(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    spec_root, content_root = _fixture_pair(
+        tmp_path,
+        atlas_uuids=["11111111-2222-3333-4444-555555555555"],
+        spec_uuids=["11111111-2222-3333-4444-555555555555"],
+    )
+    monkeypatch.setattr(mod, "DEFAULT_SPEC_ROOT", spec_root)
+    monkeypatch.setattr(mod, "DEFAULT_CONTENT_ROOT", content_root)
+    out = tmp_path / "map.json"
+    rc = main(["--emit-map", str(out)])
+    assert rc == 0
+    payload = json.loads(out.read_text(encoding="utf-8"))
+    assert payload.keys() == {"spec_to_atlas"}
+    entries = payload["spec_to_atlas"]
+    assert len(entries) == 1
+    assert entries[0]["uuid"] == "11111111-2222-3333-4444-555555555555"
+    assert entries[0]["symbol"] == "f_0"