Motivation
Executable Markdown needs deterministic file discovery for repository
instructions, test fixtures, source inspection, and workflow inputs. Authors
should be able to construct and verify the complete filesystem fixture in
Markdown.
This story follows schema-validated component returns (#176), <TempDir>
(#189), and <File> (#190).
Authoring contract
<Glob
include={["AGENTS.md", "**/AGENTS.md"]}
exclude={[".git/**", "**/node_modules/**"]}
as="instructionPaths"
/>
include is a required non-empty array of glob patterns.
exclude is an optional array and defaults to empty.
- Patterns evaluate relative to contextual
Env.cwd.
- Pattern syntax follows the filesystem glob library without an additional
component-specific dialect.
- Hidden files participate whenever the supplied pattern matches them; there is
no separate hidden-file prop.
- Exclusions win over inclusions.
- Only files are returned.
- Results are normalized relative paths with POSIX separators.
- Results are deduplicated and sorted lexically after normalization.
- No matches return an empty array.
- The component returns
string[], requires as, and renders nothing.
- A missing or non-directory
Env.cwd, invalid pattern, or filesystem traversal
failure fails the component.
Symlinks
The initial implementation never traverses symlinked directories.
@effectionx/fs exposes followSymlinks, but it does not enforce root
containment or detect traversal cycles, so it cannot safely provide internal
symlink traversal without custom traversal machinery.
A future implementation may traverse symlinked directories only if the
filesystem library directly guarantees that the resolved destination remains
inside Env.cwd and traversal is cycle-safe.
Testing
Add a colocated Glob.test.md that uses <TempDir> and <File> without
JavaScript. It covers:
- one and multiple include patterns;
- nested
** matching;
- exclusions taking precedence;
- deterministic lexical ordering;
- deduplication across overlapping include patterns;
- normalized relative paths;
- files only;
- hidden-file matching through ordinary pattern semantics; and
- an empty array when nothing matches.
Add lower-level automated tests for:
- required
include, required as, and prop validation;
- invalid glob patterns;
- missing and non-directory working directories;
- filesystem read failures;
- directory symlinks not being traversed;
- symlinks that point outside the working directory;
- cancellation during traversal; and
- deterministic return capture and replay.
Documentation
- Specify props, pattern dialect, ordering, normalization, and failure behavior
in the component reference.
- Add a website example using
<TempDir>, <File>, and <Glob> together.
- Document that hidden files follow literal pattern matching and directory
symlinks are not traversed.
Acceptance criteria
<Glob> returns the deterministic normalized string[] selected by
include minus exclude.
- Empty matches succeed with
[].
- Directory entries and files reached only through directory symlinks are not
returned.
- The component emits no Markdown and requires a capture name.
Glob.test.md exercises the public matching contract entirely in Markdown.
- Lower-level tests cover validation, failures, symlinks, cancellation, and
replay across the supported runtime matrix.
- Specification and website documentation ship in the same PR.
Not included
- Returning directories or filesystem metadata.
- A configurable root separate from
Env.cwd.
- Directory symlink traversal.
- A hidden-file prop.
- Custom pattern syntax.
Motivation
Executable Markdown needs deterministic file discovery for repository
instructions, test fixtures, source inspection, and workflow inputs. Authors
should be able to construct and verify the complete filesystem fixture in
Markdown.
This story follows schema-validated component returns (#176),
<TempDir>(#189), and
<File>(#190).Authoring contract
<Glob include={["AGENTS.md", "**/AGENTS.md"]} exclude={[".git/**", "**/node_modules/**"]} as="instructionPaths" />includeis a required non-empty array of glob patterns.excludeis an optional array and defaults to empty.Env.cwd.component-specific dialect.
no separate hidden-file prop.
string[], requiresas, and renders nothing.Env.cwd, invalid pattern, or filesystem traversalfailure fails the component.
Symlinks
The initial implementation never traverses symlinked directories.
@effectionx/fsexposesfollowSymlinks, but it does not enforce rootcontainment or detect traversal cycles, so it cannot safely provide internal
symlink traversal without custom traversal machinery.
A future implementation may traverse symlinked directories only if the
filesystem library directly guarantees that the resolved destination remains
inside
Env.cwdand traversal is cycle-safe.Testing
Add a colocated
Glob.test.mdthat uses<TempDir>and<File>withoutJavaScript. It covers:
**matching;Add lower-level automated tests for:
include, requiredas, and prop validation;Documentation
in the component reference.
<TempDir>,<File>, and<Glob>together.symlinks are not traversed.
Acceptance criteria
<Glob>returns the deterministic normalizedstring[]selected byincludeminusexclude.[].returned.
Glob.test.mdexercises the public matching contract entirely in Markdown.replay across the supported runtime matrix.
Not included
Env.cwd.