code-constraints 0.1.0__py3-none-any.whl

code_constraints/cli/update.py

@@ -0,0 +1,157 @@
+"""`cdec update` — self-update the installation in place.
+
+Equivalent to re-running the standalone installer (`install/install.{sh,ps1}`):
+pull the latest code from GitHub, re-sync Python dependencies (picking up any
+requirement changes), and rebuild the web frontend. Operates on the git checkout
+that this CLI is running from, using the same virtualenv (`sys.executable`).
+
+The refreshed code takes effect on the next `cdec` invocation — the currently
+running process keeps the modules it already imported.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from code_constraints.cli import depstamp
+
+
+class UpdateError(Exception):
+    """Raised when the update cannot proceed (not a checkout, missing tool, …)."""
+
+
+def find_repo_root(start: Path | None = None) -> Path:
+    """Walk up from this module to the git checkout that contains the project.
+
+    Looks for a directory holding both ``.git`` and ``pyproject.toml`` — that's
+    the editable checkout the installer manages (``$CDEC_HOME/repo``) or a
+    developer clone.
+    """
+    here = (start or Path(__file__)).resolve()
+    for candidate in here.parents:
+        if (candidate / ".git").exists() and (candidate / "pyproject.toml").is_file():
+            return candidate
+    raise UpdateError(
+        "could not locate the code-constraints git checkout to update.\n"
+        "This command updates an installation created by the standalone installer "
+        "(or a git clone). If you installed code-constraints some other way, update it "
+        "the same way you installed it (e.g. `pip install -U code-constraints`)."
+    )
+
+
+def _current_branch(repo_root: Path, git: str) -> str:
+    out = subprocess.run(
+        [git, "-C", str(repo_root), "rev-parse", "--abbrev-ref", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return out.stdout.strip()
+
+
+def _run(cmd: list[str], *, cwd: Path, step: str) -> None:
+    """Run a child process, streaming its output. Raise UpdateError on failure."""
+    result = subprocess.run(cmd, cwd=str(cwd), check=False)
+    if result.returncode != 0:
+        raise UpdateError(f"{step} failed (exit {result.returncode}): {' '.join(cmd)}")
+
+
+def _build_inputs(frontend_dir: Path) -> list[Path]:
+    """Files whose change should trigger a frontend rebuild (source + configs)."""
+    candidates = [
+        frontend_dir / "src",
+        frontend_dir / "package.json",
+        frontend_dir / "package-lock.json",
+        frontend_dir / "vite.config.ts",
+        frontend_dir / "svelte.config.js",
+        frontend_dir / "tsconfig.json",
+        frontend_dir / "tsconfig.app.json",
+        frontend_dir / "tsconfig.node.json",
+        frontend_dir / "index.html",
+    ]
+    return [p for p in candidates if p.exists()]
+
+
+def run_update(
+    *,
+    branch: str | None = None,
+    frontend: bool = True,
+    force: bool = False,
+    echo=print,
+) -> Path:
+    """Perform the in-place update. Returns the repo root that was updated.
+
+    Mirrors the installer flow: ``git fetch`` + ``pull --ff-only`` → ``pip
+    install -e ".[dev]"`` (via the running interpreter) → ``npm install`` +
+    ``npm run build``.
+
+    The three install steps are fingerprinted (see :mod:`code_constraints.cli.depstamp`): a
+    step is skipped when its inputs are unchanged since the last successful run,
+    unless ``force`` is set. The git pull always runs — it's cheap and it's what
+    produces the changes the fingerprints then detect.
+    """
+    repo_root = find_repo_root()
+
+    git = shutil.which("git")
+    if git is None:
+        raise UpdateError("git is not installed or not on PATH.")
+
+    target_branch = branch or _current_branch(repo_root, git)
+
+    # 1. Pull latest code.
+    echo(f"==> Updating source ({target_branch}) in {repo_root}")
+    _run([git, "-C", str(repo_root), "fetch", "--prune", "origin", target_branch],
+         cwd=repo_root, step="git fetch")
+    _run([git, "-C", str(repo_root), "checkout", target_branch],
+         cwd=repo_root, step="git checkout")
+    _run([git, "-C", str(repo_root), "pull", "--ff-only", "origin", target_branch],
+         cwd=repo_root, step="git pull")
+
+    # 2. Re-sync Python dependencies using the venv this CLI runs from. Skip when
+    #    pyproject.toml is unchanged — the editable install already reflects any
+    #    source edits, so only a dependency change warrants a reinstall.
+    venv_dir = Path(sys.executable).resolve().parent.parent
+    py_stamp = venv_dir / ".cdec-stamp-python"
+    py_inputs = [repo_root / "pyproject.toml"]
+    if force or depstamp.is_changed(py_stamp, py_inputs, base=repo_root):
+        echo("==> Installing / updating Python dependencies")
+        _run([sys.executable, "-m", "pip", "install", "--upgrade", "pip"],
+             cwd=repo_root, step="pip upgrade")
+        _run([sys.executable, "-m", "pip", "install", "-e", ".[dev]"],
+             cwd=repo_root, step="pip install")
+        depstamp.write_stamp(py_stamp, py_inputs, base=repo_root)
+    else:
+        echo("==> Python dependencies unchanged — skipping pip install")
+
+    # 3. Rebuild the frontend.
+    if frontend:
+        frontend_dir = repo_root / "frontend"
+        npm = shutil.which("npm")
+        if npm is None:
+            echo("WARNING: npm not found on PATH — skipping frontend rebuild. "
+                 "The web UI may be stale until you build it (Node 20+ required).")
+        elif not frontend_dir.is_dir():
+            echo(f"WARNING: {frontend_dir} not found — skipping frontend rebuild.")
+        else:
+            deps_stamp = frontend_dir / "node_modules" / ".cdec-stamp-deps"
+            deps_inputs = [frontend_dir / "package.json", frontend_dir / "package-lock.json"]
+            if force or depstamp.is_changed(deps_stamp, deps_inputs, base=repo_root):
+                echo("==> Installing frontend dependencies")
+                _run([npm, "install"], cwd=frontend_dir, step="npm install")
+                depstamp.write_stamp(deps_stamp, deps_inputs, base=repo_root)
+            else:
+                echo("==> Frontend dependencies unchanged — skipping npm install")
+
+            build_stamp = frontend_dir / "dist" / ".cdec-stamp-build"
+            build_inputs = _build_inputs(frontend_dir)
+            if force or depstamp.is_changed(build_stamp, build_inputs, base=repo_root):
+                echo("==> Rebuilding the web UI")
+                _run([npm, "run", "build"], cwd=frontend_dir, step="npm run build")
+                depstamp.write_stamp(build_stamp, build_inputs, base=repo_root)
+            else:
+                echo("==> Frontend sources unchanged — skipping npm run build")
+
+    return repo_root

code_constraints/core/__init__.py

@@ -0,0 +1,41 @@
+from code_constraints.core.model import (
+    Project,
+    Package,
+    Class,
+    Attribute,
+    Operation,
+    Parameter,
+    Activity,
+    ActivityNode,
+    ActivityEdge,
+    Sequence,
+    Lifeline,
+    Message,
+    SourceLocation,
+    Layout,
+    EdgeLayout,
+    DiffStatus,
+    Visibility,
+    ClassKind,
+)
+
+__all__ = [
+    "Project",
+    "Package",
+    "Class",
+    "Attribute",
+    "Operation",
+    "Parameter",
+    "Activity",
+    "ActivityNode",
+    "ActivityEdge",
+    "Sequence",
+    "Lifeline",
+    "Message",
+    "SourceLocation",
+    "Layout",
+    "EdgeLayout",
+    "DiffStatus",
+    "Visibility",
+    "ClassKind",
+]

code_constraints/core/annotations.py

@@ -0,0 +1,217 @@
+"""Parse `@cdec` annotation comments into `RuleAnnotation`s.
+
+The tag carrier for languages with no user-extensible decorator or attribute
+syntax — currently Lua and Odin (see the `ANNOTATION_MARKER` note in
+`code_constraints.core.rules` for why neither can use a no-op shim declaration).
+A tag is a namespaced comment sitting directly above the declaration:
+
+    ---@cdec sealed                              (Lua)
+    ---@cdec locked(reason = "agreed", owner = "ann")
+    //@cdec layer("domain")                      (Odin)
+    //@cdec no_instantiation(allow = ["Builder"])
+
+Shared by `code_constraints.{lua,odin}.rules_extract` so "what counts as a rule"
+stays identical across the two, exactly as `rules_extract` is shared between each
+language's UML parser and its enforce/lock analyzers.
+
+Like `core.tags`, the parser is deliberately forgiving: an unparseable annotation
+is skipped rather than raising, so a typo never fails a whole parse.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import TYPE_CHECKING
+
+from code_constraints.core.model import RuleAnnotation
+from code_constraints.core.rules import ANNOTATION_MARKER, by_annotation_name
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+# `@cdec <name>` optionally followed by an argument list. Leading comment
+# punctuation (`--`, `//`, `-`, whitespace) is skipped by searching for the
+# marker rather than anchoring at the line start.
+_ANNOTATION_RE = re.compile(
+    re.escape(ANNOTATION_MARKER) + r"\s+([A-Za-z_][A-Za-z0-9_]*)\s*(\(.*)?$",
+    re.DOTALL,
+)
+
+
+def parse_annotation(text: str) -> RuleAnnotation | None:
+    """Parse one comment's text into a `RuleAnnotation`, or None if it isn't a
+    recognised `@cdec` tag."""
+    idx = text.find(ANNOTATION_MARKER)
+    if idx < 0:
+        return None
+    match = _ANNOTATION_RE.search(text, idx)
+    if match is None:
+        return None
+    spec = by_annotation_name(match.group(1))
+    if spec is None:
+        return None
+    args, kwargs = _parse_args(match.group(2) or "")
+    return RuleAnnotation(name=spec.id, args=args, kwargs=kwargs)
+
+
+def rules_from_comments(texts: list[str]) -> list[RuleAnnotation]:
+    """Parse a run of comment texts (outermost first) into rule annotations,
+    skipping every line that isn't a `@cdec` tag."""
+    out: list[RuleAnnotation] = []
+    for text in texts:
+        rule = parse_annotation(text)
+        if rule is not None:
+            out.append(rule)
+    return out
+
+
+def literal_set(source_text: str) -> set[str]:
+    """Parse a rule argument holding a list of names into a set of strings.
+
+    Handles every shape the languages here produce for `allow=` / `creates=`,
+    because each is also a Python literal: `["Money"]` (Odin, Julia, C#),
+    `{"Money"}` (Lua table), `['Money']` (Python). Tolerant by design — an
+    unparseable value yields an empty set rather than failing the run, matching
+    `python.conformance._str_list`.
+    """
+    if not source_text:
+        return set()
+    try:
+        value = ast.literal_eval(source_text.strip())
+    except (ValueError, SyntaxError):
+        return set()
+    if isinstance(value, (list, tuple, set)):
+        return {str(v) for v in value}
+    return {str(value)}
+
+
+def rules_before_node(node: "Node", source: bytes) -> list[RuleAnnotation]:
+    """Collect `@cdec` tags from the comment block directly above `node`.
+
+    Walks previous siblings while they are `comment` nodes on consecutive lines,
+    so the block reads like a stack of decorators. Line adjacency is required:
+    a comment separated from the declaration by a blank line is prose, not a tag
+    (tree-sitter emits no node for blank lines, so sibling order alone can't tell
+    the two apart).
+    """
+    texts: list[str] = []
+    expected_line = node.start_point[0] - 1
+    current = node.prev_sibling
+    while current is not None and current.type == "comment":
+        if current.end_point[0] != expected_line:
+            break
+        texts.append(source[current.start_byte : current.end_byte].decode("utf-8", "replace"))
+        expected_line = current.start_point[0] - 1
+        current = current.prev_sibling
+    # Walked bottom-up; restore source order so stacked tags keep their order.
+    texts.reverse()
+    return rules_from_comments(texts)
+
+
+def _parse_args(raw: str) -> tuple[list[str], dict[str, str]]:
+    """Split `(a, b = c)` into positional and keyword argument *source text*.
+
+    Values are kept verbatim (quotes and brackets included) to match the
+    `RuleAnnotation` contract used by the Python and C# extractors, so consumers
+    like `conformance._str_list` and `layer_dependencies._layer_of` read them the
+    same way regardless of source language.
+    """
+    args: list[str] = []
+    kwargs: dict[str, str] = {}
+    inner = _balanced_inner(raw)
+    if not inner.strip():
+        return args, kwargs
+
+    for part in _split_top_level(inner):
+        part = part.strip()
+        if not part:
+            continue
+        name, sep, value = _split_keyword(part)
+        if sep:
+            kwargs[name] = value.strip()
+        else:
+            args.append(part)
+    return args, kwargs
+
+
+def _balanced_inner(raw: str) -> str:
+    """Return the contents of the leading balanced `(...)` group in `raw`.
+
+    Stops at the matching close paren so a trailing comment after the annotation
+    (`---@cdec layer("domain")  -- the core`) doesn't leak into the arguments.
+    """
+    raw = raw.lstrip()
+    if not raw.startswith("("):
+        return ""
+    depth = 0
+    quote: str | None = None
+    for i, ch in enumerate(raw):
+        if quote is not None:
+            if ch == quote and raw[i - 1 : i] != "\\":
+                quote = None
+            continue
+        if ch in "\"'":
+            quote = ch
+        elif ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+            if depth == 0:
+                return raw[1:i]
+    # Unbalanced: take everything after the opening paren rather than dropping
+    # the tag entirely.
+    return raw[1:]
+
+
+def _split_top_level(inner: str) -> list[str]:
+    """Split on commas that are not nested inside brackets or quotes."""
+    parts: list[str] = []
+    depth = 0
+    quote: str | None = None
+    start = 0
+    for i, ch in enumerate(inner):
+        if quote is not None:
+            if ch == quote and inner[i - 1 : i] != "\\":
+                quote = None
+            continue
+        if ch in "\"'":
+            quote = ch
+        elif ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            parts.append(inner[start:i])
+            start = i + 1
+    parts.append(inner[start:])
+    return parts
+
+
+def _split_keyword(part: str) -> tuple[str, bool, str]:
+    """Split `name = value` at the first top-level `=`.
+
+    Returns `(name, is_keyword, value)`. Comparison operators (`==`, `!=`, `<=`,
+    `>=`) are not keyword separators.
+    """
+    depth = 0
+    quote: str | None = None
+    for i, ch in enumerate(part):
+        if quote is not None:
+            if ch == quote and part[i - 1 : i] != "\\":
+                quote = None
+            continue
+        if ch in "\"'":
+            quote = ch
+        elif ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        elif ch == "=" and depth == 0:
+            if part[i + 1 : i + 2] == "=" or part[i - 1 : i] in ("!", "<", ">", "="):
+                continue
+            name = part[:i].strip()
+            if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
+                return name, True, part[i + 1 :]
+            return "", False, part
+    return "", False, part

