styles-config 2.0.0-alpha.1

package/lib/options.js

@@ -0,0 +1,128 @@
+import picomatch from 'picomatch';
+import path from 'path';
+/**
+ * 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
+ */
+function inferLanguage(filePath) {
+    if (!filePath) {
+        return undefined;
+    }
+    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;
+    }
+    // Normalize paths for comparison
+    const normalizedPattern = path.normalize(pattern);
+    const normalizedFile = path.normalize(filePath);
+    // Try exact match first
+    if (normalizedPattern === normalizedFile) {
+        return true;
+    }
+    // Try basename match (e.g., pattern "styles.less" matches "/path/to/styles.less")
+    if (path.basename(normalizedFile) === normalizedPattern) {
+        return true;
+    }
+    // Try glob/pattern match using picomatch
+    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) {
+        // Include if: no file pattern (default), or file pattern matches
+        if (!opt.file || (filePath && matchesFile(opt.file, filePath))) {
+            // Merge this entry's options, excluding the 'file' property
+            const rest = { ...opt };
+            delete rest.file;
+            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);
+ */
+export function getOptions(config = {}, params = {}) {
+    const { input: inputFile, output: outputFile } = params;
+    const { compile = {}, input, output, language: languageConfig = {} } = config;
+    // Determine language: explicit param > inferred from input extension
+    const language = params.language ?? inferLanguage(inputFile);
+    // Get language-specific options if language is determined
+    const languageOptions = language ? (languageConfig[language] ?? {}) : {};
+    // Get matched input and output options
+    const matchedInput = getMatchingOptions(input, inputFile);
+    const matchedOutput = getMatchingOptions(output, outputFile);
+    // Build result with proper merge priority:
+    // 1. compile (base)
+    // 2. language-specific
+    // 3. matched input
+    // 4. matched output
+    return {
+        // Start with compile-level settings
+        mathMode: compile.mathMode,
+        unitMode: compile.unitMode,
+        equalityMode: compile.equalityMode,
+        paths: compile.searchPaths,
+        javascriptEnabled: compile.enableJavaScript,
+        // Override with language-specific settings
+        ...languageOptions,
+        // Override with matched input settings
+        ...matchedInput,
+        // Override with matched output settings
+        ...matchedOutput
+    };
+}
+//# sourceMappingURL=options.js.map

package/lib/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"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"}

