Skip to content

Commit 8372618

Browse files
PlaneshifterPlaneshifter
committed
build: add package-reference-format commitlint rule
--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: passed - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---
1 parent a7b75d8 commit 8372618

File tree

11 files changed

+896
-0
lines changed

11 files changed

+896
-0
lines changed

‎etc/commitlint/.commitlintrc.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,29 @@
2020

2121
/* eslint-disable stdlib/jsdoc-leading-description-sentence */
2222

23+
// MODULES //
24+
25+
var stdlibPlugin = require( './plugins' );
26+
27+
28+
// MAIN //
29+
2330
/**
2431
* commitlint configuration.
2532
*
2633
* @namespace config
2734
*/
2835
var config = {};
2936

37+
/**
38+
* Custom plugins.
39+
*
40+
* @name plugins
41+
* @memberof config
42+
* @type {Array}
43+
*/
44+
config[ 'plugins' ] = [ stdlibPlugin ];
45+
3046
/**
3147
* Link to commit guidance.
3248
*

‎etc/commitlint/plugins/index.js‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var packageReferenceFormat = require( '@stdlib/_tools/commitlint/rules/package-reference-format' );
24+
25+
26+
// MAIN //
27+
28+
/**
29+
* Custom commitlint plugin for stdlib-specific rules.
30+
*
31+
* @name plugin
32+
* @type {Object}
33+
*/
34+
var plugin = {
35+
'rules': {
36+
'package-reference-format': packageReferenceFormat
37+
}
38+
};
39+
40+
41+
// EXPORTS //
42+
43+
module.exports = plugin;

‎etc/commitlint/rules/index.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -363,6 +363,15 @@ rules[ 'signed-off-by' ] = [ 0, 'always' ];
363363
*/
364364
rules[ 'trailer-exists' ] = [ 0, 'always', 'Signed-off-by:' ];
365365

366+
/**
367+
* Require that stdlib package references use backticks and exclude `@stdlib/` prefix.
368+
*
369+
* @name package-reference-format
370+
* @memberof rules
371+
* @type {Array}
372+
*/
373+
rules[ 'package-reference-format' ] = [ 2, 'always' ];
374+
366375

367376
// EXPORTS //
368377

‎lib/node_modules/@stdlib/_tools/commitlint/rules/package-reference-format/README.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# package-reference-format
22+
23+
> [Commitlint rule][commitlint-rules] enforcing that stdlib package references use backticks and exclude the `@stdlib/` prefix.
24+
25+
<section class="intro">
26+
27+
This rule ensures consistent formatting of stdlib package references in commit messages and PR titles:
28+
29+
1. Package references must be wrapped in backticks (e.g., `` `math/base/special/abs` ``).
30+
2. Package references must NOT include the `@stdlib/` prefix.
31+
32+
</section>
33+
34+
<!-- /.intro -->
35+
36+
<section class="usage">
37+
38+
## Usage
39+
40+
```javascript
41+
var rule = require( '@stdlib/_tools/commitlint/rules/package-reference-format' );
42+
```
43+
44+
#### rule( parsed, when )
45+
46+
[Commitlint rule][commitlint-rules] enforcing that stdlib package references use backticks and exclude the `@stdlib/` prefix.
47+
48+
```javascript
49+
var parsed = {
50+
'subject': 'feat: add math/base/special/abs'
51+
};
52+
var result = rule( parsed, 'always' );
53+
// returns [ false, 'Package reference `math/base/special/abs` must be wrapped in backticks.' ]
54+
```
55+
56+
**Bad**:
57+
58+
```text
59+
feat: add math/base/special/abs
60+
feat: add `@stdlib/math/base/special/abs`
61+
docs: update stats/maxabs
62+
fix: resolve issue in dists/chi/logpdf
63+
```
64+
65+
**Good**:
66+
67+
```text
68+
feat: add `math/base/special/abs`
69+
docs: update `stats/maxabs`
70+
fix: resolve issue in `dists/chi/logpdf`
71+
docs: fix typo in README
72+
```
73+
74+
</section>
75+
76+
<!-- /.usage -->
77+
78+
<section class="notes">
79+
80+
## Notes
81+
82+
- The rule detects package references by matching paths that start with known stdlib namespace segments (e.g., `math`, `stats`, `blas`, `dists`, `special`, etc.).
83+
- The list of namespace segments is stored in `lib/namespace_segments.json` and can be regenerated using the build script.
84+
- Partial paths like `dists/chi/logpdf` or `special/abs` are also detected.
85+
- URLs are excluded from detection to avoid false positives.
86+
87+
</section>
88+
89+
<!-- /.notes -->
90+
91+
<section class="examples">
92+
93+
## Examples
94+
95+
```javascript
96+
var rule = require( '@stdlib/_tools/commitlint/rules/package-reference-format' );
97+
98+
var parsed;
99+
var result;
100+
101+
// Valid commit message with backticks:
102+
parsed = {
103+
'subject': 'feat: add `math/base/special/abs`'
104+
};
105+
result = rule( parsed, 'always' );
106+
console.log( result );
107+
// => [ true, '' ]
108+
109+
// Invalid commit message without backticks:
110+
parsed = {
111+
'subject': 'feat: add math/base/special/abs'
112+
};
113+
result = rule( parsed, 'always' );
114+
console.log( result );
115+
// => [ false, 'Package reference `math/base/special/abs` must be wrapped in backticks.' ]
116+
117+
// Invalid commit message with @stdlib/ prefix:
118+
parsed = {
119+
'subject': 'feat: add `@stdlib/math/base/special/abs`'
120+
};
121+
result = rule( parsed, 'always' );
122+
console.log( result );
123+
// => [ false, 'Package references must not include the `@stdlib/` prefix. Use `pkg/path` instead of `@stdlib/pkg/path`.' ]
124+
```
125+
126+
</section>
127+
128+
<!-- /.examples -->
129+
130+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
131+
132+
<section class="related">
133+
134+
</section>
135+
136+
<!-- /.related -->
137+
138+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
139+
140+
<section class="links">
141+
142+
[commitlint-rules]: https://commitlint.js.org/#/reference-rules
143+
144+
</section>
145+
146+
<!-- /.links -->

