code-constraints 0.1.0__py3-none-any.whl

code_constraints/lint/rules/max_class_fanout.py

@@ -0,0 +1,41 @@
+"""Rule: cap the number of distinct outgoing class references on any class."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from code_constraints.core.model import DiffStatus
+from code_constraints.lint.rules import register
+from code_constraints.lint.rules.base import Rule, RuleContext, Violation
+
+
+@register("max-class-fanout")
+class MaxClassFanout(Rule):
+    """Options:
+      limit:  int, maximum allowed distinct outgoing references (default 10)
+    """
+
+    def check(self, ctx: RuleContext) -> Iterable[Violation]:
+        try:
+            limit = int(self.options.get("limit", 10))
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"max-class-fanout: 'limit' must be an integer: {exc}") from exc
+        for cls in ctx.project.iter_classes():
+            if cls.status == DiffStatus.REMOVED:
+                continue
+            if self.is_ignored(cls.qualified_name):
+                continue
+            if self.scope == "diff" and ctx.has_diff:
+                if cls.status not in (DiffStatus.ADDED, DiffStatus.CHANGED):
+                    continue
+            fanout = len(ctx.outgoing_refs.get(cls.qualified_name, set()))
+            if fanout <= limit:
+                continue
+            yield self.emit(
+                qualified_name=cls.qualified_name,
+                message=self.message_for(
+                    qualified_name=cls.qualified_name, fanout=fanout, limit=limit
+                )
+                or f"Class '{cls.qualified_name}' has fanout {fanout} (limit: {limit}).",
+                location=cls.location,
+            )

code_constraints/lint/rules/no_new_classes.py

@@ -0,0 +1,27 @@
+"""Rule: forbid adding new classes."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from code_constraints.core.model import DiffStatus
+from code_constraints.lint.rules import register
+from code_constraints.lint.rules.base import Rule, RuleContext, Violation, changed_classes
+
+
+@register("no-new-classes")
+class NoNewClasses(Rule):
+    default_scope = "diff"
+
+    def check(self, ctx: RuleContext) -> Iterable[Violation]:
+        if not ctx.has_diff:
+            return
+        for cls in changed_classes(ctx, only_status=DiffStatus.ADDED):
+            if self.is_ignored(cls.qualified_name):
+                continue
+            yield self.emit(
+                qualified_name=cls.qualified_name,
+                message=self.message_for(qualified_name=cls.qualified_name)
+                or f"New class '{cls.qualified_name}' was added.",
+                location=cls.location,
+            )

code_constraints/lint/rules/no_removed_classes.py

