@catalystiq/test-kit 0.1.0 → 0.3.0

package/dist/env/scan.js

@@ -0,0 +1,327 @@
+/**
+ * Which environment variables a repository's code reads, by name, and whether `.env.example` lists exactly those.
+ *
+ * The reads come from each file's syntax tree (see {@link envNamesInText}). A name built at run time
+ * (`process.env[name]`) is not seen: list it in `.env.example` under a comment saying `UNSCANNED`.
+ *
+ * The files are the repository's tracked code (`git ls-files`), less tests, fixtures, type declarations and the paths
+ * the caller excludes. Needs `typescript` installed (a peer dependency).
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { duplicateNames, parseEnvExample } from "./example.js";
+const CAPITALS = /^[A-Z][A-Z0-9_]*$/;
+const CODE = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
+const SKIP_SEGMENTS = new Set(['node_modules', '__tests__', '__mocks__', 'fixtures', '.next', 'dist', 'coverage']);
+/** Test trees at the top of the repository only: `src/app/test/page.tsx` is a route. */
+const SKIP_TOP = new Set(['test', 'tests', 'e2e']);
+const SKIP_FILE = /\.(?:test|spec)\.[^/]+$|\.pw\.ts$|\.d\.ts$/;
+/** npm's own variables and a runtime's internals (`__NEXT_…`) are not the app's to list. */
+const NOT_THE_APPS = /^(?:npm_|_)/;
+/** What Vite itself puts on `import.meta.env`. */
+const VITE_BUILT_INS = new Set(['BASE_URL', 'DEV', 'MODE', 'PROD', 'SSR']);
+/** TypeScript, loaded on first use, so `/env` imports (the guard) work where it is not installed. */
+let tsModule = null;
+function typescript() {
+    if (tsModule === null) {
+        try {
+            tsModule = createRequire(import.meta.url)('typescript');
+        }
+        catch {
+            throw new Error('tk-check-env-example needs typescript installed (a peer dependency of @catalystiq/test-kit)');
+        }
+    }
+    return tsModule;
+}
+/** Whether `name`, read off that object, is an environment variable. A bare `env` object counts in capitals only. */
+function isVariable(kind, name) {
+    if (NOT_THE_APPS.test(name))
+        return false;
+    if (kind === 'bare')
+        return CAPITALS.test(name);
+    if (kind === 'meta')
+        return !VITE_BUILT_INS.has(name);
+    return true;
+}
+function scriptKind(ts, fileName) {
+    if (/\.tsx$/.test(fileName))
+        return ts.ScriptKind.TSX;
+    if (/\.[mc]?ts$/.test(fileName))
+        return ts.ScriptKind.TS;
+    return ts.ScriptKind.JSX;
+}
+/**
+ * The variable names a source text reads, from its syntax tree (TypeScript's parser): comments, strings and regular
+ * expressions are never mistaken for code.
+ *
+ * A key may be a literal or a top-level string constant (`env[GOOGLE_CLIENT_ID_ENV]`), this file's or one in
+ * `constants` (the repository's, {@link stringConstants}).
+ *
+ * The environment is `process.env` (also `globalThis.process.env`, `process['env']`), `import.meta.env` (less Vite's
+ * own `DEV`, `MODE`, …), a name the file binds to one of those (`const e = process.env`), and any object named `env`
+ * (capitals only: `env.local` is not a variable; a file whose `env` is something else goes in `--exclude`). A read off
+ * it is a property (`.NAME`, `?.NAME`), an element with a literal key (`['NAME']`), an `in` test (`'NAME' in …`), or a
+ * destructuring (`const { NAME, OTHER: x }: T = …`, a parameter default, an assignment `({ NAME } = …)`). A method call
+ * (`process.env.toString()`) and a write (`process.env.TZ = …`, `delete process.env.X`) are not reads; a presence check
+ * (`Object.hasOwn(process.env, 'X')`, `Reflect.has(…)`, `.hasOwnProperty('X')`) is. `const { env: e } = process` makes
+ * `e` an alias.
+ */
+export function envNamesInText(source, fileName = 'file.ts', constants = new Map()) {
+    const ts = typescript();
+    const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKind(ts, fileName));
+    const own = topLevelStrings(ts, file);
+    const aliases = new Map();
+    const unwrapped = (node) => {
+        let n = node;
+        while (ts.isParenthesizedExpression(n) || ts.isNonNullExpression(n) || ts.isAsExpression(n) || ts.isSatisfiesExpression(n))
+            n = n.expression;
+        return n;
+    };
+    const literal = (node) => node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : undefined;
+    /** `process`, or `globalThis.process`. */
+    const isProcess = (node) => {
+        const n = unwrapped(node);
+        if (ts.isIdentifier(n))
+            return n.text === 'process';
+        return ts.isPropertyAccessExpression(n) && n.name.text === 'process' && ts.isIdentifier(n.expression) && n.expression.text === 'globalThis';
+    };
+    const envObject = (node) => {
+        const n = unwrapped(node);
+        if (ts.isIdentifier(n))
+            return aliases.get(n.text) ?? (n.text === 'env' ? 'bare' : null);
+        const key = ts.isPropertyAccessExpression(n) ? n.name.text : ts.isElementAccessExpression(n) ? literal(n.argumentExpression) : undefined;
+        if (key !== 'env' || !(ts.isPropertyAccessExpression(n) || ts.isElementAccessExpression(n)))
+            return null;
+        const owner = n.expression;
+        if (isProcess(owner))
+            return 'process';
+        if (ts.isMetaProperty(owner) && owner.keywordToken === ts.SyntaxKind.ImportKeyword && owner.name.text === 'meta')
+            return 'meta';
+        return null;
+    };
+    /** A method call on the object, an assignment to it, or a `delete` of it. */
+    const isNotARead = (node) => {
+        const parent = node.parent;
+        if (ts.isCallExpression(parent) && parent.expression === node)
+            return true;
+        if (ts.isDeleteExpression(parent))
+            return true;
+        // Only a plain `=` writes without reading: `??=`, `||=` and `+=` read the variable first.
+        return ts.isBinaryExpression(parent) && parent.left === node && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken;
+    };
+    // Aliases first: `const e = process.env` makes `e.NAME` a read, for a name the file declares only once (there is no
+    // scope analysis, so a name declared twice, once as the environment and once as something else, is no alias).
+    const declared = new Map();
+    const candidates = new Map();
+    const collectAliases = (node) => {
+        if ((ts.isVariableDeclaration(node) || ts.isParameter(node)) && ts.isIdentifier(node.name)) {
+            declared.set(node.name.text, (declared.get(node.name.text) ?? 0) + 1);
+            const kind = ts.isVariableDeclaration(node) && node.initializer ? envObject(node.initializer) : null;
+            if (kind === 'process' || kind === 'meta')
+                candidates.set(node.name.text, kind);
+        }
+        if (ts.isBindingElement(node) && ts.isIdentifier(node.name)) {
+            declared.set(node.name.text, (declared.get(node.name.text) ?? 0) + 1);
+            // `const { env: e } = process` (or `globalThis.process`).
+            const declaration = node.parent.parent;
+            const key = node.propertyName ?? node.name;
+            if (ts.isIdentifier(key) && key.text === 'env' && ts.isVariableDeclaration(declaration) && declaration.initializer && isProcess(declaration.initializer)) {
+                candidates.set(node.name.text, 'process');
+            }
+        }
+        ts.forEachChild(node, collectAliases);
+    };
+    collectAliases(file);
+    for (const [name, kind] of candidates)
+        if (declared.get(name) === 1)
+            aliases.set(name, kind);
+    /** A literal key, or a named constant holding one (`env[GOOGLE_CLIENT_ID_ENV]`): this file's, else the repository's. */
+    const keyOf = (node) => {
+        const text = literal(node);
+        if (text !== undefined || !ts.isIdentifier(node))
+            return text;
+        // A name the file declares again (a parameter `KEY`, a local `const KEY`) is not the constant.
+        const declarations = declared.get(node.text) ?? 0;
+        if (own.has(node.text))
+            return declarations === 1 ? own.get(node.text) : undefined;
+        return declarations === 0 ? constants.get(node.text) : undefined;
+    };
+    const names = new Set();
+    const add = (kind, name) => {
+        if (kind !== null && name !== undefined && isVariable(kind, name))
+            names.add(name);
+    };
+    const keyText = (key) => {
+        if (key === undefined)
+            return undefined;
+        if (ts.isIdentifier(key) || ts.isStringLiteral(key))
+            return key.text;
+        if (ts.isComputedPropertyName(key))
+            return literal(key.expression);
+        return undefined;
+    };
+    const addPattern = (pattern, from) => {
+        if (!from || !ts.isObjectBindingPattern(pattern))
+            return;
+        const kind = envObject(from);
+        for (const element of pattern.elements)
+            if (!element.dotDotDotToken)
+                add(kind, keyText(element.propertyName ?? element.name));
+    };
+    /** `Object.hasOwn(env, 'X')`, `Reflect.has(env, 'X')`, `env.hasOwnProperty('X')`: a presence check is a read. */
+    const presenceCheck = (node) => {
+        const callee = unwrapped(node.expression);
+        if (!ts.isPropertyAccessExpression(callee))
+            return;
+        const method = callee.name.text;
+        const owner = unwrapped(callee.expression);
+        if (method === 'hasOwnProperty' || method === 'propertyIsEnumerable')
+            add(envObject(owner), literal(node.arguments[0]));
+        else if (ts.isIdentifier(owner) && ((owner.text === 'Object' && method === 'hasOwn') || (owner.text === 'Reflect' && method === 'has'))) {
+            const target = node.arguments[0];
+            if (target)
+                add(envObject(target), literal(node.arguments[1]));
+        }
+    };
+    const visit = (node) => {
+        if (ts.isCallExpression(node))
+            presenceCheck(node);
+        if (ts.isPropertyAccessExpression(node)) {
+            if (!isNotARead(node))
+                add(envObject(node.expression), node.name.text);
+        }
+        else if (ts.isElementAccessExpression(node)) {
+            if (!isNotARead(node))
+                add(envObject(node.expression), keyOf(node.argumentExpression));
+        }
+        else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.InKeyword) {
+            add(envObject(node.right), keyOf(node.left));
+        }
+        else if (ts.isVariableDeclaration(node) || ts.isParameter(node)) {
+            addPattern(node.name, node.initializer);
+        }
+        else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isObjectLiteralExpression(unwrapped(node.left))) {
+            const kind = envObject(node.right);
+            for (const property of unwrapped(node.left).properties) {
+                if (ts.isShorthandPropertyAssignment(property) || ts.isPropertyAssignment(property))
+                    add(kind, keyText(property.name));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return [...names].sort();
+}
+/** A file's top-level `const NAME = 'text'` (exported or not, `as const` or not), by name. */
+function topLevelStrings(ts, file) {
+    const found = new Map();
+    for (const statement of file.statements) {
+        if (!ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            let init = declaration.initializer;
+            while (init && (ts.isAsExpression(init) || ts.isSatisfiesExpression(init) || ts.isParenthesizedExpression(init)))
+                init = init.expression;
+            if (ts.isIdentifier(declaration.name) && init && (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init))) {
+                found.set(declaration.name.text, init.text);
+            }
+        }
+    }
+    return found;
+}
+/**
+ * The repository's top-level string constants, by name, so a read through a constant another file exports
+ * (`process.env[SECRET_ENV]`) is seen. A name two files define with different text resolves to nothing.
+ */
+export function stringConstants(texts) {
+    const ts = typescript();
+    const found = new Map();
+    for (const [fileName, text] of texts) {
+        const file = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, false, scriptKind(ts, fileName));
+        for (const [name, value] of topLevelStrings(ts, file))
+            found.set(name, found.has(name) && found.get(name) !== value ? null : value);
+    }
+    return new Map([...found].filter((entry) => entry[1] !== null));
+}
+/** Whether a repository-relative path is code the scan reads. */
+export function isScannedPath(path, exclude = []) {
+    if (!CODE.test(path) || SKIP_FILE.test(path))
+        return false;
+    const segments = path.split('/');
+    if (SKIP_TOP.has(segments[0]) || segments.some((segment) => SKIP_SEGMENTS.has(segment)))
+        return false;
+    return !exclude.map(normalisedPrefix).some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+/** `./scripts/one-off/` as git spells it: `scripts/one-off`. */
+function normalisedPrefix(prefix) {
+    return prefix.replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+}
+/** The code files of the repository at `root`: tracked, or new and not ignored. */
+export function scannedFiles(root, exclude = []) {
+    // Tracked files and new ones git does not ignore, so a file not yet added is scanned too.
+    const listed = execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    const paths = listed
+        .split('\0')
+        .filter(Boolean)
+        .filter((path) => isScannedPath(path, exclude));
+    return [...new Set(paths)].sort();
+}
+/** Each name read, with the first file that reads it. */
+export function envReads(root, files) {
+    const texts = [];
+    for (const file of files) {
+        try {
+            texts.push([file, readFileSync(join(root, file), 'utf8')]);
+        }
+        catch {
+            // listed by git but deleted in the working tree
+        }
+    }
+    const constants = stringConstants(texts);
+    const reads = new Map();
+    for (const [file, text] of texts)
+        for (const name of envNamesInText(text, file, constants))
+            if (!reads.has(name))
+                reads.set(name, file);
+    return reads;
+}
+/** Compares `.env.example` with what the code reads. Every problem names variables, never a value. */
+export function checkEnvExample(root, example, exclude = []) {
+    let text;
+    try {
+        text = readFileSync(join(root, example), 'utf8');
+    }
+    catch {
+        return { problems: [`${example} does not exist`], files: 0, read: 0, listed: 0 };
+    }
+    const entries = parseEnvExample(text);
+    const all = scannedFiles(root);
+    const files = all.filter((path) => isScannedPath(path, exclude));
+    const reads = envReads(root, files);
+    const problems = [];
+    if (files.length === 0)
+        problems.push('the scan found no code files: the check would pass on nothing');
+    else if (reads.size === 0)
+        problems.push(`the scan found no environment read in ${files.length} files: the check would pass on nothing`);
+    if (entries.length === 0)
+        problems.push(`${example} names no variable`);
+    for (const prefix of exclude) {
+        if (all.every((path) => isScannedPath(path, [prefix])))
+            problems.push(`--exclude ${prefix} matches no scanned file`);
+    }
+    for (const name of duplicateNames(entries))
+        problems.push(`${name} is listed more than once in ${example}`);
+    const listed = new Map(entries.map((e) => [e.name, e]));
+    for (const [name, file] of [...reads].sort(([a], [b]) => a.localeCompare(b))) {
+        if (!listed.has(name))
+            problems.push(`${name} is read (${file}) but not listed in ${example}`);
+    }
+    for (const e of entries) {
+        if (!e.unscanned && !reads.has(e.name) && listed.get(e.name) === e) {
+            problems.push(`${e.name} is listed in ${example} (line ${e.line}) but no code reads it: remove it, or say UNSCANNED in its comment`);
+        }
+    }
+    return { problems, files: files.length, read: reads.size, listed: listed.size };
+}

package/dist/neon-test-db/README.md

@@ -0,0 +1,53 @@
+# `tk-neon-test-db`
+
+The local database test run, `npm run test:db`: a short-lived Neon branch for one command, deleted afterwards.
+
+It moved here from `getcatalystiq/github-actions` (`scripts/neon-test-db.mjs`), which every app vendored unchanged. The
+script is the same; apps now run it from the package.
+
+## Use it
+
+```json
+{
+  "devDependencies": { "@catalystiq/test-kit": "<exact version>" },
+  "scripts": { "test:db": "NEON_TEST_DB_PROJECT=… NEON_TEST_DB_PARENT=… NEON_TEST_DB_REFUSE=… tk-neon-test-db -- npm run ci:db" }
+}
+```
+
+## What it does
+
+- It **cuts** a short-lived, **schema-only** branch of `NEON_TEST_DB_PARENT` (the parent's schema, none of its rows, so
+  never production data), runs the command after `--` with `DATABASE_URL` set to that branch, and **deletes** the branch
+  it made whatever the command did, a Ctrl-C included. It deletes nothing else: the delete names the id this run created.
+- Under the kit's Vitest setup, `DATABASE_URL` holds a password, so the credential strip deletes it in each worker unless
+  the config lists it in `keepEnv` (`defineTestKitConfig({ keepEnv: ['DATABASE_URL'] })`), which also lets the tests
+  reach its host. Neon's serverless HTTP driver queries the region's gateway (`api.<region>.neon.tech`) instead, so a
+  suite that uses it lists that host in `allowHosts` too (the setup README, Network).
+- The branch carries an **expiry** (default 2 hours, at most 6), so a branch whose process died is collected by Neon.
+- It **refuses** a project listed in `NEON_TEST_DB_REFUSE` (name production's) before any call.
+- The connection string is never printed. The branch is named `tmp/test-db-<user>-<UTC yyyymmddhhmmss>-<4 hex>`.
+- `NEON_TEST_DB_INIT=parent-data` asks for a **data** copy instead, only of a parent whose branch id (never a name) is
+  listed in `NEON_TEST_DB_DATA_PARENTS`: the parents the repository names as customer-free. The branch must come back as
+  a data copy of that parent, or it is deleted unused.
+
+## Configuration
+
+From the environment (a repository's `.env.local` is not read; export them or use `dotenv --`):
+
+| Variable | Meaning |
+|---|---|
+| `NEON_API_KEY` | A key that reaches the project (a personal key, or `neonctl`'s token for a short run). |
+| `NEON_TEST_DB_PROJECT` | The Neon project id. |
+| `NEON_TEST_DB_PARENT` | The parent branch id (`br-…`) or name whose schema is copied. Never production's. |
+| `NEON_TEST_DB_REFUSE` | Project ids this command refuses outright (name production). |
+| `NEON_TEST_DB_DATABASE` | The database to connect to (default: the branch's one database that is not `postgres`). |
+| `NEON_TEST_DB_EXPIRES` | Minutes until Neon deletes the branch on its own (default 120, at most 360). |
+| `NEON_TEST_DB_KEEP=1` | Keep the branch afterwards (it still expires); prints its id, never its password. |
+| `NEON_TEST_DB_INIT` | `schema-only` (the default) or `parent-data` (above). |
+| `NEON_TEST_DB_DATA_PARENTS` | The branch ids `parent-data` may copy. |
+
+Exit codes: the command's own; 1 when the branch could not be made, checked or deleted; 2 for a configuration problem;
+128 + the signal number after a signal (130 for a Ctrl-C).
+
+The module also exports `readConfig`, `branchName` and `main` (`@catalystiq/test-kit/neon-test-db`), for a repository
+that wants to test its own `test:db` wiring.

package/dist/neon-test-db/neon-test-db.d.mts

@@ -0,0 +1,35 @@
+// Types for neon-test-db.mjs, the `tk-neon-test-db` CLI (see README.md beside it). The script stays plain JavaScript so
+// it runs with no build step and is the same file github-actions' apps ran as a vendored copy.
+
+export declare const SCHEMA_ONLY_SOURCES: string[];
+export declare const INIT_SOURCES: string[];
+export declare const NEON_API: string;
+export declare const MAX_EXPIRES: number;
+
+export interface NeonTestDbConfig {
+  problems: string[];
+  key: string;
+  project: string;
+  parent: string;
+  expires: number;
+  database: string;
+  init: string;
+  dataParents: string[];
+  keep: boolean;
+  command: string[];
+}
+
+export interface NeonTestDbDeps {
+  /** What the script reads of an answer: `ok`, `status` and `json()`. */
+  fetch: (url: string, init: RequestInit) => Promise<Pick<Response, 'ok' | 'status' | 'json'>>;
+  run: (command: string[], env: Record<string, string | undefined>) => Promise<number>;
+  log: (line: string) => void;
+  now: () => Date;
+  sleep: (ms: number) => Promise<void>;
+  onSignal: (handler: (signal?: string) => void) => () => void;
+}
+
+export declare function readConfig(env: Record<string, string | undefined>, argv: string[]): NeonTestDbConfig;
+export declare function branchName(user: string | undefined, now: Date, rand: string): string;
+/** Runs the whole flow; returns the exit code. */
+export declare function main(env: Record<string, string | undefined>, argv: string[], deps: NeonTestDbDeps): Promise<number>;