@netdata/site-build-gate 0.0.0-stage → 10.1.0-test.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +674 -0
- package/README.md +94 -2
- package/package.json +31 -4
- package/site_build_gate.mjs +1049 -0
package/README.md
CHANGED
|
@@ -1,3 +1,95 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @netdata/site-build-gate
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Fails a static site build when accepted technical defects regress. It runs after the site
|
|
4
|
+
generator, reads the built HTML and `sitemap.xml`, and makes no network requests. Netdata's
|
|
5
|
+
sites run it before every deploy so that both apply one definition of each defect.
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- Node.js 22.x
|
|
10
|
+
- A build directory containing the site's `sitemap.xml` and its HTML files
|
|
11
|
+
|
|
12
|
+
## Usage
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install --save-dev @netdata/site-build-gate
|
|
16
|
+
|
|
17
|
+
site-build-gate \
|
|
18
|
+
--build-dir build \
|
|
19
|
+
--site-origin https://learn.netdata.cloud \
|
|
20
|
+
--baseline config/site-build-gate-baseline.json \
|
|
21
|
+
--integration-route-prefix /docs/collecting-metrics/collectors \
|
|
22
|
+
--format json
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
| Option | Required | Meaning |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| `--build-dir` | yes | The built site |
|
|
28
|
+
| `--site-origin` | yes | Absolute HTTP(S) origin every sitemap location must use |
|
|
29
|
+
| `--baseline` | no | Accepted findings (see below); without it every finding is a regression |
|
|
30
|
+
| `--integration-route-prefix` | no, repeatable | Route families excluded from `heavy-page`; matched on whole path segments |
|
|
31
|
+
| `--format` | no | `text` (default) or `json`, the complete deterministic report |
|
|
32
|
+
|
|
33
|
+
Exit status:
|
|
34
|
+
|
|
35
|
+
- `0`: no findings beyond the baseline
|
|
36
|
+
- `1`: one or more regressions
|
|
37
|
+
- `2`: malformed build input or baseline
|
|
38
|
+
|
|
39
|
+
## Rules (ruleset 10)
|
|
40
|
+
|
|
41
|
+
| Rule | Classification | Applies to |
|
|
42
|
+
|---|---|---|
|
|
43
|
+
| `missing-title` | accessibility (WCAG 2.4.2) | every public HTML page |
|
|
44
|
+
| `images-missing-alt` | accessibility (WCAG 1.1.1) | every public HTML page; `alt=""` is valid |
|
|
45
|
+
| `missing-description` | presentation | index-eligible pages |
|
|
46
|
+
| `missing-h1` | presentation | index-eligible pages and every `/guides/` page |
|
|
47
|
+
| `multiple-h1` | presentation | index-eligible pages and every `/guides/` page |
|
|
48
|
+
| `duplicate-title` | presentation | index-eligible sitemap pages |
|
|
49
|
+
| `duplicate-description` | presentation | index-eligible sitemap pages |
|
|
50
|
+
| `heavy-page` | diagnostic | public HTML above 500,000 bytes, outside integration route prefixes |
|
|
51
|
+
|
|
52
|
+
A page is index-eligible when it is in the sitemap and has no `noindex`. Elements a browser
|
|
53
|
+
would not show (for example `display:none` inline styles, `hidden`, inert templates) do not
|
|
54
|
+
count.
|
|
55
|
+
|
|
56
|
+
## Baseline
|
|
57
|
+
|
|
58
|
+
A site may accept specific findings, each with a reason:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"schema": "netdata-site-build-gate-baseline-v1",
|
|
63
|
+
"contract": "netdata-site-build-gate-v1",
|
|
64
|
+
"ruleset_version": 10,
|
|
65
|
+
"allowed": [
|
|
66
|
+
{
|
|
67
|
+
"identity": "heavy-page|/reports/full/|8bfc77f03605b57794db3d8a55cf41634dc51e4279d842bf9b88b7f0081a92d5",
|
|
68
|
+
"reason": "The complete report is an accepted non-integration exception."
|
|
69
|
+
}
|
|
70
|
+
]
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- The four top-level keys are exact; anything else fails with status `2`.
|
|
75
|
+
- An identity is `rule|path`, plus `|sha256(state)` for findings that measure something, so an
|
|
76
|
+
accepted issue that grows becomes a new finding. Copy identities from the JSON report.
|
|
77
|
+
- `ruleset_version` must equal the gate's ruleset, even when `allowed` is empty.
|
|
78
|
+
- The report lists accepted findings with their reasons, and baseline entries whose finding
|
|
79
|
+
disappeared as `stale_baseline`, so they can be removed. The gate never writes a baseline.
|
|
80
|
+
|
|
81
|
+
## Report
|
|
82
|
+
|
|
83
|
+
`--format json` prints `netdata-site-build-gate-report-v1`: the ruleset, origin, checked page
|
|
84
|
+
counts, per-rule counts, and the `findings`, `accepted_findings`, `regressions` and
|
|
85
|
+
`stale_baseline` lists.
|
|
86
|
+
|
|
87
|
+
## Versioning
|
|
88
|
+
|
|
89
|
+
The major version is the ruleset. A major release can report new findings and requires the
|
|
90
|
+
baseline's `ruleset_version` to be updated with it. Minor and patch releases never change
|
|
91
|
+
findings.
|
|
92
|
+
|
|
93
|
+
## License
|
|
94
|
+
|
|
95
|
+
GPL-3.0. See `LICENSE`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,33 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@netdata/site-build-gate",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "10.1.0-test.0",
|
|
4
|
+
"description": "Fail a static site build when accepted technical defects regress.",
|
|
5
|
+
"license": "GPL-3.0",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/netdata-labs/seo.git",
|
|
9
|
+
"directory": "vendor/site-build-gate"
|
|
10
|
+
},
|
|
11
|
+
"type": "module",
|
|
12
|
+
"exports": {
|
|
13
|
+
".": "./site_build_gate.mjs",
|
|
14
|
+
"./package.json": "./package.json"
|
|
15
|
+
},
|
|
16
|
+
"bin": {
|
|
17
|
+
"site-build-gate": "site_build_gate.mjs"
|
|
18
|
+
},
|
|
19
|
+
"files": [
|
|
20
|
+
"site_build_gate.mjs"
|
|
21
|
+
],
|
|
22
|
+
"engines": {
|
|
23
|
+
"node": "22.x"
|
|
24
|
+
},
|
|
25
|
+
"publishConfig": {
|
|
26
|
+
"access": "public"
|
|
27
|
+
},
|
|
28
|
+
"dependencies": {
|
|
29
|
+
"css-tree": "^3.2.1",
|
|
30
|
+
"parse5": "^8.0.1",
|
|
31
|
+
"saxes": "^6.0.0"
|
|
32
|
+
}
|
|
33
|
+
}
|