|
| 1 | +# Copilot Coding Agent Instructions |
| 2 | + |
| 3 | +Trust these instructions. Only search the codebase if information here is incomplete or found to be in error. |
| 4 | + |
| 5 | +## Repository Overview |
| 6 | + |
| 7 | +**dependency-review-action** is a GitHub Action (TypeScript/Node.js 20) that scans pull requests for dependency changes, raising errors for vulnerabilities or invalid licenses. It queries the GitHub Dependency Review API, evaluates changes against configured rules, and produces job summaries and PR comments. The action entry point is `dist/index.js` (bundled via `ncc`). The repo is small (~15 source files, ~15 test files). |
| 8 | + |
| 9 | +## Build & Validation Commands |
| 10 | + |
| 11 | +For CI-parity installs and local validation, run `npm ci --ignore-scripts` before other commands. This is the install step used in CI; release workflows may follow different install instructions (see CONTRIBUTING). |
| 12 | + |
| 13 | +| Task | Command | Notes | |
| 14 | +| ------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | |
| 15 | +| Install | `npm ci --ignore-scripts` | ~45s. Use `--ignore-scripts` for CI-parity installs; release workflows may use `npm i` per CONTRIBUTING. | |
| 16 | +| Build | `npm run build` | Compiles `src/*.ts` → `lib/*.js` via `tsc -p tsconfig.build.json`. ~5s. | |
| 17 | +| Test | `npm test` | Runs Jest. ~8s. All tests should pass. | |
| 18 | +| Lint | `npm run lint` | ESLint on `src/**/*.ts`. Ignore the TS version warning—it still passes. | |
| 19 | +| Format check | `npm run format-check` | Prettier check on `**/*.ts`. | |
| 20 | +| Format fix | `npm run format` | Auto-fix formatting with Prettier. | |
| 21 | +| Package | `npm run package` | Bundles the action entrypoint (`package.json#main`) → `dist/index.js` via `ncc`. ~7s. Do NOT include `dist/` changes in non-release PRs. | |
| 22 | +| All | `npm run all` | Runs: build → format → lint → package → test (in that order). | |
| 23 | + |
| 24 | +### Validation Sequence After Making Changes |
| 25 | + |
| 26 | +Always run these commands in this order to validate changes: |
| 27 | + |
| 28 | +```sh |
| 29 | +npm run build |
| 30 | +npm run format-check |
| 31 | +npm run lint |
| 32 | +npm test |
| 33 | +``` |
| 34 | + |
| 35 | +If format-check fails, run `npm run format` to auto-fix, then re-check. |
| 36 | + |
| 37 | +### CI Checks (`.github/workflows/ci.yml`) |
| 38 | + |
| 39 | +CI runs on PRs (excluding `**.md` changes) with Node 20: |
| 40 | + |
| 41 | +1. **test** job: `npm ci --ignore-scripts` → `npm test` |
| 42 | +2. **lint** job: `npm ci --ignore-scripts` → `npm run format-check` → `npm run lint` |
| 43 | + |
| 44 | +Additional workflows: `dependency-review.yml` (self-test), `codeql.yml` (CodeQL analysis), `stale.yaml` (stale issues). |
| 45 | + |
| 46 | +## Project Layout |
| 47 | + |
| 48 | +``` |
| 49 | +src/ # TypeScript source (edit these files) |
| 50 | + main.ts # Entry point — orchestrates the action (532 lines) |
| 51 | + schemas.ts # Zod schemas & TypeScript types for all data structures |
| 52 | + config.ts # Reads action inputs + external YAML config |
| 53 | + dependency-graph.ts # GitHub API client for dependency diff |
| 54 | + filter.ts # Filters changes by severity, scope, allowed advisories |
| 55 | + licenses.ts # License validation against allow/deny lists |
| 56 | + deny.ts # Package/group deny-listing logic |
| 57 | + purl.ts # Package URL (PURL) parser |
| 58 | + spdx.ts # SPDX license expression handling |
| 59 | + scorecard.ts # OpenSSF Scorecard integration |
| 60 | + summary.ts # Summary/report generation (736 lines, largest module) |
| 61 | + comment-pr.ts # Posts/updates PR comments with results |
| 62 | + git-refs.ts # Resolves base/head git refs from event payload |
| 63 | + utils.ts # Shared utilities (Octokit client, grouping helpers) |
| 64 | +lib/ # Compiled JS output (from `npm run build`). Gitignored. |
| 65 | +dist/ # Bundled action (from `npm run package`). Committed but do NOT include changes in normal PRs - only pull requests which are creating new releases should have these files changed. |
| 66 | +__tests__/ # Jest test files (*.test.ts) |
| 67 | + test-helpers.ts # setInput()/clearInputs() helpers for test env vars |
| 68 | + fixtures/ # YAML config samples and factory helpers |
| 69 | + create-test-change.ts # Factory for mock Change objects |
| 70 | + create-test-vulnerability.ts # Factory for mock vulnerability objects |
| 71 | +scripts/ # Dev/debug utilities (scan_pr for manual testing, create_summary.ts for preview) |
| 72 | +action.yml # Action metadata — inputs, outputs, and `runs.main: dist/index.js` |
| 73 | +``` |
| 74 | + |
| 75 | +### Configuration Files |
| 76 | + |
| 77 | +| File | Purpose | |
| 78 | +| --------------------- | ---------------------------------------------------------------------------- | |
| 79 | +| `tsconfig.json` | Base TypeScript config (ES6 target, CommonJS, strict mode) | |
| 80 | +| `tsconfig.build.json` | Build config — extends base, includes only `src/`, outputs to `lib/` | |
| 81 | +| `jest.config.js` | Jest config — uses `ts-jest`, matches `**/*.test.ts` | |
| 82 | +| `.eslintrc.json` | ESLint — `plugin:github/recommended`, strict TS rules, no semicolons | |
| 83 | +| `.prettierrc.json` | Prettier — no semis, single quotes, no bracket spacing, trailing comma: none | |
| 84 | +| `.prettierignore` | Ignores `dist/`, `lib/`, `node_modules/` | |
| 85 | + |
| 86 | +### Key TypeScript/Style Rules |
| 87 | + |
| 88 | +- No semicolons (enforced by ESLint and Prettier) |
| 89 | +- Single quotes, no trailing commas |
| 90 | +- `@typescript-eslint/no-explicit-any: error` — never use `any` |
| 91 | +- `@typescript-eslint/explicit-function-return-type: error` — all functions need return types (expressions exempt) |
| 92 | +- Unused function parameters/args must be prefixed with `_` (e.g. `_unused`); unused variables should be removed |
| 93 | +- Use Zod schemas (in `src/schemas.ts`) for all data validation and type definitions |
| 94 | +- Config option defaults belong in Zod schemas, NOT in `action.yml` |
| 95 | + |
| 96 | +### Testing Patterns |
| 97 | + |
| 98 | +- Tests use Jest with `ts-jest` transform — no build step needed before running tests |
| 99 | +- Use `__tests__/test-helpers.ts` `setInput(name, value)` to mock action inputs (sets `INPUT_*` env vars) |
| 100 | +- Use `__tests__/fixtures/create-test-change.ts` and `create-test-vulnerability.ts` for test data factories |
| 101 | +- Test files follow `__tests__/<module>.test.ts` naming convention |
| 102 | +- Tests run directly against TypeScript source (not compiled JS) |
| 103 | + |
| 104 | +### Important Notes |
| 105 | + |
| 106 | +- The action runs on `node20` (declared in `action.yml`) |
| 107 | +- Source imports often use relative `../src/` paths (e.g. `import {readConfig} from '../src/config'`) |
| 108 | +- Adding a new action input requires changes in: `action.yml` (input definition), `src/schemas.ts` (Zod schema with default), `src/config.ts` (reading the input), and relevant source/test files |
| 109 | +- `dist/index.js` is committed for GitHub Actions but PR contributors should NOT include `dist/` changes — maintainers handle rebuilding |
| 110 | +- The `lib/` directory is gitignored |
| 111 | +- Scorecard tests make real HTTP calls to `api.securityscorecards.dev` and `deps.dev` |
0 commit comments