Skip to content

Commit 0c89552

Browse files
avivkelleravivkeller
committed
feat(remark-lint): add
1
1 parent 5be4099 commit 0c89552

30 files changed

+1590
-139
lines changed

‎.github/workflows/publish-packages.yml

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -74,13 +74,25 @@ jobs:
7474
# If a specific package is requested via workflow_dispatch, just publish that one
7575
echo "matrix={\"package\":[\"$PACKAGE\"]}" >> $GITHUB_OUTPUT
7676
else
77-
# Otherwise, identify all packages with changes since the last commit
7877
CHANGED_PACKAGES=()
7978
for pkg in $(ls -d packages/*); do
8079
PKG_NAME=$(basename "$pkg")
81-
# For manual runs, include all packages. For automatic runs, only include packages with changes
80+
PKG_JSON="$pkg/package.json"
81+
82+
# Determine if the package has changed (or include all on manual trigger)
8283
if [ "$EVENT_NAME" == "workflow_dispatch" ] || ! git diff --quiet $COMMIT_SHA~1 $COMMIT_SHA -- "$pkg/"; then
83-
CHANGED_PACKAGES+=("$PKG_NAME")
84+
HAS_VERSION=$(jq 'has("version")' "$PKG_JSON")
85+
if [ "$HAS_VERSION" == "false" ]; then
86+
# Include packages without version field
87+
CHANGED_PACKAGES+=("$PKG_NAME")
88+
else
89+
# For packages with version field, include only if version changed
90+
OLD_VERSION=$(git show $COMMIT_SHA~1:$PKG_JSON | jq -r '.version')
91+
NEW_VERSION=$(jq -r '.version' "$PKG_JSON")
92+
if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
93+
CHANGED_PACKAGES+=("$PKG_NAME")
94+
fi
95+
fi
8496
fi
8597
done
8698
@@ -125,8 +137,12 @@ jobs:
125137
run: |
126138
# Install deps
127139
pnpm install --frozen-lockfile
128-
# Create a unique version using the commit SHA as a prerelease identifier
129-
npm version --no-git-tag-version 1.0.1-$COMMIT_SHA
140+
141+
HAS_VERSION=$(jq 'has("version")' package.json)
142+
if [ "$HAS_VERSION" == "false" ]; then
143+
# Only bump version if package has no version field
144+
npm version --no-git-tag-version 1.0.1-$COMMIT_SHA
145+
fi
130146
131147
# Check if a custom publish script exists in package.json
132148
if jq -e '.scripts.publish' package.json > /dev/null; then

‎apps/site/.remarkrc.json

Lines changed: 1 addition & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,3 @@
11
{
2-
"settings": {
3-
"bullet": "-",
4-
"resourceLink": true
5-
},
6-
"plugins": [
7-
"remark-frontmatter",
8-
"remark-preset-lint-node",
9-
["remark-gfm", false],
10-
["remark-lint-fenced-code-flag", false],
11-
["remark-lint-first-heading-level", false],
12-
["remark-lint-maximum-line-length", false],
13-
["remark-lint-no-file-name-articles", false],
14-
["remark-lint-no-literal-urls", false],
15-
["remark-lint-no-unused-definitions", false],
16-
["remark-lint-no-undefined-references", false],
17-
["remark-lint-prohibited-strings", false],
18-
["remark-lint-unordered-list-marker-style", "-"],
19-
["remark-preset-lint-node/remark-lint-nodejs-links.js", false]
20-
]
2+
"plugins": ["remark-frontmatter", "@node-core/remark-lint"]
213
}

‎apps/site/package.json

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@
8282
"@eslint/eslintrc": "~3.3.1",
8383
"@flarelabs-net/wrangler-build-time-fs-assets-polyfilling": "^0.0.1",
8484
"@next/eslint-plugin-next": "15.5.0",
85+
"@node-core/remark-lint": "workspace:*",
8586
"@opennextjs/cloudflare": "^1.6.4",
8687
"@playwright/test": "^1.54.1",
8788
"@testing-library/user-event": "~14.6.1",
@@ -95,17 +96,7 @@
9596
"global-jsdom": "^26.0.0",
9697
"handlebars": "4.7.8",
9798
"jsdom": "^26.0.0",
98-
"remark-frontmatter": "5.0.0",
99-
"remark-lint-fenced-code-flag": "^4.2.0",
100-
"remark-lint-first-heading-level": "^4.0.1",
101-
"remark-lint-maximum-line-length": "^4.1.1",
102-
"remark-lint-no-file-name-articles": "^3.0.1",
103-
"remark-lint-no-literal-urls": "^4.0.1",
104-
"remark-lint-no-undefined-references": "^5.0.2",
105-
"remark-lint-no-unused-definitions": "^4.0.2",
106-
"remark-lint-prohibited-strings": "^4.0.0",
107-
"remark-lint-unordered-list-marker-style": "^4.0.1",
108-
"remark-preset-lint-node": "5.1.2",
99+
"remark-frontmatter": "^5.0.0",
109100
"stylelint": "16.23.0",
110101
"stylelint-config-standard": "39.0.0",
111102
"stylelint-order": "7.0.0",
@@ -127,4 +118,4 @@
127118
"./*/index.mjs"
128119
]
129120
}
130-
}
121+
}

