Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
235 lines (156 loc) · 9.16 KB

CONTRIBUTING.md

File metadata and controls

235 lines (156 loc) · 9.16 KB
Raw

Contributing to CVE Lite CLI

Thanks for your interest in contributing to CVE Lite CLI.

CVE Lite CLI is a lightweight, developer-focused vulnerability scanner for JavaScript and TypeScript projects. The project is intentionally opinionated: it values fast local workflow, understandable output, practical remediation guidance, and a small dependency footprint.

What kinds of contributions are helpful

Contributions are especially welcome in these areas:

  • lockfile parsing edge cases
  • npm, pnpm, and Yarn compatibility improvements
  • output clarity and readability
  • remediation guidance improvements
  • JSON output quality
  • CI examples and documentation
  • performance improvements
  • tests and reproducible bug cases
  • documentation and onboarding

Before you start

Please open an issue first for:

  • new features
  • larger refactors
  • behavior changes
  • output format changes

This helps keep the project focused and avoids duplicated work.

Small fixes such as typo corrections, tests, and minor docs updates can usually be opened directly as pull requests.

Development principles

Please keep these project principles in mind:

  • local-first workflow
  • small runtime dependency footprint
  • practical developer usability over complexity
  • honest security claims
  • clear output over noisy output
  • action-oriented remediation guidance

Coding standards

CVE Lite CLI is written in TypeScript with strict mode enabled. The project's tsconfig.json is the canonical style baseline; pull requests must pass strict type-check and the existing test suite before review.

Required checks before opening a pull request:

npm run build
npm test

Conventions used across the codebase:

  • ES modules (import / export), no require. Source files end in .ts and import other modules with explicit .js extensions on relative paths (Node ESM resolution).
  • camelCase for functions and variables, PascalCase for types and classes, kebab-case for filenames.
  • One concern per file. Modules in src/ map to a focused responsibility — parser, scanner, remediation step, output formatter — and changes that mix unrelated concerns are typically asked to be split.
  • Comments are written only when the why is non-obvious: a hidden constraint, a subtle invariant, or a workaround for a specific bug. Comments that just describe what the code does are removed during review.
  • Output and security language must be precise. Avoid words like "fully safe", "guaranteed compatible", or "stable version" in user-visible text. Findings are based on advisory data, not exploitability or runtime reachability claims.
  • Every finding should aim to produce a runnable command where the data supports it. Vague guidance like "upgrade the parent dependency chain" without naming the parent is treated as a regression.

Named constants

Magic strings and numbers must not be inlined. Extract them to named constants in src/constants.ts:

// bad
const results = await queryOsv(packages, 100);

// good
import { DEFAULT_BATCH_SIZE } from "./constants.js";
const results = await queryOsv(packages, DEFAULT_BATCH_SIZE);

This applies to repeated flag strings, batch sizes, cache TTLs, depth limits, and any other value that has a name or meaning beyond its raw literal.

DRY

Repeated logic belongs in a shared utility, not copied across files. If the same string literal, function body, or conditional pattern appears in two or more places, extract it:

  • Repeated string literals - extract to a constant
  • Repeated utility functions - extract to the appropriate module under src/utils/
  • Repeated output formatting logic - extract to src/output/formatters.ts

Pull requests that duplicate existing logic are asked to consolidate before merge.

File size and single responsibility

Each file should have one clear purpose. If you cannot describe what a file does in one sentence, it is doing too much.

Keep files focused and small. When a file grows large, extract shared logic into a dedicated utility module rather than continuing to add to it. This applies especially to src/index.ts, which is the entry point and should remain a thin orchestration layer.

New output formats (JSON, SARIF, HTML, CycloneDX) each get their own dedicated module following the html-reporter.ts pattern. Do not add a new format to an existing formatter file.

Display logic, hint text, and error messages belong in utility modules (src/utils/, src/output/), not inlined in src/index.ts.

Braces on conditionals

All if, else, for, and while blocks must use braces, even for single-line bodies:

// bad
if (condition) doSomething();

// good
if (condition) {
  doSomething();
}

Formatting

Code is formatted with Prettier. Run the formatter before opening a pull request:

npm run format

CI will reject pull requests where files are not formatted. The project config is in .prettierrc at the repo root.

What gets pushed back during review:

  • Refactors bundled into feature work or bug fixes. Open a separate issue and pull request.
  • Defensive error handling for cases that cannot occur. Trust internal invariants; only validate at system boundaries (user input, external APIs, file I/O).
  • Unsupportable claims in commit messages, release notes, or output text. Commit messages must be factual and scoped to the diff.
  • Magic strings or numbers inlined in source code instead of named constants.
  • Duplicated logic that already exists in a shared utility.

Setup

npm install
npm test
npm run build

Testing expectations

Contributors must run the automated checks before opening a pull request:

npm test
npm run build

Test policy

Any new feature, behavior change, or bug fix that affects scan logic, parsing, output, or remediation must be covered by automated unit tests in the same pull request. The test policy applies to what lands in the pull request, not to the order in which the work is done locally — it is fine to validate a change manually first and add tests before opening the PR.

Practical exceptions:

  • Documentation-only changes, repo metadata, and trivial typo fixes do not require tests.
  • Changes where automated coverage is genuinely impractical (interactive output, environment-specific behavior, untestable third-party integration points) require a clear written reproduction case in the pull request description and an explicit acknowledgment from the reviewer that tests are not practical.

Where tests live

  • tests/ directory at the project root.
  • Test files mirror the source structure and are named *.test.ts.
  • Jest is the runner, invoked through node --experimental-vm-modules via npm test.

Style

  • Assert on a module's public API rather than its internals. Tests should describe behavior the project promises to its users.
  • Reuse the existing helpers (createFinding, createScanInputForSource, and similar) where applicable so test setup stays consistent.
  • One concern per it(...) block. A test description that needs three "and"s is doing too much.

Case study contributions

When adding a case study, only touch files specific to your study. Do not modify the shared index files — maintainers update those when merging.

Files you should add or change:

  • website/docs/case-studies/<your-project>.md — the case study document
  • examples/<your-project>/ — the lockfile fixture (package.json + lockfile)
  • website/static/img/<your-project>-logo.svg — the project logo

Files you must NOT touch:

  • website/docs/case-studies/index.md — maintained by project maintainers
  • website/sidebars.ts — maintained by project maintainers
  • README.md — maintained by project maintainers
  • examples/readme.md — maintained by project maintainers
  • CHANGELOG.md — maintained at release time, never by contributors
  • package.json or package-lock.json — not part of documentation work

Touching the shared files causes merge conflicts when multiple case study PRs are open at the same time. The maintainers add your study to the index, sidebar, and README when merging.

Pull request guidelines

Please try to keep pull requests focused.

A good pull request usually includes:

  • a clear description of the problem
  • the reasoning behind the change
  • before/after examples when output changes
  • tests for behavior changes, or a clear explanation when tests are not practical
  • documentation updates if user-facing behavior changed

Commit guidance

Clear, plain-English commit messages are preferred.

Examples:

  • add pnpm lockfile edge case handling
  • improve JSON output structure
  • fix direct vs transitive classification for nested paths
  • clarify remediation guidance in README

Reporting bugs

Please include:

  • operating system
  • Node.js version
  • package manager
  • lockfile type
  • command used
  • expected behavior
  • actual behavior
  • sample lockfile or minimal reproduction if possible

Security issues

Please do not open public issues for undisclosed security-sensitive problems in the tool itself.

See the Security Policy for responsible disclosure guidance.

Code of conduct

This project follows a Code of Conduct. Please review it before participating.