API surface regression test to catch unintended exports

[LiviaMedeiros]

What is the problem this feature will solve?

Sometimes we have internal-only methods/constants/classes unintentionally exposed to userland. After being exposed for a long enough time, they inevitably become used by someone, leaving Node.js with a choice: either cause breakage in userland, or keep awkward deprecated/legacy code for years.

What is the feature you are proposing to solve the problem?

• Fixture with a list of all currently exposed properties (flat array of strings like fs/promises.readFile, dns.lookup.[customPromisifyArgs].1, etc.)
• Test that recursively goes through module.builtinModules, builds the list, and asserts equality against the fixture
• Script that would overwrite the fixture with current list using ./out/Release/node ./tools/update-api-surface.mjs

This way, the test would fail if something unintended happened, and fixture updates would clearly indicate the additions to public API. This is not 100% robust because it won't include prototypes of some objects created in runtime (for example, fs.Stats is accessible while fs.BigIntStats is not), but it would catch most of exposures.

What alternatives have you considered?

Tool (e.g. GitHub Actions workflow) that would compare public API surface against base commit and somehow report the changes if any.

[github-actions[bot]]

There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the https://github.com/nodejs/node/labels/never-stale label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment. For more information on how the project manages feature requests, please consult the feature request management document.