archive/node
1
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2025-08-15 13:48:44 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

meta: enable jsdoc/check-tag-names rule

Browse source 
PR-URL: https://github.com/nodejs/node/pull/58521
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: LiviaMedeiros <livia@cirno.name>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
This commit is contained in:
Yagiz Nizipli 2025-07-18 05:28:21 -04:00 • committed by GitHub
parent 036b1fd66d
commit 0fd1ecded6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
86 changed files with 495 additions and 247 deletions
Download patch file Download diff file Expand all files Collapse all files

50
lib/internal/modules/cjs/loader.js
View file

@ -224,6 +224,7 @@ let statCache = null;
* Internal method to add tracing capabilities for Module._load.
*
* See more {@link Module._load}
* @returns {object}
*/
function wrapModuleLoad(request, parent, isMain) {
const logLabel = `[${parent?.id || ''}] [${request}]`;
@ -245,6 +246,7 @@ function wrapModuleLoad(request, parent, isMain) {
/**
* Get a path's properties, using an in-memory cache to minimize lookups.
* @param {string} filename Absolute path to the file
* @returns {number}
*/
function stat(filename) {
// Guard against internal bugs where a non-string filename is passed in by mistake.
@ -280,6 +282,7 @@ ObjectDefineProperty(Module, '_stat', {
* @param {Module} parent Module requiring the children
* @param {Module} child Module being required
* @param {boolean} scan Add the child to the parent's children if not already present
* @returns {void}
*/
function updateChildren(parent, child, scan) {
const children = parent?.children;
@ -291,6 +294,7 @@ function updateChildren(parent, child, scan) {
/**
* Tell the watch mode that a module was required.
* @param {string} filename Absolute path of the module
* @returns {void}
*/
function reportModuleToWatchMode(filename) {
if (shouldReportRequiredModules() && process.send) {
@ -302,6 +306,7 @@ function reportModuleToWatchMode(filename) {
* Tell the watch mode that a module was not found.
* @param {string} basePath The absolute path that errored
* @param {string[]} extensions The extensions that were tried
* @returns {void}
*/
function reportModuleNotFoundToWatchMode(basePath, extensions) {
if (shouldReportRequiredModules() && process.send) {
@ -313,6 +318,7 @@ function reportModuleNotFoundToWatchMode(basePath, extensions) {
* Create a new module instance.
* @param {string} id
* @param {Module} parent
* @returns {void}
*/
function Module(id = '', parent) {
this.id = id;
@ -329,7 +335,7 @@ function Module(id = '', parent) {
Module._cache = { __proto__: null };
/** @type {Record<string, string>} */
Module._pathCache = { __proto__: null };
/** @type {Record<string, (module: Module, filename: string) => void>} */
/** @type {{[key: string]: function(Module, string): void}} */
Module._extensions = { __proto__: null };
/** @type {string[]} */
let modulePaths = [];
@ -341,6 +347,7 @@ let patched = false;
/**
* Add the CommonJS wrapper around a module's source code.
* @param {string} script Module source code
* @returns {string}
*/
let wrap = function(script) { // eslint-disable-line func-style
return Module.wrapper[0] + script + Module.wrapper[1];
@ -396,6 +403,7 @@ ObjectDefineProperty(BuiltinModule.prototype, 'isPreloading', isPreloadingDesc);
/**
* Get the parent of the current module from our cache.
* @this {Module}
* @returns {object}
*/
function getModuleParent() {
return this[kModuleParent];
@ -405,6 +413,7 @@ function getModuleParent() {
* Set the parent of the current module in our cache.
* @this {Module}
* @param {Module} value
* @returns {void}
*/
function setModuleParent(value) {
this[kModuleParent] = value;
@ -434,6 +443,7 @@ Module.isBuiltin = BuiltinModule.isBuiltin;
/**
* Prepare to run CommonJS code.
* This function is called during pre-execution, before any user code is run.
* @returns {void}
*/
function initializeCJS() {
// This need to be done at runtime in case --expose-internals is set.
@ -484,6 +494,7 @@ ObjectDefineProperty(Module, '_readPackage', {
* @param {string[]} exts File extensions to try appending in order to resolve the file
* @param {boolean} isMain Whether the file is the main entry point of the app
* @param {string} originalPath The specifier passed to `require`
* @returns {any}
*/
function tryPackage(requestPath, exts, isMain, originalPath) {
const { main: pkg, pjsonPath } = _readPackage(requestPath);
@ -526,6 +537,7 @@ function tryPackage(requestPath, exts, isMain, originalPath) {
* `--preserve-symlinks-main` and `isMain` is true , keep symlinks intact, otherwise resolve to the absolute realpath.
* @param {string} requestPath The path to the file to load.
* @param {boolean} isMain Whether the file is the main module.
* @returns {string|undefined}
*/
function tryFile(requestPath, isMain) {
const rc = _stat(requestPath);
@ -541,6 +553,7 @@ function tryFile(requestPath, isMain) {
* @param {string} basePath The path and filename without extension
* @param {string[]} exts The extensions to try
* @param {boolean} isMain Whether the module is the main module
* @returns {string|false}
*/
function tryExtensions(basePath, exts, isMain) {
for (let i = 0; i < exts.length; i++) {
@ -556,6 +569,7 @@ function tryExtensions(basePath, exts, isMain) {
/**
* Find the longest (possibly multi-dot) extension registered in `Module._extensions`.
* @param {string} filename The filename to find the longest registered extension for.
* @returns {string}
*/
function findLongestRegisteredExtension(filename) {
const name = path.basename(filename);
@ -574,6 +588,7 @@ function findLongestRegisteredExtension(filename) {
/**
* Tries to get the absolute file path of the parent module.
* @param {Module} parent The parent module object.
* @returns {string|false|void}
*/
function trySelfParentPath(parent) {
if (!parent) { return false; }
@ -593,6 +608,8 @@ function trySelfParentPath(parent) {
* Attempt to resolve a module request using the parent module package metadata.
* @param {string} parentPath The path of the parent module
* @param {string} request The module request to resolve
* @param {unknown} conditions
* @returns {false|string}
*/
function trySelf(parentPath, request, conditions) {
if (!parentPath) { return false; }
@ -635,6 +652,8 @@ const EXPORTS_PATTERN = /^((?:@[^/\\%]+\/)?[^./\\%][^/\\%]*)(\/.*)?$/;
* Resolves the exports for a given module path and request.
* @param {string} nmPath The path to the module.
* @param {string} request The request for the module.
* @param {unknown} conditions
* @returns {undefined|string}
*/
function resolveExports(nmPath, request, conditions) {
// The implementation's behavior is meant to mirror resolution in ESM.
@ -785,6 +804,7 @@ if (isWindows) {
/**
* Get the paths to the `node_modules` folder for a given path.
* @param {string} from `__dirname` of the module
* @returns {string[]}
*/
Module._nodeModulePaths = function(from) {
// Guarantee that 'from' is absolute.
@ -837,6 +857,7 @@ if (isWindows) {
/**
* Get the paths to the `node_modules` folder for a given path.
* @param {string} from `__dirname` of the module
* @returns {string[]}
*/
Module._nodeModulePaths = function(from) {
// Guarantee that 'from' is absolute.
@ -883,6 +904,7 @@ if (isWindows) {
* Get the paths for module resolution.
* @param {string} request
* @param {Module} parent
* @returns {null|string[]}
*/
Module._resolveLookupPaths = function(request, parent) {
if (BuiltinModule.normalizeRequirableId(request)) {
@ -930,6 +952,7 @@ Module._resolveLookupPaths = function(request, parent) {
/**
* Emits a warning when a non-existent property of module exports is accessed inside a circular dependency.
* @param {string} prop The name of the non-existent property.
* @returns {void}
*/
function emitCircularRequireWarning(prop) {
process.emitWarning(
@ -966,6 +989,7 @@ const CircularRequirePrototypeWarningProxy = new Proxy({}, {
* If the exports object is a plain object, it is wrapped in a proxy that warns
* about circular dependencies.
* @param {Module} module The module instance
* @returns {object}
*/
function getExportsForCircularRequire(module) {
const requiredESM = module[kRequiredModuleSymbol];
@ -1068,8 +1092,8 @@ function resolveForCJSWithHooks(specifier, parent, isMain) {
}
/**
* @typedef {import('internal/modules/customization_hooks').ModuleLoadContext} ModuleLoadContext;
* @typedef {import('internal/modules/customization_hooks').ModuleLoadResult} ModuleLoadResult;
* @typedef {import('internal/modules/customization_hooks').ModuleLoadContext} ModuleLoadContext
* @typedef {import('internal/modules/customization_hooks').ModuleLoadResult} ModuleLoadResult
*/
/**
@ -1119,10 +1143,10 @@ function getDefaultLoad(url, filename) {
/**
* Load a specified builtin module, invoking load hooks if necessary.
* @param {string} id The module ID (without the node: prefix)
* @param {string} url The module URL (with the node: prefix)
* @param {string} url The module URL (with the node: prefix)
* @param {string} format Format from resolution.
* @returns {any} If there are no load hooks or the load hooks do not override the format of the
* builtin, load and return the exports of the builtin. Otherwise, return undefined.
* builtin, load and return the exports of the builtin. Otherwise, return undefined.
*/
function loadBuiltinWithHooks(id, url, format) {
if (loadHooks.length) {
@ -1151,6 +1175,7 @@ function loadBuiltinWithHooks(id, url, format) {
* @param {string} request Specifier of module to load via `require`
* @param {Module} parent Absolute path of the module importing the child
* @param {boolean} isMain Whether the module is the main entry point
* @returns {object}
*/
Module._load = function(request, parent, isMain) {
let relResolveCacheIdentifier;
@ -1281,6 +1306,7 @@ Module._load = function(request, parent, isMain) {
* @typedef {object} ResolveFilenameOptions
* @property {string[]} paths Paths to search for modules in
* @property {string[]} conditions Conditions used for resolution.
* @returns {void|string}
*/
Module._resolveFilename = function(request, parent, isMain, options) {
if (BuiltinModule.normalizeRequirableId(request)) {
@ -1378,6 +1404,7 @@ Module._resolveFilename = function(request, parent, isMain, options) {
* @param {string} pkgPath The path of the package.json file
* @throws {ERR_INVALID_MODULE_SPECIFIER} If the resolved module specifier contains encoded `/` or `\\` characters
* @throws {Error} If the module cannot be found
* @returns {void|string|undefined}
*/
function finalizeEsmResolution(resolved, parentPath, pkgPath) {
const { encodedSepRegEx } = require('internal/modules/esm/resolve');
@ -1390,14 +1417,14 @@ function finalizeEsmResolution(resolved, parentPath, pkgPath) {
if (actual) {
return actual;
}
const err = createEsmNotFoundErr(filename, pkgPath);
throw err;
throw createEsmNotFoundErr(filename, pkgPath);
}
/**
* Creates an error object for when a requested ES module cannot be found.
* @param {string} request The name of the requested module
* @param {string} [path] The path to the requested module
* @returns {Error}
*/
function createEsmNotFoundErr(request, path) {
// eslint-disable-next-line no-restricted-syntax
@ -1413,6 +1440,7 @@ function createEsmNotFoundErr(request, path) {
/**
* Given a file name, pass it to the proper extension handler.
* @param {string} filename The `require` specifier
* @returns {void}
*/
Module.prototype.load = function(filename) {
debug('load %j for module %j', filename, this.id);
@ -1436,6 +1464,7 @@ Module.prototype.load = function(filename) {
* Loads a module at the given file path. Returns that module's `exports` property.
* @param {string} id
* @throws {ERR_INVALID_ARG_TYPE} When `id` is not a string
* @returns {any}
*/
Module.prototype.require = function(id) {
validateString(id, 'id');
@ -1577,6 +1606,7 @@ function loadESMFromCJS(mod, filename, format, source) {
* @param {string} content The content of the file being loaded
* @param {Module|undefined} cjsModuleInstance The CommonJS loader instance
* @param {'commonjs'|undefined} format Intended format of the module.
* @returns {object}
*/
function wrapSafe(filename, content, cjsModuleInstance, format) {
assert(format !== 'module', 'ESM should be handled in loadESMFromCJS()');
@ -1636,7 +1666,8 @@ function wrapSafe(filename, content, cjsModuleInstance, format) {
* @param {string} content The source code of the module
* @param {string} filename The file path of the module
* @param {'module'|'commonjs'|'commonjs-typescript'|'module-typescript'|'typescript'} format
* Intended format of the module.
* Intended format of the module.
* @returns {any}
*/
Module.prototype._compile = function(content, filename, format) {
if (format === 'commonjs-typescript' || format === 'module-typescript' || format === 'typescript') {
@ -1843,6 +1874,7 @@ Module._extensions['.json'] = function(module, filename) {
* Native handler for `.node` files.
* @param {Module} module The module to compile
* @param {string} filename The file path of the module
* @returns {any}
*/
Module._extensions['.node'] = function(module, filename) {
// Be aware this doesn't use `content`
@ -1852,6 +1884,7 @@ Module._extensions['.node'] = function(module, filename) {
/**
* Creates a `require` function that can be used to load modules from the specified path.
* @param {string} filename The path to the module
* @returns {any}
*/
function createRequireFromPath(filename) {
// Allow a directory to be passed as the filename
@ -1878,6 +1911,7 @@ const createRequireError = 'must be a file URL object, file URL string, or ' +
* @param {string | URL} filename The path or URL to the module context for this `require`
* @throws {ERR_INVALID_ARG_VALUE} If `filename` is not a string or URL, or if it is a relative path that cannot be
* resolved to an absolute path.
* @returns {object}
*/
function createRequire(filename) {
let filepath;