T-FGMJ-intersect-test-corpus-and-fixtures

Status: closed/done · Impact: high · Complexity: medium

Goal

Stand up the Intersect package skeleton and a JSON-fixture test corpus that specifies the library’s full intended behavior before any engine exists, so every later task turns fixtures from pending to green against one readable, data-driven spec.

Today

There is no plugin/lib/intersect/ package yet; this task creates it from the existing template.

Location	Role today
plugin/lib/_example/	The package template a new lib clones — index.ts plus tests/.
docs/planning/decisions/D-4FRD-intersect-api/	The API + layered-architecture decision this corpus encodes as tests.

Proposed

plugin/lib/intersect/ exists with: the public type surface and throwing stubs for every documented operation; a documented JSON fixture convention (fixtures/README.md); the complete *.cases.json corpus covering the segment core, path API, registry, and fs layers; and a bun:test harness that loads every case file and runs each case (test when active, test.todo when pending). bun test is green with the un-implemented cases reported as todo.

Approach

1. Clone plugin/lib/_example/ into plugin/lib/intersect/ (index + tests/).
2. Define the fixture convention and document it in fixtures/README.md. A case file is { "op": <operation>, "cases": [ { "name", <inputs>, "expect" | "throws", "pending"? } ] }, where <inputs> vary by op: a/b for intersects/witness; path+patterns for matches/whichMatch; query+candidates for overlapping; entries+scope/path for the registry ops; plus an optional opts object.
3. Add fixtures.ts: types for a case file plus a loader and a shape guard, so a malformed fixture fails a schema-lint test.
4. Author the corpus, one file per area — segments.cases.json, path.cases.json, options.cases.json, overlapping-witness.cases.json, registry.cases.json, fs.cases.json — covering every case in AC-3. Mark every case pending: true.
5. Write the public surface as typed throwing stubs: segments/index.ts (intersects/matches/witness on SegmentPattern), index.ts (path API parse/intersects/matches/whichMatch/overlapping/witness/compile), registry.ts (index/Registry), fs.ts (filesInScope/resolveIntersection). Each throws new Error("not implemented").
6. Write tests/fixtures.test.ts: load all *.cases.json, dispatch each case by op to the public API, register it with test (active) or test.todo (pending), and assert the return equals expect or that it throws when throws is set.

Files to touch

Location	Kind	Change
plugin/lib/intersect/segments/index.ts	new	L0 segment-core types + throwing stubs.
plugin/lib/intersect/index.ts	new	L1 path-API types + throwing stubs (parse, primitives, compile).
plugin/lib/intersect/registry.ts	new	Labeled/Registry/index types + throwing stub.
plugin/lib/intersect/fs.ts	new	L2 filesInScope/resolveIntersection types + throwing stubs.
plugin/lib/intersect/fixtures.ts	new	Fixture types + loader + shape guard.
plugin/lib/intersect/fixtures/README.md	new	The JSON fixture convention.
plugin/lib/intersect/fixtures/*.cases.json	new	The test corpus (segments / path / options / overlapping-witness / registry / fs).
plugin/lib/intersect/tests/fixtures.test.ts	new	The fixture-driven harness.

Acceptance criteria

• AC-1: bun test plugin/lib/intersect exits 0; every un-implemented case is reported as a todo, not a failure.
• AC-2: fixtures/README.md documents the case-file schema, and a schema-lint test fails if any *.cases.json violates it.
• AC-3: The corpus includes at least one case for each of: exact-path match; subtree **; * and ?; braces {a,b}; character class […]; dotfile behavior; case-insensitivity; globstar-matches-zero; disjoint patterns → false; witness returns a common path; witness returns null; overlapping returns the correct candidate subset in order; registry preserves registration order; duplicate registry id throws.
• AC-4: bunx tsc --noEmit passes with the stubs in place.

Out of scope

• Any real matching / automaton logic — T-UY5H through T-ZAZO turn the pending cases green.
• Choosing the filesystem globber — T-ZAZO.

Dependencies

• none

Discovery context

• Implements D-4FRD-intersect-api under PR-0002-intersect; fixture-first so the spec is legible before the engine exists.

---

← Back to Tasks