GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Visualizer builds no graph edges from absolute (bundle-relative) links — the form SPEC.md §5.1 recommends

Open Beginner friendly
#201 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.