package/lib/types.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Math processing modes
+ */
+export type MathMode = 'always' | 'parens-division' | 'parens' | 'strict';
+/**
+ * Unit conversion modes
+ */
+export type UnitMode = 'loose' | 'preserve' | 'strict';
+/**
+ * Equality/coercion modes for guard comparisons.
+ */
+export type EqualityMode = 'coerce' | 'strict';
+export interface JavaScriptSandboxConfig {
+    /**
+     * Allow network access for script execution runtime.
+     * @default false
+     */
+    allowHttp?: boolean;
+    /**
+     * Optional host allowlist when `allowHttp` is enabled.
+     */
+    allowNetHosts?: string[];
+    /**
+     * Optional explicit filesystem root for script reads.
+     * If omitted, compiler resolves using entry/config roots.
+     */
+    jsReadRoot?: string;
+}
+export type CompileJavaScriptOption = true | JavaScriptSandboxConfig;
+/**
+ * Less compiler options
+ * Based on less.js default-options.js and bin/lessc
+ */
+export interface LessOptions {
+    /**
+     * Inline Javascript - @plugin still allowed
+     * @default false
+     */
+    javascriptEnabled?: boolean;
+    /**
+     * Outputs a makefile import dependency list to stdout.
+     * @default false
+     */
+    depends?: boolean;
+    /**
+     * @deprecated Compress using less built-in compression.
+     * This does an okay job but does not utilise all the tricks of
+     * dedicated css compression.
+     * @default false
+     */
+    compress?: boolean;
+    /**
+     * Runs the less parser and just reports errors without any output.
+     * @default false
+     */
+    lint?: boolean;
+    /**
+     * Sets available include paths.
+     * If the file in an @import rule does not exist at that exact location,
+     * less will look for it at the location(s) passed to this option.
+     * @default []
+     */
+    paths?: string[];
+    /**
+     * Color output in the terminal
+     * @default true
+     */
+    color?: boolean;
+    /**
+     * @deprecated This option has confusing behavior and may be removed in a future version.
+     *
+     * Controls how @import statements for .less files are handled inside selector blocks (rulesets).
+     *
+     * Behavior:
+     * - @import at root level: Always processed
+     * - @import inside @-rules (@media, @supports, etc.): Processed (these are not selector blocks)
+     * - @import inside selector blocks (.class, #id, etc.): Behavior depends on this option
+     *
+     * Options:
+     * - `false` (default): All @import statements are processed regardless of context.
+     * - `true`: @import statements inside selector blocks are silently ignored and not output.
+     * - `'error'`: @import statements inside selector blocks will throw an error instead of being silently ignored.
+     *
+     * Note: Only affects .less file imports. CSS imports (url(...) or .css files) are
+     * always output as CSS @import statements regardless of this setting.
+     *
+     * @see https://github.com/less/less.js/issues/656
+     * @default false
+     */
+    strictImports?: boolean | 'error';
+    /**
+     * Allow Imports from Insecure HTTPS Hosts
+     * @default false
+     */
+    insecure?: boolean;
+    /**
+     * Allows you to add a path to every generated import and url in your css.
+     * This does not affect less import statements that are processed, just ones
+     * that are left in the output css.
+     * @default ''
+     */
+    rootpath?: string;
+    /**
+     * By default URLs are kept as-is, so if you import a file in a sub-directory
+     * that references an image, exactly the same URL will be output in the css.
+     * This option allows you to re-write URL's in imported files so that the
+     * URL is always relative to the base imported file
+     * @default false
+     */
+    rewriteUrls?: boolean | 'all' | 'local' | 'off';
+    /**
+     * How to process math operations
+     * - 'always': eagerly try to solve all operations
+     * - 'parens-division': require parens for division "/"
+     * - 'parens' or 'strict': require parens for all operations
+     * @default 'parens-division'
+     */
+    mathMode?: MathMode;
+    /**
+     * How to handle unit conversions in math operations
+     * - 'loose': Less's default 1.x-4.x behavior
+     * - 'preserve': Create calc() expressions for unit errors
+     * - 'strict': strict unit mode
+     * @default 'preserve'
+     */
+    unitMode?: UnitMode;
+    /**
+     * How to handle equality/coercion in guards and comparisons.
+     * - 'coerce': Less-compatible coercion behavior
+     * - 'strict': type-strict behavior
+     * @default 'coerce'
+     */
+    equalityMode?: EqualityMode;
+    /**
+     * @deprecated Use `mathMode` instead. This option maps to `mathMode` as follows:
+     * - 0 or 'always' → 'always'
+     * - 1 or 'parens-division' → 'parens-division'
+     * - 2 or 'parens' or 'strict' → 'parens'
+     * - 3 or 'strict-legacy' → 'parens' (removed, will default to 'strict)
+     * @default undefined (uses mathMode if provided, otherwise 'parens-division')
+     */
+    math?: 0 | 1 | 2 | 3 | MathMode | 'strict-legacy';
+    /**
+     * @deprecated Use `unitMode` instead. If `true`, sets `unitMode` to 'strict'.
+     * If `false`, sets the unitMode to 'loose.
+     * If undefined, uses the `unitMode` value (defaults to 'preserve').
+     * @default false
+     */
+    strictUnits?: boolean;
+    /**
+     * Effectively the declaration is put at the top of your base Less file,
+     * meaning it can be used but it also can be overridden if this variable
+     * is defined in the file.
+     * @default null
+     */
+    globalVars?: Record<string, string> | null;
+    /**
+     * As opposed to the global variable option, this puts the declaration at the
+     * end of your base file, meaning it will override anything defined in your Less file.
+     * @default null
+     */
+    modifyVars?: Record<string, string> | null;
+    /**
+     * This option allows you to specify a argument to go on to every URL.
+     * @default ''
+     */
+    urlArgs?: string;
+    /**
+     * @removed The dumpLineNumbers option is not useful nor supported in browsers. Use sourcemaps instead.
+     *
+     * @default undefined
+     */
+    dumpLineNumbers?: string;
+    /**
+     * Source map options
+     * @default undefined
+     */
+    sourceMap?: boolean | {
+        sourceMapFullFilename?: string;
+        sourceMapRootpath?: string;
+        sourceMapBasepath?: string;
+        sourceMapURL?: string;
+        sourceMapFileInline?: boolean;
+        outputSourceFiles?: boolean;
+        disableSourcemapAnnotation?: boolean;
+        sourceMapOutputFilename?: string;
+        sourceMapFilename?: string;
+    };
+    /**
+     * Verbose output
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Silent mode (suppress errors)
+     * @default false
+     */
+    silent?: boolean;
+    /**
+     * Quiet mode (suppress warnings)
+     * @default false
+     */
+    quiet?: boolean;
+    /**
+     * @deprecated This is legacy Less behavior.
+     *
+     * Controls whether mixins and detached rulesets "leak" their inner rules.
+     * When true:
+     * - Mixins: Mixin and VarDeclaration nodes are 'public' and 'optional' respectively
+     * - Detached rulesets: Mixin and VarDeclaration nodes are 'public' and 'private' respectively
+     * When false:
+     * - Both mixins and detached rulesets: Mixin and VarDeclaration nodes are 'private'
+     * @default true
+     */
+    leakyRules?: boolean;
+    /**
+     * Whether to collapse nested selectors (Less 1.x-4.x style flattening)
+     * When true, nested selectors like `.parent { .child { } }` are flattened to `.parent .child { }`
+     * @default false
+     */
+    collapseNesting?: boolean;
+    /**
+     * @deprecated This is legacy Less behavior.
+     *
+     * Whether to bubble root-only at-rules (@font-face, @keyframes, etc.) to the root
+     * when they are nested inside rulesets. Modern CSS supports nesting these at-rules.
+     * @default true
+     */
+    bubbleRootAtRules?: boolean;
+}
+/**
+ * Base interface for file-matching options
+ */
+export interface FileMatchOptions {
+    /**
+     * File path, relative path, or glob pattern for matching.
+     * If omitted, the options serve as defaults.
+     */
+    file?: string;
+}
+/**
+ * Input file options - can override compile and language settings per input file
+ */
+export interface InputOptions extends FileMatchOptions {
+    mathMode?: MathMode;
+    unitMode?: UnitMode;
+    equalityMode?: EqualityMode;
+    searchPaths?: string[];
+    enableJavaScript?: boolean;
+    javascriptEnabled?: boolean;
+    paths?: string[];
+    globalVars?: Record<string, string> | null;
+    modifyVars?: Record<string, string> | null;
+    strictImports?: boolean | 'error';
+    rewriteUrls?: boolean | 'all' | 'local' | 'off';
+    rootpath?: string;
+    leakyRules?: boolean;
+    collapseNesting?: boolean;
+    bubbleRootAtRules?: boolean;
+    /** Allow additional language-specific options */
+    [key: string]: any;
+}
+/**
+ * Output file options - can override output settings per output file
+ */
+export interface OutputOptions extends FileMatchOptions {
+    collapseNesting?: boolean;
+    compress?: boolean;
+    sourceMap?: boolean | {
+        sourceMapFullFilename?: string;
+        sourceMapRootpath?: string;
+        sourceMapBasepath?: string;
+        sourceMapURL?: string;
+        sourceMapFileInline?: boolean;
+        outputSourceFiles?: boolean;
+        disableSourcemapAnnotation?: boolean;
+        sourceMapOutputFilename?: string;
+        sourceMapFilename?: string;
+    };
+    /** Allow additional options */
+    [key: string]: any;
+}
+export interface StylesConfig {
+    compile?: {
+        /**
+         * Plugins can be specified as:
+         * - Plugin instances (PluginInterface from @jesscss/core)
+         * - String keys (plugin names that get resolved elsewhere)
+         *
+         * @note - Using `any` here to avoid circular dependency with @jesscss/core.
+         *         The actual type is PluginInterface from @jesscss/core.
+         */
+        plugins?: Array<any | string>;
+        searchPaths?: string[];
+        enableJavaScript?: boolean;
+        javascript?: CompileJavaScriptOption;
+        mathMode?: MathMode;
+        unitMode?: UnitMode;
+        equalityMode?: EqualityMode;
+    };
+    /**
+     * Input file options. Can be a single object for defaults, or an array
+     * where entries can have a `file` property (path or glob) to match specific inputs.
+     * Entries without a `file` property serve as defaults.
+     */
+    input?: InputOptions | InputOptions[];
+    /**
+     * Output file options. Can be a single object for defaults, or an array
+     * where entries can have a `file` property (path or glob) to match specific outputs.
+     * Entries without a `file` property serve as defaults.
+     */
+    output?: OutputOptions | OutputOptions[];
+    language?: {
+        less?: LessOptions;
+        scss?: Record<string, any>;
+        css?: Record<string, any>;
+        jess?: Record<string, any>;
+        [key: string]: LessOptions | Record<string, any> | undefined;
+    };
+}

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE;QACR;;;;;;;WAOG;QACH,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC;QAC9B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,EAAE,QAAQ,CAAC;QACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC;KACrB,CAAC;IACF,MAAM,CAAC,EAAE;QACP,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,WAAW,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KAC9D,CAAC;CACH;AAGD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC"}

