ontolint 0.1.0__py3-none-any.whl

ontolint/__init__.py

@@ -0,0 +1,7 @@
+"""Public Python API for ontology-quality linting."""
+
+from .cli import main
+from .linter import Linter
+from .models import Finding
+
+__all__ = ["Finding", "Linter", "main"]

ontolint/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m ontolint``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ontolint/_version.py

@@ -0,0 +1,15 @@
+"""Single fallback for the package version (a test pins it to ``pyproject.toml``)."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+FALLBACK_VERSION = "0.1.0"
+
+
+def package_version() -> str:
+    """Return the installed distribution version, or the packaged fallback when not installed."""
+    try:
+        return metadata.version("ontolint")
+    except metadata.PackageNotFoundError:
+        return FALLBACK_VERSION

ontolint/adapters/__init__.py

@@ -0,0 +1 @@
+"""Optional validation backends (pySHACL, ROBOT) that translate results into findings."""

ontolint/adapters/robot.py

@@ -0,0 +1,72 @@
+"""ROBOT adapter: OWL profile validation in an isolated Docker container."""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+from ontolint.models import Finding
+from ontolint.rules.specs import FIXES, SEVERITY
+
+
+def robot_profile_issues(ontology: Path, profile: str, image: str, timeout: int) -> list[Finding]:
+    """Run ROBOT profile validation in an isolated Docker container.
+
+    The ontology's parent directory is mounted read-only and the container has no
+    network access. Use a digest-pinned ``image`` in CI for reproducibility.
+    """
+    source = ontology.resolve()
+    if not source.is_file():
+        raise FileNotFoundError(source)
+    with tempfile.TemporaryDirectory(prefix="ontolint-robot-") as output_dir:
+        output = Path(output_dir)
+        report = output / "profile.txt"
+        command = [
+            "docker",
+            "run",
+            "--rm",
+            "--network",
+            "none",
+            "--memory",
+            "2g",
+            "--pids-limit",
+            "256",
+            "--cpus",
+            "2",
+            "--cap-drop",
+            "ALL",
+            "--security-opt",
+            "no-new-privileges",
+            "-v",
+            f"{source.parent}:/input:ro",
+            "-v",
+            f"{output}:/output",
+            "-w",
+            "/output",
+            image,
+            "validate-profile",
+            "--profile",
+            profile,
+            "--input",
+            f"/input/{source.name}",
+            "--output",
+            "/output/profile.txt",
+        ]
+        completed = subprocess.run(  # noqa: S603 -- fixed Docker executable and constructed argument list.
+            command, capture_output=True, text=True, timeout=timeout, check=False
+        )
+        if completed.returncode == 0:
+            return []
+        details = report.read_text(encoding="utf-8", errors="replace").strip() if report.exists() else ""
+        details = details or completed.stderr.strip() or completed.stdout.strip() or "ROBOT did not produce a report."
+        return [
+            Finding(
+                "SEM001",
+                SEVERITY["SEM001"],
+                str(source),
+                f"ROBOT OWL {profile} profile validation failed: {details[:4000]}",
+                FIXES["SEM001"],
+                "certain",
+            )
+        ]

ontolint/adapters/shacl.py

@@ -0,0 +1,147 @@
+"""pySHACL adapter: SHACL validation results become SHACL001 findings."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+
+from rdflib import Graph, URIRef
+from rdflib.namespace import RDF, SH
+from rdflib.term import Node
+
+from ontolint.models import Finding
+from ontolint.rules.specs import FIXES
+
+MAX_LIST_LENGTH = 400
+"""Longest rdf:list the SHACL backend is asked to validate (pySHACL meta-validation is quadratic in it)."""
+MAX_LIST_COST = 160_000
+"""Bound on the sum over lists of ``length ** 2`` (a few seconds of pySHACL work)."""
+
+_BAD_IRI_CHARS = frozenset('<>" {}|\\^`')
+"""The characters ``rdflib`` refuses to serialise in an IRI (``rdflib.term._is_valid_uri``)."""
+
+
+class ShapesRejected(ValueError):
+    """An input graph would make pySHACL crash or run for minutes; it is refused before validation."""
+
+
+def _first_unserialisable_iri(graph: Graph) -> str | None:
+    seen: set[str] = set()
+    for triple in graph:
+        for term in triple:
+            if isinstance(term, URIRef) and term not in seen:
+                seen.add(term)
+                if not _BAD_IRI_CHARS.isdisjoint(term):
+                    return str(term)
+    return None
+
+
+def _check_iris(graph: Graph, name: str) -> None:
+    bad = _first_unserialisable_iri(graph)
+    if bad is not None:
+        raise ShapesRejected(f"{name} contains an IRI that cannot be serialised: {bad[:80]!r}")
+
+
+@dataclass
+class _Lists:
+    """The rdf:list structure of one graph and the cells the checks have walked so far."""
+
+    name: str
+    rest: dict[Node, Node]
+    cells: set[Node]
+    reached: set[Node] = field(default_factory=set[Node])
+
+
+def _walk_list(head: Node, lists: _Lists, *, strict: bool) -> int:
+    """Walk one list from ``head`` and return its length; reject cycles, and in strict mode sharing and length."""
+    length, cell = 0, head
+    walk: set[Node] = set()
+    while cell != RDF.nil and cell in lists.cells:
+        if cell in walk:
+            raise ShapesRejected(f"{lists.name} contains a cyclic rdf:list (rdf:rest loops back)")
+        if cell in lists.reached:
+            if strict:
+                raise ShapesRejected(f"{lists.name} contains an rdf:list cell shared by several lists")
+            break  # a shared tail is legal RDF; the cells beyond it were already walked
+        walk.add(cell)
+        lists.reached.add(cell)
+        length += 1
+        if strict and length > MAX_LIST_LENGTH:
+            raise ShapesRejected(f"{lists.name} contains an rdf:list longer than {MAX_LIST_LENGTH} items")
+        cell = lists.rest.get(cell, RDF.nil)
+    return length
+
+
+def _check_lists(graph: Graph, name: str, *, strict: bool) -> None:
+    rest: dict[Node, Node] = {}
+    indegree: Counter[Node] = Counter()
+    for cell, _, tail in graph.triples((None, RDF.rest, None)):
+        if cell in rest and rest[cell] != tail:
+            raise ShapesRejected(f"{name} contains an rdf:list cell with several rdf:rest values")
+        rest[cell] = tail
+        indegree[tail] += 1
+    lists = _Lists(name, rest, set(rest) | {s for s, _, _ in graph.triples((None, RDF.first, None))})
+    cost = 0
+    for head in (c for c in lists.cells if indegree[c] == 0):
+        length = _walk_list(head, lists, strict=strict)
+        cost += length * length
+        if strict and cost > MAX_LIST_COST:
+            raise ShapesRejected(f"{name} contains too many long rdf:lists to validate in reasonable time")
+    if lists.reached != lists.cells - {RDF.nil}:
+        raise ShapesRejected(f"{name} contains a cyclic rdf:list (rdf:rest loops back)")
+
+
+def check_graph(graph: Graph, name: str, *, strict: bool = True) -> None:
+    """Raise :class:`ShapesRejected` unless pySHACL can process ``graph`` safely (linear time, no recursion).
+
+    Every check looks for IRIs rdflib cannot serialise and for cyclic lists. ``strict`` (the shapes graph)
+    additionally rejects shared, overlong or numerous long lists, because pySHACL's meta-validation of the
+    shapes walks each list once per internal result, which is quadratic in the list length.
+    """
+    _check_iris(graph, name)
+    _check_lists(graph, name, strict=strict)
+
+
+def shacl_issues(g: Graph, sg: Graph) -> list[Finding]:
+    """Validate ``g`` against ``sg`` with pySHACL (imported lazily; required only with shapes)."""
+    try:
+        from pyshacl import validate  # noqa: PLC0415 -- optional dependency, required only with --shapes.
+    except ImportError:
+        raise RuntimeError("pySHACL is needed for --shapes: pip install pyshacl") from None
+    check_graph(sg, "shapes graph")
+    try:
+        conforms, report, _ = validate(
+            g, shacl_graph=sg, inference="none", advanced=True, meta_shacl=True, abort_on_first=False
+        )
+    except ShapesRejected:
+        raise
+    except Exception as exc:
+        # The data graph may hold large enumerations, odd IRIs (IRI001 reports those) or malformed lists, and
+        # pySHACL fails on them only when a violation message has to describe such a node: diagnose it then.
+        try:
+            check_graph(g, "data graph", strict=False)
+        except ShapesRejected as problem:
+            raise ShapesRejected(f"{problem}; pySHACL failed on it: {type(exc).__name__}: {exc}") from exc
+        raise
+    if conforms:
+        return []
+    if not isinstance(report, Graph):
+        raise RuntimeError(f"pySHACL returned an unexpected report type: {type(report).__name__}")
+    results: list[Finding] = []
+    for result in report.subjects(RDF.type, SH.ValidationResult):
+        focus = str(next(report.objects(result, SH.focusNode), "(unknown)"))
+        message = "; ".join(map(str, report.objects(result, SH.resultMessage))) or "SHACL constraint violation"
+        src = str(next(report.objects(result, SH.sourceShape), "(unknown)"))
+        results.append(Finding("SHACL001", "error", focus, f"{message} [shape: {src}]", FIXES["SHACL001"], "certain"))
+    if not results:
+        results.append(
+            Finding(
+                "SHACL001",
+                "error",
+                "(shapes)",
+                "SHACL returned nonconformant without individual result nodes.",
+                FIXES["SHACL001"],
+                "certain",
+            )
+        )
+    return results

