@knighted/css 1.0.10 → 1.1.0-rc.1

package/dist/cjs/css.d.cts

@@ -1,19 +1,23 @@
 import { type TransformOptions as LightningTransformOptions } from 'lightningcss';
 import { type SpecificitySelector, type SpecificityStrategy } from './helpers.cjs';
+import { type AutoStableOption } from './autoStableSelectors.cjs';
 import type { ModuleGraphOptions } from './moduleGraph.cjs';
 import type { CssResolver } from './types.cjs';
+export type { AutoStableOption } from './autoStableSelectors.cjs';
 export type { CssResolver } from './types.cjs';
 export type { ModuleGraphOptions } from './moduleGraph.cjs';
 export declare const DEFAULT_EXTENSIONS: string[];
 type LightningCssConfig = boolean | Partial<Omit<LightningTransformOptions<never>, 'code'>>;
 type PeerLoader = (name: string) => Promise<unknown>;
+type StrictLightningVisitor = Exclude<LightningTransformOptions<never>['visitor'], undefined>;
 export interface CssOptions {
     extensions?: string[];
     cwd?: string;
     filter?: (filePath: string) => boolean;
     lightningcss?: LightningCssConfig;
+    autoStable?: AutoStableOption;
     specificityBoost?: {
-        visitor?: LightningTransformOptions<never>['visitor'];
+        visitor?: StrictLightningVisitor;
         strategy?: SpecificityStrategy;
         match?: SpecificitySelector[];
     };
@@ -31,6 +35,7 @@ export interface VanillaCompileResult {
 export interface CssResult {
     css: string;
     files: string[];
+    exports?: Record<string, string | string[]>;
 }
 export declare function css(entry: string, options?: CssOptions): Promise<string>;
 export declare function cssWithMeta(entry: string, options?: CssOptions): Promise<CssResult>;

package/dist/cjs/generateTypes.cjs

@@ -65,6 +65,13 @@ function getImportMetaUrl() {
 }
 const SELECTOR_REFERENCE = '.knighted-css';
 const SELECTOR_MODULE_SUFFIX = '.knighted-css.ts';
+const STYLE_EXTENSIONS = css_js_1.DEFAULT_EXTENSIONS.map(ext => ext.toLowerCase());
+const EXTENSION_FALLBACKS = {
+    '.js': ['.ts', '.tsx', '.jsx', '.mjs', '.cjs'],
+    '.mjs': ['.mts', '.mjs', '.js', '.ts', '.tsx'],
+    '.cjs': ['.cts', '.cjs', '.js', '.ts', '.tsx'],
+    '.jsx': ['.tsx', '.jsx'],
+};
 async function generateTypes(options = {}) {
     const rootDir = node_path_1.default.resolve(options.rootDir ?? process.cwd());
     const include = normalizeIncludeOptions(options.include, rootDir);
@@ -76,6 +83,7 @@ async function generateTypes(options = {}) {
         include,
         cacheDir,
         stableNamespace: options.stableNamespace,
+        autoStable: options.autoStable,
         tsconfig,
     };
     return generateDeclarations(internalOptions);
@@ -88,6 +96,7 @@ async function generateDeclarations(options) {
     const nextSelectorManifest = {};
     const selectorCache = new Map();
     const processedSelectors = new Set();
+    const proxyInfoCache = new Map();
     const warnings = [];
     let selectorModuleWrites = 0;
     for (const filePath of files) {
@@ -110,9 +119,14 @@ async function generateDeclarations(options) {
             let selectorMap = selectorCache.get(cacheKey);
             if (!selectorMap) {
                 try {
+                    const shouldUseCssModules = resolvedPath.endsWith('.module.css');
                     const { css } = await activeCssWithMeta(resolvedPath, {
                         cwd: options.rootDir,
                         peerResolver,
+                        autoStable: options.autoStable ? { namespace: resolvedNamespace } : undefined,
+                        lightningcss: options.autoStable && shouldUseCssModules
+                            ? { cssModules: true }
+                            : undefined,
                     });
                     selectorMap = (0, stableSelectorsLiteral_js_1.buildStableSelectorsLiteral)({
                         css,
@@ -135,7 +149,8 @@ async function generateDeclarations(options) {
             if (processedSelectors.has(manifestKey)) {
                 continue;
             }
-            const moduleWrite = await ensureSelectorModule(resolvedPath, selectorMap, previousSelectorManifest, nextSelectorManifest);
+            const proxyInfo = await resolveProxyInfo(manifestKey, selectorSource, resolvedPath, proxyInfoCache);
+            const moduleWrite = await ensureSelectorModule(resolvedPath, selectorMap, previousSelectorManifest, nextSelectorManifest, proxyInfo ?? undefined);
             if (moduleWrite) {
                 selectorModuleWrites += 1;
             }
@@ -257,6 +272,13 @@ function extractSelectorSourceSpecifier(specifier) {
     if (!base) {
         return undefined;
     }
+    /**
+     * Handles specifiers like "./entry.knighted-css.ts" where the base has no
+     * extension but the selector suffix includes one.
+     */
+    if (suffix && !node_path_1.default.extname(base)) {
+        return `${base}${suffix}`;
+    }
     return base;
 }
 const projectRequireCache = new Map();
@@ -264,14 +286,14 @@ async function resolveImportPath(resourceSpecifier, importerPath, rootDir, tscon
     if (!resourceSpecifier)
         return undefined;
     if (resourceSpecifier.startsWith('.')) {
-        return node_path_1.default.resolve(node_path_1.default.dirname(importerPath), resourceSpecifier);
+        return resolveWithExtensionFallback(node_path_1.default.resolve(node_path_1.default.dirname(importerPath), resourceSpecifier));
     }
     if (resourceSpecifier.startsWith('/')) {
-        return node_path_1.default.resolve(rootDir, resourceSpecifier.slice(1));
+        return resolveWithExtensionFallback(node_path_1.default.resolve(rootDir, resourceSpecifier.slice(1)));
     }
     const tsconfigResolved = await resolveWithTsconfigPaths(resourceSpecifier, tsconfig);
     if (tsconfigResolved) {
-        return tsconfigResolved;
+        return resolveWithExtensionFallback(tsconfigResolved);
     }
     const requireFromRoot = getProjectRequire(rootDir);
     try {
@@ -285,10 +307,15 @@ function buildSelectorModuleManifestKey(resolvedPath) {
     return resolvedPath.split(node_path_1.default.sep).join('/');
 }
 function buildSelectorModulePath(resolvedPath) {
-    return `${resolvedPath}${SELECTOR_MODULE_SUFFIX}`;
+    if (isStyleResource(resolvedPath)) {
+        return `${resolvedPath}${SELECTOR_MODULE_SUFFIX}`;
+    }
+    const ext = node_path_1.default.extname(resolvedPath);
+    const base = ext ? resolvedPath.slice(0, -ext.length) : resolvedPath;
+    return `${base}${SELECTOR_MODULE_SUFFIX}`;
 }
-function formatSelectorModuleSource(selectors) {
-    const header = '// Generated by @knighted/css/generate-types\n// Do not edit.\n';
+function formatSelectorModuleSource(selectors, proxyInfo) {
+    const header = '// Generated by @knighted/css/generate-types\n// Do not edit.\n\n';
     const entries = Array.from(selectors.entries()).sort(([a], [b]) => a.localeCompare(b));
     const lines = entries.map(([token, selector]) => `  ${JSON.stringify(token)}: ${JSON.stringify(selector)},`);
     const literal = lines.length > 0
@@ -296,14 +323,21 @@ function formatSelectorModuleSource(selectors) {
 ${lines.join('\n')}
 } as const`
         : '{} as const';
-    return `${header}
+    const proxyLines = [];
+    if (proxyInfo) {
+        proxyLines.push(`export * from '${proxyInfo.moduleSpecifier}'`);
+        if (proxyInfo.includeDefault) {
+            proxyLines.push(`export { default } from '${proxyInfo.moduleSpecifier}'`);
+        }
+        proxyLines.push(`export { knightedCss } from '${proxyInfo.moduleSpecifier}?knighted-css'`);
+        proxyLines.push('');
+    }
+    const defaultExport = proxyInfo ? '' : '\nexport default stableSelectors\n';
+    return `${header}${proxyLines.join('\n')}
 export const stableSelectors = ${literal}
 
 export type KnightedCssStableSelectors = typeof stableSelectors
-export type KnightedCssStableSelectorToken = keyof typeof stableSelectors
-
-export default stableSelectors
-`;
+export type KnightedCssStableSelectorToken = keyof typeof stableSelectors${defaultExport}`;
 }
 function hashContent(content) {
     return node_crypto_1.default.createHash('sha1').update(content).digest('hex');
@@ -347,10 +381,10 @@ function isWithinRoot(filePath, rootDir) {
     const relative = node_path_1.default.relative(rootDir, filePath);
     return relative === '' || (!relative.startsWith('..') && !node_path_1.default.isAbsolute(relative));
 }
-async function ensureSelectorModule(resolvedPath, selectors, previousManifest, nextManifest) {
+async function ensureSelectorModule(resolvedPath, selectors, previousManifest, nextManifest, proxyInfo) {
     const manifestKey = buildSelectorModuleManifestKey(resolvedPath);
     const targetPath = buildSelectorModulePath(resolvedPath);
-    const source = formatSelectorModuleSource(selectors);
+    const source = formatSelectorModuleSource(selectors, proxyInfo);
     const hash = hashContent(source);
     const previousEntry = previousManifest[manifestKey];
     const needsWrite = previousEntry?.hash !== hash || !(await fileExists(targetPath));
@@ -387,6 +421,62 @@ async function resolveWithTsconfigPaths(specifier, tsconfig) {
     }
     return undefined;
 }
+async function resolveWithExtensionFallback(candidatePath) {
+    try {
+        const stat = await promises_1.default.stat(candidatePath);
+        if (stat.isFile()) {
+            return candidatePath;
+        }
+    }
+    catch {
+        // continue to resolution fallbacks
+    }
+    const ext = node_path_1.default.extname(candidatePath);
+    const base = ext ? candidatePath.slice(0, -ext.length) : candidatePath;
+    if (!ext) {
+        const resolved = await resolveWithExtensionList(base, Array.from(SUPPORTED_EXTENSIONS));
+        if (resolved) {
+            return resolved;
+        }
+    }
+    if (ext && EXTENSION_FALLBACKS[ext]) {
+        const resolved = await resolveWithExtensionList(base, EXTENSION_FALLBACKS[ext]);
+        if (resolved) {
+            return resolved;
+        }
+    }
+    const indexResolved = await resolveIndexFallback(candidatePath);
+    if (indexResolved) {
+        return indexResolved;
+    }
+    /*
+     * Return the original candidate to preserve existing behavior when nothing
+     * resolves (callers may still want a best-effort path for warnings).
+     */
+    return candidatePath;
+}
+async function resolveWithExtensionList(base, extensions) {
+    for (const extension of extensions) {
+        const candidate = `${base}${extension}`;
+        if (await fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+async function resolveIndexFallback(candidatePath) {
+    try {
+        const stat = await promises_1.default.stat(candidatePath);
+        if (!stat.isDirectory()) {
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    const base = node_path_1.default.join(candidatePath, 'index');
+    return resolveWithExtensionList(base, Array.from(SUPPORTED_EXTENSIONS));
+}
 function loadTsconfigResolutionContext(rootDir, loader = get_tsconfig_1.getTsconfig) {
     let result;
     try {
@@ -441,6 +531,43 @@ function isNonRelativeSpecifier(specifier) {
     }
     return true;
 }
+function isStyleResource(filePath) {
+    const normalized = filePath.toLowerCase();
+    return STYLE_EXTENSIONS.some(ext => normalized.endsWith(ext));
+}
+async function resolveProxyInfo(manifestKey, selectorSource, resolvedPath, cache) {
+    if (isStyleResource(resolvedPath)) {
+        return null;
+    }
+    const cached = cache.get(manifestKey);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const defaultSignal = await getDefaultExportSignal(resolvedPath);
+    const proxyInfo = {
+        moduleSpecifier: buildProxyModuleSpecifier(resolvedPath, selectorSource),
+        includeDefault: defaultSignal === 'has-default',
+    };
+    cache.set(manifestKey, proxyInfo);
+    return proxyInfo;
+}
+function buildProxyModuleSpecifier(resolvedPath, selectorSource) {
+    const resolvedExt = node_path_1.default.extname(resolvedPath);
+    const baseName = node_path_1.default.basename(resolvedPath, resolvedExt);
+    const selectorExt = node_path_1.default.extname(selectorSource);
+    const fileName = selectorExt ? `${baseName}${selectorExt}` : `${baseName}.js`;
+    return `./${fileName}`;
+}
+async function getDefaultExportSignal(filePath) {
+    try {
+        const source = await promises_1.default.readFile(filePath, 'utf8');
+        const analysis = await (0, lexer_js_1.analyzeModule)(source, filePath);
+        return analysis.defaultSignal;
+    }
+    catch {
+        return 'unknown';
+    }
+}
 function createProjectPeerResolver(rootDir) {
     const resolver = getProjectRequire(rootDir);
     return async (name) => {
@@ -484,6 +611,7 @@ async function runGenerateTypesCli(argv = process.argv.slice(2)) {
             include: parsed.include,
             outDir: parsed.outDir,
             stableNamespace: parsed.stableNamespace,
+            autoStable: parsed.autoStable,
         });
         reportCliResult(result);
     }
@@ -498,10 +626,15 @@ function parseCliArgs(argv) {
     const include = [];
     let outDir;
     let stableNamespace;
+    let autoStable = false;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === '--help' || arg === '-h') {
-            return { rootDir, include, outDir, stableNamespace, help: true };
+            return { rootDir, include, outDir, stableNamespace, autoStable, help: true };
+        }
+        if (arg === '--auto-stable') {
+            autoStable = true;
+            continue;
         }
         if (arg === '--root' || arg === '-r') {
             const value = argv[++i];
@@ -540,7 +673,7 @@ function parseCliArgs(argv) {
         }
         include.push(arg);
     }
-    return { rootDir, include, outDir, stableNamespace };
+    return { rootDir, include, outDir, stableNamespace, autoStable };
 }
 function printHelp() {
     console.log(`Usage: knighted-css-generate-types [options]
@@ -550,6 +683,7 @@ Options:
   -i, --include <path>           Additional directories/files to scan (repeatable)
       --out-dir <path>           Directory to store selector module manifest cache
       --stable-namespace <name>  Stable namespace prefix for generated selector maps
+      --auto-stable              Enable autoStable when extracting CSS for selectors
   -h, --help                     Show this help message
 `);
 }
@@ -589,6 +723,8 @@ exports.__generateTypesInternals = {
     setModuleTypeDetector,
     setImportMetaUrlProvider,
     isNonRelativeSpecifier,
+    isStyleResource,
+    resolveWithExtensionFallback,
     createProjectPeerResolver,
     getProjectRequire,
     loadTsconfigResolutionContext,