Skip to content

Commit 787ebcb

Browse files
authored
💥 Say where components come from with --include (#631)
* 💥 Say where components come from with --include Rename the configured component-search-path surface: `includes` at every programmatic boundary, `--include` as the repeatable CLI flag, and `DEFAULT_INCLUDES` for the exported `["components", "."]` default. This is a clean break. No alias, no deprecation, no compatibility parser: the typed API no longer declares the former member, and an untyped object carrying it is not read. "Component search path" and "component search directory" stay the names of the complete ordered resolution path and of one directory on it. Includes name only the configured contribution to that path. Resolution order, diagnostics, the `searched` list, journal shape, the workflow's empty contribution and directory-target composition are unchanged. Refs #271 * 🚫 Refuse the flag --include replaced The argument parser ignores options it does not define rather than rejecting them, so `--component-dir` was silently dropped: a run searched the defaults and either failed somewhere unrelated or succeeded while ignoring where the caller said components come from. `xmd run` and `xmd test` now refuse it by name, before the run resolves its props and before a test target is discovered. Both spellings are refused — the separated value and the `=` form — and tokens after `--` still belong to the document. This is a refusal, not an alias: no value is mapped, and no generic unknown-option policy is introduced. The retired spelling is assembled from fragments at its one remaining site, so the migration audit stays empty. Refs #271 * 🐛 Read the refusal from what the parser did not consume A directory can be named after the retired flag, and naming a directory is what --include is for. Scanning raw argv read that value as an option and refused the run — the one caller using the new option correctly. The finder now reads the parser's leftovers, where a token consumed as a value no longer appears. The end-of-options separator survives into those leftovers, so a retired spelling after -- still belongs to the document. Refs #271 * 🎨 Reflow the docs list item the shorter flag changed `deno fmt` owns `site/`, and the option name lost eight characters, so the line it was wrapped for now fits differently. * 🔥 Drop the retired include flag rather than refuse it Nothing has been released that names the old flag, so there is no caller to tell. The refusal existed only to answer one, and it cost a constant assembled from fragments to keep the migration audit empty — a string the one place that handled it could not be searched for. The old spelling is now an option xmd does not define, exactly like any other typo, and no code in the repository mentions it. Refs #271 * 🔥 Stop asserting the absence of names nothing can name CR35 and CR38 proved the retired option was gone from the typed surface and unread at runtime, and CR36 proved the retired export was gone. With the old spelling deleted rather than deprecated there is nothing to be absent from: the audit already says no source mentions it, and a test that spells it from fragments only reintroduces the name it checks for. CR36 keeps what is a claim about the present surface — the default value, and that core exports it. Refs #271 --------- Co-authored-by: Taras Mankovski <74687+taras@users.noreply.github.com>
1 parent 0e88e91 commit 787ebcb

62 files changed

Lines changed: 320 additions & 220 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -186,15 +186,15 @@ jobs:
186186
- name: Smoke test the compiled binary
187187
run: |
188188
./dist/xmd test smoke-test/README.md \
189-
--component-dir smoke-test \
190-
--component-dir packages/core/components \
189+
--include smoke-test \
190+
--include packages/core/components \
191191
--raw
192192
193193
- name: Smoke test attached-service ping-pong with the compiled binary
194194
run: |
195195
./dist/xmd test smoke-test/attached-service-ping-pong.test.md \
196-
--component-dir smoke-test \
197-
--component-dir packages/core/components \
196+
--include smoke-test \
197+
--include packages/core/components \
198198
--raw
199199
200200
# Foreground execution is about what a caller sees and what status they
@@ -239,7 +239,7 @@ jobs:
239239
240240
# Components resolve from the current directory, not from the root's
241241
# identity, so a search path still finds them.
242-
./dist/xmd -e '<Badge />' --component-dir smoke-test --raw | grep -q '✓ verified'
242+
./dist/xmd -e '<Badge />' --include smoke-test --raw | grep -q '✓ verified'
243243
244244
# So does an ordinary relative filesystem read.
245245
./dist/xmd -e '<File path="smoke-test/Badge.md" />' --raw | grep -q 'verified'
@@ -379,7 +379,7 @@ jobs:
379379
- name: Smoke test xmd run through ACPX
380380
run: |
381381
./dist/xmd test smoke-test/agent/README.md \
382-
--component-dir smoke-test/agent/components \
382+
--include smoke-test/agent/components \
383383
--raw
384384
385385
# The host document-filesystem contract, on every target a release ships.

‎.github/workflows/repo-analysis.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,9 @@ jobs:
4848
GITHUB_REPOSITORY: ${{ github.repository }}
4949
run: |
5050
./dist/xmd run .reviews/AnalyzeRepoCI.md \
51-
--component-dir .reviews/components \
52-
--component-dir .reviews/policies \
53-
--component-dir packages/core/components \
51+
--include .reviews/components \
52+
--include .reviews/policies \
53+
--include packages/core/components \
5454
-j .reviews/journal.analyze.ci.jsonl > .reviews/analyze-report.md
5555
5656
- name: Write run metadata

‎.github/workflows/review.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@ jobs:
3838
DEEPINFRA_TOKEN: ${{ secrets.DEEPINFRA_TOKEN }}
3939
run: |
4040
./dist/xmd run .reviews/ReviewPR.md \
41-
--component-dir .reviews/components \
42-
--component-dir .reviews/policies \
43-
--component-dir packages/core/components \
41+
--include .reviews/components \
42+
--include .reviews/policies \
43+
--include packages/core/components \
4444
-j .reviews/journal.jsonl \
4545
--verbose
4646

‎architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2893,7 +2893,7 @@ check expressible against the shape is one a forger satisfies by construction.
28932893
And a reader that recognized an invocation by private state would recognize only
28942894
the copy of core it was imported with — while a component can be loaded from
28952895
disk beside its own copy, which is what the compiled CLI does for
2896-
`--component-dir`. Copy-local authentication and caller-visible behavior are the
2896+
`--include`. Copy-local authentication and caller-visible behavior are the
28972897
two wrong ownership sites.
28982898

28992899
So **invocation-form dispatch** owns it: the canonical, engine-owned association

‎deno.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -67,10 +67,10 @@
6767
"vendor:verify": "deno run --allow-read --allow-write=/tmp --allow-env --allow-run --cached-only --frozen scripts/verify-cloudflare-dofs.ts",
6868
"check": "deno check --frozen && deno check --frozen .reviews/components/*.ts",
6969
"check:jsr": "deno publish --dry-run --allow-dirty",
70-
"review": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.md --component-dir .reviews/components --component-dir .reviews/policies --component-dir packages/core/components -j .reviews/journal.jsonl",
71-
"review:local": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.local.md --component-dir .reviews/components --component-dir .reviews/policies --component-dir packages/core/components -j .reviews/journal.local.jsonl",
72-
"analyze": "deno run --allow-all packages/cli/src/deno.ts run .reviews/AnalyzeRepo.md --component-dir .reviews/components --component-dir .reviews/policies --component-dir packages/core/components -j .reviews/journal.analyze.jsonl",
73-
"analyze:ci": "deno run --allow-all packages/cli/src/deno.ts run .reviews/AnalyzeRepoCI.md --component-dir .reviews/components --component-dir .reviews/policies --component-dir packages/core/components -j .reviews/journal.analyze.ci.jsonl",
74-
"analyze:dispatch": "deno run --allow-all packages/cli/src/deno.ts run .reviews/DispatchRepoAnalysis.md --component-dir .reviews/components --component-dir .reviews/policies --component-dir packages/core/components -j .reviews/journal.dispatch.jsonl"
70+
"review": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.jsonl",
71+
"review:local": "deno run --allow-all packages/cli/src/deno.ts run .reviews/ReviewPR.local.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.local.jsonl",
72+
"analyze": "deno run --allow-all packages/cli/src/deno.ts run .reviews/AnalyzeRepo.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.analyze.jsonl",
73+
"analyze:ci": "deno run --allow-all packages/cli/src/deno.ts run .reviews/AnalyzeRepoCI.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.analyze.ci.jsonl",
74+
"analyze:dispatch": "deno run --allow-all packages/cli/src/deno.ts run .reviews/DispatchRepoAnalysis.md --include .reviews/components --include .reviews/policies --include packages/core/components -j .reviews/journal.dispatch.jsonl"
7575
}
7676
}

