Skip to content

feat(wiki): link god-node key concepts in community articles & normalize Windows paths - #3080

Open
sravanjcov wants to merge 2 commits into
Graphify-Labs:v8from
sravanjcov:feat/wiki-key-concept-links-and-path-normalization
Open

feat(wiki): link god-node key concepts in community articles & normalize Windows paths#3080
sravanjcov wants to merge 2 commits into
Graphify-Labs:v8from
sravanjcov:feat/wiki-key-concept-links-and-path-normalization

Conversation

@sravanjcov

Copy link
Copy Markdown

What this PR does

Two small, non-breaking improvements to `graphify/wiki.py`:

### 1. Link god-node key concepts in community articles
Community articles list "Key Concepts" — the highest-degree nodes in that community.
Previously these were always rendered as bold plain text (`**parse**`), even when the
node had a dedicated god-node article (`parse.md`).

Now, if the node has an article in the resolver, it renders as a clickable link:
`**[parse](parse.md)**`. Nodes without an article remain plain bold text — no dead
links are created. Uses the existing `_md_link`/resolver pattern already used for
cross-community links and the navigation footer.

### 2. Normalize Windows backslash paths in wiki articles
`source_file` attributes can contain Windows-style backslashes (`src\parser\main.py`)
when graphify runs on Windows. These were emitted verbatim into backtick-quoted paths
in community and god-node articles, rendering inconsistently on GitHub/GitLab/web.

Now normalized to forward slashes (`src/parser/main.py`) at render time. The graph
data (`graph.json`, node attributes) is untouched — normalization happens only in
the markdown output layer.

## What is NOT changed
- No changes to the core pipeline (`detect`, `extract`, `build`, `cluster`)
- No changes to `graph.json`, node IDs, or any cached data
- `wiki.py` is a downstream export-only module — it reads the graph read-only

## Tests
- `test_community_article_links_god_node_key_concept` — verifies god nodes link, non-god-nodes stay plain text
- `test_wiki_normalizes_windows_backslashes_in_sources` — verifies `\` → `/` in both article types
- All 33 existing tests pass unchanged

…alize Windows paths

Community articles now link Key Concepts entries to their god-node article when one exists, using the existing _md_link/resolver pattern. Nodes without an article remain plain bold text (no dead links).

Source file paths containing Windows backslashes are normalized to forward slashes in both community and god-node articles, so markdown renders consistently across platforms.

Tests: test_community_article_links_god_node_key_concept, test_wiki_normalizes_windows_backslashes_in_sources

@graphify-labs graphify-labs Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graphify reviewed this change.

Worth a look — the grounded gate found no coupling regressions or blocking issues, but 3 advisory finding(s) below merit a look before merge.

Formal verification. 1 change(s) alter behavior, breaking input(s) attached.

Behavior changes: \_community\_article changes behavior, here is the input that shows it.

The verifier found a concrete input on which \_community\_article behaves differently before and after the change. If that change is intended, ship it; if not, this is your bug.

Guarantee: This difference was REPRODUCED, the verifier actually ran both versions on that input and saw them disagree. It is real, not an artifact.

Evidence: On input \{"G":"\(lambda \_g: \(\_g\.add\_nodes\_from\(\[\(1, \{\}\), \(2, \{\}\), \(3, \{\}\)\]\), \_g\.add\_edges\_from\(\[\(1, 2, \{\}\), \(1, 3, \{\}\), \(2, 3, \{\}\)\]\), \_g\)\[\-1\]\)\(\_\_import\_\_\('networkx'\)\.Graph\(\)\)","cid":"''","nodes":"\[1, 2, 3\]","label":"'h\\u00e9llo w\\u00f6rld'","labels":"\{'a': 1, 'b': 2\}","cohesion":"100\.0","node\_community":"\{'a': None\}","resolver":"\{'a':…, the old code produced '\# héllo wörld\\n\\n\> 3 nodes · cohesion 100\.00\\n\\n\#\# Key Concepts\\n\\n\- \*\*1\*\* \(2 connections\)\\n\- \*\*2\*\* \(2 connections\)\\n\- \*\*3\*\* \(2 connections\)\\n\\n\#\# Relationships… but the new code produces raises AttributeError. Paste that input straight into a regression test.


Graphify review — findings

Normalizes Windows-style backslashes in source_file paths to forward slashes across community and god node articles (_community_article, _god_node_article), so displayed source paths render consistently regardless of platform. Links a community article's top "Key Concepts" nodes to their own god node articles via _md_link when one exists, leaving non-god-node concepts as plain bold text. Adds tests covering the god-node linking behaviour and the backslash normalization.

Worth a look

  • source_file now must be a str instead of any path-like/renderable valuegraphify/wiki.py:137 · Escalate · medium
    • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review
  • Key Concepts links every node to a god-node file even when no such article existsgraphify/wiki.py:154 · Escalate · medium
    • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review
  • Unescaped node label can inject a markdown javascript linkgraphify/wiki.py:154 · Escalate · medium
    • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review
Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 240 functions depend on the 72 functions this change touches.

Health — this change adds coupling hotspots:

  • new: to_wiki() — 43 callers, 7 callees
  • new: dispatch_command() — 2 callers, 122 callees
  • new: test_poisoned_manifest_is_healed() — 0 callers, 6 callees

Verification — 240 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

  • verification_scope: 90 function(s) in the blast radius were not formally verified this run

Formal verification

Behavior changes: \_community\_article changes behavior, here is the input that shows it.

The verifier found a concrete input on which \_community\_article behaves differently before and after the change. If that change is intended, ship it; if not, this is your bug.

Guarantee: This difference was REPRODUCED, the verifier actually ran both versions on that input and saw them disagree. It is real, not an artifact.

Evidence: On input \{"G":"\(lambda \_g: \(\_g\.add\_nodes\_from\(\[\(1, \{\}\), \(2, \{\}\), \(3, \{\}\)\]\), \_g\.add\_edges\_from\(\[\(1, 2, \{\}\), \(1, 3, \{\}\), \(2, 3, \{\}\)\]\), \_g\)\[\-1\]\)\(\_\_import\_\_\('networkx'\)\.Graph\(\)\)","cid":"''","nodes":"\[1, 2, 3\]","label":"'h\\u00e9llo w\\u00f6rld'","labels":"\{'a': 1, 'b': 2\}","cohesion":"100\.0","node\_community":"\{'a': None\}","resolver":"\{'a':…, the old code produced '\# héllo wörld\\n\\n\> 3 nodes · cohesion 100\.00\\n\\n\#\# Key Concepts\\n\\n\- \*\*1\*\* \(2 connections\)\\n\- \*\*2\*\* \(2 connections\)\\n\- \*\*3\*\* \(2 connections\)\\n\\n\#\# Relationships… but the new code produces raises AttributeError. Paste that input straight into a regression test.

Could not verify: Could not verify \_god\_node\_article.

The verifier did not have enough to check \_god\_node\_article, so it is saying so rather than guessing. No false assurance is the whole point.

Guarantee: No guarantee either way, this is an honest abstention, not a pass.

Note: Reason: non-vacuity: domain too small (only 2 distinct inputs exercised, need 3) — 'no divergence' would be near-vacuous

· 3 more finding(s) on lines outside this diff (see the check run).

… precise node-ID mapping, and markdown escaping
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant