suggest_questions() isolated-node count (757) disagrees with report.py Knowledge Gaps count (245) — inflated by rationale/JSON-leaf/TS-Props nodes

[Riaan180390]

Summary

suggest_questions()'s "isolated/weakly-connected nodes" question overcounts by ~3x compared to the report's own "Knowledge Gaps" section, because it's missing filters that report.py already applies. The inflated number makes a healthy graph look like it has a major documentation/connectivity problem when it doesn't.

Where

• graphify/analyze.py, suggest_questions(), the "Isolated or weakly-connected nodes" block (~line 504):

  isolated = [
      n for n in G.nodes()
      if G.degree(n) <= 1 and not _is_file_node(G, n) and not _is_concept_node(G, n)
  ]

• graphify/report.py's "Knowledge Gaps" section (~line 237) does the same computation but adds one more filter:

  isolated = [
      n for n in G.nodes()
      if G.degree(n) <= 1
      and not _is_file_node(G, n)
      and not _is_concept_node(G, n)
      and G.nodes[n].get("file_type") != "rationale"
  ]

Repro

On a 2213-node / 4862-edge real-world graph (Python + TS/React monorepo), the two computations disagree:

• suggest_questions() count (no rationale exclusion): 757
• report.py "Knowledge Gaps" count (with rationale exclusion): 245

Both appear in the same generated report (GRAPH_REPORT.md) — the Suggested Questions section says "757 weakly-connected nodes found — possible documentation gaps," while the Knowledge Gaps section a few paragraphs earlier says 245, for what's presented as the same concept. That's an internal inconsistency a reader will notice.

Root cause of the inflation

I broke down the 757 by file_type:

file_type	count	%	is it a real gap?
rationale	512	68%	No — these are auto-extracted docstring/comment nodes attached to their parent symbol by exactly one edge (e.g. a node whose label is the first line of a function's docstring). Degree=1 is the intended shape for these, not a missing edge.
code (JSON leaves)	86	11%	No — scalar values in JSON config trees (e.g. shadcn's components.json: $schema, rsc, baseColor, cssVariables). Same "single parent edge by construction" pattern as _JSON_NOISE_LABELS already tries to filter for package.json, but that noise list doesn't cover other config schemas.
code (TS Props interfaces)	~130	17%	No — single-use React/TypeScript prop-type interfaces declared immediately above the one component that uses them (FlowProps, TopBarProps, BottomPanelProps, etc.). Idiomatic single-use types, not undocumented code.
everything else	~29	4%	plausible real gaps

So even the smaller, "already filtered" 245 count from report.py still isn't clean — it doesn't exclude JSON config leaves or single-use TS prop interfaces, both of which are structural/idiomatic patterns rather than architectural gaps.

Suggested fix

1. Add the same file_type != "rationale" filter to suggest_questions()'s isolated-node computation so it doesn't disagree with report.py.
2. Extend the JSON-leaf exclusion (currently _is_json_key_node + _JSON_NOISE_LABELS, scoped to package-manager-style keys) to catch degree-1 leaves in any JSON file — the label being a leaf value under a JSON source with degree ≤1 is a strong enough signal regardless of which specific JSON schema it is.
3. Consider a heuristic for single-use TS/JS *Props/*Options/*Config interfaces (declared in the same file as, and only referenced by, one consumer) — these are idiomatic and shouldn't count toward "knowledge gaps" either.

Happy to share the exact reproduction script (loads graph.json, replicates both filters) if useful — got exact parity with both 757 and 245 by hand-rolling the same predicates.

[Riaan180390]

Follow-up: cohesion_score() has the same rationale-node skew

Same root cause as the isolated-node count above, but hitting a different metric: cluster.py's cohesion_score() (density = actual_internal_edges / (n·(n-1)/2)) is also inflated-in-reverse by rationale nodes, which makes well-scoped communities look artificially "weakly interconnected" and get flagged by the suggest_questions() low-cohesion check (score < 0.15 and len(nodes) >= 5).

Concrete example from the same graph: community 0 ("Data Cache & API Tests") — 65 nodes spanning exactly two files, src/data/cache.py and its matching tests/test_cache.py. Reported cohesion: 0.0524, which triggered the "Should Data Cache & API Tests be split into smaller, more focused modules?" suggested question.

Breakdown:

• 21 of the 65 nodes (32%) are rationale-typed docstring nodes (degree 1 by construction — same as issue body above). Excluding them: n=44, edges=88, density=0.093 — nearly double, but still under the 0.15 threshold.
• The remaining "low" density is itself structural, not a code smell: the community is one Cache class with five parallel, mutually-independent get_X()/set_X() accessor pairs (prices, financial metrics, line items, insider trades, company news), mirrored by five independent Test*Cache classes. None of those branches are supposed to connect to each other — get_prices() has no reason to share an edge with get_financial_metrics(). A density metric penalizes exactly this "hub + N independent parallel branches" shape regardless of code quality.

Net effect: a single, disciplined, well-tested module (one class, one matching test file, 1:1 coverage) gets flagged as a splitting candidate, when the real culprits are (a) docstring-node padding inflating n without adding edges, and (b) density being a poor proxy for "should this be split" when a module is intentionally a flat set of parallel, independent operations.

Suggested fix: same as above — exclude file_type == "rationale" nodes from cohesion_score()'s community_nodes input (or from n/possible entirely) before computing density, matching the exclusion report.py already does for the isolated-node count. Might also be worth noting in the low-cohesion suggested-question text that low density can reflect "several independent parallel concerns in one file" rather than "tangled code," since those read very differently to someone acting on the suggestion.