Redesign ASTRA referencing around a unified path grammar#8
Open
EiffL wants to merge 7 commits into
Open
Conversation
Replace the per-kind directives/roles and the dotted anchor grammar with a
single slash-path grammar that mirrors astra.yaml, addressed by one {astra}
role (inline) and one {astra} directive (block) — the MyST way — plus
colon-namespaced variants and a native #astra: cross-reference scheme.
- new src/path.ts: parse/resolve the unified grammar (collections, scope
steps, option/evidence children, registries, leading-/ and ../)
- {astra} directive renders elements, children, whole collections
(registries), and bare sub-analyses; options label/caption/compact/
show/hide/universe/class
- {astra} role is store-driven; {astra:num} emits a native numref
crossReference; {astra:cite}/{astra:cite:t} emit MyST citations from DOI
evidence; {astra:value} reads a table cell, metric, or decision selection
- #astra:<path> links resolve to crossReferences / cross-page links and
 figure embeds, page-relative with ../ support
- account for ASTRA dropping the narrative section (no card summaries,
no #narrative anchors)
- rewrite README authoring docs; add design_proposal.md
- rewrite test suites + add tests/path.test.ts (105 tests pass)
Signed-off-by: Francois Lanusse <fr.eiffel@gmail.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- resolveInlineRef: drop a redundant resolveScope for bare sub-analysis
references (the caller already resolved into the sub; read its name)
- universes/<id>: resolve the universe once in the directive instead of
re-resolving inside renderElement
- renderUniverse: build the table with the ast-helpers constructors
- extract renderDecisionBlock to dedupe the decision render in element +
registry paths
- cache slugParts on Scope, removing repeated slug.split('/')
- parseAstraPath: read the analyses branch left-to-right
No behavior change; 105 tests pass.
Signed-off-by: Francois Lanusse <fr.eiffel@gmail.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
MyST's reference resolver fills the number/label for `link` nodes during its
own pipeline but leaves plugin-injected `crossReference` nodes unresolved
(LaTeX `\ref{undefined}`, no figure number). Found while porting the DESI DR1
example: every {astra:num} and #astra: in-page reference rendered undefined.
Emit `link` nodes (url `#<identifier>`) instead so MyST resolves them natively:
- {astra:num} role → link (empty/%s text filled by MyST as "Figure N")
- the #astra: anchor transform's in-page verdict → link to #<identifier>
Tests updated to assert the link form; 105 pass. Verified against the example:
numbered figure/table references now resolve.
Signed-off-by: Francois Lanusse <fr.eiffel@gmail.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Match MyST's actual role name ({numref}) rather than inventing a `num`
abbreviation — the redesign's whole premise is to mirror MyST conventions, and
unlike cite:p/cite:t (which abbreviate nothing) `num` shortens the established
full name for no benefit.
Signed-off-by: Francois Lanusse <fr.eiffel@gmail.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bump from 0.0.3 to the latest 0.0.5. The narrative section was removed from ASTRA in this range, so the SDK no longer exports the narrative validators (validateNarrativeAnchors, checkNarrativeCoverage, validateNarrativeSections); drop them from loader validation (MySTRA was already narrative-free). Typecheck clean, 105 tests pass. Signed-off-by: Francois Lanusse <fr.eiffel@gmail.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…depth)
- The resolved-store carrier set a fixed `astra-store` identifier on every
page, colliding across the project ("Duplicate identifier"). It's selected by
its `.astra-store` class, so drop the identifier.
- Decisions rendered as h4; placed under a typical `## ` section that skips a
level (MyST "missing heading depth 3"). Render at h3 — contiguous, and the
same level findings already use.
105 tests pass; the DESI example now builds warning-free.
Signed-off-by: Francois Lanusse <fr.eiffel@gmail.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The rich theme locates the resolved-store carrier by its `astra-store` identifier; dropping it (to silence the advisory "Duplicate identifier in project" warning) left the theme with no store to join, so inline hover preview cards stopped rendering. The identifier is load-bearing — restore it and keep the (benign, always-present) duplicate-identifier warning. The decision heading-depth fix from the same batch is unrelated and retained. Signed-off-by: Francois Lanusse <fr.eiffel@gmail.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Redesigns how authors reference ASTRA components, from the ground up, to follow standard MyST conventions for roles and directives. Replaces the previous per-kind directives/roles (
{astra:decision},:::{astra:output}, …) and the separate dotted anchor grammar ([](#outputs.x)) with a single slash-path grammar that mirrorsastra.yaml, addressed by one{astra}role (inline) and one{astra}directive (block) — the same way MyST reuses{math}as both.Design rationale and full authoring docs: see
design_proposal.mdand the rewritten Authoring section of the README.The model
A path is a slash route through the analysis tree (the
astra.yamlstructure):{astra}`outputs/hubble_diagram`(+<text>display override):::{astra} outputs/hubble_diagram :::{astra:num}(nativenumref),{astra:cite}/{astra:cite:t}(citations from DOI evidence),{astra:value}(live number / decision selection)[](#astra:outputs/x),,:::{figure} #astra:outputs/x :::What changed
src/path.ts— parses/resolves the unified grammar (collections, scope steps, option/evidence children, registries, leading/,../).{astra}directive dispatches elements, children, whole collections (registries), and bare sub-analyses; options:label::caption::compact::show:/:hide::universe::class:.{astra}(store-driven hover card),{astra:num},{astra:cite},{astra:cite:t},{astra:value}.#astra:anchor resolver (prose.ts) — page-relative, with../and cross-page links; figure embeds for in-scope outputs.narrativesection, so sub-analysis card summaries and#narrative.*anchors are gone.design_proposal.mdadded.plugin-core/prosesuites rewritten for the new syntax; newtests/path.test.ts.Notes / scope
#astra:link scheme resolves relative to the page (directives have no page context at run time). Documented in the README.astra-*classes, cross-scope merge, DOI citation registration) is preserved; finding-evidence DOIs are now also registered.Verification
npm run typecheck✅npm test✅ — 105 passednpm run build+npm run bundle✅🤖 Generated with Claude Code