Skip to content

Commit 2b4585c

Browse files
committed
🐛 Hold a forms declaration and a dotted name to their own grammar
Six corrections to the `xmd syntax` catalog, all of them places where the catalog described something other than what the code accepts. **A dot is a separator, never part of a segment.** Path inversion and the symlink-relevance check asked the whole-name predicate, which admits `File.Delete`. But `File.Delete` is probed at `File/Delete.md`, so a file called `File.Delete.md` and a directory called `File.Delete` answer to no name at all. Both now ask a single-segment predicate. The dotted directory symlink is the case that showed: it was classified, found to be a directory, and failed the whole request over a path no candidate runs through. **Forms have one canonical spelling, checked where the declaration is made.** Omission means both; the only arrays are `["self-closing"]`, `["paired"]` and `["self-closing", "paired"]`. An empty array, a reversed pair, a repeated member and a form no invocation has are refused by one shared check, used by registration and by the identity declarations inspection reads — refusing in only one of those places refuses only when a document happens to run. **First-party forms now match what is accepted.** `<Json>` refuses content in its own body, so it reports one form; an assertion kind that does not read expected children refuses them, so those report one form too. Both facts are read off the value that already decides them. **The testing prose was wrong in three ways.** `<AssertThrows>` requires `message` rather than taking it optionally; its `as` binds the complete caught error segment by reference; and an ordinary assertion's `as` binds the diagnostic report it rendered, which a failing assertion never returns. **Every Markdown table cell is escaped, prop names included.** One pipe in a property name shifted every column after it. The two `as const` assertions in the CLI renderer are gone; the category-keyed tables take a declared type derived from the catalog.
1 parent ca0e238 commit 2b4585c

13 files changed

Lines changed: 468 additions & 43 deletions

‎architecture.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3280,6 +3280,19 @@ directory, so refusing is what stops the catalog silently omitting everything
32803280
beneath one. The diagnostic names the configured include and the logical entry,
32813281
never the resolved host path.
32823282

3283+
**Documented forms are canonical and checked.** A declaration says which
3284+
authored forms a component accepts, and the spelling is closed: omission means
3285+
both, and the only arrays are `["self-closing"]`, `["paired"]` and
3286+
`["self-closing", "paired"]`. One spelling per meaning is what lets a catalog be
3287+
compared without being normalized, so an empty array, a reversed pair, a
3288+
repeated member and a form no invocation has are refused where the declaration
3289+
is made — at registration and at the identity declarations inspection reads,
3290+
because a declaration refused in only one of those places is refused only when a
3291+
document happens to run. What a component accepts and what it says it accepts
3292+
come from one value: a dispatcher's forms are read off its own `FormDeclaration`,
3293+
and a component that refuses a form in its own body declares the form that
3294+
leaves.
3295+
32833296
**Documentation is descriptive metadata and nothing else.** `description`, `as`
32843297
and `context` take no part in expansion, resolution, validation, authority or
32853298
the journal. For a Markdown component they are ordinary frontmatter: a string is

‎packages/cli/src/syntax.ts‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -71,17 +71,20 @@ export function renderSyntaxJson(catalog: SyntaxCatalog): string {
7171
return `${JSON.stringify(catalog, null, 2)}\n`;
7272
}
7373

74-
const HEADINGS = {
74+
/** The three category kinds, taken from the catalog rather than restated. */
75+
type CategoryKind = SyntaxCatalog["categories"][number]["kind"];
76+
77+
const HEADINGS: Record<CategoryKind, string> = {
7578
structural: "## Built-in structural syntax",
7679
"built-in": "## Built-in components",
7780
"user-provided": "## User-provided components",
78-
} as const;
81+
};
7982

80-
const EMPTY = {
83+
const EMPTY: Record<CategoryKind, string> = {
8184
structural: "No structural constructs are reserved.",
8285
"built-in": "No components are registered in this profile.",
8386
"user-provided": "No components were found in the configured includes.",
84-
} as const;
87+
};
8588

