fix(konsistent): match variable-depth ** alongside {placeholder} and excludeFiles globs

Path matching required the pattern and matched path to have the same
number of segments when extracting placeholder values. This made any
`**` segment collapse to matching exactly one directory level whenever
the pattern also contained a `{placeholder}`, silently dropping
candidates at every other depth (#56).

`excludeFiles` entries hit the same equal-segment-count check, so a
`**/`-prefixed entry (as shown in docs/reference/configuration.md)
never matched and the file stayed in scope (#57).

Path segment matching now backtracks through candidate consumption
counts for `**`, so it can reconcile a variable-depth wildcard with
placeholder extraction and with plain excludeFiles glob patterns.

Author: mliem2k

.changeset/fix-double-star-placeholder-matching.md

@@ -0,0 +1,8 @@
+---
+"@konsistent/convention": patch
+"konsistent": patch
+---
+
+fix(konsistent): match variable-depth `**` alongside `{placeholder}` segments and glob-style `excludeFiles` patterns
+
+`**` in a `paths` pattern next to a `{placeholder}` segment previously only matched a single intermediate directory level instead of every depth, because placeholder extraction required the pattern and path to have the same number of segments. `excludeFiles` entries prefixed with `**/` were silently ignored for the same reason. Path matching now backtracks through variable-depth `**` segments when extracting placeholders and when matching `excludeFiles` glob patterns, so both now behave as documented.

e2e/fixtures/exclude-files/konsistent.json

@@ -16,7 +16,7 @@
       "must": [
         {
           "for": { "files": "{testFile}.spec.ts" },
-          "excludeFiles": ["plugins/auth/helpers.spec.ts"],
+          "excludeFiles": ["**/helpers.spec.ts"],
           "must": {
             "export": ["describe"]
           }

packages/konsistent/src/core/path-matcher.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 import type { FileSystem } from "./filesystem.js";
-import { hasPlaceholders, matchPaths, patternToGlob } from "./path-matcher.js";
+import {
+  hasPlaceholders,
+  matchesPathPattern,
+  matchPaths,
+  patternToGlob,
+} from "./path-matcher.js";
 
 function createMockFileSystem(opts: {
   globResults?: Map<string, string[]>;
@@ -376,4 +381,111 @@ describe("matchPaths", () => {
     });
     expect(results).toHaveLength(2);
   });
+
+  it("plain ** without a placeholder matches every depth (baseline, no regression)", async () => {
+    const fs = createMockFileSystem({
+      globResults: new Map([
+        ["deep/**/*.ts", ["deep/top.ts", "deep/a/mid.ts", "deep/a/b/leaf.ts"]],
+      ]),
+    });
+    const results = await matchPaths({
+      patterns: ["deep/**/*.ts"],
+      fileSystem: fs,
+    });
+    expect(results).toHaveLength(3);
+    expect(results.every((r) => Object.keys(r.placeholders).length === 0)).toBe(
+      true
+    );
+  });
+
+  it("`**` adjacent to a `{placeholder}` matches every depth (#56 regression)", async () => {
+    const fs = createMockFileSystem({
+      globResults: new Map([
+        ["deep/**/*.ts", ["deep/top.ts", "deep/a/mid.ts", "deep/a/b/leaf.ts"]],
+      ]),
+    });
+    const results = await matchPaths({
+      patterns: ["deep/**/{name}.ts"],
+      fileSystem: fs,
+    });
+    expect(results).toHaveLength(3);
+
+    const byPath = new Map(
+      results.map((r) => [r.path, r.placeholders.name.toString()])
+    );
+    expect(byPath.get("deep/top.ts")).toBe("top");
+    expect(byPath.get("deep/a/mid.ts")).toBe("mid");
+    expect(byPath.get("deep/a/b/leaf.ts")).toBe("leaf");
+  });
+
+  it("`**` before a placeholder still enforces multi-placeholder consistency", async () => {
+    const fs = createMockFileSystem({
+      globResults: new Map([
+        ["deep/**/*/*.ts", ["deep/a/b/auth/auth.ts", "deep/a/b/auth/other.ts"]],
+      ]),
+    });
+    const results = await matchPaths({
+      patterns: ["deep/**/{name}/{name}.ts"],
+      fileSystem: fs,
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0].path).toBe("deep/a/b/auth/auth.ts");
+    expect(results[0].placeholders.name.toString()).toBe("auth");
+  });
+});
+
+describe("matchesPathPattern", () => {
+  it("matches a **/ prefixed pattern against a nested file", () => {
+    expect(
+      matchesPathPattern({
+        pattern: "**/__test-env-tdd-state.ts",
+        filePath: "foo/__test-env-tdd-state.ts",
+      })
+    ).toBe(true);
+  });
+
+  it("matches a **/ prefixed pattern regardless of nesting depth", () => {
+    expect(
+      matchesPathPattern({
+        pattern: "**/__test-env-tdd-state.ts",
+        filePath: "foo/bar/baz/__test-env-tdd-state.ts",
+      })
+    ).toBe(true);
+  });
+
+  it("matches a **/ prefixed pattern at the root (zero intermediate segments)", () => {
+    expect(
+      matchesPathPattern({
+        pattern: "**/*.test.ts",
+        filePath: "foo.test.ts",
+      })
+    ).toBe(true);
+  });
+
+  it("matches a trailing ** pattern against any nested file", () => {
+    expect(
+      matchesPathPattern({
+        pattern: "src/internal/**",
+        filePath: "src/internal/deep/file.ts",
+      })
+    ).toBe(true);
+  });
+
+  it("does not match unrelated paths", () => {
+    expect(
+      matchesPathPattern({
+        pattern: "**/__test-env-tdd-state.ts",
+        filePath: "foo/other.ts",
+      })
+    ).toBe(false);
+  });
+
+  it("still matches exact literal paths without wildcards", () => {
+    expect(
+      matchesPathPattern({
+        pattern: "src/internal.ts",
+        filePath: "src/internal.ts",
+      })
+    ).toBe(true);
+  });
 });

packages/konsistent/src/core/path-matcher.ts

@@ -179,41 +179,133 @@ function mergeExtracted(opts: {
   return true;
 }
 
+/*
+ * Matches pattern segments against path segments, extracting placeholder
+ * values along the way. Unlike a simple index-by-index walk, this supports a
+ * `**` pattern segment consuming a variable number of path segments (zero or
+ * more), backtracking through candidate consumption counts until the rest of
+ * the pattern also matches. This is what lets `**` coexist with `{placeholder}`
+ * segments elsewhere in the same pattern — e.g. `deep/**\/{name}.ts` matching
+ * `deep/top.ts`, `deep/a/mid.ts`, and `deep/a/b/leaf.ts` alike.
+ */
+function matchPatternSegments(opts: {
+  patternSegments: string[];
+  pathSegments: string[];
+  patternIndex: number;
+  pathIndex: number;
+}): ExtractedValues | null {
+  const { patternSegments, pathSegments, patternIndex, pathIndex } = opts;
+
+  if (patternIndex === patternSegments.length) {
+    return pathIndex === pathSegments.length
+      ? { values: {}, constraints: {} }
+      : null;
+  }
+
+  const segment = patternSegments[patternIndex];
+
+  if (segment === "**") {
+    for (
+      let consumedUpTo = pathIndex;
+      consumedUpTo <= pathSegments.length;
+      consumedUpTo++
+    ) {
+      const rest = matchPatternSegments({
+        patternSegments,
+        pathSegments,
+        patternIndex: patternIndex + 1,
+        pathIndex: consumedUpTo,
+      });
+      if (rest !== null) {
+        return rest;
+      }
+    }
+    return null;
+  }
+
+  if (pathIndex >= pathSegments.length) {
+    return null;
+  }
+
+  const segmentResult = extractValueFromSegment({
+    patternSegment: segment,
+    pathSegment: pathSegments[pathIndex],
+  });
+  if (segmentResult === null) {
+    return null;
+  }
+
+  const rest = matchPatternSegments({
+    patternSegments,
+    pathSegments,
+    patternIndex: patternIndex + 1,
+    pathIndex: pathIndex + 1,
+  });
+  if (rest === null) {
+    return null;
+  }
+
+  const values = { ...segmentResult.values };
+  if (!mergeExtracted({ existing: values, incoming: rest.values })) {
+    return null;
+  }
+
+  return {
+    values,
+    constraints: { ...segmentResult.constraints, ...rest.constraints },
+  };
+}
+
 function tryExtractPlaceholders(opts: {
   pattern: string;
   pathSegments: string[];
 }): Record<string, string> | null {
   const { pattern, pathSegments } = opts;
   const patternSegments = pattern.split("/");
-  if (patternSegments.length !== pathSegments.length) {
-    return null;
-  }
 
-  const extracted: Record<string, string> = {};
-  const allConstraints: Record<string, string> = {};
-  for (let i = 0; i < patternSegments.length; i++) {
-    const segmentResult = extractValueFromSegment({
-      patternSegment: patternSegments[i],
-      pathSegment: pathSegments[i],
-    });
-    if (segmentResult === null) {
-      return null;
-    }
-    if (
-      !mergeExtracted({ existing: extracted, incoming: segmentResult.values })
-    ) {
-      return null;
-    }
-    Object.assign(allConstraints, segmentResult.constraints);
+  const matched = matchPatternSegments({
+    patternSegments,
+    pathSegments,
+    patternIndex: 0,
+    pathIndex: 0,
+  });
+  if (matched === null) {
+    return null;
   }
 
   if (
-    !satisfiesConstraints({ values: extracted, constraints: allConstraints })
+    !satisfiesConstraints({
+      values: matched.values,
+      constraints: matched.constraints,
+    })
   ) {
     return null;
   }
 
-  return extracted;
+  return matched.values;
+}
+
+/*
+ * Tests whether a single file path matches a path pattern, supporting the
+ * same glob syntax as `paths` (`*`, `?`, and variable-depth `**`), without
+ * extracting placeholder values. Used for `excludeFiles` patterns, which are
+ * plain glob patterns rather than placeholder patterns.
+ */
+export function matchesPathPattern(opts: {
+  pattern: string;
+  filePath: string;
+}): boolean {
+  const { pattern, filePath } = opts;
+  const patternSegments = pattern.split("/");
+  const pathSegments = filePath.split("/");
+  return (
+    matchPatternSegments({
+      patternSegments,
+      pathSegments,
+      patternIndex: 0,
+      pathIndex: 0,
+    }) !== null
+  );
 }
 
 function toPlaceholderMap(opts: {

packages/konsistent/src/core/runner.test.ts

@@ -974,6 +974,29 @@ describe("excludeFiles", () => {
     expect(diagnostics).toEqual([]);
   });
 
+  it("convention-level excludeFiles with a **/ prefixed pattern skips matching file (#57 regression)", async () => {
+    const config: ConfigV1 = {
+      version: "v1",
+      conventions: [
+        {
+          name: "source-files",
+          paths: "foo/**/*.ts",
+          excludeFiles: ["**/__test-env-tdd-state.ts"],
+          must: { haveType: "file" },
+        },
+      ],
+    };
+    const fs = createMockFileSystem({
+      globResults: new Map([
+        ["foo/**/*.ts", ["foo/__test-env-tdd-state.ts", "foo/utils.ts"]],
+      ]),
+      directories: new Set(["foo/__test-env-tdd-state.ts"]),
+      files: new Set(["foo/utils.ts"]),
+    });
+    const { diagnostics } = await run({ config, fileSystem: fs });
+    expect(diagnostics).toEqual([]);
+  });
+
   it("convention-level excludeFiles does not skip non-matching file", async () => {
     const config: ConfigV1 = {
       version: "v1",

packages/konsistent/src/core/runner.ts

@@ -32,7 +32,7 @@ import type { Diagnostic, DiagnosticSeverity } from "./diagnostics.js";
 import { createDiagnostic } from "./diagnostics.js";
 import type { FileSystem } from "./filesystem.js";
 import type { MatchedPath } from "./path-matcher.js";
-import { matchPaths } from "./path-matcher.js";
+import { matchesPathPattern, matchPaths } from "./path-matcher.js";
 import { PlaceholderValue } from "./placeholder.js";
 import {
   parsePlaceholderConstraint,
@@ -191,6 +191,9 @@ function isFileExcluded(opts: {
     if (filePath === resolved || basename(filePath) === resolved) {
       return true;
     }
+    if (matchesPathPattern({ pattern: resolved, filePath })) {
+      return true;
+    }
   }
   return false;
 }