Skip to content

AGENTS.md

Latest commit

 

History

History
91 lines (81 loc) · 5.64 KB

AGENTS.md

File metadata and controls

91 lines (81 loc) · 5.64 KB

PROJECT KNOWLEDGE BASE

Generated: 2026-03-12T00:00:00Z Commit: HEAD Branch: main

OVERVIEW

JavaScript GitHub Action that performs PR auto-review and collaborator-gated /zai PR comment commands. Runtime executes bundled dist/index.js; maintained logic lives in src/index.js plus modular services in src/lib/*.

STRUCTURE

zai-code-bot/
├── src/index.js                      # Runtime orchestration and event dispatch (1016 lines)
├── src/lib/                          # Commands/auth/context/comments/api/services
├── src/lib/auto-review.js            # Large PR batching and synthesis
├── src/lib/changed-files.js          # Paginated changed-files fetch (3000 file limit)
├── src/lib/handlers/                 # Command handlers (ask/review/explain/describe/impact/help)
├── tests/                            # Unit and integration coverage
├── dist/index.js                     # Generated ncc bundle executed by GitHub
├── dist/licenses.txt                 # Generated third-party licenses
├── action.yml                        # Action inputs and runtime entry
├── .github/workflows/ci.yml          # Test/build/dist-drift/audit gates
└── .github/workflows/code-review.yml # Consumer usage example

WHERE TO LOOK

Task Location Notes
Route events and command execution src/index.js run(), pull_request path, issue_comment command path
Parse commands and enforce allowlist src/lib/commands.js /zai parser, command normalization, help fallback
Authorization and fork policy src/lib/auth.js Collaborator checks and fork-safe behavior
Comment/reaction behavior src/lib/comments.js Marker-based upsert, threaded reply (replyToId), reactions
API retry/error handling src/lib/api.js, src/lib/logging.js Retry policy, categorized safe errors
Large PR batching and synthesis src/lib/auto-review.js Batch creation, context limit handling, synthesis prompt
Paginated changed-files fetch src/lib/changed-files.js Handles GitHub's 3000 file API limit
Command-specific behavior src/lib/handlers/AGENTS.md Local guide for each handler module
Test strategy and fixtures tests/AGENTS.md Test map and suite conventions
Action runtime contract action.yml Node runtime + dist entrypoint
Build and drift policy package.json, .github/workflows/ci.yml ncc build and dist/ drift gate

CODE MAP

Symbol Type Location Refs Role
run function src/index.js high Top-level event gate + dispatcher
handlePullRequestEvent function src/index.js medium PR auto-review flow
handleIssueCommentEvent function src/index.js high Command parse/auth/progress/dispatch flow
handlePullRequestReviewCommentEvent function src/index.js high Inline review comment command flow
dispatchCommand function src/index.js high Handler selection and response management
enforceCommandAuthorization function src/index.js medium Auth gate before command dispatch
parseCommand function src/lib/commands.js high Command extraction and validation
checkForkAuthorization function src/lib/auth.js medium Fork-aware security policy
buildHandlerContext function src/lib/context.js medium Shared context for handlers
upsertComment function src/lib/comments.js high Marker idempotency + threaded reply support
callWithRetry function src/lib/api.js medium API retry/backoff wrapper
saveContinuityState function src/lib/continuity.js medium Hidden state persistence across turns
createReviewBatches function src/lib/auto-review.js medium Large PR file chunking
fetchAllChangedFiles function src/lib/changed-files.js medium Paginated file list (3000 limit)
MAX_PR_FILES_API_LIMIT constant src/lib/changed-files.js low GitHub API ceiling (3000)

CONVENTIONS

  • Edit maintained code in src/; do not hand-edit generated dist/index.js.
  • After source changes, run npm run build and commit dist/index.js + dist/licenses.txt.
  • Use marker-based idempotent comments; preserve marker constants and update semantics.
  • Command responses should stay threaded to the invoking comment via replyToId.
  • Keep security posture strict: collaborator/fork checks before command execution, no secret leakage.

ANTI-PATTERNS (THIS PROJECT)

  • Bypassing authorization/fork checks for command handlers.
  • Executing command logic for non-PR issue comments.
  • Allowing unbounded context payloads into prompts.
  • Editing dist/ manually or shipping source changes without rebuilt artifacts.
  • Treating .github/workflows/code-review.yml example as runtime logic.

UNIQUE STYLES

  • Event-first architecture: src/index.js orchestrates; src/lib/* isolates concerns.
  • Reactions communicate command lifecycle (eyes/thinking/rocket/x).
  • Continuity is encoded with hidden markers in comments, not external storage.

COMMANDS

npm install
node --test
npm run build

NOTES

  • CI (.github/workflows/ci.yml) enforces tests, build, dist drift, and security audit.
  • No linting/formatting configs (ESLint, Prettier) — rely on code review and CI gates.
  • 6 command handlers: ask (521 lines), review (218 lines), explain (355 lines), describe (129 lines), impact (336 lines), help (95 lines).
  • Test framework: Vitest v3 (not Jest). Command: npm test → vitest run --coverage.
  • Large files: src/index.js (1016 lines), src/lib/handlers/ask.js (521 lines).