Skip to content

Make named xmd syntax work in standalone binaries #794

Description

@taras

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 TempDir

A misspelled name should instead receive the ordinary unknown-name refusal:

xmd syntax TemdDir

Current 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

  1. A release-shaped standalone binary renders xmd syntax TempDir with
    TempDir metadata and long-form documentation.
  2. xmd syntax TemdDir reaches the normal unknown-name refusal rather than a
    missing-asset failure.
  3. A compiled document containing <Syntax names={["Elicit", "File"]} />
    renders the selected documentation, including through the xmd plan
    information-request path delivered by Add read-only XMD information requests to xmd plan #762.
  4. Running from another working directory and supplying repository component
    includes cannot move or replace the packaged documentation.
  5. Omitting any package-owned components.md from a release compile fails
    focused verification before publication.
  6. The release matrix, the local build, deno task verify:clean, and
    specs/release-process-spec.md agree 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.ts
  • scripts/tests/packaged-document.test.ts
  • scripts/tests/release-targets.test.ts
  • scripts/tests/publish-workflow-membership.test.ts
  • deno task verify:clean

Out of scope

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions