@brnshkr/config 0.0.1-beta.2 → 0.0.1-beta.3

package/README.md

@@ -190,7 +190,7 @@ bun eslint --config ./conf/eslint.config.mjs --cache --cache-location ./.cache/e
 Example call, adjust as needed
 
 ```sh
-bun stylelint --config ./conf/stylelint.config.mjs --cache --cache-location ./.cache/stylelint.cache.json **/*.{css,ejs,html,less,postcss,scss,svelte,svg,vue}
+bun stylelint --config ./conf/stylelint.config.mjs --config-basedir ./ --cache --cache-location ./.cache/stylelint.cache.json **/*.{css,ejs,html,less,postcss,scss,svelte,svg,vue}
 ```
 
 <!-- omit in toc -->
@@ -275,7 +275,7 @@ Here are some frequently used examples:
 #### Composer
 
 ```sh
-composer req --dev brnshkr/config
+composer r --dev brnshkr/config
 ```
 
 This repository provides two ways to integrate configuration files and setup tools into your project:
@@ -604,7 +604,6 @@ Here are some frequently used examples (see `make help` for the complete list):
 - Add setup command for JS package (like `composer brnshkr:config:setup`)
 - Expand [`⚙️ Worflows`](#️-workflows) section in readme
 - Write sections about custom PHPStan and ESLint rules
-- Add all around support for enforcing TypeScript aliases with ESLint
 - Add Vue support
 - Add React support
 - Add Tailwind support via <https://github.com/schoero/eslint-plugin-better-tailwindcss>
@@ -645,7 +644,9 @@ See [./.github/workflows](https://github.com/brnshkr/config/blob/master/.github/
 
 This project follows [Semantic Versioning 2.0.0][semver-2.0.0-url].  
 The NPM and Composer packages are versioned in sync, so a version change does not necessarily indicate a change in a specific package.  
-Also please note the following additional information:
+
+> ❗ **Note** ❗  
+> Since changes to rules and dependencies are not considered breaking, even a patch release may introduce new errors in code that hasn't changed and break your CI without notice. We therefore strongly recommend pinning to an exact version (`-E` for the JS package managers, `composer r --dev brnshkr/config:X.Y.Z` for Composer) so updates stay opt-in and can be applied on your own schedule.
 
 <!-- omit in toc -->
 ### Changes Considered as Breaking Changes

package/dist/eslint/index.d.mts

@@ -125,6 +125,10 @@ interface RuleOptions {
    * @deprecated
    */
   'brace-style'?: Linter.RuleEntry<BraceStyle>;
+  /**
+   * Require imports to use TypeScript path aliases when the target file is reachable through a configured alias.
+   */
+  'brnshkr/require-import-alias'?: Linter.RuleEntry<BrnshkrRequireImportAlias>;
   /**
    * Require non-JavaScript imports (e.g. .json and .css) to include import attributes.
    */
@@ -6522,6 +6526,13 @@ type ArrowSpacing = [] | [{
 type BlockSpacing = [] | [("always" | "never")]; // ----- brace-style -----
 type BraceStyle = [] | [("1tbs" | "stroustrup" | "allman")] | [("1tbs" | "stroustrup" | "allman"), {
   allowSingleLine?: boolean;
+}]; // ----- brnshkr/require-import-alias -----
+type BrnshkrRequireImportAlias = [] | [{
+  aliases?: {
+    [k: string]: string[] | undefined;
+  };
+  tsConfigPath?: string;
+  ignoredPaths?: string[];
 }]; // ----- callback-return -----
 type CallbackReturn = [] | [string[]]; // ----- camelcase -----
 type Camelcase = [] | [{

package/dist/eslint/index.mjs

@@ -1,10 +1,10 @@
-import { c as objectAssign, d as objectFromEntries, f as objectKeys, h as version, i as resolvePackagesSharedAsynchronously, l as objectEntries, m as packageOrganizationUpper, n as GLOB_IGNORES, o as ESLINT_PACKAGES, p as packageOrganization, r as isModuleEnabledByDefault, t as QUOTES, u as objectFreeze } from "../shared.mjs";
+import { c as objectAssign, d as packageOrganization, f as packageOrganizationUpper, i as resolvePackagesSharedAsynchronously, l as objectEntries, n as GLOB_IGNORES, o as ESLINT_PACKAGES, p as version, r as isModuleEnabledByDefault, t as QUOTES, u as objectFromEntries } from "../shared.mjs";
 import { FlatConfigComposer } from "eslint-flat-config-utils";
+import fs from "node:fs";
+import path from "node:path";
 import jsEslint from "@eslint/js";
 import confusingBrowserGlobals from "confusing-browser-globals";
 import globals from "globals";
-import fs from "node:fs/promises";
-import path from "node:path";
 //#region ../src/js/eslint/types/scopes.ts
 const MAIN_SCOPES = {
 	[packageOrganizationUpper]: "builtin",
@@ -118,7 +118,182 @@ const GLOB_TEST_FILES = [
 	"**/*.benchmark.?(c|m)[jt]s"
 ];
 //#endregion
-//#region ../src/js/eslint/configs/builtin.ts
+//#region ../src/js/eslint/utils/tsconfig.ts
+const DEFAULT_TSCONFIG_FILENAME = "tsconfig.json";
+const JSONC_TOKEN_PATTERN = /"(?:[^"\\]|\\.)*"|\/\/[^\n]*|\/\*[\s\S]*?\*\//gv;
+const TRAILING_COMMA_PATTERN = /,(?=\s*[\]\}])/gv;
+const stripJsonc = (input) => input.replaceAll(JSONC_TOKEN_PATTERN, (match) => match.startsWith("\"") ? match : "").replaceAll(TRAILING_COMMA_PATTERN, "");
+const parseTsConfigFile = (filePath) => {
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		return JSON.parse(stripJsonc(content));
+	} catch {
+		return;
+	}
+};
+const resolveExtends = (extendsValue, fromDirectory) => {
+	if (extendsValue.startsWith(".") || path.isAbsolute(extendsValue)) {
+		const resolved = path.resolve(fromDirectory, extendsValue);
+		return path.extname(resolved) === "" ? `${resolved}.json` : resolved;
+	}
+	return path.resolve(fromDirectory, "node_modules", extendsValue);
+};
+const normalizeExtends = (raw) => {
+	if (raw.extends === void 0) return [];
+	return Array.isArray(raw.extends) ? raw.extends : [raw.extends];
+};
+const loadInternal = (filePath, visitedPaths) => {
+	if (visitedPaths.has(filePath)) return;
+	visitedPaths.add(filePath);
+	const parsedConfig = parseTsConfigFile(filePath);
+	if (!parsedConfig) return;
+	const fromDirectory = path.dirname(filePath);
+	let compilerOptions = {};
+	for (const value of normalizeExtends(parsedConfig)) compilerOptions = {
+		...compilerOptions,
+		...loadInternal(resolveExtends(value, fromDirectory), visitedPaths)?.compilerOptions
+	};
+	return { compilerOptions: {
+		...compilerOptions,
+		...parsedConfig.compilerOptions
+	} };
+};
+const cache = /* @__PURE__ */ new Map();
+const toPosix$1 = (filePath) => filePath.replaceAll("\\", "/");
+const loadTsConfigPaths = (tsConfigPath) => {
+	const absolutePath = path.resolve(tsConfigPath);
+	if (cache.has(absolutePath)) return cache.get(absolutePath);
+	const mergedConfig = loadInternal(absolutePath, /* @__PURE__ */ new Set());
+	const paths = mergedConfig?.compilerOptions?.paths;
+	if (!paths) {
+		cache.set(absolutePath, void 0);
+		return;
+	}
+	const baseUrl = path.resolve(path.dirname(absolutePath), mergedConfig.compilerOptions?.baseUrl ?? ".");
+	const result = objectFromEntries(objectEntries(paths).map(([pattern, targets]) => [pattern, targets.map((target) => toPosix$1(path.resolve(baseUrl, target)))]));
+	cache.set(absolutePath, result);
+	return result;
+};
+const doesTsConfigExist = (tsConfigPath) => {
+	try {
+		fs.accessSync(tsConfigPath, fs.constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const resolveTsConfigPath = (typescriptOptions) => {
+	let tsconfig = DEFAULT_TSCONFIG_FILENAME;
+	if (typescriptOptions) {
+		if (typeof typescriptOptions.typeAware === "string") tsconfig = typescriptOptions.typeAware;
+		else if (typeof typescriptOptions.typeAware === "object") tsconfig = typescriptOptions.typeAware.tsconfig ?? DEFAULT_TSCONFIG_FILENAME;
+	}
+	return path.resolve(process.cwd(), tsconfig);
+};
+//#endregion
+//#region ../src/js/eslint/configs/builtin/require-import-alias.ts
+const MESSAGE_ID_PREFER_ALIAS = "preferAlias";
+const MESSAGE_ID_MISSING_ALIAS = "missingAlias";
+const WILDCARD_SUFFIX = "/*";
+const WILDCARD_SUFFIX_LENGTH = 2;
+const RELATIVE_SPECIFIER_PREFIXES = ["./", "../"];
+const resolveAliases = (options) => options.aliases ?? loadTsConfigPaths(options.tsConfigPath ?? resolveTsConfigPath()) ?? {};
+const toPosix = (value) => value.replaceAll("\\", "/");
+const buildAliasMappings = (aliases) => objectEntries(aliases).filter(([pattern]) => pattern.endsWith(WILDCARD_SUFFIX)).flatMap(([pattern, targets]) => {
+	const prefix = pattern.slice(0, -WILDCARD_SUFFIX_LENGTH);
+	return targets.filter((target) => target.endsWith(WILDCARD_SUFFIX)).map((target) => ({
+		prefix,
+		baseDirectory: toPosix(target).slice(0, -WILDCARD_SUFFIX_LENGTH)
+	}));
+}).toSorted((left, right) => right.baseDirectory.length - left.baseDirectory.length);
+const findAliasReplacement = (mappings, absolutePath) => {
+	for (const { prefix, baseDirectory } of mappings) {
+		if (absolutePath === baseDirectory) return prefix;
+		if (absolutePath.startsWith(`${baseDirectory}/`)) return `${prefix}/${absolutePath.slice(baseDirectory.length + 1)}`;
+	}
+};
+const isRelativeSpecifier = (source) => RELATIVE_SPECIFIER_PREFIXES.some((prefix) => source.startsWith(prefix));
+const isAlreadyAliased = (source, mappings) => mappings.some(({ prefix }) => source === prefix || source.startsWith(`${prefix}/`));
+const isFileIgnored = (filename, patterns) => patterns.some((pattern) => path.matchesGlob(toPosix(filename), pattern) || path.matchesGlob(toPosix(path.relative(process.cwd(), filename)), pattern));
+const getQuote = (sourceNode) => "raw" in sourceNode && typeof sourceNode.raw === "string" && sourceNode.raw.startsWith("\"") ? "\"" : "'";
+const requireImportAliasRule = {
+	meta: {
+		type: "suggestion",
+		fixable: "code",
+		docs: { description: "Require imports to use TypeScript path aliases when the target file is reachable through a configured alias." },
+		schema: [{
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				aliases: {
+					type: "object",
+					additionalProperties: {
+						type: "array",
+						items: { type: "string" }
+					}
+				},
+				tsConfigPath: { type: "string" },
+				ignoredPaths: {
+					type: "array",
+					items: { type: "string" }
+				}
+			}
+		}],
+		messages: {
+			[MESSAGE_ID_PREFER_ALIAS]: "Import path '{{ source }}' must use the configured alias '{{ alias }}'.",
+			[MESSAGE_ID_MISSING_ALIAS]: "Import path '{{ source }}' resolves outside any configured TypeScript path alias. Add an alias for this location, remove all other aliases, or disable this rule."
+		}
+	},
+	create: (context) => {
+		const options = context.options[0] ?? {};
+		const ignoredPaths = options.ignoredPaths ?? [];
+		const mappings = buildAliasMappings(resolveAliases(options));
+		if (mappings.length === 0 || isFileIgnored(context.filename, ignoredPaths)) return {};
+		const fileDirectory = toPosix(path.dirname(context.filename));
+		const checkSource = (sourceNode) => {
+			if (sourceNode?.type !== "Literal" || typeof sourceNode.value !== "string") return;
+			const source = sourceNode.value;
+			if (!isRelativeSpecifier(source) || isAlreadyAliased(source, mappings)) return;
+			const replacement = findAliasReplacement(mappings, path.posix.normalize(`${fileDirectory}/${source}`));
+			if (replacement === void 0) {
+				context.report({
+					node: sourceNode,
+					messageId: MESSAGE_ID_MISSING_ALIAS,
+					data: { source }
+				});
+				return;
+			}
+			context.report({
+				node: sourceNode,
+				messageId: MESSAGE_ID_PREFER_ALIAS,
+				data: {
+					source,
+					alias: replacement
+				},
+				fix: (fixer) => fixer.replaceText(sourceNode, `${getQuote(sourceNode)}${replacement}${getQuote(sourceNode)}`)
+			});
+		};
+		return {
+			ImportDeclaration: (node) => {
+				checkSource(node.source);
+			},
+			ExportNamedDeclaration: (node) => {
+				checkSource(node.source);
+			},
+			ExportAllDeclaration: (node) => {
+				checkSource(node.source);
+			},
+			ImportExpression: (node) => {
+				checkSource(node.source);
+			}
+		};
+	}
+};
+//#endregion
+//#region ../src/js/eslint/configs/builtin/require-import-attributes.ts
+const MESSAGE_ID_MISSING_WITH_KEYWORD = "missingWithKeyword";
+const MESSAGE_ID_MISSING_TYPE_PROPERTY = "missingTypeProperty";
+const MESSAGE_ID_WRONG_TYPE_VALUE = "wrongTypeValue";
 const FILE_TYPE_MAP = {
 	".json": "json",
 	".css": "css",
@@ -130,58 +305,59 @@ const FILE_TYPE_MAP = {
 	".oct": "bytes",
 	".wasm": "webassembly"
 };
-const MESSAGE_ID_MISSING_WITH_KEYWORD = "missingWithKeyword";
-const MESSAGE_ID_MISSING_TYPE_PROPERTY = "missingTypeProperty";
-const MESSAGE_ID_WRONG_TYPE_VALUE = "wrongTypeValue";
-const RULE_DEFINITIONS = { "require-import-attributes": {
-	meta: {
-		type: "problem",
-		docs: { description: "Require non-JavaScript imports (e.g. .json and .css) to include import attributes." },
-		messages: {
-			[MESSAGE_ID_MISSING_WITH_KEYWORD]: "Non-JavaScript import ('{{ extension }}') requires an import attributes object with the 'type' property set to '{{ expectedValue }}'.",
-			[MESSAGE_ID_MISSING_TYPE_PROPERTY]: "Import attributes for non-JavaScript imports must include the 'type' property.",
-			[MESSAGE_ID_WRONG_TYPE_VALUE]: "Import attribute 'type' for '{{ file }}' must be '{{ expectedValue }}'."
-		}
-	},
-	create: (context) => ({ ImportDeclaration: (node) => {
-		const sourceValue = node.source.value;
-		const extensionIndex = sourceValue.lastIndexOf(".");
-		if (extensionIndex === -1) return;
-		const extension = sourceValue.slice(extensionIndex).toLowerCase();
-		const expectedValue = FILE_TYPE_MAP[extension];
-		if (expectedValue === void 0) return;
-		const { attributes } = node;
-		if (attributes.length === 0) {
-			context.report({
+//#endregion
+//#region ../src/js/eslint/configs/builtin/index.ts
+const RULE_DEFINITIONS = {
+	"require-import-attributes": {
+		meta: {
+			type: "problem",
+			docs: { description: "Require non-JavaScript imports (e.g. .json and .css) to include import attributes." },
+			messages: {
+				[MESSAGE_ID_MISSING_WITH_KEYWORD]: "Non-JavaScript import ('{{ extension }}') requires an import attributes object with the 'type' property set to '{{ expectedValue }}'.",
+				[MESSAGE_ID_MISSING_TYPE_PROPERTY]: "Import attributes for non-JavaScript imports must include the 'type' property.",
+				[MESSAGE_ID_WRONG_TYPE_VALUE]: "Import attribute 'type' for '{{ file }}' must be '{{ expectedValue }}'."
+			}
+		},
+		create: (context) => ({ ImportDeclaration: (node) => {
+			const sourceValue = node.source.value;
+			const extensionIndex = sourceValue.lastIndexOf(".");
+			if (extensionIndex === -1) return;
+			const extension = sourceValue.slice(extensionIndex).toLowerCase();
+			const expectedValue = FILE_TYPE_MAP[extension];
+			if (expectedValue === void 0) return;
+			const { attributes } = node;
+			if (attributes.length === 0) {
+				context.report({
+					node,
+					messageId: MESSAGE_ID_MISSING_WITH_KEYWORD,
+					data: {
+						extension,
+						expectedValue
+					}
+				});
+				return;
+			}
+			const typeProperty = attributes.find((attribute) => attribute.key.type === "Identifier" && "name" in attribute.key && attribute.key.name === "type" || attribute.key.type === "Literal" && "value" in attribute.key && attribute.key.value === "type");
+			if (!typeProperty) {
+				context.report({
+					node,
+					messageId: MESSAGE_ID_MISSING_TYPE_PROPERTY
+				});
+				return;
+			}
+			if (typeProperty.value.value !== expectedValue) context.report({
 				node,
-				messageId: MESSAGE_ID_MISSING_WITH_KEYWORD,
+				messageId: MESSAGE_ID_WRONG_TYPE_VALUE,
 				data: {
-					extension,
-					expectedValue
+					expectedValue,
+					file: sourceValue
 				}
 			});
-			return;
-		}
-		const typeProperty = attributes.find((attribute) => attribute.key.type === "Identifier" && "name" in attribute.key && attribute.key.name === "type" || attribute.key.type === "Literal" && "value" in attribute.key && attribute.key.value === "type");
-		if (!typeProperty) {
-			context.report({
-				node,
-				messageId: MESSAGE_ID_MISSING_TYPE_PROPERTY
-			});
-			return;
-		}
-		if (typeProperty.value.value !== expectedValue) context.report({
-			node,
-			messageId: MESSAGE_ID_WRONG_TYPE_VALUE,
-			data: {
-				expectedValue,
-				file: sourceValue
-			}
-		});
-	} })
-} };
-const RULES = objectFreeze(objectFromEntries(objectKeys(RULE_DEFINITIONS).map((ruleName) => [`${packageOrganization}/${ruleName}`, "error"])));
-const builtin = () => [{
+		} })
+	},
+	"require-import-alias": requireImportAliasRule
+};
+const builtin = (typescriptOptions) => [{
 	name: buildConfigName(MAIN_SCOPES[packageOrganizationUpper], SUB_SCOPES.SETUP),
 	plugins: { [packageOrganization]: {
 		meta: {
@@ -193,7 +369,10 @@ const builtin = () => [{
 }, {
 	name: buildConfigName(MAIN_SCOPES[packageOrganizationUpper], SUB_SCOPES.RULES),
 	files: GLOB_SCRIPT_FILES,
-	rules: RULES
+	rules: {
+		[`${packageOrganization}/require-import-alias`]: ["error", { tsConfigPath: resolveTsConfigPath(typeof typescriptOptions === "object" ? typescriptOptions : void 0) }],
+		[`${packageOrganization}/require-import-attributes`]: "error"
+	}
 }];
 const builtinConfig = { [packageOrganization]: builtin };
 //#endregion
@@ -817,15 +996,10 @@ const typescript = async (options) => {
 	if (!isTypescriptInstalled || !tsEslint) return [];
 	const { optional: [, pluginUnusedImports] } = await resolvePackages(MODULES.javascript);
 	const cwd = process.cwd();
-	let hasTsConfig = false;
-	try {
-		await fs.access(path.resolve(cwd, "tsconfig.json"), fs.constants.R_OK);
-		hasTsConfig = true;
-	} catch {}
 	const resolvedOptions = {
 		extraFileExtensions: [],
 		parserOptions: {},
-		typeAware: hasTsConfig,
+		typeAware: doesTsConfigExist(resolveTsConfigPath(options)),
 		...options
 	};
 	const ignores = resolvedOptions.ignores ?? [];
@@ -2634,7 +2808,7 @@ const getConfig = (optionsAndGlobalConfig, ...additionalConfigs) => {
 	if (isModuleEnabled(MODULES.test)) appendToComposer(configs.test());
 	if (isModuleEnabled(MODULES.jsdoc)) appendToComposer(configs.jsdoc());
 	if (isModuleEnabled(MODULES.node)) appendToComposer(configs.node(typeof resolvedOptions.node === "object" ? resolvedOptions.node : void 0));
-	if (isModuleEnabled(MODULES[packageOrganization])) appendToComposer(configs[packageOrganization]());
+	if (isModuleEnabled(MODULES[packageOrganization])) appendToComposer(configs[packageOrganization](resolvedOptions.typescript));
 	if (isModuleEnabled(MODULES.comments)) appendToComposer(configs.comments());
 	if (isModuleEnabled(MODULES.regexp)) appendToComposer(configs.regexp());
 	if (isModuleEnabled(MODULES.unicorn)) appendToComposer(configs.unicorn());

package/dist/scripts/stylelint.mjs

@@ -16,6 +16,8 @@ spawn("bun", [
 	"stylelint",
 	"--config",
 	"./conf/stylelint.config.mjs",
+	"--config-basedir",
+	"./",
 	"--cache",
 	"--cache-location",
 	"./.cache/stylelint.cache.json",

package/dist/shared.mjs

@@ -1,7 +1,7 @@
 import { isPackageExists } from "local-pkg";
 //#region ../package.json
 var name = "@brnshkr/config";
-var version = "0.0.1-beta.2";
+var version = "0.0.1-beta.3";
 //#endregion
 //#region ../src/js/shared/utils/package-json.ts
 const packageOrganizationInternal = name.split("/").at(0)?.replace(/^@/v, "");
@@ -16,10 +16,8 @@ const log = (type, message, context) => {
 };
 //#endregion
 //#region ../src/js/shared/utils/object.ts
-const objectKeys = (object) => Object.keys(object);
 const objectEntries = (object) => Object.entries(object);
 const objectFromEntries = (entries) => Object.fromEntries(entries);
-const objectFreeze = (object) => Object.freeze(object);
 const objectAssign = (target, source) => Object.assign(target, source);
 //#endregion
 //#region ../src/js/shared/utils/interop-import.ts
@@ -230,4 +228,4 @@ const GLOB_IGNORES = [
 //#region ../src/js/shared/utils/constants.ts
 const QUOTES = "single";
 //#endregion
-export { resolvePackagesSharedSynchronously as a, objectAssign as c, objectFromEntries as d, objectKeys as f, version as h, resolvePackagesSharedAsynchronously as i, objectEntries as l, packageOrganizationUpper as m, GLOB_IGNORES as n, ESLINT_PACKAGES as o, packageOrganization as p, isModuleEnabledByDefault as r, STYLELINT_PACKAGES as s, QUOTES as t, objectFreeze as u };
+export { resolvePackagesSharedSynchronously as a, objectAssign as c, packageOrganization as d, packageOrganizationUpper as f, resolvePackagesSharedAsynchronously as i, objectEntries as l, GLOB_IGNORES as n, ESLINT_PACKAGES as o, version as p, isModuleEnabledByDefault as r, STYLELINT_PACKAGES as s, QUOTES as t, objectFromEntries as u };

package/dist/stylelint/index.mjs

@@ -1,4 +1,4 @@
-import { a as resolvePackagesSharedSynchronously, l as objectEntries, n as GLOB_IGNORES, p as packageOrganization, r as isModuleEnabledByDefault, s as STYLELINT_PACKAGES, t as QUOTES } from "../shared.mjs";
+import { a as resolvePackagesSharedSynchronously, d as packageOrganization, l as objectEntries, n as GLOB_IGNORES, r as isModuleEnabledByDefault, s as STYLELINT_PACKAGES, t as QUOTES } from "../shared.mjs";
 //#region ../src/js/stylelint/utils/module.ts
 const MODULES = {
 	baseline: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@brnshkr/config",
-  "version": "0.0.1-beta.2",
+  "version": "0.0.1-beta.3",
   "description": "Centralized collection of configuration and tooling used across all @brnshkr projects",
   "license": "MIT",
   "author": "Patrick Rupp",