fix(runtime): search the whole rule for stray modules, not two directories

`strayModules` listed the immediate entries of the rule root and `captures/`
and nothing else, so any nested directory evaded it completely. Create
`<rule>/lib/helper.ts`, have `check.ts` import it, and the rule discovered
as clean while unsigned code ran and `check.ts` still matched its blessed
signature.

The threat model was stated correctly and implemented as something narrower.
"One import away" is not "one directory away": `import "./lib/helper.ts"`
reaches an arbitrarily deep relative path in a single hop, exactly like
`import "./helper.ts"`. Bounding the search to two directories left the hole
this slice exists to close, in the slice that closes it.

Now walks the whole rule directory, excluding `.tests/` at any depth for the
reason already documented: fixtures are data a check reads, and a fixture
that is itself TypeScript is the normal case.

Also considers only files. `readdir` returns directories too, so a directory
named `helper.ts` would have been reported as a stray module — a false
positive refusing a fine rule with an error naming something that cannot
run. `withFileTypes` plus `isFile()` was needed for the recursion anyway.

An unreadable directory now propagates instead of being swallowed, matching
`isMissingDirectory`'s contract: reading `EACCES` as "nothing here" would
make an unsearchable rule indistinguishable from a clean one, which is the
same failure this whole guard exists to prevent.

Four new cases cover the gap — `lib/helper.ts`, `captures/nested/helper.js`,
`a/b/c/deep.mjs`, and a directory named `helper.ts`. Reverting the recursion
fails exactly those and leaves the three root-level cases passing, so they
detect the gap rather than the guard's existence.

Found by the review on #217.

Author: theCodeDrift

.changeset/generator-payload-alignment.md

@@ -69,6 +69,8 @@ relative import away — so tampering with it bypasses the gate while `check.ts`
 still matches its blessed digest. Such a rule is refused, and `verify` names
 the file.
 
-Every extension a check could import is covered, not only `.ts`. A rule's
-`.tests/` fixtures are excluded, since a check reads real files under a root
-and a fixture that is itself TypeScript is ordinary.
+Every extension a check could import is covered, not only `.ts`, and the
+search is recursive: "one import away" is not "one directory away", so a
+nested directory would otherwise carry unsigned code straight past the check.
+A rule's `.tests/` fixtures are excluded at any depth, since a check reads
+real files under a root and a fixture that is itself TypeScript is ordinary.

openspec/changes/generator-payload-alignment/specs/cli-runtime-rule-execution/spec.md

@@ -56,14 +56,20 @@ this requirement makes the guarantee enforced rather than trusted.
 "Module file" SHALL cover every extension a check could import, not only `.ts`: the loader
 transpiles TypeScript, but a `.js` sibling resolves just as readily.
 
+The search SHALL be recursive. "One import away" is not "one directory away" — a single
+`import "./lib/helper.ts"` reaches an arbitrarily deep relative path in one hop — so a search
+bounded to the rule root would let any nested directory carry unsigned code past the check while
+`check.ts` still matched its blessed signature. The search SHALL also consider only files, so a
+directory whose name ends in a module extension is not reported as one.
+
 The rule's `.tests/` directory SHALL be excluded from this search. A runtime check reads real
 files under a root, so a fixture that is itself TypeScript is the normal case rather than a
 smuggled helper, and refusing it would break correct rules — a worse failure than the one being
 prevented.
 
 #### Scenario: A helper module beside check.ts is refused
 
-- **WHEN** a runtime rule directory contains `check.ts` and any other module file, at its root or under `captures/`
+- **WHEN** a runtime rule directory contains `check.ts` and any other module file, at any depth
 - **THEN** the CLI SHALL refuse the rule and name the offending file
 - **AND** SHALL NOT execute its `check.ts`
 

packages/cli/src/rules/runtime/discover.ts

@@ -3,12 +3,14 @@ import { join } from "node:path";
 
 import { parse } from "yaml";
 
+import { isMissingDirectory } from "../errno";
+
 import {
   MATCH_MODES,
   SUPPORTED_METADATA_VERSIONS,
 } from "../../types/runtime-rule";
 import type { CaptureRule, MatchMode } from "../../types/runtime-rule";
