Skip to content

Commit a6e8bb7

Browse files
authored
✨ Validate a supplied document without executing it (#654)
* ✨ Validate a supplied document without executing it (#653) Add `validateDocument()`: one core operation that reads a supplied root and the Markdown source closure ordinary component selection discovers, and answers with deterministic version-1 data — one closed code per diagnostic, the normalized schema issues execution already produces, and one record per authored invocation saying whether it is valid, invalid, or not decidable without running the document. Traversal follows source rather than execution reachability: the selected root projection first, then definitions in FIFO discovery order, each source identity read once, so a cycle terminates and is not a failure. An invocation inside authored control flow is checked like any other, and no branch is evaluated to decide whether it would run. The rules come from execution rather than a second catalog. The body output/return contract moves to `body-structure.ts`, and the static parts of every structural construct move to `structural-rules.ts`; expansion renders the same facts as the printed errors it always produced. Frontmatter and definition parsing report the phase a failure belongs to, so nothing classifies an error by reading its message. The declaration-only registry inspection built is now shared. Observation performs no document effect: no expression is evaluated, no component invoked, no repository module imported, no identity factory called, no provider installed, no journal opened, and nothing the document authored is written. * 🐛 Give one source identity one scan, and a structural fact its own record (#653) Two version-1 contracts were wrong. The root did not enter the source cache, so a root living where a component name resolves was scanned twice: a retained root at `components/Foo.md` containing `<Foo />` returned the invocation names `["Foo", "Foo"]` and read the file again. The root now registers under its own path, so a selection finding it terminates the walk the way any other cycle does and reads nothing. A structural fact a parent discovered about a descendant went to the parent alone. A misplaced `<Else>` found through its `<If>` named `If`, and the `<Else>` it was about stayed valid. Such a finding now names and is positioned at the element it identifies, reaches that element's record, and still leaves the `<If>` whose structure is malformed invalid. Preorder guarantees the parent is visited first, so the child picks it up rather than losing it. An `<If>` with an unknown prop also returned early, hiding the missing condition and a malformed `<Else>` beside it. Every independent static check now runs. Expansion's first-refusal behavior is unchanged: it stops at the first violation over the same shared facts, and validation reads all of them. Each regression was confirmed discriminating by reverting its fix. * 🐛 Keep a targeted root's projection out of the definition a component selected (#653) One path is bytes; what is parsed from them depends on who asked. Caching the root under its path conflated the two, so a targeted root's projection stood in for the full Markdown definition an ordinary component selection asks for — and a `<Foo />` in the selected section returned `valid` while the sections the root never selected held a definite `body-shape-invalid` failure. Reading and parsing are now separate. A path is read once, whatever views the walk needs; the full-definition view is registered per path. An untargeted root's body is the whole file, so it registers as that view and a name resolving there finds it already scanned — the self-cycle deduplication is unchanged. A targeted root registers no view: a component selecting that path parses the full definition from the bytes already read and enters the FIFO queue in discovery order like any other source. Both halves of the regression were confirmed discriminating: substituting the projection again, and bypassing the content cache so the second view re-reads. * 📝 Name the delivery PR in the construct inventory (#653) * 🚑 Sort with what the Node lib provides (#653) `Array.prototype.toSorted` is ES2023 and `tsconfig.node.json` targets ES2022, so every `test-node` shard failed at its typecheck before running a test. Deno's own lib is newer, which is why `deno check` and the whole local suite were green. Both call sites already build a fresh array, so sorting in place mutates nothing anyone else holds. That reinstates an oxlint `no-array-sort` warning — the shape the rest of the repository is in, and a warning rather than the error this was. Verified with the check CI runs: `tsc --project tsconfig.node.json --noEmit`, plus the validation suite under all three runtimes. * ♻️ Finish the extraction, and say what a source view is (#653) Validation still reimplemented four authored decisions expansion owns: an ordinary component's `as` form and binding name, the requirement that a component declaring `returns` is invoked with `as`, and the `<Answers>` and `<Answer>` prop, delegate, body-shape, template-form and required-value rules. Sharing the sentences was not sharing the decisions. New `invocation-rules.ts` owns the ordinary-component rules, and the `<Answers>` and `<Answer>` rules in `structural-rules.ts` split into the phases their callers ask in. Extraction is phase-appropriate rather than phase-bound: whether `as` was written as an expression is answered from the scanned element, while what a binding name may be is answered from whatever value each caller has — expansion passes the prop it resolved, validation passes the literal the author wrote. Expansion refuses at the first of them, in the phase it always did, with byte-identical prose; validation aggregates every independent one. The regressions run each document twice — once through `execute()`, once through `validateDocument()` — and require one sentence from both. Each was confirmed discriminating by giving expansion back a private copy of the rule. The source/view contract is also corrected everywhere it was stated. Bytes are read once per path; each semantic view of them is parsed and scanned once. An untargeted root is that path's full-definition view as well. A targeted root's projection and a component-selected full definition are two distinct views of one path. The claim that a source identity is parsed or scanned once is gone from architecture.md, the spec, the public comments and the tests. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 6625319 commit a6e8bb7

14 files changed

Lines changed: 4350 additions & 799 deletions

‎architecture.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3429,13 +3429,99 @@ nothing. First-party declarations hold themselves to a stricter rule — every o
34293429
states a description and decides explicitly whether `as` and `context` apply —
34303430
which is a discipline inside those packages, not a requirement on anyone else.
34313431

3432+
## The document validation boundary
3433+
3434+
Validate a supplied document as authored program structure before any part of it
3435+
runs. The operation receives one `RootDocumentSource`, root props, contextual
3436+
working directory and includes, the current component registry, and the same
3437+
plain identity-component declarations syntax inspection receives. Those values
3438+
are the declarative execution environment: validation never runs an
3439+
`ExecutionInstallation`, calls an identity factory, installs an operational
3440+
provider or reconstructs a CLI host to learn what names mean.
3441+
3442+
**Validation follows source, not execution reachability.** It applies ordinary
3443+
target selection to the root, scans that selected projection, and follows normal
3444+
component selection through every resolved Markdown definition the authored
3445+
invocations discover. The root is first; newly discovered definitions enter one
3446+
FIFO queue in their first-invocation order. Every invocation in each source is
3447+
checked in source order, including one inside authored control flow and children
3448+
beneath an origin-only TypeScript component. The validator neither evaluates a
3449+
branch nor predicts whether a component will project its children. A definition
3450+
cycle therefore terminates the source walk and is not itself a validation
3451+
failure unless a shared authored rule already makes it one.
3452+
3453+
**A path's bytes are read once; each view of them is parsed and scanned once.**
3454+
Reading and interpreting are separate, because one file can owe the walk more
3455+
than one answer. An ordinary component selection carries no target and asks for
3456+
the whole Markdown definition. A root asks for the projection its own selector
3457+
named. An untargeted root's body *is* the whole file, so it is that path's
3458+
full-definition view as well, and a name resolving there finds it already
3459+
scanned — which is what makes a root invoking itself terminate. A targeted root
3460+
projection and the full definition a component selected are two distinct views
3461+
of one path, each parsed and scanned once, from bytes read once. Letting a
3462+
projection stand in for the definition would answer for sections the root never
3463+
selected.
3464+
3465+
**A static answer never stands in for a runtime value.** Resolution, authored
3466+
form, engine-owned body shape and other structural rules run whenever their
3467+
answer does not depend on evaluating document code. Full props-schema validation
3468+
runs only when every schema-visible prop is static. A declared capture keeps the
3469+
same schema bypass it has during execution. A dynamic schema-visible expression
3470+
or an origin-only TypeScript contract makes an otherwise acceptable invocation
3471+
not statically checkable; validation does not partially solve JSON Schema around
3472+
the unknown value. A definite independent failure still wins, so an invalid form
3473+
does not become opaque because another prop is dynamic. An invocation is valid
3474+
only when every applicable check is statically proven, invalid when any such
3475+
check proves a failure, and otherwise not statically checkable. Opacity alone
3476+
does not make the document invalid.
3477+
3478+
**Parsing stays one language rule.** Validation uses the scanner and definition
3479+
parsers execution uses. Component-like text that scanner treats as text remains
3480+
text, and spread attributes retain their execution meaning. A stricter MDX
3481+
grammar is a change to execution and validation together, never an extra parser
3482+
used only to approve generated source. Component selection, declaration
3483+
admission, schemas, forms, body rules, targets and source positions likewise
3484+
come from their execution definitions. If a check needs extraction from
3485+
expansion, both callers use the extracted rule; validation does not copy it into
3486+
a second catalog.
3487+
3488+
**The answer is versioned data.** Version 1 returns the document outcome, one
3489+
ordered invocation record per authored site, and one ordered diagnostic array.
3490+
An invocation records its name and position, the selected origin when one was
3491+
resolved, and exactly one of `valid`, `invalid` or
3492+
`not-statically-checkable`. An invalid record points into the diagnostic array;
3493+
an opaque record names `dynamic-props`, `origin-only-contract`, or both as its
3494+
reason. Diagnostics carry one closed code, a message, the source position and
3495+
component when applicable, and the existing normalized schema issues when a
3496+
schema failed. The closed version-1 codes distinguish unreadable and invalid
3497+
source, invalid target, frontmatter, props and returns declarations, unresolved
3498+
and ambiguous components, invalid invocation form and body shape, props,
3499+
binding, capture, return usage and structural usage.
3500+
3501+
Ordering is part of that answer: the root precedes definitions from the FIFO
3502+
source walk, positions order records within one source, and the closed diagnostic
3503+
code order breaks a tie at one position. A source failure ends only the checks
3504+
that require the source or definition it prevented; the validator emits no
3505+
speculative follow-on error. The document outcome is invalid exactly when a
3506+
definite diagnostic exists. The stable codes and normalized schema issues are
3507+
what an ACP generator or another host consumes; neither parses the message.
3508+
3509+
**Observation performs no document effect.** Validation may read the supplied
3510+
root and selected Markdown definition files. It does not evaluate an expression,
3511+
render or project component content, invoke a component, create or read a
3512+
journal, run a command, prompt, elicit, start an agent, or perform a filesystem
3513+
operation the document authored. Those prohibitions are one boundary rather
3514+
than a test fixture's list of components: adding a component cannot make
3515+
validation effectful.
3516+
34323517
## Construct inventory
34333518

34343519
Status is measured against main.
34353520

34363521
| Construct | Does | Status |
34373522
| --- | --- | --- |
34383523
| `xmd syntax` | describes every structural construct and every selected component the production `run` profile would let a document write in the contextual working directory, as deterministic Markdown or as version-1 JSON, from one catalog. Inspection only: it registers the run profile's declarations in a bounded scope and reads the filesystem for which files exist and, for a selected Markdown component, that file's frontmatter. It runs no body, imports no repository TypeScript module, installs no provider, mints no authority and writes no journal. An include it cannot enumerate — a selection-relevant symbolic link to a directory beneath it included — fails the whole request rather than printing a healthy subset | built on the #632 stack |
3524+
| document validation | validates one supplied root projection and the recursive Markdown source closure normal component selection discovers, returning deterministic version-1 document diagnostics and `valid`, `invalid` or `not-statically-checkable` invocation outcomes without evaluating document code or installing operational host behavior | built on the #654 stack |
34393525
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
34403526
| `<Let as="name">` | binds one name in the current environment from exactly one source: the content it renders, or the exact value `value` names, bound by reference and never through the JSON boundary component props cross — the scanner resolves no JSON for that one prop, and expansion projects none. Which source it has is read from what the author wrote, before either one runs, so a construct naming both expands no child and evaluates no expression. It opens no scope, owns no resource, adds no middleware boundary and writes no journal record — replay reconstructs both sources through ordinary expansion | built on the #527 stack |
34413527
| `<Json value={…} />` | renders one supplied value as JSON text where the element was written, from one native two-space `JSON.stringify` call. An ordinary overridable core default whose operand is a capture: the exact evaluation result arrives by reference and is never mutated, cloned, replaced or frozen. It binds nothing, and `as`, content and a missing `value` are all refused before the operand evaluates. A value with no JSON text and a serialization that threw are distinct failures, each positioned at the invocation, emitting no partial output and preserving the original error as its cause. No scope, resource, authority or JSON-specific durable effect: replay reaches it through ordinary expansion, and a surrounding `<Prompt>` or `<File>` keeps its own record of the text it consumed | built on the #452 stack |

‎packages/core/mod.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,19 @@ export type {
213213
SyntaxCatalog,
214214
} from "./src/inspect.ts";
215215
export { ComponentIncludeError } from "./src/components/candidates.ts";
216+
// Document validation — one supplied document read as authored program
217+
// structure, with nothing in it executed.
218+
export { documentValidationCodeRank, validateDocument } from "./src/document-validation.ts";
219+
export type {
220+
DocumentValidation,
221+
DocumentValidationCode,
222+
DocumentValidationDiagnostic,
223+
InvocationOpacityReason,
224+
InvocationSite,
225+
InvocationValidation,
226+
ValidateDocumentOptions,
227+
ValidateDocumentSettings,
228+
} from "./src/document-validation.ts";
216229

217230
// Component registration — scope-local names resolved ahead of package defaults.
218231
export {

‎packages/core/src/answers.ts‎

Lines changed: 56 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,16 @@ import { matchPrompt, parseTemplate, resolveBinding } from "./template.ts";
8888
import type { ParsedTemplate } from "./template.ts";
8989
import type { ComponentElement, ErrorSegment, Json, Segment } from "./types.ts";
9090
import type { AnswersPlacement, DeclarationScanner } from "./declaration-scan.ts";
91+
import {
92+
answerFormViolations,
93+
answersBodyViolation,
94+
answersDelegateMessage,
95+
answersPropNameViolations,
96+
answerValueViolation,
97+
isBlankText as isBlankSegment,
98+
literalDelegate,
99+
strayAnswerMessage,
100+
} from "./structural-rules.ts";
91101

92102
/**
93103
* The enclosing expansion's recursion, handed in by the arm that dispatched the
@@ -151,23 +161,23 @@ function configError(name: string, message: string, element: ComponentElement):
151161
return { type: "error", message: positioned(`<${name}> ${message}`, element), source: name };
152162
}
153163

154-
function isAnswer(segment: Segment): segment is ComponentElement {
155-
return segment.type === "component" && segment.name === ANSWER;
164+
/**
165+
* A shared structural violation as the printed error this module produces.
166+
*
167+
* The violation's sentence already names its construct, because validation
168+
* reports the same sentence with no element to prefix it from.
169+
*/
170+
function violationError(message: string, name: string, element: ComponentElement): ErrorSegment {
171+
return { type: "error", message: positioned(message, element), source: name };
156172
}
157173

158-
/** Markdown puts blank lines between block elements; they are not a body. */
159-
function isBlankText(segment: Segment): boolean {
160-
return segment.type === "text" && segment.content.trim() === "";
174+
function isAnswer(segment: Segment): segment is ComponentElement {
175+
return segment.type === "component" && segment.name === ANSWER;
161176
}
162177

163178
/** A `<Answer>` written outside the `<Answers>` that would have read it. */
164179
export function strayAnswerError(element: ComponentElement): ErrorSegment {
165-
return configError(
166-
ANSWER,
167-
"must be a direct child of <Answers>. It is reserved: it never resolves a " +
168-
"component, and only the <Answers> it belongs to can read it.",
169-
element,
170-
);
180+
return violationError(strayAnswerMessage(), ANSWER, element);
171181
}
172182

173183
/** What one `<Answers>` element holds, before anything is decided about it. */
@@ -218,18 +228,13 @@ export function* expandAnswers(
218228
/** The region the answered body renders into. */
219229
owner: Segment[],
220230
): Operation<Segment[]> {
221-
for (const name of Object.keys({ ...element.props, ...element.expressions })) {
222-
if (name !== "delegate") {
223-
return [
224-
yield* raise(
225-
configError(ANSWERS, `does not accept a "${name}" prop (allowed: delegate).`, element),
226-
),
227-
];
228-
}
231+
const propRefusal = answersPropNameViolations(element)[0];
232+
if (propRefusal !== undefined) {
233+
return [yield* raise(violationError(propRefusal.message, ANSWERS, element))];
229234
}
230235
const delegate = yield* readDelegate(element);
231236
if (delegate.error) {
232-
return [yield* raise(configError(ANSWERS, delegate.error, element))];
237+
return [yield* raise(violationError(delegate.error, ANSWERS, element))];
233238
}
234239

235240
const partitioned = yield* partition(element, expand);
@@ -241,17 +246,9 @@ export function* expandAnswers(
241246
}
242247
const { matchers, body } = partitioned;
243248

244-
if (element.selfClosing || body.every(isBlankText)) {
245-
return [
246-
yield* raise(
247-
configError(
248-
ANSWERS,
249-
"has no body to answer for. It wraps the region whose elicitations it answers, so " +
250-
"an <Answers> containing only matchers can never do anything.",
251-
element,
252-
),
253-
),
254-
];
249+
const bodyRefusal = answersBodyViolation(element);
250+
if (bodyRefusal !== undefined) {
251+
return [yield* raise(violationError(bodyRefusal.message, ANSWERS, element))];
255252
}
256253

257254
const bindings = (yield* env)?.values ?? {};
@@ -311,18 +308,13 @@ function* readChildAnswers(
311308
element: ComponentElement,
312309
expand: ExpandSegments,
313310
): Operation<Result<AnswerConfiguration>> {
314-
for (const name of Object.keys({ ...element.props, ...element.expressions })) {
315-
if (name !== "delegate") {
316-
return Err(
317-
new Error(
318-
positioned(`<${ANSWERS}> does not accept a "${name}" prop (allowed: delegate).`, element),
319-
),
320-
);
321-
}
311+
const propRefusal = answersPropNameViolations(element)[0];
312+
if (propRefusal !== undefined) {
313+
return Err(new Error(positioned(propRefusal.message, element)));
322314
}
323315
const delegate = yield* readDelegate(element);
324316
if (delegate.error) {
325-
return Err(new Error(positioned(`<${ANSWERS}> ${delegate.error}`, element)));
317+
return Err(new Error(positioned(delegate.error, element)));
326318
}
327319
if (delegate.value) {
328320
return Err(
@@ -351,7 +343,7 @@ function* readChildAnswers(
351343
),
352344
);
353345
}
354-
if (!body.every(isBlankText)) {
346+
if (!body.every(isBlankSegment)) {
355347
return Err(
356348
new Error(
357349
positioned(
@@ -519,29 +511,18 @@ function* readAnswer(
519511
expand: ExpandSegments,
520512
index: number,
521513
): Operation<AnswerMatcher | Malformed> {
522-
for (const name of Object.keys({ ...element.props, ...element.expressions })) {
523-
if (name !== "template" && name !== "value") {
524-
return refuse(element, `does not accept a "${name}" prop (allowed: template, value).`);
525-
}
526-
}
527-
528-
// An expression template is never read, and silently produces a matcher with
529-
// no template — which first-wins plus reusable turns into permanent shadowing
530-
// of everything below it. `<WhenPrompt>` reaches its "requires a template"
531-
// error by the same route; this says so directly.
532-
if ("template" in element.expressions) {
533-
return refuse(
534-
element,
535-
"template must be a literal string prop or template children, not an expression. " +
536-
"Write the bindings a template references as {binding} holes inside it.",
537-
);
514+
// Everything about the matcher's *shape* is decided from what was written:
515+
// which props it carries, and whether its template was written as an
516+
// expression — which is never read, and would silently produce a matcher with
517+
// no template, which first-wins plus reusable turns into permanent shadowing
518+
// of everything below it — or written twice.
519+
const formRefusal = answerFormViolations(element)[0];
520+
if (formRefusal !== undefined) {
521+
return refuseAnswer(element, formRefusal.message);
538522
}
539523

540524
const templateProp = element.props.template;
541525
const hasChildren = !element.selfClosing && element.children.length > 0;
542-
if (typeof templateProp === "string" && hasChildren) {
543-
return refuse(element, "accepts either a template prop or template children, not both.");
544-
}
545526

546527
let template: ParsedTemplate | undefined;
547528
const source =
@@ -564,8 +545,9 @@ function* readAnswer(
564545
template = parsed.value;
565546
}
566547

567-
if (!("value" in element.props) && !("value" in element.expressions)) {
568-
return refuse(element, 'requires a "value" prop.');
548+
const valueRefusal = answerValueViolation(element);
549+
if (valueRefusal !== undefined) {
550+
return refuseAnswer(element, valueRefusal.message);
569551
}
570552
const value = yield* readValue(element);
571553
if (value.error) {
@@ -575,6 +557,11 @@ function* readAnswer(
575557
return template ? { template, value: value.parsed } : { value: value.parsed };
576558
}
577559

560+
/** One shared `<Answer>` sentence as this module's malformed-matcher answer. */
561+
function refuseAnswer(element: ComponentElement, message: string): Malformed {
562+
return { error: violationError(message, ANSWER, element) };
563+
}
564+
578565
function refuse(element: ComponentElement, message: string): Malformed {
579566
return { error: configError(ANSWER, message, element) };
580567
}
@@ -641,27 +628,19 @@ function* readDelegate(element: ComponentElement): Operation<{ value: boolean; e
641628
try {
642629
evaluated = yield* evaluateExpression(expression, ANSWERS, "delegate", element.projectedEnv);
643630
} catch (error) {
644-
return { value: false, error: error instanceof Error ? error.message : String(error) };
631+
return {
632+
value: false,
633+
error: `<${ANSWERS}> ${error instanceof Error ? error.message : String(error)}`,
634+
};
645635
}
646636
if (typeof evaluated !== "boolean") {
647637
return {
648638
value: false,
649-
error: `delegate must be a boolean, and {${expression}} is ${typeof evaluated}.`,
639+
error: answersDelegateMessage(`{${expression}} is ${typeof evaluated}.`),
650640
};
651641
}
652642
return { value: evaluated };
653643
}
654-
if (!("delegate" in element.props)) {
655-
return { value: false };
656-
}
657-
const raw = element.props.delegate;
658-
if (typeof raw !== "boolean") {
659-
return {
660-
value: false,
661-
error: `delegate must be a boolean — write delegate={true}, not delegate=${JSON.stringify(
662-
raw,
663-
)}.`,
664-
};
665-
}
666-
return { value: raw };
644+
const literal = literalDelegate(element);
645+
return literal.ok ? { value: literal.value } : { value: false, error: literal.error.message };
667646
}

0 commit comments

Comments
 (0)