code-constraints 0.1.0__py3-none-any.whl

code_constraints/python/fingerprint.py

@@ -0,0 +1,231 @@
+"""AST fingerprinting for Python (`cdec lock`, Engine C).
+
+Produces a digest per lockable element (module-level function, class, method,
+nested class) that captures *semantic* content only:
+
+  * line/column attributes are never serialised, so inserting code above a
+    locked function leaves its digest untouched — the whole point of hashing the
+    tree rather than a slice of the file;
+  * comments aren't in the Python AST at all, and docstrings are stripped
+    unless `include_docstrings=True`;
+  * the `@locked` tag itself is stripped recursively, so adding or removing a
+    lock (or a nested one) never invalidates an enclosing digest.
+
+The canonical serialisation is hand-rolled rather than `ast.dump` so it stays
+stable across CPython releases: fields that are `None` or empty are omitted, so
+a newly-introduced optional AST field (e.g. `type_params` in 3.12) doesn't
+silently change every digest. Any genuinely breaking change to this function
+must bump `DIGEST_ALGO`, which surfaces as an `algo-mismatch` violation telling
+the user to re-baseline rather than as a false "implementation changed".
+"""
+
+from __future__ import annotations
+
+import ast
+import copy
+from hashlib import sha256
+from pathlib import Path
+
+from code_constraints.lock.model import LOCK_RULE, LockTarget
+from code_constraints.python.rules_extract import ImportMap, build_import_map, extract_rules
+
+DIGEST_ALGO = "py-ast/1"
+
+_SKIP_DIR_NAMES = {"__pycache__", ".venv", "venv", ".tox", "build", "dist", ".git"}
+# `type_comment` carries a `# type:` comment; it is documentation, not code.
+_SKIP_FIELDS = {"type_comment"}
+
+_FUNC_TYPES = (ast.FunctionDef, ast.AsyncFunctionDef)
+
+
+def collect_lockables(
+    root: str | Path, *, include_docstrings: bool = False
+) -> list[LockTarget]:
+    """Walk `root` and return every lockable element with its digest.
+
+    Every element is returned, not just tagged ones: the engine needs digests
+    for untagged elements too, so it can tell "someone deleted the @locked tag"
+    apart from "the element is gone", and so `lock.targets:` globs can freeze
+    code that isn't practical to decorate (e.g. a whole test package).
+    """
+    root_path = Path(root).resolve()
+    out: list[LockTarget] = []
+    for py_file in sorted(root_path.rglob("*.py")):
+        if any(part in _SKIP_DIR_NAMES for part in py_file.parts):
+            continue
+        try:
+            source = py_file.read_text(encoding="utf-8")
+            tree = ast.parse(source)
+        except (OSError, SyntaxError, ValueError):
+            continue
+        rel = py_file.relative_to(root_path)
+        import_map = build_import_map(tree)
+        class_prefix, func_prefix = _scope_prefixes(rel)
+        _collect_scope(
+            tree.body,
+            class_prefix=class_prefix,
+            func_prefix=func_prefix,
+            in_class=False,
+            file=rel.as_posix(),
+            import_map=import_map,
+            include_docstrings=include_docstrings,
+            out=out,
+        )
+    return out
+
+
+def _scope_prefixes(rel: Path) -> tuple[str, str]:
+    """Return (class_prefix, function_prefix) for a module.
+
+    Classes use the *package* qualified name so lock targets line up with the
+    qualified names everywhere else in the harness (`orders.Receipt`). Module
+    functions additionally carry the module stem (`orders.billing.compute_tax`),
+    since two modules in one package may define same-named functions.
+    """
+    pkg = ".".join(rel.parts[:-1])
+    stem = rel.stem
+    if stem == "__init__":
+        module = pkg
+    else:
+        module = f"{pkg}.{stem}" if pkg else stem
+    return pkg, module
+
+
+def _collect_scope(
+    body: list[ast.stmt],
+    *,
+    class_prefix: str,
+    func_prefix: str,
+    in_class: bool,
+    file: str,
+    import_map: ImportMap,
+    include_docstrings: bool,
+    out: list[LockTarget],
+) -> None:
+    """Group same-named siblings, digest each group, then recurse into classes.
+
+    Grouping is what makes overloads (`@overload`, `@property` + `@x.setter`)
+    behave: one target covers every sibling of that name, so adding, removing,
+    or editing any of them moves the group digest.
+    """
+    groups: dict[str, list[ast.stmt]] = {}
+    for node in body:
+        if isinstance(node, (ast.ClassDef, *_FUNC_TYPES)):
+            groups.setdefault(node.name, []).append(node)
+
+    for name, nodes in groups.items():
+        is_class = isinstance(nodes[0], ast.ClassDef)
+        if is_class:
+            target = f"{class_prefix}.{name}" if class_prefix else name
+            kind = "class"
+        else:
+            prefix = class_prefix if in_class else func_prefix
+            target = f"{prefix}.{name}" if prefix else name
+            kind = "method" if in_class else "function"
+
+        digests = sorted(
+            _digest_node(n, import_map, include_docstrings) for n in nodes
+        )
+        digest = (
+            digests[0]
+            if len(digests) == 1
+            else sha256(("group:" + "|".join(digests)).encode("utf-8")).hexdigest()
+        )
+
+        declared = False
+        params: dict[str, str] = {}
+        for n in nodes:
+            for rule in extract_rules(n.decorator_list, import_map):
+                if rule.name == LOCK_RULE:
+                    declared = True
+                    params = {**rule.kwargs, **params} if params else dict(rule.kwargs)
+
+        out.append(
+            LockTarget(
+                target=target,
+                kind=kind,  # type: ignore[arg-type]
+                digest=digest,
+                algo=DIGEST_ALGO,
+                file=file,
+                line=getattr(nodes[0], "lineno", 0),
+                declared=declared,
+                params=params,
+            )
+        )
+
+        if is_class:
+            for n in nodes:
+                assert isinstance(n, ast.ClassDef)
+                _collect_scope(
+                    n.body,
+                    class_prefix=target,
+                    func_prefix=target,
+                    in_class=True,
+                    file=file,
+                    import_map=import_map,
+                    include_docstrings=include_docstrings,
+                    out=out,
+                )
+
+
+# ---------- digest ----------
+
+def _digest_node(
+    node: ast.stmt, import_map: ImportMap, include_docstrings: bool
+) -> str:
+    clone = copy.deepcopy(node)
+    _normalize(clone, import_map, include_docstrings)
+    return sha256(_canonical(clone).encode("utf-8")).hexdigest()
+
+
+def _normalize(node: ast.AST, import_map: ImportMap, include_docstrings: bool) -> None:
+    """Strip lock tags and (optionally) docstrings from the whole subtree."""
+    for sub in ast.walk(node):
+        decorators = getattr(sub, "decorator_list", None)
+        if decorators is not None:
+            sub.decorator_list = [  # type: ignore[attr-defined]
+                d for d in decorators if not _is_lock_decorator(d, import_map)
+            ]
+        if not include_docstrings and isinstance(
+            sub, (ast.Module, ast.ClassDef, *_FUNC_TYPES)
+        ):
+            _strip_docstring(sub)
+
+
+def _is_lock_decorator(dec: ast.expr, import_map: ImportMap) -> bool:
+    return any(r.name == LOCK_RULE for r in extract_rules([dec], import_map))
+
+
+def _strip_docstring(node: ast.AST) -> None:
+    body = getattr(node, "body", None)
+    if not body or not isinstance(body, list):
+        return
+    first = body[0]
+    if (
+        isinstance(first, ast.Expr)
+        and isinstance(first.value, ast.Constant)
+        and isinstance(first.value.value, str)
+    ):
+        # A body must not become empty — `def f(): """doc"""` is legal Python.
+        node.body = body[1:] if len(body) > 1 else [ast.Pass()]  # type: ignore[attr-defined]
+
+
+def _canonical(node: object) -> str:
+    """Serialise an AST to a deterministic string.
+
+    Position attributes are excluded (they live in `_attributes`, not
+    `_fields`). Empty and `None` fields are omitted so that AST fields added by
+    future Python versions don't shift existing digests.
+    """
+    if isinstance(node, ast.AST):
+        parts: list[str] = []
+        for name, value in ast.iter_fields(node):
+            if name in _SKIP_FIELDS or value is None:
+                continue
+            if isinstance(value, list) and not value:
+                continue
+            parts.append(f"{name}={_canonical(value)}")
+        return f"{type(node).__name__}({','.join(parts)})"
+    if isinstance(node, list):
+        return "[" + ",".join(_canonical(v) for v in node) + "]"
+    return repr(node)

