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

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).

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	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). 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.

See Getting Started for environment setup and Configuration for variables.