feat(remark-lint): add (#8057)

* feat(remark-lint): add

1

* fixup!

* fixup!

* fixup!

Author: avivkeller

.github/workflows/publish-packages.yml

@@ -74,13 +74,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
 
@@ -125,8 +137,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.5.0",
+    "@node-core/remark-lint": "workspace:*",
     "@opennextjs/cloudflare": "^1.6.4",
     "@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/how-to-use-streams.md

@@ -815,6 +815,7 @@ This work is derived from content published by [Matteo Collina][] in [Platformat
 [`on('close')`]: https://nodejs.org/api/stream.html#event-close_1
 [`on('error')`]: https://nodejs.org/api/stream.html#event-error_1
 [`.read()`]: https://nodejs.org/docs/latest/api/stream.html#stream_readable_read_size
+[`_read()`]: https://nodejs.org/api/stream.html#readable_readsize
 [`.write()`]: https://nodejs.org/api/stream.html#stream_writable_write_chunk_encoding_callback
 [`_write`]: https://nodejs.org/api/stream.html#writable_writechunk-encoding-callback
 [`.end()`]: https://nodejs.org/api/stream.html#writableendchunk-encoding-callback

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.
 
@@ -337,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)
 
@@ -386,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
 
@@ -426,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
 
@@ -498,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
 

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

@@ -46,7 +46,7 @@ Pemberitahuan keamanan akan didistribusikan melalui metode berikut.
 
 ## Komentar tentang kebijakan ini
 
-Jika Anda memiliki saran tentang bagaimana proses ini dapat ditingkatkan, silakan kirimkan [permintaan penarikan](https://github.com/nodejs/nodejs.org) atau [ajukan masalah (https://github.com/nodejs/security -wg/issues/new) untuk didiskusikan.
+Jika Anda memiliki saran tentang bagaimana proses ini dapat ditingkatkan, silakan kirimkan [permintaan penarikan](https://github.com/nodejs/nodejs.org) atau [ajukan masalah](https://github.com/nodejs/security-wg/issues/new) untuk didiskusikan.
 
 ## Praktik Terbaik OpenSSF
 

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,123 @@
+# `@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"]
+}
+```
+
+Run remark to lint your Markdown files:
+
+```bash
+npx remark . --frail
+```
+
+## Configuration
+
+### Released Versions
+
+Some rules, such as `node-core:yaml-comments`, validate version references against known released Node.js versions. You can provide these using the `releasedVersions` option:
+
+```json
+{
+  "plugins": [
+    [
+      "@node-core/remark-lint",
+      {
+        "releasedVersions": ["v18.0.0", "v18.1.0", "v18.2.0", "v20.0.0"]
+      }
+    ]
+  ]
+}
+```
+
+For Node.js projects, these versions can be automatically generated [using `list-released-versions-from-changelogs.mjs`](https://github.com/nodejs/node/blob/main/tools/lint-md/list-released-versions-from-changelogs.mjs).
+
+If not specified, version-related rules will accept any valid SemVer format.
+
+## Rules
+
+### `node-core:duplicate-stability-nodes`
+
+Prevents redundant stability markers in nested sections.
+
+**Not allowed:**
+
+```markdown
+# Parent Section
+
+> Stability: 2 - Stable
+
+## Child Section
+
+> Stability: 2 - Stable <!-- Redundant! -->
+```
+
+### `node-core:hashed-self-reference`
+
+Ensures self-references use fragment-only links.
+
+**Allowed:**
+
+```markdown
+See the [Introduction](#introduction) section.
+```
+
+**Not allowed:**
+
+```markdown
+See the [Introduction](document.md#introduction) section.
+```
+
+### `node-core:ordered-references`
+
+Enforces alphabetical sorting of reference-style link definitions.
+
+**Allowed:**
+
+```markdown
+[api]: https://example.com/api
+[docs]: https://example.com/docs
+[info]: https://example.com/info
+```
+
+### `node-core:required-metadata`
+
+Requires essential metadata for documentation:
+
+- `llm_description`: A description for Large Language Models (can be inferred from first paragraph)
+- `introduced_in`: API introduction version
+
+Metadata can be provided in comments:
+
+```markdown
+<!-- llm_description= Utilities for working with file paths -->
+```
+
+### `node-core:yaml-comments`
+
+Enforces structure and content of YAML comment blocks:
+
+- `added`: An array of valid version strings
+- `napiVersion`: The N-API version
+- `deprecated`: An array of valid version strings
+- `removed`: An array of valid version strings
+- `changes`: An array of:
+  - `pr-url`: Pull request URL
+  - `commit`: Commit hash (only required for security fixes)
+  - `version`: Valid version string
+  - `description`: Change description
+
+All version references must be valid SemVer, or match the provided `releasedVersions`.

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,59 @@
+{
+  "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-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.1"
+  },
+  "devDependencies": {
+    "cross-env": "catalog:",
+    "dedent": "^1.6.0",
+    "globals": "^16.3.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5"
+  }
+}