code-constraints 0.1.0__py3-none-any.whl

code_constraints/julia/rules_extract.py

@@ -0,0 +1,216 @@
+"""Recognise architectural-rule macros on Julia declarations.
+
+Shared by the UML parser, the `cdec enforce` conformance analyzer and the
+`cdec lock` fingerprinter, so "what counts as a rule" stays identical across all
+three — the same contract the Python and C# extractors hold. A macro counts as a
+rule only when the file brings the shim module into scope (`using CdecRules` /
+`import CdecRules`), so a user's own `@sealed` is never misread.
+
+Two shapes worth knowing, both of which this module folds into one
+`(rules, definition)` pair via `unwrap_macros`:
+
+1. **Stacked tags nest.** Real Julia parses `@sealed @layer "domain" struct X end`
+   as `@sealed(@layer("domain", struct X end))` — one argument, itself a
+   macrocall. tree-sitter instead emits the inner macrocall and the struct as
+   *siblings* inside the outer `macro_argument_list`. `unwrap_macros` handles
+   both by scanning the argument list for nested macrocalls and for the
+   definition, then recursing.
+
+2. **Arguments are space-separated, not parenthesised.** `@locked reason="why"
+   function f() end` puts each keyword in its own `assignment` node alongside the
+   definition. That collides with Julia's short-form function syntax, which is
+   *also* an `assignment` (`f(x::T) = x`); the two are told apart by their
+   left-hand side (`identifier` for a keyword, `call_expression` for a
+   definition). `@layer("domain")` — the parenthesised form — is a syntax error
+   in Julia, but the grammar accepts it, so `_macro_args` reads an
+   `argument_list` too rather than silently dropping the tag.
+"""
+
+from __future__ import annotations
+
+from tree_sitter import Node
+
+from code_constraints.core.model import RuleAnnotation
+from code_constraints.core.rules import JULIA_SHIM_MODULES, by_julia_name
+
+# Node types that can be the definition a tag decorates.
+DEFINITION_TYPES = frozenset(
+    {
+        "struct_definition",
+        "abstract_definition",
+        "primitive_definition",
+        "function_definition",
+        "assignment",  # short-form function definition: `f(x::T) = ...`
+        "const_statement",
+        "macro_definition",
+    }
+)
+
+
+def using_has_shim(root: Node, source: bytes) -> bool:
+    """True when the file brings the shim module into scope."""
+    stack = [root]
+    while stack:
+        node = stack.pop()
+        if node.type in ("using_statement", "import_statement"):
+            text = _text(node, source)
+            if any(mod in text for mod in JULIA_SHIM_MODULES):
+                return True
+        stack.extend(node.children)
+    return False
+
+
+def unwrap_macros(node: Node, source: bytes, shim_in_scope: bool) -> tuple[
+    list[RuleAnnotation], Node | None
+]:
+    """Peel every macro wrapping `node` and return its rules + the definition.
+
+    For a node that isn't a macrocall this is `([], node)`. Macros that aren't in
+    the rule catalog are peeled too — their arguments still contain the
+    definition, so an unrelated `@inline`/`Base.@kwdef` wrapper doesn't hide the
+    struct from the parser — but they contribute no `RuleAnnotation`.
+    """
+    if node.type != "macrocall_expression":
+        return [], node
+
+    rules: list[RuleAnnotation] = []
+    definition: Node | None = None
+    pending: list[Node] = [node]
+
+    while pending:
+        current = pending.pop(0)
+        if current.type != "macrocall_expression":
+            continue
+        spec_id = _macro_rule_id(current, source, shim_in_scope)
+        args, kwargs, nested, found = _macro_args(current, source)
+        if spec_id is not None:
+            rules.append(RuleAnnotation(name=spec_id, args=args, kwargs=kwargs))
+        if found is not None and definition is None:
+            definition = found
+        pending.extend(nested)
+
+    if definition is not None and definition.type == "macrocall_expression":
+        inner_rules, inner_def = unwrap_macros(definition, source, shim_in_scope)
+        rules.extend(inner_rules)
+        definition = inner_def
+
+    return rules, definition
+
+
+def extract_rules(node: Node, source: bytes, shim_in_scope: bool) -> list[RuleAnnotation]:
+    """Just the rules from the macros wrapping `node`."""
+    rules, _ = unwrap_macros(node, source, shim_in_scope)
+    return rules
+
+
+def foreign_macros(node: Node, source: bytes, shim_in_scope: bool) -> list[str]:
+    """Text of every non-catalog macro applied to `node`, sorted.
+
+    The fingerprinter digests the *unwrapped* definition, because the grammar
+    flattens stacked macros into siblings and there is no way to peel one tag
+    while re-serialising the rest of the chain around it. Folding this list into
+    the digest restores what unwrapping would otherwise lose: adding or removing
+    an `@inline` is a real change, while adding or removing `@locked` is not.
+    """
+    out: list[str] = []
+    pending = [node]
+    while pending:
+        current = pending.pop(0)
+        if current.type != "macrocall_expression":
+            continue
+        ident = next((c for c in current.children if c.type == "macro_identifier"), None)
+        if ident is not None and _macro_rule_id(current, source, shim_in_scope) is None:
+            prefix = (
+                _text(current.children[0], source) + "."
+                if current.children and current.children[0].type == "identifier"
+                else ""
+            )
+            out.append(prefix + _text(ident, source))
+        _args, _kwargs, nested, found = _macro_args(current, source)
+        pending.extend(nested)
+        if found is not None and found.type == "macrocall_expression":
+            pending.append(found)
+    return sorted(out)
+
+
+def macro_is_rule(node: Node, source: bytes, shim_in_scope: bool, rule_id: str) -> bool:
+    """True when `node` is a `macrocall_expression` for the given catalog rule.
+
+    The fingerprinter needs the node-to-tag mapping that `extract_rules` loses,
+    to drop the lock tag from a digest without dropping the definition it wraps.
+    """
+    if node.type != "macrocall_expression":
+        return False
+    return _macro_rule_id(node, source, shim_in_scope) == rule_id
+
+
+def _macro_rule_id(node: Node, source: bytes, shim_in_scope: bool) -> str | None:
+    if not shim_in_scope:
+        return None
+    ident = next((c for c in node.children if c.type == "macro_identifier"), None)
+    if ident is None:
+        return None
+    # A qualified call (`Base.@kwdef`) puts an identifier + `.` before the macro
+    # identifier; those are never our tags.
+    if node.children and node.children[0].type == "identifier":
+        return None
+    spec = by_julia_name(_text(ident, source))
+    return spec.id if spec else None
+
+
+def _macro_args(
+    node: Node, source: bytes
+) -> tuple[list[str], dict[str, str], list[Node], Node | None]:
+    """Split a macrocall's arguments into positional / keyword / nested macros /
+    the decorated definition."""
+    args: list[str] = []
+    kwargs: dict[str, str] = {}
+    nested: list[Node] = []
+    definition: Node | None = None
+
+    arglist = next(
+        (
+            c
+            for c in node.children
+            if c.type in ("macro_argument_list", "argument_list")
+        ),
+        None,
+    )
+    if arglist is None:
+        return args, kwargs, nested, definition
+
+    for child in arglist.named_children:
+        if child.type == "macrocall_expression":
+            nested.append(child)
+        elif child.type in ("assignment", "named_argument") and _is_keyword(child):
+            name, value = _keyword_parts(child, source)
+            if name:
+                kwargs[name] = value
+        elif child.type in DEFINITION_TYPES:
+            if definition is None:
+                definition = child
+        else:
+            args.append(_text(child, source))
+
+    return args, kwargs, nested, definition
+
+
+def _is_keyword(node: Node) -> bool:
+    """`reason="why"` is a keyword argument; `f(x::T) = x` is a definition."""
+    if node.type == "named_argument":
+        return True
+    first = node.named_children[0] if node.named_children else None
+    return first is not None and first.type == "identifier"
+
+
+def _keyword_parts(node: Node, source: bytes) -> tuple[str, str]:
+    named = node.named_children
+    if len(named) < 2:
+        return "", ""
+    return _text(named[0], source), _text(named[-1], source)
+
+
+def _text(node: Node | None, source: bytes) -> str:
+    if node is None:
+        return ""
+    return source[node.start_byte : node.end_byte].decode("utf-8", errors="replace")

