Contributing

Thanks for your interest! This repo is a deterministic website compiler (compiler/) plus a hosted service layer (packages/). The benchmarks and fixtures double as the regression suite.

Setup

npm ci                           # installs the locked workspace graph
npx playwright install chromium  # for capture / browser-gated tests

Develop

Service layer lives in packages/* (TypeScript, run via tsx, no build step).
- npm run typecheck — type-checks every workspace.
- npm test — runs every workspace's tests (node:test). Tests gate themselves: browser tests skip without Chromium; Postgres tests use TEST_DATABASE_URL or a throwaway local Postgres (root only).
- Start locally: docker compose up -d then npm run dev:api / npm run dev:worker (see docs/SERVICE.md).
Compiler lives in compiler/. See the root README.md for the architecture overview. The service layer depends on it only through compiler/src/index.ts (the library barrel) — do not import compiler internals from packages/*.

Ground rules

Don't change the compiler's clone semantics from the service layer. The service is a wrapper; clone output must stay byte-deterministic (rubric Gate 6). Golden-file tests rely on this.
Every change should keep npm run typecheck and npm test green.
Keep runtime dependencies clean with npm audit --omit=dev --audit-level=moderate.
Database schema changes: edit packages/db/src/schema.ts, then npm run db:generate to produce a migration, and commit it.
Keep new code in the style of the surrounding code (naming, comments, idiom).
Follow docs/RESPONSIBLE_USE.md. Changes that make phishing, impersonation, access-control bypass, or unbounded third-party capture easier are not acceptable.

Database migrations

npm run db:generate   # after editing the Drizzle schema → writes packages/db/migrations/*
npm run db:migrate    # applies to $DATABASE_URL

Pull requests

Fork / branch off main.
Make your change with tests; keep npm run typecheck and npm test green.
Open a PR and fill in the PR template. CI (typecheck + the full suite, with Postgres + Chromium) must pass.
If your change touches the deterministic compiler's clone output, say so and include benchmark results (npm run bench).

By participating you agree to abide by our Code of Conduct. Support expectations are documented in SUPPORT.md.

Reporting bugs & security issues

Bugs / features: open an issue using the templates.
Security vulnerabilities: do not open a public issue — follow SECURITY.md (private GitHub advisory).

2.8 KiB Raw Blame History