tslaws 0.6.4 → 0.7.0

package/dist/migrate/framework.d.ts

@@ -0,0 +1,48 @@
+import ts from 'typescript';
+import type { Source } from './source.ts';
+export declare const sources: readonly ["vitest", "jest", "rstest", "bun", "node", "fast-check", "playwright"];
+export type SourceName = (typeof sources)[number];
+export declare function isSourceName(value: string | undefined): value is SourceName;
+/** Modules that provide test structure or matchers. Their imports are rebuilt rather than copied. */
+export declare const frameworkModules: Record<string, SourceName>;
+/** Where `expect` (and the mock helpers) come from when a file uses the framework's globals instead of importing them. */
+export declare const globalsModule: Partial<Record<SourceName, {
+    module: string;
+    names: string[];
+}>>;
+/** Names that only describe test structure: an import of one is dropped, never kept for the laws. */
+export declare const structural: Set<string>;
+export interface Callee {
+    kind: 'describe' | 'test' | 'hook' | 'config';
+    hook?: 'before' | 'after';
+    /** Playwright's `use`, `setTimeout`, `step`, `info`, `configure`, `extend`. */
+    config?: string;
+    mods: Set<string>;
+    /** The call of ``.each(...)`` or the tagged template of ``.each`...` ``. */
+    each?: ts.CallExpression | ts.TaggedTemplateExpression;
+    /** `.for` (vitest) hands each row to the test as one argument instead of spreading it. */
+    forRows?: boolean;
+    /** `it.prop(arbitraries, options?)` of @fast-check/vitest and @fast-check/jest. */
+    prop?: ts.CallExpression;
+    /** `.runIf(...)` / `.skipIf(...)`, which choose at run time. */
+    conditional?: string;
+}
+/** `a.b.c` as `['a', 'b', 'c']`, or undefined when the expression is anything else. */
+export declare function chainOf(node: ts.Expression): string[] | undefined;
+export interface Bindings {
+    /** Local name to the name the framework exports it under (`it as spec` gives `spec -> it`). */
+    imported: Map<string, string>;
+    /** Local names that are a framework's whole module (`import * as t from 'vitest'`). */
+    namespaces: Set<string>;
+    /** Local names the file declares itself or imports from elsewhere: they are not the framework's globals. */
+    own: Set<string>;
+    /** Local names of fast-check's namespace (`fc`) and its named exports (local to exported name). */
+    fcNamespaces: Set<string>;
+    fcNamed: Map<string, string>;
+}
+export declare function bindingsOf(source: Source): Bindings;
+/**
+ * What a call's callee means in a test file: `describe`, `it.skip`, `test.each(table)`, `beforeEach`, `test.describe.serial`.
+ * Undefined when the callee is not the framework's.
+ */
+export declare function classify(callee: ts.Expression, b: Bindings, playwright: boolean): Callee | undefined;

package/dist/migrate/framework.js

