@davesheffer/hunch 1.45.2 → 1.47.0

package/dist/core/testSelection.d.ts

@@ -0,0 +1,122 @@
+/** One test's coverage record. `complete` = the test file passed (ran to the
+ *  end, so its coverage is whole); `closureHash` = the entry-closure hash at
+ *  refresh time; `commit` = HEAD when this entry was recorded. */
+export interface ImpactEntry {
+    files: string[];
+    complete: boolean;
+    commit: string;
+    closureHash: string;
+}
+export interface ImpactMap {
+    version: number;
+    commit: string;
+    generatedAt?: string;
+    closureHash?: string;
+    /** test file → coverage entry (repo-relative posix). */
+    map: Record<string, ImpactEntry>;
+}
+export interface SelectionInput {
+    changedFiles: string[];
+    allTests: string[];
+    impactMap?: ImpactMap;
+    /** Static dependencies of a test: transitive imports plus the closures of
+     *  repo paths its text names (see `testDependencyModel`). */
+    importGraph: (testFile: string) => Set<string>;
+    fullTriggers?: string[];
+    /** Extra per-test globs: a changed file matching one selects that test. */
+    gateMaps?: Record<string, string[]>;
+    /** Source text of a test (and its non-src helpers), for path/basename mentions. */
+    testText?: (testFile: string) => string;
+    /** Does the test start a child process (directly or through a helper)? */
+    spawning?: (testFile: string) => boolean;
+    /** Every file a spawned child could execute (all src/ plus tooling closures). */
+    wholeProgram?: Iterable<string>;
+    /** Entry-closure hash computed now; a map entry is trusted only if it matches. */
+    closureHash?: string;
+    /** src/ and tooling/ files whose text names a test file by repo path. */
+    testNamers?: (testFile: string) => string[];
+}
+export interface Selection {
+    mode: "selected" | "full" | "none";
+    tests: string[];
+    reasons: Record<string, string[]>;
+    fullReason?: string;
+    unattributed: string[];
+    /** Tests whose impact-map entry attributed a change or narrowed a spawning test. */
+    mapUsed: string[];
+}
+export declare const DEFAULT_FULL_TRIGGERS: readonly string[];
+/** Repo-root markdown (README.md, CHANGELOG.md, ...) is the only non-code change
+ *  that can skip the full suite: it selects tests that mention it, else nothing. */
+export declare function isDocsOnly(file: string): boolean;
+/** Selected tests above this share of the suite run the full suite instead. */
+export declare const MAX_SELECTED_SHARE = 0.6;
+export declare const isMetaTest: (text: string) => boolean;
+/** A map entry may narrow a spawning test only when it is complete and was
+ *  recorded against the same entry closure as now. */
+export declare function entryTrusted(entry: ImpactEntry | undefined, closureHash: string | undefined): boolean;
+export declare function selectTests(input: SelectionInput): Selection;
+/** Tracked + untracked (non-ignored) repo files, repo-relative posix, sorted. */
+export declare function listRepoFiles(root: string): string[];
+export declare function discoverTests(files: string[], glob?: string): string[];
+/** Static imports, re-exports, `import()`/`require()` with literal specifiers. */
+export declare function importSpecifiers(source: string): string[];
+/** Transitive relative-import closure per file, memoized for this call. An
+ *  unresolvable relative specifier (e.g. a deleted file) records every
+ *  candidate path, so the deletion stays attributable to its importers. */
+export declare function buildImportGraph(root: string, files?: string[]): (file: string) => Set<string>;
+/** Entries whose import closure (edges included) keys map-entry trust. */
+export declare const CLOSURE_ROOTS: readonly string[];
+/** String-literal arguments of each `join(`/`resolve(` call, found with a
+ *  balanced-paren scan so nested calls (`join(process.cwd(), "src")`) parse. */
+export declare function joinSegmentRuns(text: string): string[][];
+/** Repo files a test's text names: path-like tokens anywhere (string literals,
+ *  `--eval` import specifiers, template strings) and `join(…, "src", "x.ts")`
+ *  segment runs, resolved against the REPO ROOT (and the test's own dir for
+ *  `./`/`../` tokens), with `.js`→`.ts` mapping. */
+export declare function literalRepoPaths(text: string, fromFile: string, available: Set<string>): string[];
+/** Arguments of each `join(`/`resolve(` call: a plain string literal's value, or
+ *  `null` for anything computed (identifiers, calls, `${}` templates). */
+export declare function joinCallArgs(text: string): (string | null)[][];
+/** Top-level repo dirs a text reaches through a COMPUTED path: `` `../src/${p}` ``,
+ *  `"src/" + p`, `join(root, "src", p)`, or a later use of an alias like
+ *  `const SRC = join(ROOT, "src")`. A test doing that may read any file under
+ *  the dir, so it depends on all of them. A computed segment right after the
+ *  root (`` `../${dir}/x` ``, `"../" + dir`, `resolve(__dirname, "..", dir)`,
+ *  `` `${ROOT}/${dir}` ``) may be ANY top-level dir (fail closed). */
+export declare function templatedRepoDirs(text: string, topDirs: Set<string>): string[];
+export interface TestDependencyModel {
+    /** Static imports ∪ closures of repo paths named in the test or its helpers. */
+    dependencies: (testFile: string) => Set<string>;
+    spawning: (testFile: string) => boolean;
+    /** Text of the test plus its non-src static closure (helpers). */
+    testText: (testFile: string) => string;
+    /** All src/ files plus the closures of every tooling/*.mjs. */
+    wholeProgram: Set<string>;
+    /** Hash of the import closures (edges) of CLOSURE_ROOTS and tooling/*.mjs. */
+    closureHash: string;
+    /** src/ and tooling/ code files whose text names a test file by repo path. */
+    testNamers: (testFile: string) => string[];
+}
+export declare function testDependencyModel(root: string, files: string[], graph?: (file: string) => Set<string>): TestDependencyModel;
+/** Structural hash of the entry closures: every reachable file and its direct
+ *  edges. Content edits don't change it; a new import or file in the closure does. */
+export declare function closureHash(root: string, files: string[], graph?: (file: string) => Set<string>): string;
+/** Repo files with any executed range in V8 coverage reports
+ *  (`NODE_V8_COVERAGE` JSON: `{ result: [{ url, functions: [{ ranges }] }] }`). */
+export declare function coverageFiles(reports: unknown[], root: string, repoFiles: Set<string>): string[];
+export type ChangeMode = {
+    kind: "worktree";
+} | {
+    kind: "staged";
+} | {
+    kind: "base";
+    ref: string;
+};
+/** Changed files for a verify run. `worktree` (default): staged + unstaged +
+ *  untracked; `staged`: the index only; `base`: merge-base(ref, HEAD)..HEAD
+ *  plus the working tree. */
+export declare function changedFiles(root: string, mode?: ChangeMode): string[];
+/** Load an impact map; a missing file is `null`, a malformed one throws. A
+ *  legacy `test: string[]` entry loads as incomplete (never trusted). */
+export declare function loadImpactMap(path: string): ImpactMap | null;