@@ -0,0 +1,27 @@
+"""Rule: forbid removing classes."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from code_constraints.core.model import DiffStatus
+from code_constraints.lint.rules import register
+from code_constraints.lint.rules.base import Rule, RuleContext, Violation, changed_classes
+
+
+@register("no-removed-classes")
+class NoRemovedClasses(Rule):
+    default_scope = "diff"
+
+    def check(self, ctx: RuleContext) -> Iterable[Violation]:
+        if not ctx.has_diff:
+            return
+        for cls in changed_classes(ctx, only_status=DiffStatus.REMOVED):
+            if self.is_ignored(cls.qualified_name):
+                continue
+            yield self.emit(
+                qualified_name=cls.qualified_name,
+                message=self.message_for(qualified_name=cls.qualified_name)
+                or f"Class '{cls.qualified_name}' was removed.",
+                location=cls.location,
+            )

code_constraints/lint/rules/reference_architecture.py

@@ -0,0 +1,111 @@
+"""Rule: the code must not deviate structurally from the reference model.
+
+The adapter for the reference gate (`code_constraints.reference`). Where the
+other rules are scalpels — each one enforcing exactly the law you wrote down —
+this one is a wall: *any* structural difference from the committed
+`.cdec/reference.xmi` fails.
+
+It earns its place beside `frozen-members` because the two sit on different
+comparison engines. The diff engine matches members by signature and only calls
+a matched member changed when its *rule tags* differ, so it is blind to
+visibility changes (`public` -> `private`), modifier changes (`static`,
+`abstract`, `readonly`) and class-kind changes. The reference comparator walks
+both models field by field and catches all of them. A pull request that flips a
+public method to private passes `frozen-members` and fails this.
+
+Generating the reference is `cdec check --automatic-exceptions reference`, which
+is what `accept_current_state` below does: re-snapshot the source and commit the
+new model in the same pull request, so the architectural delta is reviewable.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+from code_constraints.lint.rules import register
+from code_constraints.lint.rules.base import Rule, RuleContext, RuleSkipped, Violation
+
+
+@register("reference-architecture")
+class ReferenceArchitecture(Rule):
+    """Options:
+      reference:  path to the reference model, relative to the project root
+                  (default: the project's `reference:` setting, else
+                  `.cdec/reference.xmi`).
+      categories: optional list[str] of deviation categories to enforce, e.g.
+                  ["class-removed", "operation-changed"]. Default: all of them.
+    """
+
+    supports_auto_accept = True
+
+    def reference_path(self, ctx: RuleContext) -> Path:
+        configured = self.options.get("reference")
+        if configured:
+            base = ctx.config_dir.parent if ctx.config_dir else Path(".")
+            path = Path(str(configured))
+            return path if path.is_absolute() else (base / path)
+        if ctx.reference_path is not None:
+            return ctx.reference_path
+        raise RuleSkipped("no reference model configured")
+
+    def check(self, ctx: RuleContext) -> Iterable[Violation]:
+        path = self.reference_path(ctx)
+        if not path.is_file():
+            raise RuleSkipped(
+                f"reference model not found: {path}. Snapshot one with "
+                f"`cdec check --automatic-exceptions reference`."
+            )
+        from code_constraints.core.model_io import load_model
+        from code_constraints.reference import compare_to_reference
+
+        if ctx.source is None or not ctx.language:
+            raise RuleSkipped("no source tree resolved")
+
+        # The rule compares against the *current* parse, never the annotated
+        # diff project: a removed class is still present (marked REMOVED) in the
+        # annotated model, and the gate must see it as gone.
+        from code_constraints.lint.pipeline import parse_source
+
+        try:
+            deviations = compare_to_reference(
+                load_model(path), parse_source(ctx.source, ctx.language)
+            )
+        except ValueError as exc:
+            raise RuleSkipped(str(exc)) from exc
+
+        only = {str(c) for c in (self.options.get("categories") or [])}
+        for deviation in deviations:
+            if only and deviation.category not in only:
+                continue
+            if self.is_ignored(deviation.qualified_name):
+                continue
+            yield Violation(
+                rule_id=self.rule_id,
+                severity=self.severity,
+                qualified_name=deviation.qualified_name,
+                message=self.message_for(
+                    qualified_name=deviation.qualified_name,
+                    category=deviation.category,
+                    member=deviation.member or "",
+                    message=deviation.message,
+                )
+                or deviation.message,
+                signature=deviation.member or deviation.category,
+                key_engine="reference",
+                key_rule=deviation.category,
+            )
+
+    def accept_current_state(self, ctx: RuleContext, *, force: bool = False) -> list[str]:
+        """Re-snapshot the reference from the current source."""
+        if ctx.source is None or not ctx.language:
+            raise RuleSkipped("no source tree resolved")
+        from code_constraints.core.model_io import save_model
+        from code_constraints.lint.pipeline import parse_source
+
+        path = self.reference_path(ctx)
+        project = parse_source(ctx.source, ctx.language)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        save_model(project, path)
+        n_classes = sum(1 for _ in project.iter_classes())
+        return [f"  wrote {path} ({n_classes} class(es) snapshotted from {ctx.source})"]

code_constraints/lint/rules/subclass_naming.py

