build: add package-reference-format commitlint rule

etc/commitlint/.commitlintrc.js

@@ -20,13 +20,29 @@
 
 /* eslint-disable stdlib/jsdoc-leading-description-sentence */
 
+// MODULES //
+
+var stdlibPlugin = require( './plugins' );
+
+
+// MAIN //
+
 /**
 * commitlint configuration.
 *
 * @namespace config
 */
 var config = {};
 
+/**
+* Custom plugins.
+*
+* @name plugins
+* @memberof config
+* @type {Array}
+*/
+config[ 'plugins' ] = [ stdlibPlugin ];
+
 /**
 * Link to commit guidance.
 *

etc/commitlint/plugins/index.js

@@ -0,0 +1,43 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var packageReferenceFormat = require( '@stdlib/_tools/commitlint/rules/package-reference-format' );
+
+
+// MAIN //
+
+/**
+* Custom commitlint plugin for stdlib-specific rules.
+*
+* @name plugin
+* @type {Object}
+*/
+var plugin = {
+	'rules': {
+		'package-reference-format': packageReferenceFormat
+	}
+};
+
+
+// EXPORTS //
+
+module.exports = plugin;

etc/commitlint/rules/index.js

@@ -363,6 +363,15 @@ rules[ 'signed-off-by' ] = [ 0, 'always' ];
 */
 rules[ 'trailer-exists' ] = [ 0, 'always', 'Signed-off-by:' ];
 
+/**
+* Require that stdlib package references use backticks and exclude `@stdlib/` prefix.
+*
+* @name package-reference-format
+* @memberof rules
+* @type {Array}
+*/
+rules[ 'package-reference-format' ] = [ 2, 'always' ];
+
 
 // EXPORTS //
 

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

@@ -0,0 +1,143 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2025 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# package-reference-format
+
+> [Commitlint rule][commitlint-rules] enforcing that stdlib package references use backticks and exclude the `@stdlib/` prefix.
+
+<section class="intro">
+
+This rule ensures consistent formatting of stdlib package references in commit messages and PR titles:
+
+1.  Package references must be wrapped in backticks (e.g., `` `math/base/special/abs` ``).
+2.  Package references must NOT include the `@stdlib/` prefix.
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var rule = require( '@stdlib/_tools/commitlint/rules/package-reference-format' );
+```
+
+#### rule( parsed, when )
+
+[Commitlint rule][commitlint-rules] enforcing that stdlib package references use backticks and exclude the `@stdlib/` prefix.
+
+```javascript
+var parsed = {
+    'subject': 'feat: add math/base/special/abs'
+};
+var result = rule( parsed, 'always' );
+// returns [ false, 'Package reference `math/base/special/abs` must be wrapped in backticks.' ]
+```
+
+**Bad**:
+
+```text
+feat: add math/base/special/abs
+feat: add `@stdlib/math/base/special/abs`
+docs: update stats/maxabs
+fix: resolve issue in dists/chi/logpdf
+```
+
+**Good**:
+
+```text
+feat: add `math/base/special/abs`
+docs: update `stats/maxabs`
+fix: resolve issue in `dists/chi/logpdf`
+docs: fix typo in README
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   The rule detects package references by matching paths that start with known stdlib namespace segments (e.g., `math`, `stats`, `blas`, `dists`, `special`, etc.).
+-   The list of namespace segments is stored in `lib/namespace_segments.json` and can be regenerated using the build script.
+-   Partial paths like `dists/chi/logpdf` or `special/abs` are also detected.
+-   URLs are excluded from detection to avoid false positives.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+```javascript
+var rule = require( '@stdlib/_tools/commitlint/rules/package-reference-format' );
+
+// Valid commit message with backticks:
+var parsed = {
+    'subject': 'feat: add `math/base/special/abs`'
+};
+var result = rule( parsed, 'always' );
+console.log( result );
+// => [ true, '' ]
+
+// Invalid commit message without backticks:
+parsed = {
+    'subject': 'feat: add math/base/special/abs'
+};
+result = rule( parsed, 'always' );
+console.log( result );
+// => [ false, 'Package reference `math/base/special/abs` must be wrapped in backticks.' ]
+
+// Invalid commit message with @stdlib/ prefix:
+parsed = {
+    'subject': 'feat: add `@stdlib/math/base/special/abs`'
+};
+result = rule( parsed, 'always' );
+console.log( result );
+// => [ false, 'Package references must not include the `@stdlib/` prefix. Use `pkg/path` instead of `@stdlib/pkg/path`.' ]
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[commitlint-rules]: https://commitlint.js.org/#/reference-rules
+
+</section>
+
+<!-- /.links -->

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

@@ -0,0 +1,69 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+var rule = require( './../lib' );
+
+// Valid commit message with backticks:
+var result = rule({
+	'subject': 'feat: add `math/base/special/abs`'
+}, 'always' );
+console.log( 'Valid message:' );
+console.log( result );
+// => [ true, '' ]
+
+console.log( '' );
+
+// Invalid commit message without backticks:
+result = rule({
+	'subject': 'feat: add math/base/special/abs'
+}, 'always' );
+console.log( 'Invalid message (missing backticks):' );
+console.log( result );
+// => [ false, 'Package reference `math/base/special/abs` must be wrapped in backticks.' ]
+
+console.log( '' );
+
+// Invalid commit message with @stdlib/ prefix:
+result = rule({
+	'subject': 'feat: add `@stdlib/math/base/special/abs`'
+}, 'always' );
+console.log( 'Invalid message (@stdlib/ prefix):' );
+console.log( result );
+// => [ false, 'Package references must not include the `@stdlib/` prefix. Use `pkg/path` instead of `@stdlib/pkg/path`.' ]
+
+console.log( '' );
+
+// Valid commit message without package references:
+result = rule({
+	'subject': 'docs: fix typo in README'
+}, 'always' );
+console.log( 'Valid message (no package reference):' );
+console.log( result );
+// => [ true, '' ]
+
+console.log( '' );
+
+// Partial path detection:
+result = rule({
+	'subject': 'fix: update dists/chi/logpdf'
+}, 'always' );
+console.log( 'Invalid message (partial path without backticks):' );
+console.log( result );
+// => [ false, 'Package reference `dists/chi/logpdf` must be wrapped in backticks.' ]

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

@@ -0,0 +1,43 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+/**
+* Commitlint rule enforcing that stdlib package references use backticks and exclude the `@stdlib/` prefix.
+*
+* @module @stdlib/_tools/commitlint/rules/package-reference-format
+*
+* @example
+* var rule = require( '@stdlib/_tools/commitlint/rules/package-reference-format' );
+*
+* var parsed = {
+*     'subject': 'add math/base/special/abs'
+* };
+* var result = rule( parsed, 'always' );
+* // returns [ false, 'Package reference `math/base/special/abs` must be wrapped in backticks.' ]
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;