Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
90 lines (62 loc) · 2.39 KB

CONTRIBUTING.md

File metadata and controls

90 lines (62 loc) · 2.39 KB

Contributing

My Reps is intended to be small enough to understand in one sitting. The main rule is: keep behavior in the shared core, and keep CLI, API, and UI code as adapters over that core.

Setup

Use a current Node.js 22 runtime.

npm install
npm test
npm run build

Run the local Vite app:

npm run dev

Run the Cloudflare Pages-style preview:

npm run pages:preview

Run the CLI during development:

npm run georep -- lookup --address "530 S King St, Honolulu, HI 96813" --mock
npm run georep -- source-status
npm run georep -- schema

Project Shape

  • src/core: validation, envelope construction, source facades, schema, and source status.
  • src/cli: terminal adapter over src/core.
  • src/api: HTTP adapter over src/core.
  • functions/api: Cloudflare Pages Function entrypoint.
  • src/web: React UI that calls /api/lookup.
  • tests/e2e: browser checks for the public demo path.
  • scripts: smoke checks and deployment helpers.

Before Opening A PR

Run:

npm test
npm run build
npm audit --omit=dev

If your change touches the browser flow, also run:

npm run test:e2e

Playwright may need system browser dependencies:

npx playwright install --with-deps chromium

Adding Or Changing Behavior

Prefer this sequence:

  1. Add or update a focused core test.
  2. Implement the core behavior.
  3. Update CLI/API/UI adapter tests only when their visible contract changes.
  4. Update docs if the command, envelope, runtime mode, or privacy behavior changes.

Do not add provider-specific logic to the UI or API adapter. Live data providers should implement the shared source interface and return the shared canonical representative model.

Privacy Boundary

The app may receive an address in order to do a lookup, but it should not persist exact addresses or exact coordinates.

Tests should avoid asserting on raw private inputs in output. Error envelopes should include query.type, source, count, latency, and sanitized error codes, not submitted addresses or upstream response bodies.

Good First Changes

  • Add another validation edge case in src/core/validation.test.ts.
  • Improve wording in README.md or docs/testing.md.
  • Add a new synthetic fixture field and update rendering tests.
  • Add a focused test for a source failure mode.
  • Add GitHub Actions for npm test, npm run build, and npm audit --omit=dev.