graphifyy 0.9.2__tar.gz → 0.9.4__tar.gz

{graphifyy-0.9.2/graphifyy.egg-info → graphifyy-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphifyy
-Version: 0.9.2
+Version: 0.9.4
 Summary: AI coding assistant skill (Claude Code, CodeBuddy, Codex, OpenCode, Kilo Code, Cursor, Gemini CLI, Aider, OpenClaw, Factory Droid, Trae, Hermes, Kiro, Pi, Devin CLI, Google Antigravity) - turn any folder of code, docs, papers, images, or videos into a queryable knowledge graph
 License: MIT License
         
@@ -687,7 +687,9 @@ graphify save-result --question "Q" --answer "A" --nodes Foo Bar --outcome usefu
 graphify reflect                   # aggregate graphify-out/memory/ outcomes into reflections/LESSONS.md
 graphify reflect --if-stale        # no-op when LESSONS.md is already newer than every input (cheap to run each session)
 graphify reflect --out docs/LESSONS.md    # write the lessons doc somewhere else
-graphify reflect --graph graphify-out/graph.json  # also group lessons by community
+graphify reflect --graph graphify-out/graph.json  # group lessons by community + write the work-memory overlay (.graphify_learning.json)
+                                   # the overlay tags nodes preferred/tentative/contested (recency-weighted, with provenance);
+                                   # graphify explain / query then show a "Lesson:" hint, flagged "code changed — re-verify" when the source moved on
 
 graphify uninstall                 # remove from all platforms in one shot
 graphify uninstall --purge         # also delete graphify-out/

{graphifyy-0.9.2 → graphifyy-0.9.4}/README.md

@@ -550,7 +550,9 @@ graphify save-result --question "Q" --answer "A" --nodes Foo Bar --outcome usefu
 graphify reflect                   # aggregate graphify-out/memory/ outcomes into reflections/LESSONS.md
 graphify reflect --if-stale        # no-op when LESSONS.md is already newer than every input (cheap to run each session)
 graphify reflect --out docs/LESSONS.md    # write the lessons doc somewhere else
-graphify reflect --graph graphify-out/graph.json  # also group lessons by community
+graphify reflect --graph graphify-out/graph.json  # group lessons by community + write the work-memory overlay (.graphify_learning.json)
+                                   # the overlay tags nodes preferred/tentative/contested (recency-weighted, with provenance);
+                                   # graphify explain / query then show a "Lesson:" hint, flagged "code changed — re-verify" when the source moved on
 
 graphify uninstall                 # remove from all platforms in one shot
 graphify uninstall --purge         # also delete graphify-out/

{graphifyy-0.9.2 → graphifyy-0.9.4}/graphify/__main__.py

@@ -148,7 +148,41 @@ def _check_skill_version(skill_dst: Path) -> None:
     except OSError:
         return
     if installed != __version__:
-        print(f"  warning: skill is from graphify {installed}, package is {__version__}. Run 'graphify install' to update.", file=sys.stderr)
+        if _version_tuple(installed) > _version_tuple(__version__):
+            # The skill on disk is NEWER than the running package. `graphify install`
+            # writes the package's OWN (older) bundled skill and re-stamps the version,
+            # so following the old "run install" advice would silently DOWNGRADE the
+            # skill. The real fix is to upgrade the package (#1568). Common for a stale
+            # `uv tool` CLI, or a contributor whose dev checkout stamped a newer skill.
+            print(
+                f"  warning: skill is from graphify {installed}, but the package is "
+                f"{__version__} (older). Upgrade the package "
+                f"(e.g. 'uv tool upgrade graphifyy' or 'pip install -U graphifyy'); "
+                f"running 'graphify install' would downgrade the skill.",
+                file=sys.stderr,
+            )
+        else:
+            print(f"  warning: skill is from graphify {installed}, package is {__version__}. Run 'graphify install' to update.", file=sys.stderr)
+
+
+def _version_tuple(version: str) -> tuple[int, ...]:
+    """Parse a version string into a comparable integer tuple (``0.9.2`` -> ``(0, 9, 2)``).
+
+    Reads the leading digits of each dot-segment, so pre/post-release suffixes
+    (``1.0.0rc1``) compare by their numeric core. A non-numeric or empty segment
+    becomes 0, so a malformed stamp degrades to a conservative comparison rather
+    than raising.
+    """
+    parts: list[int] = []
+    for segment in str(version).split("."):
+        digits = ""
+        for ch in segment:
+            if ch.isdigit():
+                digits += ch
+            else:
+                break
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts)
 
 
 def _refresh_all_version_stamps() -> None:
