💥 Say where components come from with --include - #631
Conversation
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
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
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
PR #631: 💥 Say where components come from with --include62 files, +320 / -220 Scope🟡 540 lines changed. PRs under 400 receive more thorough review. 🟡 62 files changed. Are all changes related? 🟡 Changes span 15 directories. 🟡 PR mixes config and source changes. StructuralOxlint structural signals:
SlopOxlint slop signals:
Static AnalysisOxlint: 40 diagnostics across 6 files (12 rules) no-unsafe-type-assertion (12): packages/cli/src/cli.ts, packages/core/src/invocation-identity.ts, packages/core/src/execute.ts CorrectnessNo extraneous code patterns detected. |
`deno fmt` owns `site/`, and the option name lost eight characters, so the line it was wrapped for now fits differently.
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
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
Uh oh!
There was an error while loading. Please reload this page.
Closes#271.
Why
componentDirsnamed a thing the rest of the vocabulary already had a betterword for. The configured directories a document resolves components from are now
includes, and the flag that names one is
--include.This is a 💥 clean break, and a total one: nothing has been released that names
the old spelling, so no code in the repository mentions it either.
What changes
DEFAULT_COMPONENT_DIRSDEFAULT_INCLUDEScomponentDirs(programmatic)includescomponentDir(configliere field, CLI-private)include--component-dir--includeBefore:
After:
The old flag is simply an option xmd does not define, handled exactly as any
other undefined option is. It gets no refusal, no alias and no special case,
because there is no caller to tell — see Intentionally unchanged.
“Component search path” and “component search directory” do not change. They
remain the names of the complete ordered resolution path and of one directory on
it. Includes name only the configured contribution to that path, so
componentSearchPath()keeps its name and the prose was reviewed occurrence byoccurrence rather than replaced.
How it works
The CLI keeps two spellings on purpose.
runConfig.include,testConfig.includeandDocumentConfig.includeare singular becauseconfigliere derives
--includefrom the field name; everything at theprogrammatic boundary is plural —
ExecuteSettings.includes,SelectOptions.includes,InspectComponentOptions.includes,TestingHostSettings.includes.runDocumentmaps one to the other. No customargv parsing was added: configliere's existing array field already gives ordered
repeats that replace the default.
Review guide
Start with:
packages/core/src/components/select.tsThen review:
packages/core/mod.ts,execute.ts,inspect.ts— the public surfacepackages/cli/src/cli.ts— the schemas and the singular/plural boundarypackages/core/src/execution-request.ts— the middleware snapshot stilldetaches and freezes
What must stay true
git grep -nE 'componentDirs|componentDir|DEFAULT_COMPONENT_DIRS|--component-dir' -- .returning nothing. That grep is the whole of the absence claim; no test
restates it.
includes: []uses none — enforced byoptions.includes ?? DEFAULT_INCLUDES, checked by CR37.include: []at workflow assembly, checked byworkflow-component-bundleandworkflow-bundle.first duplicate wins — enforced by
componentSearchPath(), checked by DT32.How to verify it
DEFAULT_INCLUDESis["components", "."]and thatmod.tsexports it.
??semantics and that the default array is copied, notshared. Fails if
||is used or[]is widened to the defaults.--includeare searched in caller order and thatexplicit values replace rather than extend the defaults: a same-named
component sits on the default path and loses.
spelled exactly and one spelled differently but resolving the same.
<Execution host="run">resolves acomponent only through the outer command's
--include, with the bare run asthe negative control.
--include.Scope
Included
deno.jsontasks, theCI/review/repo-analysis workflows, smoke scripts, specs, architecture and site
copy — one commit's worth of change, because either half alone leaves
maincontradicting its own API or unable to run its own commands.
Intentionally unchanged
first token it does not recognize rather than rejecting it, so the retired
flag is dropped in silence like any typo. An earlier revision of this branch
added a refusal for it; that was removed once it was established there are no
users to migrate. Refusing unknown options in general is a separate concern
and not this PR's.
deprecation leaves nothing that could still answer to the old spelling, and a
test naming it — necessarily by assembling the string, since the audit forbids
the literal — would reintroduce the very name it checks for. The
git grepaudit above is the single place absence is claimed.
searcheddiagnostic, theunresolved message, journal shape and replay.
componentSearchPath()and the words “component search path” and “componentsearch directory”.
specs/release-process-spec.md: no release configuration changed.Generated or mechanical changes
behavior change. The parts that are not:
packages/core/src/components/select.ts,execute.ts,inspect.ts,execution-request.ts,mod.ts,packages/cli/src/cli.ts,packages/cli/src/testing-host.ts, and the regressions incomponent-registration.test.ts,inline-cli.test.ts,test-target.test.ts,testing-execution-host.test.ts.Risks and limitations
The zero-match audit is the controlling evidence and it is clean.
the default path instead. Accepted deliberately: there is no released binary
naming it.
mainand still adds the old spellings. It isnot stacked here, and must adopt
--includewhile rebasing after this lands.migrated.
Scope confirmation