‎apps/site/pages/en/learn/modules/how-to-use-streams.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -815,6 +815,7 @@ This work is derived from content published by [Matteo Collina][] in [Platformat
815815
[`on('close')`]: https://nodejs.org/api/stream.html#event-close_1
816816
[`on('error')`]: https://nodejs.org/api/stream.html#event-error_1
817817
[`.read()`]: https://nodejs.org/docs/latest/api/stream.html#stream_readable_read_size
818+
[`_read()`]: https://nodejs.org/api/stream.html#readable_readsize
818819
[`.write()`]: https://nodejs.org/api/stream.html#stream_writable_write_chunk_encoding_callback
819820
[`_write`]: https://nodejs.org/api/stream.html#writable_writechunk-encoding-callback
820821
[`.end()`]: https://nodejs.org/api/stream.html#writableendchunk-encoding-callback

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ authors: JakobJingleheimer
66

77
# Publishing a package
88

9-
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).
9+
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).
1010

1111
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.
1212

@@ -337,7 +337,7 @@ We're not in Kansas anymore, Toto.
337337

338338
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`.
339339

340-
💡 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.
340+
💡 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.
341341

342342
**Working example**: [esm-with-cjs-distro](https://github.com/JakobJingleheimer/nodejs-module-config-examples/tree/main/packages/esm/cjs-distro)
343343

@@ -386,7 +386,7 @@ If your files explicitly _all_ use `.cjs` and/or `.mjs` file extensions (none us
386386
}
387387
```
388388

389-
💡 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.
389+
💡 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.
390390

391391
#### Publish a CJS distribution with an ESM wrapper
392392

@@ -426,7 +426,7 @@ This is also almost identical to the [CJS source and dual distribution using an
426426
}
427427
```
428428

429-
💡 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.
429+
💡 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.
430430

431431
#### Publish both full CJS & ESM distributions
432432

@@ -498,7 +498,7 @@ Alternatively, you can use `"default"` and `"node"` keys, which are less counter
498498
}
499499
```
500500

501-
💡 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.
501+
💡 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.
502502

503503
##### Use the `.mjs` (or equivalent) file extension for all source code files
504504

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Pemberitahuan keamanan akan didistribusikan melalui metode berikut.
4646

4747
## Komentar tentang kebijakan ini
4848

49-
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.
49+
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.
5050

5151
## Praktik Terbaik OpenSSF
5252

‎packages/remark-lint/.lintstagedrc.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"**/*.{js,mjs,ts,tsx,md,mdx}": ["prettier --check --write", "eslint --fix"],
3+
"**/*.{json,yml}": ["prettier --check --write"]
4+
}

‎packages/remark-lint/README.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# `@node-core/remark-lint`
2+
3+
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).
4+
5+
## Installation
6+
7+
```bash
8+
npm install --save-dev @node-core/remark-lint
9+
```
10+
11+
## Usage
12+
13+
Add the plugin to your `.remarkrc` or `remark.config.js`:
14+
15+
```json
16+
{
17+
"plugins": ["@node-core/remark-lint"]
18+
}
19+
```
20+
21+
Run remark to lint your Markdown files:
22+
23+
```bash
24+
npx remark . --frail
25+
```
26+
27+
## Configuration
28+
29+
### Released Versions
30+
31+
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:
32+
33+
```json
34+
{
35+
"plugins": [
36+
[
37+
"@node-core/remark-lint",
38+
{
39+
"releasedVersions": ["v18.0.0", "v18.1.0", "v18.2.0", "v20.0.0"]
40+
}
41+
]
42+
]
43+
}
44+
```
45+
46+
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).
47+
48+
If not specified, version-related rules will accept any valid SemVer format.
49+
50+
## Rules
51+
52+
### `node-core:duplicate-stability-nodes`
53+
54+
Prevents redundant stability markers in nested sections.
55+
56+
**Not allowed:**
57+
58+
```markdown
59+
# Parent Section
60+
61+
> Stability: 2 - Stable
62+
63+
## Child Section
64+
65+
> Stability: 2 - Stable <!-- Redundant! -->
66+
```
67+
68+
### `node-core:hashed-self-reference`
69+
70+
Ensures self-references use fragment-only links.
71+
72+
**Allowed:**
73+
74+
```markdown
75+
See the [Introduction](#introduction) section.
76+
```
77+
78+
**Not allowed:**
79+
80+
```markdown
81+
See the [Introduction](document.md#introduction) section.
82+
```
83+
84+
### `node-core:ordered-references`
85+
86+
Enforces alphabetical sorting of reference-style link definitions.
87+
88+
**Allowed:**
89+
90+
```markdown
91+
[api]: https://example.com/api
92+
[docs]: https://example.com/docs
93+
[info]: https://example.com/info
94+
```
95+
96+
### `node-core:required-metadata`
97+
98+
Requires essential metadata for documentation:
99+
100+
- `llm_description`: A description for Large Language Models (can be inferred from first paragraph)
101+
- `introduced_in`: API introduction version
102+
103+
Metadata can be provided in comments:
104+
105+
```markdown
106+
<!-- llm_description= Utilities for working with file paths -->
107+
```
108+
109+
### `node-core:yaml-comments`
110+
111+
Enforces structure and content of YAML comment blocks:
112+
113+
- `added`: An array of valid version strings
114+
- `napiVersion`: The N-API version
115+
- `deprecated`: An array of valid version strings
116+
- `removed`: An array of valid version strings
117+
- `changes`: An array of:
118+
- `pr-url`: Pull request URL
119+
- `commit`: Commit hash (only required for security fixes)
120+
- `version`: Valid version string
121+
- `description`: Change description
122+
123+
All version references must be valid SemVer, or match the provided `releasedVersions`.

