docs(agents): document how to add log events when porting from pnpm#374
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdded documentation requiring pacquet to mirror pnpm reporter emissions: a cardinal-rule note in AGENTS.md and a new "Reporter / log events" section in CODE_STYLE_GUIDE.md covering channel mapping, threading R: Reporter, emit placement, testing, prohibitions, and a worked example. ChangesDocumentation: Log Event Porting Guidance
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Pull request overview
Adds repository guidance to ensure ports from pnpm/pnpm preserve reporter event emissions (channel mapping, payload shape, ordering/cadence) so pacquet’s NDJSON remains consumable by @pnpm/cli.default-reporter.
Changes:
- Adds a new “Reporter / log events” section to
CODE_STYLE_GUIDE.mddescribing how to find upstream emits, map channels toLogEvent, threadR: Reporter, place emits, and test via a recording fake. - Updates
AGENTS.md’s cardinal rule list to explicitly include log emissions as part of “match pnpm” and links to the new style guide section.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| CODE_STYLE_GUIDE.md | New guidance section documenting the reporter/log-event porting and testing conventions. |
| AGENTS.md | Adds an explicit cardinal-rule pointer that “match pnpm” includes log emissions, linking to the style guide section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Closes #346. Adds a "Reporter / log events" section to `CODE_STYLE_GUIDE.md` covering the convention for porting reporter emissions: - **Finding the upstream emit** — three call shapes to grep for in `pnpm/pnpm` (`globalLogger.<channel>.<level>(...)`, `logger.<level>({ name: 'pnpm:<channel>', ... })`, and direct `streamParser.write(...)` calls). - **Channel mapping** — `crates/reporter/src/lib.rs`'s `LogEvent` enum is the canonical list, with each variant pinning `#[serde(rename = "pnpm:<channel>")]`. Includes the convention for adding a new channel (mirror the upstream TS shape field-for-field, add a wire-shape unit test). - **Threading** — `<R: Reporter>` generic on every fn that emits, turbofish at the production entry point, install-scoped state via parameters where dedup matters (e.g. `link_file`'s `&AtomicU8`). - **Where to put the emit** — match the upstream call site's position relative to side effects; cite the upstream permalink at a pinned SHA in the code comment. - **Testing** — recording-fake DI per #339, a `static Mutex<Vec<LogEvent>>` per test, sequence assertion via `matches!`. Verify the test catches the regression. - **What not to do** — don't reformat upstream messages, don't invent channels, don't change emit granularity in either direction. - **Worked example** — `pnpm:summary` in `Install::run` (landed in #355): shows the upstream permalink, the pacquet emit, and the test that pins the sequence. Adds a sixth bullet to `AGENTS.md`'s cardinal rule pointing at the new section, so the "match pnpm" mandate explicitly covers log emissions.
Per Copilot review on #374: - The placeholder `LogEvent::<Variant>(...)` looked like Rust generics syntax. Rephrase as concrete examples (`LogEvent::Stage(...)`, `LogEvent::Context(...)`) so a porter doesn't read it as `LogEvent::<Stage>(...)`. - The "what not to do" example pointed at `pacquet-tarball::run_without_mem_cache`'s gate, but the `pnpm:fetching-progress in_progress` throttle actually lives one call down, in `fetch_and_extract_once`. Update the reference so the cross-link resolves. The third Copilot finding (`ProgressMessage` and the `pnpm:fetching-progress` channel referenced as if they don't exist) was a rebase artifact — this branch was cut before #372 merged. The rebase onto current `main` makes those references valid; no further edit needed.
479dec8 to
4e7cc6c
Compare
A style guide should let a porter read it linearly without context-switching to GitHub. The four issue references (#345 for the reporter origin, #347 for the channel-backfill audit, #339 for the recording-fake pattern, #355 for the worked example's PR) were project history, not convention — none of them carried information the doc itself didn't already restate inline. Replace each with the concrete fact the reader needs: the reporter lives in `crates/reporter` (with its trait, enum, and sinks named in place); to add a new channel, do X, Y, Z (instead of "the work tracked under #347"); the recording-fake pattern is the unit-struct + static-mutex shape (described directly, no "from #339"); and the worked example is just the code, no "added in #355".
There was a problem hiding this comment.
🧹 Nitpick comments (2)
CODE_STYLE_GUIDE.md (2)
668-701: ⚡ Quick winSoften the concurrency claim about the
static Mutex(and clarify reset semantics).“The mutex is per-test, so concurrent tests in the same binary don't race on it” is mostly true because each test function has its own
static EVENTS. But it’s more precise to say thestaticis shared across all invocations of that specific test function within the process (and you still reset it to avoid cross-retry contamination).Consider a wording tweak like:
- “The mutex is per-test-function, so other tests have independent buffers. Reset it at the start in case the same test is re-run within the same process.”
Proposed wording tweak
-The mutex is per-test, so concurrent tests in the same binary don't race on it. Reset it at the top of the test in case nextest reuses the process for a retry. +The mutex is per-test-function, so other tests have independent buffers. Reset it at the top in case nextest reuses the process for a retry.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CODE_STYLE_GUIDE.md` around lines 668 - 701, Update the wording to clarify the scope of the static Mutex used in the example: state that the static EVENTS Mutex is shared across all invocations of that specific test function within the process (not per-process or per-test-binary), so other test functions have independent buffers but repeated runs/retries of the same test reuse the same static; keep the guidance to reset EVENTS at the start of install_emits_pnpm_event_sequence to avoid cross-retry contamination and mention the RecordingReporter and LogEvent usage remains the same.
704-710: Add pinned upstream permalink toremoteTarballFetcher.tsreference (matches guide's established pattern).This section correctly documents the throttling and size-gate behavior, but it references upstream's
remoteTarballFetcher.tsandlodash.throttle(..., 500)without a pinned permalink. The guide already establishes the pattern for citing upstream code (lines 654, 659, 713–727) using pinned SHAs likehttps://github.com/pnpm/pnpm/blob/086c5e91e8/[path]#L[line]. To prevent doc drift and match the guide's own requirements, link to the specific upstream commit and line(s) that justify the "exactly mirrors" claim. Similarly, optionally link to the exact pacquet location (BIG_TARBALL_SIZEandIN_PROGRESS_THROTTLEatcrates/tarball/src/lib.rs:846–847).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CODE_STYLE_GUIDE.md` around lines 704 - 710, Add a pinned upstream permalink to the reference of remoteTarballFetcher.ts and the lodash.throttle(..., 500) call so the claim "exactly mirrors" is verifiable: update the sentence mentioning remoteTarballFetcher.ts to include a GitHub blob URL pinned to the specific commit/SHA that contains the referenced lodash.throttle line, and likewise add an optional pinned permalink to the pacquet location (crates/tarball/src/lib.rs) pointing at the BIG_TARBALL_SIZE and IN_PROGRESS_THROTTLE lines referenced by fetch_and_extract_once; reference the unique symbols remoteTarballFetcher.ts, lodash.throttle, fetch_and_extract_once, BIG_TARBALL_SIZE and IN_PROGRESS_THROTTLE so reviewers can locate the exact lines.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@CODE_STYLE_GUIDE.md`:
- Around line 668-701: Update the wording to clarify the scope of the static
Mutex used in the example: state that the static EVENTS Mutex is shared across
all invocations of that specific test function within the process (not
per-process or per-test-binary), so other test functions have independent
buffers but repeated runs/retries of the same test reuse the same static; keep
the guidance to reset EVENTS at the start of install_emits_pnpm_event_sequence
to avoid cross-retry contamination and mention the RecordingReporter and
LogEvent usage remains the same.
- Around line 704-710: Add a pinned upstream permalink to the reference of
remoteTarballFetcher.ts and the lodash.throttle(..., 500) call so the claim
"exactly mirrors" is verifiable: update the sentence mentioning
remoteTarballFetcher.ts to include a GitHub blob URL pinned to the specific
commit/SHA that contains the referenced lodash.throttle line, and likewise add
an optional pinned permalink to the pacquet location (crates/tarball/src/lib.rs)
pointing at the BIG_TARBALL_SIZE and IN_PROGRESS_THROTTLE lines referenced by
fetch_and_extract_once; reference the unique symbols remoteTarballFetcher.ts,
lodash.throttle, fetch_and_extract_once, BIG_TARBALL_SIZE and
IN_PROGRESS_THROTTLE so reviewers can locate the exact lines.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: e86910c3-18c7-478f-b5b1-0b5ad5eb42f9
📒 Files selected for processing (2)
AGENTS.mdCODE_STYLE_GUIDE.md
✅ Files skipped from review due to trivial changes (1)
- AGENTS.md
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Two nitpicks on #374: - The "concurrent tests don't race on the mutex" sentence conflated two distinct properties (cross-test isolation, which comes from the static being scoped to a single test fn, vs cross-retry contamination, which is what the reset addresses). Reword to call those out separately. - The "mirrors `lodash.throttle(...)` in upstream's `remoteTarballFetcher.ts`" claim cited upstream code without a pinned permalink, breaking the same convention the guide states for upstream citations elsewhere. Add the pinned link to `remoteTarballFetcher.ts:143-144` at SHA `086c5e91e8`.
Per Copilot review on #374: the doc claimed every `LogEvent` variant is documented with both an upstream type permalink *and* an emit-site permalink. That holds for single-site channels (`Context`, `Summary`, `PackageImportMethod`, `FetchingProgress`) but not for `Stage` and `Progress`, which span the install lifecycle and fire from multiple call sites. Soften the claim: every variant pins the upstream type permalink; single-site channels also pin the emit; multi-site channels leave the porter to grep the upstream file for each status's call site.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…ull set Per Copilot review on #374: the doc said "the canonical list of channels lives in `LogEvent`", but `LogEvent` only contains the variants pacquet currently emits — it's not pnpm's complete channel set. The doc comment on `LogEvent` itself acknowledges this: "Variants are added as pacquet starts emitting them." Reword to: "the channels pacquet currently emits live in `LogEvent`", with an explicit note that the enum is *not* exhaustive and that porting a function whose upstream emits a channel `LogEvent` doesn't yet have is the trigger for adding a new variant. Keeps the existing "To add a new channel" instructions intact below.
Summary
Closes #346.
Adds a Reporter / log events section to
CODE_STYLE_GUIDE.mdplus a pointer inAGENTS.md's cardinal-rule section so the "match pnpm" mandate explicitly covers log emissions.The section walks a porter through the full lifecycle:
pnpm/pnpm(globalLogger,logger.debug({ name: ... }),streamParser.write(...)).LogEventis the channels pacquet currently emits, not pnpm's full set; the convention for adding a new variant when an upstream channel is missing (mirror the TS shape field-for-field, add a wire-shape unit test) lives in the section. Notes the type-vs-emit-site permalink distinction: single-site channels link both, multi-site channels (Stage,Progress) only pin the type.<R: Reporter>generic on every fn that emits, turbofish at the production entry point, install-scoped state via&AtomicU8-style parameters where dedup matters (link_file::log_method_oncecited as the example).static Mutex<Vec<LogEvent>>declared inside the test fn); sequence assertion viamatches!. Verify the test catches the regression by temporarily commenting out the emit.pnpm:fetching-progress in_progress'sContent-Length+>= 5 MB+ 500ms gate as the worked counter-example, with the pinned upstream permalink toremoteTarballFetcher.ts).pnpm:summaryinInstall::run. Shows the upstream permalink, the pacquet emit with code comment, and the test that pins the sequence.The doc is self-contained — no GitHub-issue back-references in the body — so a porter reads it linearly without context-switching.
Pure docs, no code changes.
Test plan
AGENTS.md's pointer links toCODE_STYLE_GUIDE.md#reporter--log-events; the heading lives at the matching slug.typosclean.cargo fmt/taplono-op (no Rust / TOML touched).References
pnpm:summaryemit cited in the section): feat(reporter): emit pnpm:summary at install end #355.