code-constraints 0.1.0__py3-none-any.whl

code_constraints/cli/_assets/shims/odin/cdec_rules.odin

@@ -0,0 +1,67 @@
+/*
+No-op architectural-rule tags for code-constraints (Odin).
+
+Odin's `@(...)` attributes are a closed set — the compiler rejects any attribute
+it does not know ("unknown attribute"), so a no-op `@(cdec_sealed)` would fail to
+build. Tags are therefore written as namespaced annotation comments placed
+directly above the declaration, in the slot an attribute would occupy. The
+`@cdec` prefix is the namespace, so an unrelated comment can never false-match.
+
+	//@cdec sealed
+	//@cdec layer("domain")
+	Invoice :: struct {
+		id:    string,
+		total: f64,
+	}
+
+	//@cdec no_instantiation(allow = ["Builder"])
+	summarise :: proc(inv: ^Invoice) -> string { ... }
+
+	//@cdec locked(reason = "agreed settlement sequence")
+	settle :: proc(inv: ^Invoice) -> f64 { ... }
+
+Annotation arguments use call syntax: positional (`layer("domain")`) or named
+with `=` (`locked(reason = "why", owner = "ann")`). Lists use brackets:
+`no_instantiation(allow = ["Builder"])`. A bare tag needs no parentheses.
+
+Odin has no methods-inside-structs, so code-constraints models a procedure as an
+*operation of* a struct when its first parameter is that struct or a pointer to
+it (`proc(inv: ^Invoice, ...)`). Tag such a procedure to constrain that operation.
+
+Enforcement happens out-of-band via `cdec check` (drift), `cdec enforce`
+(implementation conformance) and `cdec lock` (implementation freeze). The
+annotations do nothing at compile time or runtime.
+
+This file additionally declares each tag as a no-op procedure, for code that
+prefers an explicit call to a comment, and as the canonical in-repo reference for
+the tag vocabulary. The parser reads the annotation comments, not these calls.
+*/
+package cdec_rules
+
+// Forbid constructing objects in the tagged struct's operations or procedure
+// body. Option: `allow` — type names that may still be constructed.
+no_instantiation :: proc(subject: rawptr = nil) {}
+
+// Declare the tagged procedure free of side effects. Body analysis is deferred;
+// the tag is still captured, visualised and frozen against removal.
+no_side_effects :: proc(subject: rawptr = nil) {}
+
+// Forbid embedding the tagged struct as a `using` base (no subtyping).
+sealed :: proc(subject: rawptr = nil) {}
+
+// Forbid reassigning the tagged struct's fields after construction.
+immutable :: proc(subject: rawptr = nil) {}
+
+// Mark the tagged struct/procedure as the designated constructor of the types in
+// `creates`; constructing those types elsewhere is forbidden.
+factory :: proc(subject: rawptr = nil) {}
+
+// Freeze the tagged implementation. `cdec lock set` records the element's
+// normalised AST digest in `.cdec/locks.yaml`; any later semantic change to the
+// body — or removal of the tag — fails `cdec lock check`. Reformatting, moving
+// the declaration, and editing comments do not trip the lock.
+// Options: `reason`, `owner`.
+locked :: proc(subject: rawptr = nil) {}
+
+// Assign the struct to an architectural layer for dependency-direction checks.
+layer :: proc(subject: rawptr = nil) {}

code_constraints/cli/_assets/shims/python/cdec_rules.py