‎packages/cli/src/cli.ts‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ const runConfig = object({
164164
aliases: ["-e"],
165165
...field(z.string().optional()),
166166
},
167-
componentDir: {
167+
include: {
168168
description: "component search directory",
169169
...field(z.array(z.string()), field.default(["components", "."]), field.array()),
170170
},
@@ -226,7 +226,7 @@ const testConfig = object({
226226
description: "glob for test documents, relative to a directory target (repeatable)",
227227
...field(z.array(z.string()), field.default(["**/*.test.md"]), field.array()),
228228
},
229-
componentDir: {
229+
include: {
230230
description: "component search directory",
231231
...field(z.array(z.string()), field.default(["components", "."]), field.array()),
232232
},
@@ -538,7 +538,7 @@ function keepsProcessOutput(journal: string | undefined): boolean {
538538

539539
interface DocumentConfig {
540540
root: RootDocumentSource;
541-
componentDir: string[];
541+
include: string[];
542542
verbose: boolean;
543543
journal: string | undefined;
544544
raw: boolean;
@@ -662,8 +662,7 @@ function* runDocument(
662662
mode: DocumentMode,
663663
installService: HostServiceInstaller,
664664
): Operation<Result<void>> {
665-
const { root, componentDir, verbose, journal, raw, secretDetection, retainProcessOutput } =
666-
config;
665+
const { root, include, verbose, journal, raw, secretDetection, retainProcessOutput } = config;
667666

668667
// Every CLI invocation starts from an empty stream unless the caller owns
669668
// one. --journal writes current-run diagnostics only; existing traces are
@@ -744,7 +743,7 @@ function* runDocument(
744743
// before document code begins, so a child is offered exactly what this
745744
// command assembled — and never a second description of it.
746745
const testingHost = testingExecutionHost({
747-
componentDirs: componentDir,
746+
includes: include,
748747
secretDetection,
749748
installService,
750749
});
@@ -758,7 +757,7 @@ function* runDocument(
758757
...root,
759758
stream,
760759
props: mode.props,
761-
componentDirs: componentDir,
760+
includes: include,
762761
secretDetection,
763762
// Whatever the host path decided. A run that keeps nothing forwards its
764763
// commands' output to the reader and accumulates none of it.
@@ -972,7 +971,7 @@ function* test(
972971
{
973972
...config,
974973
root: { path: document.path },
975-
componentDir: componentSearchPath(document, target.root, config.componentDir),
974+
include: componentSearchPath(document, target.root, config.include),
976975
},
977976
{ testing: true },
978977
installService,
@@ -1829,7 +1828,7 @@ function* dispatch(
18291828
// search path would read the mutable checkout beside it, so a
18301829
// repository component fails to resolve rather than resolving
18311830
// to content the definition does not describe.
1832-
componentDir: [],
1831+
include: [],
18331832
verbose: request.verbose,
18341833
journal: undefined,
18351834
raw: request.raw,

‎packages/cli/src/testing-host.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ import type { HostServiceInstaller } from "./cli.ts";
4343
/** What the entrypoint already decided, and a child must not decide again. */
4444
export interface TestingHostSettings {
4545
/** The component search path this run resolves names through. */
46-
readonly componentDirs: string[];
46+
readonly includes: string[];
4747
/** Whether durable events are scanned for credentials before they persist. */
4848
readonly secretDetection: boolean;
4949
/** The native service adapter this entrypoint supplies. */
@@ -117,7 +117,7 @@ function* runProfileChild(
117117
...root,
118118
stream,
119119
props: request.props,
120-
componentDirs: settings.componentDirs,
120+
includes: settings.includes,
121121
secretDetection: settings.secretDetection,
122122
retainProcessOutput: diagnostic,
123123
},

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,14 +73,15 @@ describe("Tier CH — xmd help", { sanitizeOps: false, sanitizeResources: false
7373
expect(stdout).toContain("markdown document to execute");
7474
expect(stdout).toContain("-e, --eval");
7575
expect(stdout).toContain("Exactly one root document is required");
76-
expect(stdout).toContain("--component-dir");
76+
expect(stdout).toContain("--include");
7777
expect(stderr).not.toContain("Invalid input");
7878
});
7979

8080
it("CH3: xmd test --help prints test help", function* () {
8181
const { stdout } = yield* runCli(["test", "--help"]).expect();
8282
expect(stdout).toContain("Usage: xmd test [OPTIONS] [path]");
8383
expect(stdout).toContain("markdown document or directory to test");
84+
expect(stdout).toContain("--include");
8485
});
8586

8687
it("CH4: --version prints the version", function* () {

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

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import { expect } from "@executablemd/test-support/expect";
1414
import { runCli } from "@executablemd/test-support/launch";
1515
import { ensure, until } from "effection";
1616
import type { Operation } from "effection";
17-
import { readTextFile, rm, writeTextFile } from "@effectionx/fs";
17+
import { ensureDir, readTextFile, rm, writeTextFile } from "@effectionx/fs";
1818
import { mkdtemp, readdir } from "node:fs/promises";
1919
import { tmpdir } from "node:os";
2020
import { join } from "node:path";
@@ -201,12 +201,32 @@ describe(
201201
const implicit = yield* runCli(["-e", "<Greeting />\n", "--raw"], { cwd: root }).expect();
202202
expect(implicit.stdout).toContain("Hello from a component");
203203

204-
const explicit = yield* runCli(["-e", "<Greeting />\n", "--component-dir", ".", "--raw"], {
204+
const explicit = yield* runCli(["-e", "<Greeting />\n", "--include", ".", "--raw"], {
205205
cwd: root,
206206
}).expect();
207207
expect(explicit.stdout).toContain("Hello from a component");
208208
});
209209

210+
it("IE25: repeated includes are searched in caller order, replacing the defaults", function* () {
211+
const root = yield* useWorkspace({ "Greeting.md": "from the default path\n" });
212+
for (const dir of ["first", "second"]) {
213+
yield* ensureDir(join(root, dir));
214+
yield* writeTextFile(join(root, dir, "Greeting.md"), `from the ${dir} include\n`);
215+
}
216+
217+
const { stdout } = yield* runCli(
218+
["-e", "<Greeting />\n", "--include", "first", "--include", "second", "--raw"],
219+
{ cwd: root },
220+
).expect();
221+
222+
// Argv order is the search order…
223+
expect(stdout).toContain("from the first include");
224+
expect(stdout).not.toContain("from the second include");
225+
// …and an explicit value replaces the defaults rather than extending
226+
// them, so the candidate sitting on the default path never competes.
227+
expect(stdout).not.toContain("from the default path");
228+
});
229+
210230
it("IE18: running an inline document leaves the directory as it was", function* () {
211231
// The distinct fault this retained row catches: inline execution must
212232
// not add any top-level filesystem entry — a file, a directory, or a

‎packages/cli/tests/service-document.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ function* runDocument(stream: InMemoryStream): Operation<string> {
6262
yield* execute({
6363
path: "doc.md",
6464
stream,
65-
componentDirs: ["components", "."],
65+
includes: ["components", "."],
6666
}),
6767
);
6868
}),

0 commit comments

Comments
 (0)