Dependency auditing and updates

This project includes helper scripts and CI automation to keep runtime and build dependencies current and secure.

Quick checks

• npm run deps:outdated prints available updates with current, wanted, and latest versions.
• npm run deps:audit runs npm audit with --audit-level=high and --omit=dev to fail fast on high-severity production vulnerabilities.
• npm run deps:report runs both checks together via scripts/dependency-report.sh.

Automated coverage

The Dependency audit GitHub Actions workflow runs weekly, on pull requests targeting main, on pushes to staging and main, and on demand via Run workflow. It:

• Installs dependencies with npm ci --ignore-scripts to ensure consistency with the lockfile.
• Runs npm outdated and npm audit --omit=dev --audit-level=high in a single report streamed to the workflow logs and uploaded as the dependency-report.txt artifact.
• Fails the job when actionable high-severity runtime vulnerabilities are detected, ensuring they are surfaced quickly while still allowing reports to be downloaded for triage.

Dependabot policy (noise-controlled)

Dependabot is configured to minimize branch/PR churn while keeping baseline maintenance active:

• Cadence: monthly on Monday morning (America/New_York).
• Open PR caps:
  • npm: 1
  • github-actions: 1
• Grouping: all minor+patch updates are grouped into one PR per ecosystem.
• Major-version updates: suppressed (ignore semver-major) and handled manually in dedicated upgrade passes.
• Rebase behavior: disabled to reduce notification/commit churn on already-open Dependabot PRs.

Recommended workflow

1. Run npm run deps:report before releases or infrastructure upgrades to surface dependency drift early.
2. When upgrades are needed, prefer bumping the primary version pins in dependencies/devDependencies and then remove matching entries from resolutions/overrides where safe to reduce maintenance burden.
3. After upgrades, regenerate the lockfile and run the existing test suites (npm test, npm run lint, npm run test:e2e when applicable).
4. Document any pinned resolutions you must keep (for example, due to vendor compatibility) in the PR description.

Handling known vulnerabilities

If a vulnerability cannot be addressed immediately:

1. Capture the current findings for tracking:

   npm audit --omit=dev --audit-level=high --json > audit-findings.json

2. Use npm audit resolve to explicitly acknowledge the advisory and generate or update audit-resolve.json:

   npm audit resolve --omit=dev --audit-level=high

   Select reviewed for advisories you have validated and documented, and commit the resulting audit-resolve.json alongside a short rationale (issue link, upstream PR, or planned upgrade version).
3. Track the follow-up in an issue so the allowlist remains intentional. Remove the audit-resolve.json entry once the dependency is upgraded or the advisory is withdrawn.

Notes on existing pins

• The project currently pins several GraphQL codegen packages and Vite via resolutions and overrides. When upstream compatibility improves, review and remove these pins to simplify future updates.
• The Node engines constraint is defined in package.json. Confirm CI and deployment targets meet these versions before introducing new dependencies that rely on newer Node features.