verifika 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/). The CLI flags, exit codes, configuration format (`version: 1`) and JSON output (`schemaVersion: 1`) are the public API.
+
+## [0.0.2] - 2026-10-12
+
+### Changed
+
+- `vfk` is now the advertised command: `--help`, run hints (`Run: vfk logs <check>`), error hints, the README, the docs and the agent skill use it. `verifika` keeps working and is identical.
+
+### Added
+
+- README: a copy-paste prompt that has a coding agent install Verifika, write and validate a config, and install the skill.
+
+## [0.0.1] - 2026-10-12
+
+First public release.
+
+### Added
+
+- `vfk`: a shorthand executable for `verifika`, installed by the same package.
+- `verifika` / `verifika run`: runs configured checks concurrently with dependency ordering, per-check timeouts, optional fail-fast, process-tree cleanup and signal handling.
+- Safety defaults: checks run sequentially unless `defaults.concurrency` or `-j` opts into parallelism; CI always runs the full suite unless `--changed`/`--changed-since` is passed explicitly (environment variables cannot switch CI mode off); a check passes only if its process tree was confirmed cleaned up; concurrent Verifika invocations in one directory keep their run records and logs apart.
+- Hybrid selection: selective runs from git changes locally (`changes.base`, `--changed`, `--changed-since <ref>` with merge-base semantics), full runs in CI and with `--all`, explicit `--check`. Global invalidation (`invalidateAll`), `paths`/`exclude` globs, `always` checks and `dependsOn`.
+- Conservative fallbacks: full runs when git cannot determine changes implicitly; exit 2 when an explicit comparison is impossible.
+- Output modes: `human` (live progress), `agent` (one line on success, bounded failure preview), `json` (versioned result, `schemaVersion: 1`) and `quiet`.
+- `verifika plan` to show selection decisions and reasons without running checks.
+- `verifika logs` with `--failed`, `--tail` and `--run`; logs stored in a self-ignoring `.verifika/` directory with retention (`defaults.keepRuns`).
+- `verifika init` to create a starter config from `package.json` scripts.
+- JSON schema for `verifika.config.json` with editor autocomplete.
+- Agent skill (`skills/verifika/SKILL.md`) for Claude Code, Codex, OpenCode and other agents.
+- Published to npm as `verifika`; the package tarball is also attached to the GitHub release.
+
+### Known limitations
+
+- No per-check lock: checks that write shared outputs need `dependsOn` or `concurrency: 1` (see the configuration reference).
+- A process that deliberately detaches from the check (on Linux and macOS: leaves the process group, for example via `setsid`; on Windows: breaks away from the job with an exited intermediate parent) is not tracked unless it keeps the check's output open, in which case the check is reported as `error`.
+- On Windows, confirming cleanup queries the process table with PowerShell after each check, which costs roughly 0.5–3 s per check.
+
+[0.0.2]: https://github.com/alexportelli12/verifika/releases/tag/v0.0.2
+[0.0.1]: https://github.com/alexportelli12/verifika/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Portelli
+
+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

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# Verifika
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/alexportelli12/verifika/actions/workflows/ci.yml/badge.svg)](https://github.com/alexportelli12/verifika/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/alexportelli12/verifika)](https://github.com/alexportelli12/verifika/releases/latest)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Run only the checks your change needs. Get one line back when they pass.**
+
+Every repository has a verification gate: format, lint, typecheck, tests, build. Using it well is harder than it looks:
+
+- **Running everything is slow.** A one-line fix waits minutes for checks it cannot affect, so people (and agents) skip the gate or batch changes until the end.
+- **Picking checks by hand is unreliable.** It is easy to forget the one that breaks, and "it passed" stops meaning much.
+- **Failures are buried in noise.** A test runner can print tens of thousands of lines to report one failed assertion. A coding agent pays for every line in tokens and context, and often never reaches the line that matters.
+
+Verifika fixes this with one config file and one command. You list your checks in `verifika.config.json`, with the files each one covers. Then `vfk` runs only the checks your changes affect, CI runs all of them, and the output says exactly what failed:
+
+```text
+$ vfk
+PASS 3/3 (4.1s) selective: 2 files changed since HEAD (a1b2c3d); 2 skipped
+
+$ vfk --all
+FAIL 4/5 (12s) full run (--all)
+typecheck: exit 2
+  src/cart.ts(14,7): error TS2322: Type 'string' is not assignable to type 'number'.
+Run: vfk logs typecheck
+```
+
+## Why Verifika
+
+- **Small output, especially for agents.** On a real Angular project, one failing test produced 94,900 bytes of output with the project's previous verify script (~23,700 tokens). Verifika reported the same failure in 369 bytes (~90 tokens): the test name, the assertion and the totals. Full logs stay on disk until you ask for them.
+- **Less waiting.** Locally, only affected checks run: in a 25-check monorepo, a typical edit ran 1–13 of them. Checks that share no build outputs can also run in parallel; on that Angular project, four at a time cut the full gate from 95.5 s to 61.7 s. [Measurements](docs/benchmarks.md).
+- **Deterministic and conservative.** Selection comes from your config, file globs, dependencies and git; no heuristics, no LLM. When the scope of a change is unclear, Verifika runs everything or fails loudly. It never quietly skips a check, and in CI it runs the full suite unless you explicitly ask for a selective run.
+- **Trustworthy results.** Timeouts, fail-fast, correct exit codes and signal handling. A check only passes once its whole process tree has exited. Tested on Linux, macOS and Windows.
+- **Built for humans and coding agents alike.** Live progress on a terminal, one line in agent sessions, JSON for scripts. It ships an [agent skill](skills/verifika/SKILL.md) for Claude Code, Codex, OpenCode and others.
+- **Small.** One JSON file, one runtime dependency, no daemon, no cache to invalidate.
+
+_Verifika_ is Maltese for "verification". The command is `vfk`, short for `verifika`; both are installed and identical.
+
+## Get started
+
+Requires Node.js 22.13 or newer.
+
+### With a coding agent
+
+Paste this prompt into Claude Code, Codex, OpenCode or another coding agent, from your repository root. It installs Verifika, writes and validates a config for your project, and reports what it found.
+
+```text
+Set up Verifika (https://github.com/alexportelli12/verifika) in this repository.
+
+1. Check that Node.js is 22.13 or newer, and install the project's dependencies if
+   they are missing. Install Verifika as a dev dependency with this repository's
+   package manager (npm install --save-dev verifika, or the pnpm/yarn equivalent).
+   It provides the `vfk` command.
+2. Run `npx vfk init` to create verifika.config.json, then refine it by reading
+   package.json, the CI workflows and the tool configs:
+   - One check per quality gate the project actually has (such as format, lint,
+     typecheck, unit tests, build). Do not invent checks for tools it does not use,
+     or add a check that another one already fully covers. Every command must be
+     non-interactive and exit on its own: no watch mode, no prompts, no dev servers.
+   - Give each check `paths` globs for the files that can affect it, so local runs
+     select only what a change needs. If unsure, leave `paths` out: the check then
+     runs on every change.
+   - Add `dependsOn` where one check needs another's output (for example e2e after build).
+   - Keep concurrency at 1 unless the checks clearly share no build outputs.
+   - If package.json has no "verify" script, add "verify": "vfk --all".
+   Reference: https://github.com/alexportelli12/verifika/blob/main/docs/configuration.md
+3. Validate the config:
+   - Run `npx vfk --all`. If a check fails, decide whether the config is wrong (fix it)
+     or the project already fails that check (report it; do not fix it).
+   - Run `npx vfk plan`. Until this setup is committed, the changed package.json and
+     lockfile select every check; that is expected. Explain which checks a typical
+     source edit and a documentation-only edit would select once it is committed.
+4. Install the agent skill: copy node_modules/verifika/skills/verifika into this
+   agent's skills directory (see
+   https://github.com/alexportelli12/verifika/blob/main/docs/agents.md).
+
+Do not change source code or existing scripts to make checks pass, and do not commit.
+Finish with: the checks you configured and why, the --all result, the expected
+selection for those two edits, and any existing failures you found.
+```
+
+Review the config it writes before committing it: the commands in it run on every verification.
+
+### By hand
+
+```sh
+npm install --save-dev verifika
+npx vfk init     # creates verifika.config.json from your package.json scripts
+```
+
+`init` only maps conventional script names (`lint`, `test`, `build`, ...) and leaves every check unfiltered, so open the file and give each check `paths`:
+
+```json
+{
+  "$schema": "./node_modules/verifika/schemas/verifika.schema.json",
+  "version": 1,
+  "changes": {
+    "invalidateAll": ["package.json", "package-lock.json", "tsconfig*.json"]
+  },
+  "checks": {
+    "format": { "command": "npm run format:check" },
+    "lint": { "command": "npm run lint", "paths": ["src/**/*.{ts,html}"] },
+    "typecheck": { "command": "npm run typecheck", "paths": ["src/**/*.ts"] },
+    "test": { "command": "npm test", "paths": ["src/**", "test/**"] },
+    "build": { "command": "npm run build", "paths": ["src/**"], "dependsOn": ["typecheck"] }
+  }
+}
+```
+
+If your repository checks the formatting of every file (for example `prettier --check .`), format the new `verifika.config.json` too. Then:
+
+```sh
+npx vfk plan     # which checks would run for your changes, and why
+npx vfk          # run them
+npx vfk --all    # run everything (do this before you push)
+```
+
+Add a script so everyone runs the same full gate:
+
+```json
+{ "scripts": { "verify": "vfk --all" } }
+```
+
+Run logs go to `.verifika/`, which ignores itself in git, so you do not need to edit `.gitignore`. To install globally instead, run `npm install --global verifika`.
+
+## How checks are selected
+
+| Situation                                 | What runs                                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `vfk` locally                             | Checks whose `paths` match files changed since `changes.base` (default `HEAD`: your uncommitted and untracked work) |
+| `vfk` in CI (`CI` or a known CI variable) | Everything; only `--changed`/`--changed-since` on the command line can narrow it                                    |
+| `vfk --all`                               | Everything                                                                                                          |
+| `vfk --check lint`                        | `lint` and its dependencies                                                                                         |
+| `vfk --changed-since origin/main`         | Checks matching files changed since `merge-base(origin/main, HEAD)`, plus uncommitted and untracked files           |
+| A changed file matches `invalidateAll`    | Everything                                                                                                          |
+| Git unavailable, no commits, unknown base | Everything, with the reason printed (or an error, when you asked for `--changed`/`--changed-since` explicitly)      |
+
+A check without `paths` runs whenever any file changed; `"always": true` runs it even when nothing changed. Selecting a check also selects its `dependsOn` checks. `vfk plan` shows every decision.
+
+## Output modes
+
+The default is `human` on an interactive terminal and `agent` otherwise. Override with `--mode` or `VERIFIKA_MODE`.
+
+| Mode    | Success                       | Failure                                             |
+| ------- | ----------------------------- | --------------------------------------------------- |
+| `human` | Live progress, summary        | Failing checks, previews, logs hint                 |
+| `agent` | One line: `PASS 4/4 (4.3s) …` | One line per problem, bounded preview, logs command |
+| `json`  | Versioned result document     | Same document, `"status": "failed"`                 |
+| `quiet` | Nothing                       | One line on stderr                                  |
+
+Exit codes: `0` passed (or nothing to verify), `1` verification failed, `2` usage or configuration error, `128+n` interrupted by a signal (`130` SIGINT, `143` SIGTERM).
+
+## Logs
+
+Every run stores each check's combined stdout/stderr under `.verifika/runs/<run-id>/`. The directory ignores itself in git, and only the last 10 runs are kept (`defaults.keepRuns`).
+
+```sh
+vfk logs                  # latest run: statuses and log paths
+vfk logs typecheck        # full log of one check
+vfk logs --failed         # logs of every failed check
+vfk logs test --tail 50   # last 50 lines
+```
+
+Logs contain whatever your commands print, which can include secrets. They never leave your machine; keep `.verifika/` out of anything you publish.
+
+## Agent integration
+
+Verifika ships an [agent skill](skills/verifika/SKILL.md) that teaches coding agents when to run selective versus full verification, how to read results, and how not to claim success too early. See [docs/agents.md](docs/agents.md) to install it for Claude Code, Codex or OpenCode.
+
+## Documentation
+
+- [Configuration reference](docs/configuration.md)
+- [CLI reference](docs/cli.md)
+- [Agent integration](docs/agents.md)
+- [Architecture](docs/architecture.md)
+- [Validation and benchmarks](docs/benchmarks.md)
+- [Example configs](examples/)
+- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md)
+
+## Trust model
+
+`verifika.config.json` is trusted code: its commands run through your shell with your permissions, exactly like `package.json` scripts. Verifika never puts file names, git refs or other external input into those commands. Review config changes as carefully as script changes.
+
+## License
+
+[MIT](LICENSE)

