Skip to content

Commit 470fe98

Browse files
committed
🏷️ Name the additive inspection field targetInfo (#463)
The field is one name, and it runs from the outline through the parsed root document to the public inspection result.
1 parent 3accee9 commit 470fe98

7 files changed

Lines changed: 25 additions & 25 deletions

File tree

‎packages/cli/src/cli.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1020,7 +1020,7 @@ interface PropsPhase {
10201020
* Carried from the one inspection this phase already performs — help never
10211021
* reads the document a second time.
10221022
*/
1023-
targetCatalog?: readonly DocumentTargetInfo[];
1023+
targetInfo?: readonly DocumentTargetInfo[];
10241024
error?: string;
10251025
/**
10261026
* The immutable definition a `workflow start` established, when it did.
@@ -1121,15 +1121,15 @@ function* preparePropsPhase(args: string[], evalFlags: EvalFlags): Operation<Pro
11211121
const document = yield* inspectDocument(root);
11221122
const bindings = buildBindings(document.props);
11231123
const extraction = extractPropsArgs(args, bindings);
1124-
const addressable = root.source === undefined && document.targetCatalog.length > 0;
1124+
const addressable = root.source === undefined && document.targetInfo.length > 0;
11251125
return {
11261126
args: extraction.rest,
11271127
root: exactRoot(root, document.target),
11281128
bindings,
11291129
extraction,
11301130
propsSchema: document.props,
11311131
declared: declaredProperties(document.props),
1132-
...(addressable ? { targetCatalog: document.targetCatalog } : {}),
1132+
...(addressable ? { targetInfo: document.targetInfo } : {}),
11331133
};
11341134
} catch (error) {
11351135
return {
@@ -1396,10 +1396,10 @@ function renderHelp(phase: PropsPhase): string {
13961396
const withProperties = phase.declared?.length
13971397
? `${withSource}\n\n${formatProperties(documentPath, phase.bindings)}`
13981398
: withSource;
1399-
if (phase.targetCatalog === undefined) {
1399+
if (phase.targetInfo === undefined) {
14001400
return withProperties;
14011401
}
1402-
return `${withProperties}\n\n${formatTargets(documentPath, phase.targetCatalog)}`;
1402+
return `${withProperties}\n\n${formatTargets(documentPath, phase.targetInfo)}`;
14031403
}
14041404

14051405
/**
@@ -1410,8 +1410,8 @@ function renderHelp(phase: PropsPhase): string {
14101410
* than one a selector resolves arbitrarily. A section that states no
14111411
* description is listed all the same: it is still selectable.
14121412
*/
1413-
function formatTargets(documentPath: string, catalog: readonly DocumentTargetInfo[]): string {
1414-
const entries = catalog.map((entry) => {
1413+
function formatTargets(documentPath: string, targets: readonly DocumentTargetInfo[]): string {
1414+
const entries = targets.map((entry) => {
14151415
const reference = ` ${formatDocumentReference(documentPath, entry.target)}`;
14161416
return entry.description === undefined ? reference : `${reference}\n ${entry.description}`;
14171417
});

‎packages/core/src/definition.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ export interface ParsedRootDocument {
139139
/** Canonical encoded target fragments in document order, duplicates kept. */
140140
targets: readonly string[];
141141
/** The same fragments, in the same order, each with its own description. */
142-
targetCatalog: readonly DocumentTargetInfo[];
142+
targetInfo: readonly DocumentTargetInfo[];
143143
/** The exact canonical target selected, when one was requested. */
144144
target?: string;
145145
}
@@ -182,7 +182,7 @@ export function* parseRootMarkdownDefinition(
182182
return {
183183
definition: buildDefinition(name, path, frontmatter, bodySegments),
184184
targets: outline.targets,
185-
targetCatalog: outline.catalog,
185+
targetInfo: outline.targetInfo,
186186
};
187187
}
188188

@@ -202,7 +202,7 @@ export function* parseRootMarkdownDefinition(
202202
return {
203203
definition: buildDefinition(name, path, frontmatter, bodySegments),
204204
targets: outline.targets,
205-
targetCatalog: outline.catalog,
205+
targetInfo: outline.targetInfo,
206206
target: entry.target,
207207
};
208208
}

‎packages/core/src/document-targets.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ export interface DocumentOutline {
7575
/** Canonical encoded fragments in source order, duplicates retained. */
7676
readonly targets: readonly string[];
7777
/** The same entries, in the same order, each with its own description. */
78-
readonly catalog: readonly DocumentTargetInfo[];
78+
readonly targetInfo: readonly DocumentTargetInfo[];
7979
/** Where the preamble ends: the first root-flow heading, or the body end. */
8080
readonly preambleEnd: number;
8181
readonly bodyLength: number;
@@ -958,7 +958,7 @@ export function outlineDocument(body: string, spans: readonly ComponentSpan[]):
958958
headings: [],
959959
entries: [],
960960
targets: [],
961-
catalog: [],
961+
targetInfo: [],
962962
preambleEnd: body.length,
963963
bodyLength: body.length,
964964
};
@@ -1011,7 +1011,7 @@ export function outlineDocument(body: string, spans: readonly ComponentSpan[]):
10111011
targets: entries.map((entry) => entry.target),
10121012
// Derived from the same ordered entries as `targets`, so the two cannot
10131013
// disagree about what the document addresses or in which order.
1014-
catalog: entries.map(({ target, description }) =>
1014+
targetInfo: entries.map(({ target, description }) =>
10151015
description === undefined ? { target } : { target, description },
10161016
),
10171017
// The first heading in the root flow, whatever its depth. The preamble is

‎packages/core/src/inspect.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ export interface DocumentInfo {
6262
* array back to its `target` members reproduces it exactly. A description
6363
* decides nothing about selection, projection, execution, or replay.
6464
*/
65-
readonly targetCatalog: readonly DocumentTargetInfo[];
65+
readonly targetInfo: readonly DocumentTargetInfo[];
6666

6767
/**
6868
* The exact canonical target the requested selector resolved to. Present only
@@ -103,7 +103,7 @@ export function* inspectDocument(options: InspectOptions): Operation<DocumentInf
103103
returns: definition.returns ?? TEXT_RETURN_SCHEMA,
104104
returnMode: definition.returns === undefined ? "text" : "value",
105105
targets: parsed.targets,
106-
targetCatalog: parsed.targetCatalog,
106+
targetInfo: parsed.targetInfo,
107107
...(parsed.target === undefined ? {} : { target: parsed.target }),
108108
};
109109
}

‎packages/core/tests/document-targets.test.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -764,22 +764,22 @@ describe("Tier DT — inspection", () => {
764764
it("DT79: the structured catalog carries the same targets, in order, with duplicates", function* (): Operation<void> {
765765
const info = yield* inspectDocument(inlineSource(DESCRIBED_DUPLICATES));
766766
expect(info.targets).toEqual(["Same", "Same", "Plain"]);
767-
expect(info.targetCatalog).toEqual([
767+
expect(info.targetInfo).toEqual([
768768
{ target: "Same", description: "The first section under this canonical path." },
769769
{ target: "Same", description: "The second section under the very same path." },
770770
{ target: "Plain" },
771771
]);
772772
// The identity surface is derived from the same entries, so the described
773773
// catalog cannot address anything the canonical array does not.
774-
expect(info.targetCatalog.map(({ target }) => target)).toEqual(info.targets);
774+
expect(info.targetInfo.map(({ target }) => target)).toEqual(info.targets);
775775
});
776776

777777
it("DT80: a selected inspection reports the exact target and the whole catalog", function* (): Operation<void> {
778778
const info = yield* inspectDocument(inlineSource(DESCRIBED_DUPLICATES, { target: "Pl*" }));
779779
expect(info.target).toBe("Plain");
780780
expect(info.targets).toEqual(["Same", "Same", "Plain"]);
781-
expect(info.targetCatalog.map(({ target }) => target)).toEqual(info.targets);
782-
expect(info.targetCatalog[0]).toEqual({
781+
expect(info.targetInfo.map(({ target }) => target)).toEqual(info.targets);
782+
expect(info.targetInfo[0]).toEqual({
783783
target: "Same",
784784
description: "The first section under this canonical path.",
785785
});
@@ -821,7 +821,7 @@ const DESCRIBED_DUPLICATES = [
821821

822822
/** The description a section states, or `undefined` when it states none. */
823823
function description(body: string, target: string): string | undefined {
824-
const entry = outline(body).catalog.find((candidate) => candidate.target === target);
824+
const entry = outline(body).targetInfo.find((candidate) => candidate.target === target);
825825
if (entry === undefined) {
826826
throw new Error(`${target} is not addressed by this document`);
827827
}

‎specs/executable-mdx-spec.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6746,7 +6746,7 @@ what it declares — without executing the document or creating a journal:
67466746
- `targets` — every document target the root addresses, as canonical encoded
67476747
fragments without the document path or a leading `#`, in document order,
67486748
duplicates retained (§5.4).
6749-
- `targetCatalog` — the same targets, in the same order and with the same
6749+
- `targetInfo` — the same targets, in the same order and with the same
67506750
duplicates, each as a `DocumentTargetInfo` carrying its `target` and, when the
67516751
section states one, its `description` (§5.4). Informational and additive:
67526752
`targets` remains the identity surface, and mapping this array to its `target`
@@ -8549,7 +8549,7 @@ Defined in [Workflow runs](./workflow-spec.md) §9.4 and §9.6–§9.7.
85498549
| DT40–DT43 | Positions | A retained element keeps its authored offset and line, CRLF included; frontmatter, props and return mode survive; the untargeted parse still scans the whole body |
85508550
| DT44–DT47 | Inspection | The catalog is reported without selecting; a glob resolves to the exact target; an unresolvable target fails inspection; the failure's data is frozen and rebuilt |
85518551
| DT67–DT78 | Descriptions | The first direct static paragraph describes its section, past blank lines and comment-only HTML, kept whole with formatting reduced and whitespace collapsed; a fence, component, list, quote or child heading first leaves no description and later prose is not reached; an interpolation or an inline component omits the paragraph whole rather than as a static prefix |
8552-
| DT79/DT80 | Structured catalog | `targetCatalog` carries the same targets, order and duplicates as `targets`, each with its own description, on the unselected path and beside an unchanged exact `target` on the selected one |
8552+
| DT79/DT80 | Structured catalog | `targetInfo` carries the same targets, order and duplicates as `targets`, each with its own description, on the unselected path and beside an unchanged exact `target` on the selected one |
85538553
| DT52/DT53 | Recognition | A failure from a separately loaded copy, and one built here, are read on the same terms |
85548554
| DT54–DT56 | Reconstruction | The result is a fresh local error, never the candidate; a mutable nested list is copied and later mutation changes nothing; a revoked Proxy cannot reach through a result already built |
85558555
| DT57 | Closed data | Enumerable, non-enumerable and symbol-keyed extras are refused |

‎specs/root-document-props-spec.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -311,14 +311,14 @@ const inline = yield* inspectDocument(inlineSource("---\nprops:\n name: { type:
311311
```
312312

313313
The same result describes what the document addresses. `targets` is the
314-
canonical identity surface, and the additive `targetCatalog` carries the same
314+
canonical identity surface, and the additive `targetInfo` carries the same
315315
fragments, in the same order and with the same duplicates, each as a
316316
`DocumentTargetInfo` — its `target`, and its `description` when the section
317317
states one:
318318

319319
```typescript
320-
const { targets, targetCatalog } = yield* inspectDocument({ path: "hello.md" });
321-
targetCatalog.map(({ target }) => target); // exactly `targets`
320+
const { targets, targetInfo } = yield* inspectDocument({ path: "hello.md" });
321+
targetInfo.map(({ target }) => target); // exactly `targets`
322322
```
323323

324324
Inspection resolves relative paths against the contextual working directory.

0 commit comments

Comments
 (0)