@@ -0,0 +1,71 @@
+"""Rule: enforce a naming pattern on classes inheriting from a base/interface.
+
+Example: every implementation of `IFactory` must end in `Factory`.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+from code_constraints.core.model import DiffStatus
+from code_constraints.lint.rules import register
+from code_constraints.lint.rules.base import Rule, RuleContext, Violation, match_any_glob
+
+
+@register("subclass-naming")
+class SubclassNaming(Rule):
+    """Options:
+      base:          glob pattern matched against entries in `Class.bases`
+                     (e.g. "IFactory", "*.IFactory")
+      name_pattern:  regex applied to the class name (full match)
+    """
+
+    def check(self, ctx: RuleContext) -> Iterable[Violation]:
+        base_pattern = self.options.get("base")
+        name_pattern = self.options.get("name_pattern")
+        if not base_pattern or not name_pattern:
+            return
+        try:
+            regex = re.compile(name_pattern)
+        except re.error as exc:  # pragma: no cover - config-validation territory
+            raise ValueError(
+                f"subclass-naming: invalid name_pattern regex {name_pattern!r}: {exc}"
+            ) from exc
+
+        base_globs = base_pattern if isinstance(base_pattern, list) else [base_pattern]
+
+        for cls in ctx.project.iter_classes():
+            if cls.status == DiffStatus.REMOVED:
+                continue
+            if self.is_ignored(cls.qualified_name):
+                continue
+            if self.scope == "diff" and ctx.has_diff:
+                if cls.status not in (DiffStatus.ADDED, DiffStatus.CHANGED):
+                    continue
+            # Match if any of the class's bases matches the configured base.
+            # We match both the literal base text and its short name (last
+            # dotted segment) so callers can write either "IFactory" or
+            # "myapp.factories.IFactory".
+            matched = False
+            for base in cls.bases:
+                short = base.split(".")[-1]
+                if match_any_glob(base, base_globs) or match_any_glob(short, base_globs):
+                    matched = True
+                    break
+            if not matched:
+                continue
+            if regex.fullmatch(cls.name):
+                continue
+            yield self.emit(
+                qualified_name=cls.qualified_name,
+                message=self.message_for(
+                    qualified_name=cls.qualified_name,
+                    name=cls.name,
+                    base=base_pattern,
+                    pattern=name_pattern,
+                )
+                or f"Class '{cls.qualified_name}' inherits from {base_pattern!r} "
+                f"but its name does not match /{name_pattern}/.",
+                location=cls.location,
+            )

code_constraints/lint/rules/tag_conformance.py

@@ -0,0 +1,76 @@
+"""Rule: the implementation must honour the constraint tags written on it.
+
+This is the adapter for the conformance engine (`code_constraints.enforce`,
+"Engine B"). Every other rule in this package reads only the model; this one
+re-parses the source and inspects method bodies, which is why it needs
+`ctx.source` and `ctx.language`.
+
+The engine stays an independent package with its own result type — the rule
+imports it lazily and translates `Finding`s into `Violation`s. What the
+`rules.yaml` entry buys is uniformity: tag conformance is now configured,
+reported, ignored and excepted exactly like every other law in the file, instead
+of through a second command with a second report and a second exit code.
+
+Violations key under the `enforce` engine (`F-…`), not under the rules entry, so
+renaming the entry never invalidates a granted exception.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from code_constraints.core.model import SourceLocation
+from code_constraints.lint.rules import register
+from code_constraints.lint.rules.base import Rule, RuleContext, RuleSkipped, Violation
+
+#: Languages whose parsers recognise constraint tags. The other supported
+#: languages parse and diff fine but have no tag syntax, so a `tag-conformance`
+#: rule there would report "clean" while checking nothing.
+TAGGED_LANGUAGES = ("python", "csharp", "odin", "lua", "julia")
+
+
+@register("tag-conformance")
+class TagConformance(Rule):
+    """Options:
+      rules:  optional list[str] of catalog ids to check (default: all of them),
+              e.g. ["no-instantiation", "factory"] to adopt one tag at a time.
+    """
+
+    def check(self, ctx: RuleContext) -> Iterable[Violation]:
+        if ctx.source is None or not ctx.language:
+            raise RuleSkipped("no source tree resolved")
+        if ctx.language not in TAGGED_LANGUAGES:
+            raise RuleSkipped(
+                f"{ctx.language} has no constraint-tag syntax; supported: "
+                f"{', '.join(TAGGED_LANGUAGES)}"
+            )
+        from code_constraints.enforce import enforce as run_enforce
+
+        only = {str(r) for r in (self.options.get("rules") or [])}
+        findings = run_enforce(ctx.source, ctx.language)
+        for finding in findings:
+            if only and finding.rule not in only:
+                continue
+            if self.is_ignored(finding.qualified_name):
+                continue
+            location = (
+                SourceLocation(file=finding.file, start_line=finding.line, end_line=finding.line)
+                if finding.file
+                else None
+            )
+            yield Violation(
+                rule_id=self.rule_id,
+                severity=self.severity,
+                qualified_name=finding.qualified_name,
+                message=self.message_for(
+                    qualified_name=finding.qualified_name,
+                    rule=finding.rule,
+                    detail=finding.detail,
+                    message=finding.message,
+                )
+                or finding.message,
+                location=location,
+                signature=finding.detail,
+                key_engine="enforce",
+                key_rule=finding.rule,
+            )

code_constraints/lock/__init__.py

@@ -0,0 +1,73 @@
+"""The implementation-freeze engine (Engine C).
+
+Freezes the *body* of a class or function so it cannot change without an
+explicit, reviewable re-baseline. Identity is AST-derived, not line-based, so
+code added above a locked element never trips it.
+
+Driven by the `implementation-locks` rule type in `.cdec/rules.yaml`, which is
+what `cdec check` runs. This package stays independent of the other engines:
+the rule is a thin adapter over the entry points below.
+
+Public surface:
+
+    from code_constraints.lock import (
+        LockOptions, check_locks, update_locks, collect_targets,
+        load_locks, write_locks, format_report,
+    )
+"""
+
+from code_constraints.lock.engine import (
+    BYPASS_ENV,
+    BYPASS_REASON_ENV,
+    LockOptions,
+    UnsupportedLockLanguage,
+    UpdateResult,
+    check_locks,
+    collect_targets,
+    is_locked_target,
+    resolve_entries_for_removal,
+    update_locks,
+)
+from code_constraints.lock.model import (
+    LOCK_RULE,
+    LockEntry,
+    LockReport,
+    LockTarget,
+    LockViolation,
+    format_report,
+    match_any_glob,
+    report_to_json,
+)
+from code_constraints.lock.store import (
+    LOCKFILE_VERSION,
+    LOCKS_FILENAME,
+    LockfileError,
+    load_locks,
+    write_locks,
+)
+
+__all__ = [
+    "BYPASS_ENV",
+    "BYPASS_REASON_ENV",
+    "LOCKFILE_VERSION",
+    "LOCKS_FILENAME",
+    "LOCK_RULE",
+    "LockEntry",
+    "LockOptions",
+    "LockReport",
+    "LockTarget",
+    "LockViolation",
+    "LockfileError",
+    "UnsupportedLockLanguage",
+    "UpdateResult",
+    "check_locks",
+    "collect_targets",
+    "format_report",
+    "is_locked_target",
+    "load_locks",
+    "match_any_glob",
+    "report_to_json",
+    "resolve_entries_for_removal",
+    "update_locks",
+    "write_locks",
+]