csd-intent 0.4.0__py3-none-any.whl

csd_intent/__init__.py

@@ -0,0 +1,46 @@
+"""csd-intent - cross-runtime auditor for CSD intent specifications.
+
+Validates intent.yaml against CSD-INTENT-01 (schema check), confirms every
+@intent / intent() marker references a real claim (orphan check), and reports
+unattested claims by walking every test file in the project (coverage check).
+
+Nested projects: a repo may contain nested intent projects (a subdirectory with its
+own intent.yaml). ``audit_tree()`` discovers and audits each as its own project, so a
+nested project's markers are checked against its own intent.yaml rather than orphaning
+against the outer project's claims.
+
+Public API:
+    audit(project_dir, intent_path=None, test_dirs=None) -> AuditReport
+    audit_tree(project_dir) -> list[AuditReport]
+    AuditReport, AuditViolation
+    parse_intent_yaml(path)  # raises DuplicateKeyError on a repeated key
+    check_schema(claims)
+    collect_attestations(test_dirs)
+    find_nested_intent_projects(root)
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .audit import AuditReport, AuditViolation, audit, audit_tree
+from .schema import DuplicateKeyError, check_schema, parse_intent_yaml
+from .walker import collect_attestations, find_nested_intent_projects
+
+try:
+    __version__ = version("csd-intent")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "AuditReport",
+    "AuditViolation",
+    "DuplicateKeyError",
+    "__version__",
+    "audit",
+    "audit_tree",
+    "check_schema",
+    "collect_attestations",
+    "find_nested_intent_projects",
+    "parse_intent_yaml",
+]

csd_intent/audit.py

@@ -0,0 +1,194 @@
+"""Orchestrates schema + orphan + coverage checks into a single audit report."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+from .schema import DuplicateKeyError, check_schema, parse_intent_yaml, top_level_keys
+from .walker import collect_attestations, find_nested_intent_projects
+
+__all__ = [
+    "AuditReport",
+    "AuditViolation",
+    "ViolationKind",
+    "audit",
+    "audit_tree",
+]
+
+
+class ViolationKind(str, Enum):
+    SCHEMA = "schema"
+    ORPHAN = "orphan"
+    UNATTESTED = "unattested"
+
+
+@dataclass(frozen=True)
+class AuditViolation:
+    kind: ViolationKind
+    claim_id: str | None
+    message: str
+
+    def __str__(self) -> str:
+        prefix = self.claim_id or "intent.yaml"
+        return f"[{self.kind.value}] {prefix}: {self.message}"
+
+
+@dataclass
+class AuditReport:
+    """The result of a project audit. Empty `violations` = clean."""
+
+    intent_path: Path
+    claim_count: int
+    attested_claims: set[str] = field(default_factory=set)
+    orphan_refs: dict[str, list[str]] = field(default_factory=dict)
+    violations: list[AuditViolation] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.violations
+
+    @property
+    def unattested(self) -> list[str]:
+        return sorted(
+            v.claim_id
+            for v in self.violations
+            if v.kind == ViolationKind.UNATTESTED and v.claim_id
+        )
+
+    def format(self) -> str:
+        if self.ok:
+            return (
+                f"intent.yaml ({self.intent_path}): {self.claim_count} claims, "
+                f"{len(self.attested_claims)} attested. CLEAN."
+            )
+        by_kind: dict[ViolationKind, list[AuditViolation]] = {}
+        for v in self.violations:
+            by_kind.setdefault(v.kind, []).append(v)
+        lines = [
+            f"intent.yaml ({self.intent_path}): {self.claim_count} claims, "
+            f"{len(self.violations)} violation(s)."
+        ]
+        for kind in (ViolationKind.SCHEMA, ViolationKind.ORPHAN, ViolationKind.UNATTESTED):
+            items = by_kind.get(kind, [])
+            if not items:
+                continue
+            lines.append(f"\n{kind.value.upper()} ({len(items)}):")
+            for v in items:
+                lines.append(f"  {v}")
+        return "\n".join(lines)
+
+
+def audit(
+    project_dir: Path,
+    intent_path: Path | None = None,
+    test_dirs: list[Path] | None = None,
+) -> AuditReport:
+    """Audit a project's intent spec + test attestations.
+
+    Args:
+        project_dir: project root (used to resolve defaults).
+        intent_path: explicit intent.yaml location; defaults to ``project_dir/intent.yaml``.
+        test_dirs:   directories to scan for @intent / intent() markers; defaults to
+                     ``[project_dir]`` (the walker handles exclude rules).
+    """
+    project_dir = project_dir.resolve()
+    intent_path = (intent_path or project_dir / "intent.yaml").resolve()
+    test_dirs = test_dirs or [project_dir]
+
+    report = AuditReport(intent_path=intent_path, claim_count=0)
+
+    if not intent_path.exists():
+        report.violations.append(
+            AuditViolation(ViolationKind.SCHEMA, None, f"intent.yaml not found at {intent_path}")
+        )
+        return report
+
+    # A repeated key resolves last-wins in YAML itself, so the earlier claim is gone
+    # before any check runs and its markers now attest the survivor. Nothing further
+    # in this audit would be true of the spec its author wrote, so stop here (#12).
+    try:
+        claims = parse_intent_yaml(intent_path)
+    except DuplicateKeyError as exc:
+        report.violations.append(AuditViolation(ViolationKind.SCHEMA, None, str(exc)))
+        return report
+
+    report.claim_count = len(claims)
+
+    # A file present with nothing the parser recognises is schema drift, not an
+    # empty-but-valid project: report it loudly rather than a silent CLEAN (#5).
+    if not claims:
+        keys = top_level_keys(intent_path)
+        found = f"found keys: {', '.join(keys)}" if keys else "the file has no top-level keys"
+        report.violations.append(
+            AuditViolation(
+                ViolationKind.SCHEMA,
+                None,
+                f"intent.yaml has no top-level INT-* claims; {found}",
+            )
+        )
+
+    # Schema
+    for msg in check_schema(claims):
+        cid = msg.split(":", 1)[0] if ":" in msg else None
+        rest = msg.split(":", 1)[1].strip() if ":" in msg else msg
+        report.violations.append(AuditViolation(ViolationKind.SCHEMA, cid, rest))
+
+    # Attestations across all test dirs
+    attestations = collect_attestations(test_dirs)
+    claim_ids = set(claims.keys())
+    attested_ids = set(attestations.keys())
+    report.attested_claims = claim_ids & attested_ids
+
+    # Orphans: marker references a claim that does not exist
+    for cid in sorted(attested_ids - claim_ids):
+        refs = attestations.get(cid, [])
+        report.orphan_refs[cid] = refs
+        report.violations.append(
+            AuditViolation(
+                ViolationKind.ORPHAN,
+                cid,
+                f"test marker references unknown claim ({len(refs)} ref(s): {refs[:3]}{'...' if len(refs) > 3 else ''})",
+            )
+        )
+
+    # Unattested: claim has no marker anywhere.
+    # Only enforce for ACTIVE claims. Deprecated claims document a behaviour
+    # that no longer holds (no tests expected). Draft claims are pre-implementation
+    # placeholders (tests may not yet exist) - surface as informational but don't
+    # treat as a failing violation.
+    for cid in sorted(claim_ids - attested_ids):
+        status = str(claims[cid].get("status", "active"))
+        if status == "deprecated":
+            continue
+        if status == "draft":
+            continue
+        report.violations.append(
+            AuditViolation(
+                ViolationKind.UNATTESTED, cid, "no @intent / intent() marker references this claim"
+            )
+        )
+
+    return report
+
+
+def audit_tree(project_dir: Path) -> list[AuditReport]:
+    """Discover and audit every intent project at or below ``project_dir``.
+
+    The starting ``project_dir`` is audited as the root project (its marker scan is
+    bounded by any nested project subtrees). Each subdirectory that carries its own
+    ``intent.yaml`` is then audited as an independent project against the markers in
+    its own subtree (bounded, in turn, by any still-deeper nested projects). The result
+    is a complete, non-overlapping partition of the tree into projects.
+
+    Returns one :class:`AuditReport` per project, root first, then nested projects in a
+    deterministic (sorted) order. This is the auto-discovery path used by the CLI when no
+    explicit ``--intent`` / ``--tests-dir`` override is given. For the explicit
+    single-project case, call :func:`audit` directly.
+    """
+    project_dir = project_dir.resolve()
+    reports = [audit(project_dir)]
+    for nested in find_nested_intent_projects(project_dir):
+        reports.append(audit(nested))
+    return reports