-import { RULES_DIRECTORY } from "../layout";
+import { RULES_DIRECTORY, RULE_TESTS_DIRECTORY } from "../layout";
 
 /**
  * Directory (relative to `.taskless/`) that holds runtime rules — the
@@ -82,22 +84,46 @@ const MODULE_EXTENSIONS = [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"];
 
 export async function strayModules(ruleDirectory: string): Promise<string[]> {
   const stray: string[] = [];
-  for (const relative of ["", CAPTURES_DIRECTORY]) {
-    const directory =
-      relative === "" ? ruleDirectory : join(ruleDirectory, relative);
-    let entries: string[];
+
+  // RECURSIVE, because "one import away" is not "one directory away". A single
+  // `import "./lib/helper.ts"` reaches an arbitrarily deep relative path in one
+  // hop, so scanning only the rule root and `captures/` would let any nested
+  // directory carry unsigned code straight past this check while `check.ts`
+  // still matched its blessed signature.
+  async function walk(directory: string, prefix: string): Promise<void> {
+    let entries;
     try {
-      entries = await readdir(directory);
-    } catch {
-      continue;
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      // A directory that is genuinely absent contributes nothing. Anything
+      // else is a real IO problem and must not be read as "nothing here",
+      // because that is indistinguishable from a clean rule.
+      if (isMissingDirectory(error)) return;
+      throw error;
     }
-    for (const name of entries) {
-      if (relative === "" && name === CHECK_FILE) continue;
-      if (MODULE_EXTENSIONS.some((extension) => name.endsWith(extension))) {
-        stray.push(relative === "" ? name : `${relative}/${name}`);
+    for (const entry of entries) {
+      const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) {
+        // Fixtures are data the check reads, not modules it imports; see the
+        // note above on why searching them would refuse correct rules.
+        if (relative === RULE_TESTS_DIRECTORY) continue;
+        await walk(join(directory, entry.name), relative);
+        continue;
+      }
+      // `isFile()` rather than a name test: a DIRECTORY named `helper.ts`
+      // is not an executable file, and reporting it would refuse a fine rule
+      // with an error naming something that cannot run.
+      if (!entry.isFile()) continue;
+      if (relative === CHECK_FILE) continue;
+      if (
+        MODULE_EXTENSIONS.some((extension) => entry.name.endsWith(extension))
+      ) {
+        stray.push(relative);
       }
     }
   }
+
+  await walk(ruleDirectory, "");
   return stray.toSorted();
 }
 

packages/cli/test/engine-dispatch.test.ts

@@ -440,6 +440,11 @@ describe("engine dispatch by directory", () => {
     ["helper.mjs", "helper.mjs"],
     // Reachable from check.ts by a relative import just the same.
     ["captures/helper.ts", "captures/helper.ts"],
+    // "One import away" is not "one directory away": a single
+    // `import "./lib/helper.ts"` reaches any depth in one hop.
+    ["lib/helper.ts", "lib/helper.ts"],
+    ["captures/nested/helper.js", "captures/nested/helper.js"],
+    ["a/b/c/deep.mjs", "a/b/c/deep.mjs"],
   ])(
     "refuses a runtime rule carrying %s beside check.ts",
     async (path, named) => {
@@ -455,6 +460,12 @@ describe("engine dispatch by directory", () => {
         "utf8"
       );
       await writeFile(join(rule, "check.ts"), RUNTIME_CHECK, "utf8");
+      // Parent computed from the delivered path rather than via `dirname`, to
+      // keep this test off the shared import line.
+      const slash = path.lastIndexOf("/");
+      if (slash > 0) {
+        await mkdir(join(rule, path.slice(0, slash)), { recursive: true });
+      }
       await writeFile(join(rule, path), "export const x = 1;\n", "utf8");
 
       // Only check.ts is signed, so a second module is code reachable from a
@@ -470,6 +481,23 @@ describe("engine dispatch by directory", () => {
     }
   );
 
+  it("does not report a directory whose name ends in a module extension", async () => {
+    // `readdir` returns directories too. A directory named `helper.ts` cannot
+    // execute, so refusing the rule would be a false positive naming something
+    // that is not a file.
+    const rule = ruleDirectory(temporaryDirectory, "runtime", "logs-abc12345");
+    await mkdir(join(rule, "captures"), { recursive: true });
+    await mkdir(join(rule, "helper.ts"), { recursive: true });
+    await writeFile(
+      join(rule, "captures", "logs.yml"),
+      RUNTIME_CAPTURE,
+      "utf8"
+    );
+    await writeFile(join(rule, "check.ts"), RUNTIME_CHECK, "utf8");
+
+    expect(await discoverRuntimeRules(temporaryDirectory)).toHaveLength(1);
+  });
+
   it("allows a TypeScript fixture under .tests/", async () => {
     // A runtime check reads real files under a root, so a fixture that is
     // legitimately TypeScript is the normal case rather than a smuggled
@@ -484,8 +512,9 @@ describe("engine dispatch by directory", () => {
       "utf8"
     );
     await writeFile(join(rule, "check.ts"), RUNTIME_CHECK, "utf8");
+    await mkdir(join(rule, ".tests", "valid", "deep"), { recursive: true });
     await writeFile(
-      join(rule, ".tests", "valid", "sample.ts"),
+      join(rule, ".tests", "valid", "deep", "sample.ts"),
       "console.log('x');\n",
       "utf8"
     );