GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Visualizer builds no graph edges from absolute (bundle-relative) links — the form SPEC.md §5.1 recommends
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
**Summary.** `okf/SPEC.md` §5.1 says absolute (bundle-relative) links — targets beginning with `/`, resolved against the bundle root — are "the **recommended** form" for cross-linking concepts. But the reference visualizer's graph builder drops exactly those links, so a bundle that follows the spec's recommendation renders as a zero-edge graph (isolated nodes, empty backlinks panel).
**Where.** In `okf/src/reference_agent/viewer/generator.py`, `_extract_links` (line 54) skips external `://` URLs *and* any target starting with `/`:
```python
if "://" in target or target.startswith("/"):
continue
```
The front-end does the opposite: `static/viz.js` (`rewriteInternalLinks`, line 220) rewires exactly the `/….md` hrefs for in-viewer detail-panel navigation (`href.startsWith("/") && href.endsWith(".md")`). So with absolute links you get working panel navigation but no edges; the two components disagree about which link form is real.
**Why it's easy to miss.** All three sample bundles (`crypto_bitcoin`, `ga4`, `stackoverflow`) use relative links exclusively, so the shipped corpus never exercises the recommended form.
**Repro.** A minimal bundle of two concepts where `a.md` contains `[B](/b.md)`:
```
bundle/
├── a.md # frontmatter: type: Thing — body links [B](/b.md)
└── b.md # frontmatter: type: Thing
```
`python -m reference_agent visualize --bundle bundle/` → 2 nodes, 0 edges. Changing the link to `[B](./b.md)` produces the edge. (Observed in practice: a real ~80-concept bundle rendered 0 edges with absolute links and 494 edges once switched to relative.)
**Suggested fix.** When building edges, treat a leading-`/` target as bundle-root-relative: strip the slash and resolve to a concept id the same way `rewriteInternalLinks` already does client-side — plausibly a one-line change to the skip condition in `_extract_links`.
Happy to send a PR if that direction is acceptable.
Contributor guide
Research direction
Start in okf/src/reference_agent/viewer/generator.py at _extract_links, then compare its handling of bundle-relative targets with static/viz.js and rewriteInternalLinks. Reproduce with the two-concept bundle in the issue using `python -m reference_agent visualize --bundle bundle/`; done means `/b.md` produces a graph edge and the corresponding backlinks/navigation behavior remains working.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, python
- Domain
- data-visualization, frontend
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100