pabst-checker 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesse Alama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# Pabst: A blue-ribbon approach to **P**roperty-**B**ased **T**esting
+
+Annotate your functions with properties they're supposed to have, then try to invalidate them with [fast-check](https://fast-check.dev/).
+
+Put the properties your functions should have in a JSDoc comment, run Pabst,
+and get either "cases passed" or a counterexample that shows the property doesn't hold.
+
+_Example_ Look at this code. We're trying to assert that the value of the function is
+non-zero provided the second argument is an integer. Can you spot the error?
+
+```ts
+/**
+ * @ensures{nonzero} forall (x: bigint) (y: number),
+ *   Number.isInteger(y) ==> foo(x, y) !== 0
+ */
+export function foo(x: bigint, y: number): number {
+  return Number(x % 2n) + (y % 2) + 1;
+}
+```
+
+Each remainder looks like it should be 0 or 1, so the sum looks like it's at
+least 1. But JavaScript's `%` returns _negative_ remainders for negative
+operands: `foo(-1n, 0)` is `-1 + 0 + 1 === 0`. You don't have to spot that —
+`pabst test` falsifies the property and reports a counterexample.
+
+## Philosophy
+
+Pabst is a property-based testing tool. Instead of checking
+your function against a handful of hand-picked examples,
+pabst (delegating to `fast-check`) generates many random
+inputs and works hard to **refute** the property you
+attached; when it succeeds, it shrinks the failure to a
+small, readable counterexample. One thing should be
+understood, though: failing to invalidate a property — even
+across many runs — is no _proof_ that the property holds. It
+is evidence that it holds, but the property might still be
+false on inputs the generator never tried. If your goal is
+to prove the absence of counterexamples, you need
+proof-based tools such as
+[Thales](https://github.com/jessealama/thales). That said,
+property-based testing is a powerful technique that exposes
+a lot of bugs for very little effort, and it sits
+comfortably alongside proof-based approaches.
+
+## Installation
+
+```bash
+npm install --save-dev pabst-checker
+```
+
+The package is `pabst-checker`; the command it installs is `pabst`.
+
+Requires Node 24+. Pabst bundles its own [vitest](https://vitest.dev/) and
+declares [fast-check](https://fast-check.dev/) as a peer dependency (npm
+installs it for you), so nothing else is needed. The peer relationship
+means pabst validates your annotations against the same fast-check copy
+the generated tests run with — if your project pins an incompatible
+fast-check, npm says so at install time instead of your tests failing
+mysteriously.
+
+## Usage
+
+```bash
+pabst test                             # discover sources, test, print a JSON report
+pabst test <files-or-globs>            # same, on an explicit file list
+pabst test --seed <n> <files-or-globs> # reproduce a prior run's generation
+pabst gen  [files-or-globs]            # generate only; run your own vitest against .pabst/
+```
+
+With no file arguments, pabst discovers your sources: if `tsconfig.json`
+exists, it scans exactly the files `tsc` would compile; otherwise it falls
+back to `src/**`. If neither yields anything, it exits with an error asking
+for an explicit glob. Discovery stays inside the current directory — a
+tsconfig reaching outside it (say, a monorepo `include` of `../shared`) has
+those files skipped; run pabst in the package that owns them.
+
+Declaration files (`.d.ts`) are skipped by default — tsc copies JSDoc into
+them, so scanning both a declaration and its source would extract every
+property twice. A pattern that explicitly names declarations
+(`pabst gen "index.d.ts"`) is honored, for packages whose hand-written types
+are the source.
+
+Pabst writes the test files it generates to a `.pabst/` directory in your
+project. Those files are regenerated on every run, so there is no reason to
+commit them — add `.pabst/` to your `.gitignore`:
+
+```gitignore
+.pabst/
+```
+
+## Output
+
+`pabst test` prints a single JSON object to **stdout**; **stderr** carries only
+progress and crashes. The envelope is always present — a clean run just has an
+empty `issues` array:
+
+```json
+{
+  "version": "0.7.0",
+  "startedAt": "2026-06-26T17:42:03.000Z",
+  "cwd": "/path/to/project",
+  "seed": 1834592013,
+  "generated": 5,
+  "passed": 5,
+  "failed": 0,
+  "issues": []
+}
+```
+
+Each issue records where the property lived and why it failed:
+
+```json
+{
+  "file": "src/math.ts",
+  "function": "add",
+  "property": "commutes",
+  "kind": "falsified",
+  "counterexample": { "x": 1, "y": 2 }
+}
+```
+
+- `kind` is `"falsified"` (returned `false`), `"threw"` (raised an exception —
+  see `error`), or `"exhausted"` (too many precondition skips — `error` explains,
+  and there is no `counterexample`).
+- Counterexample values are JSON-native where they round-trip; bigints and
+  non-finite numbers appear as fast-check strings (e.g. `"1n"`).
+- The `seed` is generated per run and echoed back; pass it to `--seed` to
+  reproduce a failing run exactly.
+
+The process exits `0` when `issues` is empty, `1` when there is at least one
+issue, and `2` on usage errors — including annotation errors such as a
+malformed formula, an unsupported domain, or a reference to an unexported
+symbol, which are reported as a one-line message on stderr.
+
+## Grammar
+
+The normative grammar lives in [`docs/grammar.ebnf`](docs/grammar.ebnf);
+this section is the guided tour.
+
+A property is a universally quantified formula in Pabst's **logic surface**.
+Non-ASCII symbols are the canonical form; most have ASCII fallbacks
+(negation `¬` and the equation glyphs `≡`/`≢` are glyph-only — the ASCII
+spelling of an equation is a plain `Object.is` call).
+
+```ts
+/**
+ * @ensures{guarded} forall (x: int),
+ *   isPrime(x) ∧ x > 2 → isOdd(x)
+ */
+```
+
+- **Quantifier:** `forall` / `∀`, one-or-more binder groups, then a comma, then
+  the body. Lean-style grouping `(x y: int)` is supported. Existential `∃` /
+  `exists` is intentionally rejected (PBT cannot soundly confirm existence).
+- **Domains:** `int`, `nat`, `number`, `boolean`, `string`, `bigint`.
+  A numeric domain (`int`, `nat`, `number`, `bigint`) may be constrained to
+  an interval: `forall (x: int ∈ [1, 30])` (ASCII fallback: `in`). Each
+  bound is independently inclusive (`[`/`]`) or exclusive (`(`/`)`), so
+  `(0, 1]`, `[0, 30)`, and `(0, 30)` all work — for `int`/`nat`/`bigint`
+  an exclusive bound is a ±1 adjustment. An endpoint may be unbounded:
+  `-∞`/`∞` (ASCII: `Infinity`), so `(x: number ∈ (0, ∞))` is a strictly
+  positive number (excluding `-0` — and `Infinity`, since the bound is
+  exclusive; `[0, ∞]` may generate `Infinity` itself). For `int`, `nat`,
+  and `bigint` an ∞ endpoint must be exclusive; for `int`/`nat` it means
+  the safe integer limit (±2^53 − 1), and a finite endpoint beyond that
+  limit clamps to it with a warning. A `nat` interval reaching below 0
+  clamps to 0 (`(-2, 5]` and `(-∞, 5]` denote the same naturals).
+  `number` intervals follow fast-check's double ordering, in which every
+  double is distinct: `-0` sits below `0`, and an exclusive bound removes
+  exactly one adjacent double — so `[-1, 0)` can generate `-0` (which
+  `== 0`), and `(-0, 0]` is the singleton `{0}`. A bounded `number` never
+  generates `NaN`.
+- **Regex guards** constrain a string binder to strings matching a JS
+  regular expression: `forall (s: string ∈ /[a-z]+/)` (ASCII fallback:
+  `in`). Membership means the _whole_ string matches — pabst anchors the
+  pattern for you (lowering to `fc.stringMatching(/^(?:[a-z]+)$/)`), so
+  `/[a-z]+/` never generates `"3fk!"`. Flags `s` and `u` are allowed (`u`
+  enables `\p{...}` escapes); everything else is rejected — `m` because it
+  would reintroduce substring matching, `i`/`v` because fast-check's
+  generator lacks them, `g`/`y`/`d` because they don't affect generation.
+  Patterns outside fast-check's supported subset (lookarounds,
+  backreferences, `\b`) are compile-time errors. Careful inside JSDoc: a
+  `*/` in a pattern (e.g. the trailing star in a pattern matching
+  zero-or-more) ends the comment early — write `{0,}` instead of a
+  trailing `*`, or wrap it in `(?:...)`.
+- **Connectives** (tightest→loosest): `¬` > `∧` > `∨` > `→` > `↔`.
+  Fallbacks: `∧`=`/\`, `∨`=`\/`, `→`=`->`/`==>`, `↔`=`<->`/`iff`.
+  Negation `¬` is glyph-only.
+- **Equations:** `A ≡ B` means identity — sugar for `Object.is(A, B)`;
+  `A ≢ B` is its negation. Both are glyph-only, like `¬`: in plain ASCII,
+  call `Object.is(A, B)` directly (negate at an atom's top level with `≢` or
+  `¬(Object.is(A, B))`; nested `!Object.is(A, B)` is fine). This is
+  SameValue, not mathematical equality: `NaN ≡ NaN` holds and `-0 ≡ 0` does
+  not, so `x + 0 ≡ x` is refutable at `x = -0` (guard with `x ≢ -0 →` if
+  that is intended).
+  An equation lives at the **top level of an atom** — it splits the atom
+  into two JS sides. In nested positions (callbacks, call arguments,
+  template substitutions), call `Object.is` directly:
+  `xs.every(x => Object.is(x, 0))`, not `xs.every(x => x ≡ 0)`.
+  An unparenthesized `??` or ternary beside `≡` is an error — parenthesize
+  the intended grouping, e.g. `a ≡ (b ?? c)` or `a ≡ (b ? c : d)`.
+  Chains like `a ≡ b ≡ c` are errors — write
+  `a ≡ b ∧ b ≡ c`. Loose `==`/`!=` are errors (use `≡`/`≢` or `===`/`!==`);
+  `===`/`!==` keep their exact JS meaning; assignments — plain `=` and
+  compound forms like `+=` — cannot appear in a formula (default-parameter
+  initializers in callbacks are fine); `≠` is rejected with a hint to
+  write `≢`.
+- **Atoms are JavaScript** and must be genuine booleans — every atom is checked
+  at runtime (`5 ∧ true` is an error, not a coercion). You may **not** use JS
+  `&&`/`||`/`!` at an atom's top level — use the glyphs. They remain legal
+  _inside_ a leaf (e.g. a callback `xs.every(x => x > 0 && x < 10)`).
+- **Implication discard:** a **top-level** `→`'s antecedents become `fc.pre(...)`
+  (QuickCheck-style discarded cases, reported as `exhausted` if too many skip);
+  a **parenthesised** `→` is ordinary material implication `¬P ∨ Q`.
+- **Biconditional** `↔` is non-associative (parenthesise chains) and is _not_ a
+  discard — it lowers to boolean equality.
+- **Scoping:** every symbol an atom references must be `export`ed from its module.
+
+Each `@ensures{name}` becomes one issue (keyed by file, function, and property
+name) if it fails. Generated files land in the `.pabst/` directory (see
+[Usage](#usage)) mirroring the source tree; they are regenerated every run and
+must never be hand-edited.
+
+## Development
+
+```bash
+npm install
+npm test          # vitest
+npm run build     # tsc -> dist/
+```
+
+Requires Node 24+.

package/dist/build-spec.d.ts

@@ -0,0 +1,2 @@
+import type { PropertySpec } from "./ir.js";
+export declare function buildSpecs(file: string): PropertySpec[];

package/dist/build-spec.js

@@ -0,0 +1,46 @@
+import { extract } from "./extract.js";
+import { parsePrefix } from "./prefix-parser.js";
+import { parseBody } from "./formula-parser.js";
+import { lowerTop } from "./lower.js";
+import { collectAtoms } from "./formula-ast.js";
+import { freeIdentifiers, classify } from "./free-idents.js";
+import { PabstError } from "./errors.js";
+export function buildSpecs(file) {
+    const { exports, annotations } = extract(file);
+    const specs = [];
+    for (const a of annotations) {
+        try {
+            specs.push(buildSpec(a, exports, file));
+        }
+        catch (e) {
+            if (e instanceof PabstError) {
+                throw new PabstError(`${file}:${a.line}: @ensures{${a.propertyName}}: ${e.message}`, { cause: e });
+            }
+            throw e;
+        }
+    }
+    return specs;
+}
+function buildSpec(a, exports, file) {
+    const { binders, body } = parsePrefix(a.formula);
+    const ast = parseBody(body);
+    const { preconditions, body: loweredBody } = lowerTop(ast);
+    const boundVars = new Set(binders.map((b) => b.varName));
+    const idents = new Set();
+    for (const atom of collectAtoms(ast)) {
+        for (const id of freeIdentifiers(atom))
+            idents.add(id);
+    }
+    const { freeExports } = classify(idents, boundVars, exports);
+    return {
+        name: a.propertyName,
+        functionName: a.functionName,
+        className: a.className,
+        isStatic: a.isStatic,
+        binders,
+        body: loweredBody,
+        preconditions,
+        freeExports,
+        location: { file, line: a.line },
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): number;

package/dist/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFileSync, realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { generate } from "./codegen.js";
+import { resolveFiles } from "./discover.js";
+import { PabstError } from "./errors.js";
+import { runTests } from "./run.js";
+import { randomSeed, parseSeed } from "./seed.js";
+function readVersion() {
+    const url = new URL("../package.json", import.meta.url);
+    return JSON.parse(readFileSync(url, "utf8")).version;
+}
+const USAGE = "usage: pabst <test|gen> [--seed <n>] [files-or-globs...]";
+const HELP = `${USAGE}
+
+commands:
+  test  generate property tests from @ensures annotations, run them, and
+        print a JSON report to stdout
+  gen   generate only; run your own vitest against .pabst/
+
+when no files are given, pabst discovers your sources: the files that
+tsconfig.json would compile or, failing that, src/**. declaration files
+(.d.ts) are skipped unless a pattern names them (e.g. pabst gen index.d.ts).
+
+options:
+  --seed <n>  reproduce a prior run's generation (n is echoed in the report)
+  -h, --help  show this help`;
+export function main(argv = process.argv.slice(2)) {
+    // parseArgs throws on unknown options and the like — usage errors, which
+    // map to the documented exit-2 mode; anything else crashes loudly.
+    let positionals;
+    let values;
+    try {
+        ({ positionals, values } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                seed: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+        }));
+    }
+    catch (e) {
+        if (e instanceof TypeError &&
+            "code" in e &&
+            typeof e.code === "string" &&
+            e.code.startsWith("ERR_PARSE_ARGS_")) {
+            console.error(USAGE);
+            return 2;
+        }
+        throw e;
+    }
+    if (values.help) {
+        console.log(HELP);
+        return 0;
+    }
+    const command = positionals[0];
+    const patterns = positionals.slice(1);
+    if (command !== "test" && command !== "gen") {
+        console.error(USAGE);
+        return 2;
+    }
+    // User-facing errors anywhere below — a bad --seed, file resolution coming
+    // up empty, a malformed tsconfig, compile errors — are PabstErrors and map
+    // to the documented exit-2 error mode; anything else is an internal bug
+    // and crashes loudly.
+    try {
+        return run(command, patterns, values.seed);
+    }
+    catch (e) {
+        if (e instanceof PabstError) {
+            console.error(`error: ${e.message}`);
+            return 2;
+        }
+        throw e;
+    }
+}
+function run(command, patterns, seedArg) {
+    const seed = seedArg !== undefined ? parseSeed(seedArg) : randomSeed();
+    const { files, source } = resolveFiles(patterns);
+    if (source !== "arguments") {
+        console.error(`pabst: no files given; discovered ${files.length} file(s) via ${source}`);
+    }
+    const startedAt = new Date().toISOString();
+    const cwd = process.cwd();
+    const version = readVersion();
+    const results = generate(files, ".pabst", seed);
+    const generated = results.reduce((n, r) => n + r.propertyCount, 0);
+    console.error(`pabst: generated ${generated} propert${generated === 1 ? "y" : "ies"} across ${results.length} file(s) into .pabst/`);
+    if (command === "gen")
+        return 0;
+    const result = runTests(".pabst", {
+        version,
+        startedAt,
+        cwd,
+        seed,
+        generated,
+    });
+    if (result.kind === "no-results") {
+        process.stderr.write(result.stdout);
+        process.stderr.write(result.stderr);
+        return result.status;
+    }
+    if (result.kind === "broken-run") {
+        for (const m of result.messages)
+            console.error(`error: ${m}`);
+        return result.status;
+    }
+    console.log(JSON.stringify(result.envelope, null, 2));
+    return result.envelope.failed > 0 ? 1 : 0;
+}
+// npm installs the bin as a symlink (node_modules/.bin/pabst -> this file).
+// Node resolves the main module to its realpath, but argv[1] keeps the
+// symlink path, so argv[1] must be realpath'd before comparing.
+if (process.argv[1] &&
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    process.exit(main());
+}

package/dist/codegen.d.ts

@@ -0,0 +1,6 @@
+export interface GenResult {
+    sourceFile: string;
+    outFile: string;
+    propertyCount: number;
+}
+export declare function generate(files: string[], outRoot?: string, seed?: number): GenResult[];

package/dist/codegen.js

@@ -0,0 +1,30 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildSpecs } from "./build-spec.js";
+import { emit } from "./emit.js";
+import { PabstError } from "./errors.js";
+import { randomSeed } from "./seed.js";
+const SRC_EXT = /\.(ts|tsx|mts|cts|js|mjs|cjs)$/;
+export function generate(files, outRoot = ".pabst", seed = randomSeed()) {
+    const results = [];
+    for (const file of files) {
+        const rel = path.relative(process.cwd(), path.resolve(file));
+        // Out files mirror rel under outRoot, so a ".."-led (or, across Windows
+        // drives, absolute) rel would place them outside it — where the runner
+        // never looks. Refuse rather than silently skip what looks generated.
+        if (rel === ".." ||
+            rel.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(rel)) {
+            throw new PabstError(`${file} is outside the current directory; run pabst from the directory containing it`);
+        }
+        const specs = buildSpecs(file);
+        if (specs.length === 0)
+            continue;
+        const noExt = rel.replace(SRC_EXT, "");
+        const outFile = path.join(outRoot, noExt + ".pabst.test.ts");
+        fs.mkdirSync(path.dirname(outFile), { recursive: true });
+        fs.writeFileSync(outFile, emit(specs, file, outFile, seed), "utf8");
+        results.push({ sourceFile: file, outFile, propertyCount: specs.length });
+    }
+    return results;
+}

package/dist/desugar.d.ts

@@ -0,0 +1,5 @@
+export interface Desugared {
+    preconditions: string[];
+    body: string;
+}
+export declare function desugar(body: string): Desugared;

package/dist/desugar.js

@@ -0,0 +1,136 @@
+/** Split `s` at depth-0 implication arrows (==>, ->, →). Returns trimmed segments. */
+function splitTopArrows(s) {
+    const segs = [];
+    let depth = 0;
+    let start = 0;
+    let str = null;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (str) {
+            if (c === "\\") {
+                i++;
+                continue;
+            }
+            if (c === str)
+                str = null;
+            continue;
+        }
+        if (c === "'" || c === '"' || c === "`") {
+            str = c;
+            continue;
+        }
+        if (c === "(" || c === "[" || c === "{") {
+            depth++;
+            continue;
+        }
+        if (c === ")" || c === "]" || c === "}") {
+            depth--;
+            continue;
+        }
+        if (depth !== 0)
+            continue;
+        if (s.startsWith("==>", i)) {
+            segs.push(s.slice(start, i).trim());
+            i += 2;
+            start = i + 1;
+            continue;
+        }
+        if (s.startsWith("->", i)) {
+            segs.push(s.slice(start, i).trim());
+            i += 1;
+            start = i + 1;
+            continue;
+        }
+        if (c === "→") {
+            segs.push(s.slice(start, i).trim());
+            start = i + 1;
+            continue;
+        }
+    }
+    segs.push(s.slice(start).trim());
+    return segs;
+}
+/** Index of the `)` matching the `(` at `open`. */
+function matchParen(s, open) {
+    let depth = 0;
+    let str = null;
+    for (let i = open; i < s.length; i++) {
+        const c = s[i];
+        if (str) {
+            if (c === "\\") {
+                i++;
+                continue;
+            }
+            if (c === str)
+                str = null;
+            continue;
+        }
+        if (c === "'" || c === '"' || c === "`") {
+            str = c;
+            continue;
+        }
+        if (c === "(")
+            depth++;
+        else if (c === ")") {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    throw new Error(`unbalanced parentheses in property body: ${s}`);
+}
+/** Desugar arrows that appear inside parentheses; pass everything else through. */
+function desugarNested(s) {
+    let out = "";
+    let i = 0;
+    let str = null;
+    while (i < s.length) {
+        const c = s[i];
+        if (str) {
+            out += c;
+            if (c === "\\" && i + 1 < s.length) {
+                out += s[i + 1];
+                i += 2;
+                continue;
+            }
+            if (c === str)
+                str = null;
+            i++;
+            continue;
+        }
+        if (c === "'" || c === '"' || c === "`") {
+            str = c;
+            out += c;
+            i++;
+            continue;
+        }
+        if (c === "(") {
+            const close = matchParen(s, i);
+            out += "(" + desugarExpr(s.slice(i + 1, close)) + ")";
+            i = close + 1;
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    return out;
+}
+/** Fully desugar an expression: arrows at this level → !(P)||(Q), then recurse into parens. */
+function desugarExpr(s) {
+    return foldImplication(splitTopArrows(s));
+}
+function foldImplication(segs) {
+    if (segs.length === 1)
+        return desugarNested(segs[0]);
+    return `!(${desugarNested(segs[0])}) || (${foldImplication(segs.slice(1))})`;
+}
+export function desugar(body) {
+    const segs = splitTopArrows(body);
+    if (segs.length === 1) {
+        return { preconditions: [], body: desugarNested(segs[0]) };
+    }
+    return {
+        preconditions: segs.slice(0, -1).map(desugarNested),
+        body: desugarNested(segs[segs.length - 1]),
+    };
+}

package/dist/discover.d.ts

@@ -0,0 +1,16 @@
+/**
+ * True for TypeScript source files pabst should scan: .ts/.tsx/.mts/.cts,
+ * excluding declaration files — tsc copies JSDoc into declarations, so
+ * scanning them alongside their sources extracts every property twice.
+ */
+export declare function isTsSource(file: string): boolean;
+export interface Discovery {
+    files: string[];
+    source: "arguments" | "tsconfig.json" | "src/";
+}
+/**
+ * The files pabst should scan: matches of the given patterns or, with no
+ * patterns, zero-argument discovery (the tsconfig.json file list, then the
+ * src/ convention). Throws PabstError when nothing usable is found.
+ */
+export declare function resolveFiles(patterns: string[]): Discovery;