Skip to content
binpatch

Contributing

Thanks for considering a contribution to binpatch. This page documents how we work, how to set up a dev environment, and what to expect from review.

Project shape

Section titled “Project shape”
binpatch/
├── src/                    # Library source
│   ├── index.ts            # Public API barrel
│   ├── contract.ts         # Shared types + constants
│   ├── events.ts           # ProgressEvent + safeProgress
│   ├── errors.ts           # BinpatchError
│   ├── bspatch.ts          # TRDIFF10 parse + apply
│   ├── discover.ts         # resolveAndApply orchestration
│   ├── patch-cache.ts      # On-disk cache
│   └── sources/
│       ├── oci.ts          # Generic OCI client
│       ├── ghcr.ts         # GHCR source strategy
│       └── github-release.ts  # GitHub Releases source strategy
├── test/                   # Vitest suite
├── action/                 # GitHub Action YAML
├── website/                # Astro/Starlight docs site
├── .craft.yml              # Release config
└── .github/workflows/      # CI, release, publish, pages

Dev setup

Section titled “Dev setup”
Terminal window
git clone https://github.com/BYK/binpatch
cd binpatch
npm install
npm test
npm run build

Node 22.5+ is required (matches the project’s minimum).

Tests

Section titled “Tests”

We use Vitest. The test suite covers:

  • test/bspatch.test.ts — TRDIFF10 parse + apply (the main surface)
  • test/discover.test.ts — resolveAndApply orchestration
  • test/sources.test.ts — OCI / GHCR / GitHub Releases source strategies
  • test/progress.test.ts — progress event formatting helpers

Run a single test file:

Terminal window
npm test -- test/bspatch.test.ts

Run with coverage:

Terminal window
npm run test:coverage

Mutation-verify your fix

Section titled “Mutation-verify your fix”

We treat every fix as a hypothesis to be falsified. Before opening a PR:

  1. Write the fix.
  2. Write a regression test that fails on the bug.
  3. Revert the fix (locally — never push). Confirm the test now fails (“never trust a fix without seeing it fail”).
  4. Restore the fix. Confirm the test passes.
  5. Open the PR. The review will look for this discipline.

Pull request workflow

Section titled “Pull request workflow”
  1. Fork or branch.
  2. Make your change with tests.
  3. Run the full gate locally:
    Terminal window
    npm run typecheck
    npm test
    npm run build
  4. Open the PR against main.
  5. Address review comments. We use the project’s two-reviewer discipline — at least one approval from a maintainer.
  6. A maintainer will merge (squash) once CI is green.

Coding conventions

Section titled “Coding conventions”
  • No barrel exports inside the library. Import from the source module directly: 
    // ✗ Avoid
    import { applyPatchChainInMemory } from "binpatch";
    // (this works, but...)
    // ✓ Prefer in test files
    import { applyPatchChainInMemory } from "../src/bspatch";
    Within the library, internal modules import each other directly (no barrel from index.ts to internal).
  • No native code. No node-gyp, no .node addons, no WASM. Anything that requires native code is out of scope.
  • No third-party runtime deps. The library’s only runtime dep is Node.js itself.
  • applyPatch() always returns the SHA-256 inline. Don’t add a separate verify step.

Security disclosures

Section titled “Security disclosures”

Found a security issue? Email security@withlore.ai or open a private security advisory on GitHub. Do not open a public issue.

Code of conduct

Section titled “Code of conduct”

Be kind. We follow the Contributor Covenant. Maintainers reserve the right to remove comments or close issues that violate the standard.

License

Section titled “License”

By contributing, you agree that your contributions will be licensed under the project’s MIT license.

Next

Section titled “Next”