csd_intent/cli.py

@@ -0,0 +1,158 @@
+"""CLI entry point for csd-intent.
+
+Usage:
+  csd-intent [PROJECT_DIR]
+             [--intent PATH]
+             [--tests-dir DIR]...
+             [--fail-on schema|orphan|unattested|any|none]
+             [--quiet]
+             [--version]
+
+Default ``PROJECT_DIR`` is the cwd. Default ``--fail-on`` is ``any`` (exit non-zero
+on any violation). Use ``--fail-on schema`` to only fail on schema problems and
+treat coverage gaps as warnings (matches the "intent before test" CSD workflow).
+
+Nested projects: when PROJECT_DIR contains nested intent projects (subdirectories with
+their own intent.yaml), each is discovered and audited as its own project against the
+markers in its own subtree. A per-project summary is printed and the process exits
+non-zero if *any* project has a failing violation. Passing ``--intent`` or
+``--tests-dir`` switches to an explicit single-project audit (no auto-discovery).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .audit import AuditReport, ViolationKind, audit, audit_tree
+
+_FAIL_MAP = {
+    "schema": {ViolationKind.SCHEMA},
+    "orphan": {ViolationKind.ORPHAN},
+    "unattested": {ViolationKind.UNATTESTED},
+    "any": {ViolationKind.SCHEMA, ViolationKind.ORPHAN, ViolationKind.UNATTESTED},
+    "none": set(),
+}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="csd-intent",
+        description="Audit a CSD intent project: schema + orphan + coverage checks.",
+    )
+    parser.add_argument(
+        "project_dir",
+        nargs="?",
+        default=".",
+        type=Path,
+        help="Project root (default: cwd).",
+    )
+    parser.add_argument(
+        "--intent",
+        type=Path,
+        default=None,
+        help=(
+            "Path to intent.yaml; a relative path is anchored to PROJECT_DIR "
+            "(default: PROJECT_DIR/intent.yaml)."
+        ),
+    )
+    parser.add_argument(
+        "--tests-dir",
+        dest="tests_dirs",
+        action="append",
+        type=Path,
+        default=None,
+        help=(
+            "Directory to scan for test markers; a relative path is anchored to "
+            "PROJECT_DIR (repeatable; default: PROJECT_DIR)."
+        ),
+    )
+    parser.add_argument(
+        "--fail-on",
+        choices=tuple(_FAIL_MAP.keys()),
+        default="any",
+        help="Which violation kinds cause a non-zero exit (default: any).",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress the per-violation report; only print the summary line.",
+    )
+    parser.add_argument("--version", action="store_true", help="Print version and exit.")
+    return parser
+
+
+def _print_report(report: AuditReport, quiet: bool) -> None:
+    if quiet:
+        print(
+            f"{report.intent_path}: {report.claim_count} claims, "
+            f"{len(report.violations)} violation(s)."
+        )
+    else:
+        print(report.format())
+
+
+def _has_failing_violation(report: AuditReport, fail_kinds: set[ViolationKind]) -> bool:
+    return any(v.kind in fail_kinds for v in report.violations)
+
+
+def _anchored(project_dir: Path, path: Path) -> Path:
+    """Anchor a relative path to the project root rather than the caller's cwd."""
+    return path if path.is_absolute() else project_dir / path
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    if args.version:
+        from . import __version__
+
+        print(__version__)
+        return 0
+
+    fail_kinds = _FAIL_MAP[args.fail_on]
+
+    # Explicit single-project mode: --intent / --tests-dir disables auto-discovery.
+    if args.intent is not None or args.tests_dirs is not None:
+        report = audit(
+            project_dir=args.project_dir,
+            intent_path=(
+                None if args.intent is None else _anchored(args.project_dir, args.intent)
+            ),
+            test_dirs=(
+                None
+                if args.tests_dirs is None
+                else [_anchored(args.project_dir, d) for d in args.tests_dirs]
+            ),
+        )
+        _print_report(report, args.quiet)
+        return 1 if _has_failing_violation(report, fail_kinds) else 0
+
+    # Auto-discovery mode: audit the root project plus any nested intent projects.
+    reports = audit_tree(args.project_dir)
+
+    # Backward-compatible single-project output when there is no nesting: identical
+    # to the pre-nesting behaviour (one report, no per-project banner).
+    if len(reports) == 1:
+        _print_report(reports[0], args.quiet)
+        return 1 if _has_failing_violation(reports[0], fail_kinds) else 0
+
+    # Multiple projects: per-project report plus an aggregate summary.
+    failed = 0
+    for i, report in enumerate(reports):
+        if i:
+            print()
+        _print_report(report, args.quiet)
+        if _has_failing_violation(report, fail_kinds):
+            failed += 1
+
+    clean = len(reports) - failed
+    print(
+        f"\n{len(reports)} project(s) audited: {clean} clean, {failed} with violation(s)."
+    )
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