ontolint/catalogue.py

@@ -0,0 +1,77 @@
+"""Typed view of the planning catalogue (implemented and proposed rules).
+
+The catalogue records what is *planned* (:class:`CatalogueStatus`); runtime outcomes
+(:class:`ExecutionStatus`) are a different concept and live on :class:`RuleExecution`.
+The canonical file is ``data/rule_catalogue.csv`` in the repository; an identical copy
+ships inside the package so the loader works from an installed wheel (a test enforces
+that the two never drift).
+"""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from functools import cache
+from importlib import resources
+
+from .models import CatalogueStatus, RuleBackend
+
+# Backends of implemented rules; planned rules use free-text backends and map to ``None``.
+# Graph-algorithm rules (hierarchy metrics) and shapes-graph authoring rules run in-process on
+# RDFLib graphs, so they map to the RDFLIB backend even though the catalogue prose is more specific.
+# Mixed backends of still-proposed rows (for example "RDFLib graph or OWL profile backend") stay
+# unmapped until a row is implemented and its actual backend is known.
+BACKEND_IDS: dict[str, RuleBackend] = {
+    "RDFLib graph": RuleBackend.RDFLIB,
+    "RDFLib graph algorithms": RuleBackend.RDFLIB,
+    "pySHACL and RDFLib graph": RuleBackend.RDFLIB,
+    "pySHACL": RuleBackend.PYSHACL,
+    "ROBOT Docker backend": RuleBackend.ROBOT_DOCKER,
+    "CLI": RuleBackend.CLI,
+}
+
+
+@dataclass(frozen=True)
+class CatalogueRow:
+    """One catalogue entry."""
+
+    rule_id: str
+    family: str
+    title: str
+    status: CatalogueStatus
+    category: str
+    backend: str
+    test_requirement: str
+
+    @property
+    def backend_id(self) -> RuleBackend | None:
+        """The stable backend identifier, or ``None`` for a planned, unmapped backend."""
+        return BACKEND_IDS.get(self.backend)
+
+
+@cache
+def load_catalogue() -> tuple[CatalogueRow, ...]:
+    """Load every catalogue row in file order from the packaged CSV."""
+    text = resources.files("ontolint").joinpath("data/rule_catalogue.csv").read_text(encoding="utf-8")
+    return tuple(
+        CatalogueRow(
+            rule_id=row["rule_id"],
+            family=row["family"],
+            title=row["title"],
+            status=CatalogueStatus(row["status"]),
+            category=row["category"],
+            backend=row["backend"],
+            test_requirement=row["test_requirement"],
+        )
+        for row in csv.DictReader(text.splitlines())
+    )
+
+
+def implemented_rows() -> tuple[CatalogueRow, ...]:
+    """Rows whose rules ship in the built-in registry."""
+    return tuple(row for row in load_catalogue() if row.status is CatalogueStatus.IMPLEMENTED)
+
+
+def planned_rows() -> tuple[CatalogueRow, ...]:
+    """Rows that are proposed but not yet implemented."""
+    return tuple(row for row in load_catalogue() if row.status is not CatalogueStatus.IMPLEMENTED)

