Skip to content

fix(wiki): let the file page and the code reach each other - #2091

Open
RaghavChamadiya wants to merge 1 commit into
mainfrom
fix/wiki-file-route-crossing
Open

fix(wiki): let the file page and the code reach each other#2091
RaghavChamadiya wants to merge 1 commit into
mainfrom
fix/wiki-file-route-crossing

Conversation

@RaghavChamadiya

Copy link
Copy Markdown
Member

The wiki and the file route documented the same file and could not reach each other

Two crossings, one of them missing and one of them dead.

The file route rendered a wiki body with no page list. files/[...path]/page.tsx
passed content and nothing else to WikiMarkdown, so every backticked path in the
embedded documentation was plain text. The docs reader has resolved those since the
path index shipped; the file page, where the reader is already looking at a file, did
not.

The cycle page said something untrue about test code. scc-620e46d9a910 on this
repo's own index is twenty files under tests/unit/ingestion/parser/, all reaching a
shared conftest.py. The page told the reader that "nothing in this group can be
loaded, tested or extracted without the rest of it", which describes a working pytest
tree as debt to pay down, and then offered to help break it.

The crossing

WikiMarkdown needs buildHref as well as pages, and a function cannot cross from
a server component into a client one, so this is a small client wrapper rather than
the one prop it looked like. It fetches the page list through the existing shared SWR
key instead of server-side: the list is repo-wide, and server-side it would ride the
flight payload of every file page. The tab mounts only when it is selected, and until
the list lands the paths render as plain code, exactly as before.

Refs route through the existing pageHref helper, not fileEntityPath. The path
index resolves a directory ref to its module page, and the file route calls
notFound() on a directory, so keying the href off "has a target_path" would have
turned seven dead text spans in this index into seven links to a 404. A wrong link is
worse than no link.

The cycle page

Before, on scc-620e46d9a910:

20 files import each other in a loop, directly or transitively. Nothing in this
group can be loaded, tested or extracted without the rest of it.

## Files in the cycle

                                        <- blank line between every bullet
- `tests/unit/ingestion/parser/_helpers.py`

- `tests/unit/ingestion/parser/conftest.py`
...                                     <- all 20, then all 20 again in the table

## Symbols defined in the cycle

### `tests/unit/ingestion/parser/_helpers.py`
                                        <- heading, nothing under it

**Total symbols in cycle:** 270
---                                     <- markdown reads this as a heading

After:

20 test files import each other in a loop, through the fixtures and helpers they
share. A test tree is built this way on purpose, so this is a cycle in the import
graph rather than debt to pay down.

**Cycle id:** `scc-620e46d9a910`

## The loop

- `tests/unit/ingestion/parser/_helpers.py` -> `tests/unit/ingestion/parser/conftest.py`
- `tests/unit/ingestion/parser/conftest.py` -> `tests/unit/ingestion/parser/test_cpp.py`

## What holds it together

Ranked by how many of the cycle's edges each file carries. The file at the top is the
shared fixture the rest import, so it is the one to read first to understand how this
suite is set up.

| File | Imports in cycle | Imported by | Total |
| --- | --- | --- | --- |
| `tests/unit/ingestion/parser/conftest.py` | 18 | 19 | 37 |
| `tests/unit/ingestion/parser/_helpers.py` | 1 | 18 | 19 |

**Total symbols in cycle:** 270

---

The member list is now printed once. It moved from the bullets to the ranking table,
which is the superset: the bullets were capped at 30 and the table never was, and the
table says how entangled each member is. The empty-bullet and empty-heading fixes are
in the assembler rather than the template, because that is where a blank name and a
file with nothing public are produced.

Nothing leaves the index

Page.content is one string that FTS5 indexes, the vector store embeds, get_context
returns verbatim and a reader reads, so a prettier page that drops tokens is a
regression. Measured on all 15 SCC pages in this repo's live index by rendering the
same reconstructed context through both templates and diffing the backticked tokens:
nothing is lost on any page. Member counts run 2 / 3 / 20 (min / median / max), so
the 30-bullet cap was never reached and the deleted list was pure duplication. The one
live case of the new empty-heading guard is _helpers.py, whose path still appears in
the table and on both sides of its loop edges.

