fix: preserve semantic layer, stamp hyperedges, PHP namespaces, ignore diagnostic (#1925 #1920 #1923 #1922)

- #1925: a missing manifest.json no longer degrades `extract --code-only`
  into a full scan that discards the committed semantic layer. An existing
  graph.json is a sufficient incremental baseline (detect_incremental treats
  an absent manifest as "all new / none deleted"), so out-of-scope doc/paper/
  image nodes are preserved while genuinely deleted sources still evict.
- #1920: _stamped_manifest_files now counts hyperedge output, so a doc whose
  only chunk output is a hyperedge is stamped instead of re-extracted forever.
- #1923: new namespace/use-aware PHP resolver (mirrors the Java resolver, runs
  before the unique-name rewire) so App\Models\Page and an imported
  Filament\Pages\Page stay distinct — no more false inherits/imports edge.
- #1922: detect() records ignored files/dirs in a new `ignored` diagnostic
  field (the nested-ignore scoping bug itself shipped in 0.9.16 / #1873).

Regression tests added for each; full suite 3325 passed, 3 skipped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: safishamsi

CHANGELOG.md

@@ -4,6 +4,10 @@ Full release notes with details on each version: [GitHub Releases](https://githu
 
 ## 0.9.17 (unreleased)
 
+- Fix: a missing `manifest.json` no longer degrades `graphify extract --code-only` into a full scan that discards the committed semantic layer (#1925). On a fresh clone (or when the manifest is deliberately untracked because its mtimes churn), the incremental gate required both `manifest.json` and `graph.json`; with only the graph present it fell to a full scan, and under `--code-only` that dropped every doc/paper/image node — silently replacing a curated graph with an AST-only skeleton. An existing `graph.json` is now a sufficient incremental baseline: `detect_incremental` already treats an absent manifest as "everything new / nothing deleted", so `build_merge` + `_stale_graph_sources` preserve files that are merely out of this run's scope while still evicting genuinely deleted sources.
+- Fix: hyperedge-only documents are now stamped in the manifest instead of being re-extracted on every run (#1920). `_stamped_manifest_files` (#1897) decided a semantic doc "produced output" by inspecting only `nodes` and `edges`, never `hyperedges`, so a chunk whose only output for a doc was a hyperedge (3+ nodes sharing a concept) left that doc unstamped and perpetually re-queued. Stamping now counts hyperedge output too, mirroring the per-`source_file` keying the semantic cache already uses.
+- Fix: the PHP extractor now disambiguates same-named classes across namespaces (#1923). A bare class reference (`extends Page`) collapsed onto the only internal class named `Page`, so `App\Models\Page` and an imported `Filament\Pages\Page` fused into one node, manufacturing a false `inherits`/`imports` edge and a bogus cross-community bridge. A new namespace/`use`-aware resolution pass (mirroring the Java resolver, running before the unique-name rewire) re-points supertype/import references to the real definition, or parks provably-external ones on a fully-qualified stub the bare-name rewire cannot collapse. Plain, non-namespaced PHP is unchanged.
+- Fix: `detect()` now records files and directories dropped by a `.gitignore`/`.graphifyignore` rule in a new `ignored` diagnostic field (#1922). The nested-ignore scoping bug itself was fixed in 0.9.16 (#1873); this closes the remaining gap where an ignored path left no trace in any diagnostic, so an over-broad rule looked like a clean scan. Entries are per-directory where a subtree is pruned, keeping the list bounded.
 - Fix: `_semantic_id_remap` is now idempotent, so incremental rebuilds stop churning (#1917). When a file's canonical stem contained its own legacy stem as a prefix (parent dir name equals the file stem, e.g. `.claude/CLAUDE.md`, `docs/docs.md`), an already-migrated semantic node id re-matched the legacy branch and gained another stem segment on every build (`claude_x` -> `claude_claude_x` -> ...). Because `_origin` is persisted, every `graphify update` re-fed nodes through the remap, so the ids grew unboundedly and the `same_topology`/`same_graph`/`no_change` short-circuits never fired — rewriting `graph.json` and re-running clustering on every zero-delta update. The remap now skips an id that already carries its canonical stem (mirroring the `graph_has_legacy_ids` check), while a genuine one-time legacy migration still applies. (An already-corrupted graph needs one `graphify extract --force` to reset the grown ids.)
 - Perf: `graphify query` now scores the graph once per query instead of T+1 times for a T-term query (#1889 / #1918, thanks @Sirhan1). The per-term-guarantee (#1445) previously re-scored the whole graph once per token; `_score_query` now computes the combined ranking and each token's singleton winner in a single traversal, feeding `_pick_seeds` via `best_seed_by_term`. Behavior is preserved (verified byte-identical against the old per-term scoring across a differential fuzz); ~1.3-1.4x faster and independent of query length.
 

graphify/cli.py

@@ -65,11 +65,18 @@ def _stamped_manifest_files(
     empty so detect_incremental re-queues them (#933).
 
     Both sides of the membership test are resolved against the scan ``root``
-    before comparing (#1897): node/edge ``source_file`` values are
+    before comparing (#1897): node/edge/hyperedge ``source_file`` values are
     root-relative on a fresh extraction while ``files_by_type`` entries are
     absolute (from detect()), so a raw string comparison never matched and
     every freshly-extracted semantic doc was dropped from the manifest.
     Mirrors the #1890 path normalization in graphify.llm.
+
+    Hyperedges are counted as output (#1920): a chunk whose only result for a
+    document is a hyperedge (3+ nodes sharing a concept) is valid output that
+    the semantic cache persists per-``source_file`` — omitting it here left the
+    doc unstamped, so detect_incremental re-queued it on every run. The stamping
+    condition mirrors the cache-write keying (a hyperedge carries its own
+    ``source_file``); do not derive it from member nodes.
     """
     root = Path(root)
 
@@ -83,7 +90,7 @@ def _resolve(value: str) -> Path:
             return p
 
     sem_extracted: set[Path] = set()
-    for coll in ("nodes", "edges"):
+    for coll in ("nodes", "edges", "hyperedges"):
         for item in sem_result.get(coll, []):
             sf = item.get("source_file", "")
             if sf:
@@ -2281,12 +2288,26 @@ def _parse_float(name: str, raw: str) -> float:
         )
         manifest_path = graphify_out / "manifest.json"
         existing_graph_path = graphify_out / "graph.json"
-        incremental_mode = manifest_path.exists() and existing_graph_path.exists() if has_path else False
+        # #1925: a missing manifest.json must not degrade to a full scan that
+        # discards the existing graph's semantic layer. An existing graph.json
+        # is a sufficient incremental baseline: detect_incremental treats an
+        # absent manifest as "everything is new" (re-extract all, nothing
+        # deleted), and build_merge + _stale_graph_sources reconcile replaced
+        # and genuinely-deleted sources against the current corpus, so doc/
+        # paper/image nodes survive a --code-only rebuild instead of being
+        # dropped with the rest of the committed graph.
+        incremental_mode = existing_graph_path.exists() if has_path else False
         # --force: full scan, not the manifest-gated incremental diff — a warm
         # unchanged tree would otherwise dispatch zero files (#1894).
         incremental_mode = incremental_mode and not force
         if force:
             print("[graphify extract] --force: full re-scan, semantic cache reads skipped")
+        elif incremental_mode and not manifest_path.exists():
+            print(
+                "[graphify extract] manifest.json missing; using existing "
+                "graph.json as the incremental baseline (all files re-checked; "
+                "nodes for files outside this run's scope are preserved)"
+            )
 
         if not has_path:
             code_files = []

graphify/detect.py

@@ -1151,6 +1151,11 @@ def _wc(path: Path) -> int:
 
     skipped_sensitive: list[str] = []
     unclassified: list[str] = []
+    # Files/dirs dropped by a .gitignore/.graphifyignore rule. Recorded so an
+    # over-broad ignore (or a legitimately-ignored subtree) is visible instead
+    # of silently vanishing from the graph (#1922). Directory-level entries keep
+    # this bounded — a pruned `data/` is one entry, not one per contained file.
+    ignored: list[str] = []
     ignore_patterns = _load_graphifyignore(root)
     ignore_cache: dict[Path, bool] = {}  # shared across all _is_ignored calls in this scan
     # CLI --exclude patterns are anchored at the scan root and appended last
@@ -1222,11 +1227,15 @@ def _on_walk_error(err: OSError) -> None:
                 # any `!` rule existed — e.g. a single `!docs/**` made the walk descend
                 # bin/, obj/, wwwroot/, generated/, … : a pathological slowdown on large
                 # repos for no correctness gain.
-                dirnames[:] = [
-                    d for d in dirnames
-                    if not _is_noise_dir(d, dp)
-                    and not _is_ignored(dp / d, root, ignore_patterns, _cache=ignore_cache)
-                ]
+                kept_dirs: list[str] = []
+                for d in dirnames:
+                    if _is_noise_dir(d, dp):
+                        continue
+                    if _is_ignored(dp / d, root, ignore_patterns, _cache=ignore_cache):
+                        ignored.append(str(dp / d) + os.sep)
+                        continue
+                    kept_dirs.append(d)
+                dirnames[:] = kept_dirs
                 if follow_symlinks:
                     safe_dirs: list[str] = []
                     for d in dirnames:
@@ -1256,6 +1265,7 @@ def _on_walk_error(err: OSError) -> None:
             if str(p).startswith(str(converted_dir)):
                 continue
         if not in_memory and _is_ignored(p, root, ignore_patterns, _cache=ignore_cache):
+            ignored.append(str(p))
             continue
         if not _resolves_under_root(p, root):
             skipped_sensitive.append(str(p) + " [symlink target outside scan root]")
@@ -1338,6 +1348,7 @@ def _on_walk_error(err: OSError) -> None:
         "skipped_sensitive": skipped_sensitive,
         "unclassified": sorted(unclassified),
         "walk_errors": walk_errors,
+        "ignored": sorted(ignored),
         "graphifyignore_patterns": len(ignore_patterns),
         "scan_root": str(root.resolve()),
     }

graphify/extract.py

@@ -113,6 +113,7 @@
     _resolve_cross_file_java_imports,
     _resolve_export_target,
     _resolve_java_type_references,
+    _resolve_php_type_references,
     _resolve_js_import_path,
     _resolve_js_import_target,
     _resolve_js_module_path,
@@ -4581,6 +4582,22 @@ def extract(
     _merge_swift_extensions(per_file, all_nodes, all_edges)
     _disambiguate_colliding_node_ids(all_nodes, all_edges, all_raw_calls, root)
     _canonicalize_csharp_namespace_nodes(all_nodes, all_edges)
+    # PHP namespace/use disambiguation must run BEFORE the unique-stub rewire:
+    # the false merge (#1923) happens inside the rewire when a bare-name stub
+    # matches a unique internal class from a different namespace.
+    _php_exts = {".php", ".phtml", ".php3", ".php4", ".php5", ".php7", ".phps"}
+    _php_sel = [
+        (r, p) for r, p in zip(per_file, paths)
+        if p.suffix.lower() in _php_exts and not p.name.lower().endswith(".blade.php")
+    ]
+    if _php_sel:
+        try:
+            _resolve_php_type_references(
+                [r for r, _ in _php_sel], [p for _, p in _php_sel], all_nodes, all_edges
+            )
+        except Exception as exc:
+            import logging
+            logging.getLogger(__name__).warning("PHP type-reference resolution failed, skipping: %s", exc)
     _rewire_unique_stub_nodes(all_nodes, all_edges)
 
     # Add cross-file class-level edges (Python only - uses Python parser internally)