fix: .match() returns 'covers' (not 'parent') for deep template vs concrete

When `this` contained DEEP_WILDCARD, matchesPrefix could succeed against a
longer `other` by collapsing `**`, and the old code interpreted that as
"this is a literal prefix of other" → "parent". It also returned `null`
for `a.**.b vs a.b` because patternMatches required equal lengths.

Two fixes:
- patternMatches now supports `**` collapsing zero-or-more segments (was
  equal-length-only). This is the relation the docs describe as "covers".
- match() checks wildcard coverage BEFORE literal parent/child, and gates
  the parent/child branches on the shorter side being wildcard-free. A
  wildcard prefix is not a literal prefix.

Tests:
- deep template vs longer concrete → covers / covered-by (was parent/child)
- deep template vs shorter concrete (** collapses to zero) → covers (was null)
- single-* template vs equal-length concrete unchanged

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sergeyshmakov

src/impl/base-path-impl.ts

@@ -7,6 +7,7 @@ import type {
 	TemplatePath,
 } from "../types.js";
 import {
+	hasWildcardSegment,
 	matchesPrefix,
 	patternMatches,
 	resolveSegments,
@@ -56,19 +57,30 @@ export abstract class AbstractPathImpl<T = unknown, V = unknown> {
 	match(other: ResolvablePath<T>): MatchResult | null {
 		const otherSegs = resolveSegments(other);
 		if (segmentsEqual(this.segments, otherSegs)) return { relation: "equals" };
+
+		// Check wildcard coverage BEFORE literal prefix. patternMatches handles
+		// `**` collapsing, so a deep template can fully cover a concrete path of
+		// any length — that's a "covers", not "parent". Order matters: a literal
+		// prefix check that's wildcard-aware (via matchesPrefix) would otherwise
+		// misclassify "a.**.b covers a.x.y.b" as "parent".
+		if (patternMatches(this.segments, otherSegs)) return { relation: "covers" };
+		if (patternMatches(otherSegs, this.segments))
+			return { relation: "covered-by" };
+
+		// Literal parent/child: the shorter side must be wildcard-free, otherwise
+		// it's not a literal prefix.
 		if (
+			!hasWildcardSegment(otherSegs) &&
 			matchesPrefix(this.segments, otherSegs) &&
 			this.segments.length > otherSegs.length
 		)
 			return { relation: "child" };
 		if (
+			!hasWildcardSegment(this.segments) &&
 			matchesPrefix(otherSegs, this.segments) &&
 			otherSegs.length > this.segments.length
 		)
 			return { relation: "parent" };
-		if (patternMatches(this.segments, otherSegs)) return { relation: "covers" };
-		if (patternMatches(otherSegs, this.segments))
-			return { relation: "covered-by" };
 		return null;
 	}
 

src/tests/interactions.spec.ts

@@ -120,6 +120,40 @@ describe("Path interactions", () => {
 			expect(a.match(b)?.relation).toBe("equals");
 		});
 
+		it("deep template returns 'covers' against a longer concrete (** collapse)", () => {
+			interface Node {
+				value: string;
+				children: Node[];
+			}
+			interface Root {
+				tree: Node;
+			}
+			const deep = path((p: Root) => p.tree).deep((n) => n.value);
+			const deeper = path((p: Root) => p.tree.children[0].value);
+			// Pre-fix bug: returned "parent" because matchesPrefix(other, this)
+			// was true via ** expansion AND otherSegs.length > this.segments.length.
+			expect(deep.match(deeper)?.relation).toBe("covers");
+			expect(deeper.match(deep)?.relation).toBe("covered-by");
+		});
+
+		it("deep template returns 'covers' against a shorter concrete (** collapses to zero)", () => {
+			interface Data {
+				a: { b: string };
+			}
+			const deep = path((p: Data) => p.a).deep((n) => n.b);
+			const shorter = path((p: Data) => p.a.b);
+			// Pre-fix bug: returned null because patternMatches required equal lengths.
+			expect(deep.match(shorter)?.relation).toBe("covers");
+			expect(shorter.match(deep)?.relation).toBe("covered-by");
+		});
+
+		it("single-* template returns 'covers' for an equal-length concrete (unchanged behaviour)", () => {
+			const tmpl = path((p: R) => p.items).each((i) => i.name);
+			const concrete = path((p: R) => p.items[0].name);
+			expect(tmpl.match(concrete)?.relation).toBe("covers");
+			expect(concrete.match(tmpl)?.relation).toBe("covered-by");
+		});
+
 		it("immutability: does not mutate original path", () => {
 			const concrete = path((p: R) => p.items[0].name);
 			const template = path((p: R) => p.items).each(

src/utils.ts

@@ -85,18 +85,48 @@ export function matchesPrefix(
 	return p === prefix.length;
 }
 
+/**
+ * Returns `true` iff `pattern` matches `concrete` exactly when wildcards
+ * are expanded:
+ *   - `WILDCARD` (`*`) consumes exactly one segment.
+ *   - `DEEP_WILDCARD` (`**`) consumes zero or more segments.
+ *   - all other segments must be `===` to the corresponding concrete segment.
+ *
+ * Lengths need not match: a single `**` lets the pattern collapse to a
+ * shorter concrete or stretch to a longer one. This is the "covers"
+ * relation used by `.match()` and is broader than `matchesPrefix`, which
+ * only requires the pattern to match a leading slice.
+ */
 export function patternMatches(
 	pattern: readonly Segment[],
 	concrete: readonly Segment[],
 ): boolean {
-	if (pattern.length !== concrete.length) return false;
-	for (let i = 0; i < pattern.length; i++) {
-		if (
-			pattern[i] !== WILDCARD &&
-			pattern[i] !== DEEP_WILDCARD &&
-			pattern[i] !== concrete[i]
-		)
+	function walk(pi: number, ci: number): boolean {
+		if (pi === pattern.length) return ci === concrete.length;
+		const seg = pattern[pi];
+		if (seg === DEEP_WILDCARD) {
+			for (let skip = 0; ci + skip <= concrete.length; skip++) {
+				if (walk(pi + 1, ci + skip)) return true;
+			}
 			return false;
+		}
+		if (ci === concrete.length) return false;
+		if (seg === WILDCARD) return walk(pi + 1, ci + 1);
+		if (seg !== concrete[ci]) return false;
+		return walk(pi + 1, ci + 1);
+	}
+	return walk(0, 0);
+}
+
+function hasWildcardSegment(segments: readonly Segment[]): boolean {
+	for (const s of segments) {
+		if (s === WILDCARD || s === DEEP_WILDCARD) return true;
 	}
-	return true;
+	return false;
 }
+
+/**
+ * Returns `true` iff `segments` contains a wildcard sentinel
+ * (`WILDCARD` or `DEEP_WILDCARD`).
+ */
+export { hasWildcardSegment };