Three of the fifteen summaries change, the three all-test cycles, because
_extract_summary reads the opening paragraph. It trades boilerplate that was
byte-identical across all fifteen summaries for test files, fixtures, helpers,
test tree, and stops asserting something false to get_answer.

What I did not do

I did not bump STRUCTURAL_GENERATION_VERSION. I started to, and then checked
what it reaches. _structural_scc_page passes no subject_hash, so
structural_content_hash returns "" and _structural_page stores no render key;
structural.py:600 says so directly ("an empty hash keeps them out of the
fingerprint-staleness sweep"). The bump therefore refreshes none of the pages this
change touches, while marking every stored file_page and symbol_spotlight stale
through structural_fingerprint and re-rendering 4,438 of them, in this repo alone,
to byte-identical output. All cost, no effect. Say the word if you want it anyway.

The "Open file page" link is unchanged. It shipped in #2082 and it works: the
door on a wiki file page reaches the file route, and this change completes the loop
back out of it. The dead-ref treatment was proposed for it (tertiary ink, accent on
hover only) and it currently renders in full accent. I left it alone. The comment
above it records deliberate decisions about its size and its position in the
provenance row, and the case for restyling is that it is the page's only action, not
that it is wrong. Worth a separate look, not a drive-by.

Gate

Clicked through on this repo's own index, against a local next dev build:

  • wiki file page, Open file page ->, lands on
    /repos/{id}/files/packages/cli/src/repowise/cli/helpers.py
  • that page's Documentation tab carries 39 resolved path links; clicking one lands on
    /repos/{id}/files/packages/cli/src/repowise/cli/output.py
  • no directory-shaped link in the body; the only ones on the page are the breadcrumb

The links read as ink: live refs take a 6% ground and primary ink with accent on hover
only, dead refs stay plain tertiary mono. In the "Depends on" section of that page,
.../cli/output.py is decorated and .../cli/errors.py and the __init__.py entries
are not, because there is no page behind them.

Tests

Each behaviour change has a test that fails on the baseline source, verified by
restoring the pre-change file and re-running, not by assumption:

  • a path in an embedded body becomes a link to that file's route
  • a directory ref goes to the docs reader, not to a 404
  • a path with no page behind it stays plain text
  • the members are named exactly once
  • no blank-line run and no leading newline, on a full, a bare and an all-test cycle
  • the delimiter row is followed by the first row, not by a blank line
  • an all-test cycle drops the untangle-this sentence and the "Where to break it" heading
  • a production cycle keeps both
  • the assembler drops an unnamed symbol, drops a file with nothing public, and flags a
    cycle whose members are all test files

packages/web/vitest.config.ts needed esbuild: { jsx: "automatic" }: the app's
tsconfig says jsx: preserve, which Vite cannot compile, so it fell back to the
classic transform and any component rendered from a test threw React is not defined.

tests/unit/generation      1546 passed
packages/ui                1575 passed (186 files)
packages/web                 87 passed (17 files)
ruff check                 All checks passed
tsc --noEmit (web)         clean

The file route embedded a wiki body with no page list, so every backticked
path in it rendered as dead text on the one surface where the reader is
already looking at a file. It now resolves them the way the docs reader
does, routing a file ref to the file route and a directory ref to its module
page rather than to a route that 404s on a directory.

The cycle page also read badly. Its members were bulleted once and then
listed again as ranking rows, every list was loose, a symbol with no name
printed a bare bullet, and a file with nothing public printed a heading with
nothing under it. And it told a reader that a group of test files sharing a
conftest "cannot be loaded, tested or extracted without the rest of it",
which describes a working test tree as debt. An all-test cycle now gets its
own sentence and its own heading.
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