AGENTS.md

1# comment-checker-core — apply-patch Parser + Checker Runner (Core)
2 
3**Generated:** 2026-06-17
4 
5## OVERVIEW
6 
7Two responsibilities: (1) parse LLM apply-patch edits into structured `CheckerEdit[]`, and (2) run the external `@code-yeongyu/comment-checker` binary to detect AI-slop comments in changed code. Spawn is dependency-injected (not `child_process.spawn`) so both editions can drive the same core. Package: `@oh-my-opencode/comment-checker-core`.
8 
9## PUBLIC API (`src/index.ts`)
10 
11| Export | Source | Role |
12|--------|--------|------|
13| `parseApplyPatchRequests(patch)` | `apply-patch-edits.ts` | parse `*** Add/Update/Delete File:` + `*** Move to:` protocol with `@@` context + `+`/`-` markers |
14| `extractApplyPatchEdits(details, args?)` | `apply-patch-edits.ts` | high-level extractor (patch text OR metadata files) |
15| `getApplyPatchMetadataFiles(details)` | `apply-patch-edits.ts` | read files from nested `details.files` / `result.files` / `metadata.files` |
16| `resolveCommentCheckerBinary(input)` | `runner.ts` | locate binary via `createRequire(@code-yeongyu/comment-checker)` |
17| `runCommentChecker(input, options)` | `runner.ts` | pipe `HookInput` JSON to stdin, read stdout/stderr, return `CheckResult` |
18| types (17) | `types.ts` | `CheckerEdit`, `HookInput`, `CheckResult`, `SpawnFn`/`SpawnProcess`/`SpawnSignal`, `ApplyPatchFileMetadata`, … |
19 
20## DEPENDENCIES & CONSUMERS
21 
22- **Depends on:** `@oh-my-opencode/utils` (`isRecord` from `utils/record-type-guard`).
23- **Consumed by BOTH editions:** `omo-opencode/src/hooks/comment-checker/{hook,types,cli}.ts` and `omo-codex/plugin/components/comment-checker/src/{core,core-values,apply-patch,request-extractor}.ts`.
24 
25## NOTES
26 
27- **Exit-code contract:** `0` = clean, `2` = has comments; any other code / error / timeout silently returns `{hasComments: false, message: ""}`.
28- **Spawn timeouts:** default 30s, 1s kill grace, SIGTERM→SIGKILL escalation.
29- **`SpawnProcess` is an injected interface** — `stdin.write/end`, `ReadableStream<Uint8Array>` stdout/stderr, `exited: Promise<number>` — never the Node `ChildProcess` type directly.
30- **`HookInput` mirrors OpenCode's `tool.execute.before` input schema** exactly, so the same parser serves the Codex `PreToolUse`/`PostToolUse` adapters.
31- Parent: [`packages/AGENTS.md`](../AGENTS.md).
32