@@ -0,0 +1,94 @@
+"""No-op architectural-rule decorators for code-constraints.
+
+Import these to tag classes and methods with architectural constraints. They do
+nothing at runtime — they exist so tagged code still imports/runs, and so the
+UML parser can recognise the tags (it only treats a decorator as a rule when its
+base name was imported from this module). Enforcement happens out-of-band via
+`cdec check` (drift) and `cdec enforce` (implementation conformance).
+
+    from cdec_rules import no_instantiation, factory, sealed, immutable, layer, locked
+
+    @sealed
+    @layer("domain")
+    class Order: ...
+
+    class OrderService:
+        @no_instantiation(allow=["list", "dict"])
+        def total(self): ...
+
+        @locked(reason="agreed settlement sequence")
+        def settle(self): ...
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+_T = TypeVar("_T")
+
+
+def _passthrough(obj: _T) -> _T:
+    return obj
+
+
+def _decorator_factory(*_args: Any, **_kwargs: Any) -> Callable[[_T], _T]:
+    return _passthrough
+
+
+def no_instantiation(*args: Any, **kwargs: Any):
+    """Forbid constructing objects in the tagged class/method body.
+
+    `allow` (list[str]): type names that may still be instantiated (e.g.
+    collections like "list", "dict")."""
+    # Support both bare `@no_instantiation` and `@no_instantiation(allow=[...])`.
+    if len(args) == 1 and not kwargs and callable(args[0]):
+        return args[0]
+    return _passthrough
+
+
+def no_side_effects(*args: Any, **kwargs: Any):
+    """Declare the tagged operation free of side effects."""
+    if len(args) == 1 and not kwargs and callable(args[0]):
+        return args[0]
+    return _passthrough
+
+
+def factory(*args: Any, **kwargs: Any):
+    """Mark the tagged class/method as the designated factory for the types in
+    `creates` (list[str]); constructing those types elsewhere is forbidden."""
+    if len(args) == 1 and not kwargs and callable(args[0]):
+        return args[0]
+    return _passthrough
+
+
+def layer(*args: Any, **kwargs: Any):
+    """Assign the class to an architectural layer, e.g. `@layer("domain")`."""
+    if len(args) == 1 and not kwargs and callable(args[0]):
+        return args[0]
+    return _passthrough
+
+
+def locked(*args: Any, **kwargs: Any):
+    """Freeze the tagged class/function implementation.
+
+    The element's normalised AST is digested and recorded in `.cdec/locks.yaml`
+    by `cdec lock set`. Any later semantic change to the body — or removal of
+    this tag — fails `cdec lock check` (and `cdec check`, which runs it). Moving
+    the element around the file, reformatting it, or editing comments does not
+    trip the lock: the digest is computed from the AST, not the source text.
+
+    Optional metadata: `reason` (why it's frozen) and `owner` (who to ask).
+    Both are recorded in the lockfile and echoed in violation messages."""
+    if len(args) == 1 and not kwargs and callable(args[0]):
+        return args[0]
+    return _passthrough
+
+
+def sealed(obj: _T) -> _T:
+    """Forbid subclassing the tagged class."""
+    return obj
+
+
+def immutable(obj: _T) -> _T:
+    """Forbid reassigning the tagged class's fields after construction."""
+    return obj

code_constraints/cli/_assets/skills/cdec-architecture-loop/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: cdec-architecture-loop
+description: Discuss and iterate architectural decisions with code-constraints — author a JSON model of the target architecture, show it in the browser diffed against the code with `cdec propose`, refine it through conversation (the open tab refreshes on every push), then lock it with `cdec reference set` to constrain development, and accept deliberate exceptions afterwards with `cdec exceptions allow`. Use whenever the user wants to plan, review, restructure, or agree on class/package architecture, discuss a refactor's target shape, compare a design against the current code, update the reference architecture, or decide what to do when `cdec check` / the `tag-conformance` rule blocks a change they want to keep.
+---
+
+# UML architecture discussion loop
+
+You are driving an interactive architecture review with the **code-constraints** tool. The
+human looks at a live diagram in their browser; you edit a JSON model file and push
+updates. Never paste raw XMI (or the whole JSON) into the chat as the primary review
+medium — the diagram diff *is* the review medium; chat is for reasoning and decisions.
+
+## The loop
+
+```bash
+# 0. Nothing to start manually — `cdec propose` reuses a running `cdec serve`
+#    (port 8765) or boots one itself.
+
+# 1. Get an editable model (pick ONE starting point):
+cdec parse <src> --lang <lang> --out target.json        # start from the code as-is
+cdec convert .cdec/reference.xmi target.json             # start from the locked design
+
+# 2. Edit target.json to express the proposed architecture (see shape below).
+
+# 3. Push for review, pre-filtered to what's under discussion:
+cdec propose target.json --focus pkg.ClassA,pkg.ClassB
+#    green = code still needs to grow this; red = proposal removes this.
+#    --against reference   → diff vs the locked design instead of the code
+#    --against none        → render the proposal standalone (greenfield)
+#    --no-browser          → push without opening a tab (tab already open)
+
+# 4. Discuss → edit target.json → `cdec propose` again. The open tab refreshes
+#    in place (it polls; positions and filters survive). Repeat until agreed.
+
+# 5. Lock the agreed design (ONLY after explicit approval from the human):
+cdec reference set target.json                          # writes .cdec/reference.xmi
+
+# 6. Development is now constrained:
+cdec check        # exit 1 on structural deviation (CI gate)
+cdec check                 # drift rules (frozen tags, layers, forbidden refs)
+cdec check                        # every rule: drift, tags, locks, reference
+
+# 7. When a constraint blocks something the design intends to allow:
+cdec exceptions allow V-1A2B3C4D --reason "why this is acceptable"
+```
+
+If `cdec` is not on PATH, use `.venv/Scripts/python.exe -m code_constraints.cli <command>`.
+
+## When the constraints block a legitimate change
+
+A locked design that can only say *no* gets switched off. Step 7 is the release valve, and
+picking the right one is itself an architectural decision — say which you chose and why:
+
+| The blocked change is… | Do this |
+|---|---|
+| a deliberate change to the **architecture** | edit `target.json` → `cdec propose` → approval → `cdec reference set`. Back to the loop. |
+| a **known, acceptable exception** | `cdec exceptions allow <key> --reason "…"` — the rule keeps protecting everything else. |
+| evidence the **rule is wrong** | change it in `.cdec/rules.yaml`, and justify it. Rare, and never silent. |
+
+Every issue leads with a stable key — `V-` (check), `F-` (enforce), `L-` (lock):
+
+```
+- [V-DD3EA5B2] billing.LegacyGateway — billing/legacy.py:12: 'billing.LegacyGateway' is not allowed to reference 'ui.Panel'.
+```
+
+Keys hash *what* an issue is, never where it sits, so they survive reformatting and repeat
+run to run. For a batch: `cdec exceptions review --out review.txt`, mark lines `[ALLOW]` (or
+`[ALLOW: reason]`), then `cdec exceptions patch --file review.txt`. A `cdec check --log-out`
+file is patchable as-is. `cdec exceptions list` / `remove KEY` / `prune` manage what's been
+accepted.
+
+- **Always pass a reason.** The waiver is committed and read by a human.
+- **`L-` keys are not waivable.** `cdec exceptions allow` refuses them and prints
+  `cdec check --automatic-exceptions locks --target … --force` — a frozen implementation changes only on the human's
+  explicit say-so, never on your initiative.
+- Prefer a waiver over adding an `ignore:` glob or dropping a rule: one reviewable line
+  about one element, versus turning the rule off for everything it would have caught.
+
+## How to run the conversation
+
+- **One artifact**: keep a single `target.json` on disk and evolve it across the whole
+  discussion. Don't fork variants unless the human asks to compare alternatives.
+- **Small pushes, narrow focus**: push after each meaningful change and set `--focus`
+  to the 2–6 classes the current question is about, so the human isn't hunting
+  through the whole canvas. Change focus as the discussion moves.
+- **Narrate the delta, not the model**: after each push, say in one or two sentences
+  what changed since the last push and what you want the human to look at.
+- **Ask, don't lock**: `cdec reference set` is the commitment point — it changes what
+  every developer's `cdec check` / `cdec check` fails on. Run it only after the
+  human explicitly approves the *current* model (approval of an earlier iteration
+  doesn't carry over).
+- After locking, offer the enforcement follow-ups: rule tags (`@layer`, `@sealed`,
+  `@immutable`, `@factory`, `@no_instantiation` — Python/C# only) and `.cdec/rules.yaml`
+  lint rules (`forbidden-package-references`, `no-cyclic-package-dependencies`, … —
+  all languages). Every rule and tag, with options and pass/fail examples, is catalogued in
+  `docs/RULES_CATALOGUE.md`.
+- **Say how each new rule handles what already violates it.** Turning on a rule that fires
+  on twenty existing classes with no stated way through is how a team ends up deleting the
+  rule. Either fix them, waive them individually with reasons, or `cdec check
+  --automatic-exceptions rules` to grandfather the lot — but name the choice.
+
+## The JSON model shape
+
+Same document the web editor uses; snake_case; produce a valid skeleton with
+`cdec parse … --out x.json` and edit it rather than writing from scratch when possible.
+
+```json
+{
+  "source_language": "python",
+  "packages": [
+    {
+      "name": "billing",
+      "qualified_name": "billing",
+      "classes": [
+        {
+          "name": "Invoice",
+          "qualified_name": "billing.Invoice",
+          "kind": "class",
+          "attributes": [{ "name": "total", "type": "float" }],
+          "operations": [
+            { "name": "pay", "parameters": [], "return_type": "bool" }
+          ],
+          "bases": ["billing.Document"],
+          "description": "why this class exists"
+        }
+      ],
+      "sub_packages": []
+    }
+  ],
+  "associations": []
+}
+```
+
+Notes:
+- `kind` is one of `class|interface|abstract|enum|struct|record|static`; `bases` holds
+  qualified names and draws inheritance edges.
+- An attribute `type` naming a project class draws an association edge automatically
+  (collection wrappers like `list[X]` / `List<X>` are unwrapped).
+- Omitted optional fields default sensibly; unknown classes referenced in `bases`
+  render as external placeholder nodes.
+- `.json` and `.xmi` are interchangeable in every command; `cdec convert` translates.
+
+## Pitfalls
+
+- The viewer runs on **port 8765** (8000 is reserved by Windows http.sys on this machine).
+- Repeated `cdec propose` pushes for the same `(source path, lang)` hit the same
+  project, which is what makes the open tab refresh — don't vary `--source` between
+  iterations of one discussion.
+- Diff orientation: the proposal is the NEW side. If the human expects "what would I
+  have to delete", remind them red = present in code, absent from proposal.
+- For TypeScript/Svelte, rule *tags* don't exist — encode constraints as package-level
+  lint rules in `.cdec/rules.yaml` instead, and say so.

code_constraints/cli/depstamp.py

@@ -0,0 +1,118 @@
+"""Dependency fingerprinting for the install/update flows.
+
+Each heavy install step (pip install, npm install, npm run build) hashes the
+files that determine its output and stores that hash in a *stamp file*. On the
+next run the step is skipped when the freshly-computed hash matches the stamp —
+so re-running `cdec update`, the standalone installers, or `scripts/bootstrap.*`
+no longer reinstalls everything when nothing relevant has changed.
+
+This module is intentionally pure-stdlib so it can be used two ways:
+
+* imported by ``code_constraints.cli.update`` (``from code_constraints.cli import depstamp``), and
+* run by file path from the shell installers
+  (``python /path/to/depstamp.py check --stamp <file> <inputs...>``) — which
+  works even before the package is pip-installed, i.e. on a first install.
+
+A directory passed as an input is expanded to every file beneath it (sorted),
+so a source tree like ``frontend/src`` produces a stable, content-addressed
+hash that changes whenever any file under it is added, removed, or edited.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+# Bumped if the hashing scheme ever changes, to invalidate old stamps.
+_SCHEME = "cdec-depstamp-v1"
+
+
+def _iter_files(path: Path):
+    """Yield the files contributing to the fingerprint for ``path``.
+
+    A file yields itself; a directory yields every file beneath it (recursively).
+    Missing paths yield nothing — a manifest that doesn't exist simply doesn't
+    contribute, which keeps the hash defined even on a partial checkout.
+    """
+    if path.is_dir():
+        yield from (p for p in sorted(path.rglob("*")) if p.is_file())
+    elif path.is_file():
+        yield path
+
+
+def fingerprint(inputs: list[Path], *, base: Path | None = None) -> str:
+    """Return a SHA256 hex digest over the contents of ``inputs``.
+
+    The digest folds in each contributing file's path (relative to ``base`` when
+    given, so the hash is stable regardless of the absolute checkout location)
+    and its bytes. File order is normalised by sorting, so the result depends
+    only on the set of files and their contents.
+    """
+    h = hashlib.sha256()
+    h.update(_SCHEME.encode())
+
+    entries: list[tuple[str, Path]] = []
+    for raw in inputs:
+        for f in _iter_files(raw):
+            try:
+                rel = f.relative_to(base) if base else f
+            except ValueError:
+                rel = f
+            entries.append((rel.as_posix(), f))
+
+    for rel_str, f in sorted(entries, key=lambda e: e[0]):
+        h.update(rel_str.encode())
+        h.update(b"\0")
+        h.update(f.read_bytes())
+        h.update(b"\0")
+
+    return h.hexdigest()
+
+
+def is_changed(stamp: Path, inputs: list[Path], *, base: Path | None = None) -> bool:
+    """True if the step should run: stamp missing, unreadable, or hash differs."""
+    if not stamp.is_file():
+        return True
+    try:
+        previous = stamp.read_text(encoding="utf-8").strip()
+    except OSError:
+        return True
+    return previous != fingerprint(inputs, base=base)
+
+
+def write_stamp(stamp: Path, inputs: list[Path], *, base: Path | None = None) -> None:
+    """Record the current fingerprint of ``inputs`` into ``stamp``."""
+    stamp.parent.mkdir(parents=True, exist_ok=True)
+    stamp.write_text(fingerprint(inputs, base=base), encoding="utf-8")
+
+
+def _main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Dependency fingerprint stamps.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    for name in ("check", "write"):
+        p = sub.add_parser(name)
+        p.add_argument("--stamp", required=True, type=Path, help="Stamp file path.")
+        p.add_argument(
+            "--base",
+            type=Path,
+            default=None,
+            help="Base dir to relativise input paths against (for stable hashing).",
+        )
+        p.add_argument("inputs", nargs="+", type=Path, help="Files/dirs to fingerprint.")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "check":
+        # Exit 0 = changed (run the step); exit 1 = unchanged (skip). This maps
+        # onto shell `if` truthiness so callers can write `if python ... check`.
+        return 0 if is_changed(args.stamp, args.inputs, base=args.base) else 1
+
+    write_stamp(args.stamp, args.inputs, base=args.base)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(_main())

code_constraints/cli/detect.py

@@ -0,0 +1,77 @@
+"""Heuristic source-language detection for `cdec serve parse`.
+
+When the user doesn't pass `--lang`, we guess the project's language from the
+mix of file extensions in the tree. The rule (per spec):
+
+  1. ANY `.svelte` file present  -> "svelte"  (Svelte projects also carry .ts,
+     so .svelte wins over typescript).
+  2. otherwise the language with the most files among python/.py,
+     csharp/.cs, typescript/.ts|.tsx, odin/.odin, lua/.lua, julia/.jl.
+  3. nothing recognised           -> None (the caller asks for --lang).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+# Directories never worth walking for language detection.
+IGNORE_DIRS = frozenset(
+    {
+        ".git",
+        ".venv",
+        "venv",
+        "node_modules",
+        "dist",
+        "build",
+        ".svelte-kit",
+        "obj",
+        "bin",
+        "__pycache__",
+        ".cdec_cache",
+    }
+)
+
+# Extension -> language. `.svelte` is handled as an override, not via counting.
+EXT_TO_LANG = {
+    ".py": "python",
+    ".cs": "csharp",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".odin": "odin",
+    ".lua": "lua",
+    ".jl": "julia",
+}
+
+# Deterministic tie-break order when counts are equal.
+_PRIORITY = ("python", "csharp", "typescript", "odin", "lua", "julia")
+
+
+def detect_language(root: Path) -> Optional[str]:
+    """Return the detected language for the tree at `root`, or None."""
+    counts: dict[str, int] = {}
+    saw_svelte = False
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Prune ignored directories in place so os.walk doesn't descend.
+        dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS]
+        for name in filenames:
+            ext = os.path.splitext(name)[1].lower()
+            if ext == ".svelte":
+                saw_svelte = True
+                continue
+            lang = EXT_TO_LANG.get(ext)
+            if lang is not None:
+                counts[lang] = counts.get(lang, 0) + 1
+
+    if saw_svelte:
+        return "svelte"
+    if not counts:
+        return None
+    best = max(counts.values())
+    for lang in _PRIORITY:
+        if counts.get(lang, 0) == best:
+            return lang
+    # Fallback (shouldn't happen given _PRIORITY covers EXT_TO_LANG values).
+    return max(counts, key=lambda k: counts[k])