Skip to content

CLAUDE.md

Latest commit

 

History

History
106 lines (78 loc) · 3.66 KB

CLAUDE.md

File metadata and controls

106 lines (78 loc) · 3.66 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository structure

This is a monorepo with two main parts:

  • node/ — The CLI tool and core library (TypeScript, published to npm as retire). Source in node/src/, compiled output in node/lib/.
  • repository/ — The vulnerability database and tooling to manage it.

Node CLI (node/)

cd node
npm install
npm run build       # compile TypeScript → lib/
npm run test        # run the test suite (node/spec/tests/*.spec.ts)
npm run check       # lint + typecheck
npm run lint        # eslint --fix
npm run typecheck   # tsc --noEmit

Testing

Tests use the built-in node:test runner (describe/it with node:assert), not jest.

The specs import from ../../lib/, not ../../src/, so npm run build must be run before npm run test — otherwise you are testing the previously compiled output and your changes will appear to have no effect:

cd node
npm run build && npm run test

Run a single test file:

cd node
TS_NODE_PROJECT=tsconfig.spec.json node --require ts-node/register --test spec/tests/contentscan.spec.ts

Run a single test by name (matched as a regex against the it(...) description):

cd node
TS_NODE_PROJECT=tsconfig.spec.json node --require ts-node/register --test \
  --test-name-pattern 'should validate report according to schema' spec/tests/cyclonedx.spec.ts

Reporters that emit CycloneDX are validated against the JSON schemas bundled in node/spec/schema/. When adding support for a new spec version, add its bom-<version>.schema.json there too.

Vulnerability repository (repository/)

The source of truth is jsrepository-master.json. The other jsrepository*.json files are derived outputs and must be kept in sync.

After editing jsrepository-master.json, regenerate all derived files:

cd repository
node convertToVersioned

Validate that all derived files are in sync and the format is correct:

cd repository
node validate

Test that detection regexes actually match the real library files (downloads from CDN, cached in repository/tmp/):

cd repository
node test-detection.js
node test-detection.js <library-name>   # test a single library

Before submitting a PR: always run validate and test-detection.js.

Repository format

Entries in jsrepository-master.json use §§version§§ as a placeholder for a version-capturing regex group. Required fields per vulnerability:

  • severity — align with CVE/GHSA severity when available
  • cwe — array of CWE IDs
  • identifiers — at least one of: CVE, githubID, pr, issue

Version ranges: omit atOrAbove if no lower bound is known; use "999.0.0" for below when no upper bound is known.

Do not edit jsrepository.json directly — it is generated from master. Do not submit to npmrepository.json (deprecated).

Core detection logic (node/src/)

  • retire.ts — core scanning functions: scanUri, scanFileName, scanFileContent, check
  • scanner.ts — filesystem walker, orchestrates scanning files and npm packages
  • deepscan.ts — AST-based detection for libraries that embed version strings in non-obvious ways
  • repo.ts — loads and validates the repository (uses zod schema)
  • cli.ts — commander-based CLI entry point
  • reporters/ — output formatters (console, JSON, CycloneDX SBOM)

Bumping the version number

When bumping the version number of node/package.json, also update the version number in:

  • node/lib/retire.js
  • chrome/extension/manifest.json
  • chrome/extension-no-func/manifest.json