package/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "styles-config",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "2.0.0-alpha.1",
+  "description": "General-purpose configuration for styling frameworks (Jess, Less, Sass, Tailwind, etc.)",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./lib/index.js",
+      "types": "./lib/index.d.ts",
+      "source": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "cosmiconfig": "^9.0.0",
+    "picomatch": "^4.0.2",
+    "@jesscss/core": "2.0.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/picomatch": "^3.0.1",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "author": "Matthew Dean",
+  "license": "MIT",
+  "scripts": {
+    "build": "pnpm compile",
+    "compile": "tsc -p tsconfig.build.json",
+    "test": "vitest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './loader.js';
+export * from './options.js';

package/src/loader.ts

@@ -0,0 +1,112 @@
+import { cosmiconfig, cosmiconfigSync, defaultLoadersSync } from 'cosmiconfig';
+import type { StylesConfig } from './types.js';
+
+export interface LoadedConfigMeta {
+  config: StylesConfig;
+  configFilePath?: string;
+}
+
+const explorer = cosmiconfig('styles', {
+  searchPlaces: [
+    'styles.config.ts',
+    'styles.config.js',
+    'styles.config.mts',
+    'styles.config.mjs',
+    'styles.config.cjs',
+    'styles.config.cts'
+  ],
+  loaders: {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '.mts': defaultLoadersSync['.ts'],
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '.cts': defaultLoadersSync['.ts'],
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '.mjs': defaultLoadersSync['.js'],
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '.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: {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '.mts': defaultLoadersSync['.ts'],
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '.cts': defaultLoadersSync['.ts'],
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '.mjs': defaultLoadersSync['.js'],
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    '.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
+ */
+export async function loadConfig(searchFrom?: string): Promise<StylesConfig | null> {
+  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
+ */
+export function loadConfigSync(searchFrom?: string): StylesConfig {
+  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.
+ */
+export function loadConfigSyncWithMeta(searchFrom?: string): LoadedConfigMeta {
+  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
+ */
+export async function loadConfigFromPath(filePath: string): Promise<StylesConfig | null> {
+  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
+ */
+export function loadConfigFromPathSync(filePath: string): StylesConfig {
+  const result = explorerSync.load(filePath);
+  return result?.config ? normalizeConfig(result.config) : {};
+}
+
+/**
+ * Normalize config object - handle default exports and ensure proper type
+ */
+function normalizeConfig(config: any): StylesConfig {
+  // Handle default export (common in ES modules)
+  if (typeof config === 'object' && config !== null && 'default' in config) {
+    return config.default as StylesConfig;
+  }
+  return config as StylesConfig;
+}