@blumintinc/eslint-plugin-blumint 1.18.16 → 1.19.0

package/lib/rules/prefer-union-from-const-array.d.ts

@@ -0,0 +1,3 @@
+import { TSESLint } from '@typescript-eslint/utils';
+export declare const preferUnionFromConstArray: TSESLint.RuleModule<"preferDerivedUnion", [], TSESLint.RuleListener>;
+export default preferUnionFromConstArray;

package/lib/rules/prefer-union-from-const-array.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preferUnionFromConstArray = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+/**
+ * Mechanically derive an UPPER_SNAKE constant base from a PascalCase/camelCase
+ * type name by inserting `_` at every lowercase/digit-to-uppercase boundary and
+ * uppercasing. `TournamentActionId` -> `TOURNAMENT_ACTION_ID`. Acronym runs stay
+ * glued together (`HTTPStatus` -> `HTTPSTATUS`), which is an acceptable simple
+ * behavior per the spec since no reliable acronym segmentation exists.
+ */
+function toUpperSnake(name) {
+    return name
+        .split(/(?<=[a-z0-9])(?=[A-Z])/)
+        .join('_')
+        .toUpperCase();
+}
+/**
+ * A union member qualifies only when it is a string-literal type. Numbers,
+ * `null`, `undefined`, `string`, template-literal types, and type references
+ * all fail this guard and disqualify the entire union (string-literal-only).
+ */
+function isStringLiteralType(member) {
+    if (member.type !== utils_1.AST_NODE_TYPES.TSLiteralType) {
+        return false;
+    }
+    const { literal } = member;
+    return (literal.type === utils_1.AST_NODE_TYPES.Literal && typeof literal.value === 'string');
+}
+/**
+ * Walk the scope chain upward collecting declared variable names. Used to skip
+ * the autofix (report-only) when the derived `{TYPE}_VALUES` name is already
+ * bound, so the fix never shadows or duplicates an existing identifier.
+ */
+function isNameInScope(scope, name) {
+    let current = scope;
+    while (current) {
+        if (current.variables.some((variable) => variable.name === name)) {
+            return true;
+        }
+        current = current.upper;
+    }
+    return false;
+}
+exports.preferUnionFromConstArray = (0, createRule_1.createRule)({
+    name: 'prefer-union-from-const-array',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Derive string-literal union types from an `as const` array instead of declaring the union inline, so the runtime value set and the type share a single source of truth',
+            recommended: 'error',
+        },
+        fixable: 'code',
+        schema: [],
+        messages: {
+            preferDerivedUnion: 'Derive this union from an `as const` array: `const {{constName}} = [...] as const; type {{typeName}} = (typeof {{constName}})[number];`. This tethers the type to importable runtime values and prevents silent drift. Consider also naming each literal as its own exported constant so call sites never repeat magic strings.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        return {
+            TSTypeAliasDeclaration(node) {
+                const { typeAnnotation } = node;
+                if (typeAnnotation.type !== utils_1.AST_NODE_TYPES.TSUnionType) {
+                    return;
+                }
+                const members = typeAnnotation.types;
+                // A single-member "union" is not a TSUnionType, but guard anyway; only
+                // multi-member unions are in scope.
+                if (members.length < 2) {
+                    return;
+                }
+                // Every member must be a string literal; any other member kind
+                // (number, null, undefined, string, template literal, type reference)
+                // disqualifies the whole union.
+                if (!members.every(isStringLiteralType)) {
+                    return;
+                }
+                const typeName = node.id.name;
+                const constName = `${toUpperSnake(typeName)}_VALUES`;
+                // The type alias is exported when wrapped in `export type X = ...`
+                // (a local export declaration, not a re-export with a `source`).
+                const isExported = node.parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+                    !node.parent.source;
+                const fixNode = isExported
+                    ? node.parent
+                    : node;
+                // Skip the fix (report-only) when the derived const name already exists
+                // in scope, to avoid shadowing/duplicating an existing declaration.
+                const hasCollision = isNameInScope(context.getScope(), constName);
+                if (hasCollision) {
+                    context.report({
+                        node,
+                        messageId: 'preferDerivedUnion',
+                        data: { constName, typeName },
+                    });
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: 'preferDerivedUnion',
+                    data: { constName, typeName },
+                    fix(fixer) {
+                        const literals = members
+                            .map((member) => {
+                            const literal = member.literal;
+                            return literal.raw ?? sourceCode.getText(literal);
+                        })
+                            .join(', ');
+                        const typeParams = node.typeParameters
+                            ? sourceCode.getText(node.typeParameters)
+                            : '';
+                        const constKeyword = isExported ? 'export const' : 'const';
+                        const typeKeyword = isExported ? 'export type' : 'type';
+                        // Preserve the declaration's own indentation for the second line;
+                        // the first line reuses the original leading whitespace (untouched
+                        // because the fix range starts at the `export`/`type` keyword, not
+                        // at the start of the line — this also leaves leading comments in
+                        // place).
+                        const lineText = sourceCode.lines[fixNode.loc.start.line - 1] ?? '';
+                        const indentMatch = lineText
+                            .slice(0, fixNode.loc.start.column)
+                            .match(/^\s*/);
+                        const indent = indentMatch ? indentMatch[0] : '';
+                        const constDecl = `${constKeyword} ${constName} = [${literals}] as const;`;
+                        const typeDecl = `${typeKeyword} ${typeName}${typeParams} = (typeof ${constName})[number];`;
+                        return fixer.replaceText(fixNode, `${constDecl}\n${indent}${typeDecl}`);
+                    },
+                });
+            },
+        };
+    },
+});
+exports.default = exports.preferUnionFromConstArray;
+//# sourceMappingURL=prefer-union-from-const-array.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.18.16",
+  "version": "1.19.0",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,50 @@
 [
+  {
+    "version": "1.19.0",
+    "date": "2026-07-13T23:57:00.324Z",
+    "rules": [
+      {
+        "name": "enforce-single-exported-unit-per-file",
+        "changeType": "feat",
+        "issues": [
+          1295
+        ],
+        "summary": "limit each file to one exported component/class (closes #1295)"
+      },
+      {
+        "name": "no-harness-coupled-disables",
+        "changeType": "feat",
+        "issues": [
+          1296
+        ],
+        "summary": "flag eslint-disable justifications coupled to the dev harness (closes #1296)"
+      },
+      {
+        "name": "prefer-clone-deep",
+        "changeType": "fix",
+        "issues": [
+          1299
+        ],
+        "summary": "stop flagging top-level spread beside a sibling nested object (closes #1299)"
+      },
+      {
+        "name": "prefer-map-over-conditional-dispatch",
+        "changeType": "feat",
+        "issues": [
+          1298
+        ],
+        "summary": "flag literal-union dispatch that should be a Record lookup (closes #1298)"
+      },
+      {
+        "name": "prefer-union-from-const-array",
+        "changeType": "feat",
+        "issues": [
+          1297
+        ],
+        "summary": "derive string-literal union types from an as-const array (closes #1297)"
+      }
+    ]
+  },
   {
     "version": "1.18.16",
     "date": "2026-07-13T17:31:09.661Z",