Skip to content

Add xmd validate for non-executing document validation #655

Description

@taras

Motivation

Core's validateDocument() boundary from #653 can decide whether a supplied
document and its recursively selected Markdown definitions contain definite
static failures without executing the document. There is no direct CLI command
for a person, editor, CI job, or agent to ask that question.

Expose that boundary as xmd validate. The command is a projection of core's
versioned result, not another validator, and preserves the no-execution boundary
that makes validation safe before approval.

Command

xmd validate workflow.md
xmd validate 'workflow.md#Build'
xmd validate --eval '<File path="README.md" />'
xmd validate workflow.md --include ./components --include ./shared
xmd validate workflow.md --json

The command accepts only inputs that can change static interpretation:

  • exactly one root document, supplied as a path/document reference or with
    --eval, using the same mutual-exclusion and target-selection behavior as
    xmd run;
  • the same document-property arguments as xmd run, because root props are part
    of validation;
  • ordered, repeatable --include values, with the run default
    ["components", "."] and explicit values replacing that default; and
  • --json for the lossless structured result.

Execution-only options do not belong to this command: no agent provider,
approval mode, timeout, journal, verbose output, raw rendering, workflow state,
or secret-detection configuration.

Host profile

Validation describes the production run environment without installing it.
As xmd syntax does, it registers the shared Agent, testing, and web component
declarations in one bounded scope and supplies declaration-only identity
components such as <Session>. It then calls core's validateDocument() once.

The command does not create an execution, call an identity factory, import a
repository TypeScript component, evaluate an expression or block, invoke a
component, install an operational provider, start an agent, elicit, open a
journal, or perform a filesystem effect authored by the document. Its only
filesystem reads are the root and Markdown component sources normal selection
identifies.

Output and exit status

xmd validate writes one deterministic human-readable report. It preserves the
core result's diagnostic order and reports each diagnostic with its code,
message, component when present, and authored path/line/column when present. It
also names invocations whose outcome is not-statically-checkable and their
reasons, so a successful exit is not presented as proof of a runtime-dependent
contract.

xmd validate --json writes the exact versioned DocumentValidation value as
two-space-indented JSON with one trailing newline. Consumers use diagnostic
codes, normalized schema issues, invocation outcomes, opacity reasons, and
diagnostic indexes directly; the CLI does not add a second schema or make a
consumer parse rendered prose.

Both output forms use:

  • exit status 0 when DocumentValidation.outcome is valid, including when the
    result truthfully identifies invocations that are not statically checkable;
  • exit status 1 when the outcome is invalid, after writing the complete result
    to stdout; and
  • exit status 1 with the error on stderr and no partial stdout when CLI parsing,
    host declaration, or another caller-configuration failure prevents a
    DocumentValidation result from being produced.

Root source, target, frontmatter, or declaration failures represented by core as
document diagnostics are ordinary complete validation results, not CLI setup
errors.

Acceptance criteria

  • A valid document exits 0 and is identified as valid in both human and JSON
    output.
  • A missing component, invalid props, malformed root, or defect in a recursively
    selected Markdown component exits 1 and preserves core's diagnostic order,
    source position, code, and invocation-to-diagnostic relationship.
  • A target reference validates only the selected root projection while still
    following ordinary full-definition component selection, including the
    two-views/one-read case from Validate supplied document structure without executing it #653.
  • An origin-only TypeScript component is not imported. Its invocation is shown
    as not statically checkable when no independent definite failure makes it
    invalid.
  • --json is the exact version-1 core result with no CLI-only wrapper or
    reconstructed fields.
  • Repeated --include values and document properties have the same meaning as
    they do for xmd run.
  • Help lists the validation inputs and excludes every execution-only option.
  • A failing result remains available on stdout even though the process exits 1;
    a caller-configuration failure writes only to stderr.
  • Focused evidence proves that validation performs zero document-authored or
    host-operational effects and does not create a journal or execution.
  • The implementation adds an end-to-end Markdown/CLI row for human and JSON
    output, target selection, invalid exit status, opacity, and the no-execution
    seam, alongside focused renderer and help tests.

Specification

Add xmd validate to the document-validation section of
specs/executable-mdx-spec.md, to the architecture construct inventory, and to
the CLI test-plan tiers. The CLI contract consumes #653's public types and
ordering unchanged.

Sequencing

Depends on #653. xmd prompt (#260) continues to call the core boundary
directly; it does not shell out to this command or parse either renderer.

Out of scope

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions