vigiles 41.1.0 → 41.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.nothing = exports.notice = exports.run = exports.inject = exports.tools = exports.HookCompileError = exports.ask = exports.deny = exports.allow = void 0;
3
+ exports.nothing = exports.notice = exports.run = exports.inject = exports.tools = exports.HookCompileError = exports.SHELL_TOOL = exports.ask = exports.deny = exports.allow = void 0;
4
4
  exports.matchesTool = matchesTool;
5
5
  exports.invalidToolPatterns = invalidToolPatterns;
6
6
  exports.gateAction = gateAction;
@@ -140,6 +140,8 @@ function matchesTool(tools, name) {
140
140
  }
141
141
  /** Regex metacharacters — an entry containing one is a PATTERN, not a name. */
142
142
  const REGEX_META = /[.*+?^${}()|[\]\\]/;
143
+ /** The declared entries that are tool NAMES (no regex metacharacter), not patterns. */
144
+ const literalToolNames = (tools) => tools.filter((t) => !REGEX_META.test(t));
143
145
  /** Tool patterns that are not valid regexes — rejected at compile, see {@link matchesTool}. */
144
146
  function invalidToolPatterns(tools) {
145
147
  return tools.filter((t) => {
@@ -477,19 +479,7 @@ function writeTargetsOf(leaf) {
477
479
  const underChdir = (target, chdir) => chdir === null || target === "" || target.startsWith("~")
478
480
  ? target
479
481
  : resolveRef(chdir, target);
480
- /**
481
- * An AST-backed view of a Bash command.
482
- *
483
- * @param raw - the command line as the tool event carried it.
484
- * @param root - the project root repo-relative prefixes resolve against, from
485
- * the runtime ({@link projectRootOf}: `$CLAUDE_PROJECT_DIR`, else the event's
486
- * own `cwd`, never `process.cwd()`). Omitting it does NOT disarm the denylist
487
- * matchers — without a root an absolute token is `"undecidable"` rather than
488
- * placeable, and {@link CommandView.touches} treats that as a match. It does
489
- * cost precision: with a root, `/somewhere-else/notes/x` is provably not this
490
- * repo's `notes`; without one it can only be over-blocked.
491
- */
492
- function commandView(raw, root) {
482
+ function parseCommand(raw) {
493
483
  const leaves = (0, bash_effects_js_1.leafCommands)(raw);
494
484
  // The operation-normalized leaves carry the redirections (and quote-unwrapped,
495
485
  // wrapper-resolved argv) that `writesTo` needs; `leafCommands` cannot see them.
@@ -505,12 +495,40 @@ function commandView(raw, root) {
505
495
  // `NormalizedLeaf.chdir` for why the value was being read and discarded.
506
496
  ...writeTargetsOf(leaf).map((t) => underChdir(t, leaf.chdir)),
507
497
  ]);
498
+ return { leaves, normalized, allWriteTargets };
499
+ }
500
+ /**
501
+ * An AST-backed view of a Bash command.
502
+ *
503
+ * @param raw - the command line as the tool event carried it.
504
+ * @param root - the project root repo-relative prefixes resolve against, from
505
+ * the runtime ({@link projectRootOf}: `$CLAUDE_PROJECT_DIR`, else the event's
506
+ * own `cwd`, never `process.cwd()`). Omitting it does NOT disarm the denylist
507
+ * matchers — without a root an absolute token is `"undecidable"` rather than
508
+ * placeable, and {@link CommandView.touches} treats that as a match. It does
509
+ * cost precision: with a root, `/somewhere-else/notes/x` is provably not this
510
+ * repo's `notes`; without one it can only be over-blocked.
511
+ */
512
+ function commandView(raw, root) {
513
+ // 🔴 PARSED ON THE FIRST PREDICATE CALL, NOT HERE. Building the view used to
514
+ // parse at once, which was harmless while only a Bash GATE built one — a gate
515
+ // exists to ask about the command. Since #396 (a) a react declared for Bash
516
+ // carries this view too, and most such reacts read only `e.response` ("the
517
+ // command failed"). An eager parse would make every one of them load the shell
518
+ // parser (`mvdan-sh`, ~70–140 ms) on every Bash call for a value it never
519
+ // reads. `src/hook-runtime-graph.test.ts` pins both directions: a Bash react
520
+ // that never asks does not load the parser; one that asks does. Memoized, so a
521
+ // view parses at most once however many predicates a decision calls.
522
+ // eslint-disable-next-line functional/no-let -- the memo cell of a lazy parse; it is written once, on the first predicate call, and never reassigned after
523
+ let parsed;
524
+ const parse = () => (parsed ??= parseCommand(raw));
508
525
  const matchedWriteTargets = (prefixes) => [
509
- ...new Set(allWriteTargets.filter((t) => prefixes.some((p) => matchesPrefix(prefixVerdict(t, p, root), "match")))),
526
+ ...new Set(parse().allWriteTargets.filter((t) => prefixes.some((p) => matchesPrefix(prefixVerdict(t, p, root), "match")))),
510
527
  ];
511
528
  return {
512
529
  raw,
513
530
  runs(program, opts) {
531
+ const { leaves, normalized } = parse();
514
532
  const tokens = program.split(/\s+/).filter(Boolean);
515
533
  // 🔴 READS RAW **AND** NORMALIZED ARGV — the same union `touches` already
516
534
  // uses, and for the same reason. This matcher read only `leaves` (raw), so
@@ -570,25 +588,31 @@ function commandView(raw, root) {
570
588
  // `writesTo` was already correct precisely because it reads `normalized`;
571
589
  // this is the same class as the other siblings this PR keeps finding, so
572
590
  // both denylists now read the SAME argv.
573
- touches: (prefixes) =>
574
- // 🔴 THE UNION IS THE FIX, AND EACH HALF COVERS THE OTHER'S BLIND SPOT.
575
- // Raw argv keeps a word exactly as written, so a QUOTED path arrives as
576
- // `"papers/x.tex"` and matches nothing — measured end-to-end on a shipped
577
- // guard: unquoted exited 2, quoted exited 0. Normalized argv unwraps the
578
- // quotes, but `stripWrappers` also CONSUMES wrapper options, so
579
- // `env -C secrets cat key` loses `secrets` entirely and a denylist on it
580
- // fails open. Reading only one of the two trades one bypass for the other;
581
- // that is exactly what the previous commit did, and it earned a P1.
582
- // A denylist over-matching costs an argument. Missing costs the write.
583
- [...leaves.map((argv) => argv.slice(1)), ...normalized.map((l) => l.args)]
584
- .flat()
585
- // `--chdir=secrets` is ONE token, so the path is invisible to a whole-token
586
- // comparison. Only the tail of an `--opt=value` word can be a path, so the
587
- // extra candidate is added rather than replacing the token.
588
- .flatMap((tok) => /^-{1,2}[^=]+=/.test(tok)
589
- ? [tok, tok.slice(tok.indexOf("=") + 1)]
590
- : [tok])
591
- .some((tok) => prefixes.some((p) => matchesPrefix(prefixVerdict(tok, p, root), "match"))),
591
+ touches: (prefixes) => {
592
+ const { leaves, normalized } = parse();
593
+ return (
594
+ // 🔴 THE UNION IS THE FIX, AND EACH HALF COVERS THE OTHER'S BLIND SPOT.
595
+ // Raw argv keeps a word exactly as written, so a QUOTED path arrives as
596
+ // `"papers/x.tex"` and matches nothing — measured end-to-end on a shipped
597
+ // guard: unquoted exited 2, quoted exited 0. Normalized argv unwraps the
598
+ // quotes, but `stripWrappers` also CONSUMES wrapper options, so
599
+ // `env -C secrets cat key` loses `secrets` entirely and a denylist on it
600
+ // fails open. Reading only one of the two trades one bypass for the other;
601
+ // that is exactly what the previous commit did, and it earned a P1.
602
+ // A denylist over-matching costs an argument. Missing costs the write.
603
+ [
604
+ ...leaves.map((argv) => argv.slice(1)),
605
+ ...normalized.map((l) => l.args),
606
+ ]
607
+ .flat()
608
+ // `--chdir=secrets` is ONE token, so the path is invisible to a whole-token
609
+ // comparison. Only the tail of an `--opt=value` word can be a path, so the
610
+ // extra candidate is added rather than replacing the token.
611
+ .flatMap((tok) => /^-{1,2}[^=]+=/.test(tok)
612
+ ? [tok, tok.slice(tok.indexOf("=") + 1)]
613
+ : [tok])
614
+ .some((tok) => prefixes.some((p) => matchesPrefix(prefixVerdict(tok, p, root), "match"))));
615
+ },
592
616
  // DERIVED, not a second implementation of the same rule. The boolean stays
593
617
  // because `writesTo(secrets) ? deny() : allow()` is the common gate shape,
594
618
  // but it is a PROJECTION of the list — one code path, so the two can never
@@ -600,10 +624,38 @@ function commandView(raw, root) {
600
624
  // pipe-to-shell, and a raw-only check misses both (`isBareShellLeaf` tests
601
625
  // the head literally, and the normalizer is what reduces `/bin/sh`→`sh` and
602
626
  // strips the wrapper).
603
- pipesToShell: () => leaves.some(isBareShellLeaf) ||
604
- normalized.some((leaf) => isBareShellLeaf(leaf.argv)),
627
+ pipesToShell: () => {
628
+ const { leaves, normalized } = parse();
629
+ return (leaves.some(isBareShellLeaf) ||
630
+ normalized.some((leaf) => isBareShellLeaf(leaf.argv)));
631
+ },
605
632
  };
606
633
  }
634
+ /**
635
+ * The shell tool's name in a hook payload — the one spelling, shared by the Bash
636
+ * gate and the Bash react. A payload-vocabulary fact rather than a per-harness
637
+ * one: Claude Code sends `Bash`, and Codex's hooks docs (read 2026-11-17) say its
638
+ * shell commands, unified exec included, arrive "as `Bash`" too. Not read from
639
+ * the adapter on purpose: resolving it costs the ~280 ms adapter-registry load
640
+ * that `hook-runtime.ts` keeps off every gate path. ⚠️ No real Codex payload has
641
+ * been captured to confirm the docs; the Codex delivery fixture in this repo
642
+ * spells the tool `shell`, Codex's MODEL-facing name. Revisit with a port field
643
+ * if a harness's payload diverges.
644
+ */
645
+ exports.SHELL_TOOL = "Bash";
646
+ /**
647
+ * The command of a SHELL event, or `undefined` when the event is not one. Keyed
648
+ * on the tool name alone; a shell event with no string command reads as `""`, so
649
+ * every predicate of its view is false (the gate's behaviour since it existed).
650
+ * Used by both the Bash gate and the Bash react — one decode for "this event's
651
+ * command".
652
+ */
653
+ function shellCommandOf(raw) {
654
+ if (raw.tool_name !== exports.SHELL_TOOL)
655
+ return undefined;
656
+ const c = raw.tool_input?.command;
657
+ return typeof c === "string" ? c : "";
658
+ }
607
659
  /**
608
660
  * @experimental Compiled hooks are provisional — see docs/compiled-hooks.md#status--pending.
609
661
  * Imported and CALLED as `experimental_defineHook` — do not alias the prefix away at
@@ -642,14 +694,12 @@ function decideProgram(program, rawEvent, ctx = {}, root = typeof rawEvent.cwd =
642
694
  // role routes through `matchesTool`; that runtime/emit disagreement is the
643
695
  // one MEASURED and fixed for reacts on 2026-08-12 (see the header), and it
644
696
  // survived here on the flagship role. Removed 2026-09-08.
645
- if (rawEvent.tool_name !== "Bash")
697
+ const command = shellCommandOf(rawEvent);
698
+ if (command === undefined)
646
699
  return (0, exports.allow)();
647
- const command = typeof rawEvent.tool_input?.command === "string"
648
- ? rawEvent.tool_input.command
649
- : "";
650
700
  return program.decide({
651
701
  event: program.on,
652
- tool: "Bash",
702
+ tool: exports.SHELL_TOOL,
653
703
  command: commandView(command, root),
654
704
  ctx: ctx,
655
705
  });
@@ -947,7 +997,7 @@ function compileHookProgram(source, hook, opts = {}) {
947
997
  // itself (dialect.mcpToolPattern), so a fully-spelled server tool passes on
948
998
  // both counts.
949
999
  if (opts.dialect) {
950
- const literal = hook.match.tools.filter((t) => !REGEX_META.test(t));
1000
+ const literal = literalToolNames(hook.match.tools);
951
1001
  const badNames = (0, hook_events_js_1.authoringIssues)((0, tool_contract_js_1.verifyToolContract)(literal, opts.dialect));
952
1002
  if (badNames.length > 0) {
953
1003
  throw new HookCompileError(badNames[0].message);
@@ -1194,6 +1244,11 @@ function undecidablePathWarning(filePath, root) {
1194
1244
  `Repo-relative prefixes in this hook cannot match it, so the hook is ` +
1195
1245
  `deciding on less than it looks like it is. Set CLAUDE_PROJECT_DIR.`);
1196
1246
  }
1247
+ /**
1248
+ * Declare the tools a hook matches: `match: tools("Edit", "Write")`. The names
1249
+ * keep their LITERAL types, which is how a react declared with `tools("Bash")`
1250
+ * alone is known to carry `e.command`.
1251
+ */
1197
1252
  const tools = (...names) => ({
1198
1253
  tools: names,
1199
1254
  });
@@ -1395,13 +1450,27 @@ function runReact(hook, raw, ctx = {}, root = typeof raw.cwd === "string" ? raw.
1395
1450
  const fp = typeof raw.tool_input?.file_path === "string"
1396
1451
  ? raw.tool_input.file_path
1397
1452
  : "";
1398
- return hook.react({
1453
+ const base = {
1399
1454
  event: hook.on,
1400
1455
  tool: t,
1401
1456
  path: pathView(fp, root),
1402
1457
  response: responseView(raw.tool_response),
1403
1458
  ctx: ctx,
1404
- });
1459
+ };
1460
+ // The command is attached on SHELL events only, keyed on the tool NAME — never
1461
+ // on the presence of `tool_input.command`, which Codex's `apply_patch` also
1462
+ // carries (a patch, not a command line). The type promises it only to a react
1463
+ // declared for Bash alone; at run time it is present on every Bash event, so a
1464
+ // react whose declared tools merely MATCH Bash does not see a different object.
1465
+ const command = shellCommandOf(raw);
1466
+ const event = command === undefined
1467
+ ? base
1468
+ : { ...base, command: commandView(command, root) };
1469
+ // `ReactEvent<N, T>` is a conditional type over a still-generic `T`, which tsc
1470
+ // cannot narrow from a value; the runtime half of the promise is the tool-name
1471
+ // check above, held by the adapter twins' payload tests.
1472
+ // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- see the line above
1473
+ return hook.react(event);
1405
1474
  }
1406
1475
  /**
1407
1476
  * Resolve a raw payload's project root ONCE, at the entry point.
@@ -143,13 +143,29 @@ export declare function unsafeInlineProviders(needs: readonly NeedSpec[]): Inlin
143
143
  * `dangerous`)? Reused when compiling a `.vigiles/providers/` file.
144
144
  */
145
145
  export declare function unsafeProvider(def: RegisteredProvider): boolean;
146
+ /** One resolved fact: a string, a boolean (built-ins), or a state fact. */
147
+ type Fact = string | boolean | StateFact;
146
148
  /**
147
- * Gather the DECLARED facts into a context object (the trusted-host step). Only
148
- * the names in `needs` are gathered, each at most once; a built-in, inline, or
149
- * registered provider that can't resolve yields its default ("" / false), never
150
- * throws. Pure over the injected `io` (CLI passes a real execSync; tests a fake)
151
- * and the `registry` (the loaded `.vigiles/providers/`, for `provider()` refs).
149
+ * Resolve ONE declared need — the single resolver behind both {@link lazyContext}
150
+ * and {@link gatherContext}. TOTAL: an unresolvable need yields its default (""
151
+ * for a command or a missing registered ref, the built-in's own default, a
152
+ * never-recorded `state()` fact), never throws.
152
153
  */
153
- export declare function gatherContext(needs: readonly NeedSpec[], io: ProviderIO, registry?: ProviderRegistry): Record<string, string | boolean | StateFact>;
154
+ export declare function resolveNeed(need: NeedSpec, io: ProviderIO, registry?: ProviderRegistry): Fact;
155
+ /**
156
+ * The runtime's `e.ctx`: one enumerable, MEMOIZED getter per DECLARED need.
157
+ * Nothing runs until a key is read, each key resolves at most once per context
158
+ * (two reads in one decision see one value), and a key never read never runs —
159
+ * so an unread `dangerously()` provider costs nothing and fires nothing. Getters
160
+ * never throw ({@link resolveNeed} is total). `io.now` is fixed when the context
161
+ * is built, so a `state()` age does not depend on when `decide` reads it.
162
+ */
163
+ export declare function lazyContext(needs: readonly NeedSpec[], io: ProviderIO, registry?: ProviderRegistry): Readonly<Record<string, Fact>>;
164
+ /**
165
+ * Gather the DECLARED facts eagerly: {@link lazyContext} with every key read
166
+ * once (the eager twin, same resolver). Kept for callers that want a plain
167
+ * snapshot object. Pure over the injected `io` and the `registry`.
168
+ */
169
+ export declare function gatherContext(needs: readonly NeedSpec[], io: ProviderIO, registry?: ProviderRegistry): Readonly<Record<string, Fact>>;
154
170
  export {};
155
171
  //# sourceMappingURL=hook-providers.d.ts.map
@@ -4,6 +4,8 @@ exports.BUILTIN_PROVIDERS = exports.provider = exports.defineProvider = exports.
4
4
  exports.unknownProviders = unknownProviders;
5
5
  exports.unsafeInlineProviders = unsafeInlineProviders;
6
6
  exports.unsafeProvider = unsafeProvider;
7
+ exports.resolveNeed = resolveNeed;
8
+ exports.lazyContext = lazyContext;
7
9
  exports.gatherContext = gatherContext;
8
10
  /**
9
11
  * Hook CONTEXT PROVIDERS — let a compiled gate decide on EXTERNAL STATE (git
@@ -138,30 +140,62 @@ function unsafeProvider(def) {
138
140
  return !def.dangerous && !(0, bash_effects_js_1.isReadOnlyBash)(def.run);
139
141
  }
140
142
  /**
141
- * Gather the DECLARED facts into a context object (the trusted-host step). Only
142
- * the names in `needs` are gathered, each at most once; a built-in, inline, or
143
- * registered provider that can't resolve yields its default ("" / false), never
144
- * throws. Pure over the injected `io` (CLI passes a real execSync; tests a fake)
145
- * and the `registry` (the loaded `.vigiles/providers/`, for `provider()` refs).
143
+ * Resolve ONE declared need — the single resolver behind both {@link lazyContext}
144
+ * and {@link gatherContext}. TOTAL: an unresolvable need yields its default (""
145
+ * for a command or a missing registered ref, the built-in's own default, a
146
+ * never-recorded `state()` fact), never throws.
146
147
  */
147
- function gatherContext(needs, io, registry = {}) {
148
- const ctx = {};
149
- for (const need of needs) {
150
- if ((0, hook_state_js_1.isStateNeed)(need)) {
151
- // The one need that reaches no subprocess: the trusted runtime hands the
152
- // stored entry (or null) straight in, and the fact view does the clamping
153
- // every shell stamp-reader used to re-implement by hand.
154
- ctx[need.name] = (0, hook_state_js_1.stateFact)(io.readState(need.name), io.now);
155
- }
156
- else if (isInline(need))
157
- ctx[need.name] = tryExec(io, need.run);
158
- else if (isRef(need)) {
159
- const def = registry[need.name];
160
- ctx[need.name] = def ? tryExec(io, def.run) : "";
161
- }
162
- else
163
- ctx[need] = exports.BUILTIN_PROVIDERS[need].gather(io);
148
+ function resolveNeed(need, io, registry = {}) {
149
+ if ((0, hook_state_js_1.isStateNeed)(need)) {
150
+ // The one need that reaches no subprocess: the trusted runtime hands the
151
+ // stored entry (or null) straight in, and the fact view does the clamping
152
+ // every shell stamp-reader used to re-implement by hand.
153
+ return (0, hook_state_js_1.stateFact)(io.readState(need.name), io.now);
164
154
  }
165
- return ctx;
155
+ if (isInline(need))
156
+ return tryExec(io, need.run);
157
+ if (isRef(need)) {
158
+ const def = registry[need.name];
159
+ return def ? tryExec(io, def.run) : "";
160
+ }
161
+ return exports.BUILTIN_PROVIDERS[need].gather(io);
162
+ }
163
+ /** The key a need is exposed under in `e.ctx`. */
164
+ const needKey = (need) => typeof need === "string" ? need : need.name;
165
+ /**
166
+ * The runtime's `e.ctx`: one enumerable, MEMOIZED getter per DECLARED need.
167
+ * Nothing runs until a key is read, each key resolves at most once per context
168
+ * (two reads in one decision see one value), and a key never read never runs —
169
+ * so an unread `dangerously()` provider costs nothing and fires nothing. Getters
170
+ * never throw ({@link resolveNeed} is total). `io.now` is fixed when the context
171
+ * is built, so a `state()` age does not depend on when `decide` reads it.
172
+ */
173
+ function lazyContext(needs, io, registry = {}) {
174
+ return Object.defineProperties({}, Object.fromEntries(needs.map((need) => [
175
+ needKey(need),
176
+ {
177
+ enumerable: true,
178
+ configurable: true,
179
+ // Memoization by self-replacement: the first read resolves the need and
180
+ // redefines the key as a plain data property holding the result, so a
181
+ // second read can never run it again and no cache variable exists.
182
+ get() {
183
+ const value = resolveNeed(need, io, registry);
184
+ Object.defineProperty(this, needKey(need), {
185
+ value,
186
+ enumerable: true,
187
+ });
188
+ return value;
189
+ },
190
+ },
191
+ ])));
192
+ }
193
+ /**
194
+ * Gather the DECLARED facts eagerly: {@link lazyContext} with every key read
195
+ * once (the eager twin, same resolver). Kept for callers that want a plain
196
+ * snapshot object. Pure over the injected `io` and the `registry`.
197
+ */
198
+ function gatherContext(needs, io, registry = {}) {
199
+ return Object.fromEntries(Object.entries(lazyContext(needs, io, registry)));
166
200
  }
167
201
  //# sourceMappingURL=hook-providers.js.map
@@ -0,0 +1,99 @@
1
+ /**
2
+ * What one harness file can REACH — the files whose change can change its
3
+ * outcome — for `vigiles test --changed` (`./test-selection.ts` decides with it).
4
+ *
5
+ * Three edges, followed from the harness through every code file it reaches:
6
+ *
7
+ * 1. IMPORTS — relative `import`/`export … from`/`require`/literal `import()`,
8
+ * found by TypeScript's `preProcessFile` and resolved by `resolveModuleName`.
9
+ * 2. EFFECT CALLS — a call that runs, reads or copies a file: the `spawn`/`exec`
10
+ * family (the command and its argv array), `readFile*`/`createReadStream`,
11
+ * `cp*`/`copyFile*`, and `runHook(command)`. Only CALL ARGUMENTS count: a path
12
+ * inside an object literal (`tool_input.file_path` in a synthetic hook event)
13
+ * is a fixture, never a dependency. A script the call runs is followed like
14
+ * an import, so its own imports and calls count too.
15
+ * 3. BUILD OUTPUT → SOURCE — a path inside the tsconfig's `outDir` is read as its
16
+ * `rootDir` counterpart (`dist/x.js` → `src/x.ts`), so a harness that imports
17
+ * the build is reached by a change to the source behind it.
18
+ *
19
+ * An effect path is EVALUATED, not matched as text: string literals, `+` and
20
+ * template literals, `path.join`/`resolve`/`dirname`, `__dirname`,
21
+ * `import.meta.{url,dirname,filename}`, `new URL(x, import.meta.url)`,
22
+ * `fileURLToPath`, `process.cwd()`, and a `const` bound to any of those. A path
23
+ * whose start is known and whose end is not (`join(ROOT, "data", name)`) is a
24
+ * PREFIX: any change under `data/` reaches the harness. A path with nothing
25
+ * known is UNRESOLVED and reported as such; what to do with it is the
26
+ * selector's decision, not this module's.
27
+ *
28
+ * Pure: every read goes through {@link SourceHost}.
29
+ */
30
+ import ts from "typescript";
31
+ /** The reads reach needs. Paths are absolute. */
32
+ export interface SourceHost {
33
+ /** A file's text, or null when it is absent or unreadable. */
34
+ readonly read: (path: string) => string | null;
35
+ readonly isFile: (path: string) => boolean;
36
+ /** tsc's own directory walk (`ts.sys.readDirectory`), for a tsconfig's inputs. */
37
+ readonly readDirectory: ts.ParseConfigHost["readDirectory"];
38
+ /** The real path behind a symlink — a workspace package linked into node_modules. */
39
+ readonly realpath: (path: string) => string;
40
+ }
41
+ /** What `<cwd>/tsconfig.json` says, read by TypeScript itself (`extends` included). */
42
+ export interface Project {
43
+ /** Where the build writes and the source it writes from; undefined with no `outDir`. */
44
+ readonly build: OutputLayout | undefined;
45
+ /** Its compiler options, so `paths`/`baseUrl` apply when a bare specifier is resolved. */
46
+ readonly options: Readonly<ts.CompilerOptions>;
47
+ }
48
+ /** Where a TypeScript build writes, and the source it writes from. Absolute. */
49
+ export interface OutputLayout {
50
+ readonly outDir: string;
51
+ readonly rootDir: string;
52
+ }
53
+ /** A file or folder an effect call names, cwd-relative and POSIX. */
54
+ export interface EffectDep {
55
+ readonly path: string;
56
+ /** True: any changed path STARTING with `path` (an unknown tail). */
57
+ readonly prefix: boolean;
58
+ readonly call: string;
59
+ }
60
+ /** An effect call whose path argument could not be evaluated at all. */
61
+ export interface Unresolved {
62
+ readonly call: string;
63
+ readonly file: string;
64
+ readonly line: number;
65
+ }
66
+ export interface Reach {
67
+ /** Code and data files reached by import, cwd-relative and POSIX. */
68
+ readonly imports: ReadonlySet<string>;
69
+ readonly effects: readonly EffectDep[];
70
+ readonly unresolved: readonly Unresolved[];
71
+ }
72
+ export type ReachHit = {
73
+ readonly kind: "import";
74
+ } | {
75
+ readonly kind: "reads";
76
+ readonly call: string;
77
+ };
78
+ /** Does a change to `changed` (cwd-relative) reach through `r`, and how? */
79
+ export declare function reachMatch(r: Reach, changed: string): ReachHit | undefined;
80
+ /**
81
+ * `<cwd>/tsconfig.json` as TypeScript reads it. No tsconfig → undefined. With
82
+ * no `outDir`, `build` is undefined and paths are taken as they are; an unset
83
+ * `rootDir` is tsc's own default (see {@link commonSourceDir}).
84
+ */
85
+ export declare function readProject(cwd: string, host: SourceHost): Project | undefined;
86
+ /** `relative`, in POSIX separators. */
87
+ export declare function posixRelative(from: string, to: string): string;
88
+ export interface ReachSetup {
89
+ readonly cwd: string;
90
+ readonly host: SourceHost;
91
+ /** `readProject(cwd, host)`, read once per run. */
92
+ readonly project: Project | undefined;
93
+ }
94
+ /**
95
+ * What each harness file reaches, for one run. The resolution cache is shared
96
+ * by every file the returned function is asked about.
97
+ */
98
+ export declare function reachFor(setup: ReachSetup): (file: string) => Reach;
99
+ //# sourceMappingURL=test-reach.d.ts.map