test-inventory 0.4.1 → 0.6.0

package/dist/dependency-hash.d.ts

@@ -0,0 +1,242 @@
+import { type Node } from 'oxc-parser';
+import type { ConfigGap, RunsWith } from './config-dependencies.ts';
+import type { Extraction, Frame, PendingTest } from './extract.ts';
+import type { ModuleReader, ModuleSource, Problem, Span } from './model.ts';
+import type { ParsedFile } from './parse.ts';
+import { type SourceText } from './source.ts';
+import type { Framework } from './types.ts';
+import { Values } from './values.ts';
+/** A file whose code a test can run: the scanned file, a module it imports, or a data file such as JSON. */
+interface Module {
+    relativeFilePath: string;
+    /** Null for a file that isn't JavaScript or TypeScript, which is taken by its text. */
+    parsed: ParsedFile | null;
+    /** The file's text with line endings read as `\n`, for a file that isn't code. */
+    text: string | null;
+    values: Values;
+    readModule: ModuleReader | null;
+    /** Its top-level code that runs when it is imported, and the modules it imports, which run then too. */
+    load: [Unit | null, Unit | null];
+    /** All of it, for a module used in ways the scan can't narrow down to declarations. */
+    whole: [Unit | null, Unit | null];
+    /** What each import in the module stands for, as it is asked for once per test file that reaches it. */
+    imports: Map<string, Unit[]>;
+    /** The module each specifier names, as a barrel's `export *` is searched once for every name imported through it. */
+    reads: Map<string, ReturnType<ModuleReader>>;
+}
+/** Code to hash, with the scopes around each node, so that the names it uses can be followed to their declarations. */
+interface Root {
+    node: Node;
+    scopes: readonly Node[];
+}
+/**
+ * A piece of code a test may run, and the pieces it uses in turn. A unit with a `place` and no code stands for
+ * something the scan can't follow.
+ */
+interface Unit {
+    module: Module;
+    roots: Root[];
+    /** Nodes left out, given as end by start: the tests and describes in a file's or a describe's own code. */
+    cut: ReadonlyMap<number, number>;
+    /** Whether names in types are followed too, for type tests. */
+    types: boolean;
+    /** Extra units it always brings in, such as the code its module runs when it is imported. */
+    with: Unit[];
+    edges: Set<Unit> | null;
+    place: Place | null;
+    /** For a test object built with `extend()`, the fixtures left out of its code. */
+    fixtures: Fixtures | null;
+    /** Fills in `roots` and `with` when the walk first reaches the unit. */
+    prepare: (() => void) | null;
+    /**
+     * Fixtures the functions in its code ask for when passed to a hook, a condition such as `test.skip()`, `test.use()`
+     * or a test, as a helper that registers a hook does; null when one takes them whole or can't be told.
+     */
+    asks: string[] | null;
+    /** The snapshot matchers its code calls, which compare against files beside the test file. */
+    snapshots: SnapshotUse[];
+    hash: string | null | undefined;
+}
+/** A snapshot matcher a test's code calls, and the name or path it gives; null when it gives none the scan can read. */
+export interface SnapshotUse {
+    matcher: string;
+    name: string | null;
+    /** Given as path parts, as `['portfolio', 'allocation.png']`, which Playwright doesn't sanitize. */
+    isParts: boolean;
+}
+/** Reads the snapshot files of a scan from disk, and says whether the config moves them. */
+export interface SnapshotFiles {
+    framework: Framework;
+    /** The files in a folder of the project and the folders in it, as paths in the folder with `/`; none for no folder. */
+    list(folder: string): string[] | 'unreadable';
+    /** A file's bytes, from the project root; null when there is none, as before a snapshot is first written. */
+    read(file: string): Uint8Array | null | 'unreadable';
+    /** Where the config puts snapshots elsewhere, which the scan doesn't follow; null when it doesn't. */
+    moved: ConfigGap | null;
+}
+/** Something a test reaches that the scan can't follow. */
+export interface Place {
+    relativeFilePath: string;
+    source: SourceText;
+    problem: Problem;
+    /** Not reported, as when one file's code is scanned and no import is read: the test record says enough. */
+    isQuiet: boolean;
+}
+/** The units some roots reach, the hashes of their code by file, each list sorted, and the places among them. */
+interface Reach {
+    units: Set<Unit>;
+    byFile: Map<string, string[]>;
+    places: Place[];
+    /** The fixtures of the test objects among the units, which each test takes as it needs them. */
+    fixtures: Fixtures[];
+    /** The fixtures the units' code asks for; null when some of it asks for all. */
+    asks: string[] | null;
+    snapshots: SnapshotUse[];
+}
+/** A fixture one `extend()` call defines, and the fixtures it asks for; null when it takes them whole. */
+interface Fixture {
+    unit: Unit;
+    uses: string[] | null;
+}
+/** The fixtures a test object's own `extend()` calls define, left out of the object's unit and taken per test. */
+interface Fixtures {
+    byName: Map<string, Fixture[]>;
+    /** Fixtures with `auto: true`, which run for every test that uses the object. */
+    auto: string[];
+    framework: Framework;
+}
+/** The fixtures a test asks for: its own, and those of the hooks around it. */
+export interface FixtureNeeds {
+    names: string[];
+    /** The test or a hook takes its fixtures whole, so it may use any. */
+    all: boolean;
+}
+/** What a test runs, as the test record gives it. */
+export interface Dependencies {
+    hash: string;
+    files: string[];
+    isComplete: boolean;
+}
+/**
+ * Follows what each test runs, across the files of one scan: its call, the code around it, and every declaration
+ * that code uses, in its own file and through imports. Each piece is read once per scan, however many tests reach it.
+ */
+export declare class DependencyGraph {
+    private readonly modules;
+    private readonly units;
+    private readonly imports;
+    private readonly snapshotFiles;
+    private readonly calledTests;
+    private readonly testObjects;
+    /** Places already reported, so that one the scan reaches from many files is reported once. */
+    private readonly reported;
+    /** The module of a file the scan reads code from, given as its parsed file. */
+    module(parsed: ParsedFile, relativeFilePath: string, values: Values, readModule: ModuleReader | null): Module;
+    /**
+     * Code a test or a describe runs, written in `module`. `cut` lists the nodes left out, such as the tests in a
+     * describe.
+     */
+    unit(module: Module, nodes: Node[], cut: Span[], types: boolean): Unit;
+    /** The code a file runs when it is loaded, leaving out the tests and describes at `cut`. */
+    loadUnit(module: Module, types: boolean, cut?: Span[], allImports?: boolean): Unit;
+    /** The units a set of roots reaches, leaving out those `skip` reached, with their hashes by file. */
+    reach(roots: Unit[], skip?: Reach[]): Reach;
+    /**
+     * Everything a test's roots reach on top of `base`, the code its file runs when loaded, which all its tests share,
+     * with the fixtures it needs of each test object reached: the hash, the files, and whether all of it could be
+     * followed.
+     */
+    dependencies(roots: Unit[], bases: Reach[], needs: FixtureNeeds, snapshots: (uses: SnapshotUse[]) => Unit[], report: (place: Place) => void): Dependencies;
+    private newModule;
+    private newUnit;
+    private hashOf;
+    /** The module a file imports, read and parsed once per scan. */
+    private moduleOf;
+    private textUnit;
+    private wholeUnit;
+    /** The unit of a declaration: a declarator, function, class, enum, namespace or `import x = require()`. */
+    private declarationUnit;
+    /** Whether a name is bound to a test object, once per declaration, as a file may call a helper thousands of times. */
+    private isTestObject;
+    /**
+     * A file a test compares against, by its bytes: a snapshot or a screenshot, read once per scan however many tests
+     * compare against it; null when there is none yet.
+     */
+    snapshotUnit(relativeFilePath: string, read: () => Uint8Array | null | 'unreadable'): Unit | null | 'unreadable';
+    /** A place in a scanned file that marks its tests without a warning, as for what one file's code can't show. */
+    quietUnit(module: Module, message: string): Unit;
+    /** An import of a name a test uses: the module it names and how, as `import { round } from 'lodash'`. */
+    private importUnit;
+    /** A place in a module the scan can't follow, as a unit that marks the tests that reach it. */
+    private placeUnit;
+    /**
+     * A module the config runs each test with, taken whole: the config itself, a setup file, or a file of a setup
+     * project.
+     */
+    runUnit(source: ModuleSource, isConfig: boolean): Unit;
+    /** Something in a config the scan can't follow, as a unit that marks the tests whose config it is. */
+    gapUnit(gap: ConfigGap): Unit;
+    /**
+     * What a module's import of `name` from `specifier` stands for, `at` being the statement in `from` that imports it:
+     * the declaration it exports, `*` for all of it, or `''` for the code it runs when loaded. Installed packages give
+     * nothing; a local module that can't be read gives a place.
+     */
+    private imported;
+    /** The module a specifier names, from where `from` is; null when no module is read, as for one file's code. */
+    private read;
+    private readImport;
+    /**
+     * The units of what a module exports under a name: its own export first, then one an `export *` passes on, as the
+     * module system picks them. `*` is the whole module. A name the scan can't find, as with CommonJS exports, also
+     * takes the whole module, so that nothing it may run is left out.
+     */
+    private exported;
+    /** What `export * from source` gives for a name; null when the module behind it doesn't export it. */
+    private reexported;
+    /**
+     * The units a name stands for where it is declared: the declaration, the export of the module it's imported from, or
+     * for a parameter only the parameters, as the call that passes their values is followed on its own.
+     */
+    private toDeclaration;
+    /**
+     * A test object built with `extend()` on the framework's own: its code without the fixtures its `extend()` calls
+     * define, which each test takes as it needs them. Null for any other value.
+     */
+    private testObjectUnit;
+    private readTestObject;
+    /**
+     * The framework of a test object: its own `test`, `mergeTests()` of test objects, or one built on them with
+     * `extend()`, followed through imports; null for an expression that isn't one.
+     */
+    private frameworkOf;
+    /**
+     * Takes what the values given to `test.use()`, `override()` or `scoped()` ask for: functions and `[fn, options]`
+     * pairs, as `extend()` takes them. Playwright's options and a spread of its `devices` are values, not fixtures.
+     */
+    private useValues;
+    /**
+     * Whether a call is on a test object, so that its functions run with fixtures: the framework's own, a global one,
+     * one built with `extend()`, or a parameter, as a helper that takes the test object has.
+     */
+    private isTestReference;
+    /**
+     * The fixtures a fixture's or hook's function asks for. A value such as a constant asks for none; null when the
+     * function takes them whole, or the value can't be told, as a factory's result or a fixture from a package.
+     */
+    private fixtureUses;
+    /**
+     * What an expression holds, followed through constants and imports to the function or value they are bound to; the
+     * expression itself when it is something else, with the module and scopes to read it in.
+     */
+    private valueOf;
+    private importOf;
+    /** The units a unit uses directly: the declarations its names refer to, and the modules it loads. */
+    private edgesOf;
+}
+/**
+ * What each test of a scanned file runs: its own call, the helper call that registers it, every describe around it
+ * with its hooks and options, the file's own top-level code, and what all of these reach. `report` gets each place the
+ * scan can't follow, once per scan.
+ */
+export declare function fileDependencies(graph: DependencyGraph, main: Frame, extraction: Extraction, types: boolean, report: (place: Place) => void, runsWith?: RunsWith, snapshotFiles?: SnapshotFiles | null): (test: PendingTest) => Dependencies;
+export {};