@@ -0,0 +1,249 @@
+// The test frameworks migrate reads: which module each comes from, what its calls are named, and how a call in a test
+// file is told apart (by the import it came from, or by the global the framework provides).
+import ts from 'typescript';
+export const sources = ['vitest', 'jest', 'rstest', 'bun', 'node', 'fast-check', 'playwright'];
+export function isSourceName(value) {
+    return sources.includes(value ?? '');
+}
+/** Modules that provide test structure or matchers. Their imports are rebuilt rather than copied. */
+export const frameworkModules = {
+    vitest: 'vitest',
+    '@jest/globals': 'jest',
+    '@rstest/core': 'rstest',
+    'bun:test': 'bun',
+    'node:test': 'node',
+    '@playwright/test': 'playwright',
+    'fast-check': 'fast-check',
+    '@fast-check/vitest': 'vitest',
+    '@fast-check/jest': 'jest',
+};
+/** Where `expect` (and the mock helpers) come from when a file uses the framework's globals instead of importing them. */
+export const globalsModule = {
+    vitest: { module: 'vitest', names: ['expect', 'vi'] },
+    jest: { module: '@jest/globals', names: ['expect', 'jest'] },
+    rstest: { module: '@rstest/core', names: ['expect', 'rs', 'rstest'] },
+    bun: { module: 'bun:test', names: ['expect', 'mock', 'spyOn'] },
+    playwright: { module: '@playwright/test', names: ['expect'] },
+};
+/** Names that only describe test structure: an import of one is dropped, never kept for the laws. */
+export const structural = new Set([
+    'describe',
+    'suite',
+    'it',
+    'test',
+    'xit',
+    'xtest',
+    'xdescribe',
+    'fit',
+    'ftest',
+    'fdescribe',
+    'beforeEach',
+    'afterEach',
+    'beforeAll',
+    'afterAll',
+    'before',
+    'after',
+]);
+/** `a.b.c` as `['a', 'b', 'c']`, or undefined when the expression is anything else. */
+export function chainOf(node) {
+    if (ts.isIdentifier(node))
+        return [node.text];
+    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name)) {
+        const inner = chainOf(node.expression);
+        return inner === undefined ? undefined : [...inner, node.name.text];
+    }
+    return undefined;
+}
+function declaredTopLevel(statement) {
+    const names = [];
+    const bind = (name) => {
+        if (ts.isIdentifier(name))
+            names.push(name.text);
+        else
+            for (const element of name.elements)
+                if (ts.isBindingElement(element))
+                    bind(element.name);
+    };
+    if (ts.isVariableStatement(statement))
+        for (const d of statement.declarationList.declarations)
+            bind(d.name);
+    else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name !== undefined)
+        names.push(statement.name.text);
+    return names;
+}
+export function bindingsOf(source) {
+    const b = {
+        imported: new Map(),
+        namespaces: new Set(),
+        own: new Set(),
+        fcNamespaces: new Set(),
+        fcNamed: new Map(),
+    };
+    for (const statement of source.file.statements) {
+        if (!ts.isImportDeclaration(statement)) {
+            for (const name of declaredTopLevel(statement))
+                b.own.add(name);
+            continue;
+        }
+        const clause = statement.importClause;
+        if (clause === undefined || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        const module = statement.moduleSpecifier.text;
+        const known = frameworkModules[module] !== undefined;
+        const fastCheck = module === 'fast-check';
+        const fastCheckRelated = fastCheck || module === '@fast-check/vitest' || module === '@fast-check/jest';
+        if (clause.name !== undefined) {
+            if (fastCheck)
+                b.fcNamespaces.add(clause.name.text);
+            else if (known)
+                b.imported.set(clause.name.text, 'test');
+            else
+                b.own.add(clause.name.text);
+        }
+        const named = clause.namedBindings;
+        if (named === undefined)
+            continue;
+        if (ts.isNamespaceImport(named)) {
+            if (fastCheck)
+                b.fcNamespaces.add(named.name.text);
+            else if (known)
+                b.namespaces.add(named.name.text);
+            else
+                b.own.add(named.name.text);
+            continue;
+        }
+        for (const element of named.elements) {
+            const local = element.name.text;
+            const original = (element.propertyName ?? element.name).text;
+            if (fastCheck)
+                b.fcNamed.set(local, original);
+            else if (known && fastCheckRelated && original === 'fc')
+                b.fcNamespaces.add(local);
+            else if (known)
+                b.imported.set(local, original);
+            else
+                b.own.add(local);
+        }
+    }
+    return b;
+}
+const modifiers = new Set([
+    'skip',
+    'todo',
+    'fixme',
+    'only',
+    'concurrent',
+    'sequential',
+    'serial',
+    'parallel',
+    'shuffle',
+    'slow',
+    'fails',
+    'failing',
+    'fail',
+]);
+const aliases = {
+    xit: ['it', 'skip'],
+    xtest: ['test', 'skip'],
+    xdescribe: ['describe', 'skip'],
+    fit: ['it', 'only'],
+    ftest: ['test', 'only'],
+    fdescribe: ['describe', 'only'],
+};
+const playwrightConfig = new Set(['use', 'setTimeout', 'step', 'info', 'extend', 'configure']);
+/**
+ * What a call's callee means in a test file: `describe`, `it.skip`, `test.each(table)`, `beforeEach`, `test.describe.serial`.
+ * Undefined when the callee is not the framework's.
+ */
+export function classify(callee, b, playwright) {
+    const mods = new Set();
+    let each;
+    let prop;
+    let conditional;
+    let forRows = false;
+    let node = callee;
+    if (ts.isTaggedTemplateExpression(node)) {
+        const tag = chainOf(node.tag);
+        if (tag?.[tag.length - 1] !== 'each')
+            return undefined;
+        each = node;
+        node = node.tag;
+    }
+    else if (ts.isCallExpression(node)) {
+        const inner = chainOf(node.expression);
+        const last = inner?.[inner.length - 1];
+        if (last === 'each' || last === 'for') {
+            each = node;
+            forRows = last === 'for';
+        }
+        else if (last === 'prop')
+            prop = node;
+        else if (last === 'runIf' || last === 'skipIf')
+            conditional = last;
+        else
+            return undefined;
+        node = node.expression;
+    }
+    const chain = chainOf(node);
+    if (chain === undefined)
+        return undefined;
+    let [root, ...rest] = chain;
+    if (b.namespaces.has(root) && rest.length > 0)
+        [root, ...rest] = rest;
+    else if (b.namespaces.has(root))
+        return undefined;
+    if (each !== undefined || prop !== undefined || conditional !== undefined)
+        rest = rest.slice(0, -1);
+    let name = b.imported.get(root);
+    if (name === undefined) {
+        if (b.own.has(root) || !structural.has(root))
+            return undefined;
+        name = root;
+    }
+    const alias = aliases[name];
+    if (alias !== undefined) {
+        name = alias[0];
+        mods.add(alias[1]);
+    }
+    const result = { kind: 'test', mods, each, forRows, prop, conditional };
+    if (playwright) {
+        if (name !== 'test')
+            return undefined;
+        const sub = rest[0];
+        if (sub === 'describe') {
+            result.kind = 'describe';
+            rest = rest.slice(1);
+        }
+        else if (sub === 'beforeEach' || sub === 'afterEach' || sub === 'beforeAll' || sub === 'afterAll') {
+            name = sub;
+            rest = rest.slice(1);
+        }
+        else if (sub !== undefined && playwrightConfig.has(sub)) {
+            result.kind = 'config';
+            result.config = sub;
+            rest = rest.slice(1);
+        }
+        // `test.describe.configure(...)`
+        if (result.kind === 'describe' && rest[0] !== undefined && playwrightConfig.has(rest[0])) {
+            result.kind = 'config';
+            result.config = rest[0];
+            rest = rest.slice(1);
+        }
+    }
+    for (const m of rest) {
+        if (!modifiers.has(m))
+            return undefined;
+        mods.add(m);
+    }
+    if (result.kind === 'config')
+        return result;
+    if (name === 'describe' || name === 'suite')
+        result.kind = 'describe';
+    else if (/^(before|after)(Each|All)?$/.test(name)) {
+        result.kind = 'hook';
+        result.hook = name.startsWith('before') ? 'before' : 'after';
+    }
+    else if (name !== 'it' && name !== 'test')
+        return undefined;
+    return result;
+}

package/dist/migrate/index.d.ts

@@ -0,0 +1,16 @@
+import { type SourceName } from './framework.ts';
+import { type MigrateReport } from './report.ts';
+export interface MigrateOptions {
+    cwd: string;
+    from: SourceName;
+    /** Test files or directories; empty means every test file under `cwd`. */
+    files: string[];
+    write: boolean;
+    /** A directory to write the laws under instead of next to the sources. */
+    out?: string;
+}
+export declare function targetFor(file: string, options: Pick<MigrateOptions, 'cwd' | 'from' | 'out'>): string;
+export declare function migrate(options: MigrateOptions): MigrateReport;
+export declare const migrateUsage: string;
+/** The `migrate` command: prints the report. Status 0 when it ran, 2 when the arguments are wrong. */
+export declare function migrateCommand(cwd: string, from: string | undefined, files: string[], flags: Map<string, string | true>, write: (text: string) => void): number;

package/dist/migrate/index.js

@@ -0,0 +1,155 @@
+// `tslaws migrate <from> [files...] [--write] [--out DIR]`: reads test files of another framework and writes the same
+// tests as laws. A dry run says what would happen; `--write` creates files that do not exist and never replaces one.
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { convertTestFile } from "./convert.js";
+import { frameworkModules, isSourceName, sources } from "./framework.js";
+import { renderReport } from "./report.js";
+const ignoredDirs = new Set(['node_modules', '.tslaws', '.git', 'dist', 'build', 'coverage']);
+const testFile = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+const sourceFile = /\.[cm]?[jt]sx?$/;
+const slash = (path) => path.replace(/\\/g, '/');
+function walk(dir, into) {
+    for (const entry of readdirSync(dir).sort()) {
+        if (ignoredDirs.has(entry))
+            continue;
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            walk(full, into);
+        else if (testFile.test(entry) && !entry.endsWith('.d.ts'))
+            into.push(full);
+    }
+}
+/** The framework modules a file imports or requires. */
+function modulesOf(text) {
+    const found = new Set();
+    for (const match of text.matchAll(/(?:from\s+|import\s*\(\s*|require\s*\(\s*|import\s+)(['"])([^'"]+)\1/g))
+        if (frameworkModules[match[2]] !== undefined)
+            found.add(match[2]);
+    return found;
+}
+/** Whether a file found by searching (not named by the person) belongs to the framework being migrated. */
+function belongs(text, from) {
+    const modules = [...modulesOf(text)];
+    if (from === 'fast-check')
+        return modules.some((m) => frameworkModules[m] === 'fast-check' || m.startsWith('@fast-check/'));
+    if (from === 'playwright')
+        return modules.includes('@playwright/test');
+    const own = modules.filter((m) => frameworkModules[m] === from);
+    if (own.length > 0)
+        return true;
+    // No framework import at all: the file relies on globals, which vitest, jest and rstest provide.
+    return (!modules.some((m) => frameworkModules[m] !== 'fast-check') &&
+        (from === 'vitest' || from === 'jest' || from === 'rstest'));
+}
+/** `src/a.test.ts` to `a`, the name the laws file is built on. */
+function baseOf(file) {
+    const name = basename(file);
+    const stripped = name.replace(/\.(?:test|spec)(?=\.[cm]?[jt]sx?$)/, '').replace(/\.[cm]?[jt]sx?$/, '');
+    return stripped === '' ? name : stripped;
+}
+export function targetFor(file, options) {
+    const suffix = options.from === 'playwright' ? '.browser.laws.ts' : '.laws.ts';
+    const name = `${baseOf(file)}${suffix}`;
+    const dir = dirname(resolve(options.cwd, file));
+    if (options.out === undefined)
+        return join(dir, name);
+    const mirrored = relative(options.cwd, dir);
+    return join(resolve(options.cwd, options.out), mirrored.startsWith('..') ? '' : mirrored, name);
+}
+/** How a module specifier written in the source reads from the file the laws are written to. */
+function rewriter(sourceDir, targetDir) {
+    return (specifier) => {
+        if (sourceDir === targetDir)
+            return specifier;
+        let rel = slash(relative(targetDir, resolve(sourceDir, specifier)));
+        if (rel === '')
+            rel = '.';
+        return rel.startsWith('.') ? rel : `./${rel}`;
+    };
+}
+export function migrate(options) {
+    const { cwd, from } = options;
+    const found = [];
+    const explicit = new Set();
+    for (const file of options.files.length > 0 ? options.files : ['.']) {
+        const full = resolve(cwd, file);
+        if (!existsSync(full))
+            throw new Error(`no such file: ${file}`);
+        if (statSync(full).isDirectory())
+            walk(full, found);
+        else if (sourceFile.test(full)) {
+            found.push(full);
+            explicit.add(full);
+        }
+        else
+            throw new Error(`not a TypeScript or JavaScript file: ${file}`);
+    }
+    const files = [];
+    const claimed = new Set();
+    for (const full of found) {
+        if (/\.laws\.[cm]?[jt]s$/.test(full))
+            continue;
+        const text = readFileSync(full, 'utf8');
+        if (!explicit.has(full) && !belongs(text, from))
+            continue;
+        const source = slash(relative(cwd, full));
+        const target = targetFor(full, options);
+        const converted = convertTestFile({
+            path: full,
+            text,
+            from,
+            rewrite: rewriter(dirname(full), dirname(target)),
+        });
+        for (const entry of converted.entries)
+            entry.file = source;
+        const result = { source, laws: converted.laws, entries: converted.entries, written: 'none' };
+        if (converted.output !== undefined && converted.laws.length > 0) {
+            result.target = slash(relative(cwd, target));
+            result.output = converted.output;
+            if (claimed.has(target)) {
+                result.written = 'exists';
+                result.entries.push({
+                    file: source,
+                    line: 1,
+                    kind: 'note',
+                    message: `${result.target} is already the target of another test file in this run; this file is not written`,
+                });
+            }
+            else if (existsSync(target))
+                result.written = 'exists';
+            else if (options.write) {
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, converted.output);
+                result.written = 'written';
+            }
+            else
+                result.written = 'dry-run';
+            claimed.add(target);
+        }
+        files.push(result);
+    }
+    return { from, write: options.write, files };
+}
+export const migrateUsage = `tslaws migrate ${sources.join('|')} [files...] [--write] [--out DIR]   convert existing tests into laws (*.laws.ts; Playwright becomes *.browser.laws.ts); a dry run unless --write; never overwrites; the new laws are not in the lock`;
+/** The `migrate` command: prints the report. Status 0 when it ran, 2 when the arguments are wrong. */
+export function migrateCommand(cwd, from, files, flags, write) {
+    if (!isSourceName(from)) {
+        write(`tslaws migrate needs the framework to read: one of ${sources.join(', ')}\n`);
+        return 2;
+    }
+    const out = flags.get('out');
+    if (out === true || out === '') {
+        write('--out needs a directory\n');
+        return 2;
+    }
+    try {
+        const report = migrate({ cwd, from, files, write: flags.has('write'), out });
+        write(renderReport(report));
+        return 0;
+    }
+    catch (error) {
+        write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+}

package/dist/migrate/report.d.ts

@@ -0,0 +1,35 @@
+export type EntryKind = 
+/** A test that was skipped on purpose (`.skip`, `.todo`, `xit`): no law is written for it. */
+'skipped'
+/** A construct with no faithful law: it is left out or kept as it was, and the person decides. */
+ | 'unconverted'
+/** Converted, but something was dropped or changes meaning (a timeout, a `.only`, a hook that now runs per law). */
+ | 'note';
+export interface Entry {
+    file: string;
+    line: number;
+    kind: EntryKind;
+    message: string;
+}
+export interface FileResult {
+    /** The source, relative to the working directory, with forward slashes. */
+    source: string;
+    /** Where the laws would be written (relative to the working directory), or undefined when none were produced. */
+    target?: string;
+    /** The text of the converted file. */
+    output?: string;
+    /** Names of the laws written, in order. */
+    laws: string[];
+    entries: Entry[];
+    /** Set by `--write`: whether the file was written, and why not otherwise. */
+    written?: 'written' | 'exists' | 'dry-run' | 'none';
+}
+export interface MigrateReport {
+    from: string;
+    write: boolean;
+    files: FileResult[];
+}
+export declare function lawCount(report: MigrateReport): number;
+export declare function entriesOf(report: MigrateReport, kind: EntryKind): Entry[];
+/** The text `tslaws migrate` prints: a summary, then what was skipped, what could not be converted, and notes. */
+export declare function renderReport(report: MigrateReport): string;

package/dist/migrate/report.js

@@ -0,0 +1,40 @@
+// What a migration tells the person: files read, laws written, and every construct it left behind, with file:line.
+export function lawCount(report) {
+    return report.files.reduce((total, f) => total + f.laws.length, 0);
+}
+export function entriesOf(report, kind) {
+    return report.files.flatMap((f) => f.entries.filter((e) => e.kind === kind));
+}
+/** The text `tslaws migrate` prints: a summary, then what was skipped, what could not be converted, and notes. */
+export function renderReport(report) {
+    const lines = [`tslaws migrate ${report.from}${report.write ? '' : ' (dry run: nothing is written)'}`, ''];
+    for (const file of report.files) {
+        const counts = ['skipped', 'unconverted', 'note']
+            .map((k) => [k, file.entries.filter((e) => e.kind === k).length])
+            .filter(([, n]) => n > 0)
+            .map(([k, n]) => `${n} ${k === 'unconverted' ? 'not converted' : k === 'note' ? (n === 1 ? 'note' : 'notes') : k}`);
+        const where = file.target === undefined
+            ? 'no laws'
+            : `${file.target}: ${file.laws.length} law${file.laws.length === 1 ? '' : 's'}`;
+        const state = file.written === 'written' ? ' [written]' : file.written === 'exists' ? ' [exists: not overwritten]' : '';
+        lines.push(`${file.source} -> ${where}${counts.length > 0 ? ` (${counts.join(', ')})` : ''}${state}`);
+    }
+    const section = (title, kind) => {
+        const found = entriesOf(report, kind);
+        if (found.length === 0)
+            return;
+        lines.push('', `${title} (${found.length}):`);
+        for (const e of found)
+            lines.push(`  ${e.file}:${e.line} ${e.message}`);
+    };
+    section('Skipped, no law written', 'skipped');
+    section('Not converted', 'unconverted');
+    section('Notes', 'note');
+    const converted = report.files.filter((f) => f.target !== undefined).length;
+    lines.push('', `Files: ${report.files.length} read, ${converted} converted. Laws emitted: ${lawCount(report)}. Not converted: ${entriesOf(report, 'unconverted').length}.`);
+    if (!report.write && converted > 0)
+        lines.push('Dry run: pass --write to write the files. Existing files are never overwritten.');
+    if (converted > 0)
+        lines.push('The new laws are not in tsc-laws.lock. Read them, run `tslaws check`, and have a person run `tslaws accept`.');
+    return `${lines.join('\n')}\n`;
+}

package/dist/migrate/source.d.ts

@@ -0,0 +1,42 @@
+import ts from 'typescript';
+export interface Edit {
+    start: number;
+    end: number;
+    text: string;
+}
+export declare function scriptKindOf(file: string): ts.ScriptKind;
+export declare class Source {
+    readonly file: ts.SourceFile;
+    readonly text: string;
+    private readonly edits;
+    private readonly lines;
+    private readonly protectedLines;
+    /** Every identifier that appears anywhere in the file, so new names can avoid them. */
+    readonly taken: Set<string>;
+    readonly path: string;
+    constructor(path: string, text: string);
+    /** 1-based line of a position. */
+    lineOf(pos: number): number;
+    lineOfNode(node: ts.Node): number;
+    /** Replaces `start..end` with a single line of text; the same edit made twice counts once. */
+    edit(start: number, end: number, text: string): void;
+    /** The original text of `start..end` with the edits inside it applied. */
+    private render;
+    /** The text of a node, edits applied, on its own (no reindentation). */
+    textOf(node: ts.Node): string;
+    /** A statement's range including the comments written above it and a comment after it on the same line. */
+    rangeOf(node: ts.Node): [number, number];
+    /** The statements' text at `depth` levels of two spaces, comments included, template strings untouched. */
+    statements(nodes: readonly ts.Node[], depth: number): string[];
+    /** Copies `start..end` as lines at `depth`, keeping the shape the code had. */
+    block(start: number, end: number, depth: number): string[];
+}
+/** Names a statement declares at its top level (variables, destructured ones, functions, classes). */
+export declare function declaredNames(statement: ts.Statement): string[];
+/** Every identifier written inside `node`. */
+export declare function identifiersIn(node: ts.Node, into: Set<string>): void;
+/** A string as a single-quoted TypeScript literal. */
+export declare function quote(value: string): string;
+/** A string literal's value when `node` is a plain string or a template with no substitutions. */
+export declare function literalText(node: ts.Node | undefined): string | undefined;
+export declare function unwrap(node: ts.Expression): ts.Expression;