code_constraints/python/parser.py

@@ -0,0 +1,330 @@
+"""Parse a Python project (directory of .py files) into a `code_constraints.core.Project`.
+
+Strategy:
+- Walk the directory; every `.py` file is parsed with `ast.parse`.
+- Packages are derived from directory structure relative to the root.
+- Each `ClassDef` becomes a `code_constraints.core.Class`. Methods become `Operation`s.
+  Class-level type-annotated assignments and `self.x = ...` in `__init__`
+  become `Attribute`s.
+- Activity / sequence tags found in source are forwarded to `activity.py` and
+  `sequence.py` (built later) which turn tagged regions into UML elements.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+from code_constraints.core.model import (
+    Attribute,
+    Class,
+    Operation,
+    Package,
+    Parameter,
+    Project,
+    SourceLocation,
+    Visibility,
+)
+from code_constraints.core.tags import TagInstance, find_tags
+from code_constraints.python.activity import build_activity_from_tag
+from code_constraints.python.rules_extract import ImportMap, build_import_map, extract_rules
+from code_constraints.python.sequence import build_sequence_from_tag
+
+
+def parse_project(root: str | Path) -> Project:
+    root_path = Path(root).resolve()
+    if not root_path.is_dir():
+        raise ValueError(f"not a directory: {root_path}")
+
+    project = Project(source_language="python", root_path=str(root_path))
+    package_index: dict[str, Package] = {}
+
+    for py_file in sorted(root_path.rglob("*.py")):
+        if _should_skip(py_file):
+            continue
+        _parse_file(py_file, root_path, project, package_index)
+
+    return project
+
+
+_SKIP_DIR_NAMES = {"__pycache__", ".venv", "venv", ".tox", "build", "dist", ".git"}
+
+
+def _should_skip(p: Path) -> bool:
+    return any(part in _SKIP_DIR_NAMES for part in p.parts)
+
+
+def _parse_file(
+    file: Path,
+    root: Path,
+    project: Project,
+    package_index: dict[str, Package],
+) -> None:
+    rel = file.relative_to(root)
+    package_qn = _qualified_package_name(rel)
+    pkg = _ensure_package(project, package_qn, package_index)
+
+    source = file.read_text(encoding="utf-8", errors="replace")
+    try:
+        tree = ast.parse(source, filename=str(file))
+    except SyntaxError:
+        return
+
+    file_str = str(rel.as_posix())
+    import_map = build_import_map(tree)
+
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            cls = _class_from_node(node, package_qn, file_str, import_map)
+            pkg.classes.append(cls)
+
+    tags = find_tags(source, comment_prefix="#")
+    for tag in tags:
+        if tag.kind == "uml-activity" and not tag.self_closed:
+            act = build_activity_from_tag(tag, tree, source, file=file_str)
+            if act is not None:
+                project.activities.append(act)
+        elif tag.kind == "uml-sequence" and not tag.self_closed:
+            seq = build_sequence_from_tag(tag, tree, source, file=file_str)
+            if seq is not None:
+                project.sequences.append(seq)
+
+
+def _qualified_package_name(rel_file: Path) -> str:
+    parts = list(rel_file.parts[:-1])  # drop the file itself
+    if not parts:
+        return "__root__"
+    return ".".join(parts)
+
+
+def _ensure_package(
+    project: Project, qualified_name: str, index: dict[str, Package]
+) -> Package:
+    if qualified_name in index:
+        return index[qualified_name]
+
+    if qualified_name == "__root__":
+        pkg = Package(name="__root__", qualified_name="__root__")
+        project.packages.append(pkg)
+        index[qualified_name] = pkg
+        return pkg
+
+    parts = qualified_name.split(".")
+    parent_qn = ".".join(parts[:-1]) if len(parts) > 1 else None
+    if parent_qn is None:
+        pkg = Package(name=parts[0], qualified_name=qualified_name)
+        project.packages.append(pkg)
+    else:
+        parent = _ensure_package(project, parent_qn, index)
+        pkg = Package(name=parts[-1], qualified_name=qualified_name)
+        parent.sub_packages.append(pkg)
+    index[qualified_name] = pkg
+    return pkg
+
+
+# ---------- class / member extraction ----------
+
+def _class_from_node(
+    node: ast.ClassDef, package_qn: str, file: str, import_map: ImportMap
+) -> Class:
+    qn = f"{package_qn}.{node.name}" if package_qn and package_qn != "__root__" else node.name
+    cls = Class(
+        name=node.name,
+        qualified_name=qn,
+        kind=_class_kind(node),
+        bases=[_unparse(b) for b in node.bases],
+        location=SourceLocation(
+            file=file,
+            start_line=getattr(node, "lineno", 0),
+            end_line=getattr(node, "end_lineno", 0) or getattr(node, "lineno", 0),
+        ),
+        description=ast.get_docstring(node, clean=True) or None,
+        rules=extract_rules(node.decorator_list, import_map),
+    )
+
+    for body_node in node.body:
+        if isinstance(body_node, ast.AnnAssign) and isinstance(body_node.target, ast.Name):
+            cls.attributes.append(
+                Attribute(
+                    name=body_node.target.id,
+                    type=_unparse(body_node.annotation) if body_node.annotation else "",
+                    visibility=_visibility(body_node.target.id),
+                    is_static=True,
+                    default=_unparse(body_node.value) if body_node.value else None,
+                )
+            )
+        elif isinstance(body_node, ast.Assign):
+            for tgt in body_node.targets:
+                if isinstance(tgt, ast.Name):
+                    cls.attributes.append(
+                        Attribute(
+                            name=tgt.id,
+                            type="",
+                            visibility=_visibility(tgt.id),
+                            is_static=True,
+                            default=_unparse(body_node.value) if body_node.value else None,
+                        )
+                    )
+        elif isinstance(body_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            cls.operations.append(_operation_from_func(body_node, import_map))
+            cls.dependencies.extend(_body_type_refs(body_node))
+            if body_node.name == "__init__":
+                for attr in _instance_attributes_from_init(body_node):
+                    if not any(a.name == attr.name for a in cls.attributes):
+                        cls.attributes.append(attr)
+
+    cls.dependencies = _dedupe_refs(cls.dependencies, drop=node.name)
+    return cls
+
+
+def _class_kind(node: ast.ClassDef) -> str:
+    for base in node.bases:
+        base_name = _unparse(base)
+        if base_name in {"ABC", "abc.ABC"}:
+            return "abstract"
+        if base_name in {"Enum", "IntEnum", "enum.Enum", "enum.IntEnum"}:
+            return "enum"
+        if base_name in {"Protocol", "typing.Protocol"}:
+            return "interface"
+    for kw in node.keywords:
+        if kw.arg == "metaclass" and _unparse(kw.value) in {"ABCMeta", "abc.ABCMeta"}:
+            return "abstract"
+    return "class"
+
+
+def _operation_from_func(
+    node: ast.FunctionDef | ast.AsyncFunctionDef, import_map: ImportMap
+) -> Operation:
+    params: list[Parameter] = []
+    args = node.args
+    pos = list(args.posonlyargs) + list(args.args)
+    defaults = list(args.defaults)
+    default_offset = len(pos) - len(defaults)
+    for i, arg in enumerate(pos):
+        if arg.arg == "self":
+            continue
+        default = (
+            _unparse(defaults[i - default_offset]) if i >= default_offset else None
+        )
+        params.append(
+            Parameter(
+                name=arg.arg,
+                type=_unparse(arg.annotation) if arg.annotation else "",
+                default=default,
+            )
+        )
+    for arg, default in zip(args.kwonlyargs, args.kw_defaults):
+        params.append(
+            Parameter(
+                name=arg.arg,
+                type=_unparse(arg.annotation) if arg.annotation else "",
+                default=_unparse(default) if default else None,
+            )
+        )
+
+    is_static = any(_is_decorator(d, "staticmethod") for d in node.decorator_list)
+    is_abstract = any(
+        _is_decorator(d, "abstractmethod") or _is_decorator(d, "abc.abstractmethod")
+        for d in node.decorator_list
+    )
+
+    return Operation(
+        name=node.name,
+        parameters=params,
+        return_type=_unparse(node.returns) if node.returns else "",
+        visibility=_visibility(node.name),
+        is_static=is_static,
+        is_abstract=is_abstract,
+        description=ast.get_docstring(node, clean=True) or None,
+        rules=extract_rules(node.decorator_list, import_map),
+    )
+
+
+def _instance_attributes_from_init(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[Attribute]:
+    out: list[Attribute] = []
+    for stmt in ast.walk(node):
+        if isinstance(stmt, ast.AnnAssign) and _is_self_attr(stmt.target):
+            assert isinstance(stmt.target, ast.Attribute)
+            out.append(
+                Attribute(
+                    name=stmt.target.attr,
+                    type=_unparse(stmt.annotation) if stmt.annotation else "",
+                    visibility=_visibility(stmt.target.attr),
+                )
+            )
+        elif isinstance(stmt, ast.Assign):
+            for tgt in stmt.targets:
+                if _is_self_attr(tgt):
+                    assert isinstance(tgt, ast.Attribute)
+                    out.append(
+                        Attribute(
+                            name=tgt.attr,
+                            type="",
+                            visibility=_visibility(tgt.attr),
+                        )
+                    )
+    return out
+
+
+def _is_self_attr(node: ast.AST) -> bool:
+    return (
+        isinstance(node, ast.Attribute)
+        and isinstance(node.value, ast.Name)
+        and node.value.id == "self"
+    )
+
+
+def _is_decorator(dec: ast.expr, name: str) -> bool:
+    return _unparse(dec) == name
+
+
+def _visibility(name: str) -> Visibility:
+    if name.startswith("__") and not name.endswith("__"):
+        return Visibility.PRIVATE
+    if name.startswith("_"):
+        return Visibility.PROTECTED
+    return Visibility.PUBLIC
+
+
+def _unparse(node: ast.AST | None) -> str:
+    if node is None:
+        return ""
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""
+
+
+_PASCAL_IDENT_RE = re.compile(r"^[A-Z][A-Za-z0-9_]*$")
+
+
+def _body_type_refs(node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[str]:
+    """Collect PascalCase names referenced inside a function body.
+
+    Mirrors the C# parser heuristic: a PascalCase `Name` (a constructor call
+    `Foo()`, a static-call receiver `Foo.bar()`, a local annotation, etc.) is a
+    candidate type reference. `resolve_association` later keeps only those that
+    map to a project class.
+    """
+    out: list[str] = []
+    seen: set[str] = set()
+    for n in ast.walk(node):
+        if isinstance(n, ast.Name) and n.id not in seen and _PASCAL_IDENT_RE.match(n.id):
+            seen.add(n.id)
+            out.append(n.id)
+    return out
+
+
+def _dedupe_refs(refs: list[str], *, drop: str = "") -> list[str]:
+    """Order-preserving dedupe, dropping a given name (the owning class)."""
+    out: list[str] = []
+    seen: set[str] = set()
+    for r in refs:
+        if r == drop or r in seen:
+            continue
+        seen.add(r)
+        out.append(r)
+    return out

code_constraints/python/rules_extract.py

@@ -0,0 +1,83 @@
+"""Recognise architectural-rule decorators on Python classes/functions.
+
+Shared by the UML parser (to attach `RuleAnnotation`s to the model) and the
+`cdec enforce` conformance analyzer (to find tagged elements). A decorator counts
+as a rule only when its base name was imported from one of the shim modules
+(`cdec_rules` / `code_constraints.rules`) — so a user's own decorator that happens to
+share a name is never misread as a rule.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+from code_constraints.core.model import RuleAnnotation
+from code_constraints.core.rules import PYTHON_SHIM_MODULES, by_python_name
+
+
+@dataclass
+class ImportMap:
+    # local name -> exported shim name, for `from <shim> import x [as y]`
+    from_imports: dict[str, str] = field(default_factory=dict)
+    # local module alias -> real shim module dotted name
+    module_aliases: dict[str, str] = field(default_factory=dict)
+
+
+def build_import_map(tree: ast.AST) -> ImportMap:
+    im = ImportMap(module_aliases={m: m for m in PYTHON_SHIM_MODULES})
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            mod = node.module or ""
+            if mod in PYTHON_SHIM_MODULES:
+                for alias in node.names:
+                    im.from_imports[alias.asname or alias.name] = alias.name
+            elif mod == "code_constraints":
+                for alias in node.names:
+                    if alias.name == "rules":
+                        im.module_aliases[alias.asname or "rules"] = "code_constraints.rules"
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name in PYTHON_SHIM_MODULES and alias.asname:
+                    im.module_aliases[alias.asname] = alias.name
+    return im
+
+
+def extract_rules(decorator_list: list[ast.expr], import_map: ImportMap) -> list[RuleAnnotation]:
+    rules: list[RuleAnnotation] = []
+    for dec in decorator_list:
+        callee = dec.func if isinstance(dec, ast.Call) else dec
+        spec_id = _resolve(callee, import_map)
+        if spec_id is None:
+            continue
+        args: list[str] = []
+        kwargs: dict[str, str] = {}
+        if isinstance(dec, ast.Call):
+            args = [_unparse(a) for a in dec.args]
+            for kw in dec.keywords:
+                if kw.arg is not None:
+                    kwargs[kw.arg] = _unparse(kw.value)
+        rules.append(RuleAnnotation(name=spec_id, args=args, kwargs=kwargs))
+    return rules
+
+
+def _resolve(callee: ast.expr, im: ImportMap) -> str | None:
+    text = _unparse(callee)
+    if not text:
+        return None
+    if "." not in text:
+        exported = im.from_imports.get(text)
+        spec = by_python_name(exported) if exported else None
+    else:
+        prefix, _, final = text.rpartition(".")
+        spec = by_python_name(final) if prefix in im.module_aliases else None
+    return spec.id if spec else None
+
+
+def _unparse(node: ast.AST | None) -> str:
+    if node is None:
+        return ""
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""