ontolint/cli.py

@@ -0,0 +1,302 @@
+"""Command-line interface: argument parsing, orchestration, and report output.
+
+Exit codes: ``0`` clean, ``1`` findings reach ``--fail-on``, ``2`` tool failure.  A tool failure is
+bad input/configuration/selectors, or a requested rule that failed or is unsupported (for example
+``--owl-profile`` without Docker): the report is still written, but the run cannot pass.
+Rules skipped for an optional input that was not supplied, or by an ignore, never affect the code.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from contextvars import ContextVar
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from rdflib import Graph
+
+from . import engine
+from ._version import package_version
+from .catalogue import planned_rows
+from .loader import InputRejected, ParseFailure, load_graph
+from .models import ExecutionStatus, Finding, RuleBackend, RuleExecution
+from .paths import InputFile, resolve_inputs
+from .policy import Policy
+from .profiles import PROFILES, Profile
+from .reporting import FileReport, RunReport, fingerprint, render_report, run_exit_code
+from .rule_info import UnknownRuleError, explain_rule, render_explanation, render_rule_list, rule_rows
+from .rules.registry import RuleRegistry, UnknownSelectorError, default_registry
+from .selection import Selection, SelectorSyntaxError, resolve_selection, split_selectors, unknown_selector_help
+
+FORMATS = ["text", "json", "sarif"]
+
+
+def _positive_int(text: str) -> int:
+    """argparse type for the loader limits: an integer of at least 1."""
+    try:
+        value = int(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"must be a positive integer, got {text!r}") from None
+    if value < 1:
+        raise argparse.ArgumentTypeError(f"must be a positive integer (at least 1), got {value}")
+    return value
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the ``ontolint`` argument parser."""
+    ap = argparse.ArgumentParser(description="Ontology anti-pattern linter. No automatic network/import access.")
+    ap.add_argument(
+        "ontology",
+        nargs="*",
+        help="Ontology RDF file(s); each is linted independently. Expand globs in your shell; directories are rejected",
+    )
+    ap.add_argument("--shapes", help="Optional SHACL shapes graph (requires pyshacl)")
+    ap.add_argument("--base", help="Only lint declared terms in this namespace")
+    ap.add_argument("--config", help="Optional JSON policy with ignored_rules, severity_overrides and thresholds")
+    ap.add_argument("--baseline", help="JSON of fingerprints to exclude from displayed and gating findings")
+    ap.add_argument("--write-baseline", help="Write full set of fingerprints for future differential linting")
+    ap.add_argument("--language", action="append", default=[], help="Required label language; repeatable")
+    ap.add_argument("--depth-limit", type=int)
+    ap.add_argument("--inheritance-limit", type=int)
+    ap.add_argument("--soup-limit", type=int)
+    ap.add_argument(
+        "--max-input-bytes", type=_positive_int, help="Refuse input files larger than this (default 64 MiB)"
+    )
+    ap.add_argument(
+        "--max-triples", type=_positive_int, help="Refuse inputs with more triples than this (default 5000000)"
+    )
+    ap.add_argument("--owl-profile", choices=("EL", "QL", "RL", "DL", "Full"))
+    ap.add_argument("--robot-image", default="ontolint-robot:1.9.11")
+    ap.add_argument("--robot-timeout", type=int, default=120)
+    ap.add_argument("--format", choices=FORMATS, default="text")
+    ap.add_argument("--output", help="Output file (default stdout)")
+    ap.add_argument("--fail-on", choices=["error", "warning", "info", "never"], default=None)
+    _add_selection_arguments(ap)
+    return ap
+
+
+def _add_selection_arguments(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--profile", choices=sorted(PROFILES), help="Named rule profile; see the README for each profile")
+    ap.add_argument(
+        "--select", action="append", default=[], help="Rule IDs or families to run; comma-separated, repeatable"
+    )
+    ap.add_argument(
+        "--ignore", action="append", default=[], help="Rule IDs or families to skip; comma-separated, repeatable"
+    )
+    ap.add_argument("--list-rules", action="store_true", help="List implemented and proposed rules, then exit")
+    ap.add_argument("--explain", metavar="RULE", help="Explain one rule, then exit")
+    ap.add_argument("--version", action="store_true", help="Print the version, then exit")
+
+
+def _policy(args: argparse.Namespace, config: Policy, ignored: frozenset[str]) -> Policy:
+    """Merge CLI options over the policy file; explicit CLI options take precedence."""
+    return replace(
+        config,
+        base=args.base if args.base is not None else config.base,
+        languages=tuple(x.lower() for x in args.language) if args.language else config.languages,
+        depth_limit=args.depth_limit if args.depth_limit is not None else config.depth_limit,
+        inheritance_limit=args.inheritance_limit if args.inheritance_limit is not None else config.inheritance_limit,
+        soup_limit=args.soup_limit if args.soup_limit is not None else config.soup_limit,
+        max_input_bytes=args.max_input_bytes if args.max_input_bytes is not None else config.max_input_bytes,
+        max_triples=args.max_triples if args.max_triples is not None else config.max_triples,
+        ignored_rules=ignored,
+    )
+
+
+@dataclass(frozen=True)
+class RunPlan:
+    """Everything shared by every file of one invocation."""
+
+    policy: Policy
+    selection: Selection
+    overrides: dict[str, str]
+    shapes: Graph | None
+    registry: RuleRegistry
+
+
+def _lint_file(item: InputFile, graph: Graph, plan: RunPlan, args: argparse.Namespace) -> FileReport:
+    """Lint one parsed file and record an execution outcome for every selected rule."""
+    ctx = engine.build_context(graph, plan.shapes, plan.policy)
+    if ctx.context.ownership.base_selected_nothing:
+        print(
+            f"TOOL002: warning: --base {plan.policy.base!r} selects none of the terms declared in {item.display}; "
+            "term-level rules have nothing to check (is the base a prefix of the term IRIs?)",
+            file=sys.stderr,
+        )
+    robot = (
+        engine.RobotRequest(item.path, args.owl_profile, args.robot_image, args.robot_timeout)
+        if args.owl_profile
+        else None
+    )
+    executions: list[RuleExecution] = []
+    findings: tuple[Finding, ...] = ()
+    run_ids = [s.rule_id for s in plan.selection.run]
+    if run_ids:
+        result = engine.execute(ctx, run_ids, registry=plan.registry, robot=robot)
+        findings, executions = result.findings, list(result.executions)
+    executions += [
+        RuleExecution(s.rule_id, ExecutionStatus.SKIPPED, "ignored by --ignore or profile")
+        for s in plan.selection.ignored
+    ]
+    findings = tuple(replace(f, severity=plan.overrides.get(f.rule, f.severity)) for f in _legacy_order(findings, plan))
+    return FileReport(item.display, item.uri, findings, tuple(sorted(executions, key=lambda x: x.rule_id)))
+
+
+def _legacy_order(findings: Sequence[Finding], plan: RunPlan) -> list[Finding]:
+    """Graph rules first (already sorted), then SHACL, then ROBOT: the order reports have always used."""
+    rank = {RuleBackend.RDFLIB: 0, RuleBackend.PYSHACL: 1, RuleBackend.ROBOT_DOCKER: 2}
+    backends = {s.rule_id: s.backend for s in plan.registry.all()}
+    return sorted(findings, key=lambda f: rank.get(backends.get(f.rule, RuleBackend.RDFLIB), 0))
+
+
+def _file_fingerprints(report: FileReport, multi: bool) -> set[str]:
+    return {fingerprint(f, report.path if multi else None) for f in report.findings}
+
+
+def _apply_baselines(files: list[FileReport], args: argparse.Namespace) -> list[FileReport]:
+    multi = len(files) > 1
+    if args.write_baseline:
+        everything = sorted(set().union(*(_file_fingerprints(r, multi) for r in files)))
+        Path(args.write_baseline).write_text(
+            json.dumps({"fingerprints": everything}, indent=2) + "\n", encoding="utf-8"
+        )
+    if args.baseline:
+        prior = set(json.loads(Path(args.baseline).read_text(encoding="utf-8")).get("fingerprints", []))
+        files = [
+            replace(r, findings=tuple(f for f in r.findings if fingerprint(f, r.path if multi else None) not in prior))
+            for r in files
+        ]
+    return files
+
+
+_LOADER_POLICY: ContextVar[Policy | None] = ContextVar("loader_policy", default=None)
+
+
+def _parse_inputs(inputs: list[InputFile]) -> tuple[list[Graph], list[str]]:
+    """Parse every input safely (no network, bounded size); return the graphs and one message per failure.
+
+    The limits come from the policy of the current run (:data:`_LOADER_POLICY`, set by :func:`_lint`).
+    """
+    policy = _LOADER_POLICY.get() or Policy()
+    graphs: list[Graph] = []
+    errors: list[str] = []
+    for item in inputs:
+        try:
+            graphs.append(load_graph(item, policy))
+        except InputRejected as exc:
+            where = f" for {item.display}" if len(inputs) > 1 and item.display not in exc.message else ""
+            errors.append(f"{exc.rule_id}: {exc.message}{where}")
+        except Exception as exc:  # noqa: BLE001 -- any other failure (unreadable file ...) is a reportable input error.
+            errors.append(_parse_error(exc, item.display if len(inputs) > 1 else None))
+    return graphs, errors
+
+
+def _parse_error(exc: Exception, display: str | None) -> str:
+    """The ``INPUT001`` line for a parse failure; ``display`` names the file when several were given."""
+    where = f" for {display}" if display else ""
+    name, detail = (exc.cause_type, exc.detail) if isinstance(exc, ParseFailure) else (type(exc).__name__, str(exc))
+    return f"INPUT001: RDF input parsing failed{where}: {name}: {detail}"
+
+
+def _info_command(args: argparse.Namespace) -> int | None:
+    """Handle --version, --list-rules and --explain; ``None`` means a normal lint run."""
+    registry = default_registry()
+    if args.version:
+        print(f"ontolint {package_version()}")
+    elif args.list_rules:
+        print(render_rule_list(rule_rows(registry), "json" if args.format != "text" else "text"))
+    elif args.explain:
+        try:
+            print(render_explanation(explain_rule(args.explain, registry), "json" if args.format != "text" else "text"))
+        except UnknownRuleError:
+            print(f"TOOL001: unknown rule {args.explain!r}; use --list-rules to see valid identifiers", file=sys.stderr)
+            return 2
+    else:
+        return None
+    return 0
+
+
+def _profile(args: argparse.Namespace) -> Profile | None:
+    return PROFILES[args.profile] if args.profile else None
+
+
+def _plan(args: argparse.Namespace, config: Policy, shapes: Graph | None, registry: RuleRegistry) -> RunPlan:
+    profile = _profile(args)
+    selection = resolve_selection(registry, profile, split_selectors(args.select), split_selectors(args.ignore))
+    overrides = {**dict(profile.severity_overrides if profile else ()), **config.severity_mapping}
+    return RunPlan(_policy(args, config, config.ignored_rules), selection, overrides, shapes, registry)
+
+
+def _emit(output: str, args: argparse.Namespace) -> None:
+    if args.output:
+        Path(args.output).write_text(output + "\n", encoding="utf-8")
+    else:
+        print(output)
+
+
+def _lint(args: argparse.Namespace, stage: list[str]) -> RunReport | int:
+    """Run the whole lint; ``stage`` tracks progress for error messages. Returns a report or an exit code."""
+    registry = default_registry()
+    config = Policy.from_mapping(json.loads(Path(args.config).read_text(encoding="utf-8")) if args.config else {})
+    stage[0] = "RDF input parsing"
+    limits = _policy(args, config, config.ignored_rules)
+    inputs = resolve_inputs(args.ontology, Path.cwd())
+    _LOADER_POLICY.set(limits)
+    graphs, errors = _parse_inputs(inputs)
+    if errors:
+        print("\n".join(errors), file=sys.stderr)
+        return 2
+    shapes: Graph | None = None
+    if args.shapes:
+        try:
+            shapes = load_graph(resolve_inputs([args.shapes], Path.cwd())[0], limits)
+        except InputRejected as exc:
+            print(f"{exc.rule_id}: {exc.message}", file=sys.stderr)
+            return 2
+        except ParseFailure as exc:
+            print(_parse_error(exc, None), file=sys.stderr)
+            return 2
+    stage[0] = "lint execution"
+    plan = _plan(args, config, shapes, registry)
+    files = [_lint_file(item, graph, plan, args) for item, graph in zip(inputs, graphs, strict=True)]
+    return RunReport(tuple(_apply_baselines(files, args)), plan.selection.run + plan.selection.ignored, plan.overrides)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the linter CLI and return its process exit code (0 clean, 1 gated findings, 2 tool failure)."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    info = _info_command(args)
+    if info is not None:
+        return info
+    if not args.ontology:
+        parser.error("at least one ONTOLOGY path is required")
+    stage = ["configuration"]
+    try:
+        outcome = _lint(args, stage)
+    except (UnknownSelectorError, SelectorSyntaxError) as exc:
+        proposed = frozenset(row.rule_id for row in planned_rows())
+        message = unknown_selector_help(exc, proposed) if isinstance(exc, UnknownSelectorError) else str(exc)
+        print(f"TOOL001: configuration failed: {type(exc).__name__}: {message}", file=sys.stderr)
+        return 2
+    except Exception as exc:
+        # Parser/configuration errors are tool failures, not SHACL conformance results.
+        code = "INPUT001" if stage[0] == "RDF input parsing" else "TOOL001"
+        print(f"{code}: {stage[0]} failed: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 2
+    if isinstance(outcome, int):
+        return outcome
+    return _finish(outcome, args)
+
+
+def _finish(report: RunReport, args: argparse.Namespace) -> int:
+    profile = _profile(args)
+    fail_on = args.fail_on or (profile.fail_on if profile else "error")
+    code = run_exit_code(report, fail_on)
+    _emit(render_report(report, args.format, code), args)
+    for path, x in report.broken:
+        print(f"TOOL001: rule {x.rule_id} {x.status.value} for {path}: {x.detail}", file=sys.stderr)
+    return code