csd_intent/schema.py

@@ -0,0 +1,196 @@
+"""CSD-INTENT-01 schema validation for intent.yaml claims.
+
+Validates the canonical claim shape:
+
+    INT-NNN:
+      version: X.Y.Z
+      status: draft | active | deprecated
+      statement: "..."             # required
+      rationale: "..."             # optional in CSD; recommended
+      test:
+        scope: unit | integration | e2e
+        component: "..."
+        type: invariant | behavior | contract
+      criticality: critical | high | medium | low
+
+The legacy flat shape (top-level `scope:` instead of nested `test.scope`) is
+accepted with a warning so projects can migrate incrementally.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Hashable
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+__all__ = [
+    "ID_PATTERN",
+    "VALID_CRITICALITY",
+    "VALID_SCOPE",
+    "VALID_STATUS",
+    "VALID_TYPE",
+    "VERSION_PATTERN",
+    "DuplicateKeyError",
+    "check_schema",
+    "parse_intent_yaml",
+    "top_level_keys",
+]
+
+# Accept either canonical `INT-NNN` (CSD-INTENT-01 §3.1) or our extended
+# `INT-PREFIX-NNN` style for multi-module monorepos. Both are valid here.
+ID_PATTERN = re.compile(r"^INT-[A-Z0-9-]+$")
+VERSION_PATTERN = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+$")
+
+VALID_STATUS = {"draft", "active", "deprecated"}
+VALID_SCOPE = {"unit", "integration", "e2e"}
+VALID_TYPE = {"invariant", "behavior", "contract"}
+VALID_CRITICALITY = {"critical", "high", "medium", "low"}
+
+# Top-level fields required on every claim per CSD-INTENT-01 §4.1.
+# (id is implicit from the YAML key, so we don't check it separately.)
+REQUIRED_TOP = {"version", "status", "statement", "criticality"}
+
+
+_MERGE_TAG = "tag:yaml.org,2002:merge"
+
+
+class DuplicateKeyError(ValueError):
+    """A mapping in intent.yaml declares the same key twice.
+
+    YAML's own resolution is last-wins and silent, so a repeated claim id destroys
+    the earlier claim before any check can see it: the claim stops being enforced
+    and every marker written for it silently re-points at the survivor (issue #12).
+    A duplicate id has no valid interpretation, so the parse refuses it.
+    """
+
+    def __init__(self, key: object, first_line: int, second_line: int) -> None:
+        self.key = key
+        self.first_line = first_line
+        self.second_line = second_line
+        super().__init__(
+            f"duplicate key `{key}` (first declared on line {first_line}, "
+            f"declared again on line {second_line}); YAML would silently keep only "
+            f"the last one"
+        )
+
+
+class _UniqueKeySafeLoader(yaml.SafeLoader):
+    """SafeLoader that refuses a repeated mapping key instead of resolving last-wins."""
+
+    def construct_mapping(self, node: yaml.MappingNode, deep: bool = False) -> dict[Any, Any]:
+        # Scan the raw key nodes before the base class flattens merge keys (`<<`),
+        # so a legitimate merge-plus-override is not mistaken for a duplicate.
+        seen: dict[Any, int] = {}
+        for key_node, _ in node.value:
+            if key_node.tag == _MERGE_TAG:
+                continue  # `<<` is expanded by the base class, and an override is legal
+            key = self.construct_object(key_node, deep=deep)
+            if not isinstance(key, Hashable):
+                continue  # the base constructor reports unhashable keys itself
+            line = key_node.start_mark.line + 1
+            if key in seen:
+                raise DuplicateKeyError(key, seen[key], line)
+            seen[key] = line
+        return super().construct_mapping(node, deep=deep)
+
+
+def _load(path: Path) -> Any:
+    """Load a YAML document, refusing duplicate mapping keys (`DuplicateKeyError`)."""
+    text = path.read_text(encoding="utf-8")
+    return yaml.load(text, Loader=_UniqueKeySafeLoader)
+
+
+def parse_intent_yaml(path: Path) -> dict[str, dict[str, Any]]:
+    """Parse an intent.yaml. Returns {claim_id: claim_dict}. Non-INT keys ignored.
+
+    Raises `DuplicateKeyError` when the file declares the same key twice: dropping
+    one of them silently is never the right answer (issue #12).
+    """
+    data = _load(path) or {}
+    if not isinstance(data, dict):
+        return {}
+    out: dict[str, dict[str, Any]] = {}
+    for key, value in data.items():
+        if isinstance(key, str) and key.startswith("INT-") and isinstance(value, dict):
+            out[key] = value
+    return out
+
+
+def top_level_keys(path: Path) -> list[str]:
+    """Sorted top-level YAML keys, for diagnosing a zero-claims schema mismatch."""
+    data = _load(path) or {}
+    if not isinstance(data, dict):
+        return []
+    return sorted(str(key) for key in data.keys())
+
+
+def _scope_and_test(claim: dict[str, Any]) -> tuple[str | None, dict[str, Any] | None]:
+    """Return (effective_scope, nested_test_dict_or_None)."""
+    test = claim.get("test")
+    if isinstance(test, dict):
+        scope = test.get("scope")
+        return (scope if isinstance(scope, str) else None, test)
+    legacy = claim.get("scope")
+    return (legacy if isinstance(legacy, str) else None, None)
+
+
+def check_schema(claims: dict[str, dict[str, Any]]) -> list[str]:
+    """Return a list of human-readable schema violations. Empty list = pass."""
+    violations: list[str] = []
+
+    for cid, claim in claims.items():
+        if not ID_PATTERN.match(cid):
+            violations.append(f"{cid}: id does not match {ID_PATTERN.pattern}")
+
+        missing = REQUIRED_TOP - set(claim.keys())
+        if missing:
+            violations.append(f"{cid}: missing required fields {sorted(missing)}")
+
+        version = claim.get("version")
+        if version is not None and (
+            not isinstance(version, str) or not VERSION_PATTERN.match(version)
+        ):
+            violations.append(f"{cid}: version `{version!r}` is not semver X.Y.Z")
+
+        status = claim.get("status")
+        if status is not None and status not in VALID_STATUS:
+            violations.append(
+                f"{cid}: invalid status `{status!r}` (allowed {sorted(VALID_STATUS)})"
+            )
+
+        criticality = claim.get("criticality")
+        if criticality is not None and criticality not in VALID_CRITICALITY:
+            violations.append(
+                f"{cid}: invalid criticality `{criticality!r}` "
+                f"(allowed {sorted(VALID_CRITICALITY)})"
+            )
+
+        statement = claim.get("statement")
+        if statement is not None and (not isinstance(statement, str) or len(statement) < 10):
+            violations.append(f"{cid}: statement must be a string of >=10 characters")
+
+        scope, test = _scope_and_test(claim)
+        if scope is None:
+            violations.append(f"{cid}: missing scope (must appear as `test.scope` or top-level `scope`)")
+        elif scope not in VALID_SCOPE:
+            violations.append(
+                f"{cid}: invalid scope `{scope!r}` (allowed {sorted(VALID_SCOPE)})"
+            )
+
+        # Test object validation (only meaningful when present)
+        if test is not None:
+            if "component" not in test:
+                violations.append(f"{cid}: test.component is required")
+            if "type" not in test:
+                violations.append(f"{cid}: test.type is required")
+            else:
+                ttype = test["type"]
+                if ttype not in VALID_TYPE:
+                    violations.append(
+                        f"{cid}: invalid test.type `{ttype!r}` (allowed {sorted(VALID_TYPE)})"
+                    )
+
+    return violations

csd_intent/walker.py

@@ -0,0 +1,211 @@
+"""Multi-language walker that finds @intent / intent() markers in test files.
+
+Two strategies:
+  - .py    → AST walk for @intent("INT-...") decorators on test_ functions
+  - .ts/.tsx/.js/.jsx/.mts/.cts → regex for intent('INT-...', name, fn) calls
+
+Both produce {claim_id: [test_ref, ...]} where test_ref is "<rel-path>::<name>".
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from collections.abc import Iterable
+from pathlib import Path
+
+__all__ = [
+    "DEFAULT_EXCLUDE_DIRS",
+    "INTENT_FILENAME",
+    "JS_EXTS",
+    "PY_EXT",
+    "TEST_FILE_RE",
+    "collect_attestations",
+    "find_nested_intent_projects",
+]
+
+DEFAULT_EXCLUDE_DIRS = frozenset(
+    {
+        "node_modules",
+        ".venv",
+        "venv",
+        "dist",
+        "build",
+        ".git",
+        "__pycache__",
+        ".pytest_cache",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".tox",
+        ".egg-info",
+    }
+)
+
+PY_EXT = ".py"
+JS_EXTS = frozenset({".ts", ".tsx", ".js", ".jsx", ".mts", ".cts"})
+
+# A directory that contains this file (other than the scan root) is a *nested
+# intent project* - a separate project boundary. The marker walk must not descend
+# into it, so its markers do not orphan against the outer project's claims.
+INTENT_FILENAME = "intent.yaml"
+TEST_FILE_RE = re.compile(r"(^|[._-])(test|spec)([._-]|$)|test_|_test\.|\.test\.|\.spec\.")
+
+# Matches intent('INT-XXX', "name", ...) OR intent("INT-XXX", "name", ...)
+# Also array form: intent(['INT-X', 'INT-Y'], 'name', ...)
+_JS_INTENT_RE = re.compile(
+    r"\bintent\s*\(\s*"
+    r"(?:\[\s*(?P<list>[^\]]+?)\s*\]|(?P<q1>['\"`])(?P<id>INT-[A-Z0-9-]+)(?P=q1))"
+    r"\s*,\s*(?P<q2>['\"`])(?P<name>[\s\S]*?)(?P=q2)\s*,"
+)
+_JS_ID_IN_LIST_RE = re.compile(r"['\"`](INT-[A-Z0-9-]+)['\"`]")
+
+
+def collect_attestations(
+    test_dirs: Iterable[Path],
+    exclude_dirs: frozenset[str] = DEFAULT_EXCLUDE_DIRS,
+    respect_nested_projects: bool = True,
+) -> dict[str, list[str]]:
+    """Walk `test_dirs` and return {claim_id: [test_ref, ...]} for every intent marker.
+
+    test_refs are formatted ``<rel-path>::<test-name>`` for readability in error output.
+
+    When ``respect_nested_projects`` is True (the default), any subdirectory below a
+    scanned root that contains its own ``intent.yaml`` is treated as a separate project
+    boundary: the walk does not descend into it, so the nested project's markers do not
+    orphan against the outer project's claims. The scanned root itself is never skipped,
+    even though it normally contains an ``intent.yaml`` (it *is* the project under audit).
+    """
+    out: dict[str, list[str]] = {}
+    for root in test_dirs:
+        if not root.exists():
+            continue
+        base = root.resolve()
+        for path in _walk_files(base, exclude_dirs, respect_nested_projects):
+            if not _is_test_file(path):
+                continue
+            try:
+                text = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+            rel = path.relative_to(base).as_posix()
+            if path.suffix == PY_EXT:
+                _collect_from_python(text, rel, out)
+            elif path.suffix in JS_EXTS:
+                _collect_from_js(text, rel, out)
+    return out
+
+
+def _walk_files(
+    root: Path,
+    exclude_dirs: frozenset[str],
+    respect_nested_projects: bool = True,
+) -> Iterable[Path]:
+    """Recursively yield files under ``root``, skipping excluded directory names.
+
+    Stops descending into any nested intent-project subtree (a subdirectory that
+    contains its own ``intent.yaml``) when ``respect_nested_projects`` is True. The
+    starting ``root`` is always scanned even if it holds an ``intent.yaml``.
+    """
+    for entry in root.iterdir():
+        if entry.is_symlink():
+            continue
+        if entry.is_dir():
+            if entry.name in exclude_dirs:
+                continue
+            if respect_nested_projects and (entry / INTENT_FILENAME).is_file():
+                # A nested intent project - a separate boundary. Do not descend.
+                continue
+            yield from _walk_files(entry, exclude_dirs, respect_nested_projects)
+        elif entry.is_file():
+            yield entry
+
+
+def find_nested_intent_projects(
+    root: Path,
+    exclude_dirs: frozenset[str] = DEFAULT_EXCLUDE_DIRS,
+) -> list[Path]:
+    """Return directories *strictly below* ``root`` that hold their own ``intent.yaml``.
+
+    The ``root`` itself is never included (it is the project being audited). Results are
+    sorted for deterministic output. Each returned directory is the root of a separate
+    intent project; auditing it with ``respect_nested_projects=True`` bounds its marker
+    scan against any still-deeper nested projects, giving a complete, non-overlapping
+    partition of the tree.
+    """
+    base = root.resolve()
+    found: list[Path] = []
+
+    def _descend(current: Path) -> None:
+        for entry in sorted(current.iterdir()):
+            if entry.is_symlink() or not entry.is_dir():
+                continue
+            if entry.name in exclude_dirs:
+                continue
+            if (entry / INTENT_FILENAME).is_file():
+                found.append(entry)
+            # Always descend further so deeper-nested projects are also discovered.
+            _descend(entry)
+
+    if base.is_dir():
+        _descend(base)
+    return found
+
+
+def _is_test_file(path: Path) -> bool:
+    """Is this file a test by conventional naming?"""
+    name = path.name
+    if path.suffix == PY_EXT:
+        return name.startswith("test_") or name.endswith("_test.py")
+    return bool(TEST_FILE_RE.search(name))
+
+
+def _collect_from_python(text: str, rel_path: str, out: dict[str, list[str]]) -> None:
+    """AST-walk a .py file looking for @intent("INT-...") decorators."""
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            continue
+        if not node.name.startswith("test_"):
+            continue
+        for dec in node.decorator_list:
+            for cid in _extract_ids_from_decorator(dec):
+                ref = f"{rel_path}::{node.name}"
+                out.setdefault(cid, []).append(ref)
+
+
+def _extract_ids_from_decorator(node: ast.expr) -> list[str]:
+    """If `node` is a call to `intent(...)`, return the claim-ID string args."""
+    if not isinstance(node, ast.Call):
+        return []
+    func = node.func
+    name = (
+        func.id
+        if isinstance(func, ast.Name)
+        else func.attr
+        if isinstance(func, ast.Attribute)
+        else None
+    )
+    if name != "intent":
+        return []
+    ids: list[str] = []
+    for arg in node.args:
+        if isinstance(arg, ast.Constant) and isinstance(arg.value, str) and arg.value.startswith("INT-"):
+            ids.append(arg.value)
+    return ids
+
+
+def _collect_from_js(text: str, rel_path: str, out: dict[str, list[str]]) -> None:
+    """Regex-scan a JS/TS file for intent('INT-...', name, fn) calls."""
+    for match in _JS_INTENT_RE.finditer(text):
+        name = match.group("name")
+        ids: list[str] = []
+        if match.group("list"):
+            ids.extend(_JS_ID_IN_LIST_RE.findall(match.group("list")))
+        elif match.group("id"):
+            ids.append(match.group("id"))
+        for cid in ids:
+            ref = f"{rel_path}::{name}"
+            out.setdefault(cid, []).append(ref)

csd_intent-0.4.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: csd-intent
+Version: 0.4.0
+Summary: Cross-runtime audit tool for CSD intent specifications. Validates intent.yaml against CSD-INTENT-01 and verifies each claim is attested by at least one test across pytest, vitest, Playwright, or any other runner using the standard intent() marker.
+Author: Rafael Pires
+License: MIT
+Project-URL: Homepage, https://github.com/PSA-Department-of-Engineering/csd-library
+Project-URL: Documentation, https://github.com/PSA-Department-of-Engineering/csd-library#readme
+Project-URL: CSD methodology, https://github.com/PSA-Department-of-Engineering/cognitive-software-delivery
+Keywords: csd,intent,testing,specification,audit,cross-language
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# csd-intent
+
+Cross-runtime audit tool for CSD intent specifications. Validates `intent.yaml`
+against [CSD-INTENT-01](https://github.com/PSA-Department-of-Engineering/cognitive-software-delivery) and confirms every
+claim is attested by at least one test marker across **any** test runner -
+pytest, vitest, Playwright, Jest, or anything that uses the standard `intent()`
+/ `@intent()` marker shape.
+
+This tool is **standalone**. It does not run inside your project's test suite; it
+is invoked separately (CLI, CI step, or pre-commit hook).
+
+## Why it exists
+
+`pytest-intent`, `vitest-intent`, and `playwright-intent` provide the test-side
+marker helpers - they let a test declare which intent claim it attests. They
+deliberately know nothing about other runtimes, schema validation, or whether a
+claim is unattested.
+
+`csd-intent` owns the cross-runtime auditing: it walks every test file in the
+project (Python via AST, TS/JS via regex), reads `intent.yaml`, and answers:
+
+1. **Schema** - does every claim match CSD-INTENT-01?
+2. **Orphan** - does every test marker reference a real claim?
+3. **Coverage** - does every claim have at least one attesting test, anywhere?
+
+## Install
+
+```bash
+# From PyPI:
+pip install csd-intent
+
+# Local dev against a csd-library checkout:
+pip install -e path/to/csd-library/csd-intent
+```
+
+## Use
+
+```bash
+# Audit the current directory (expects intent.yaml at the root):
+csd-intent
+
+# Audit a specific project:
+csd-intent /path/to/project
+
+# Audit but tolerate unattested claims (the "intent before test" workflow):
+csd-intent --fail-on schema
+
+# Constrain the scan to specific directories:
+csd-intent --tests-dir backend/tests --tests-dir frontend/src --tests-dir e2e
+
+# Quiet summary only:
+csd-intent --quiet
+```
+
+Exit code is `0` on a clean audit, `1` when any violation falls into the
+configured `--fail-on` set (`any` by default).
+
+## Output
+
+```
+intent.yaml (/path/to/project/intent.yaml): 24 claims, 2 violation(s).
+
+UNATTESTED (2):
+  [unattested] INT-SB-018: no @intent / intent() marker references this claim
+  [unattested] INT-SB-029: no @intent / intent() marker references this claim
+```
+
+## What it scans
+
+- **Python**: any file matching `test_*.py` or `*_test.py`, walked via AST for
+  `@intent("INT-...")` decorators on functions starting with `test_`.
+- **JS/TS**: any file matching `*.test.{ts,tsx,js,jsx,mts,cts}` or
+  `*.spec.{ts,...}`, scanned by regex for `intent('INT-...', 'name', fn)` calls
+  (single-ID and array-of-IDs forms both supported).
+- **Excluded directories**: `node_modules`, `.venv`, `venv`, `dist`, `build`,
+  `.git`, `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.tox`.
+
+## CSD-INTENT-01 conformance
+
+The schema check validates each claim against the canonical fields per
+[CSD-INTENT-01 §4.1](https://github.com/PSA-Department-of-Engineering/cognitive-software-delivery):
+
+```yaml
+INT-NNN:
+  version: 1.0.0
+  status: active                # draft | active | deprecated
+  statement: "..."              # >= 10 chars, RFC 2119 language
+  rationale: "..."              # optional but recommended
+  test:
+    scope: integration          # unit | integration | e2e
+    component: SwitchFlow
+    type: behavior              # invariant | behavior | contract
+  criticality: critical         # critical | high | medium | low
+```
+
+For projects still on the legacy flat-`scope:` shape, the tool accepts it (with
+no warning) - that's a migration concession, not a recommendation.
+
+### Duplicate keys are refused
+
+`intent.yaml` is parsed with a loader that raises on a repeated key rather than
+resolving it last-wins. A claim id reused by accident would otherwise delete the
+earlier claim before any check could see it - and every marker written for that
+claim would silently start attesting the survivor, with the audit still printing
+`CLEAN`. The duplicate is reported as a schema violation naming both lines:
+
+```
+SCHEMA (1):
+  [schema] intent.yaml: duplicate key `INT-GATE-006` (first declared on line 42,
+  declared again on line 187); YAML would silently keep only the last one
+```
+
+Merge keys still work: `<<: *base` plus an explicit override is not a duplicate.
+
+## License
+
+MIT.

csd_intent-0.4.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+csd_intent/__init__.py,sha256=nFHCLz3m9SAMIbAmOrjYhHzAAA87uWQ_ohcErQUradQ,1592
+csd_intent/audit.py,sha256=25DTzlA2CrwCcVL7BydICFEgUe8VLtXV6SV81owLYkA,7079
+csd_intent/cli.py,sha256=IBU9M3O0XGacdPF4Ew454hKPIZ9-NGxpUu6IKCymv6M,5130
+csd_intent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+csd_intent/schema.py,sha256=d490KC-rotQ_B_QYjcwZTDDESxDYxthxuB_L9eCB2uo,7434
+csd_intent/walker.py,sha256=YsiGDvLhIv6Cki1NufV35TY0wrxNQecIw_iyP_U8yOA,7453
+csd_intent-0.4.0.dist-info/licenses/LICENSE,sha256=ngjAHPmFeQOm2fm-eMuriVgRfTA8aX8FpdnP9NgoGD0,1069
+csd_intent-0.4.0.dist-info/METADATA,sha256=XjKahOTzUZQnfnZPM9G5DGNJu6-DZTruuiVvwDCeb3U,5670
+csd_intent-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+csd_intent-0.4.0.dist-info/entry_points.txt,sha256=L1L37Zg8hh6jMNlWMiBQQp27YstvYrGE7XVLj4sRRHw,51
+csd_intent-0.4.0.dist-info/top_level.txt,sha256=RMKlGhAFmT6IF0uknN5jv2ElnxWLkPsQwS-jh19B2bQ,11
+csd_intent-0.4.0.dist-info/RECORD,,

csd_intent-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

csd_intent-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+csd-intent = csd_intent.cli:main

csd_intent-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Pires
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

csd_intent-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+csd_intent