AGENTS.md

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

Coding Principles

Principles inspired by andrej-karpathy-skills. Bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them — don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it — don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

Spec

See spec.md for the full design specification.

Always update spec.md after modifying any functionality, commands, flags, or output formats.

Development

npm run build        # Build with tsup (required before running e2e tests)
npm run dev          # Watch mode
npm run test         # Run all tests with vitest
npm run typecheck    # TypeScript type check
node dist/index.js   # Run built CLI

To run a single test file:

npx vitest run src/__tests__/cli.test.ts

Note: The e2e tests in src/__tests__/cli.test.ts run against the built dist/index.js — always npm run build first.

Architecture

Data Flow

CLI invocation
  → src/index.ts         (parses global flags, dispatches to command)
  → src/commands/*.ts    (command logic)
  → src/data/version.ts  (resolves antd version: --flag > node_modules > package.json > fallback)
  → src/data/loader.ts   (loads data/v4.json | v5.json | v6.json)
  → src/output/          (formats output as text/json/markdown)

Adding a New Command

1. Create src/commands/<name>.ts exporting registerXxxCommand(program: Command): void
2. Import and call it in src/index.ts under the appropriate comment block
3. Follow the pattern: read global opts via program.opts<GlobalOptions>(), call detectVersion(), load metadata, then output() or printError()

Key Modules

• src/types.ts — All shared types (ComponentData, MetadataStore, GlobalOptions, CLIError) and the localize() helper for en/zh switching
• src/data/loader.ts — loadMetadata(majorVersion) loads bundled JSON; findComponent() does case-insensitive lookup
• src/data/version.ts — detectVersion(flagVersion?) returns { version, majorVersion, source }; also exports compare() and valid() semver helpers
• src/output/error.ts — createError(), printError(), fuzzyMatch() (Levenshtein-based typo suggestions), and ErrorCodes constants
• src/output/formatter.ts — output(data, format) and formatTable(headers, rows, format) for aligned text/markdown/json tables
• src/utils/scan.ts — collectFiles(dir) and getJSXElementName(node) used by lint and usage commands

Project Structure

src/
  index.ts          # CLI entry point, registers all commands
  types.ts          # Shared TypeScript types + localize() helper
  commands/         # One file per command (list, info, demo, token, semantic, changelog/diff, doctor, usage, lint, migrate, mcp)
  mcp/              # MCP server: tools.ts (7 tool definitions + handlers), prompts.ts (prompt constants)
  data/             # loader.ts, version.ts, cache.ts
  output/           # formatter.ts, error.ts
  utils/            # scan.ts (file collection + antd import parsing)
  __tests__/        # e2e CLI tests (require built dist/), unit tests in commands/ subdir

data/
  v4.json           # Bundled antd v4 metadata
  v5.json           # Bundled antd v5 metadata
  v6.json           # Bundled antd v6 metadata

scripts/
  extract.ts        # Data extraction from antd source checkout
  extractors/       # Per-data-type extractor modules

Tech Stack

• TypeScript + Node.js (ESM, "type": "module")
• CLI framework: commander
• Build: tsup
• Tests: vitest
• Node minimum: 20+

Git Workflow

• Never commit directly to main. Always create a feature branch and submit a PR.

Release Workflow

Every publish (including beta/pre-release) must follow this checklist:

1. Update CHANGELOG.md with a version section describing all changes
2. Run tests (npm run test)
3. npm publish --otp=<code> (add --tag beta for pre-releases)
4. git tag v{version} && git push origin v{version}
5. Create GitHub Release: gh release create v{version} --title "v{version}" --notes "<changelog content>" (add --prerelease for beta)

CHANGELOG.md and GitHub Release notes must have identical content. Never use auto-generated release notes — always write them manually to match the CHANGELOG.

Testing Safety

Tests must NEVER cause real-world side effects. Any function that interacts with external services (GitHub API, npm registry, network requests, file system outside temp dirs, etc.) must be fully mocked in tests. Specifically:

• submitViaGh, checkGhAvailable and any function that calls gh CLI or creates GitHub issues must use vi.fn() with a safe default implementation (e.g. vi.fn(() => false)), never vi.fn(actualFunction) which would use the real function as fallback
• vi.restoreAllMocks() resets mocks to their default implementation — if the default is the real function, it will execute after restore. Always use safe no-op defaults in vi.mock() factories
• Network-calling functions (node:https, fetch, etc.) must be mocked to prevent real HTTP requests
• Tests that create temp files/directories must clean up in finally blocks or afterEach

Key Conventions

• All commands support --format json|text|markdown and --lang en|zh
• JSON output must be machine-parseable with no decoration
• Error output follows the standard shape: { error, code, message, suggestion }; errors go to stderr, normal output to stdout
• Exit codes: 0 success, 1 user error, 2 system error
• Data is fully bundled — no remote fetch at runtime
• CLI version flag is -V / --cli-version (not --version, which targets antd version)
• Bilingual data stored as paired fields: description / descriptionZh, use localize(en, zh, lang) to pick