scripts.factory_conformance

Reference › scripts › factory_conformance

The command-line interface for the SPEC-033 B2 conformance engine, which checks that the AST agrees with the design (ADR-0007 and ADR-0008). It uses the engine in engine and the contract models in models; the factory narrative describes the subsystem. No module or test imports it.

Invocation: main has one subcommand, check (_cmd_check; its parser is _add_check_parser). The command can read the declared design edges from a file (_load_declared_edges), compares them with the edges in the code, and prints the resulting ConformanceReport (_print_report). Its exit code comes from the handler.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/scripts/factory_conformance.py

#!/usr/bin/env python3
"""CLI for the SPEC-033 B2 AST≡design conformance engine (ADR-0007/ADR-0008).

Subcommands
-----------
check   Load a :class:`DesignContract` (B3) and run
        :func:`check_conformance` against the code tree at ``--repo-root``,
        printing a JSON :class:`ConformanceReport`. Exits 0 if conformant,
        1 if not. An INVALID contract file (malformed JSON, unsupported
        schema version, or a structural violation caught by
        :func:`~orchestrata_ultimate.factory.contracts.models.
        validate_contract`) is a HARD ERROR -- exit 2 -- distinct from a
        non-conformant (but structurally valid) contract.

Examples
--------
    python scripts/factory_conformance.py check --repo-root . \\
        --contract contract.json

    python scripts/factory_conformance.py check --repo-root . \\
        --contract contract.json --edges edges.json

ADR-0008: a green report from this CLI is a STRUCTURAL claim only
(existence, signatures, dependency edges) -- never a correctness claim.
See ``src/orchestrata_ultimate/factory/conformance/engine.py``.
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

# Ensure repo src is on path when run directly (mirrors factory_fastpath.py).
_repo_src = Path(__file__).resolve().parent.parent / "src"
if str(_repo_src) not in sys.path:
    sys.path.insert(0, str(_repo_src))

from orchestrata_ultimate.factory.conformance.engine import (  # noqa: E402
    ConformanceReport,
    check_conformance,
)
from orchestrata_ultimate.factory.contracts.models import (  # noqa: E402
    ContractValidationError,
    load_contract,
)

_HARD_ERROR_EXIT = 2


def _load_declared_edges(path: str | None) -> dict[str, set[str]]:
    """Load a ``{node_id: [package, ...]}`` JSON mapping, or ``{}`` if absent."""
    if path is None:
        return {}
    with open(path, encoding="utf-8") as f:
        data = json.load(f)
    return {node_id: set(packages) for node_id, packages in data.items()}


def _print_report(report: ConformanceReport) -> None:
    print(json.dumps(report.to_dict(), indent=2))


def _cmd_check(args: argparse.Namespace) -> int:
    repo_root = Path(args.repo_root)
    try:
        contract = load_contract(args.contract)
    except (OSError, ValueError, ContractValidationError) as exc:
        print(f"ERROR: invalid contract file {args.contract!r}: {exc}", file=sys.stderr)
        return _HARD_ERROR_EXIT

    try:
        declared_edges = _load_declared_edges(args.edges)
    except (OSError, ValueError) as exc:
        print(f"ERROR: invalid edges file {args.edges!r}: {exc}", file=sys.stderr)
        return _HARD_ERROR_EXIT

    report = check_conformance(repo_root, contract, declared_edges=declared_edges)
    _print_report(report)
    return 0 if report.conformant else 1


def _add_check_parser(sub: argparse._SubParsersAction) -> None:
    check_p = sub.add_parser(
        "check",
        help="Check a DesignContract against the code tree; prints a JSON report.",
    )
    check_p.add_argument("--repo-root", required=True)
    check_p.add_argument("--contract", required=True)
    check_p.add_argument(
        "--edges",
        default=None,
        help="optional JSON file of {node_id: [declared outbound package, ...]}",
    )


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="factory_conformance",
        description="SPEC-033 B2 AST≡design conformance engine CLI (ADR-0007/ADR-0008).",
    )
    sub = parser.add_subparsers(dest="command", required=True)
    _add_check_parser(sub)
    return parser


def main(argv: list[str] | None = None) -> int:
    """Parse ``argv`` and dispatch to the matching subcommand handler."""
    parser = _build_parser()
    args = parser.parse_args(argv)

    dispatch = {
        "check": _cmd_check,
    }
    handler = dispatch[args.command]
    return handler(args)


if __name__ == "__main__":
    sys.exit(main())