Render: link and code-span attribute types, and use internal links more generally
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Idoneità per principianti
- 62/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Tranquilla
- Stack tecnologico
- go
- Ambito
- documentation
Direzione di ricerca
Inizia da markdown.go:309, in typeCell, quindi esamina la gestione di intestazioni e ancore utilizzata per il Markdown renderizzato; mermaid.go:104-108 spiega perché gli attributi vengono omessi dall'output Mermaid. Confronta i file generati in docs/05-parking-garage/ e examples/ con i rispettivi goldens. Il lavoro è completato quando i riferimenti ai tipi usano link interni stabili e code span in modo coerente, i test fissano lo schema delle ancore e i goldens sono aggiornati.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Found while reviewing #37 (renderer hardening). Not a bug and not a security issue — #37 closes the escaping hole, so a hostile type string is already rendered as text. This is about the Markdown being more useful to read.
The concrete case: attributes[].type
attributes[].type renders in exactly one place: the Markdown attribute table's Type column, markdown.go:309 via typeCell. The Mermaid ER never sees it — it deliberately omits attributes, since freeform conceptual types like enum[active, archived] aren't valid erDiagram attribute types (mermaid.go:104-108).
typeCell has two branches: a scope.Name whose scope is a bound import becomes a link; everything else falls through to mdCell as plain prose. So the same column renders three ways:
| `holderName` | string |
| `status` | AccountStatus |
| `paidWith` | [payments.PaymentMethod](./payments.modelith.md#paymentmethod) |
Two things are worth changing.
A local enum type isn't linked, but a cross-model one is. That is backwards from what a reader expects. In docs/05-parking-garage/garage.modelith.md, AccountStatus is defined 30 lines above under ### + backticked name, which already generates the anchor #accountstatus. Nothing uses it:
$ grep -c '](#' docs/05-parking-garage/garage.modelith.md
0
The document has anchors and no internal links to them. Meanwhile a type pointing at another file gets a working link.
The type is the only identifier the renderer doesn't code-span. Attribute names, enum value names, action names, actor names, import scopes and paths all go through codeSpan. The enum's own definition heading is code-spanned. The type cell referencing that enum is bare, so one table row has a code-spanned name sitting next to a bare type.
Target:
| `status` | [`AccountStatus`](#accountstatus) |
| `paidWith` | [`payments.PaymentMethod`](./payments.modelith.md#paymentmethod) |
A code span nests inside a link label in GFM, so both cases can render consistently rather than diverging.
The broader theme
The rendered Markdown has more anchors than it uses. Other candidates, roughly in order of how obviously useful they are:
- A relationship's
entity:— link to that entity's section. - An action's
preserves:and a scenario'sinvariants_touched:— link to the invariant they name. These are already id references the linter resolves, so the target is known to be valid. - Backticked entity and glossary terms in prose —
lintalready resolves these for its backticked-term check, so the renderer could link what the linter already matched. This one is the largest and most likely to look noisy; worth prototyping before committing.
The principle: where the linter already resolves a reference, the renderer usually knows enough to link it.
Notes for whoever picks this up
- Do it when
typeCellis already open. Cross-model imports slice 2 (vendoring, ADR-0010) touches that function for vendored-model links; folding this in there avoids churning the goldens twice. - Goldens will churn across every attribute row in
examples/anddocs/05-parking-garage/. - Anchor generation depends on the renderer's heading format, so a test should pin the anchor scheme rather than assuming GitHub's slugging stays put.
- Deliberately kept out of #37, which is a security fix — a presentation change riding along would have made that diff harder to review.
🤖 Filed by Claude Code
- Lingua principale
- Go
- Stelle
- 32
- Fork
- 5
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di stacklok/modelith
-
enhancement
Difficoltà 2/5 Mezza giornata Idoneità per principianti 68/100
-
Difficoltà 4/5 3-5 giorni Idoneità per principianti 35/100
-
Difficoltà 5/5 Più di una settimana Idoneità per principianti 28/100
-
documentation
Difficoltà 5/5 Più di una settimana Idoneità per principianti 30/100
-
Difficoltà 3/5 1-2 giorni Idoneità per principianti 58/100
Tutte le issue di stacklok/modelith
Issue simili
-
kind/bug needs-triage
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 72/100
matrixorigin/matrixone#29223 ·
-
needs-acceptance wg/data-plane-networking
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
vllm-project/semantic-router#4024 · 1 commento ·
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
-
bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 86/100
alexgorbatchev/dotfiles#107 ·
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 84/100