code_constraints/lint/__init__.py

@@ -0,0 +1,10 @@
+"""Architectural-lint engine for `cdec check`.
+
+Reads rule definitions from a project-root `.cdec/` folder, runs them against
+the current `Project` (optionally diffed against a reference), and emits a
+report. Designed to gate CI on rule violations.
+"""
+
+from code_constraints.lint.engine import run_checks  # noqa: F401
+from code_constraints.lint.report import Report  # noqa: F401
+from code_constraints.lint.rules.base import Severity, Violation  # noqa: F401

code_constraints/lint/baseline.py

@@ -0,0 +1,96 @@
+"""The rule engine's view of the `exceptions:` ledger.
+
+The file itself is owned by `code_constraints.waivers.store`, which is engine-
+agnostic; this module is the thin adapter that turns `Violation`s into lookups
+against it. Keeping the file format in one place is what lets an exception
+granted from a reviewed report and one recorded by
+`cdec check --automatic-exceptions` land in the same list.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+from code_constraints.lint.rules.base import Violation
+from code_constraints.waivers.store import (
+    Waiver,
+    WaiverStore,
+    load_waivers,
+    now_stamp,
+    save_waivers,
+)
+
+
+@dataclass
+class Baseline:
+    store: WaiverStore = field(default_factory=WaiverStore)
+
+    def contains(self, v: Violation) -> bool:
+        # Locks are never exempted: `Violation.waivable` is False for them, and
+        # honouring an `exceptions:` entry here would be a silent back door
+        # around the privileged re-baseline.
+        return v.waivable and self.store.has(v.key())
+
+    def filter(
+        self, violations: list[Violation]
+    ) -> tuple[list[Violation], list[Violation]]:
+        kept: list[Violation] = []
+        suppressed: list[Violation] = []
+        for v in violations:
+            (suppressed if self.contains(v) else kept).append(v)
+        return kept, suppressed
+
+
+def load_baseline(config_dir: Path) -> Baseline:
+    return Baseline(store=load_waivers(config_dir))
+
+
+def write_baseline(config_dir: Path, violations: Iterable[Violation]) -> Path:
+    """Grandfather `violations` as the accepted set — `--automatic-exceptions`.
+
+    Every engine's exceptions are rewritten together, because the violations
+    handed in come from one run of every rule. Non-waivable violations (locks)
+    are dropped rather than recorded: accepting one of those is a privileged
+    re-baseline, never an exception. Reason / author / date already recorded for
+    an issue are carried over, so re-running never erases why something was
+    accepted. Returns the file written.
+    """
+    store = load_waivers(config_dir)
+    stamp = now_stamp()
+    store.replace_all(
+        [
+            Waiver(
+                engine=v.key_engine,
+                rule=v.key_rule or v.rule_id,
+                qualified_name=v.qualified_name,
+                detail=v.signature or "",
+                reason=_existing_reason(store, v),
+                added=_existing_added(store, v) or stamp,
+                added_by=_existing_actor(store, v),
+            )
+            for v in violations
+            if v.waivable
+        ]
+    )
+    return save_waivers(config_dir, store)
+
+
+def _existing(store: WaiverStore, v: Violation) -> Waiver | None:
+    return store.get(v.key())
+
+
+def _existing_reason(store: WaiverStore, v: Violation) -> str:
+    existing = _existing(store, v)
+    return existing.reason if existing else ""
+
+
+def _existing_added(store: WaiverStore, v: Violation) -> str:
+    existing = _existing(store, v)
+    return existing.added if existing else ""
+
+
+def _existing_actor(store: WaiverStore, v: Violation) -> str:
+    existing = _existing(store, v)
+    return existing.added_by if existing else ""

code_constraints/lint/config.py

@@ -0,0 +1,239 @@
+"""Load and validate `.cdec/rules.yaml` — project settings and rules.
+
+One file holds everything: the settings that say *what* to check, the `rules:`
+list that says *which laws apply*, and (in the tool-managed tail, see
+`code_constraints.core.rulesdoc`) the exceptions granted and the digests of
+frozen implementations.
+
+`.cdec/config.yaml` is the legacy home of the settings. It is still read when it
+exists, so a project scaffolded by an older `cdec init` keeps working, but
+`rules.yaml` wins key by key and `cdec init --migrate` folds the old file in.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from code_constraints.core.model import SUPPORTED_LANGUAGES
+from code_constraints.core.rulesdoc import RULES_FILENAME, RulesFileError, load_document
+from code_constraints.lint.rules import get_rule_class, known_rule_types
+from code_constraints.lint.rules.base import Rule, Severity
+
+# `RULES_FILENAME` is re-exported: every consumer already imports the rest of the
+# `.cdec/` vocabulary from here, and splitting the filename off would make them
+# import two modules to name one folder.
+__all__ = [
+    "BASELINE_FILENAME",
+    "CONFIG_FILENAME",
+    "ConfigError",
+    "LOCKS_FILENAME",
+    "LoadedRules",
+    "ProjectConfig",
+    "REFERENCE_FILENAME",
+    "RULES_FILENAME",
+    "legacy_files",
+    "load_project_config",
+    "load_rules",
+    "rules_path",
+]
+
+CONFIG_FILENAME = "config.yaml"  # legacy; superseded by rules.yaml
+REFERENCE_FILENAME = "reference.xmi"
+# Legacy ledgers, folded into rules.yaml by `cdec init --migrate`. Still read
+# when present so an existing project doesn't break on upgrade.
+BASELINE_FILENAME = "baseline.yaml"
+LOCKS_FILENAME = "locks.yaml"
+
+
+class ConfigError(ValueError):
+    pass
+
+
+@dataclass
+class ProjectConfig:
+    """The `what and where` half of `.cdec/rules.yaml`."""
+
+    language: str
+    source: Path
+    config_dir: Path = Path(".cdec")
+    reference: Path | None = None
+    json_out: Path | None = None
+    log_out: Path | None = None
+
+    @property
+    def rules_path(self) -> Path:
+        return self.config_dir / RULES_FILENAME
+
+    @property
+    def reference_path(self) -> Path:
+        return self.reference or (self.config_dir / REFERENCE_FILENAME)
+
+
+@dataclass
+class LoadedRules:
+    rules: list[Rule] = field(default_factory=list)
+
+    def of_type(self, type_name: str) -> list[Rule]:
+        return [r for r in self.rules if r.type_name == type_name]
+
+
+def rules_path(config_dir: Path) -> Path:
+    return config_dir / RULES_FILENAME
+
+
+def legacy_files(config_dir: Path) -> list[Path]:
+    """Legacy per-concern files present in `config_dir`, in migration order."""
+    return [
+        path
+        for path in (
+            config_dir / CONFIG_FILENAME,
+            config_dir / BASELINE_FILENAME,
+            config_dir / LOCKS_FILENAME,
+        )
+        if path.is_file()
+    ]
+
+
+def load_project_config(config_dir: Path) -> ProjectConfig:
+    """Read the project settings. `rules.yaml` wins; `config.yaml` fills gaps."""
+    rules_file = config_dir / RULES_FILENAME
+    legacy_file = config_dir / CONFIG_FILENAME
+    if not rules_file.is_file() and not legacy_file.is_file():
+        raise ConfigError(
+            f"missing {rules_file}. Run `cdec init` to scaffold it."
+        )
+
+    try:
+        raw = load_document(rules_file)
+    except RulesFileError as exc:
+        raise ConfigError(str(exc)) from exc
+    merged: dict[str, Any] = {**_load_legacy_settings(legacy_file), **raw}
+    where = rules_file if rules_file.is_file() else legacy_file
+
+    language = merged.get("language")
+    if language not in SUPPORTED_LANGUAGES:
+        allowed = ", ".join(SUPPORTED_LANGUAGES)
+        raise ConfigError(f"{where}: 'language' must be one of: {allowed}")
+    source = merged.get("source")
+    if not source:
+        raise ConfigError(f"{where}: 'source' is required")
+
+    # `reference:` is a plain top-level path now. The legacy nesting
+    # (`baseline: {reference: ...}`) still resolves.
+    reference_value = merged.get("reference")
+    if reference_value is None:
+        legacy_baseline = merged.get("baseline")
+        if isinstance(legacy_baseline, dict):
+            reference_value = legacy_baseline.get("reference")
+
+    output = merged.get("output") or {}
+    if not isinstance(output, dict):
+        raise ConfigError(f"{where}: 'output' must be a mapping")
+
+    return ProjectConfig(
+        language=language,
+        source=_resolve(source, config_dir.parent),
+        config_dir=config_dir,
+        reference=_resolve(reference_value, config_dir.parent) if reference_value else None,
+        json_out=_resolve(output.get("json"), config_dir.parent) if output.get("json") else None,
+        log_out=_resolve(output.get("log"), config_dir.parent) if output.get("log") else None,
+    )
+
+
+def _load_legacy_settings(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    with path.open("r", encoding="utf-8") as fh:
+        raw = yaml.safe_load(fh) or {}
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{path}: top-level must be a mapping")
+    # `lock:` used to be a settings section; it is now the options of an
+    # `implementation-locks` rule, so it is not carried over here.
+    return {k: v for k, v in raw.items() if k != "lock"}
+
+
+def load_rules(config_dir: Path) -> LoadedRules:
+    """Build the rule objects from the `rules:` list."""
+    path = config_dir / RULES_FILENAME
+    if not path.is_file():
+        # A project still on the legacy layout may have no rules.yaml at all.
+        raise ConfigError(f"missing {path}. Run `cdec init` to scaffold it.")
+    try:
+        raw = load_document(path)
+    except RulesFileError as exc:
+        raise ConfigError(str(exc)) from exc
+
+    entries = raw.get("rules") or []
+    if not isinstance(entries, list):
+        raise ConfigError(f"{path}: 'rules' must be a list")
+
+    out: list[Rule] = []
+    seen_ids: set[str] = set()
+    for i, entry in enumerate(entries):
+        rule = _build_rule(path, i, entry, seen_ids)
+        if rule is not None:
+            out.append(rule)
+    return LoadedRules(rules=out)
+
+
+def _build_rule(
+    path: Path, i: int, entry: Any, seen_ids: set[str]
+) -> Rule | None:
+    if not isinstance(entry, dict):
+        raise ConfigError(f"{path}: rules[{i}] must be a mapping")
+    rule_id = entry.get("id")
+    type_name = entry.get("type")
+    if not rule_id:
+        raise ConfigError(f"{path}: rules[{i}] missing 'id'")
+    if rule_id in seen_ids:
+        raise ConfigError(f"{path}: duplicate rule id {rule_id!r}")
+    seen_ids.add(rule_id)
+    if not type_name:
+        raise ConfigError(f"{path}: rules[{i}] (id={rule_id}) missing 'type'")
+    rule_cls = get_rule_class(type_name)
+    if rule_cls is None:
+        raise ConfigError(
+            f"{path}: rules[{i}] (id={rule_id}) has unknown type {type_name!r}. "
+            f"Known types: {', '.join(known_rule_types())}"
+        )
+    severity_raw = entry.get("severity", "error")
+    # YAML 1.1 parses bare `off` / `on` as booleans; coerce back to strings.
+    if isinstance(severity_raw, bool):
+        severity_raw = "off" if severity_raw is False else "on"
+    try:
+        severity = Severity(severity_raw)
+    except ValueError as exc:
+        raise ConfigError(
+            f"{path}: rules[{i}] (id={rule_id}) has invalid severity {severity_raw!r}"
+        ) from exc
+    if severity == Severity.OFF:
+        return None
+    scope = entry.get("scope", rule_cls.default_scope)
+    if scope not in ("diff", "snapshot"):
+        raise ConfigError(f"{path}: rules[{i}] (id={rule_id}) has invalid scope {scope!r}")
+    ignore = entry.get("ignore") or []
+    if not isinstance(ignore, list):
+        raise ConfigError(f"{path}: rules[{i}] (id={rule_id}) 'ignore' must be a list")
+    reserved = {"id", "type", "severity", "scope", "message", "ignore"}
+    options: dict[str, Any] = {k: v for k, v in entry.items() if k not in reserved}
+    return rule_cls(
+        rule_id=rule_id,
+        severity=severity,
+        scope=scope,
+        message=entry.get("message", ""),
+        ignore=ignore,
+        options=options,
+    )
+
+
+def _resolve(path_value: str | None, base: Path) -> Path:
+    if path_value is None:
+        return base
+    p = Path(path_value)
+    if p.is_absolute():
+        return p
+    return (base / p).resolve()