Skip to content

AGENTS.md

Latest commit

 

History

History
45 lines (33 loc) · 2.56 KB

AGENTS.md

File metadata and controls

45 lines (33 loc) · 2.56 KB

Repository Guidelines

Project Structure & Module Organization

  • src/ contains the extension source (TypeScript). Entry point is src/extension.ts, with feature areas under src/commands/, src/redmine/, src/kanban/, src/timer/, and src/webviews/.
  • test/ hosts Vitest suites: unit tests in test/unit/, integration tests in test/integration/, and supporting fixtures/mocks in test/fixtures/ and test/mocks/.
  • media/ holds walkthrough content and assets used by the extension UI.
  • docs/ contains architecture notes, API references, and performance guidance.
  • Build output lands in out/ (generated by esbuild.cjs).

Build, Test, and Development Commands

  • npm install installs dependencies and git hooks (scripts/install-hooks.sh).
  • npm run compile builds the extension into out/ (production build).
  • npm run watch runs the incremental build for local dev.
  • npm run lint checks code style with ESLint.
  • npm run typecheck runs tsc --noEmit.
  • npm test runs the Vitest suite once; npm run test:watch keeps it running.
  • npm run test:coverage runs tests with coverage; npm run ci runs lint + typecheck + coverage.
  • npm run package builds a VSIX package.
  • npm run create-test-issues seeds Redmine with test data for manual workflows.

Coding Style & Naming Conventions

  • Formatting is enforced by Prettier (tabWidth: 2, semicolons, trailing commas, LF line endings).
  • Linting is enforced by ESLint (npm run lint).
  • Use descriptive, feature-based filenames consistent with existing modules (e.g., kanban-controller.ts, redmine-server.ts).

Testing Guidelines

  • Framework: Vitest (vitest.config.ts).
  • Naming convention: *.test.ts under test/unit/ or test/integration/.
  • Add new tests near the related feature area and prefer unit coverage for utilities.

Commit & Pull Request Guidelines

  • Commit history favors short, imperative subjects (e.g., “Add …”, “Fix …”, “Move …”), no trailing period.
  • Commit messages are validated: subject ≤ 50 chars, body lines ≤ 72 chars, blank line between subject/body.
  • CONTRIBUTING expects Type: description with types like Add, Fix, Feat, Chore, Docs, Test, Refactor, Revert.
  • PRs should be small and focused; add a [Unreleased] entry to CHANGELOG.md for user-facing changes and discuss new features in GitHub Discussions first.

Security & Configuration Notes

  • The extension requires HTTPS and stores API keys in the OS keychain.
  • When debugging API issues, use Redmine: Show API Output and include sanitized logs in issues.