redhat-developer / redhat-developer/rhdh-plugins

Add API report completeness validation instruction for review agents

Open Beginner friendly
#4,506 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement feature fullsend ready-for-triage Review effort 1/5 triaged
Dominant language
TypeScript
Stars
48
Forks
120
Avg merge
2d 6h
Merged PRs (30d)
337

Description

What happened

On PR #4417, the fix agent pushed commit 6e4e53b which included api-report changes. The review agent (run 33420007704) flagged report.api.md as stale — a correct but shallow finding. The human reviewer then discovered the problem was catastrophic: a prior commit had run api-extractor without --tsc, reading stale .d.ts files, which dropped the entire DeltaSyncManager public API surface (6 exported symbols) from the report. Three follow-up commits (88cc6bd, df74548/05ffd1f, b03bb6b) were needed to fix this, including reverting unintended reordering in unrelated packages.

What could go better

The review agent detected the api-report was stale but did not assess its structural completeness. It noticed field-level issues (like the updated optionality mismatch) but missed that entire classes and interfaces were absent from the report. If the review agent had cross-referenced the symbols exported from src/index.ts against the entries in report.api.md, it would have detected the missing DeltaSyncManager, CursorStore, CursorState, ApplyDeltaOptions, DeltaSyncManagerOptions, and InMemoryCursorStore entries. Confidence: high — the diff and human triage comments explicitly document this gap. This is complementary to existing issue #4392 (which covers code/fix agent regeneration); even if agents always regenerate the report, an incorrect regeneration (as happened here) would go undetected without review-side validation.

Proposed change

Add a review-focused instruction to .fullsend/AGENTS.md after the existing changeset guidance. The instruction should tell the review agent: when a PR adds, removes, or renames public exports in any plugin package, verify that report.api.md includes entries for all symbols re-exported from the package's src/index.ts. Flag missing or unexpectedly removed entries as a medium-severity finding. Example instruction text: "When reviewing PRs that change public API surface (exports in src/index.ts), cross-check report.api.md to confirm all exported symbols appear in the report. A report missing exported symbols indicates a broken api-extractor run."

Validation criteria

The next 3 agent-authored or agent-reviewed PRs in this repo that modify public API exports should have the review agent validate api-report completeness against src/index.ts exports. The review agent should flag any missing symbols rather than only noting staleness.


Generated by retro agent from https://github.com/redhat-developer/rhdh-plugins/pull/4417

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in .fullsend/AGENTS.md after the existing changeset guidance and review the proposed API-report completeness instruction. Ensure it tells review agents to compare public exports from each plugin package's src/index.ts with report.api.md and flag missing or unexpectedly removed entries as medium severity. Done means the instruction is added and the next three relevant PRs are covered by the stated validation criterion.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
developer-experience
Issue type
Feature
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.