You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
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
Executing a document to determine whether it succeeds.
Treating runtime opacity as a definite validation failure.
Restricting generated documents to an approved component subset.
Motivation
Core's
validateDocument()boundary from #653 can decide whether a supplieddocument 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'sversioned result, not another validator, and preserves the no-execution boundary
that makes validation safe before approval.
Command
The command accepts only inputs that can change static interpretation:
--eval, using the same mutual-exclusion and target-selection behavior asxmd run;xmd run, because root props are partof validation;
--includevalues, with the run default["components", "."]and explicit values replacing that default; and--jsonfor 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
runenvironment without installing it.As
xmd syntaxdoes, it registers the shared Agent, testing, and web componentdeclarations in one bounded scope and supplies declaration-only identity
components such as
<Session>. It then calls core'svalidateDocument()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 validatewrites one deterministic human-readable report. It preserves thecore 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-checkableand theirreasons, so a successful exit is not presented as proof of a runtime-dependent
contract.
xmd validate --jsonwrites the exact versionedDocumentValidationvalue astwo-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:
DocumentValidation.outcomeisvalid, including when theresult truthfully identifies invocations that are not statically checkable;
invalid, after writing the complete resultto stdout; and
host declaration, or another caller-configuration failure prevents a
DocumentValidationresult 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
output.
selected Markdown component exits 1 and preserves core's diagnostic order,
source position, code, and invocation-to-diagnostic relationship.
following ordinary full-definition component selection, including the
two-views/one-read case from Validate supplied document structure without executing it #653.
as not statically checkable when no independent definite failure makes it
invalid.
--jsonis the exact version-1 core result with no CLI-only wrapper orreconstructed fields.
--includevalues and document properties have the same meaning asthey do for
xmd run.a caller-configuration failure writes only to stderr.
host-operational effects and does not create a journal or execution.
output, target selection, invalid exit status, opacity, and the no-execution
seam, alongside focused renderer and help tests.
Specification
Add
xmd validateto the document-validation section ofspecs/executable-mdx-spec.md, to the architecture construct inventory, and tothe 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 boundarydirectly; it does not shell out to this command or parse either renderer.
Out of scope
xmd prompt: turn a request into an approved executable Plan #260.precedence defined by Validate supplied document structure without executing it #653.