Skip to content

AGENTS.md

Latest commit

 

History

History
57 lines (44 loc) · 2.43 KB

AGENTS.md

File metadata and controls

57 lines (44 loc) · 2.43 KB

Agent Guide

This document provides essential information for AI agents and developers working on the @nahkies/openapi-code-generator monorepo.

Project Overview

This is a monorepo managed with pnpm. It produces a CLI tool for generating high-quality TypeScript client SDKs and server scaffolding from OpenAPI 3.0, 3.1, and TypeSpec specifications.

Critical Constraints

  • Execution: NEVER use npx. ALWAYS use pnpm run <script> or pnpm exec <command>.
  • Read-Only Directories:
    • integration-tests-definitions/: Contains source specifications.
    • integration-tests/*/src/generated/: Contains generated code.
    • tsconfig.tsbuildinfo: Compiler state files.
  • Generated Files:
    • src/core/schemas/openapi-3.0-specification-validator.js
    • src/core/schemas/openapi-3.1-specification-validator.js
    • (These are generated by ajv during the build process).

Development Workflow

Environment

  • Node.js: >= 22.x (CI tests on 22.x and 24.x).
  • Package Manager: pnpm (Corepack enabled).

Common Commands

  • Install: pnpm install
  • Build: pnpm build (generates validators, bundles packages, and runs tsc -b).
  • Lint/Format: pnpm lint (uses Biome). For CI-style checks, use pnpm ci-lint.
  • Unit Tests: pnpm test (uses Jest). For coverage, use pnpm ci-test.
  • Integration Tests:
    • Generate: pnpm integration:generate
    • Validate/Build: pnpm integration:validate
  • E2E Tests:
    • Generate: pnpm e2e:generate
    • Validate: pnpm e2e:validate
  • Full Pipeline: pnpm ci-pipeline (runs all checks locally).

Testing Standards

  • Unit Testing: Tests are co-located with source code (.spec.ts).
  • Jest Globals: You MUST explicitly import Jest globals in test files: 
    import {describe, expect, it} from "@jest/globals"
  • Regression: Always ensure pnpm integration:validate passes after changes to generation logic.

Project Structure

For a detailed overview of the system's design, internal patterns (such as Builders and the Intermediate Representation), and data flows, please refer to docs/architecture.md.

  • packages/*: Implementation of the generator and its runtimes.
  • integration-tests-definitions: OpenAPI/TypeSpec definitions for testing.
  • integration-tests: Generated code from the above definitions.
  • scripts/: Maintenance and CI/CD scripts.
  • e2e/: End-to-end tests.