@@ -3186,6 +3220,30 @@ def main() -> None:
         )
         print(f"  Type:      {d.get('file_type', '')}")
         print(f"  Community: {d.get('community_name') or d.get('community', '')}")
+        # Work-memory overlay: a derived experiential hint from `graphify reflect`,
+        # merged in display-only from the .graphify_learning.json sidecar next to
+        # graph.json. No line when the node has no overlay entry.
+        try:
+            from graphify.reflect import load_learning_overlay as _llo
+            from graphify.security import sanitize_label as _sl
+            _overlay = _llo(gp)
+            _entry = _overlay.get(str(nid))
+            if _entry:
+                _status = _sl(str(_entry.get("status", "")))
+                if _status == "contested":
+                    _line = (f"  Lesson: contested (useful {_entry.get('uses', 0)} / "
+                             f"dead-end {_entry.get('neg', 0)})")
+                elif _status == "preferred":
+                    _line = (f"  Lesson: preferred source (start here) — "
+                             f"{_entry.get('uses', 0)} useful, score={_entry.get('score', 0)}")
+                else:
+                    _line = (f"  Lesson: {_status or 'tentative'} — "
+                             f"{_entry.get('uses', 0)} useful, score={_entry.get('score', 0)}")
+                if _entry.get("stale"):
+                    _line += " [code changed since — re-verify]"
+                print(_line)
+        except Exception:
+            pass
         print(f"  Degree:    {G.degree(nid)}")
         from graphify.build import edge_data
         connections: list[tuple[str, str, dict]] = []  # (direction, neighbor_id, edge_data)
@@ -3501,17 +3559,20 @@ def main() -> None:
         else:
             # No labels file yet (or `graphify label` forced a refresh). When run
             # standalone there is no orchestrating agent to do skill.md Step 5, so
-            # auto-name communities with the configured backend rather than leave
-            # "Community N" (#1097). Degrades to placeholders if no backend/on error.
+            # auto-name communities rather than leave "Community N" (#1097).
+            from graphify.cluster import label_communities_by_hub
             from graphify.llm import generate_community_labels
             print("Labeling communities...")
-            # The final labels (LLM or placeholder fallback) are persisted to
-            # .graphify_labels.json by the unconditional write below.
+            # Deterministic, LLM-free base labels: name each community after its
+            # highest-degree hub, so the report is readable even with no backend
+            # (previously bare "Community N"). A configured LLM backend overrides these
+            # with richer names below; its no-backend placeholder fallback does NOT.
+            hub_labels = label_communities_by_hub(G, communities)
             label_communities_input = communities
-            labels = {}
+            labels = dict(hub_labels)
             if missing_only:
                 labels = {
-                    cid: existing_labels.get(cid, f"Community {cid}")
+                    cid: existing_labels.get(cid, hub_labels[cid])
                     for cid in communities
                 }
                 label_communities_input = {
@@ -3523,16 +3584,24 @@ def main() -> None:
                 G, label_communities_input, backend=label_backend, model=label_model, gods=gods,
                 max_concurrency=label_max_concurrency, batch_size=label_batch_size,
             )
-            labels.update(generated_labels)
+            # Only let the LLM OVERRIDE where it produced a real name — its no-backend
+            # fallback returns "Community {cid}" placeholders, which must not clobber
+            # the deterministic hub labels.
+            labels.update({
+                cid: v for cid, v in generated_labels.items()
+                if v and v != f"Community {cid}"
+            })
         stages.mark("label")
         questions = suggest_questions(G, communities, labels)
         tokens = {"input": 0, "output": 0}
         from graphify.export import _git_head as _gh
         _commit = _gh()
+        from graphify.report import load_learning_for_report as _llfr
         report = generate(G, communities, cohesion, labels, gods, surprises,
                           {"warning": "cluster-only mode — file stats not available"},
                           tokens, str(watch_path), suggested_questions=questions,
-                          min_community_size=min_community_size, built_at_commit=_commit)
+                          min_community_size=min_community_size, built_at_commit=_commit,
+                          learning=_llfr(out / "graph.json"))
         (out / "GRAPH_REPORT.md").write_text(report, encoding="utf-8")
         stages.mark("report")
         from graphify.export import backup_if_protected as _backup

