From 8a49e1f38a59ac5bb93fadff059d60c3612d189c Mon Sep 17 00:00:00 2001
From: ayushcodes10 <ayushcodes10@gmail.com>
Date: Fri, 25 Sep 2026 17:25:08 +0530
Subject: [PATCH] Gate the undocumented components reason on a real semantic
 layer

GRAPH_REPORT.md's Knowledge Gaps section always offered undocumented
components as a possible explanation for an isolated node, regardless
of whether the graph could ever actually have one. That phrase only
means anything when a semantic layer exists, document, paper or image
nodes an LLM extracted meaning from, where an isolated node genuinely
could be mentioned but never explained further. A code only graph has
no such nodes at all, so offering it as a live possibility on every
report is misleading.

The reason now checks whether any node in the graph carries a
document, paper or image file_type before including that clause,
using the same VALID_FILE_TYPES distinction validate.py already
draws between the semantic layer and code/rationale/concept nodes, so
no new build time flag is needed.

Fixes issue 3801.
---
 graphify/report.py | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/graphify/report.py b/graphify/report.py
index ac854a2e6..65e1ffada 100644
--- a/graphify/report.py
+++ b/graphify/report.py
@@ -335,8 +335,23 @@ def generate(
             suffix = f" (+{len(isolated)-5} more)" if len(isolated) > 5 else ""
             raw_isolated = sum(1 for n in G.nodes() if G.degree(n) <= 1)
             lines.append(f"- **{len(isolated)} isolated node(s):** {', '.join(f'`{l}`' for l in isolated_labels)}{suffix}")
+            # "Undocumented components" only means anything when a semantic
+            # layer exists: document/paper/image nodes an LLM extracted
+            # meaning from, where an isolated node genuinely could be
+            # "mentioned but never explained further." A code-only graph
+            # (--code-only, or any run where semantic extraction never
+            # happened) has no such nodes at all, so offering it as a live
+            # possibility on every report is misleading (#3801).
+            has_semantic_layer = any(
+                G.nodes[n].get("file_type") in ("document", "paper", "image")
+                for n in G.nodes()
+            )
+            reason = (
+                "possible missing edges or undocumented components" if has_semantic_layer
+                else "possible missing edges"
+            )
             lines.append(
-                "  These have ≤1 connection - possible missing edges or undocumented components. "
+                f"  These have ≤1 connection - {reason}. "
                 f"(Counts symbols only; {raw_isolated} node(s) total have ≤1 connection when "
                 "file, concept and rationale nodes are included.)"
             )