package/dist/ci.js

@@ -0,0 +1,34 @@
+/** Variables set by common CI providers. */
+export const CI_VARIABLES = [
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "BUILDKITE",
+    "CIRCLECI",
+    "TRAVIS",
+    "JENKINS_URL",
+    "TF_BUILD",
+    "TEAMCITY_VERSION",
+    "BITBUCKET_BUILD_NUMBER",
+    "CODEBUILD_BUILD_ID",
+    "DRONE",
+    "APPVEYOR",
+    "SEMAPHORE",
+];
+/**
+ * Decides whether this is a CI run, where verification defaults to the full
+ * suite. Environment variables can only turn CI mode on: a truthy `CI` or any
+ * provider variable means CI, and nothing (including `CI=false`, which some
+ * build setups export for unrelated reasons) can switch a detected provider
+ * off. Selective runs in CI require an explicit `--changed` or `--changed-since`.
+ */
+export function detectCi(env) {
+    if (isEnabled(env.CI))
+        return { ci: true, source: "CI" };
+    const provider = CI_VARIABLES.find((name) => isEnabled(env[name]));
+    return provider ? { ci: true, source: provider } : { ci: false, source: "none" };
+}
+function isEnabled(value) {
+    if (value === undefined)
+        return false;
+    return !["", "0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}

package/dist/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { ExitCode } from "./errors.js";
+import { main } from "./main.js";
+const write = (stream) => (text) => {
+    stream.write(text);
+};
+// A closed pipe (e.g. `verifika logs lint | head`) is not an error worth a stack trace.
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on("error", (error) => {
+        if (error.code !== "EPIPE")
+            throw error;
+    });
+}
+main(process.argv.slice(2), {
+    cwd: process.cwd(),
+    env: process.env,
+    isTTY: Boolean(process.stdout.isTTY),
+    out: write(process.stdout),
+    err: write(process.stderr),
+}).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`verifika: internal error: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exitCode = ExitCode.Internal;
+});

package/dist/config.js

@@ -0,0 +1,294 @@
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { VerifikaError } from "./errors.js";
+export const CONFIG_FILE = "verifika.config.json";
+export const CHECK_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const DEFAULT_TIMEOUT_MS = 600_000;
+/** Largest delay setTimeout accepts (about 24.8 days); larger values would fire immediately. */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+/** Device names Windows reserves in every directory; they cannot be log file names. */
+const RESERVED_NAMES = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/i;
+const DEFAULT_KEEP_RUNS = 10;
+/**
+ * Checks run one at a time unless the config (or `-j`) opts into parallelism:
+ * only the project knows which of its scripts share build outputs, and running
+ * those concurrently produces real but misleading failures.
+ */
+export const DEFAULT_CONCURRENCY = 1;
+/** Walks up from `cwd` to find verifika.config.json, or uses the explicit path. */
+export function findConfigFile(cwd, explicit) {
+    if (explicit) {
+        const file = path.resolve(cwd, explicit);
+        if (!isFile(file))
+            throw new VerifikaError(`config file not found: ${explicit}`);
+        return file;
+    }
+    let directory = path.resolve(cwd);
+    for (;;) {
+        const candidate = path.join(directory, CONFIG_FILE);
+        if (isFile(candidate))
+            return candidate;
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            throw new VerifikaError(`no ${CONFIG_FILE} found in ${cwd} or any parent directory`, "Create one with: vfk init");
+        }
+        directory = parent;
+    }
+}
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function loadConfig(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw new VerifikaError(`cannot read ${file}: ${error.message}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text.replace(/^\uFEFF/, ""));
+    }
+    catch (error) {
+        throw new VerifikaError(`${path.basename(file)} is not valid JSON: ${error.message}`);
+    }
+    return parseConfig(raw, file);
+}
+/** Validates raw JSON and applies defaults. Reports every problem at once. */
+export function parseConfig(raw, file) {
+    const errors = [];
+    const v = new Validator(errors);
+    if (!v.object(raw, "config"))
+        throw configError(file, errors);
+    v.keys(raw, "config", ["$schema", "version", "defaults", "changes", "checks"]);
+    v.string(raw.$schema, "$schema");
+    if (raw.version !== 1) {
+        errors.push(raw.version === undefined
+            ? "version: required; set it to 1"
+            : `version: unsupported value ${JSON.stringify(raw.version)}; this release supports 1`);
+    }
+    const defaults = raw.defaults ?? {};
+    let concurrency = DEFAULT_CONCURRENCY;
+    let timeoutMs = DEFAULT_TIMEOUT_MS;
+    let failFast = false;
+    let keepRuns = DEFAULT_KEEP_RUNS;
+    if (v.object(defaults, "defaults")) {
+        v.keys(defaults, "defaults", ["concurrency", "timeoutMs", "failFast", "keepRuns"]);
+        concurrency = v.integer(defaults.concurrency, "defaults.concurrency", 1, 64) ?? concurrency;
+        timeoutMs = v.integer(defaults.timeoutMs, "defaults.timeoutMs", 1, MAX_TIMEOUT_MS) ?? timeoutMs;
+        failFast = v.boolean(defaults.failFast, "defaults.failFast") ?? failFast;
+        keepRuns = v.integer(defaults.keepRuns, "defaults.keepRuns", 1, 1000) ?? keepRuns;
+    }
+    const changes = raw.changes ?? {};
+    let base = "HEAD";
+    let invalidateAll = [];
+    if (v.object(changes, "changes")) {
+        v.keys(changes, "changes", ["base", "invalidateAll"]);
+        base = v.string(changes.base, "changes.base") ?? base;
+        invalidateAll = v.globs(changes.invalidateAll, "changes.invalidateAll", true) ?? [];
+    }
+    // A config edit can change what every check means, so it always invalidates everything.
+    if (!invalidateAll.includes(CONFIG_FILE))
+        invalidateAll = [...invalidateAll, CONFIG_FILE];
+    const checks = [];
+    if (raw.checks === undefined) {
+        errors.push("checks: required; declare at least one check");
+    }
+    else if (v.object(raw.checks, "checks")) {
+        const entries = Object.entries(raw.checks);
+        if (entries.length === 0)
+            errors.push("checks: declare at least one check");
+        for (const [name, value] of entries) {
+            const at = `checks.${name}`;
+            if (!CHECK_NAME_PATTERN.test(name)) {
+                errors.push(`${at}: invalid name; use letters, digits, ".", "_" or "-", starting with a letter or digit`);
+            }
+            if (RESERVED_NAMES.test(name)) {
+                errors.push(`${at}: "${name}" is a reserved device name on Windows; choose another name`);
+            }
+            const clash = entries.find(([other]) => other !== name && other.toLowerCase() === name.toLowerCase());
+            if (clash && clash[0] < name) {
+                errors.push(`${at}: differs from "${clash[0]}" only by case; log files would collide`);
+            }
+            if (!v.object(value, at))
+                continue;
+            v.keys(value, at, ["command", "paths", "exclude", "always", "dependsOn", "timeoutMs"]);
+            const command = v.string(value.command, `${at}.command`, true);
+            const paths = v.globs(value.paths, `${at}.paths`, false);
+            const exclude = v.globs(value.exclude, `${at}.exclude`, true) ?? [];
+            const always = v.boolean(value.always, `${at}.always`) ?? false;
+            const dependsOn = v.stringArray(value.dependsOn, `${at}.dependsOn`) ?? [];
+            const checkTimeout = v.integer(value.timeoutMs, `${at}.timeoutMs`, 1, MAX_TIMEOUT_MS);
+            if (always && paths) {
+                errors.push(`${at}: "always" and "paths" cannot be combined; an always-run check ignores paths`);
+            }
+            if (always && exclude.length > 0) {
+                errors.push(`${at}: "always" and "exclude" cannot be combined`);
+            }
+            checks.push({
+                name,
+                command: command ?? "",
+                paths,
+                exclude,
+                always,
+                dependsOn,
+                timeoutMs: checkTimeout ?? timeoutMs,
+            });
+        }
+        validateDependencies(checks, errors);
+    }
+    if (errors.length > 0)
+        throw configError(file, errors);
+    return {
+        file,
+        root: path.dirname(file),
+        concurrency,
+        timeoutMs,
+        failFast,
+        keepRuns,
+        base,
+        invalidateAll,
+        checks,
+    };
+}
+function validateDependencies(checks, errors) {
+    const byName = new Map(checks.map((check) => [check.name, check]));
+    for (const check of checks) {
+        const seen = new Set();
+        for (const dependency of check.dependsOn) {
+            if (dependency === check.name) {
+                errors.push(`checks.${check.name}.dependsOn: a check cannot depend on itself`);
+            }
+            else if (!byName.has(dependency)) {
+                errors.push(`checks.${check.name}.dependsOn: unknown check "${dependency}"`);
+            }
+            else if (seen.has(dependency)) {
+                errors.push(`checks.${check.name}.dependsOn: "${dependency}" is listed twice`);
+            }
+            seen.add(dependency);
+        }
+    }
+    const cycle = findCycle(checks, byName);
+    if (cycle)
+        errors.push(`checks: dependency cycle ${cycle.join(" -> ")}`);
+}
+function findCycle(checks, byName) {
+    const state = new Map();
+    const stack = [];
+    const visit = (name) => {
+        if (state.get(name) === "done")
+            return null;
+        if (state.get(name) === "visiting")
+            return [...stack.slice(stack.indexOf(name)), name];
+        state.set(name, "visiting");
+        stack.push(name);
+        for (const dependency of byName.get(name)?.dependsOn ?? []) {
+            if (dependency === name || !byName.has(dependency))
+                continue;
+            const cycle = visit(dependency);
+            if (cycle)
+                return cycle;
+        }
+        stack.pop();
+        state.set(name, "done");
+        return null;
+    };
+    for (const check of checks) {
+        const cycle = visit(check.name);
+        if (cycle)
+            return cycle;
+    }
+    return null;
+}
+function configError(file, errors) {
+    return new VerifikaError(`invalid ${path.basename(file)}:\n${errors.map((error) => `  - ${error}`).join("\n")}`);
+}
+/** Small collecting validator; each method returns `undefined` for absent or invalid values. */
+class Validator {
+    errors;
+    constructor(errors) {
+        this.errors = errors;
+    }
+    object(value, at) {
+        if (typeof value === "object" && value !== null && !Array.isArray(value))
+            return true;
+        this.errors.push(`${at}: expected an object`);
+        return false;
+    }
+    keys(value, at, allowed) {
+        for (const key of Object.keys(value)) {
+            if (!allowed.includes(key)) {
+                this.errors.push(`${at}: unknown property "${key}" (allowed: ${allowed.join(", ")})`);
+            }
+        }
+    }
+    string(value, at, required = false) {
+        if (value === undefined) {
+            if (required)
+                this.errors.push(`${at}: required`);
+            return undefined;
+        }
+        if (typeof value === "string" && value.trim() !== "")
+            return value;
+        this.errors.push(`${at}: expected a non-empty string`);
+        return undefined;
+    }
+    boolean(value, at) {
+        if (value === undefined || typeof value === "boolean")
+            return value;
+        this.errors.push(`${at}: expected true or false`);
+        return undefined;
+    }
+    integer(value, at, min, max) {
+        if (value === undefined)
+            return undefined;
+        if (typeof value === "number" &&
+            Number.isInteger(value) &&
+            value >= min &&
+            (max === undefined || value <= max)) {
+            return value;
+        }
+        const range = max === undefined ? `>= ${min}` : `between ${min} and ${max}`;
+        this.errors.push(`${at}: expected an integer ${range}`);
+        return undefined;
+    }
+    stringArray(value, at) {
+        if (value === undefined)
+            return undefined;
+        if (Array.isArray(value) &&
+            value.every((item) => typeof item === "string" && item.trim() !== "")) {
+            return value;
+        }
+        this.errors.push(`${at}: expected an array of non-empty strings`);
+        return undefined;
+    }
+    /** Glob lists must be portable: forward slashes, relative to the config directory. */
+    globs(value, at, allowEmpty) {
+        const list = this.stringArray(value, at);
+        if (list === undefined)
+            return undefined;
+        if (list.length === 0 && !allowEmpty) {
+            this.errors.push(`${at}: must not be empty; omit it to match every file, or use "always": true`);
+            return undefined;
+        }
+        const normalized = [];
+        for (const pattern of list) {
+            if (pattern.includes("\\")) {
+                this.errors.push(`${at}: "${pattern}" contains a backslash; use forward slashes on every platform`);
+            }
+            else if (pattern.startsWith("/") || /^[A-Za-z]:/.test(pattern)) {
+                this.errors.push(`${at}: "${pattern}" is absolute; patterns are relative to the config directory`);
+            }
+            else {
+                normalized.push(pattern.replace(/^(\.\/)+/, ""));
+            }
+        }
+        return normalized;
+    }
+}

package/dist/errors.js

@@ -0,0 +1,19 @@
+/** Exit codes are part of the public CLI contract; see docs/cli.md. */
+export const ExitCode = {
+    Passed: 0,
+    Failed: 1,
+    Usage: 2,
+    Internal: 70,
+};
+/**
+ * A problem with how Verifika was invoked or configured. These never represent
+ * check results, so they always exit with the usage code rather than a pass.
+ */
+export class VerifikaError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = "VerifikaError";
+        this.hint = hint;
+    }
+}

package/dist/format.js

@@ -0,0 +1,10 @@
+/** Compact duration: `0.4s`, `12s`, `3m05s`. */
+export function formatSeconds(ms) {
+    const seconds = ms / 1000;
+    if (seconds < 10)
+        return `${seconds.toFixed(1)}s`;
+    if (seconds < 120)
+        return `${Math.round(seconds)}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m${String(Math.floor(seconds % 60)).padStart(2, "0")}s`;
+}