styles-config 2.0.0-alpha.1 → 2.0.0-alpha.11

package/README.md

@@ -1,10 +1,19 @@
 # styles-config
 
-A general-purpose configuration system for styling frameworks including Jess, Less, Sass, Tailwind, and more.
+**A shared configuration schema and loader for styling tools (Jess, Less, Sass,
+Tailwind, …).**
+
+`styles-config` is part of the [Jess](https://github.com/jesscss/jess) project.
+It is published **unscoped** — the package name is `styles-config`, not
+`@jesscss/config`.
 
 ## Overview
 
-`styles-config` provides a unified configuration format and loading system that works across multiple CSS preprocessors and styling frameworks. It allows you to define configuration once and use it with different tools, or maintain separate configurations for different frameworks.
+`styles-config` provides a unified configuration format and loading system that
+works across multiple CSS preprocessors and styling frameworks. It lets you define
+configuration once and use it with different tools, or maintain separate
+configurations for different frameworks. Jess itself reads its compile options
+through this loader.
 
 ## Features
 
@@ -16,14 +25,12 @@ A general-purpose configuration system for styling frameworks including Jess, Le
 
 ## Installation
 
-```bash
+```sh
 npm install styles-config
-# or
-pnpm add styles-config
-# or
-yarn add styles-config
 ```
 
+Published to npm under both the `latest` and `alpha` dist-tags.
+
 ## Configuration File Format
 
 Create a configuration file in your project root. Supported file names:
@@ -39,8 +46,9 @@ interface StylesConfig {
     searchPaths?: string[];
     enableJavaScript?: boolean;
     mathMode?: 'always' | 'parens-division' | 'parens' | 'strict';
-    unitMode?: 'loose' | 'strict';
-    equalityMode?: 'coerce' | 'strict';
+    unitMode?: 'loose' | 'preserve' | 'strict';
+    functionMode?: 'preserve' | 'error';
+    equalityMode?: 'less' | 'sass' | 'exact';
   };
   input?: InputOptions | InputOptions[];
   output?: OutputOptions | OutputOptions[];
@@ -78,7 +86,7 @@ export default {
   compile: {
     mathMode: 'parens-division',
     unitMode: 'loose',
-    equalityMode: 'coerce',
+    equalityMode: 'less',
     searchPaths: ['./src/styles', './node_modules']
   },
   input: [
@@ -320,6 +328,16 @@ This package is designed to be extensible. To add support for a new framework:
 2. Add the extension mapping in `src/options.ts` if needed
 3. Update the documentation
 
+## Status
+
+Alpha. Part of the Jess monorepo, which is early software under active
+development. Please [report issues](https://github.com/jesscss/jess/issues).
+
+## Links
+
+- Repository: <https://github.com/jesscss/jess>
+- Documentation: <https://jesscss.github.io/> (currently pre-alpha content)
+
 ## License
 
-MIT
+[MIT](https://github.com/jesscss/jess/blob/dev/LICENSE)

package/lib/index.cjs

@@ -0,0 +1,249 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let cosmiconfig = require("cosmiconfig");
+let picomatch = require("picomatch");
+picomatch = __toESM(picomatch);
+let path = require("path");
+path = __toESM(path);
+//#region src/loader.ts
+const explorer = (0, cosmiconfig.cosmiconfig)("styles", {
+	searchPlaces: [
+		"styles.config.ts",
+		"styles.config.js",
+		"styles.config.mts",
+		"styles.config.mjs",
+		"styles.config.cjs",
+		"styles.config.cts"
+	],
+	loaders: {
+		".mts": cosmiconfig.defaultLoadersSync[".ts"],
+		".cts": cosmiconfig.defaultLoadersSync[".ts"],
+		".mjs": cosmiconfig.defaultLoadersSync[".js"],
+		".cjs": cosmiconfig.defaultLoadersSync[".cjs"]
+	}
+});
+const explorerSync = (0, cosmiconfig.cosmiconfigSync)("styles", {
+	searchPlaces: [
+		"styles.config.ts",
+		"styles.config.js",
+		"styles.config.mts",
+		"styles.config.mjs",
+		"styles.config.cjs",
+		"styles.config.cts"
+	],
+	loaders: {
+		".mts": cosmiconfig.defaultLoadersSync[".ts"],
+		".cts": cosmiconfig.defaultLoadersSync[".ts"],
+		".mjs": cosmiconfig.defaultLoadersSync[".js"],
+		".cjs": cosmiconfig.defaultLoadersSync[".cjs"]
+	}
+});
+/**
+* Load styles configuration from the file system (async)
+* @param searchFrom - Directory to search from (defaults to process.cwd())
+* @returns Configuration object or null if not found
+*/
+async function loadConfig(searchFrom) {
+	const result = await explorer.search(searchFrom);
+	return result?.config ? normalizeConfig(result.config) : null;
+}
+/**
+* Load styles configuration from the file system (sync)
+* @param searchFrom - Directory to search from (defaults to process.cwd())
+* @returns Configuration object or empty object if not found
+*/
+function loadConfigSync(searchFrom) {
+	const result = explorerSync.search(searchFrom);
+	return result?.config ? normalizeConfig(result.config) : {};
+}
+/**
+* Load styles configuration with metadata (sync).
+* Includes config file path when a config file is discovered.
+*/
+function loadConfigSyncWithMeta(searchFrom) {
+	const result = explorerSync.search(searchFrom);
+	return {
+		config: result?.config ? normalizeConfig(result.config) : {},
+		configFilePath: result?.filepath
+	};
+}
+/**
+* Load styles configuration from a specific file path (async)
+* @param filePath - Path to the config file
+* @returns Configuration object or null if not found
+*/
+async function loadConfigFromPath(filePath) {
+	const result = await explorer.load(filePath);
+	return result?.config ? normalizeConfig(result.config) : null;
+}
+/**
+* Load styles configuration from a specific file path (sync)
+* @param filePath - Path to the config file
+* @returns Configuration object or empty object if not found
+*/
+function loadConfigFromPathSync(filePath) {
+	const result = explorerSync.load(filePath);
+	return result?.config ? normalizeConfig(result.config) : {};
+}
+/**
+* Normalize config object - handle default exports and ensure proper type
+*/
+function isStylesConfig(value) {
+	return typeof value === "object" && value !== null;
+}
+function normalizeConfig(config) {
+	if (isStylesConfig(config) && "default" in config) return normalizeConfig(config.default);
+	if (isStylesConfig(config)) return config;
+	return {};
+}
+//#endregion
+//#region src/options.ts
+/**
+* Expand the `strict` convenience preset. When `strict` is truthy, fills the
+* strict bundle for any governed option left `undefined` — an explicitly set
+* option always wins. Modeled after `tsconfig`'s `strict`: it only *sets*
+* semantic options, it is not itself a mode. Sets the strictest value of each
+* governed axis (`equalityMode: 'exact'` is the no-coercion dialect).
+*
+* Returns a new object (never mutates the input); a no-op when `strict` is falsy.
+*/
+function applyStrictPreset(opts) {
+	if (!opts?.strict) return opts;
+	const filled = { ...opts };
+	filled.unitMode ??= "strict";
+	filled.equalityMode ??= "exact";
+	filled.leakyScope ??= false;
+	filled.allowOverloadedImport ??= false;
+	return filled;
+}
+/**
+* Map of file extensions to language keys
+*/
+const extensionToLanguage = new Map([
+	[".less", "less"],
+	[".scss", "scss"],
+	[".sass", "scss"],
+	[".jess", "jess"],
+	[".css", "css"]
+]);
+/**
+* Infer language from a file path's extension. Exported so a consumer that has
+* to route by dialect (built-in function set, plugin choice) reads the SAME
+* extension map the option resolution uses instead of keeping its own copy.
+*/
+function inferLanguage(filePath) {
+	if (!filePath) return;
+	const ext = path.default.extname(filePath).toLowerCase();
+	return extensionToLanguage.get(ext);
+}
+/**
+* Check if a file path matches a pattern (exact path, relative path, or glob)
+*/
+function matchesFile(pattern, filePath) {
+	if (!pattern || !filePath) return false;
+	const normalizedPattern = path.default.normalize(pattern);
+	const normalizedFile = path.default.normalize(filePath);
+	if (normalizedPattern === normalizedFile) return true;
+	if (path.default.basename(normalizedFile) === normalizedPattern) return true;
+	const isMatch = (0, picomatch.default)(pattern, { dot: true });
+	return isMatch(filePath) || isMatch(normalizedFile);
+}
+/**
+* Get matching options from an array of file-based options.
+* Returns merged options from:
+* 1. All entries without a `file` property (defaults)
+* 2. All entries whose `file` pattern matches the given path
+*
+* Later entries override earlier ones.
+*/
+function getMatchingOptions(options, filePath) {
+	if (!options) return {};
+	const optionsArray = Array.isArray(options) ? options : [options];
+	let result = {};
+	for (const opt of optionsArray) if (!opt.file || filePath && matchesFile(opt.file, filePath)) {
+		const { file, ...rest } = opt;
+		result = {
+			...result,
+			...rest
+		};
+	}
+	return result;
+}
+/**
+* Get merged options by combining compile, language, input, and output settings.
+*
+* Merge priority (later wins):
+* 1. compile options (base)
+* 2. language-specific options (inferred from input extension or explicitly specified)
+* 3. matched input options (if input path provided and matches)
+* 4. matched output options (if output path provided and matches)
+*
+* @param config - The styles configuration object
+* @param params - Options specifying language, input file, and output file
+* @returns Merged options object
+*
+* @example
+* // Get Less options for a specific input/output (language inferred from .less extension)
+* const options = getOptions(config, {
+*   input: 'src/styles/main.less',
+*   output: 'dist/main.css'
+* });
+*
+* @example
+* // Explicitly specify language
+* const options = getOptions(config, { language: 'less' });
+*
+* @example
+* // Get base options without language-specific settings
+* const options = getOptions(config);
+*/
+function getOptions(config = {}, params = {}) {
+	const { input: inputFile, output: outputFile } = params;
+	const { compile = {}, input, output, language: languageConfig = {} } = config;
+	const language = params.language ?? inferLanguage(inputFile);
+	const languageOptions = language ? languageConfig[language] ?? {} : {};
+	const matchedInput = getMatchingOptions(input, inputFile);
+	const matchedOutput = getMatchingOptions(output, outputFile);
+	return {
+		mathMode: compile.mathMode,
+		unitMode: compile.unitMode,
+		equalityMode: compile.equalityMode,
+		allowExtendSelectors: compile.allowExtendSelectors,
+		processImports: compile.processImports,
+		disableScriptModules: compile.disableScriptModules ?? compile.disablePluginRule,
+		paths: compile.searchPaths,
+		...languageOptions,
+		...matchedInput,
+		...matchedOutput
+	};
+}
+//#endregion
+exports.applyStrictPreset = applyStrictPreset;
+exports.getOptions = getOptions;
+exports.inferLanguage = inferLanguage;
+exports.loadConfig = loadConfig;
+exports.loadConfigFromPath = loadConfigFromPath;
+exports.loadConfigFromPathSync = loadConfigFromPathSync;
+exports.loadConfigSync = loadConfigSync;
+exports.loadConfigSyncWithMeta = loadConfigSyncWithMeta;

package/lib/index.js

@@ -1,4 +1,217 @@
-export * from './types.js';
-export * from './loader.js';
-export * from './options.js';
-//# sourceMappingURL=index.js.map
+import { cosmiconfig, cosmiconfigSync, defaultLoadersSync } from "cosmiconfig";
+import picomatch from "picomatch";
+import path from "path";
+//#region src/loader.ts
+const explorer = cosmiconfig("styles", {
+	searchPlaces: [
+		"styles.config.ts",
+		"styles.config.js",
+		"styles.config.mts",
+		"styles.config.mjs",
+		"styles.config.cjs",
+		"styles.config.cts"
+	],
+	loaders: {
+		".mts": defaultLoadersSync[".ts"],
+		".cts": defaultLoadersSync[".ts"],
+		".mjs": defaultLoadersSync[".js"],
+		".cjs": defaultLoadersSync[".cjs"]
+	}
+});
+const explorerSync = cosmiconfigSync("styles", {
+	searchPlaces: [
+		"styles.config.ts",
+		"styles.config.js",
+		"styles.config.mts",
+		"styles.config.mjs",
+		"styles.config.cjs",
+		"styles.config.cts"
+	],
+	loaders: {
+		".mts": defaultLoadersSync[".ts"],
+		".cts": defaultLoadersSync[".ts"],
+		".mjs": defaultLoadersSync[".js"],
+		".cjs": defaultLoadersSync[".cjs"]
+	}
+});
+/**
+* Load styles configuration from the file system (async)
+* @param searchFrom - Directory to search from (defaults to process.cwd())
+* @returns Configuration object or null if not found
+*/
+async function loadConfig(searchFrom) {
+	const result = await explorer.search(searchFrom);
+	return result?.config ? normalizeConfig(result.config) : null;
+}
+/**
+* Load styles configuration from the file system (sync)
+* @param searchFrom - Directory to search from (defaults to process.cwd())
+* @returns Configuration object or empty object if not found
+*/
+function loadConfigSync(searchFrom) {
+	const result = explorerSync.search(searchFrom);
+	return result?.config ? normalizeConfig(result.config) : {};
+}
+/**
+* Load styles configuration with metadata (sync).
+* Includes config file path when a config file is discovered.
+*/
+function loadConfigSyncWithMeta(searchFrom) {
+	const result = explorerSync.search(searchFrom);
+	return {
+		config: result?.config ? normalizeConfig(result.config) : {},
+		configFilePath: result?.filepath
+	};
+}
+/**
+* Load styles configuration from a specific file path (async)
+* @param filePath - Path to the config file
+* @returns Configuration object or null if not found
+*/
+async function loadConfigFromPath(filePath) {
+	const result = await explorer.load(filePath);
+	return result?.config ? normalizeConfig(result.config) : null;
+}
+/**
+* Load styles configuration from a specific file path (sync)
+* @param filePath - Path to the config file
+* @returns Configuration object or empty object if not found
+*/
+function loadConfigFromPathSync(filePath) {
+	const result = explorerSync.load(filePath);
+	return result?.config ? normalizeConfig(result.config) : {};
+}
+/**
+* Normalize config object - handle default exports and ensure proper type
+*/
+function isStylesConfig(value) {
+	return typeof value === "object" && value !== null;
+}
+function normalizeConfig(config) {
+	if (isStylesConfig(config) && "default" in config) return normalizeConfig(config.default);
+	if (isStylesConfig(config)) return config;
+	return {};
+}
+//#endregion
+//#region src/options.ts
+/**
+* Expand the `strict` convenience preset. When `strict` is truthy, fills the
+* strict bundle for any governed option left `undefined` — an explicitly set
+* option always wins. Modeled after `tsconfig`'s `strict`: it only *sets*
+* semantic options, it is not itself a mode. Sets the strictest value of each
+* governed axis (`equalityMode: 'exact'` is the no-coercion dialect).
+*
+* Returns a new object (never mutates the input); a no-op when `strict` is falsy.
+*/
+function applyStrictPreset(opts) {
+	if (!opts?.strict) return opts;
+	const filled = { ...opts };
+	filled.unitMode ??= "strict";
+	filled.equalityMode ??= "exact";
+	filled.leakyScope ??= false;
+	filled.allowOverloadedImport ??= false;
+	return filled;
+}
+/**
+* Map of file extensions to language keys
+*/
+const extensionToLanguage = new Map([
+	[".less", "less"],
+	[".scss", "scss"],
+	[".sass", "scss"],
+	[".jess", "jess"],
+	[".css", "css"]
+]);
+/**
+* Infer language from a file path's extension. Exported so a consumer that has
+* to route by dialect (built-in function set, plugin choice) reads the SAME
+* extension map the option resolution uses instead of keeping its own copy.
+*/
+function inferLanguage(filePath) {
+	if (!filePath) return;
+	const ext = path.extname(filePath).toLowerCase();
+	return extensionToLanguage.get(ext);
+}
+/**
+* Check if a file path matches a pattern (exact path, relative path, or glob)
+*/
+function matchesFile(pattern, filePath) {
+	if (!pattern || !filePath) return false;
+	const normalizedPattern = path.normalize(pattern);
+	const normalizedFile = path.normalize(filePath);
+	if (normalizedPattern === normalizedFile) return true;
+	if (path.basename(normalizedFile) === normalizedPattern) return true;
+	const isMatch = picomatch(pattern, { dot: true });
+	return isMatch(filePath) || isMatch(normalizedFile);
+}
+/**
+* Get matching options from an array of file-based options.
+* Returns merged options from:
+* 1. All entries without a `file` property (defaults)
+* 2. All entries whose `file` pattern matches the given path
+*
+* Later entries override earlier ones.
+*/
+function getMatchingOptions(options, filePath) {
+	if (!options) return {};
+	const optionsArray = Array.isArray(options) ? options : [options];
+	let result = {};
+	for (const opt of optionsArray) if (!opt.file || filePath && matchesFile(opt.file, filePath)) {
+		const { file, ...rest } = opt;
+		result = {
+			...result,
+			...rest
+		};
+	}
+	return result;
+}
+/**
+* Get merged options by combining compile, language, input, and output settings.
+*
+* Merge priority (later wins):
+* 1. compile options (base)
+* 2. language-specific options (inferred from input extension or explicitly specified)
+* 3. matched input options (if input path provided and matches)
+* 4. matched output options (if output path provided and matches)
+*
+* @param config - The styles configuration object
+* @param params - Options specifying language, input file, and output file
+* @returns Merged options object
+*
+* @example
+* // Get Less options for a specific input/output (language inferred from .less extension)
+* const options = getOptions(config, {
+*   input: 'src/styles/main.less',
+*   output: 'dist/main.css'
+* });
+*
+* @example
+* // Explicitly specify language
+* const options = getOptions(config, { language: 'less' });
+*
+* @example
+* // Get base options without language-specific settings
+* const options = getOptions(config);
+*/
+function getOptions(config = {}, params = {}) {
+	const { input: inputFile, output: outputFile } = params;
+	const { compile = {}, input, output, language: languageConfig = {} } = config;
+	const language = params.language ?? inferLanguage(inputFile);
+	const languageOptions = language ? languageConfig[language] ?? {} : {};
+	const matchedInput = getMatchingOptions(input, inputFile);
+	const matchedOutput = getMatchingOptions(output, outputFile);
+	return {
+		mathMode: compile.mathMode,
+		unitMode: compile.unitMode,
+		equalityMode: compile.equalityMode,
+		allowExtendSelectors: compile.allowExtendSelectors,
+		processImports: compile.processImports,
+		disableScriptModules: compile.disableScriptModules ?? compile.disablePluginRule,
+		paths: compile.searchPaths,
+		...languageOptions,
+		...matchedInput,
+		...matchedOutput
+	};
+}
+//#endregion
+export { applyStrictPreset, getOptions, inferLanguage, loadConfig, loadConfigFromPath, loadConfigFromPathSync, loadConfigSync, loadConfigSyncWithMeta };

package/lib/options.d.ts

@@ -1,4 +1,25 @@
 import type { StylesConfig } from './types.js';
+/**
+ * Options bag the `strict` preset can expand. Any bag carrying a `strict` flag
+ * plus the semantic modes it governs.
+ */
+export interface StrictPresetOptions {
+    strict?: boolean;
+    unitMode?: 'loose' | 'preserve' | 'strict';
+    equalityMode?: 'less' | 'sass' | 'exact';
+    leakyScope?: boolean;
+    allowOverloadedImport?: boolean;
+}
+/**
+ * Expand the `strict` convenience preset. When `strict` is truthy, fills the
+ * strict bundle for any governed option left `undefined` — an explicitly set
+ * option always wins. Modeled after `tsconfig`'s `strict`: it only *sets*
+ * semantic options, it is not itself a mode. Sets the strictest value of each
+ * governed axis (`equalityMode: 'exact'` is the no-coercion dialect).
+ *
+ * Returns a new object (never mutates the input); a no-op when `strict` is falsy.
+ */
+export declare function applyStrictPreset<T extends StrictPresetOptions>(opts: T): T;
 /**
  * Options for retrieving merged configuration
  */
@@ -18,6 +39,12 @@ export interface GetOptionsParams {
      */
     output?: string;
 }
+/**
+ * Infer language from a file path's extension. Exported so a consumer that has
+ * to route by dialect (built-in function set, plugin choice) reads the SAME
+ * extension map the option resolution uses instead of keeping its own copy.
+ */
+export declare function inferLanguage(filePath: string | undefined): string | undefined;
 /**
  * Get merged options by combining compile, language, input, and output settings.
  *