Skip to content

docs(hooks): generate the hook event × tool matrix from the hooks factories - #2540

Merged
dyoshikawa merged 2 commits into
mainfrom
resolve-scrap-issue-2522-hook-matrix
Aug 1, 2026
Merged

docs(hooks): generate the hook event × tool matrix from the hooks factories#2540
dyoshikawa merged 2 commits into
mainfrom
resolve-scrap-issue-2522-hook-matrix

Conversation

@dyoshikawa

Copy link
Copy Markdown
Owner

Summary

The Hook event × tool matrix in docs/reference/file-formats.md was hand-maintained and had drifted badly:

  • Missing columns for twelve hook-capable targets (Pi Coding Agent, Amp, Hermes Agent, Reasonix, Qwen Code, Vibe, Junie, Grok CLI, Kimi Code, the Kiro CLI/IDE variants, and the Claude Code / Antigravity plugin variants).
  • Still carried a Gemini CLI column, which is no longer a rulesync target at all.

This PR takes the issue's "generate it so it cannot go stale" option:

  • New scripts/hook-events-table.ts renders the table between HOOK_EVENTS_MATRIX markers from each hooks factory's supportedEvents in toolHooksFactories — the same source of truth the generator's skip-warnings come from. Columns follow TOOL_DISPLAY order (like the other generated tables) and rows follow canonical HOOK_EVENTS order, restricted to events at least one target supports. A hooks target missing from TOOL_DISPLAY throws.
  • scripts/generate-docs-content.ts applies the renderer (and oxfmt) to file-formats.md before embedding the docs, so a stale committed table makes the existing check:docs-content drift gate fail — no new package script and no package.json change needed.
  • The regenerated table now has 28 tool columns × 48 event rows; I machine-verified every cell against the *_HOOK_EVENTS constants (0 mismatches).
  • The hooks prose PascalCase-translation list now names Qwen Code instead of the removed Gemini CLI target.

Testing

  • pnpm cicheck green (generation is idempotent; second run produces no diff).
  • Cell-by-cell verification script against toolHooksFactories reported checked rows: 48 cols: 28 errors: 0.

Closes #2522

🤖 Generated with Claude Code

dyoshikawa pushed a commit that referenced this pull request Jul 31, 2026
…mt plumbing

Review follow-ups on PR #2540:

- check:docs-content now also diffs docs/reference/file-formats.md, so a
  committed-stale table cannot slip past the gate even when the embed is
  fresh (matches how check:supported-tools diffs its markdown targets).
- file-formats.md is rewritten unconditionally: the renderer emits cells
  without column padding and oxfmt owns the final layout, so the old
  changed-content guard never fired anyway.
- The oxfmt invocation is factored into a runOxfmt helper with stderr
  inherited, keeping formatter failures diagnosable.
- The marker-replacement logic is extracted to scripts/markdown-markers.ts
  (shared with generate-supported-tools-tables.ts) and now rejects
  END-before-BEGIN instead of silently duplicating content.
- Unit tests for renderHookEventsMatrix and replaceBetweenMarkers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@dyoshikawa

Copy link
Copy Markdown
Owner Author

Status: review complete and ready to merge, but intentionally left for a manual merge.

  • Two review rounds (code + security) finished with zero mid-or-above findings; the round-1 findings (drift-gate hole, dead guard, oxfmt plumbing, DRY, tests) were all addressed in 76fad24.
  • CI is fully green on the head commit (all 9 checks including Windows/macOS E2E).
  • This PR touches package.json (one line in scripts: check:docs-content now also diffs docs/reference/file-formats.md), and the autonomous batch flow does not auto-merge PRs that edit package.json per its safety policy.

One optional follow-up noted by review (not blocking): generate-supported-tools-tables.ts still uses the pnpm exec oxfmt invocation without the Windows shell handling; unifying it with runOxfmt could be a tiny future cleanup.

cm-dyoshikawa and others added 2 commits August 1, 2026 07:59
…tories

The Hook event x tool matrix in docs/reference/file-formats.md was
hand-maintained and had drifted badly: it was missing columns for twelve
hook-capable targets (Pi, Amp, Hermes Agent, Reasonix, Qwen Code, Vibe,
Junie, Grok CLI, Kimi Code, Kiro CLI/IDE variants, plugin variants) and
still carried a column for Gemini CLI, which is no longer a rulesync
target at all.

The table is now rendered between HOOK_EVENTS_MATRIX markers by
scripts/hook-events-table.ts from each hooks factory's supportedEvents
(the same source of truth the generator warns from at generate time),
with columns ordered like the other generated tables (TOOL_DISPLAY) and
rows in canonical HOOK_EVENTS order, restricted to events at least one
target supports. scripts/generate-docs-content.ts applies it before
embedding the docs, so a stale committed table fails the existing
check:docs-content drift gate - no new package script needed.

Also updates the hooks prose to name Qwen Code instead of the removed
Gemini CLI target in the PascalCase-translation list.

Closes #2522

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…mt plumbing

Review follow-ups on PR #2540:

- check:docs-content now also diffs docs/reference/file-formats.md, so a
  committed-stale table cannot slip past the gate even when the embed is
  fresh (matches how check:supported-tools diffs its markdown targets).
- file-formats.md is rewritten unconditionally: the renderer emits cells
  without column padding and oxfmt owns the final layout, so the old
  changed-content guard never fired anyway.
- The oxfmt invocation is factored into a runOxfmt helper with stderr
  inherited, keeping formatter failures diagnosable.
- The marker-replacement logic is extracted to scripts/markdown-markers.ts
  (shared with generate-supported-tools-tables.ts) and now rejects
  END-before-BEGIN instead of silently duplicating content.
- Unit tests for renderHookEventsMatrix and replaceBetweenMarkers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@dyoshikawa
dyoshikawa force-pushed the resolve-scrap-issue-2522-hook-matrix branch from 76fad24 to b134a35 Compare August 1, 2026 15:01
@dyoshikawa
dyoshikawa merged commit e888789 into main Aug 1, 2026
9 checks passed
@dyoshikawa

Copy link
Copy Markdown
Owner Author

@dyoshikawa Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: Hook event × tool matrix in file-formats.md is missing columns for several hook-capable targets (Pi, Amp, Hermes, Reasonix, Qwen, ...)

2 participants