Development

Development

How to contribute to DataShield and pass the gates CI enforces.

Local gates

Run the same checks CI does, in this order, before proposing changes:

npm run lint -- --max-warnings 0   # zero warnings allowed
npx tsc --noEmit                   # type check
npx prisma validate                # when prisma/ changes
npm run build                      # build without real secrets
npm test                           # vitest unit tests
npm run test:integration           # vitest integration tests (needs the DB)
npm run test:e2e                   # playwright end-to-end

Unit tests sit next to the code as *.test.ts; integration tests that need a real database use *.itest.ts and run under a separate Vitest config.

Respect the existing Prettier config; do not reformat unrelated lines.

Conventions (from AGENTS.md)

• Scope discipline: fix only what is asked, no adjacent refactors, no premature abstractions, no feature flags or compat shims for removed code.
• Comments: only when the why is non-obvious. No multi-line docstrings.
• Error handling: validate only at system boundaries (user input, external APIs); trust framework guarantees.
• ASCII only in source and docs. No em dash, no accented characters. The compliance workflow blocks non-ASCII.
• Secrets: never hardcode tokens/keys; never log passwords, tokens, or PII.
• Dependencies: do not add one without clear need; new deps must not introduce high/critical advisories (npm audit --audit-level=high blocks CI).

Branches

Work lands on develop and reaches main by pull request. Both branches run the full CI workflow and both are protected by the aggregate ci check.

Commits and PRs

Follow Conventional Commits:

• Subject 50 characters or fewer.
• No Co-Authored-By lines.
• Body only when the why is not obvious from the diff.
• The PR title is the gate CI validates (squash merge uses it), so it must be a valid Conventional Commit.

CI workflows

Workflow	Trigger	Jobs
CI (ci.yml)	push + PR to main and develop	quality (lint, types, schema), test, build, aggregated ci gate
Security (security.yml)	push + PR + weekly	npm audit, Gitleaks, TruffleHog, dependency review
Compliance (compliance.yml)	PR to main	PR-title check, added-line content checks, CODEOWNERS check
CodeQL (codeql.yml)	push + PR	static analysis

The ci job is the aggregate status check required by branch protection; it is green only when quality, test, and build all pass.

Git hooks

npm install runs prepare (.githooks/install.sh), wiring local hooks that mirror the CI compliance checks (commit-message validation, added-line content scans). This catches issues before you push.

Project conventions worth knowing

• Node is pinned to 22 (.nvmrc, engines). The make targets select it automatically via nvm, so they work even when your shell's default Node differs; otherwise run nvm use.
• The Prisma client regenerates on npm install (postinstall).
• npm run dev only warns about pending migrations; it never applies them. Run npm run db:migrate yourself after pulling a new migration. The Docker path (docker compose up) applies migrations and seeds on every start.

See Getting Started for environment setup and Configuration for variables.