Skip to content
This repository was archived by the owner on May 14, 2026. It is now read-only.

docs(agents): document how to add log events when porting from pnpm#374

Merged
zkochan merged 6 commits into
mainfrom
docs/agents-reporter-convention
May 2, 2026
Merged

docs(agents): document how to add log events when porting from pnpm#374
zkochan merged 6 commits into
mainfrom
docs/agents-reporter-convention

Conversation

@zkochan

@zkochan zkochan commented May 2, 2026

Copy link
Copy Markdown
Member

Summary

Closes #346.

Adds a Reporter / log events section to CODE_STYLE_GUIDE.md plus a pointer in AGENTS.md's cardinal-rule section so the "match pnpm" mandate explicitly covers log emissions.

The section walks a porter through the full lifecycle:

  • Finding the upstream emit — three call shapes to grep for in pnpm/pnpm (globalLogger, logger.debug({ name: ... }), streamParser.write(...)).
  • Channel mappingLogEvent is 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.
  • Threading the reporter<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_once cited as the example).
  • 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 reporter (unit-struct + static Mutex<Vec<LogEvent>> declared inside the test fn); sequence assertion via matches!. Verify the test catches the regression by temporarily commenting out the emit.
  • What not to do — don't reformat upstream messages, don't invent channels, don't change emit granularity (cites pnpm:fetching-progress in_progress's Content-Length + >= 5 MB + 500ms gate as the worked counter-example, with the pinned upstream permalink to remoteTarballFetcher.ts).
  • Worked examplepnpm:summary in Install::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

  • Anchors resolve: AGENTS.md's pointer links to CODE_STYLE_GUIDE.md#reporter--log-events; the heading lives at the matching slug.
  • typos clean.
  • cargo fmt / taplo no-op (no Rust / TOML touched).

References

Copilot AI review requested due to automatic review settings May 2, 2026 20:56
@coderabbitai

coderabbitai Bot commented May 2, 2026

Copy link
Copy Markdown

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Added 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.

Changes

Documentation: Log Event Porting Guidance

Layer / File(s) Summary
Cardinal Rule
AGENTS.md
Added item requiring pnpm:<channel> log emissions routed via the logger/stream pipeline to match pnpm's call site, payload, and ordering; references the style guide reporter section.
Data Shape / Canonical Mapping
CODE_STYLE_GUIDE.md (lines 604–624)
Defines canonical mapping of LogEvent variants to pnpm:<channel> via #[serde(rename = "pnpm:<channel>")] and requires payload-field parity with upstream TypeScript shapes; documents how to locate upstream emit call sites.
Core Convention
CODE_STYLE_GUIDE.md (lines 625–667)
Specifies threading convention using a generic R: Reporter through ported functions and calling R::emit(...), with turbofish/monomorphization guidance for production entry points.
Placement & Ordering
CODE_STYLE_GUIDE.md (lines 668–670)
Prescribes placing emits adjacent to upstream side-effect sites to preserve pnpm ordering and requires pinned upstream permalink citations next to each emit.
Tests / Prohibitions / Example
CODE_STYLE_GUIDE.md (lines 671–731)
Adds a per-test recording-reporter pattern (static Mutex<Vec<LogEvent>>) to assert exact emitted sequences; lists prohibitions (no reformatting of upstream messages, no inventing channels, no changing emission granularity); includes a worked example (pnpm:summary emitted from Install::run after importing_done) and points to the sequence-pinning test location.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

Possibly related PRs

Suggested reviewers

  • KSXGitHub

Poem

🐰 I hop through logs both near and far,
Mapping channels like a tiny star,
Emit in order, keep payload true,
Thread the Reporter, tests in view,
Pacquet echoes pnpm — a faithful queue!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: documenting how to add log events when porting code from pnpm.
Linked Issues check ✅ Passed The pull request fully addresses all coding and documentation requirements from issue #346: identifying upstream emissions patterns, channel mapping guidance, threading convention, emit placement rules, testing strategy, prohibitions, and a worked example with upstream permalink.
Out of Scope Changes check ✅ Passed All changes are directly aligned with the scope defined in issue #346—pure documentation additions to AGENTS.md and CODE_STYLE_GUIDE.md with no code modifications.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/agents-reporter-convention

Comment @coderabbitai help to get the list of available commands and usage tips.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.md describing how to find upstream emits, map channels to LogEvent, thread R: 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.

Comment thread CODE_STYLE_GUIDE.md Outdated
Comment thread CODE_STYLE_GUIDE.md Outdated
Comment thread CODE_STYLE_GUIDE.md Outdated
zkochan added 2 commits May 2, 2026 23:10
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.
@zkochan zkochan force-pushed the docs/agents-reporter-convention branch from 479dec8 to 4e7cc6c Compare May 2, 2026 21:11
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".
Copilot AI review requested due to automatic review settings May 2, 2026 21:15

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (2)
CODE_STYLE_GUIDE.md (2)

668-701: ⚡ Quick win

Soften 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 the static is 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 to remoteTarballFetcher.ts reference (matches guide's established pattern).

This section correctly documents the throttling and size-gate behavior, but it references upstream's remoteTarballFetcher.ts and lodash.throttle(..., 500) without a pinned permalink. The guide already establishes the pattern for citing upstream code (lines 654, 659, 713–727) using pinned SHAs like https://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_SIZE and IN_PROGRESS_THROTTLE at crates/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

📥 Commits

Reviewing files that changed from the base of the PR and between 479dec8 and 4e7cc6c.

📒 Files selected for processing (2)
  • AGENTS.md
  • CODE_STYLE_GUIDE.md
✅ Files skipped from review due to trivial changes (1)
  • AGENTS.md

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread CODE_STYLE_GUIDE.md Outdated
zkochan added 2 commits May 2, 2026 23:18
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.
Copilot AI review requested due to automatic review settings May 2, 2026 21:19

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread CODE_STYLE_GUIDE.md Outdated
…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.
@zkochan zkochan enabled auto-merge (squash) May 2, 2026 21:52
@zkochan zkochan disabled auto-merge May 2, 2026 21:52
@zkochan zkochan merged commit 2c80ba6 into main May 2, 2026
1 check passed
@zkochan zkochan deleted the docs/agents-reporter-convention branch May 2, 2026 21:52
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(agents): document how to add log events when porting from pnpm

2 participants