Skip to content

AGENTS.md

Latest commit

 

History

History
59 lines (41 loc) · 2.83 KB

AGENTS.md

File metadata and controls

59 lines (41 loc) · 2.83 KB
Raw

datadog-ci

TypeScript monorepo for the Datadog CI CLI tool. Uses Yarn 4 workspaces, Clipanion for CLI commands, and Jest for testing.

See CONTRIBUTING.md for full details on creating commands, releasing, and CI.

Quick commands

yarn install          # install dependencies
yarn build            # compile TypeScript
yarn launch <scope> <cmd> [args]  # run a command in dev (no build needed)
yarn test             # run all tests
yarn test <path>      # run tests for a specific package/file
yarn lint             # lint (fails on errors)
yarn format           # lint + auto-fix

Architecture

  • packages/base -- command definitions (descriptions, paths, args), extends BaseCommand. Does NOT hold implementations (with some exceptions).
  • packages/plugin-<scope> -- command implementations for a scope. Exports PluginCommand extending the base command.
  • packages/datadog-ci -- thin CLI entrypoint, lists built-in plugins as dependencies.

Commands are registered in packages/base/src/cli.ts (auto-generated by bin/lint-packages.ts -- do not edit manually).

Creating a new command

  1. Create the base command in packages/base/src/commands/<scope>/<command>.ts extending BaseCommand
  2. The execute() method should call executePluginCommand(this)
  3. Run yarn plugin:create <scope> to scaffold the plugin package
  4. Implement the plugin in packages/plugin-<scope>/src/commands/<command>.ts
  5. Update CODEOWNERS, README, labels per the checklist in CONTRIBUTING.md

Config resolution order

File config -> environment variables -> CLI args (highest priority).

Code style

Prettier + ESLint enforce formatting and style. Run yarn format to auto-fix, yarn lint to check. A post-commit hook runs lint automatically.

Not enforced by lint -- follow manually:

  • Use getRequestBuilder() from helpers/utils or httpRequest() from helpers/request for HTTP -- not raw fetch or axios
  • Use datadogRoute() from helpers/request/datadog-route to build Datadog API paths, and thirdParty() from helpers/request/third-party for external URLs. Never try to bypass this with casts, and never use thirdParty() for Datadog API calls.

Testing

  • Jest, files in __tests__/*.test.ts, fixtures in __tests__/fixtures/
  • Use createMockContext() and makeRunCLI() from packages/base/src/helpers/__tests__/testing-tools.ts
  • Use createCommand() to instantiate a command with mock context for unit tests
  • jest.spyOn() for mocking, follow existing patterns in nearby test files

Verification

After making changes, always verify by running:

  1. yarn build -- ensure TypeScript compiles cleanly
  2. yarn lint -- ensure no lint errors (use yarn format to auto-fix)
  3. yarn test <path to relevant test files> -- ensure tests pass for affected packages