Skip to content

Add a deterministic contextual Glob component #191

Description

@taras

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions