feat(remark-lint): add

Author: avivkeller

.github/workflows/publish-packages.yml

@@ -72,13 +72,25 @@ jobs:
             # If a specific package is requested via workflow_dispatch, just publish that one
             echo "matrix={\"package\":[\"$PACKAGE\"]}" >> $GITHUB_OUTPUT
           else
-            # Otherwise, identify all packages with changes since the last commit
             CHANGED_PACKAGES=()
             for pkg in $(ls -d packages/*); do
               PKG_NAME=$(basename "$pkg")
-              # For manual runs, include all packages. For automatic runs, only include packages with changes
+              PKG_JSON="$pkg/package.json"
+
+              # Determine if the package has changed (or include all on manual trigger)
               if [ "$EVENT_NAME" == "workflow_dispatch" ] || ! git diff --quiet $COMMIT_SHA~1 $COMMIT_SHA -- "$pkg/"; then
-                CHANGED_PACKAGES+=("$PKG_NAME")
+                HAS_VERSION=$(jq 'has("version")' "$PKG_JSON")
+                if [ "$HAS_VERSION" == "false" ]; then
+                  # Include packages without version field
+                  CHANGED_PACKAGES+=("$PKG_NAME")
+                else
+                  # For packages with version field, include only if version changed
+                  OLD_VERSION=$(git show $COMMIT_SHA~1:$PKG_JSON | jq -r '.version')
+                  NEW_VERSION=$(jq -r '.version' "$PKG_JSON")
+                  if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
+                    CHANGED_PACKAGES+=("$PKG_NAME")
+                  fi
+                fi
               fi
             done
 
@@ -120,8 +132,12 @@ jobs:
         run: |
           # Install deps
           pnpm install --frozen-lockfile
-          # Create a unique version using the commit SHA as a prerelease identifier
-          npm version --no-git-tag-version 1.0.1-$COMMIT_SHA
+
+          HAS_VERSION=$(jq 'has("version")' package.json)
+          if [ "$HAS_VERSION" == "false" ]; then
+            # Only bump version if package has no version field
+            npm version --no-git-tag-version 1.0.1-$COMMIT_SHA
+          fi
 
           # Check if a custom publish script exists in package.json
           if jq -e '.scripts.publish' package.json > /dev/null; then

apps/site/.remarkrc.json

@@ -1,21 +1,3 @@
 {
-  "settings": {
-    "bullet": "-",
-    "resourceLink": true
-  },
-  "plugins": [
-    "remark-frontmatter",
-    "remark-preset-lint-node",
-    ["remark-gfm", false],
-    ["remark-lint-fenced-code-flag", false],
-    ["remark-lint-first-heading-level", false],
-    ["remark-lint-maximum-line-length", false],
-    ["remark-lint-no-file-name-articles", false],
-    ["remark-lint-no-literal-urls", false],
-    ["remark-lint-no-unused-definitions", false],
-    ["remark-lint-no-undefined-references", false],
-    ["remark-lint-prohibited-strings", false],
-    ["remark-lint-unordered-list-marker-style", "-"],
-    ["remark-preset-lint-node/remark-lint-nodejs-links.js", false]
-  ]
+  "plugins": ["remark-frontmatter", "@node-core/remark-lint"]
 }

apps/site/package.json

@@ -82,6 +82,7 @@
     "@eslint/eslintrc": "~3.3.1",
     "@flarelabs-net/wrangler-build-time-fs-assets-polyfilling": "^0.0.1",
     "@next/eslint-plugin-next": "15.4.4",
+    "@node-core/remark-lint": "workspace:*",
     "@opennextjs/cloudflare": "^1.6.2",
     "@playwright/test": "^1.54.1",
     "@testing-library/user-event": "~14.6.1",
@@ -95,17 +96,7 @@
     "global-jsdom": "^26.0.0",
     "handlebars": "4.7.8",
     "jsdom": "^26.0.0",
-    "remark-frontmatter": "5.0.0",
-    "remark-lint-fenced-code-flag": "^4.2.0",
-    "remark-lint-first-heading-level": "^4.0.1",
-    "remark-lint-maximum-line-length": "^4.1.1",
-    "remark-lint-no-file-name-articles": "^3.0.1",
-    "remark-lint-no-literal-urls": "^4.0.1",
-    "remark-lint-no-undefined-references": "^5.0.2",
-    "remark-lint-no-unused-definitions": "^4.0.2",
-    "remark-lint-prohibited-strings": "^4.0.0",
-    "remark-lint-unordered-list-marker-style": "^4.0.1",
-    "remark-preset-lint-node": "5.1.2",
+    "remark-frontmatter": "^5.0.0",
     "stylelint": "16.23.0",
     "stylelint-config-standard": "39.0.0",
     "stylelint-order": "7.0.0",

apps/site/pages/en/learn/modules/publishing-a-package.mdx

@@ -6,7 +6,7 @@ authors: JakobJingleheimer
 
 # Publishing a package
 
-All the provided `package.json` configurations (not specifically marked “does not work”) work in Node.js 12.22.x (v12 latest, the oldest supported line) and 17.2.0 (current latest at the time)[^1], and for grins, with webpack 5.53.0 and 5.63.0 respectively. These are available: [JakobJingleheimer/nodejs-module-config-examples](https://github.com/JakobJingleheimer/nodejs-module-config-examples).
+All the provided `package.json` configurations (not specifically marked “does not work”) work in Node.js 12.22.x (v12 latest, the oldest supported line) and 17.2.0 (current latest at the time)\[^1], and for grins, with webpack 5.53.0 and 5.63.0 respectively. These are available: [JakobJingleheimer/nodejs-module-config-examples](https://github.com/JakobJingleheimer/nodejs-module-config-examples).
 
 For curious cats, [How did we get here](#how-did-we-get-here) and [Down the rabbit-hole](#down-the-rabbit-hole) provide background and deeper explanations.
 
@@ -36,19 +36,23 @@ There are other options available, mostly for historical purposes.
       <td>ESM: consumers <code>import</code> your package</td>
       <td><a href="#cjs-source-and-only-esm-distribution">CJS source and only ESM distribution</a></td>
     </tr>
+
     <tr>
       <td>CJS & ESM: consumers either <code>require()</code> or <code>import</code> your package</td>
       <td><a href="#cjs-source-and-both-cjs-amp-esm-distribution">CJS source and both CJS & ESM distribution</a></td>
     </tr>
+
     <tr>
       <td rowSpan="2">ESM source code using <code>import</code></td>
       <td>CJS: consumers <code>require()</code> your package (and you use top-level <code>await</code>)</td>
       <td><a href="#esm-source-with-only-cjs-distribution">ESM source with only CJS distribution</a></td>
     </tr>
+
     <tr>
       <td>CJS & ESM: consumers either <code>require()</code> or <code>import</code> your package</td>
       <td><a href="#esm-source-and-both-cjs-amp-esm-distribution">ESM source and both CJS & ESM distribution</a></td>
     </tr>
+
   </tbody>
 </table>
 
@@ -333,7 +337,7 @@ We're not in Kansas anymore, Toto.
 
 The configurations (there are 2 options) are nearly the same as [ESM source and both CJS & ESM distribution](#esm-source-and-both-cjs-amp-esm-distribution), just exclude `packageJson.exports.import`.
 
-💡 Using `"type": "module"`[^2] paired with the `.cjs` file extension (for commonjs files) yields best results. For more information on why, see [Down the rabbit-hole](#down-the-rabbit-hole) and [Gotchas](#gotchas) below.
+💡 Using `"type": "module"`\[^2] paired with the `.cjs` file extension (for commonjs files) yields best results. For more information on why, see [Down the rabbit-hole](#down-the-rabbit-hole) and [Gotchas](#gotchas) below.
 
 **Working example**: [esm-with-cjs-distro](https://github.com/JakobJingleheimer/nodejs-module-config-examples/tree/main/packages/esm/cjs-distro)
 
@@ -382,7 +386,7 @@ If your files explicitly _all_ use `.cjs` and/or `.mjs` file extensions (none us
 }
 ```
 
-💡 Using `"type": "module"`[^2] paired with the `.cjs` file extension (for commonjs files) yields best results. For more information on why, see [Down the rabbit-hole](#down-the-rabbit-hole) and [Gotchas](#gotchas) below.
+💡 Using `"type": "module"`\[^2] paired with the `.cjs` file extension (for commonjs files) yields best results. For more information on why, see [Down the rabbit-hole](#down-the-rabbit-hole) and [Gotchas](#gotchas) below.
 
 #### Publish a CJS distribution with an ESM wrapper
 
@@ -422,7 +426,7 @@ This is also almost identical to the [CJS source and dual distribution using an
 }
 ```
 
-💡 Using `"type": "module"`[^2] paired with the `.cjs` file extension (for commonjs files) yields best results. For more information on why, see [Down the rabbit-hole](#down-the-rabbit-hole) and [Gotchas](#gotchas) below.
+💡 Using `"type": "module"`\[^2] paired with the `.cjs` file extension (for commonjs files) yields best results. For more information on why, see [Down the rabbit-hole](#down-the-rabbit-hole) and [Gotchas](#gotchas) below.
 
 #### Publish both full CJS & ESM distributions
 
@@ -494,7 +498,7 @@ Alternatively, you can use `"default"` and `"node"` keys, which are less counter
 }
 ```
 
-💡 Using `"type": "module"`[^2] paired with the `.cjs` file extension (for commonjs files) yields best results. For more information on why, see [Down the rabbit-hole](#down-the-rabbit-hole) and [Gotchas](#gotchas) below.
+💡 Using `"type": "module"`\[^2] paired with the `.cjs` file extension (for commonjs files) yields best results. For more information on why, see [Down the rabbit-hole](#down-the-rabbit-hole) and [Gotchas](#gotchas) below.
 
 ##### Use the `.mjs` (or equivalent) file extension for all source code files
 
@@ -523,9 +527,11 @@ The `"engines"` field provides both a human-friendly and a machine-friendly indi
 Specifically in relation to Node.js, there are 4 problems to solve:
 
 - Determining format of source code files (author running their own code)
+
 - Determining format of distribution files (code consumers will receive)
 
 - Publicising distribution code for when it is `require()`’d (consumer expects CJS)
+
 - Publicising distribution code for when it is `import`’d (consumer probably wants ESM)
 
 ⚠️ The first 2 are **independent** of the last 2.
@@ -592,6 +598,6 @@ Excluding `"type": "module"` produces the opposite problem:
 
 This does not work because `packageJson.exports["."].import` will get interpreted as CJS (but it’s actually ESM).
 
-[^1]: There was a bug in Node.js v13.0–13.6 where `packageJson.exports["."]` had to be an array with verbose config options as the first item (as an object) and the “default” as the second item (as a string). See [nodejs/modules#446](https://github.com/nodejs/modules/issues/446).
+\[^1]: There was a bug in Node.js v13.0–13.6 where `packageJson.exports["."]` had to be an array with verbose config options as the first item (as an object) and the “default” as the second item (as a string). See [nodejs/modules#446](https://github.com/nodejs/modules/issues/446).
 
-[^2]: The `"type"` field in package.json changes what the `.js` file extension means, similar to to an [HTML script element’s type attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-type).
+\[^2]: The `"type"` field in package.json changes what the `.js` file extension means, similar to to an [HTML script element’s type attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-type).

apps/site/pages/fr/about/security-reporting.mdx

@@ -85,4 +85,4 @@ Si vous avez des suggestions sur la façon dont ce processus pourrait être amé
   />
 </a>
 
-Le [badge des meilleures pratiques] de l'Open Source Security Foundation (OpenSSF) (https://github.com/coreinfrastructure/best-practices-badge) est un moyen pour les projets de logiciels libres et open source (FLOSS) de montrer qu'ils suivent les meilleures pratiques. Les projets peuvent volontairement auto-certifier la manière dont ils suivent chaque meilleure pratique. Les utilisateurs du badge peuvent rapidement déterminer quels sont les projets FLOSS qui suivent les meilleures pratiques et qui sont donc plus susceptibles de produire des logiciels sécurisés de meilleure qualité.
+Le \[badge des meilleures pratiques] de l'Open Source Security Foundation (OpenSSF) (https://github.com/coreinfrastructure/best-practices-badge) est un moyen pour les projets de logiciels libres et open source (FLOSS) de montrer qu'ils suivent les meilleures pratiques. Les projets peuvent volontairement auto-certifier la manière dont ils suivent chaque meilleure pratique. Les utilisateurs du badge peuvent rapidement déterminer quels sont les projets FLOSS qui suivent les meilleures pratiques et qui sont donc plus susceptibles de produire des logiciels sécurisés de meilleure qualité.

packages/remark-lint/.lintstagedrc.json

@@ -0,0 +1,4 @@
+{
+  "**/*.{js,mjs,ts,tsx,md,mdx}": ["prettier --check --write", "eslint --fix"],
+  "**/*.{json,yml}": ["prettier --check --write"]
+}

packages/remark-lint/README.md

@@ -0,0 +1,39 @@
+# `@node-core/remark-lint`
+
+A [`remark-lint`](https://github.com/remarkjs/remark-lint) plugin with configurations tailored to the documentation and contribution standards of the [Node.js GitHub Organization](https://github.com/nodejs).
+
+## Installation
+
+```bash
+npm install --save-dev @node-core/remark-lint
+```
+
+## Usage
+
+Add the plugin to your `.remarkrc` or `remark.config.js`:
+
+```json
+{
+  "plugins": ["@node-core/remark-lint"]
+}
+```
+
+You can then run `remark` over your markdown files:
+
+```bash
+npx remark . --frail
+```
+
+## Settings
+
+### `NODE_RELEASED_VERSIONS`
+
+Some lint rules (such as `node-core:yaml-comments`) require knowledge of released Node.js versions to validate version references.
+
+You can provide these using the `NODE_RELEASED_VERSIONS` environment variable:
+
+```bash
+NODE_RELEASED_VERSIONS=20.12.0,18.19.1,16.20.2 npx remark .
+```
+
+If not set, version-related rules will accept any valid SemVer.

packages/remark-lint/eslint.config.js

@@ -0,0 +1,17 @@
+import globals from 'globals';
+
+import baseConfig from '../../eslint.config.js';
+
+export default [
+  ...baseConfig,
+  {
+    languageOptions: {
+      globals: globals.nodeBuiltin,
+      parserOptions: {
+        // Allow nullish syntax (i.e. "?." or "??"),
+        // and top-level await
+        ecmaVersion: 'latest',
+      },
+    },
+  },
+];

packages/remark-lint/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@node-core/remark-lint",
+  "type": "module",
+  "version": "1.0.0",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./api": "./src/api.mjs"
+  },
+  "scripts": {
+    "lint": "node --run lint:js",
+    "lint:fix": "node --run lint:js:fix",
+    "lint:js": "eslint \"**/*.mjs\"",
+    "lint:js:fix": "node --run lint:js -- --fix",
+    "test": "node --run test:unit",
+    "test:unit": "cross-env NODE_NO_WARNINGS=1 node --experimental-test-coverage --test \"**/*.test.mjs\""
+  },
+  "dependencies": {
+    "remark-gfm": "~4.0.1",
+    "remark-lint-blockquote-indentation": "^4.0.1",
+    "remark-lint-checkbox-character-style": "^5.0.1",
+    "remark-lint-checkbox-content-indent": "^5.0.1",
+    "remark-lint-code-block-style": "^4.0.1",
+    "remark-lint-definition-spacing": "^4.0.1",
+    "remark-lint-fenced-code-flag": "^4.2.0",
+    "remark-lint-fenced-code-marker": "^4.0.1",
+    "remark-lint-file-extension": "^3.0.1",
+    "remark-lint-final-definition": "^4.0.2",
+    "remark-lint-heading-style": "^4.0.1",
+    "remark-lint-maximum-line-length": "^4.1.1",
+    "remark-lint-no-consecutive-blank-lines": "^5.0.1",
+    "remark-lint-no-file-name-consecutive-dashes": "^3.0.1",
+    "remark-lint-no-file-name-outer-dashes": "^3.0.1",
+    "remark-lint-no-heading-indent": "^5.0.1",
+    "remark-lint-no-literal-urls": "^4.0.1",
+    "remark-lint-no-multiple-toplevel-headings": "^4.0.1",
+    "remark-lint-no-shell-dollars": "^4.0.1",
+    "remark-lint-no-table-indentation": "^5.0.1",
+    "remark-lint-no-tabs": "^4.0.1",
+    "remark-lint-no-trailing-spaces": "^3.0.2",
+    "remark-lint-no-unused-definitions": "^4.0.2",
+    "remark-lint-prohibited-strings": "^4.0.0",
+    "remark-lint-rule-style": "^4.0.1",
+    "remark-lint-strong-marker": "^4.0.1",
+    "remark-lint-table-cell-padding": "^5.1.1",
+    "remark-lint-table-pipes": "^5.0.1",
+    "remark-lint-unordered-list-marker-style": "^4.0.1",
+    "remark-preset-lint-recommended": "^7.0.1",
+    "semver": "~7.7.2",
+    "unified-lint-rule": "^3.0.1",
+    "unist-util-visit": "^5.0.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "cross-env": "catalog:",
+    "dedent": "^1.6.0",
+    "globals": "^16.3.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5"
+  }
+}

