From b669409dacaf48c05663ebe6e0ab291fbc2044bd Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:01:50 +0000 Subject: [PATCH 1/3] docs: update AGENTS.md from scheduled task --- src/lib/handlers/AGENTS.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/lib/handlers/AGENTS.md b/src/lib/handlers/AGENTS.md index da2dbf9..f253735 100644 --- a/src/lib/handlers/AGENTS.md +++ b/src/lib/handlers/AGENTS.md @@ -1,15 +1,17 @@ # HANDLER MODULE GUIDE ## OVERVIEW + Command handlers implement `/zai` behavior only after parsing + authorization; each module owns prompt construction, API call wiring, and response formatting. The `scheduled` handler is distinct: it executes scheduled tasks defined in `.zai-scheduled.yml` (and the manual `/zai update-agents` command) rather than responding to a standard review command. ## WHERE TO LOOK + | Command | File | Notes | |---------|------|-------| | `/zai ask` | `src/lib/handlers/ask.js` | Uses continuity state and broad PR context | | `/zai review ` | `src/lib/handlers/review.js` | Targeted diff review, file-in-PR validation | -| `/zai explain #Lx-Ly` | `src/lib/handlers/explain.js` | Range parsing + snippet extraction | -| `/zai describe` | `src/lib/handlers/describe.js` | File/directory description | +| `/zai explain #Lx-Ly` | `src/lib/handlers/explain.js` | Range parsing + snippet extraction; auto-detects range from review comments when omitted | +| `/zai describe` | `src/lib/handlers/describe.js` | Generate a PR description from commit messages | | `/zai impact` | `src/lib/handlers/impact.js` | Change impact analysis | | `/zai help` | `src/lib/handlers/help.js` | Static help output with auth gate | | `/zai update-agents` | `src/index.js` (`dispatchCommand`) | Manual AGENTS.md regen; reuses `handleUpdateAgentsTask` | @@ -17,6 +19,7 @@ Command handlers implement `/zai` behavior only after parsing + authorization; e | Handler registry | `src/lib/handlers/index.js` | Dispatcher map consumed by runtime (note: `scheduled` is exported but not in the `/zai` HANDLERS map) | ## SCHEDULED MODULE (`scheduled.js`) KEY SYMBOLS + - `handleScheduledEvent` (entry) → `executeScheduledTask` (per-task) → `buildExecutionContext` → `getScheduledHandler` (registry lookup). - `handleUpdateAgentsTask` (grounded flow): gist command → `collectRepositoryContext` (`../repository-context.js`: real tree + existing AGENTS.md discovery + key files) → `buildAgentsUpgradePrompt` (embeds context, tells model it has NO live repo access) → `callZaiApiWithRetry` → `parseFileUpdatesFromResponse` (multi-format JSON) → `validateGeneratedAgentFiles` (`../agents-validation.js`: rejects non-AGENTS paths, out-of-scope writes, hallucinated content referencing non-existent files) → diff vs repo files → `createPR`. - Registry: `SCHEDULED_HANDLERS` (const) + `registerScheduledHandler`/`getAllScheduledHandlers` for extension. @@ -25,24 +28,29 @@ Command handlers implement `/zai` behavior only after parsing + authorization; e - Scoping config (all optional, per-task in `.zai-scheduled.yml`): `context_paths`, `target_paths`, `exclude_paths`, `max_context_chars`, `max_file_chars`, `max_files_to_fetch`, `allow_create_new`, `update_existing_only`. ## CONVENTIONS + - Keep command argument parsing explicit and reject invalid formats early. - Always use threaded replies (`replyToId`) for command results. -- Reactions should reflect lifecycle: acknowledge -> work -> success/failure. +- Reactions should reflect lifecycle: acknowledge → work → success/failure. - Keep prompts bounded via context truncation helpers; never pass raw unbounded patches. - Return user-safe failures; log internal details through shared logging helpers. ## TESTING -- Local handler unit coverage exists in `tests/handlers/`: `ask.test.js`, `explain.test.js`, `impact.test.js`, `review.test.js`, `scheduled.test.js`. + +- Handler unit coverage in `tests/handlers/`: `ask.test.js`, `explain.test.js`, `impact.test.js`, `review.test.js`, `scheduled.test.js`. +- `describe` handler tested in `tests/describe.test.js` (at `tests/` level, not `tests/handlers/`). - Scheduled pipeline coverage: `tests/handlers/scheduled.test.js` (registry, PR creation, parse, grounded `handleUpdateAgentsTask` flow incl. hallucination rejection), `tests/scheduled-config.test.js` (config + `validateAgentsConfig` scoping fields), `tests/repository-context.test.js` (tree/AGENTS.md discovery/budgets/globs), `tests/agents-validation.test.js` (path/hallucination/target-path guards incl. PR #15 regression). - End-to-end command pipeline behavior is validated in `tests/integration/command-pipeline.test.js`. - When changing parsing or output contracts, update both unit and integration assertions. ## ANTI-PATTERNS + - Parsing arguments with loose heuristics that silently alter user intent. - Posting top-level comments for command replies (breaks conversational threading). - Bypassing `auth.checkForkAuthorization` in a handler. - Embedding duplicate parser/auth logic that already exists upstream. ## NOTES + - Prefer adding helper functions within a handler module before introducing cross-handler coupling. - Keep marker constants stable once tests depend on them. From 84914fbb7fb8e0d8359bcd2ae4db6bf8f6a1fc49 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:01:51 +0000 Subject: [PATCH 2/3] docs: update AGENTS.md from scheduled task --- tests/AGENTS.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/tests/AGENTS.md b/tests/AGENTS.md index 4fb56f8..b25505a 100644 --- a/tests/AGENTS.md +++ b/tests/AGENTS.md @@ -1,9 +1,11 @@ # TEST SUITE GUIDE ## OVERVIEW + Repository test coverage mixes module-focused tests in `tests/*.test.js` and scenario-driven flows in `tests/integration/*`. ## STRUCTURE + ```text tests/ ├── *.test.js # Module-level tests for lib/runtime units @@ -15,32 +17,40 @@ tests/ ``` ## WHERE TO LOOK + | Task | Location | Notes | |------|----------|-------| | Parser/auth/comment unit behavior | `tests/commands.test.js`, `tests/auth.test.js`, `tests/comments.test.js` | Fast regression checks | | Runtime orchestration checks | `tests/action.test.js`, `tests/handlers.test.js`, `tests/index.test.js` | Entry flow and dispatch behavior | -| API and logging resilience | `tests/api.test.js`, `tests/logging.test.js` | Retry/error categorization | +| API and logging resilience | `tests/api.test.js`, `tests/logging.test.js` | Retry/error categorization, progressive timeout | | Context, PR fetch, and batching | `tests/context.test.js`, `tests/pr-context.test.js`, `tests/changed-files.test.js`, `tests/auto-review.test.js` | Diff scoping, file-at-ref fetch, paginated/batched review | | Continuity and events | `tests/continuity.test.js`, `tests/events.test.js` | Hidden-marker state, event-type detection | | Code scope and window extraction | `tests/lib/code-scope.test.js` | Token budget, enclosing block, window extraction | | Describe handler | `tests/describe.test.js` | PR description generation | | Scheduled pipeline | `tests/handlers/scheduled.test.js`, `tests/scheduled-config.test.js`, `tests/repository-context.test.js`, `tests/agents-validation.test.js` | Config load + `validateAgentsConfig` scoping; `parseFileUpdatesFromResponse`; grounded `handleUpdateAgentsTask` flow incl. hallucination rejection; repo-context collection (tree/budgets/globs); validation guards incl. PR #15 regression | | Scheduled pipeline (integration) | (pending) | End-to-end schedule event → context → Z.ai mock → validated PR is still a gap; unit coverage of the grounded flow exists via the `handleUpdateAgentsTask` seam (`__callZaiForTest`). | -| Full command pipeline | `tests/integration/command-pipeline.test.js` | Parse -> auth -> handler -> output contract | +| Full command pipeline | `tests/integration/command-pipeline.test.js` | Parse → auth → handler → output contract | | PR auto-review behavior | `tests/integration/pr-auto-review.test.js` | Marker upsert and PR event lifecycle | +| Shared mocks | `tests/helpers/mocks.js` | Reusable mock utilities for handlers and services | ## CONVENTIONS -- Test framework: Vitest v3 (uses vitest globals: describe/test/expect); configured via `vitest.config.js`. + +- Test framework: Vitest v3 (uses vitest globals: `describe`/`test`/`expect`); configured via `vitest.config.js`. - Keep tests deterministic with explicit mock payloads and marker assertions. - Prefer scenario names that encode trigger + expected visible outcome. - When changing comment markers or command UX, update integration snapshots/assertions immediately. +- Use `tests/helpers/mocks.js` for shared mock utilities instead of duplicating inline. +- Use `tests/fixtures/` for static event payloads instead of inline JSON. ## ANTI-PATTERNS + - Deleting integration assertions to make behavior changes pass. - Asserting only internal calls without validating user-visible output. - Duplicating large fixtures inline when reusable fixtures already exist. ## NOTES + - Test command: `npm test` → `vitest run --coverage`. - Coverage uploaded to Codecov. - Integration tests are the safety net for command threading and marker idempotency. +- Run specific test file: `npx vitest run `. From 1a1c652d7f36c13c92f80f80dda0b517a788210c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:01:52 +0000 Subject: [PATCH 3/3] docs: update AGENTS.md from scheduled task --- tests/integration/AGENTS.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/tests/integration/AGENTS.md b/tests/integration/AGENTS.md index 3f8f542..45e43d3 100644 --- a/tests/integration/AGENTS.md +++ b/tests/integration/AGENTS.md @@ -1,9 +1,11 @@ # INTEGRATION TEST GUIDE ## OVERVIEW -Integration tests verify end-to-end GitHub event pipelines and visible bot behavior, not just isolated helper logic. + +Integration tests verify end-to-end GitHub event pipelines and visible bot behavior, not just isolated helper logic. They are the primary safety net for command threading and marker idempotency. ## WHERE TO LOOK + | Scenario | File | Notes | |----------|------|-------| | Issue comment command pipeline | `tests/integration/command-pipeline.test.js` | Event classification, command parse, auth, dispatch, response shape | @@ -11,11 +13,20 @@ Integration tests verify end-to-end GitHub event pipelines and visible bot behav | Integration fixture data | `tests/integration/fixtures/events.js` | Shared event payloads for realistic event simulation | ## CONVENTIONS + +- Test framework: Vitest v3 with globals (`describe`/`test`/`expect`); configured via `vitest.config.js`. - Test the public behavior chain from event input to final comment/reaction outcome. - Cover both happy paths and safety gates (non-PR comments, unauthorized users, empty diffs). - Keep marker expectations explicit so idempotent update regressions are caught quickly. +- Use shared fixtures from `tests/integration/fixtures/events.js` instead of duplicating event payloads inline. ## ANTI-PATTERNS + - Replacing integration assertions with unit-level mocks only. - Ignoring failure-path expectations for auth and API errors. - Coupling tests to unrelated implementation details that break harmless refactors. + +## NOTES + +- Run integration tests only: `npx vitest run tests/integration/`. +- Parent guide: `tests/AGENTS.md` for full test suite layout and conventions.