8689
export function renderSyntaxMarkdown(catalog: SyntaxCatalog): string {
8790
const sections = catalog.categories.map((category) => {
@@ -214,14 +217,25 @@ function propertyRows(props: PropsSchema): string[] {
214217
);
215218
const rows: string[] = [];
216219
for (const [name, schema] of Object.entries(properties)) {
220+
// Every cell is escaped on the way in, the prop name included: a schema
221+
// property may be spelled with anything, and one pipe in a name would
222+
// shift every column after it.
217223
rows.push(
218-
`| ${code(name)} | ${summarizeType(schema)} | ${required.has(name) ? "yes" : "no"} | ` +
219-
`${cell(describeProp(schema))} |`,
224+
row([
225+
code(name),
226+
summarizeType(schema),
227+
required.has(name) ? "yes" : "no",
228+
describeProp(schema),
229+
]),
220230
);
221231
}
222232
return rows;
223233
}
224234

235+
function row(cells: readonly string[]): string {
236+
return `| ${cells.map(cell).join(" | ")} |`;
237+
}
238+
225239
/**
226240
* The type column, or an honest refusal to reduce one.
227241
*
@@ -238,7 +252,9 @@ function summarizeType(schema: Json): string {
238252
return code(type);
239253
}
240254
if (Array.isArray(type) && type.every((member) => typeof member === "string")) {
241-
return type.map(code).join(" \\| ");
255+
// Unescaped: `row()` escapes every cell once, and escaping here as well
256+
// would put a backslash in front of the backslash.
257+
return type.map(code).join(" | ");
242258
}
243259
return "JSON Schema";
244260
}

‎packages/cli/tests/syntax-cli.test.ts‎

Lines changed: 83 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import { tmpdir } from "node:os";
2020
import { dirname, join } from "node:path";
2121
import { API } from "@executablemd/runtime";
2222
import { CORE_COMPONENT_NAMES } from "@executablemd/core";
23-
import type { SyntaxCatalog } from "@executablemd/core";
23+
import type { PropsSchema, SyntaxCatalog } from "@executablemd/core";
2424
import { renderSyntaxJson, renderSyntaxMarkdown, syntaxCatalog } from "../src/syntax.ts";
2525

2626
function* useWorkspace<T>(
@@ -92,6 +92,34 @@ function names(entries: readonly { name: string }[]): string[] {
9292
return entries.map((entry) => entry.name);
9393
}
9494

95+
/** One built-in entry carrying `props`, for a renderer row that supplies its own. */
96+
function catalogWith(props: PropsSchema): SyntaxCatalog {
97+
return {
98+
version: 1,
99+
categories: [
100+
{ kind: "structural", entries: [] },
101+
{
102+
kind: "built-in",
103+
entries: [
104+
{
105+
kind: "component",
106+
name: "Awkward",
107+
origin: { kind: "registered", origin: "test", reserved: false },
108+
sourceKind: "registered",
109+
inspectability: "complete",
110+
forms: ["self-closing"],
111+
props,
112+
captures: [],
113+
returnMode: "text",
114+
returns: { type: "string" },
115+
},
116+
],
117+
},
118+
{ kind: "user-provided", entries: [] },
119+
],
120+
};
121+
}
122+
95123
describe("Tier SX — the run profile the command describes", () => {
96124
it("SX1: names core, Agent, testing and web defaults, and <Session>", function* () {
97125
const catalog = yield* syntaxCatalog([]);
@@ -127,6 +155,36 @@ describe("Tier SX — the run profile the command describes", () => {
127155
expect(names(undocumented)).toEqual([]);
128156
});
129157

158+
it("SX2b: reports the testing contracts as they actually are", function* () {
159+
const catalog = yield* syntaxCatalog([]);
160+
const entries = catalog.categories[1].entries;
161+
162+
const throws = entries.find((entry) => entry.name === "AssertThrows");
163+
// `message` is a capture, so it is deliberately absent from the schema —
164+
// which is exactly why the prose has to say it is required.
165+
expect(throws?.captures).toEqual(["message"]);
166+
expect(throws?.props.properties).toEqual({});
167+
expect(throws?.description).toContain("required");
168+
// The return binds by reference, so `as` receives the segment itself.
169+
expect(throws?.as).toContain("caught error segment");
170+
171+
// An ordinary assertion returns its report, so `as` binds text — not the
172+
// outcome, which a failing assertion never returns at all.
173+
const equals = entries.find((entry) => entry.name === "AssertEquals");
174+
expect(equals?.as).toContain("diagnostic report");
175+
expect(equals?.returnMode).toBe("text");
176+
177+
// A kind that reads expected children accepts both forms; one that refuses
178+
// them accepts one, and `assertions.test.ts` proves the refusal.
179+
expect(equals?.forms).toEqual(["self-closing", "paired"]);
180+
expect(entries.find((entry) => entry.name === "Assert")?.forms).toEqual(["self-closing"]);
181+
expect(entries.find((entry) => entry.name === "AssertMatch")?.forms).toEqual(["self-closing"]);
182+
expect(entries.find((entry) => entry.name === "AssertStringIncludes")?.forms).toEqual([
183+
"self-closing",
184+
"paired",
185+
]);
186+
});
187+
130188
it("SX3: describes <Session> without minting an execution claimant", function* () {
131189
const catalog = yield* syntaxCatalog([]);
132190
const session = catalog.categories[1].entries.find((entry) => entry.name === "Session");
@@ -176,6 +234,30 @@ describe("Tier SX — the renderers take a value", () => {
176234
expect(rendered.json.endsWith("\n")).toBe(true);
177235
});
178236

237+
it("SX4b: escapes a table cell that would otherwise shift the columns", function* () {
238+
const markdown = renderSyntaxMarkdown(
239+
catalogWith({
240+
type: "object",
241+
properties: {
242+
"left|right": { type: "string", description: "a | in the description, and\na break" },
243+
plain: { type: ["string", "number"] },
244+
},
245+
required: ["left|right"],
246+
additionalProperties: false,
247+
}),
248+
);
249+
250+
const rows = markdown.split("\n").filter((line) => line.startsWith("| `"));
251+
expect(rows).toEqual([
252+
"| `left\\|right` | `string` | yes | a \\| in the description, and a break |",
253+
"| `plain` | `string` \\| `number` | no | |",
254+
]);
255+
// Every row still has the four columns the header declares.
256+
for (const line of rows) {
257+
expect(line.split(/(?<!\\)\|/).length).toBe(6);
258+
}
259+
});
260+
179261
it("SX5: renders the same bytes twice from the same catalog", function* () {
180262
const catalog = yield* syntaxCatalog([]);
181263

‎packages/core/src/components/candidates.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424

2525
import { glob, lstat, stat } from "@executablemd/runtime";
2626
import type { Operation } from "effection";
27-
import { isComponentName } from "./registration.ts";
27+
import { isComponentName, isComponentNameSegment } from "./registration.ts";
2828

2929
/** An include that exists but cannot be enumerated as a component directory. */
3030
export class ComponentIncludeError extends Error {
@@ -51,9 +51,9 @@ function within(include: string, path: string): string {
5151
* The name a repository path answers to, or `undefined` when it answers to
5252
* none.
5353
*
54-
* Each segment is held to the single-segment grammar rather than to the dotted
55-
* one, because that is what the forward mapping produces: `File.Delete` is
56-
* probed at `File/Delete.md`, so a file literally named `File.Delete.md`
54+
* Each path segment is held to the single-segment grammar rather than to the
55+
* dotted one, because that is what the forward mapping produces: `File.Delete`
56+
* is probed at `File/Delete.md`, so a file literally named `File.Delete.md`
5757
* answers to no name at all and must not be reported as though it did.
5858
*/
5959
export function repositoryComponentName(path: string): string | undefined {
@@ -64,7 +64,7 @@ export function repositoryComponentName(path: string): string | undefined {
6464
}
6565
const stem =
6666
last === "index.md" || last === "index.ts" ? segments.slice(0, -1) : withoutSuffix(segments);
67-
if (stem === undefined || stem.length === 0 || !stem.every(isComponentName)) {
67+
if (stem === undefined || stem.length === 0 || !stem.every(isComponentNameSegment)) {
6868
return undefined;
6969
}
7070
const name = stem.join(".");
@@ -92,7 +92,7 @@ function couldContribute(path: string): boolean {
9292
if (repositoryComponentName(path) !== undefined) {
9393
return true;
9494
}
95-
return path.split("/").every(isComponentName);
95+
return path.split("/").every(isComponentNameSegment);
9696
}
9797

9898
/**

‎packages/core/src/components/registration.ts‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ import type { Context, Operation } from "effection";
1717
import { Component } from "../component-api.ts";
1818
import { updateOwn } from "../scope-local.ts";
1919
import { RESERVED_STRUCTURAL } from "../structural.ts";
20+
import { formsRefusal } from "../invocation-identity.ts";
2021
import { documentationOf } from "./documentation.ts";
2122
import type { ComponentDocumentation } from "./documentation.ts";
2223
import { compilePropsSchema, compileReturnsSchema } from "../validate.ts";
@@ -94,6 +95,21 @@ const OwnContributions: Context<OwnIndex> = createContext<OwnIndex>(
9495

9596
const SEGMENT = /^[A-Z][A-Za-z0-9_]*$/;
9697

98+
/**
99+
* Whether `segment` is spelled the way one dot-separated part of a component
100+
* name is.
101+
*
102+
* Distinct from the whole-name predicate below, and the distinction matters
103+
* wherever a name is taken apart: a path segment carries exactly one part, so
104+
* `File.Delete` is a two-part *name* and never a one-part *segment*. A caller
105+
* that inverts a path asks this, because `File.Delete` is written at
106+
* `File/Delete.md` and a file literally called `File.Delete.md` answers to
107+
* nothing.
108+
*/
109+
export function isComponentNameSegment(segment: string): boolean {
110+
return SEGMENT.test(segment);
111+
}
112+
97113
/**
98114
* Whether `name` is spelled the way a document writes a component name.
99115
*
@@ -103,7 +119,7 @@ const SEGMENT = /^[A-Z][A-Za-z0-9_]*$/;
103119
* registration, or a name nothing supplies.
104120
*/
105121
export function isComponentName(name: string): boolean {
106-
return name.length > 0 && name.split(".").every((segment) => SEGMENT.test(segment));
122+
return name.length > 0 && name.split(".").every(isComponentNameSegment);
107123
}
108124

109125
function kindOf(registration: ComponentRegistration): Kind {
@@ -231,6 +247,10 @@ export function* registerComponents(
231247
yield* compileReturnsSchema(returns);
232248
}
233249
assertUsableCaptures(name, registration.captures, props);
250+
const badForms = formsRefusal(forms);
251+
if (badForms !== undefined) {
252+
throw new ComponentRegistrationError(`the registration for "${name}" ${badForms}`);
253+
}
234254

235255
const kind = kindOf(registration);
236256
const already = additions.get(name)?.[kind];

‎packages/core/src/components/registry.ts‎

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,13 @@ import { parseJsonObject } from "../json.ts";
3030
import { declaredForms, formDispatcher } from "../invocation-identity.ts";
3131
import { documented } from "./documentation.ts";
3232
import type { FirstPartyDocumentation } from "./documentation.ts";
33-
import type { FormDeclaration, FunctionComponent, PropsSchema, ReturnsSchema } from "../types.ts";
33+
import type {
34+
FormDeclaration,
35+
FunctionComponent,
36+
InvocationForm,
37+
PropsSchema,
38+
ReturnsSchema,
39+
} from "../types.ts";
3440

3541
/** The origin every core component reports to inspection. */
3642
export const CORE_ORIGIN = "@executablemd/core";
@@ -45,6 +51,16 @@ export const CORE_ORIGIN = "@executablemd/core";
4551
interface CoreOptions {
4652
returns?: ReturnsSchema;
4753
captures?: readonly string[];
54+
/**
55+
* The forms this component accepts, when it is form-sensitive without being
56+
* a dispatcher.
57+
*
58+
* A component that hands over a `FormDeclaration` needs none of this: its
59+
* forms are read off that declaration below. This is for one that refuses a
60+
* form in its own body — `<Json>`, which will not render content — so what it
61+
* accepts and what it says it accepts are still written once each and agree.
62+
*/
63+
forms?: readonly InvocationForm[];
4864
}
4965

5066
/**
@@ -71,6 +87,7 @@ function core(
7187
const declaration = typeof implementation === "function" ? undefined : implementation;
7288
const fn = typeof implementation === "function" ? implementation : formDispatcher(implementation);
7389
const { returns, captures } = options;
90+
const forms = declaration === undefined ? options.forms : declaredForms(declaration);
7491
return [
7592
name,
7693
{
@@ -81,7 +98,7 @@ function core(
8198
props,
8299
...(returns === undefined ? {} : { returns }),
83100
...(captures === undefined ? {} : { captures }),
84-
...(declaration === undefined ? {} : { forms: declaredForms(declaration) }),
101+
...(forms === undefined ? {} : { forms }),
85102
...documented(documentation),
86103
fn,
87104
},
@@ -163,11 +180,12 @@ export const CORE_REGISTRY: ComponentRegistry = new Map<string, RegistryEntry>([
163180
description:
164181
"Renders a structured value as JSON text at the position it is written. There is no " +
165182
"indent, replacer or sorting option: the whole transformation is one value to one " +
166-
"piece of text.",
183+
"piece of text. It renders the value it is given rather than content, so the paired " +
184+
"form is refused.",
167185
as: null,
168186
context: null,
169187
},
170-
{ captures: ["value"] },
188+
{ captures: ["value"], forms: ["self-closing"] },
171189
),
172190
core(
173191
"Parse",

‎packages/core/src/inspect.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,12 @@ import {
1919
import type { DocumentTargetInfo } from "./document-targets.ts";
2020
import { Component } from "./component-api.ts";
2121
import { DEFAULT_INCLUDES, effectiveRegistry, selectComponent } from "./components/select.ts";
22-
import { mergeRegistry } from "./components/registration.ts";
22+
import { ComponentRegistrationError, mergeRegistry } from "./components/registration.ts";
2323
import { repositoryCandidateNames } from "./components/candidates.ts";
2424
import { documentationOf } from "./components/documentation.ts";
2525
import type { ComponentDocumentation } from "./components/documentation.ts";
2626
import { STRUCTURAL_DECLARATIONS } from "./structural.ts";
27+
import { formsRefusal } from "./invocation-identity.ts";
2728
import type { IdentityComponent } from "./invocation-identity.ts";
2829
import { readRootSource, rootSourcePath } from "./root-source.ts";
2930
import type { RootDocumentSource } from "./root-source.ts";
@@ -448,6 +449,16 @@ function byCodePoint(left: string, right: string): number {
448449
function declaredRegistry(components: readonly IdentityComponent[]): ComponentRegistry {
449450
const entries = new Map<string, RegistryEntry>();
450451
for (const component of components) {
452+
// The same check registration makes, at the other place a declaration
453+
// enters: ordinary execution registers these, and inspection reads them
454+
// without registering anything, so a malformed one has to be refused twice
455+
// or it is refused only when a document happens to run.
456+
const badForms = formsRefusal(component.forms);
457+
if (badForms !== undefined) {
458+
throw new ComponentRegistrationError(
459+
`the identity component "${component.name}" ${badForms}`,
460+
);
461+
}
451462
const definition: FunctionComponentDefinition = {
452463
kind: "function",
453464
name: component.name,

0 commit comments

Comments
 (0)