‎lib/node_modules/@stdlib/_tools/commitlint/rules/package-reference-format/examples/index.js‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
var rule = require( './../lib' );
22+
23+
// Valid commit message with backticks:
24+
var result = rule({
25+
'subject': 'feat: add `math/base/special/abs`'
26+
}, 'always' );
27+
console.log( 'Valid message:' );
28+
console.log( result );
29+
// => [ true, '' ]
30+
31+
console.log( '' );
32+
33+
// Invalid commit message without backticks:
34+
result = rule({
35+
'subject': 'feat: add math/base/special/abs'
36+
}, 'always' );
37+
console.log( 'Invalid message (missing backticks):' );
38+
console.log( result );
39+
// => [ false, 'Package reference `math/base/special/abs` must be wrapped in backticks.' ]
40+
41+
console.log( '' );
42+
43+
// Invalid commit message with @stdlib/ prefix:
44+
result = rule({
45+
'subject': 'feat: add `@stdlib/math/base/special/abs`'
46+
}, 'always' );
47+
console.log( 'Invalid message (@stdlib/ prefix):' );
48+
console.log( result );
49+
// => [ false, 'Package references must not include the `@stdlib/` prefix. Use `pkg/path` instead of `@stdlib/pkg/path`.' ]
50+
51+
console.log( '' );
52+
53+
// Valid commit message without package references:
54+
result = rule({
55+
'subject': 'docs: fix typo in README'
56+
}, 'always' );
57+
console.log( 'Valid message (no package reference):' );
58+
console.log( result );
59+
// => [ true, '' ]
60+
61+
console.log( '' );
62+
63+
// Partial path detection:
64+
result = rule({
65+
'subject': 'fix: update dists/chi/logpdf'
66+
}, 'always' );
67+
console.log( 'Invalid message (partial path without backticks):' );
68+
console.log( result );
69+
// => [ false, 'Package reference `dists/chi/logpdf` must be wrapped in backticks.' ]

‎lib/node_modules/@stdlib/_tools/commitlint/rules/package-reference-format/lib/index.js‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
/**
22+
* Commitlint rule enforcing that stdlib package references use backticks and exclude the `@stdlib/` prefix.
23+
*
24+
* @module @stdlib/_tools/commitlint/rules/package-reference-format
25+
*
26+
* @example
27+
* var rule = require( '@stdlib/_tools/commitlint/rules/package-reference-format' );
28+
*
29+
* var parsed = {
30+
* 'subject': 'add math/base/special/abs'
31+
* };
32+
* var result = rule( parsed, 'always' );
33+
* // returns [ false, 'Package reference `math/base/special/abs` must be wrapped in backticks.' ]
34+
*/
35+
36+
// MODULES //
37+
38+
var main = require( './main.js' );
39+
40+
41+
// EXPORTS //
42+
43+
module.exports = main;

0 commit comments

Comments
 (0)