@knighted/css 1.0.0-rc.8 → 1.0.0

package/dist/moduleGraph.js

@@ -0,0 +1,426 @@
+import path from 'node:path';
+import { builtinModules } from 'node:module';
+import { existsSync, promises as fs, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseSync, Visitor } from 'oxc-parser';
+import { ResolverFactory, } from 'oxc-resolver';
+import { createMatchPath } from 'tsconfig-paths';
+import { getTsconfig } from 'get-tsconfig';
+const SCRIPT_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+const BUILTIN_SPECIFIERS = new Set([
+    ...builtinModules,
+    ...builtinModules.map(mod => `node:${mod}`),
+]);
+const tsconfigResultCache = new Map();
+const tsconfigFsCache = new Map();
+export async function collectStyleImports(entryPath, options) {
+    const { cwd, styleExtensions, filter, resolver, graphOptions } = options;
+    const normalizedStyles = normalizeExtensions(styleExtensions);
+    const scriptExtensions = normalizeExtensions([
+        ...SCRIPT_EXTENSIONS,
+        ...(graphOptions?.extensions ?? []),
+    ]);
+    const resolutionExtensions = dedupeExtensions([
+        ...scriptExtensions,
+        ...normalizedStyles,
+    ]);
+    const tsconfigMatcher = createTsconfigMatcher(graphOptions?.tsConfig, cwd, resolutionExtensions);
+    const seenScripts = new Set();
+    const seenStyles = new Set();
+    const styleOrder = [];
+    const resolutionCache = new Map();
+    const resolverFactory = createResolverFactory(cwd, resolutionExtensions, scriptExtensions, graphOptions);
+    async function walk(filePath) {
+        const absolutePath = path.resolve(filePath);
+        if (seenScripts.has(absolutePath)) {
+            return;
+        }
+        seenScripts.add(absolutePath);
+        const source = await readSourceFile(absolutePath);
+        if (!source) {
+            return;
+        }
+        const specifiers = extractModuleSpecifiers(source, absolutePath);
+        for (const specifier of specifiers) {
+            if (!specifier || isBuiltinSpecifier(specifier)) {
+                continue;
+            }
+            const resolved = await resolveImport(specifier, absolutePath);
+            if (!resolved) {
+                continue;
+            }
+            const normalized = path.resolve(resolved);
+            if (!filter(normalized)) {
+                continue;
+            }
+            if (isStyleExtension(normalized, normalizedStyles)) {
+                if (!seenStyles.has(normalized)) {
+                    seenStyles.add(normalized);
+                    styleOrder.push(normalized);
+                }
+                continue;
+            }
+            if (isScriptExtension(normalized, scriptExtensions)) {
+                await walk(normalized);
+            }
+        }
+    }
+    async function resolveImport(specifier, importer) {
+        const cacheKey = `${importer}::${specifier}`;
+        if (resolutionCache.has(cacheKey)) {
+            return resolutionCache.get(cacheKey);
+        }
+        let resolved;
+        if (resolver) {
+            resolved = normalizeResolverResult(await resolver(specifier, { cwd, from: importer }), cwd);
+        }
+        if (!resolved && tsconfigMatcher) {
+            resolved = tsconfigMatcher(specifier);
+        }
+        if (!resolved) {
+            resolved = resolveWithFactory(resolverFactory, specifier, importer, resolutionExtensions);
+        }
+        resolutionCache.set(cacheKey, resolved);
+        return resolved;
+    }
+    await walk(entryPath);
+    return styleOrder;
+}
+function normalizeExtensions(extensions) {
+    const result = new Set();
+    for (const ext of extensions) {
+        if (!ext)
+            continue;
+        const normalized = ext.startsWith('.') ? ext.toLowerCase() : `.${ext.toLowerCase()}`;
+        result.add(normalized);
+    }
+    return Array.from(result);
+}
+function dedupeExtensions(extensions) {
+    const result = new Set();
+    for (const ext of extensions) {
+        result.add(ext);
+    }
+    return Array.from(result);
+}
+function isBuiltinSpecifier(specifier) {
+    if (BUILTIN_SPECIFIERS.has(specifier)) {
+        return true;
+    }
+    if (specifier.startsWith('node:')) {
+        return true;
+    }
+    return false;
+}
+function isStyleExtension(filePath, extensions) {
+    const lower = filePath.toLowerCase();
+    return extensions.some(ext => lower.endsWith(ext));
+}
+function isScriptExtension(filePath, extensions) {
+    const ext = path.extname(filePath).toLowerCase();
+    return extensions.includes(ext);
+}
+async function readSourceFile(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractModuleSpecifiers(sourceText, filePath) {
+    let program;
+    try {
+        ;
+        ({ program } = parseSync(filePath, sourceText, { sourceType: 'unambiguous' }));
+    }
+    catch {
+        return [];
+    }
+    const specifiers = [];
+    const addSpecifier = (raw) => {
+        if (!raw) {
+            return;
+        }
+        const normalized = normalizeSpecifier(raw);
+        if (normalized) {
+            specifiers.push(normalized);
+        }
+    };
+    const visitor = new Visitor({
+        ImportDeclaration(node) {
+            addSpecifier(node.source?.value);
+        },
+        ExportNamedDeclaration(node) {
+            if (node.source) {
+                addSpecifier(node.source.value);
+            }
+        },
+        ExportAllDeclaration(node) {
+            addSpecifier(node.source?.value);
+        },
+        TSImportEqualsDeclaration(node) {
+            const specifier = extractImportEqualsSpecifier(node);
+            if (specifier) {
+                addSpecifier(specifier);
+            }
+        },
+        ImportExpression(node) {
+            const specifier = getStringFromExpression(node.source);
+            if (specifier) {
+                addSpecifier(specifier);
+            }
+        },
+        CallExpression(node) {
+            if (!isRequireLikeCallee(node.callee)) {
+                return;
+            }
+            const specifier = getStringFromArgument(node.arguments[0]);
+            if (specifier) {
+                addSpecifier(specifier);
+            }
+        },
+    });
+    visitor.visit(program);
+    return specifiers;
+}
+function normalizeSpecifier(raw) {
+    if (!raw)
+        return '';
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.startsWith('\0')) {
+        return '';
+    }
+    const querySearchOffset = trimmed.startsWith('#') ? 1 : 0;
+    const remainder = trimmed.slice(querySearchOffset);
+    const queryMatchIndex = remainder.search(/[?#]/);
+    const queryIndex = queryMatchIndex === -1 ? -1 : querySearchOffset + queryMatchIndex;
+    const withoutQuery = queryIndex === -1 ? trimmed : trimmed.slice(0, queryIndex);
+    if (!withoutQuery) {
+        return '';
+    }
+    if (/^[a-z][\w+.-]*:/i.test(withoutQuery) && !withoutQuery.startsWith('file:')) {
+        return '';
+    }
+    return withoutQuery;
+}
+function extractImportEqualsSpecifier(node) {
+    if (node.moduleReference.type === 'TSExternalModuleReference') {
+        return node.moduleReference.expression.value;
+    }
+    return undefined;
+}
+function getStringFromArgument(argument) {
+    if (!argument || argument.type === 'SpreadElement') {
+        return undefined;
+    }
+    return getStringFromExpression(argument);
+}
+function getStringFromExpression(expression) {
+    if (!expression) {
+        return undefined;
+    }
+    if (expression.type === 'Literal') {
+        const literalValue = expression.value;
+        return typeof literalValue === 'string' ? literalValue : undefined;
+    }
+    if (expression.type === 'TemplateLiteral' && expression.expressions.length === 0) {
+        const [first] = expression.quasis;
+        return first?.value.cooked ?? first?.value.raw ?? undefined;
+    }
+    return undefined;
+}
+function isRequireLikeCallee(expression) {
+    const target = unwrapExpression(expression);
+    if (target.type === 'Identifier') {
+        return target.name === 'require';
+    }
+    if (target.type === 'MemberExpression') {
+        const object = target.object;
+        if (object.type === 'Identifier') {
+            return object.name === 'require';
+        }
+    }
+    return false;
+}
+function unwrapExpression(expression) {
+    if (expression.type === 'ChainExpression') {
+        const inner = expression.expression;
+        if (inner.type === 'CallExpression') {
+            return unwrapExpression(inner.callee);
+        }
+        return unwrapExpression(inner);
+    }
+    if (expression.type === 'TSNonNullExpression') {
+        return unwrapExpression(expression.expression);
+    }
+    return expression;
+}
+function normalizeResolverResult(result, cwd) {
+    if (!result) {
+        return undefined;
+    }
+    if (result.startsWith('file://')) {
+        try {
+            return fileURLToPath(new URL(result));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return path.isAbsolute(result) ? result : path.resolve(cwd, result);
+}
+function resolveWithFactory(factory, specifier, importer, extensions) {
+    if (specifier.startsWith('file://')) {
+        try {
+            return findExistingFile(fileURLToPath(new URL(specifier)), extensions);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (/^[a-z][\w+.-]*:/i.test(specifier)) {
+        return undefined;
+    }
+    try {
+        const result = factory.resolveFileSync(importer, specifier);
+        return result?.path;
+    }
+    catch {
+        return undefined;
+    }
+}
+function createResolverFactory(cwd, extensions, scriptExtensions, graphOptions) {
+    const options = {
+        extensions,
+        conditionNames: graphOptions?.conditions,
+    };
+    const extensionAlias = buildExtensionAlias(scriptExtensions);
+    if (extensionAlias) {
+        options.extensionAlias = extensionAlias;
+    }
+    const tsconfigOption = resolveResolverTsconfig(graphOptions?.tsConfig, cwd);
+    options.tsconfig = tsconfigOption ?? 'auto';
+    return new ResolverFactory(options);
+}
+function buildExtensionAlias(scriptExtensions) {
+    const alias = {};
+    const jsTargets = dedupeExtensions(scriptExtensions.filter(ext => ['.js', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts'].includes(ext)));
+    if (jsTargets.length > 0) {
+        for (const key of ['.js', '.mjs', '.cjs']) {
+            alias[key] = jsTargets;
+        }
+    }
+    const jsxTargets = dedupeExtensions(scriptExtensions.filter(ext => ext === '.jsx' || ext === '.tsx'));
+    if (jsxTargets.length > 0) {
+        alias['.jsx'] = jsxTargets;
+    }
+    return Object.keys(alias).length > 0 ? alias : undefined;
+}
+function resolveResolverTsconfig(input, cwd) {
+    if (!input || typeof input !== 'string') {
+        return undefined;
+    }
+    const resolved = resolveTsconfigPath(input, cwd);
+    if (!resolved) {
+        return undefined;
+    }
+    return { configFile: resolved };
+}
+function createTsconfigMatcher(input, cwd, extensions) {
+    const config = loadTsconfigPaths(input, cwd);
+    if (!config) {
+        return undefined;
+    }
+    const matchPath = createMatchPath(config.absoluteBaseUrl, config.paths);
+    return (specifier) => {
+        const matched = matchPath(specifier, undefined, undefined, extensions);
+        if (!matched) {
+            return undefined;
+        }
+        return findExistingFile(matched, extensions) ?? matched;
+    };
+}
+function loadTsconfigPaths(input, cwd) {
+    if (!input) {
+        return undefined;
+    }
+    if (typeof input === 'string') {
+        const target = path.isAbsolute(input) ? input : path.resolve(cwd, input);
+        const cached = tsconfigResultCache.get(target);
+        if (cached !== undefined) {
+            return cached ?? undefined;
+        }
+        const result = getTsconfig(target, undefined, tsconfigFsCache);
+        if (!result) {
+            tsconfigResultCache.set(target, null);
+            return undefined;
+        }
+        const normalized = normalizeTsconfigCompilerOptions(result.config.compilerOptions, path.dirname(result.path));
+        tsconfigResultCache.set(target, normalized ?? null);
+        return normalized;
+    }
+    const compilerOptions = input.compilerOptions;
+    return normalizeTsconfigCompilerOptions(compilerOptions, cwd);
+}
+function normalizeTsconfigCompilerOptions(compilerOptions, configDir) {
+    if (!compilerOptions?.baseUrl || !compilerOptions.paths) {
+        return undefined;
+    }
+    const normalizedPaths = {};
+    for (const [pattern, replacements] of Object.entries(compilerOptions.paths)) {
+        if (!replacements || replacements.length === 0) {
+            continue;
+        }
+        normalizedPaths[pattern] = Array.isArray(replacements)
+            ? [...replacements]
+            : [replacements];
+    }
+    if (Object.keys(normalizedPaths).length === 0) {
+        return undefined;
+    }
+    const absoluteBaseUrl = path.isAbsolute(compilerOptions.baseUrl)
+        ? compilerOptions.baseUrl
+        : path.resolve(configDir, compilerOptions.baseUrl);
+    return { absoluteBaseUrl, paths: normalizedPaths };
+}
+function resolveTsconfigPath(tsconfigPath, cwd) {
+    const absolute = path.isAbsolute(tsconfigPath)
+        ? tsconfigPath
+        : path.resolve(cwd, tsconfigPath);
+    if (!existsSync(absolute)) {
+        return undefined;
+    }
+    const stats = statSync(absolute);
+    if (stats.isDirectory()) {
+        const candidate = path.join(absolute, 'tsconfig.json');
+        return existsSync(candidate) ? candidate : undefined;
+    }
+    return absolute;
+}
+function findExistingFile(candidate, extensions) {
+    const candidateHasExt = hasExtension(candidate);
+    if (candidateHasExt && existsSync(candidate)) {
+        return candidate;
+    }
+    if (!candidateHasExt) {
+        for (const ext of extensions) {
+            const withExt = `${candidate}${ext}`;
+            if (existsSync(withExt)) {
+                return withExt;
+            }
+        }
+    }
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+        for (const ext of extensions) {
+            const indexPath = path.join(candidate, `index${ext}`);
+            if (existsSync(indexPath)) {
+                return indexPath;
+            }
+        }
+    }
+    return undefined;
+}
+function hasExtension(filePath) {
+    return Boolean(path.extname(filePath));
+}

package/dist/sassInternals.d.ts

@@ -1,6 +1,5 @@
-export type CssResolver = (specifier: string, ctx: {
-    cwd: string;
-}) => string | Promise<string | undefined>;
+import type { CssResolver } from './types.js';
+export type { CssResolver } from './types.js';
 export declare function createSassImporter({ cwd, resolver, }: {
     cwd: string;
     resolver?: CssResolver;
@@ -13,7 +12,7 @@ export declare function createSassImporter({ cwd, resolver, }: {
         syntax: "scss" | "indented";
     }>;
 } | undefined;
-export declare function resolveAliasSpecifier(specifier: string, resolver: CssResolver, cwd: string): Promise<string | undefined>;
+export declare function resolveAliasSpecifier(specifier: string, resolver: CssResolver, cwd: string, from?: string): Promise<string | undefined>;
 export declare function shouldNormalizeSpecifier(specifier: string): boolean;
 export declare function ensureSassPath(filePath: string): string | undefined;
 export declare function resolveRelativeSpecifier(specifier: string, containingUrl?: URL | null): string | undefined;

package/dist/sassInternals.js

@@ -13,8 +13,11 @@ export function createSassImporter({ cwd, resolver, }) {
                     console.error('[knighted-css:sass] containing url:', context.containingUrl.href);
                 }
             }
+            const containingPath = context?.containingUrl
+                ? fileURLToPath(context.containingUrl)
+                : undefined;
             if (shouldNormalizeSpecifier(url)) {
-                const resolvedPath = await resolveAliasSpecifier(url, resolver, cwd);
+                const resolvedPath = await resolveAliasSpecifier(url, resolver, cwd, containingPath);
                 if (!resolvedPath) {
                     if (debug) {
                         console.error('[knighted-css:sass] resolver returned no result for', url);
@@ -50,8 +53,8 @@ export function createSassImporter({ cwd, resolver, }) {
         },
     };
 }
-export async function resolveAliasSpecifier(specifier, resolver, cwd) {
-    const resolved = await resolver(specifier, { cwd });
+export async function resolveAliasSpecifier(specifier, resolver, cwd, from) {
+    const resolved = await resolver(specifier, { cwd, from });
     if (!resolved) {
         return undefined;
     }

package/dist/stableSelectors.d.ts

@@ -5,9 +5,24 @@ export interface StableClassNameOptions extends StableSelectorOptions {
     token?: string;
     join?: (values: string[]) => string;
 }
+export interface MergeStableClassSingleInput extends StableSelectorOptions {
+    hashed: string | string[];
+    selector?: string;
+    token: string;
+    join?: (values: string[]) => string;
+}
+export interface MergeStableClassBatchInput<Hashed extends Record<string, string | string[]>, Selectors extends Record<string, string> | undefined = Record<string, string>> extends StableSelectorOptions {
+    hashed: Hashed;
+    selectors?: Selectors;
+    join?: (values: string[]) => string;
+}
 export declare function stableToken(token: string, options?: StableSelectorOptions): string;
 export declare function stableClass(token: string, options?: StableSelectorOptions): string;
 export declare function stableSelector(token: string, options?: StableSelectorOptions): string;
 export declare function createStableClassFactory(options?: StableSelectorOptions): (token: string) => string;
 export declare function stableClassName<T extends Record<string, string>>(styles: T, key: keyof T | string, options?: StableClassNameOptions): string;
 export declare const stableClassFromModule: typeof stableClassName;
+export declare function mergeStableClass(input: MergeStableClassSingleInput): string;
+export declare function mergeStableClass<Hashed extends Record<string, string | string[]>>(input: MergeStableClassBatchInput<Hashed>): {
+    [Key in keyof Hashed]: string;
+};

package/dist/stableSelectors.js

@@ -1,5 +1,6 @@
 const DEFAULT_NAMESPACE = 'knighted';
 const defaultJoin = (values) => values.filter(Boolean).join(' ');
+const toArray = (value) => Array.isArray(value) ? value : [value];
 const normalizeToken = (token) => {
     const sanitized = token
         .trim()
@@ -34,3 +35,30 @@ export function stableClassName(styles, key, options) {
     return join([hashed, stable]);
 }
 export const stableClassFromModule = stableClassName;
+export function mergeStableClass(input) {
+    if ('token' in input) {
+        return mergeSingle(input);
+    }
+    return mergeBatch(input);
+}
+function mergeSingle(input) {
+    const join = input.join ?? defaultJoin;
+    const hashed = toArray(input.hashed);
+    const stable = input.selector?.trim().length
+        ? input.selector
+        : stableClass(input.token, { namespace: input.namespace });
+    return join([...hashed, stable]);
+}
+function mergeBatch(input) {
+    const join = input.join ?? defaultJoin;
+    const output = {};
+    for (const key of Object.keys(input.hashed)) {
+        const hashedValue = input.hashed[key];
+        const selector = input.selectors?.[String(key)];
+        const stable = selector?.trim().length
+            ? selector
+            : stableClass(String(key), { namespace: input.namespace });
+        output[key] = join([...toArray(hashedValue), stable]);
+    }
+    return output;
+}

package/dist/stableSelectorsLiteral.d.ts

@@ -2,11 +2,13 @@ export interface StableSelectorsLiteralResult {
     literal: string;
     selectorMap: Map<string, string>;
 }
+type StableSelectorsLiteralTarget = 'ts' | 'js';
 export declare function buildStableSelectorsLiteral(options: {
     css: string;
     namespace: string;
     resourcePath: string;
     emitWarning: (message: string) => void;
+    target?: StableSelectorsLiteralTarget;
 }): StableSelectorsLiteralResult;
 export declare function collectStableSelectors(css: string, namespace: string, filename?: string): Map<string, string>;
 declare function collectStableSelectorsByRegex(css: string, namespace: string): Map<string, string>;

package/dist/stableSelectorsLiteral.js

@@ -1,20 +1,23 @@
 import { transform as lightningTransform } from 'lightningcss';
 import { escapeRegex, serializeSelector } from './helpers.js';
 export function buildStableSelectorsLiteral(options) {
+    const target = options.target ?? 'ts';
     const trimmedNamespace = options.namespace.trim();
     if (!trimmedNamespace) {
         options.emitWarning(`stableSelectors requested for ${options.resourcePath} but "stableNamespace" resolved to an empty value.`);
-        return {
-            literal: 'export const stableSelectors = {} as const;\n',
-            selectorMap: new Map(),
-        };
+        return finalizeLiteral(new Map(), target);
     }
     const selectorMap = collectStableSelectors(options.css, trimmedNamespace, options.resourcePath);
     if (selectorMap.size === 0) {
         options.emitWarning(`stableSelectors requested for ${options.resourcePath} but no selectors matched namespace "${trimmedNamespace}".`);
     }
+    return finalizeLiteral(selectorMap, target);
+}
+function finalizeLiteral(selectorMap, target) {
+    const formatted = formatStableSelectorMap(selectorMap);
+    const suffix = target === 'ts' ? ' as const' : '';
     return {
-        literal: `export const stableSelectors = ${formatStableSelectorMap(selectorMap)} as const;\n`,
+        literal: `export const stableSelectors = ${formatted}${suffix};\n`,
         selectorMap,
     };
 }

package/dist/types.d.ts

@@ -0,0 +1,4 @@
+export type CssResolver = (specifier: string, ctx: {
+    cwd: string;
+    from?: string;
+}) => string | Promise<string | undefined>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/loader-queries.d.ts

@@ -19,7 +19,12 @@ declare module '*?knighted-css&types' {
  * TypeScript cannot infer the underlying module automatically, so consumers can
  * import the default export and narrow it with `KnightedCssCombinedModule<typeof import('./file')>`.
  */
-type KnightedCssCombinedModule<TModule> = TModule & { knightedCss: string }
+type KnightedCssCombinedExtras = Readonly<Record<string, unknown>>
+
+type KnightedCssCombinedModule<
+  TModule,
+  TExtras extends KnightedCssCombinedExtras = Record<never, never>,
+> = TModule & TExtras & { knightedCss: string }
 
 declare module '*?knighted-css&combined' {
   const combined: KnightedCssCombinedModule<Record<string, unknown>>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/css",
-  "version": "1.0.0-rc.8",
+  "version": "1.0.0",
   "description": "A build-time utility that traverses JavaScript/TypeScript module dependency graphs to extract, compile, and optimize all imported CSS into a single, in-memory string.",
   "type": "module",
   "main": "./dist/css.js",
@@ -10,6 +10,9 @@
       "loader": [
         "./dist/loader.d.ts"
       ],
+      "loader-helpers": [
+        "./dist/loader-helpers.d.ts"
+      ],
       "loader-queries": [
         "./loader-queries.d.ts"
       ],
@@ -32,6 +35,11 @@
       "import": "./dist/loader.js",
       "require": "./dist/cjs/loader.cjs"
     },
+    "./loader-helpers": {
+      "types": "./dist/loader-helpers.d.ts",
+      "import": "./dist/loader-helpers.js",
+      "require": "./dist/cjs/loader-helpers.cjs"
+    },
     "./loader-queries": {
       "types": "./loader-queries.d.ts",
       "default": "./loader-queries.d.ts"
@@ -76,15 +84,13 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "dependency-tree": "^11.2.0",
     "es-module-lexer": "^2.0.0",
     "lightningcss": "^1.30.2",
-    "node-module-type": "^1.0.1"
-  },
-  "overrides": {
-    "module-lookup-amd": {
-      "glob": "^9.0.0"
-    }
+    "node-module-type": "^1.0.1",
+    "get-tsconfig": "^4.13.0",
+    "oxc-parser": "^0.104.0",
+    "oxc-resolver": "^11.16.0",
+    "tsconfig-paths": "^4.2.0"
   },
   "peerDependencies": {
     "@vanilla-extract/integration": "^8.0.0",