{graphifyy-0.9.2 → graphifyy-0.9.4}/graphify/affected.py

@@ -11,6 +11,7 @@ import networkx as nx
 
 DEFAULT_AFFECTED_RELATIONS = (
     "calls",
+    "indirect_call",
     "references",
     "imports",
     "imports_from",
@@ -209,7 +210,13 @@ def load_graph(path: Path) -> nx.Graph:
     import json
     from networkx.readwrite import json_graph
 
-    raw = json.loads(path.read_text(encoding="utf-8"))
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        raise RuntimeError(
+            f"Cannot read graph file {path}: {exc}. "
+            "Re-run 'graphify extract' to regenerate it."
+        ) from exc
     # Force directed so stored caller→callee direction survives the round-trip;
     # mirrors serve.py and __main__.py (#1174).
     raw = {**raw, "directed": True}

{graphifyy-0.9.2 → graphifyy-0.9.4}/graphify/build.py

@@ -53,6 +53,56 @@ _FILE_TYPE_SYNONYMS = {
 }
 
 
+# Hyperedge member lists are canonically keyed `nodes` (see graphify/llm.py
+# extraction spec), but LLM/subagent drift and externally-supplied graph.json
+# sometimes emit `members` or `node_ids`. _normalize_hyperedge_members folds
+# those aliases into `nodes` at ingest so every downstream consumer reads one
+# canonical key — mirroring the `from`/`to` edge-endpoint tolerance below.
+_HE_MEMBER_ALIASES = ("members", "node_ids")
+
+
+def _normalize_hyperedge_members(he: object) -> None:
+    """Canonicalize a hyperedge's member list onto the `nodes` key, in place.
+
+    If `nodes` is already a list it wins (canonical), and only stray alias keys
+    are dropped. Otherwise the first alias (`members`, then `node_ids`) that is a
+    list is moved to `nodes`, deduped preserving order, with a single stderr
+    WARNING naming the hyperedge id and alias used. Leftover alias keys are
+    always removed so downstream code never re-reads them.
+    """
+    if not isinstance(he, dict):
+        return
+    if not isinstance(he.get("nodes"), list):
+        for alias in _HE_MEMBER_ALIASES:
+            val = he.get(alias)
+            if isinstance(val, list):
+                seen: set = set()
+                deduped: list = []
+                for ref in val:
+                    try:
+                        is_dupe = ref in seen
+                    except TypeError:
+                        is_dupe = False  # unhashable ref: keep it, validator flags it
+                    if is_dupe:
+                        continue
+                    try:
+                        seen.add(ref)
+                    except TypeError:
+                        pass
+                    deduped.append(ref)
+                he["nodes"] = deduped
+                print(
+                    f"[graphify] WARNING: hyperedge "
+                    f"'{he.get('id', '?')}' uses field '{alias}' instead of "
+                    f"'nodes'; normalizing.",
+                    file=sys.stderr,
+                )
+                break
+    # Drop any leftover alias keys regardless of which branch ran above.
+    for alias in _HE_MEMBER_ALIASES:
+        he.pop(alias, None)
+
+
 def _norm_source_file(p: str | None, root: str | None = None) -> str | None:
     """Normalize path separators and relativize absolute paths.
 
@@ -67,10 +117,43 @@ def _norm_source_file(p: str | None, root: str | None = None) -> str | None:
         try:
             p = Path(p).relative_to(root).as_posix()
         except ValueError:
-            pass
+            # Lexical relative_to failed. Retry with both sides fully resolved:
+            # a symlinked scan root (macOS /var -> /private/var, or a symlinked
+            # home/worktree) makes the raw prefixes differ even though they point
+            # at the same dir, which otherwise silently defeats prune/replace
+            # matching. Only the slow path resolves, so the common lexical match
+            # stays filesystem-free.
+            try:
+                p = Path(p).resolve().relative_to(Path(root).resolve()).as_posix()
+            except (ValueError, OSError):
+                pass
     return p
 
 
+def _infer_merge_root(graph_path: Path) -> str | None:
+    """Best-effort scan root for relativizing paths in build_merge when the caller
+    passes no ``root`` (#1571).
+
+    Prefers the committed ``graphify-out/.graphify_root`` marker — the authoritative
+    scan root graphify records at build/watch time (#686/#1423) — then falls back to
+    the directory that contains the output dir (``graph.json``'s grandparent, i.e.
+    ``<root>/graphify-out/graph.json`` -> ``<root>``). Returns None if neither
+    resolves, in which case normalization is a no-op (prior behavior).
+    """
+    try:
+        marker = graph_path.parent / ".graphify_root"
+        if marker.exists():
+            recorded = marker.read_text(encoding="utf-8").strip()
+            if recorded:
+                return str(Path(recorded).resolve())
+    except OSError:
+        pass
+    try:
+        return str(graph_path.parent.parent.resolve())
+    except Exception:
+        return None
+
+
 def edge_data(G: nx.Graph, u: str, v: str) -> dict:
     """Return one edge attribute dict for (u, v), tolerating MultiGraph.
 
@@ -279,6 +362,14 @@ def build_from_json(extraction: dict, *, directed: bool = False, root: str | Pat
         if ft and ft not in {"code", "document", "paper", "image", "rationale", "concept"}:
             node["file_type"] = _FILE_TYPE_SYNONYMS.get(ft, "concept")
 
+    # Canonicalize hyperedge member lists (#1561): producers sometimes key the
+    # member list `members`/`node_ids` instead of `nodes`. Fold aliases onto
+    # `nodes` here — BEFORE validation and the semantic-rekey loop below — so
+    # every downstream consumer (rekey, source_file relativize, to_json) reads
+    # one canonical key, the same way edge endpoints alias from/to at build.
+    for he in extraction.get("hyperedges", []) or []:
+        _normalize_hyperedge_members(he)
+
     errors = validate_extraction(extraction)
     # Dangling edges (stdlib/external imports) are expected - only warn about real schema errors.
     real_errors = [e for e in errors if "does not match any node id" not in e]
@@ -489,8 +580,15 @@ def build_from_json(extraction: dict, *, directed: bool = False, root: str | Pat
                 ".ts": "js", ".tsx": "js",
                 ".go": "go", ".rs": "rs",
                 ".java": "jvm", ".kt": "jvm", ".scala": "jvm", ".groovy": "jvm",
-                ".c": "c", ".h": "c", ".cc": "cpp", ".cpp": "cpp", ".hpp": "cpp",
-                ".cu": "cpp", ".cuh": "cpp", ".metal": "cpp",
+                # C, C++, and ObjC interoperate within one compilation unit: a method
+                # declared in a shared `.h` is defined/called from a `.c`/`.cpp`/`.m`
+                # sibling, so a cross-file INFERRED call from impl to its header decl
+                # is legitimate, not a phantom name-collision across languages. Treat
+                # the whole C family as one so the receiver-typed C++/ObjC member-call
+                # resolvers' header-targeting edges survive build (#1547/#1556).
+                ".c": "c", ".h": "c", ".cc": "c", ".cpp": "c", ".hpp": "c",
+                ".cxx": "c", ".hh": "c", ".hxx": "c",
+                ".cu": "c", ".cuh": "c", ".metal": "c", ".m": "c", ".mm": "c",
                 ".rb": "rb", ".php": "php", ".cs": "cs", ".swift": "swift", ".lua": "lua",
             }
             src_ext = Path(G.nodes[src].get("source_file") or "").suffix.lower()
@@ -577,7 +675,15 @@ def deduplicate_by_label(nodes: list[dict], edges: list[dict]) -> tuple[list[dic
     """Merge nodes that share a normalised label, rewriting edge references.
 
     Prefers IDs without chunk suffixes (_c\\d+) and shorter IDs when tied.
-    Drops self-loops created by the merge. Called in build() automatically.
+    Drops self-loops created by the merge.
+
+    Dormant: this is NOT wired into ``build()`` — the active dedup path is
+    ``deduplicate_entities`` (imported and called in ``build``), which supersedes
+    it. The previous "Called in build() automatically" note was never true. It
+    also merges by label alone with no ``file_type`` guard, so it must not be
+    enabled for code nodes: same-label symbols from different files/packages
+    (e.g. two ``Account`` types) would collapse into one — the cross-file
+    conflation ``deduplicate_entities`` deliberately avoids for code (#1205).
     """
     _CHUNK_SUFFIX = re.compile(r"_c\d+$")
     canonical: dict[str, dict] = {}  # norm_label -> surviving node
@@ -649,16 +755,36 @@ def build_merge(
         # NetworkX round-trip loses direction permanently (#760).
         from graphify.security import check_graph_file_size_cap
         check_graph_file_size_cap(graph_path)
-        data = json.loads(graph_path.read_text(encoding="utf-8"))
+        try:
+            data = json.loads(graph_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            raise RuntimeError(
+                f"Cannot read {graph_path} for incremental merge: {exc}. "
+                "Delete the file and run a full rebuild."
+            ) from exc
         links_key = "links" if "links" in data else "edges"
         existing_nodes = list(data.get("nodes", []))
         existing_edges = list(data.get(links_key, []))
+        existing_hyperedges = list(data.get("hyperedges", []))
         had_graph = True
     else:
         existing_nodes = []
         existing_edges = []
+        existing_hyperedges = []
         had_graph = False
 
+    # Effective root for relativizing absolute source_file / prune paths back to the
+    # stored relative source_file keys. When the caller passes root we use it;
+    # otherwise fall back to the graph's recorded scan root, so absolute
+    # prune_sources and new-chunk paths still match even when a caller omits root
+    # (#1571 — the skill's --update runbook calls build_merge without root, so
+    # absolute deleted-file paths never matched the relative node keys and their
+    # nodes survived as ghosts).
+    _eff_root = (
+        str(Path(root).resolve()) if root is not None
+        else _infer_merge_root(graph_path)
+    )
+
     # Re-extracted files REPLACE their prior contribution. Every source_file
     # present in new_chunks is dropped from the loaded base before merging, so a
     # CHANGED file's stale nodes/edges don't accumulate across incremental
@@ -668,7 +794,7 @@ def build_merge(
     # for them; genuinely deleted files are still handled via prune_sources.
     # Matched in both raw and _norm_source_file form because new_chunks may carry
     # absolute win32 paths while the stored graph keeps relative posix (#1007).
-    _replace_root = str(Path(root).resolve()) if root is not None else None
+    _replace_root = _eff_root
     new_sources: set[str] = set()
     for ch in new_chunks:
         for n in ch.get("nodes", []):
@@ -691,23 +817,46 @@ def build_merge(
     all_chunks = base + list(new_chunks)
     G = build(all_chunks, directed=directed, dedup=dedup, dedup_llm_backend=dedup_llm_backend, root=root)
 
+    # Prune set for deleted source files — both the raw form (matches nodes that
+    # kept absolute source_file) and the normalised relative form (matches nodes
+    # relativised by _norm_source_file at build time). .resolve() (via _eff_root)
+    # handles symlinked roots and ".." / "./" segments so Path.relative_to()
+    # succeeds even when the scan root is a symlink. (#1007, #1571)
+    prune_set: set[str] = set()
+    for p in (prune_sources or []):
+        if not p:
+            continue
+        prune_set.add(p)
+        norm = _norm_source_file(p, _eff_root)
+        if norm:
+            prune_set.add(norm)
+
+    # Carry forward hyperedges from files that were neither re-extracted nor
+    # deleted (#1574). build() only sees the new chunks' hyperedges, so without
+    # this every --update collapses the graph's hyperedge set down to just the
+    # changed files'. Re-extracted files' prior hyperedges are dropped (their new
+    # version is already in G — replace-per-source, like nodes/edges); deleted
+    # files' are dropped via prune_set. id-dedup (attach_hyperedges) so a carried
+    # hyperedge never duplicates one the new chunks re-emitted. Mirrors watch.py,
+    # which already preserves existing hyperedges across a rebuild.
+    if existing_hyperedges:
+        carried = []
+        for he in existing_hyperedges:
+            if not isinstance(he, dict):
+                continue
+            sf = he.get("source_file")
+            norm = _norm_source_file(sf, _eff_root)
+            if sf in new_sources or norm in new_sources:
+                continue  # re-extracted — replaced by the new chunk's version
+            if sf in prune_set or norm in prune_set:
+                continue  # deleted — pruned
+            carried.append(he)
+        if carried:
+            from graphify.export import attach_hyperedges
+            attach_hyperedges(G, carried)
+
     # Prune nodes and edges from deleted source files
     if prune_sources:
-        # Build a set containing both the raw form (matches nodes that kept
-        # absolute source_file) and the normalised relative form (matches nodes
-        # that were relativised by _norm_source_file at build time).
-        # .resolve() handles symlinked roots and redundant ".." / "./" segments
-        # so Path.relative_to() succeeds even when the scan root is a symlink.
-        # (#1007: manifest absolute paths vs graph relative source_file mismatch)
-        _root_str = str(Path(root).resolve()) if root is not None else None
-        prune_set: set[str] = set()
-        for p in prune_sources:
-            if not p:
-                continue
-            prune_set.add(p)
-            norm = _norm_source_file(p, _root_str)
-            if norm:
-                prune_set.add(norm)
         to_remove = [
             n for n, d in G.nodes(data=True)
             if d.get("source_file") in prune_set

{graphifyy-0.9.2 → graphifyy-0.9.4}/graphify/cluster.py

@@ -83,6 +83,33 @@ _COHESION_SPLIT_THRESHOLD = 0.05 # re-split communities with cohesion below this
 _COHESION_SPLIT_MIN_SIZE = 50    # only cohesion-split if community has at least this many nodes
 
 
+def label_communities_by_hub(
+    G: nx.Graph, communities: dict[int, list[str]]
+) -> dict[int, str]:
+    """Deterministic, LLM-free community labels: name each community after its
+    highest-degree member — the structural hub — so a report reads ``auth`` /
+    ``log_action`` instead of ``Community 70``. Degree is measured on the full graph
+    ``G``; ties break by node id for run-to-run stability. A community whose members
+    are all absent from ``G`` falls back to ``Community {cid}``.
+
+    Used as the default (no-backend) labeler; an LLM naming pass, when configured,
+    overrides these with richer names.
+    """
+    labels: dict[int, str] = {}
+    for cid, members in communities.items():
+        present = [n for n in members if n in G]
+        if not present:
+            labels[cid] = f"Community {cid}"
+            continue
+        # highest degree wins; ties broken by node id (ascending) for determinism
+        hub = min(present, key=lambda n: (-G.degree(n), str(n)))
+        name = str(G.nodes[hub].get("label") or hub).strip()
+        if name.endswith("()"):
+            name = name[:-2]
+        labels[cid] = name or f"Community {cid}"
+    return labels
+
+
 def cluster(
     G: nx.Graph,
     resolution: float = 1.0,

{graphifyy-0.9.2 → graphifyy-0.9.4}/graphify/dedup.py

@@ -6,6 +6,7 @@ Jaro-Winkler verification → same-community boost → union-find merge.
 from __future__ import annotations
 import math
 import re
+import sys
 import unicodedata
 from collections import defaultdict
 
@@ -219,12 +220,29 @@ def deduplicate_entities(
     if len(nodes) <= 1:
         return nodes, edges
 
-    # Pre-deduplicate: keep first occurrence of each id
+    # Pre-deduplicate: keep first occurrence of each id.
+    # Warn when two nodes share an ID but originate from different source files —
+    # this indicates a cross-chunk ID collision (#1504) where silent data loss occurs.
     seen_ids: dict[str, dict] = {}
     for node in nodes:
         nid = node.get("id", "")
-        if nid and nid not in seen_ids:
+        if not nid:
+            continue
+        if nid not in seen_ids:
             seen_ids[nid] = node
+        else:
+            existing_sf = seen_ids[nid].get("source_file") or ""
+            new_sf = node.get("source_file") or ""
+            if existing_sf != new_sf:
+                print(
+                    f"[graphify] WARNING: node '{nid}' from '{new_sf}' collides with "
+                    f"node from '{existing_sf}' — the second node will be dropped. "
+                    f"This is a cross-chunk ID collision caused by two files with the "
+                    f"same name in different directories. To avoid data loss, run "
+                    f"'graphify extract' per subfolder and merge with "
+                    f"'graphify merge-graphs'.",
+                    file=sys.stderr,
+                )
     unique_nodes = list(seen_ids.values())
 
     if len(unique_nodes) <= 1:

{graphifyy-0.9.2 → graphifyy-0.9.4}/graphify/diagnostics.py

@@ -274,7 +274,13 @@ def _read_json_file(path: str | Path) -> dict[str, Any]:
 
     json_path = Path(path)
     check_graph_file_size_cap(json_path)
-    data = json.loads(json_path.read_text(encoding="utf-8"))
+    try:
+        data = json.loads(json_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        raise RuntimeError(
+            f"Cannot parse {json_path}: {exc}. "
+            "The file may be corrupted — re-run 'graphify extract'."
+        ) from exc
     if not isinstance(data, dict):
         raise ValueError("diagnostic input must be a JSON object")
     return data

{graphifyy-0.9.2 → graphifyy-0.9.4}/graphify/export.py

@@ -636,6 +636,7 @@ def to_html(
     community_labels: dict[int, str] | None = None,
     member_counts: dict[int, int] | None = None,
     node_limit: int | None = None,
+    learning_overlay: dict | None = None,
 ) -> None:
     """Generate an interactive vis.js HTML visualization of the graph.
 
@@ -678,7 +679,7 @@ def to_html(
             if raw_hyperedges:
                 remapped = []
                 for he in raw_hyperedges:
-                    he_members = he.get("nodes") or he.get("members") or []
+                    he_members = he.get("nodes", [])
                     comm_ids, seen = [], set()
                     for nid in he_members:
                         c = node_to_community.get(nid)
@@ -713,6 +714,21 @@ def to_html(
     max_deg = max(degree.values(), default=1) or 1
     max_mc = (max(member_counts.values(), default=1) or 1) if member_counts else 1
 
+    # Work-memory overlay (derived sidecar). When not passed explicitly, load it
+    # best-effort from the sibling .graphify_learning.json next to the output
+    # graph.html (which lives beside graph.json). Empty/missing => no learning
+    # fields, so the un-annotated render is byte-identical to pre-feature.
+    if learning_overlay is None:
+        learning_overlay = {}
+        try:
+            from graphify.reflect import load_learning_overlay as _llo
+            learning_overlay = _llo(Path(output_path))
+        except Exception:
+            learning_overlay = {}
+    # Status -> ring color. preferred=green, contested=amber. Tentative gets no
+    # ring (it's not yet trustworthy enough to highlight in the map).
+    _RING = {"preferred": "#22c55e", "contested": "#f59e0b"}
+
     # Build nodes list for vis.js
     vis_nodes = []
     for node_id, data in G.nodes(data=True):
@@ -728,7 +744,7 @@ def to_html(
             size = 10 + 30 * (deg / max_deg)
             # Only show label for high-degree nodes by default; others show on hover
             font_size = 12 if deg >= max_deg * 0.15 else 0
-        vis_nodes.append({
+        node = {
             "id": node_id,
             "label": label,
             "color": {"background": color, "border": color, "highlight": {"background": "#ffffff", "border": color}},
@@ -740,7 +756,38 @@ def to_html(
             "source_file": sanitize_label(str(data.get("source_file") or "")),
             "file_type": data.get("file_type", ""),
             "degree": deg,
-        })
+        }
+        # Conditional learning fields — only present for annotated nodes, so
+        # un-annotated output keeps the exact pre-feature node dict shape.
+        entry = learning_overlay.get(str(node_id)) if learning_overlay else None
+        if entry:
+            status = sanitize_label(str(entry.get("status", "")))
+            stale = bool(entry.get("stale"))
+            node["learning_status"] = status
+            node["learning_stale"] = stale
+            ring = _RING.get(status)
+            if ring:
+                # Status-colored ring via the border; stale => desaturated +
+                # dashed (vis.js supports per-node `shapeProperties.borderDashes`).
+                if stale:
+                    ring = "#9ca3af"
+                    node["shapeProperties"] = {"borderDashes": [4, 4]}
+                node["borderWidth"] = 3
+                node["color"] = {
+                    "background": color, "border": ring,
+                    "highlight": {"background": "#ffffff", "border": ring},
+                }
+            # Lesson line appended to the hover title.
+            if status == "contested":
+                lesson = f"Lesson: contested (useful {entry.get('uses', 0)} / dead-end {entry.get('neg', 0)})"
+            elif status == "preferred":
+                lesson = f"Lesson: preferred source ({entry.get('uses', 0)} useful, score={entry.get('score', 0)})"
+            else:
+                lesson = f"Lesson: {status} ({entry.get('uses', 0)} useful)"
+            if stale:
+                lesson += " [code changed — re-verify]"
+            node["title"] = _html.escape(label) + "\n" + _html.escape(sanitize_label(lesson))
+        vis_nodes.append(node)
 
     # Build edges list. Restore original edge direction from _src/_tgt
     # (stashed by build.py for exactly this reason): undirected NetworkX