Repository navigation
Make named xmd syntax work in standalone binaries #794
Description
Story
As someone using a standalone xmd binary, I want a named syntax lookup to
show the component's documentation, so I can learn how to write that component
without installing a source or package distribution.
Example
This command should show TempDir's syntax metadata and long-form
documentation:
xmd syntax TempDirA misspelled name should instead receive the ordinary unknown-name refusal:
xmd syntax TemdDirCurrent gap
The standalone binaries published in v0.12.0 fail both commands before checking
the requested name:
the packaged component documentation is missing from this build (looked in file:///var/folders/.../deno-compile-xmd/packages/core/src/components/components.md)
Compact xmd syntax and xmd syntax --json still work. Named lookup fails
because it is the path that reads package-owned components.md files.
The local deno task build compile includes every first-party documentation
asset. The separate cross-platform compile in .github/workflows/release.yml
includes the packaged command documents but omits the components.md assets,
so all five published binaries can be built and released without the
documentation they need at runtime.
The existing compiled-binary tests exercise the local build command. They do
not distinguish it from the release compile that omitted these files.
Contract
Every standalone release binary contains the same package-owned component
documentation used by source, npm and JSR executions. Named xmd syntax and
named <Syntax> read those embedded bytes relative to their owning package,
independent of the process working directory and component search paths.
The local and release compile paths derive their packaged-asset inputs from one
authoritative definition or are otherwise checked for exact agreement. Adding
a new package-owned documentation asset cannot leave the release compile
silently incomplete.
A release-shaped compiled binary must demonstrate named lookup before it can be
published. Missing documentation withholds the release rather than producing a
binary whose compact catalog works while its documented lookup fails.
Existing v0.12.0 assets remain historical. Deliver the correction through a
patch release rather than replacing published binaries silently.
Acceptance
- A release-shaped standalone binary renders
xmd syntax TempDirwith
TempDirmetadata and long-form documentation. xmd syntax TemdDirreaches the normal unknown-name refusal rather than a
missing-asset failure.- A compiled document containing
<Syntax names={["Elicit", "File"]} />
renders the selected documentation, including through thexmd plan
information-request path delivered by Add read-only XMD information requests toxmd plan#762. - Running from another working directory and supplying repository component
includes cannot move or replace the packaged documentation. - Omitting any package-owned
components.mdfrom a release compile fails
focused verification before publication. - The release matrix, the local build,
deno task verify:clean, and
specs/release-process-spec.mdagree about the assets a standalone binary
carries.
Evidence
Add a regression that executes a binary produced by the release compile shape,
not only deno task build, and performs both a successful named lookup and the
misspelled-name negative control. Keep the existing compiled Plan and package
distribution coverage.
Relevant existing entrypoints include:
scripts/tests/plan-component-compiled.test.tsscripts/tests/packaged-document.test.tsscripts/tests/release-targets.test.tsscripts/tests/publish-workflow-membership.test.tsdeno task verify:clean
Out of scope
- Changing the authored contents of component documentation.
- Changing the compact syntax catalog or its JSON schema.
- Replacing or deleting the v0.12.0 release assets.
- Website reference generation owned by Generate website reference documentation from
xmdCLI output #678.
Activity