fux-engine 0.1.2__tar.gz → 0.2.0__tar.gz

{fux_engine-0.1.2/fux_engine.egg-info → fux_engine-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fux-engine
-Version: 0.1.2
+Version: 0.2.0
 Summary: Fux — a portable agent-aware knowledge engine: rules, memory, narrative, and graph in one frontmatter substrate.
 Author-email: arpit arya <arpitarya.me@gmail.com>
 License: MIT

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/__init__.py

@@ -3,4 +3,4 @@
 One frontmatter substrate → derived index, graph, and memory views.
 $0 deterministic maintenance; no mandatory LLM calls. See docs/fux-plan.md.
 """
-__version__ = "0.1.2"
+__version__ = "0.2.0"

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/cli.py

@@ -120,6 +120,25 @@ def build_parser() -> argparse.ArgumentParser:
     ex.add_argument("term")
     ex.set_defaults(fn=cligraph.cmd_explain)
 
+    imp2 = sub.add_parser("impact", help="downstream blast radius of changing a file ($0)")
+    imp2.add_argument("file")
+    imp2.set_defaults(fn=cligraph.cmd_impact)
+
+    cmp = sub.add_parser("components", help="design-system registry + data-binding catalog ($0)")
+    cmp.add_argument("--kind", choices=["all", "components", "hooks", "dtos"], default="all")
+    cmp.add_argument("--scope", help="restrict to files under this path prefix")
+    cmp.add_argument("--json", action="store_true", help="machine-readable output (for Orff)")
+    cmp.set_defaults(fn=cligraph.cmd_components)
+
+    vs = sub.add_parser("validate-spec", help="validate a generated UISpec against the registry ($0)")
+    vs.add_argument("file")
+    vs.add_argument("--json", action="store_true", help="emit {ok, errors} as JSON")
+    vs.set_defaults(fn=cligraph.cmd_validate_spec)
+
+    fb = sub.add_parser("feedback", help="record/summarise on-the-fly generation outcomes ($0)")
+    fb.add_argument("--record", metavar="FILE", help="append one outcome from JSON ('-' = stdin)")
+    fb.set_defaults(fn=cliquery.cmd_feedback)
+
     sub.add_parser("report", help="write GRAPH_REPORT.md (god nodes + communities)").set_defaults(fn=cligraph.cmd_report)
 
     sub.add_parser("setup", help="copy bundled assets (schema, hooks, skills) to ~/.claude/fux/").set_defaults(fn=clicmds.cmd_setup)

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/cligraph.py

@@ -113,6 +113,35 @@ def cmd_explain(args) -> int:
     return 0
 
 
+def cmd_impact(args) -> int:
+    from fux import impact
+    print(impact.render(impact.run(root(), args.file)), end="")
+    return 0
+
+
+def cmd_components(args) -> int:
+    from fux import components
+    reg = components.registry(root(), scope=getattr(args, "scope", None))
+    if getattr(args, "json", False):
+        print(components.render_json(reg), end="")
+    else:
+        print(components.render(reg, kind=getattr(args, "kind", "all")), end="")
+    return 0
+
+
+def cmd_validate_spec(args) -> int:
+    import json
+    from pathlib import Path
+
+    from fux import uispec
+    ok, errs = uispec.run(root(), Path(args.file))
+    if getattr(args, "json", False):
+        print(json.dumps({"ok": ok, "errors": errs}))
+    else:
+        print(uispec.render(ok, errs), end="")
+    return 0 if ok else 2
+
+
 def cmd_report(_args) -> int:
     from fux import paths
     here = root()

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/cliquery.py

@@ -2,12 +2,24 @@
 from __future__ import annotations
 import sys
 
-from fux import (capture, config, costledger, coverage, explain, fetchrules,
-                 lint, loader, mine, parity, paths, recall, savings, scaffold,
-                 seal, stats, tour, verify)
+from fux import (capture, config, costledger, coverage, explain, feedback,
+                 fetchrules, lint, loader, mine, parity, paths, recall, savings,
+                 scaffold, seal, stats, tour, verify)
 from fux.cliutil import root
 
 
+def cmd_feedback(args) -> int:
+    import json
+    here = root()
+    if getattr(args, "record", None):
+        raw = sys.stdin.read() if args.record == "-" else open(args.record).read()
+        feedback.record(here, json.loads(raw))
+        print("fux feedback: recorded")
+        return 0
+    print(feedback.render(feedback.load(here)))
+    return 0
+
+
 def cmd_recall(args) -> int:
     hybrid = True if getattr(args, "hybrid", False) else None
     expand = True if getattr(args, "expand", False) else None

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/community.py

@@ -2,20 +2,24 @@
 
 Replaces graphify's clustering. Synchronous label propagation with sorted,
 tie-broken updates so the result is reproducible across runs (no randomness).
+Votes are **edge-weighted**: a low-confidence `references` edge (weight 0.25) pulls
+a node into a community far less than a precise `calls`/`contains` edge, so the
+loose whole-file xref can't over-fragment or mis-merge clusters by raw count.
 """
 from __future__ import annotations
 
-from collections import Counter
+_TIE = 1e-9
 
 
-def _adjacency(nodes: list[dict], edges: list[dict]) -> dict[str, set[str]]:
+def _adjacency(nodes: list[dict], edges: list[dict]) -> dict[str, dict[str, float]]:
     ids = {n["id"] for n in nodes}
-    adj: dict[str, set[str]] = {n["id"]: set() for n in nodes}
+    adj: dict[str, dict[str, float]] = {n["id"]: {} for n in nodes}
     for e in edges:
         s, t = e.get("source"), e.get("target")
         if s in ids and t in ids and s != t:
-            adj[s].add(t)
-            adj[t].add(s)
+            w = float(e.get("weight", 1.0))
+            adj[s][t] = adj[s].get(t, 0.0) + w
+            adj[t][s] = adj[t].get(s, 0.0) + w
     return adj
 
 
@@ -29,10 +33,12 @@ def detect(nodes: list[dict], edges: list[dict], max_iter: int = 30) -> dict[str
         for nid in order:
             if not adj[nid]:
                 continue
-            votes = Counter(label[n] for n in adj[nid])
+            votes: dict[str, float] = {}
+            for nbr, w in adj[nid].items():
+                votes[label[nbr]] = votes.get(label[nbr], 0.0) + w
             top = max(votes.values())
-            # Deterministic tie-break: smallest label among the winners.
-            best = min(lab for lab, c in votes.items() if c == top)
+            # Deterministic tie-break: smallest label among the (near-)winners.
+            best = min(lab for lab, c in votes.items() if top - c < _TIE)
             if label[nid] != best:
                 label[nid] = best
                 changed = True

fux_engine-0.2.0/fux/components.py

@@ -0,0 +1,98 @@
+"""`fux components` — the design-system registry + data-binding catalog ($0, §18.3).
+
+The runtime-generation prerequisite: so Orff composes UI from existing primitives
+and binds to real data instead of inventing either. Pure stdlib analysis over the
+built graph + source files — component names with their prop fields, plus the
+hooks and DTOs a generated component must wire to. Never calls an LLM.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from fux.astextract import sanitize_lines
+from fux.graphquery import load
+
+_DECL = re.compile(r"\b(?:interface|type)\s+(\w+)\b")
+_MEMBER = re.compile(r"^\s*(?:readonly\s+)?([A-Za-z_]\w*)\s*(\?)?\s*:\s*(.+?);?\s*$")
+# Source-scan patterns — backend-independent (work with or without tree-sitter).
+_PROPS = re.compile(r"(?:export\s+)?(?:interface|type)\s+(\w+)Props\b")
+_DTO = re.compile(r"(?:export\s+)?(?:interface|type)\s+(\w+DTO)\b")
+_HOOK = re.compile(r"(?:export\s+)?(?:const|(?:async\s+)?function)\s+(use[A-Z]\w*)")
+_TS = (".ts", ".tsx")
+
+
+def _props_of(text: str, name: str) -> list[dict]:
+    """Extract the field list of an `interface/type <name>` block, depth-1 only."""
+    san, lines = sanitize_lines(text), text.split("\n")
+    start = next((i for i, s in enumerate(san)
+                  if (m := _DECL.search(s)) and m.group(1) == name), None)
+    if start is None:
+        return []
+    depth, opened, out = 0, False, []
+    for k in range(start, len(san)):
+        at_start = depth
+        if opened and at_start == 1:
+            mm = _MEMBER.match(lines[k])
+            if mm and not lines[k].lstrip().startswith(("//", "*", "/*")):
+                out.append({"name": mm.group(1), "optional": bool(mm.group(2)),
+                            "type": mm.group(3).strip().rstrip(";")})
+        for ch in san[k]:
+            if ch == "{":
+                depth += 1; opened = True
+            elif ch == "}":
+                depth -= 1
+        if opened and depth <= 0:
+            break
+    return out
+
+
+def registry(root: Path, scope: str | None = None) -> dict:
+    """Components (name + props), data hooks (use*), and DTOs, by scanning the
+    TS/TSX sources that the graph covers. Backend-independent — relies on naming
+    conventions in the text, not on tree-sitter symbol nodes."""
+    graph = load(root)                       # raises SystemExit if no graph yet
+    files = sorted({n["file"] for n in graph["nodes"]
+                    if n.get("type") == "code-file" and (n.get("file") or "").endswith(_TS)
+                    and (not scope or n["file"].startswith(scope))})
+    comps, hooks, dtos, seen = [], [], [], set()
+    for rel in files:
+        try:
+            text = (root / rel).read_text(encoding="utf-8")
+        except OSError:
+            continue
+        for i, line in enumerate(sanitize_lines(text), 1):
+            if (m := _PROPS.search(line)):
+                comps.append({"name": m.group(1), "file": rel, "line": i,
+                              "props": _props_of(text, m.group(1) + "Props")})
+            if (d := _DTO.search(line)):
+                dtos.append({"name": d.group(1), "file": rel})
+            if (h := _HOOK.search(line)) and (h.group(1), rel) not in seen:
+                seen.add((h.group(1), rel))
+                hooks.append({"name": h.group(1), "file": rel})
+    key = lambda x: x["name"]
+    return {"components": sorted(comps, key=key),
+            "hooks": sorted(hooks, key=key), "dtos": sorted(dtos, key=key)}
+
+
+def render(reg: dict, kind: str = "all") -> str:
+    out: list[str] = []
+    if kind in ("all", "components"):
+        out.append(f"## Components ({len(reg['components'])}) — compose from these")
+        for c in reg["components"]:
+            ps = ", ".join(p["name"] + ("?" if p["optional"] else "") for p in c["props"])
+            out.append(f"- **{c['name']}** ({c['file']}) — props: {ps or '—'}")
+        out.append("")
+    if kind in ("all", "hooks"):
+        out.append(f"## Data hooks ({len(reg['hooks'])}) — bind to these, don't refetch")
+        out += [f"- {h['name']} ({h['file']})" for h in reg["hooks"]]
+        out.append("")
+    if kind in ("all", "dtos"):
+        out.append(f"## DTOs ({len(reg['dtos'])}) — the data shapes")
+        out += [f"- {d['name']} ({d['file']})" for d in reg["dtos"]]
+    return "\n".join(out).rstrip() + "\n"
+
+
+def render_json(reg: dict) -> str:
+    return json.dumps(reg, indent=2, ensure_ascii=False) + "\n"

fux_engine-0.2.0/fux/feedback.py

@@ -0,0 +1,65 @@
+"""`fux feedback` — record + summarise on-the-fly generation outcomes (§18.4, $0).
+
+The brain's learning loop: every Orff compose attempt (valid / rejected / repaired)
+is appended as a JSON line, and `fux feedback` reports the acceptance rate and the
+most common rejection reasons — so a recurring validator failure becomes a signal to
+add a component, a prop, or a contract rule. Deterministic; no LLM, no memory writes.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from collections import Counter
+from pathlib import Path
+
+from fux import paths
+
+_FIELDS = ("prompt", "valid", "errors", "attempts", "provider", "model")
+
+
+def _file(root: Path) -> Path:
+    d = paths.Footprint(root).base / "capture"
+    d.mkdir(parents=True, exist_ok=True)
+    return d / "feedback.jsonl"
+
+
+def record(root: Path, data: dict) -> dict:
+    rec = {
+        "ts": _dt.datetime.now().isoformat(timespec="seconds"),
+        "prompt": str(data.get("prompt", ""))[:200],
+        "valid": bool(data.get("valid")),
+        "errors": list(data.get("errors") or []),
+        "attempts": int(data.get("attempts", 1)),
+        "provider": data.get("provider"),
+        "model": data.get("model"),
+    }
+    with _file(root).open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(rec) + "\n")
+    return rec
+
+
+def load(root: Path) -> list[dict]:
+    f = _file(root)
+    return [json.loads(x) for x in f.read_text().splitlines() if x.strip()] if f.exists() else []
+
+
+def _reason(err: str) -> str:
+    for key in ("unknown component", "not on", "missing required prop",
+                "data hook", "takes no children", "did not return"):
+        if key in err:
+            return key
+    return err[:40]
+
+
+def render(rows: list[dict]) -> str:
+    if not rows:
+        return "fux feedback: no generation outcomes recorded yet."
+    ok = sum(1 for r in rows if r["valid"])
+    first_try = sum(1 for r in rows if r["valid"] and r["attempts"] == 1)
+    reasons = Counter(_reason(e) for r in rows if not r["valid"] for e in r["errors"])
+    out = [f"fux feedback — {len(rows)} compose(s): {ok} valid "
+           f"({100 * ok // len(rows)}%), {first_try} on first try."]
+    if reasons:
+        out.append("Top rejection reasons (candidate registry/rule gaps):")
+        out += [f"  {n}× {r}" for r, n in reasons.most_common(5)]
+    return "\n".join(out)

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/graph.py

@@ -10,6 +10,29 @@ from fux.model import RuleSet
 
 REF_RE = re.compile(r"^([^#]+)(?:#L(\d+)(?:-L?(\d+))?)?$")
 
+# Per-edge-type confidence + clustering/centrality weight. Structural (`contains`,
+# `calls`) and authored (`governs`, `related`, typed rule↔rule) edges are precise —
+# EXTRACTED, full weight. The looser whole-file `references` xref ([_xref]) matches
+# any identifier against any symbol label, so it is INFERRED and down-weighted: it
+# is the dominant edge by raw count and would otherwise drown the precise signal in
+# community detection + PageRank. graphify carried this confidence label; Fux now does too.
+_EDGE_CONF: dict[str, tuple[str, float]] = {
+    "contains": ("EXTRACTED", 1.0),
+    "calls": ("EXTRACTED", 1.0),
+    "governs": ("EXTRACTED", 1.0),
+    "related": ("EXTRACTED", 1.0),
+    "references": ("INFERRED", 0.25),
+}
+_DEFAULT_CONF = ("EXTRACTED", 1.0)          # authored typed rule↔rule edges
+
+
+def _stamp_confidence(edges: list[dict]) -> None:
+    """Annotate each edge with ``confidence`` (EXTRACTED|INFERRED) + clustering ``weight``."""
+    for e in edges:
+        conf, weight = _EDGE_CONF.get(e["type"], _DEFAULT_CONF)
+        e.setdefault("confidence", conf)
+        e.setdefault("weight", weight)
+
 
 def _iter_sources(root: Path, include: list[str], ignore: list[str]):
     for path in sorted(root.rglob("*")):
@@ -51,6 +74,7 @@ def build(root: Path, rs: RuleSet, cfg: dict, full: bool = False) -> dict:
     edges += xcalls
     edges += _xref(nodes, texts, covered)
     _add_knowledge(nodes, edges, rs)
+    _stamp_confidence(edges)            # weight-aware before clustering/centrality
     comm = community.detect(list(nodes.values()), edges)
     for nid, c in comm.items():
         nodes[nid]["community"] = c

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/graphquery.py

@@ -28,6 +28,19 @@ def _adj(graph: dict) -> dict[str, set[str]]:
     return adj
 
 
+def _wadj(graph: dict) -> dict[str, dict[str, float]]:
+    """Weighted undirected adjacency for centrality — low-confidence `references`
+    edges (weight 0.25) carry proportionally less rank than precise `calls`."""
+    adj: dict[str, dict[str, float]] = {n["id"]: {} for n in graph["nodes"]}
+    for e in graph["edges"]:
+        s, t = e["source"], e["target"]
+        if s in adj and t in adj:
+            w = float(e.get("weight", 1.0))
+            adj[s][t] = adj[s].get(t, 0.0) + w
+            adj[t][s] = adj[t].get(s, 0.0) + w
+    return adj
+
+
 def find(graph: dict, term: str) -> dict | None:
     """Resolve a free-text term to the best-matching node."""
     t = term.lower().strip()
@@ -109,8 +122,8 @@ def pagerank(graph: dict, damping: float = 0.85, iterations: int = 100,
     """
     ids = sorted(n["id"] for n in graph["nodes"])
     n = len(ids) or 1
-    adj = _adj(graph)
-    deg = {nid: len(adj.get(nid, ())) for nid in ids}
+    adj = _wadj(graph)
+    deg = {nid: sum(adj.get(nid, {}).values()) for nid in ids}    # weighted degree
     rank = {nid: 1.0 / n for nid in ids}
     base = (1.0 - damping) / n
     for _ in range(iterations):
@@ -119,8 +132,8 @@ def pagerank(graph: dict, damping: float = 0.85, iterations: int = 100,
         for nid in ids:
             if deg[nid]:
                 share = damping * rank[nid] / deg[nid]
-                for m in sorted(adj[nid]):
-                    nxt[m] += share
+                for m, w in sorted(adj[nid].items()):
+                    nxt[m] += share * w
         if sum(abs(nxt[nid] - rank[nid]) for nid in ids) < tol:
             rank = nxt
             break

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/hybrid.py

@@ -29,7 +29,11 @@ def fuse(root: Path, query: str, rules: list[Rule], top: int = 6,
     if semantic:
         rankings.append(semantic)
 
-    graphical = _graph_ranking(root, lexical[:3])
+    # Seed graph proximity from the lexical anchors — but fall back to the semantic
+    # top when lexical is empty, which is exactly the paraphrase case hybrid exists
+    # to rescue (no shared keyword → no lexical hit → the graph leg would otherwise
+    # go dark). plan §17.1 / recall-engine.compare.md phase-2 trigger.
+    graphical = _graph_ranking(root, (lexical or semantic)[:3])
     if graphical:
         rankings.append([rid for rid in graphical if rid in by_id])
 

fux_engine-0.2.0/fux/impact.py

@@ -0,0 +1,100 @@
+"""`fux impact <file>` — downstream blast radius of changing a file ($0, §18.1).
+
+The "maintain code" brain capability: before you touch a file, see what it can
+break — invariants to re-verify, governing rules whose *why* may go stale, and
+the callers that depend on its symbols. Stdlib graph traversal; no LLM.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from fux import explain, graphquery
+from fux.model import Rule
+
+
+@dataclass
+class Impact:
+    target: str
+    symbols: list[str] = field(default_factory=list)        # symbols defined here
+    governing: list[Rule] = field(default_factory=list)     # rules that govern it
+    invariants: list[Rule] = field(default_factory=list)    # governing ⊃ machine-checkable
+    callers: list[str] = field(default_factory=list)        # precise `calls` dependents
+    referenced_by: list[str] = field(default_factory=list)  # loose `references` (INFERRED)
+    related: list[str] = field(default_factory=list)        # one-hop related rule ids
+    in_graph: bool = True
+
+    @property
+    def empty(self) -> bool:
+        return not (self.governing or self.callers or self.referenced_by)
+
+
+def _norm(file_rel: str) -> str:
+    return file_rel.replace("\\", "/").lstrip("./").rstrip("/")
+
+
+def run(root: Path, file_rel: str) -> Impact:
+    """Compute the blast radius of editing ``file_rel`` from the built graph."""
+    target = _norm(file_rel)
+    graph = graphquery.load(root)            # raises SystemExit if no graph yet
+    ids = {n["id"] for n in graph["nodes"]}
+    # Symbols defined in the file (contains edges: file → symbol).
+    symbols = sorted(e["target"] for e in graph["edges"]
+                     if e["type"] == "contains" and e["source"] == target)
+    sym_set = set(symbols) | {target}
+
+    # Split precise `calls` from loose `references` (INFERRED) so real callers
+    # aren't drowned by generic-name collisions (value/total/get).
+    callers: set[str] = set()
+    referenced_by: set[str] = set()
+    for e in graph["edges"]:
+        if e["target"] not in sym_set:
+            continue
+        dependent = e["source"].split("::", 1)[0]
+        if dependent == target:
+            continue
+        if e["type"] == "calls":
+            callers.add(dependent)
+        elif e["type"] == "references":
+            referenced_by.add(dependent)
+    referenced_by -= callers                 # a precise call beats a loose ref
+
+    governing = explain.refs(root, target)
+    invariants = [r for r in governing if r.type == "invariant" or r.fm.get("check")]
+    related = sorted({rid for r in governing for rid in r.related})
+
+    return Impact(target=target, symbols=symbols, governing=governing,
+                  invariants=invariants, callers=sorted(callers),
+                  referenced_by=sorted(referenced_by),
+                  related=related, in_graph=target in ids)
+
+
+def render(im: Impact) -> str:
+    """A maintenance checklist, ordered by how expensive it is to get wrong."""
+    out = [f"# impact of changing {im.target}"]
+    if not im.in_graph:
+        out.append("_(not a graphed file — `fux build` may be stale, or the path is wrong)_")
+    inv_ids = {r.id for r in im.invariants}
+
+    def section(title: str, items: list[str], cap: int | None = None) -> None:
+        if not items:
+            return
+        out.extend(["", f"## {title}"])
+        out.extend(f"- {x}" for x in (items[:cap] if cap else items))
+        if cap and len(items) > cap:
+            out.append(f"  …and {len(items) - cap} more")
+
+    section("Invariants that must still hold — run `fux verify`",
+            [f"**{r.id}** ({r.type})" + (f" — `{r.fm['check']}`" if r.fm.get("check") else "")
+             for r in im.invariants])
+    section("Governing rules — update the *why* if behaviour changed",
+            [f"{r.id} ({r.type}) — {r.title}" for r in im.governing if r.id not in inv_ids])
+    if im.related:
+        out += ["", "## Related knowledge to review", "  " + ", ".join(im.related)]
+    section(f"Downstream callers ({len(im.callers)} file(s) call into this — re-test)", im.callers)
+    section(f"Possibly affected ({len(im.referenced_by)} reference these names — lower confidence)",
+            im.referenced_by, cap=10)
+    if im.empty:
+        out += ["", "No governing rules and no downstream callers found — low blast "
+                "radius, or this file isn't graphed/governed yet."]
+    return "\n".join(out).strip() + "\n"

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/mcpserver.py

@@ -16,8 +16,8 @@ import json
 import sys
 from pathlib import Path
 
-from fux import (__version__, coverage, explain, graphquery, paths, recall,
-                 savings, scaffold, stats)
+from fux import (__version__, components, coverage, explain, graphquery, impact,
+                 paths, recall, savings, scaffold, stats, uispec)
 
 PROTOCOL = "2024-11-05"
 
@@ -34,6 +34,23 @@ TOOLS = [
      "description": "Reverse lookup — which rules govern a given file path.",
      "inputSchema": {"type": "object", "required": ["file"],
                      "properties": {"file": {"type": "string"}}}},
+    {"name": "fux_impact",
+     "description": "Downstream blast radius of changing a file: governing rules whose "
+                    "why may go stale, invariants to re-verify, and caller files that may break.",
+     "inputSchema": {"type": "object", "required": ["file"],
+                     "properties": {"file": {"type": "string"}}}},
+    {"name": "fux_components",
+     "description": "The design-system registry + data-binding catalog (JSON): UI components "
+                    "with their prop fields, data hooks (use*), and DTO shapes — so a generated "
+                    "component composes from real primitives and binds to real data.",
+     "inputSchema": {"type": "object", "properties": {
+         "scope": {"type": "string"}}}},
+    {"name": "fux_validate_spec",
+     "description": "Validate a declarative UISpec against the registry before mounting — "
+                    "rejects unknown components, undeclared props, and unknown data hooks. "
+                    "Returns 'valid' or the list of violations. The runtime guardrail.",
+     "inputSchema": {"type": "object", "required": ["spec"], "properties": {
+         "spec": {"type": "object", "description": "the UISpec node tree"}}}},
     {"name": "fux_coverage",
      "description": "Percent of important code files that carry a governing rule.",
      "inputSchema": {"type": "object", "properties": {}}},
@@ -83,6 +100,13 @@ def _call(name: str, args: dict) -> str:
         hits = explain.refs(root, args["file"])
         return "\n".join(f"{r.id} ({r.type}) — {r.title}" for r in hits) \
             or f"(no rules govern {args['file']})"
+    if name == "fux_impact":
+        return impact.render(impact.run(root, args["file"]))
+    if name == "fux_components":
+        return components.render_json(components.registry(root, scope=args.get("scope")))
+    if name == "fux_validate_spec":
+        errs = uispec.validate(components.registry(root), args["spec"])
+        return uispec.render(not errs, errs)
     if name == "fux_coverage":
         c = coverage.run(root)
         return f"{c.pct:.0f}% ({c.governed}/{c.total} important files governed)"

{fux_engine-0.1.2 → fux_engine-0.2.0}/fux/report.py

@@ -15,6 +15,7 @@ def render(graph: dict) -> str:
              f"{meta.get('code_files', 0)} code files · {meta.get('rules', 0)} rules · "
              f"{meta.get('communities', 0)} communities._", ""]
     lines += _types(nodes)
+    lines += _edges(graph["edges"])
     lines += _god(graph, by_id)
     lines += _chokepoints(graph, by_id)
     lines += _communities(nodes)
@@ -28,6 +29,16 @@ def _types(nodes: list[dict]) -> list[str]:
     return out + [""]
 
 
+def _edges(edges: list[dict]) -> list[str]:
+    """Edge mix by type + confidence — INFERRED edges are the loose, down-weighted ones."""
+    by_type = Counter(e.get("type") for e in edges)
+    inferred = sum(1 for e in edges if e.get("confidence") == "INFERRED")
+    out = ["## Edges", "", f"_{inferred} of {len(edges)} are INFERRED "
+           "(low-confidence `references`, down-weighted in clustering/centrality)._", ""]
+    out += [f"- {t}: {c}" for t, c in sorted(by_type.items(), key=lambda kv: -kv[1])]
+    return out + [""]
+
+
 def _god(graph: dict, by_id: dict) -> list[str]:
     out = ["## God nodes (highest connectivity)", ""]
     for nid, deg in graphquery.god_nodes(graph, 12):

fux_engine-0.2.0/fux/uispec.py

@@ -0,0 +1,64 @@
+"""`fux validate-spec` — validate a declarative UISpec against the registry ($0, §18.3.3).
+
+The mount-time guardrail for Orff's on-the-fly generation: a generated UI may only
+compose **registry** components, with **declared** props, bound to **known** data
+hooks. Anything else is rejected before it can render. This is what makes runtime
+generation safe — the model emits a declarative tree, never code; the frontend
+renders it from a whitelist. Pure structural validation; no code execution, no LLM.
+
+UISpec node:  {"component": "Card", "props": {...}, "data": "useHoldings",
+               "children": [ <node>, {"text": "literal"} ]}
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fux import components
+
+
+def validate(reg: dict, spec: object) -> list[str]:
+    """Return a list of violations; empty means the spec is safe to mount."""
+    by_name = {c["name"]: c for c in reg["components"]}
+    hooks = {h["name"] for h in reg["hooks"]}
+    errs: list[str] = []
+    _node(spec, "$", by_name, hooks, errs)
+    return errs
+
+
+def _node(node: object, path: str, by_name: dict, hooks: set, errs: list[str]) -> None:
+    if isinstance(node, dict) and "text" in node and "component" not in node:
+        return                                       # literal text leaf
+    if not isinstance(node, dict) or "component" not in node:
+        errs.append(f"{path}: node needs a 'component' or 'text'")
+        return
+    name = node["component"]
+    comp = by_name.get(name)
+    if comp is None:
+        errs.append(f"{path}: unknown component '{name}' — not in the registry")
+        return
+    prop_names = {p["name"] for p in comp["props"]}
+    required = {p["name"] for p in comp["props"] if not p["optional"]} - {"children", "className"}
+    here = f"{path}.{name}"
+    props = node.get("props") or {}
+    errs += [f"{here}: prop '{k}' not on {name}" for k in props if k not in prop_names]
+    errs += [f"{here}: missing required prop '{r}'" for r in sorted(required - set(props))]
+    if (data := node.get("data")) and data not in hooks:
+        errs.append(f"{here}: data hook '{data}' not in the registry")
+    children = node.get("children") or []
+    if children and "children" not in prop_names:
+        errs.append(f"{here}: {name} takes no children")
+    for i, ch in enumerate(children):
+        _node(ch, f"{here}[{i}]", by_name, hooks, errs)
+
+
+def run(root: Path, spec_path: Path) -> tuple[bool, list[str]]:
+    reg = components.registry(root)
+    errs = validate(reg, json.loads(spec_path.read_text(encoding="utf-8")))
+    return not errs, errs
+
+
+def render(ok: bool, errs: list[str]) -> str:
+    if ok:
+        return "✔ spec valid — every component, prop, and data hook is in the registry\n"
+    return "✘ spec rejected:\n" + "\n".join(f"  - {e}" for e in errs) + "\n"