verify-repo

Test the state of your repository. Make your coding agents prove they're done.

NOTE: This package is a rough prototype. Expect bugs.

Define checks

Create files that match **/*?.verify.{js,ts}. Each file has access to the shared verify instance:

// repo.verify.ts
import { verify } from "verify-repo";

verify.file("package.json").exists();
verify.dir("dist").exists();
verify.script("dev").runs();
verify.git.isClean();
verify.prettier("src/**/*.ts").isFormatted();

Built-in checks

• command("npm run build").runs() or .outputs(/ready/)
• script("dev").runs()
• file("README.md").exists() / .contains("Install")
• dir("dist").exists() / dir("node_modules").not.exists()
• prettier.isFormatted() or prettier("src/**/*.ts").isFormatted()
• git.isClean(), git.branch("main").isCurrent()
• ts.noErrors(), ts.buildsProject("tsconfig.build.json")
• eslint.passes({ maxWarnings: 0 })
• bun.test.passes({ args: ["--filter", "unit"] })
• docker.builds("Dockerfile.prod", { tag: "my-app:prod" })

Run

You can run the verifications using the CLI:

npx verify-repo

Or programmatically:

import { run } from "verify-repo";

await run({
  root: process.cwd(), // default
  // pattern, ignore, plugins, etc. are optional overrides
});

run discovers every *.verify.ts/*.verify.js file, loads them, and executes all checks in parallel. A non-zero exit (or thrown RepoVerificationFailedError) indicates a failure.

Explore available checks

To see a list of all available checks and their documentation, run:

npx verify-repo --docs

Configuration

You can configure the runtime using verify.config.ts in the root of your project:

// verify.config.ts
import { configure } from "verify-repo";

configure({
  root: process.cwd(),
  // Add custom plugins or override defaults here
  concurrency: 5,
});

Authoring plugins

You can extend verify-repo with custom checks by creating a plugin.

• name / description: Metadata for the plugin.
• docs: Documentation for the checks provided by the plugin (shown in --docs).
• api: A function that returns the API extensions. It receives a VerificationContext containing:
  • dir: The current working directory for the check.
  • register(description, handler): Register a check. The handler must return { pass: boolean, message: string }.
  • entry: A helper to create a chainable API (e.g. verify.myPlugin.check(...)).

Here is an example of a custom plugin that checks for content in the README.md file:

export const readme = () =>
  plugin({
    name: "README checker",
    description: "Checks for contents in the README file.",
    docs: [
      {
        signature: 'verify.readme.contains("content")',
        description: "Checks that the README file contains the specified content.",
      },
    ],
    api: () => ({
      readme: ({ dir, entry, register }) =>
        entry({
          contains: (content: string) => {
            register(`README contains ${content}`, async () => {
              const file = await readFile(path.join(dir, "README.md"));
              if (file.includes(content)) {
                return { pass: true, message: `README contains "${content}"` };
              } else {
                return { pass: false, message: `README does not contain "${content}"` };
              }
            });
          },
        }),
    }),
  });

To use your custom plugin, add it to verify.config.ts:

import { configure } from "verify-repo";
import { readme } from "./plugins/readme";

configure({
  plugins: [readme()],
});

Now you can use it in your verification files:

// repo.verify.ts
verify.readme.contains("Getting Started");