Skip to content

Commit bac8810

Browse files
Keep the package loadable on node 12, and enforce it (#216)
* Emit es2019 so the built output parses on node 12 engines has claimed node >= 12 all along, but nothing enforced it, and a tsconfig target of es2020 let a nullish coalescing operator reach dist as written. Node 12 cannot parse it, so requiring the package threw a SyntaxError at load: not a broken code path but a package that could not be loaded at all on the oldest runtime it claims. Lowering the target to es2019 makes tsc downlevel that operator and refuse any newer syntax at compile time, so the emitted output cannot drift past node 12 again without a build failure. lib stays at es2020 for the bigint types; every es2020 library addition already exists in node 12. The two BigInt literals become BigInt() calls, which is what a target below es2020 requires and what the surrounding code already does. The dev toolchain cannot run on node 12 to catch this: mocha 11, chai 6, tsx and c8 all require node 18 or newer, mocha's own entry point uses node: prefixed requires, and node 12 ships npm 6.14 which cannot read a lockfileVersion 3 lockfile. A matrix entry would fail on the toolchain and report nothing about the library. The new job instead builds dist on a current node and then requires it under node 12, which is what a consumer on an old runtime does and the only place a regression in emitted syntax shows up. The smoke test covers both address families, subnets, BigInt round trips, byte arrays and fromURL, the site of the operator in question. * Format the repository with prettier Seventeen files had drifted from prettier's output, which made a formatting warning on a touched file indistinguishable from one already there and cost time on the previous commit deciding which was which. Everything prettier covers now matches it. Two categories are excluded rather than reformatted. The vendored InterMapper address fixtures stay in the shape they arrived in so they remain comparable against their source. Build output is listed as well, so a local build or coverage run cannot make a check of the whole tree fail on files that are not in the repository. The example block at the top of the README aligns its result comments into a column, which prettier would collapse, so the template marks that one fence prettier-ignore. The marker is an HTML comment and flows through into the generated README, where it does not render. * Clear the eslint findings across src, test and scripts Nothing linted the TypeScript: eslint's default extension list is .js alone, so `eslint .` only ever saw the config file itself and reported clean while seventeen findings sat in the library and its tests. They are all resolved here so the rules can be enforced. no-bitwise is off rather than suppressed. Masks, prefix lengths and the NAT64 and Teredo encodings are defined in terms of shifts and xors, so the rule fires on correct code throughout: nine inline suppressions had accumulated against six live findings, and one suppression had drifted onto the line after the operator it was meant to cover. The suppressions are gone with it. The two ignored catch bindings become optional catch bindings, which es2019 allows and node 12 supports. The NAT64 bit assembly becomes an array joined at the end, so the reserved u octet can be named instead of appearing as a bare string in the middle of a concatenation. A shadowed path in the readme builder and a shadowed v6 in a test are renamed for what they hold, and the closure returned by isCorrect gets a name. Build scripts are allowed to write to stdout, which is how they report progress. * Check formatting and lint in CI and from a pre-commit hook There was no lint script and no CI step for one, so formatting drift and lint findings only surfaced when someone happened to run the tools by hand. CI now runs both against the whole tree, with eslint pointed at .ts as well as .js and warnings treated as failures so nothing accumulates below the threshold. The check reports rather than corrects. Correcting in CI means granting a workflow write access to the repository, and a token-authored commit does not retrigger workflows, so a pull request would end up with its head unchecked; fork pull requests would still need fixing by hand either way. The same check therefore runs from a pre-commit hook, installed by pointing core.hooksPath at a committed hooks directory, so a violation is caught before it is pushed and `npm run lint:fix` corrects everything mechanical. Extending airbnb-base rather than airbnb drops eslint-plugin-react, eslint-plugin-react-hooks and eslint-plugin-jsx-a11y from a library with no react in it, taking 377 lines out of the lockfile and with them the warning the react plugin printed on every run because it could not detect a version. The rules that remain are the same ones; airbnb adds only react and accessibility rules on top of that base. * Check that the generated README is current in CI The API reference in the README is generated from the source, including the line numbers its per-method source links point at, so any change under src leaves it stale until `npm run docs` is run again. That happened twice while writing the previous commits and was only noticed by hand. CI now regenerates it and fails if the result differs from what is committed.
1 parent 9b3d848 commit bac8810

19 files changed

Lines changed: 444 additions & 625 deletions

‎.eslintrc.js‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ module.exports = {
1010

1111
plugins: ['filenames', 'import', 'prettier', 'sort-imports-es6-autofix', '@typescript-eslint'],
1212

13-
extends: ['airbnb', 'prettier'],
13+
extends: ['airbnb-base', 'prettier'],
1414

1515
rules: {
1616
'array-callback-return': 'off',
@@ -31,6 +31,10 @@ module.exports = {
3131
'import/order': 'off',
3232
'import/prefer-default-export': 'off',
3333
'lines-between-class-members': 'off',
34+
// Masks, prefix lengths and the NAT64 and Teredo encodings are all defined
35+
// in terms of shifts and xors, so the rule fires on correct code
36+
// throughout and its inline suppressions outnumbered its findings.
37+
'no-bitwise': 'off',
3438
'no-case-declarations': 'off',
3539
'no-cond-assign': ['error', 'except-parens'],
3640
'no-continue': 'off',
@@ -85,4 +89,14 @@ module.exports = {
8589
{ ignoreCase: true, memberSyntaxSortOrder: ['none', 'all', 'single', 'multiple'] },
8690
],
8791
},
92+
93+
overrides: [
94+
{
95+
// Build scripts report progress on stdout.
96+
files: ['scripts/**/*.ts'],
97+
rules: {
98+
'no-console': 'off',
99+
},
100+
},
101+
],
88102
};

‎.github/workflows/ci.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,36 @@ concurrency:
1616
cancel-in-progress: true
1717

1818
jobs:
19+
# Formatting and lint findings are reported, not corrected, in CI. Correcting
20+
# them here would mean granting a workflow write access to the repository and
21+
# would still leave fork pull requests to fix by hand, so the same check runs
22+
# from a pre-commit hook, where `npm run lint:fix` is one command away.
23+
lint:
24+
runs-on: ubuntu-latest
25+
26+
steps:
27+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
28+
29+
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
30+
with:
31+
node-version: '22'
32+
cache: npm
33+
34+
- run: npm ci
35+
36+
- run: npm run lint
37+
38+
# The API reference in the README is generated from the source, down to
39+
# the line numbers its links point at, so any change under src leaves it
40+
# stale until it is rebuilt.
41+
- name: Check the generated README is current
42+
run: |
43+
npm run docs
44+
git diff --exit-code README.md || {
45+
echo 'README.md is out of date; run `npm run docs` and commit the result.'
46+
exit 1
47+
}
48+
1949
test:
2050
name: test-${{ matrix.node-version }}
2151
runs-on: ubuntu-latest
@@ -45,3 +75,33 @@ jobs:
4575
# Tokenless upload; public repositories do not need a token, and a
4676
# fork pull request would not have access to one anyway.
4777
fail_ci_if_error: false
78+
79+
# The oldest node `engines` claims. The dev toolchain (mocha, tsx, c8) and the
80+
# lockfile's npm version both need a modern node, so the suite itself cannot
81+
# run here; instead this builds dist on a current node and requires it under
82+
# node 12, which is what a consumer on an old runtime does and the only place
83+
# emitted-syntax regressions show up.
84+
smoke:
85+
name: smoke-12
86+
runs-on: ubuntu-latest
87+
88+
steps:
89+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
90+
91+
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
92+
with:
93+
node-version: '22'
94+
cache: npm
95+
96+
- run: npm ci
97+
98+
- run: npm run build
99+
100+
# Switching the active node after the build; nothing below runs npm, so
101+
# node 12's bundled npm 6 never has to read the lockfile.
102+
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
103+
with:
104+
node-version: '12'
105+
106+
- run: node test/node-12-smoke.js
107+
name: Run dist smoke test

‎.mocharc.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
recursive: true
22
reporter: spec
33
node-option:
4-
- import=tsx
5-
- import=source-map-support/register
4+
- import=tsx
5+
- import=source-map-support/register
66
inline-diffs: false
77
spec: test/**/*.ts

‎.prettierignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Vendored test fixtures, kept in the shape they arrived in so they stay
2+
# comparable against their source.
3+
test/data/
4+
5+
# Build output.
6+
dist/
7+
coverage/
8+
docs/

‎.vscode/settings.json‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
{
2-
"typescript.tsdk": "node_modules/typescript/lib",
2+
"typescript.tsdk": "node_modules/typescript/lib",
33

4-
"eslint.options": {
5-
"configFile": "./.eslintrc.js"
6-
},
4+
"eslint.options": {
5+
"configFile": "./.eslintrc.js"
6+
},
77

8-
"files.exclude": {
9-
"**/.git": true,
10-
"**/.DS_Store": true,
11-
"coverage/**": true,
12-
"node_modules/**": true,
13-
"dist/**": true,
14-
"build/**": true,
15-
"assets/**": true,
16-
"tmp/**": true
17-
}
8+
"files.exclude": {
9+
"**/.git": true,
10+
"**/.DS_Store": true,
11+
"coverage/**": true,
12+
"node_modules/**": true,
13+
"dist/**": true,
14+
"build/**": true,
15+
"assets/**": true,
16+
"tmp/**": true
17+
}
1818
}

‎CODE_OF_CONDUCT.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,19 +8,19 @@ In the interest of fostering an open and welcoming environment, we as contributo
88

99
Examples of behavior that contributes to creating a positive environment include:
1010

11-
* Using welcoming and inclusive language
12-
* Being respectful of differing viewpoints and experiences
13-
* Gracefully accepting constructive criticism
14-
* Focusing on what is best for the community
15-
* Showing empathy towards other community members
11+
- Using welcoming and inclusive language
12+
- Being respectful of differing viewpoints and experiences
13+
- Gracefully accepting constructive criticism
14+
- Focusing on what is best for the community
15+
- Showing empathy towards other community members
1616

1717
Examples of unacceptable behavior by participants include:
1818

19-
* The use of sexualized language or imagery and unwelcome sexual attention or advances
20-
* Trolling, insulting/derogatory comments, and personal or political attacks
21-
* Public or private harassment
22-
* Publishing others' private information, such as a physical or electronic address, without explicit permission
23-
* Other conduct which could reasonably be considered inappropriate in a professional setting
19+
- The use of sexualized language or imagery and unwelcome sexual attention or advances
20+
- Trolling, insulting/derogatory comments, and personal or political attacks
21+
- Public or private harassment
22+
- Publishing others' private information, such as a physical or electronic address, without explicit permission
23+
- Other conduct which could reasonably be considered inappropriate in a professional setting
2424

2525
## Our Responsibilities
2626

0 commit comments

Comments
 (0)