Merge branch 'main' into feat/standard-yaml-support

Author: moshams272

.github/workflows/auto-merge.yml

@@ -22,4 +22,4 @@ jobs:
 
       - uses: nodejs/web-team/actions/auto-merge-prs@b087df186d25f8792fb85cc7794f68718726b8ee
         with:
-          merge-method: queue
+          merge-method: squash

.github/workflows/publish.yml

@@ -95,5 +95,5 @@ jobs:
             :bust_in_silhouette: *Published by*: ${{ github.triggering_actor }}
             :octocat: *Commit*: <https://github.com/${{ github.repository }}/commit/${{ env.COMMIT_SHA }}|${{ env.COMMIT_SHA }}>
           SLACK_USERNAME: nodejs-bot
-          SLACK_CHANNEL: nodejs-web-infra
+          SLACK_CHANNEL: nodejs-web-infra-alerts
           SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }}

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@node-core/doc-kit",
   "type": "module",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nodejs/doc-kit.git"
@@ -57,6 +57,7 @@
     "estree-util-to-js": "^2.0.0",
     "estree-util-visit": "^2.0.0",
     "github-slugger": "^2.0.0",
+    "glob-parent": "^6.0.2",
     "globals": "^17.3.0",
     "hast-util-to-string": "^3.0.1",
     "hastscript": "^9.0.1",
@@ -85,7 +86,6 @@
     "unist-util-remove": "^4.0.0",
     "unist-util-select": "^5.1.0",
     "unist-util-visit": "^5.1.0",
-    "vfile": "^6.0.3",
     "yaml": "^2.8.2"
   }
 }

package.json

@@ -1,6 +1,6 @@
 'use strict';
 
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { visit } from 'unist-util-visit';
@@ -13,6 +13,7 @@ import {
   normalizeSectionName,
 } from './utils/section.mjs';
 import getConfig from '../../utils/configuration/index.mjs';
+import { writeFile } from '../../utils/file.mjs';
 
 /**
  * Generates a file list from code blocks.

src/generators/addon-verify/generate.mjs

@@ -6,7 +6,8 @@ The `api-links` generator creates a mapping of publicly accessible functions to
 
 The `api-links` generator accepts the following configuration options:
 
-| Name     | Type      | Default                 | Description                                         |
-| -------- | --------- | ----------------------- | --------------------------------------------------- |
-| `output` | `string`  | -                       | The directory where `apilinks.json` will be written |
-| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON                   |
+| Name        | Type      | Default                              | Description                                         |
+| ----------- | --------- | ------------------------------------ | --------------------------------------------------- |
+| `output`    | `string`  | -                                    | The directory where `apilinks.json` will be written |
+| `sourceURL` | `string`  | `'${GITHUB_BLOB_URL}lib/{fileName}'` | URL template for linking to source files            |
+| `minify`    | `boolean` | Inherited from `global`              | Whether to minify the output JSON                   |

src/generators/api-links/README.md

@@ -1,16 +1,13 @@
 'use strict';
 
-import { writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 
 import { checkIndirectReferences } from './utils/checkIndirectReferences.mjs';
 import { extractExports } from './utils/extractExports.mjs';
 import { findDefinitions } from './utils/findDefinitions.mjs';
 import getConfig from '../../utils/configuration/index.mjs';
-import {
-  GITHUB_BLOB_URL,
-  populate,
-} from '../../utils/configuration/templates.mjs';
+import { populate } from '../../utils/configuration/templates.mjs';
+import { withExt, writeFile } from '../../utils/file.mjs';
 
 /**
  * Generates the `apilinks.json` file.
@@ -33,16 +30,19 @@ export async function generate(input) {
      */
     const nameToLineNumberMap = {};
 
-    // `http.js` -> `http`
-    const baseName = basename(program.path, '.js');
+    const fileName = basename(program.path);
+    const baseName = withExt(fileName);
 
     const exports = extractExports(program, baseName, nameToLineNumberMap);
 
     findDefinitions(program, baseName, nameToLineNumberMap, exports);
 
     checkIndirectReferences(program, exports, nameToLineNumberMap);
 
-    const fullGitUrl = `${populate(GITHUB_BLOB_URL, config)}lib/${baseName}.js`;
+    const fullGitUrl = populate(config.sourceURL, {
+      ...config,
+      fileName,
+    });
 
     // Add the exports we found in this program to our output
     Object.keys(nameToLineNumberMap).forEach(key => {

src/generators/api-links/generate.mjs

@@ -1,5 +1,6 @@
 'use strict';
 
+import { GITHUB_BLOB_URL } from '../../utils/configuration/templates.mjs';
 import { createLazyGenerator } from '../../utils/generators.mjs';
 
 /**
@@ -23,4 +24,8 @@ export default createLazyGenerator({
   // Unlike the rest of the generators, this utilizes Javascript sources being
   // passed into the input field rather than Markdown.
   dependsOn: 'ast-js',
+
+  defaultConfiguration: {
+    sourceURL: `${GITHUB_BLOB_URL}lib/{fileName}`,
+  },
 });

src/generators/api-links/index.mjs

@@ -5,6 +5,8 @@ export interface ProgramExports {
 }
 
 export type Generator = GeneratorMetadata<
-  {},
+  {
+    sourceURL: string;
+  },
   Generate<undefined, Promise<Record<string, string>>>
 >;

src/generators/api-links/types.d.ts

@@ -1,11 +1,11 @@
 'use strict';
 
-import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { remove } from 'unist-util-remove';
 
 import getConfig from '../../utils/configuration/index.mjs';
+import { writeFile } from '../../utils/file.mjs';
 import { UNIST } from '../../utils/queries/index.mjs';
 
 /**