packages/remark-lint/src/api.mjs

@@ -0,0 +1,55 @@
+import remarkGfm from 'remark-gfm';
+import remarkLintFencedCodeFlag from 'remark-lint-fenced-code-flag';
+import remarkLintMaximumLineLength from 'remark-lint-maximum-line-length';
+import remarkLintNoUnusedDefinitions from 'remark-lint-no-unused-definitions';
+import remarkLintProhibitedStrings from 'remark-lint-prohibited-strings';
+import remarkLintUnorderedListMarkerStyle from 'remark-lint-unordered-list-marker-style';
+
+import basePreset from './index.mjs';
+import duplicateStabilityNodes from './rules/duplicate-stability-nodes.mjs';
+import hashedSelfReference from './rules/hashed-self-reference.mjs';
+import orderedReferences from './rules/ordered-references.mjs';
+import requiredMetadata from './rules/required-metadata.mjs';
+import yamlComments from './rules/yaml/index.mjs';
+
+export default {
+  settings: {
+    ...basePreset.settings,
+    bullet: '*',
+  },
+  plugins: [
+    remarkGfm,
+    ...basePreset.plugins,
+    duplicateStabilityNodes,
+    yamlComments,
+    hashedSelfReference,
+    orderedReferences,
+    requiredMetadata,
+    remarkLintNoUnusedDefinitions,
+    [remarkLintFencedCodeFlag, { allowEmpty: false }],
+    [remarkLintMaximumLineLength, 120],
+    [remarkLintUnorderedListMarkerStyle, '*'],
+    [
+      remarkLintProhibitedStrings,
+      [
+        { yes: 'End-of-Life' },
+        { no: 'filesystem', yes: 'file system' },
+        { yes: 'GitHub' },
+        { no: 'hostname', yes: 'host name' },
+        { yes: 'JavaScript' },
+        { no: '[Ll]ong[ -][Tt]erm [Ss]upport', yes: 'Long Term Support' },
+        { no: 'Node', yes: 'Node.js', ignoreNextTo: '-API' },
+        { yes: 'Node.js' },
+        { no: 'Node[Jj][Ss]', yes: 'Node.js' },
+        { no: "Node\\.js's?", yes: 'the Node.js' },
+        { no: '[Nn]ote that', yes: '<nothing>' },
+        { yes: 'RFC' },
+        { no: '[Rr][Ff][Cc]\\d+', yes: 'RFC <number>' },
+        { yes: 'TypeScript' },
+        { yes: 'Unix' },
+        { yes: 'Valgrind' },
+        { yes: 'V8' },
+      ],
+    ],
+  ],
+};