@atlasng/commitlint-config 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cyberinfrastructure for Network Science Center at Indiana University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @atlasng/commitlint-config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared [commitlint](https://commitlint.js.org/) configuration for AtlasNG and other Nx workspaces. It enforces [Conventional Commits](https://www.conventionalcommits.org/) and only accepts scopes that are Nx project names.
+
+## Installation
+
+```bash
+npm install --save-dev @commitlint/cli @atlasng/commitlint-config
+```
+
+## Usage
+
+Extend the configuration from `commitlint.config.mjs`:
+
+```js
+export default {
+  extends: ['@atlasng'],
+};
+```
+
+The configuration:
+
+- extends `@commitlint/config-conventional`
+- restricts `scope-enum` to the workspace's Nx project names (`@org/name` becomes `name`), or allows no scopes when the directory has no `nx.json`
+- ignores commits created by Nx Cloud self-healing CI reruns
+
+### Additional scopes
+
+No scopes beyond the project names are allowed by default. Use `utils.getProjects` to add your own, for example a `release` scope for `nx release` commits:
+
+```js
+import atlasng from '@atlasng/commitlint-config';
+
+export default {
+  extends: ['@atlasng'],
+  rules: {
+    'scope-enum': async (ctx) => [2, 'always', [...atlasng.utils.getProjects(ctx), 'release']],
+  },
+};
+```
+
+### Selecting projects
+
+`utils.getProjects(ctx, selector)` accepts an optional selector that receives each project's `name`, `projectType` and `tags`:
+
+```js
+import atlasng from '@atlasng/commitlint-config';
+
+export default {
+  extends: ['@atlasng'],
+  rules: {
+    'scope-enum': async (ctx) => [
+      2,
+      'always',
+      atlasng.utils.getProjects(ctx, ({ tags }) => !tags?.includes('internal')),
+    ],
+  },
+};
+```
+
+`utils.isNxSelfHealingCommit(message)` is also exported for configurations that replace `ignores`.

package/index.d.ts

@@ -0,0 +1,89 @@
+export default config;
+/**
+ * Commitlint context passed to configuration rule functions.
+ */
+export type CommitlintContext = {
+    /**
+     * Directory commitlint runs in. Defaults to `process.cwd()`.
+     */
+    cwd?: string | undefined;
+};
+/**
+ * Subset of an Nx project configuration that project selectors receive.
+ */
+export type ProjectSummary = {
+    /**
+     * Project name.
+     */
+    name: string;
+    /**
+     * Either `application` or `library` when declared.
+     */
+    projectType?: string | undefined;
+    /**
+     * Tags declared on the project.
+     */
+    tags?: string[] | undefined;
+};
+/**
+ * Predicate that decides whether a project contributes a commit scope.
+ */
+export type ProjectSelector = (project: ProjectSummary) => boolean;
+/**
+ * Commitlint rule configuration tuple for `scope-enum`. The severity `2` is an error.
+ */
+export type ScopeEnumRuleConfig = [2, "always", string[]];
+/**
+ * Helpers exposed for consumers that extend the shared configuration.
+ */
+export type CommitlintConfigUtils = {
+    /**
+     * Lists Nx project names usable as commit scopes.
+     */
+    getProjects: typeof getProjects;
+    /**
+     * Detects Nx Cloud self-healing CI commits.
+     */
+    isNxSelfHealingCommit: typeof isNxSelfHealingCommit;
+};
+/**
+ * Shared commitlint configuration.
+ */
+export type CommitlintConfig = {
+    /**
+     * Configurations this configuration builds on.
+     */
+    extends: string[];
+    /**
+     * Predicates for commit messages commitlint skips.
+     */
+    ignores: ((message: string) => boolean)[];
+    /**
+     * Rule overrides.
+     */
+    rules: {
+        "scope-enum": (ctx?: CommitlintContext) => Promise<ScopeEnumRuleConfig>;
+    };
+    /**
+     * Helpers for extending the configuration.
+     */
+    utils: CommitlintConfigUtils;
+};
+/** @type {CommitlintConfig} */
+declare const config: CommitlintConfig;
+/**
+ * Lists the Nx project names in the workspace, for use as commit scopes. Scoped names such as
+ * `@org/name` are reduced to `name`.
+ *
+ * @param {CommitlintContext} [ctx] Commitlint context; its `cwd` locates the workspace.
+ * @param {ProjectSelector} [selector] Optional filter applied to each project.
+ * @returns {string[]} Matching project names, or an empty list when `cwd` has no `nx.json`.
+ */
+declare function getProjects(ctx?: CommitlintContext, selector?: ProjectSelector): string[];
+/**
+ * Checks whether a commit was produced by Nx Cloud's self-healing CI.
+ *
+ * @param {string} message The complete commit message.
+ * @returns {boolean} Whether commitlint should ignore the message.
+ */
+declare function isNxSelfHealingCommit(message: string): boolean;

package/index.js

@@ -0,0 +1,82 @@
+// @ts-check
+import nxScopes from '@commitlint/config-nx-scopes';
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Commitlint context passed to configuration rule functions.
+ *
+ * @typedef {object} CommitlintContext
+ * @property {string} [cwd] Directory commitlint runs in. Defaults to `process.cwd()`.
+ */
+/**
+ * Subset of an Nx project configuration that project selectors receive.
+ *
+ * @typedef {object} ProjectSummary
+ * @property {string} name Project name.
+ * @property {string} [projectType] Either `application` or `library` when declared.
+ * @property {string[]} [tags] Tags declared on the project.
+ */
+/**
+ * Predicate that decides whether a project contributes a commit scope.
+ *
+ * @callback ProjectSelector
+ * @param {ProjectSummary} project Project to test.
+ * @returns {boolean} Whether the project name is an allowed scope.
+ */
+/**
+ * Commitlint rule configuration tuple for `scope-enum`. The severity `2` is an error.
+ *
+ * @typedef {[2, 'always', string[]]} ScopeEnumRuleConfig
+ */
+/**
+ * Helpers exposed for consumers that extend the shared configuration.
+ *
+ * @typedef {object} CommitlintConfigUtils
+ * @property {typeof getProjects} getProjects Lists Nx project names usable as commit scopes.
+ * @property {typeof isNxSelfHealingCommit} isNxSelfHealingCommit Detects Nx Cloud self-healing CI commits.
+ */
+/**
+ * Shared commitlint configuration.
+ *
+ * @typedef {object} CommitlintConfig
+ * @property {string[]} extends Configurations this configuration builds on.
+ * @property {((message: string) => boolean)[]} ignores Predicates for commit messages commitlint skips.
+ * @property {{ 'scope-enum': (ctx?: CommitlintContext) => Promise<ScopeEnumRuleConfig> }} rules Rule overrides.
+ * @property {CommitlintConfigUtils} utils Helpers for extending the configuration.
+ */
+/** Matches the marker Nx Cloud adds to commits created by self-healing CI reruns. */
+const NX_SELF_HEALING_RERUN_PATTERN = /\[Self-Healing CI Rerun\]/iu;
+/**
+ * Checks whether a commit was produced by Nx Cloud's self-healing CI.
+ *
+ * @param {string} message The complete commit message.
+ * @returns {boolean} Whether commitlint should ignore the message.
+ */
+function isNxSelfHealingCommit(message) {
+    return NX_SELF_HEALING_RERUN_PATTERN.test(message);
+}
+/**
+ * Lists the Nx project names in the workspace, for use as commit scopes. Scoped names such as
+ * `@org/name` are reduced to `name`.
+ *
+ * @param {CommitlintContext} [ctx] Commitlint context; its `cwd` locates the workspace.
+ * @param {ProjectSelector} [selector] Optional filter applied to each project.
+ * @returns {string[]} Matching project names, or an empty list when `cwd` has no `nx.json`.
+ */
+function getProjects(ctx, selector) {
+    const cwd = ctx?.cwd || process.cwd();
+    if (!fs.existsSync(path.join(cwd, 'nx.json'))) {
+        return [];
+    }
+    return nxScopes.utils.getProjects({ ...ctx, cwd }, selector);
+}
+/** @type {CommitlintConfig} */
+const config = {
+    extends: ['@commitlint/config-conventional'],
+    ignores: [isNxSelfHealingCommit],
+    rules: {
+        'scope-enum': async (ctx) => [2, 'always', getProjects(ctx)],
+    },
+    utils: { getProjects, isNxSelfHealingCommit },
+};
+export default config;

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@atlasng/commitlint-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Shared commitlint configuration with Nx project scopes for AtlasNG and related Nx workspaces",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cns-iu/AtlasNG",
+    "directory": "libs/tooling/commitlint-config"
+  },
+  "homepage": "https://github.com/cns-iu/AtlasNG/tree/main/libs/tooling/commitlint-config",
+  "bugs": {
+    "url": "https://github.com/cns-iu/AtlasNG/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@commitlint/config-conventional": "^21.2.2",
+    "@commitlint/config-nx-scopes": "^21.2.0"
+  },
+  "peerDependencies": {
+    "@commitlint/cli": "^21.0.0"
+  },
+  "types": "./index.d.ts",
+  "module": "./index.js",
+  "main": "./index.js"
 }