feat: introduce logger #367

araujogui · 2025-07-23T22:14:12Z

Description

Introduces a logger with multiple transports (console and github)

Validation

npx doc-kit generate -i doc/api/*.md -t web -o out/

Related Issues

Fixes #329

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format & node --run lint.
I've covered new added functionality with unit tests if necessary.

vercel · 2025-07-23T22:14:16Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
api-docs-tooling	✅ Ready (Inspect)	Visit Preview	Jul 25, 2025 8:48pm

Copilot

Pull Request Overview

This PR introduces a new logger system with multiple transports (console and GitHub) to replace the existing reporter system in the linter. The new logger provides structured logging with levels, timestamps, and formatted output across different environments.

Key changes:

Replaces the existing linter reporter system with a centralized logger infrastructure
Adds support for console and GitHub Actions transports with proper formatting
Updates CLI interface to use transport terminology instead of reporter terminology

Reviewed Changes

Copilot reviewed 19 out of 26 changed files in this pull request and generated 4 comments.

File	Description
src/logger/	New logger infrastructure with constants, utilities, transports, and singleton pattern
src/linter/index.mjs	Updated to use new logger system instead of reporters
src/linter/reporters/	Removed old reporter files
README.md	Updated CLI documentation to reflect transport terminology

Comments suppressed due to low confidence (1)

src/logger/tests/logger.test.mjs:195

This test is marked with it.only which means other tests in this file will be skipped during execution. This should be removed to ensure all tests run.

  it.only('should log error message', t => {

src/logger/__tests__/transports/github.test.mjs

src/logger/transports/github.mjs

avivkeller

Will this work on generators? Since, they are each offloaded to a desperate thread?

What if, and it may be far too complicated, we send the logging data back to the parent thread, which has the instantiated logger class, to then handle the incoming data with the appropriate transport, drppping the need to statically have a getInstance. (We could also re-instantiate the logger on the children, which may be simpler)

Like,

ThreadedLogger.error(...)

on("log", (group, level, message, etc) =>

src/logger/logger.mjs

src/logger/transports/index.mjs

ovflowd · 2025-07-23T23:07:04Z

Will this solution also work with progress bars?

src/logger/transports/github.mjs

ovflowd · 2025-07-23T23:10:07Z

src/logger/transports/console.mjs

+ * @param {import('../types').TransportContext} context
+ * @returns {void}
+ */
+export const console = ({


I wonder the compatibility of this for indeed work done by generators 🤔

Either generators will need to run their own logger instances individually if they want to log OR we only log high-level progress between each generator.

Although I'd wish the progress would be more granular:

for example instead of progress bar prgressing when each generator finishes, having it progress when each file gets updated is chef-kiss imo.

We could also send the logs to the parent, and have it to the processing, but that's more complex?

🤷 well worker_threads can communicate back and forth, Im fine with such comm.

ovflowd · 2025-07-23T23:10:39Z

src/logger/logger.mjs

We truly went the route of in-house logger?

As much as I like this, should maybe it be its own package then? I wonder the pros-cons of maintainin something like a logger in-house.

What do you mean? Do you want to create a new monorepo?

ovflowd · 2025-07-23T23:13:05Z

src/logger/index.mjs

+/**
+ * Singleton logger instance for consistent logging across the app.
+ */
+export const Logger = (() => {


I don't think you need to wrap this whole thing as a function. You can just move this code to top level.

Or at least, do:

export const Logger = () => {}; // <- raw export of the factory. export default Logger(); // <- default export of the singleton

What about the transport param in the init method?

src/logger/index.mjs

codecov · 2025-07-25T20:43:41Z

Codecov Report

❌ Patch coverage is 96.10516% with 40 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.17%. Comparing base (9436edd) to head (30f3407).
⚠️ Report is 8 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/linter/index.mjs	52.17%	11 Missing ⚠️
bin/commands/list.mjs	0.00%	9 Missing ⚠️
src/logger/index.mjs	85.45%	8 Missing ⚠️
bin/commands/lint.mjs	66.66%	4 Missing ⚠️
bin/commands/generate.mjs	25.00%	3 Missing ⚠️
bin/commands/interactive.mjs	0.00%	2 Missing ⚠️
bin/utils.mjs	50.00%	1 Missing ⚠️
src/logger/transports/github.mjs	97.61%	1 Missing ⚠️
src/logger/utils/colors.mjs	94.44%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #367      +/-   ##
==========================================
+ Coverage   70.80%   76.17%   +5.36%     
==========================================
  Files         127      127              
  Lines       11620    11945     +325     
  Branches      694      779      +85     
==========================================
+ Hits         8228     9099     +871     
+ Misses       3389     2843     -546     
  Partials        3        3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

avivkeller · 2025-07-25T21:20:05Z

@araujogui OOC is there a package that does this all for us?

araujogui · 2025-07-26T01:57:31Z

@araujogui OOC is there a package that does this all for us?

Well, pino is the best option I know

avivkeller · 2025-07-26T14:37:58Z

What about signale?

import signale from "signale";

signale.error("...");
signale.pending("...");

It looks like it should be easy to globally configure (https://github.com/klaudiosinani/signale#settingsobj). Each generator can have it's own scope

araujogui · 2025-07-28T20:59:30Z

What about signale?
import signale from "signale";

signale.error("...");
signale.pending("...");
It looks like it should be easy to globally configure (https://github.com/klaudiosinani/signale#settingsobj). Each generator can have it's own scope

It seems like a good option, but I would like the team to discuss this better before I invest more time into this pr. @nodejs/web-infra

araujogui added 10 commits July 23, 2025 17:36

feat: create logger module

d3aaa34

fix: correct return type

cd5f37b

feat: remove console calls

bdcc6d1

feat: replace linter reporters to transports

74d977b

feat: change default logger level

8ebee46

fix: init logger on list command

a016fe5

feat: add array logging

37d17ab

test: fix logger init

5116d00

chore: remove .tool-versions

13ce931

fix: missing logger init on generate command

d50a727

Copilot AI review requested due to automatic review settings July 23, 2025 22:14

araujogui requested a review from a team as a code owner July 23, 2025 22:14

Copilot AI reviewed Jul 23, 2025

View reviewed changes

vercel bot deployed to Preview July 23, 2025 22:16 View deployment

fix: github actions fn mapping

d06e927

vercel bot deployed to Preview July 23, 2025 22:54 View deployment

araujogui added 2 commits July 23, 2025 19:57

fix: use utc timezone

c43df87

test: remove it.only

7069bc4

avivkeller reviewed Jul 23, 2025

View reviewed changes

src/logger/logger.mjs Outdated Show resolved Hide resolved

src/logger/transports/index.mjs Outdated Show resolved Hide resolved

src/logger/transports/index.mjs Outdated Show resolved Hide resolved

vercel bot deployed to Preview July 23, 2025 23:02 View deployment

ovflowd reviewed Jul 23, 2025

View reviewed changes

src/logger/transports/github.mjs Outdated Show resolved Hide resolved

ovflowd reviewed Jul 23, 2025

View reviewed changes

src/logger/index.mjs Outdated Show resolved Hide resolved

araujogui added 3 commits July 25, 2025 17:38

refactor: use default exports

c0342e4

refactor: remove namespace gh import

512ab7a

refactor: remove @ts-check

d53ae56

vercel bot deployed to Preview July 25, 2025 20:44 View deployment

araujogui added 2 commits July 25, 2025 17:45

refactor: remove module check

ad540f1

test: fix imports

30f3407

vercel bot deployed to Preview July 25, 2025 20:48 View deployment

feat: introduce logger #367

Are you sure you want to change the base?

feat: introduce logger #367

Uh oh!

Conversation

araujogui commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Validation

Related Issues

Check List

Uh oh!

vercel bot commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avivkeller left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ovflowd commented Jul 23, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codecov bot commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

avivkeller commented Jul 25, 2025

Uh oh!

araujogui commented Jul 26, 2025

Uh oh!

avivkeller commented Jul 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

araujogui commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

araujogui commented Jul 23, 2025 •

edited

Loading

vercel bot commented Jul 23, 2025 •

edited

Loading

avivkeller left a comment •

edited

Loading

codecov bot commented Jul 25, 2025 •

edited

Loading

avivkeller commented Jul 26, 2025 •

edited

Loading

araujogui commented Jul 28, 2025 •

edited

Loading