‎packages/remark-lint/eslint.config.js

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
import globals from 'globals';
2+
3+
import baseConfig from '../../eslint.config.js';
4+
5+
export default [
6+
...baseConfig,
7+
{
8+
languageOptions: {
9+
globals: globals.nodeBuiltin,
10+
parserOptions: {
11+
// Allow nullish syntax (i.e. "?." or "??"),
12+
// and top-level await
13+
ecmaVersion: 'latest',
14+
},
15+
},
16+
},
17+
];

‎packages/remark-lint/package.json

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
{
2+
"name": "@node-core/remark-lint",
3+
"type": "module",
4+
"version": "1.0.0",
5+
"exports": {
6+
".": "./src/index.mjs",
7+
"./api": "./src/api.mjs"
8+
},
9+
"scripts": {
10+
"lint": "node --run lint:js",
11+
"lint:fix": "node --run lint:js:fix",
12+
"lint:js": "eslint \"**/*.mjs\"",
13+
"lint:js:fix": "node --run lint:js -- --fix",
14+
"test": "node --run test:unit",
15+
"test:unit": "cross-env NODE_NO_WARNINGS=1 node --experimental-test-coverage --test \"**/*.test.mjs\""
16+
},
17+
"dependencies": {
18+
"remark-gfm": "^4.0.1",
19+
"remark-lint-blockquote-indentation": "^4.0.1",
20+
"remark-lint-checkbox-character-style": "^5.0.1",
21+
"remark-lint-checkbox-content-indent": "^5.0.1",
22+
"remark-lint-code-block-style": "^4.0.1",
23+
"remark-lint-definition-spacing": "^4.0.1",
24+
"remark-lint-fenced-code-flag": "^4.2.0",
25+
"remark-lint-fenced-code-marker": "^4.0.1",
26+
"remark-lint-final-definition": "^4.0.2",
27+
"remark-lint-heading-style": "^4.0.1",
28+
"remark-lint-maximum-line-length": "^4.1.1",
29+
"remark-lint-no-consecutive-blank-lines": "^5.0.1",
30+
"remark-lint-no-file-name-consecutive-dashes": "^3.0.1",
31+
"remark-lint-no-file-name-outer-dashes": "^3.0.1",
32+
"remark-lint-no-heading-indent": "^5.0.1",
33+
"remark-lint-no-literal-urls": "^4.0.1",
34+
"remark-lint-no-multiple-toplevel-headings": "^4.0.1",
35+
"remark-lint-no-shell-dollars": "^4.0.1",
36+
"remark-lint-no-table-indentation": "^5.0.1",
37+
"remark-lint-no-tabs": "^4.0.1",
38+
"remark-lint-no-trailing-spaces": "^3.0.2",
39+
"remark-lint-no-unused-definitions": "^4.0.2",
40+
"remark-lint-prohibited-strings": "^4.0.0",
41+
"remark-lint-rule-style": "^4.0.1",
42+
"remark-lint-strong-marker": "^4.0.1",
43+
"remark-lint-table-cell-padding": "^5.1.1",
44+
"remark-lint-table-pipes": "^5.0.1",
45+
"remark-lint-unordered-list-marker-style": "^4.0.1",
46+
"remark-preset-lint-recommended": "^7.0.1",
47+
"semver": "^7.7.2",
48+
"unified-lint-rule": "^3.0.1",
49+
"unist-util-visit": "^5.0.0",
50+
"yaml": "^2.8.1"
51+
},
52+
"devDependencies": {
53+
"cross-env": "catalog:",
54+
"dedent": "^1.6.0",
55+
"globals": "^16.3.0",
56+
"remark-parse": "^11.0.0",
57+
"unified": "^11.0.5"
58+
}
59+
}

0 commit comments

Comments
 (0)