code_constraints/core/associations.py

@@ -0,0 +1,134 @@
+"""Resolve a typed attribute to a project class for association edges.
+
+Shared by every graph builder in `graph_model.py` so the class and package
+canvases apply the same wrapper-stripping and lookup rules.
+"""
+
+from __future__ import annotations
+
+from code_constraints.core.model import Project
+
+# Common .NET / Python collection wrappers whose inner type is the real
+# association target. Order does not matter — these are matched by exact head.
+COLLECTION_WRAPPERS = (
+    "List", "IList", "IReadOnlyList", "ICollection", "IReadOnlyCollection",
+    "IEnumerable", "HashSet", "ISet", "Queue", "Stack",
+    "ObservableCollection", "ConcurrentBag", "ConcurrentQueue",
+    "list", "set", "tuple", "frozenset", "Iterable", "Sequence", "Collection",
+)
+
+_DICTIONARY_HEADS = (
+    "Dictionary", "IDictionary", "IReadOnlyDictionary", "dict", "Map", "Mapping",
+)
+
+# Single-arg unwrap heads (Python typing). `Optional[T]` collapses to T.
+_OPTIONAL_HEADS = ("Optional",)
+
+
+def build_class_index(project: Project) -> dict[str, str]:
+    """Map both qualified and (when unambiguous) short class names → qualified name.
+
+    Cached on the Project instance so repeated callers share the work.
+    """
+    cached: dict[str, str] | None = getattr(project, "_assoc_index", None)
+    if cached is not None:
+        return cached
+
+    index: dict[str, str] = {}
+    short_counts: dict[str, int] = {}
+    for cls in project.iter_classes():
+        index[cls.qualified_name] = cls.qualified_name
+        short_counts[cls.name] = short_counts.get(cls.name, 0) + 1
+    for cls in project.iter_classes():
+        if short_counts[cls.name] == 1:
+            index.setdefault(cls.name, cls.qualified_name)
+
+    object.__setattr__(project, "_assoc_index", index)
+    return index
+
+
+def resolve_association(raw_type: str, project: Project) -> tuple[str | None, str]:
+    """Return (target qualified name, multiplicity) for an attribute type, or
+    (None, "") if it doesn't reference a project class.
+
+    Multiplicity is "*" for arrays / collections / dictionaries and "" otherwise.
+    """
+    if not raw_type:
+        return None, ""
+
+    candidate = raw_type.strip()
+    multiplicity = ""
+
+    if candidate.endswith("?"):
+        candidate = candidate[:-1].strip()
+
+    while candidate.endswith("[]") or candidate.endswith("[,]"):
+        candidate = candidate.rsplit("[", 1)[0].strip()
+        multiplicity = "*"
+
+    if "<" in candidate and candidate.endswith(">"):
+        head, _, rest = candidate.partition("<")
+        inner = rest[:-1]
+        head = head.strip()
+        if head in COLLECTION_WRAPPERS or head.split(".")[-1] in COLLECTION_WRAPPERS:
+            multiplicity = "*"
+            candidate = _split_generic_args(inner)[0].strip()
+        elif head in _DICTIONARY_HEADS:
+            multiplicity = "*"
+            args = _split_generic_args(inner)
+            candidate = args[-1].strip() if args else ""
+        else:
+            candidate = head
+
+    # Python 3.9+ subscript generics: `list[T]`, `dict[K,V]`, `Optional[T]`.
+    # Mirrors the `<>` block above but with `[]` brackets.
+    elif "[" in candidate and candidate.endswith("]"):
+        head, _, rest = candidate.partition("[")
+        inner = rest[:-1]
+        head = head.strip()
+        if head in COLLECTION_WRAPPERS or head.split(".")[-1] in COLLECTION_WRAPPERS:
+            multiplicity = "*"
+            candidate = _split_generic_args(inner)[0].strip()
+        elif head in _DICTIONARY_HEADS:
+            multiplicity = "*"
+            args = _split_generic_args(inner)
+            candidate = args[-1].strip() if args else ""
+        elif head in _OPTIONAL_HEADS:
+            # Optional[T] is just T with allow-None semantics — keep
+            # multiplicity unchanged ("" by default).
+            args = _split_generic_args(inner)
+            candidate = args[0].strip() if args else ""
+        else:
+            candidate = head
+
+    candidate = candidate.split(".")[-1] if candidate else candidate
+    if not candidate:
+        return None, ""
+
+    index = build_class_index(project)
+    target = index.get(candidate) or index.get(raw_type)
+    if target is None:
+        return None, ""
+    return target, multiplicity
+
+
+def _split_generic_args(inner: str) -> list[str]:
+    """Split a comma-separated generic-arg list, respecting nested <> and []."""
+    out: list[str] = []
+    depth = 0
+    current: list[str] = []
+    for ch in inner:
+        if ch in ("<", "["):
+            depth += 1
+            current.append(ch)
+        elif ch in (">", "]"):
+            depth -= 1
+            current.append(ch)
+        elif ch == "," and depth == 0:
+            out.append("".join(current))
+            current = []
+        else:
+            current.append(ch)
+    if current:
+        out.append("".join(current))
+    return out