@knighted/css 1.0.0-rc.7 → 1.0.0-rc.9

package/dist/cjs/generateTypes.cjs

@@ -0,0 +1,529 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__generateTypesInternals = void 0;
+exports.generateTypes = generateTypes;
+exports.runGenerateTypesCli = runGenerateTypesCli;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_module_1 = require("node:module");
+const node_url_1 = require("node:url");
+const es_module_lexer_1 = require("es-module-lexer");
+const node_module_type_1 = require("node-module-type");
+const css_js_1 = require("./css.cjs");
+const loaderInternals_js_1 = require("./loaderInternals.cjs");
+const stableSelectorsLiteral_js_1 = require("./stableSelectorsLiteral.cjs");
+const stableNamespace_js_1 = require("./stableNamespace.cjs");
+const DEFAULT_SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'coverage',
+    '.knighted-css',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    '.output',
+    'tmp',
+]);
+const SUPPORTED_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mts',
+    '.cts',
+    '.mjs',
+    '.cjs',
+]);
+function resolvePackageRoot() {
+    const detectedType = (0, node_module_type_1.moduleType)();
+    if (detectedType === 'commonjs' && typeof __dirname === 'string') {
+        return node_path_1.default.resolve(__dirname, '..');
+    }
+    const moduleUrl = getImportMetaUrl();
+    if (moduleUrl) {
+        return node_path_1.default.resolve(node_path_1.default.dirname((0, node_url_1.fileURLToPath)(moduleUrl)), '..');
+    }
+    return node_path_1.default.resolve(process.cwd(), 'node_modules', '@knighted', 'css');
+}
+function getImportMetaUrl() {
+    try {
+        return (0, eval)('import.meta.url');
+    }
+    catch {
+        return undefined;
+    }
+}
+const PACKAGE_ROOT = resolvePackageRoot();
+const DEFAULT_TYPES_ROOT = node_path_1.default.join(PACKAGE_ROOT, 'types-stub');
+const DEFAULT_OUT_DIR = node_path_1.default.join(PACKAGE_ROOT, 'node_modules', '.knighted-css');
+async function generateTypes(options = {}) {
+    const rootDir = node_path_1.default.resolve(options.rootDir ?? process.cwd());
+    const include = normalizeIncludeOptions(options.include, rootDir);
+    const outDir = node_path_1.default.resolve(options.outDir ?? DEFAULT_OUT_DIR);
+    const typesRoot = node_path_1.default.resolve(options.typesRoot ?? DEFAULT_TYPES_ROOT);
+    await es_module_lexer_1.init;
+    await promises_1.default.mkdir(outDir, { recursive: true });
+    await promises_1.default.mkdir(typesRoot, { recursive: true });
+    const internalOptions = {
+        rootDir,
+        include,
+        outDir,
+        typesRoot,
+        stableNamespace: options.stableNamespace,
+    };
+    return generateDeclarations(internalOptions);
+}
+async function generateDeclarations(options) {
+    const peerResolver = createProjectPeerResolver(options.rootDir);
+    const files = await collectCandidateFiles(options.include);
+    const manifestPath = node_path_1.default.join(options.outDir, 'manifest.json');
+    const previousManifest = await readManifest(manifestPath);
+    const nextManifest = {};
+    const selectorCache = new Map();
+    const processedSpecifiers = new Set();
+    const declarations = [];
+    const warnings = [];
+    let writes = 0;
+    for (const filePath of files) {
+        const matches = await findSpecifierImports(filePath);
+        for (const match of matches) {
+            const cleaned = match.specifier.trim();
+            const inlineFree = stripInlineLoader(cleaned);
+            if (!inlineFree.includes('?knighted-css'))
+                continue;
+            const { resource, query } = splitResourceAndQuery(inlineFree);
+            if (!query || !(0, loaderInternals_js_1.hasQueryFlag)(query, loaderInternals_js_1.TYPES_QUERY_FLAG)) {
+                continue;
+            }
+            if (processedSpecifiers.has(cleaned)) {
+                continue;
+            }
+            const resolvedNamespace = (0, stableNamespace_js_1.resolveStableNamespace)(options.stableNamespace);
+            const resolvedPath = await resolveImportPath(resource, match.importer, options.rootDir);
+            if (!resolvedPath) {
+                warnings.push(`Unable to resolve ${resource} referenced by ${relativeToRoot(match.importer, options.rootDir)}.`);
+                continue;
+            }
+            const cacheKey = `${resolvedPath}::${resolvedNamespace}`;
+            let selectorMap = selectorCache.get(cacheKey);
+            if (!selectorMap) {
+                try {
+                    const { css } = await (0, css_js_1.cssWithMeta)(resolvedPath, {
+                        cwd: options.rootDir,
+                        peerResolver,
+                    });
+                    selectorMap = (0, stableSelectorsLiteral_js_1.buildStableSelectorsLiteral)({
+                        css,
+                        namespace: resolvedNamespace,
+                        resourcePath: resolvedPath,
+                        emitWarning: message => warnings.push(message),
+                    }).selectorMap;
+                }
+                catch (error) {
+                    warnings.push(`Failed to extract CSS for ${relativeToRoot(resolvedPath, options.rootDir)}: ${formatErrorMessage(error)}`);
+                    continue;
+                }
+                selectorCache.set(cacheKey, selectorMap);
+            }
+            const variant = (0, loaderInternals_js_1.determineSelectorVariant)(query);
+            const declaration = formatModuleDeclaration(cleaned, variant, selectorMap);
+            const declarationHash = hashContent(declaration);
+            const fileName = buildDeclarationFileName(cleaned);
+            const targetPath = node_path_1.default.join(options.outDir, fileName);
+            const previousEntry = previousManifest[cleaned];
+            const needsWrite = previousEntry?.hash !== declarationHash || !(await fileExists(targetPath));
+            if (needsWrite) {
+                await promises_1.default.writeFile(targetPath, declaration, 'utf8');
+                writes += 1;
+            }
+            nextManifest[cleaned] = { file: fileName, hash: declarationHash };
+            if (needsWrite) {
+                declarations.push({ specifier: cleaned, filePath: targetPath });
+            }
+            processedSpecifiers.add(cleaned);
+        }
+    }
+    const removed = await removeStaleDeclarations(previousManifest, nextManifest, options.outDir);
+    await writeManifest(manifestPath, nextManifest);
+    const typesIndexPath = node_path_1.default.join(options.typesRoot, 'index.d.ts');
+    await writeTypesIndex(typesIndexPath, nextManifest, options.outDir);
+    if (Object.keys(nextManifest).length === 0) {
+        declarations.length = 0;
+    }
+    return {
+        written: writes,
+        removed,
+        declarations,
+        warnings,
+        outDir: options.outDir,
+        typesIndexPath,
+    };
+}
+function normalizeIncludeOptions(include, rootDir) {
+    if (!include || include.length === 0) {
+        return [rootDir];
+    }
+    return include.map(entry => node_path_1.default.isAbsolute(entry) ? entry : node_path_1.default.resolve(rootDir, entry));
+}
+async function collectCandidateFiles(entries) {
+    const files = [];
+    const visited = new Set();
+    async function walk(entryPath) {
+        const resolved = node_path_1.default.resolve(entryPath);
+        if (visited.has(resolved)) {
+            return;
+        }
+        visited.add(resolved);
+        let stat;
+        try {
+            stat = await promises_1.default.stat(resolved);
+        }
+        catch {
+            return;
+        }
+        if (stat.isDirectory()) {
+            const base = node_path_1.default.basename(resolved);
+            if (DEFAULT_SKIP_DIRS.has(base)) {
+                return;
+            }
+            const children = await promises_1.default.readdir(resolved, { withFileTypes: true });
+            for (const child of children) {
+                await walk(node_path_1.default.join(resolved, child.name));
+            }
+            return;
+        }
+        if (!stat.isFile()) {
+            return;
+        }
+        const ext = node_path_1.default.extname(resolved).toLowerCase();
+        if (!SUPPORTED_EXTENSIONS.has(ext)) {
+            return;
+        }
+        files.push(resolved);
+    }
+    for (const entry of entries) {
+        await walk(entry);
+    }
+    return files;
+}
+async function findSpecifierImports(filePath) {
+    let source;
+    try {
+        source = await promises_1.default.readFile(filePath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    if (!source.includes('?knighted-css')) {
+        return [];
+    }
+    const matches = [];
+    const [imports] = (0, es_module_lexer_1.parse)(source, filePath);
+    for (const record of imports) {
+        const specifier = record.n ?? source.slice(record.s, record.e);
+        if (specifier && specifier.includes('?knighted-css')) {
+            matches.push({ specifier, importer: filePath });
+        }
+    }
+    const requireRegex = /require\((['"])([^'"`]+?\?knighted-css[^'"`]*)\1\)/g;
+    let reqMatch;
+    while ((reqMatch = requireRegex.exec(source)) !== null) {
+        const spec = reqMatch[2];
+        if (spec) {
+            matches.push({ specifier: spec, importer: filePath });
+        }
+    }
+    return matches;
+}
+function stripInlineLoader(specifier) {
+    const idx = specifier.lastIndexOf('!');
+    return idx >= 0 ? specifier.slice(idx + 1) : specifier;
+}
+function splitResourceAndQuery(specifier) {
+    const hashIndex = specifier.indexOf('#');
+    const trimmed = hashIndex >= 0 ? specifier.slice(0, hashIndex) : specifier;
+    const queryIndex = trimmed.indexOf('?');
+    if (queryIndex < 0) {
+        return { resource: trimmed, query: '' };
+    }
+    return { resource: trimmed.slice(0, queryIndex), query: trimmed.slice(queryIndex) };
+}
+const projectRequireCache = new Map();
+async function resolveImportPath(resourceSpecifier, importerPath, rootDir) {
+    if (!resourceSpecifier)
+        return undefined;
+    if (resourceSpecifier.startsWith('.')) {
+        return 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));
+    }
+    const requireFromRoot = getProjectRequire(rootDir);
+    try {
+        return requireFromRoot.resolve(resourceSpecifier);
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildDeclarationFileName(specifier) {
+    const digest = node_crypto_1.default.createHash('sha1').update(specifier).digest('hex').slice(0, 12);
+    return `knt-${digest}.d.ts`;
+}
+function formatModuleDeclaration(specifier, variant, selectors) {
+    const literalSpecifier = JSON.stringify(specifier);
+    const selectorType = formatSelectorType(selectors);
+    const header = `declare module ${literalSpecifier} {`;
+    const footer = '}';
+    if (variant === 'types') {
+        return `${header}
+  export const knightedCss: string
+  export const stableSelectors: ${selectorType}
+${footer}
+`;
+    }
+    const stableLine = `  export const stableSelectors: ${selectorType}`;
+    const shared = `  const combined: KnightedCssCombinedModule<Record<string, unknown>>
+  export const knightedCss: string
+${stableLine}`;
+    if (variant === 'combined') {
+        return `${header}
+${shared}
+  export default combined
+${footer}
+`;
+    }
+    return `${header}
+${shared}
+${footer}
+`;
+}
+function formatSelectorType(selectors) {
+    if (selectors.size === 0) {
+        return 'Readonly<Record<string, string>>';
+    }
+    const entries = Array.from(selectors.entries()).sort(([a], [b]) => a.localeCompare(b));
+    const lines = entries.map(([token, selector]) => `    readonly ${JSON.stringify(token)}: ${JSON.stringify(selector)}`);
+    return `Readonly<{
+${lines.join('\n')}
+  }>`;
+}
+function hashContent(content) {
+    return node_crypto_1.default.createHash('sha1').update(content).digest('hex');
+}
+async function readManifest(manifestPath) {
+    try {
+        const raw = await promises_1.default.readFile(manifestPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+async function writeManifest(manifestPath, manifest) {
+    await promises_1.default.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+}
+async function removeStaleDeclarations(previous, next, outDir) {
+    const stale = Object.entries(previous).filter(([specifier]) => !next[specifier]);
+    let removed = 0;
+    for (const [, entry] of stale) {
+        const targetPath = node_path_1.default.join(outDir, entry.file);
+        try {
+            await promises_1.default.unlink(targetPath);
+            removed += 1;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return removed;
+}
+async function writeTypesIndex(indexPath, manifest, outDir) {
+    const header = '// Generated by @knighted/css/generate-types\n// Do not edit.\n';
+    const references = Object.values(manifest)
+        .sort((a, b) => a.file.localeCompare(b.file))
+        .map(entry => {
+        const rel = node_path_1.default
+            .relative(node_path_1.default.dirname(indexPath), node_path_1.default.join(outDir, entry.file))
+            .split(node_path_1.default.sep)
+            .join('/');
+        return `/// <reference path="${rel}" />`;
+    });
+    const content = references.length > 0
+        ? `${header}
+${references.join('\n')}
+`
+        : `${header}
+`;
+    await promises_1.default.writeFile(indexPath, content, 'utf8');
+}
+function formatErrorMessage(error) {
+    if (error instanceof Error && typeof error.message === 'string') {
+        return error.message;
+    }
+    return String(error);
+}
+function relativeToRoot(filePath, rootDir) {
+    return node_path_1.default.relative(rootDir, filePath) || filePath;
+}
+async function fileExists(target) {
+    try {
+        await promises_1.default.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function createProjectPeerResolver(rootDir) {
+    const resolver = getProjectRequire(rootDir);
+    return async (name) => {
+        const resolved = resolver.resolve(name);
+        return import((0, node_url_1.pathToFileURL)(resolved).href);
+    };
+}
+function getProjectRequire(rootDir) {
+    const cached = projectRequireCache.get(rootDir);
+    if (cached) {
+        return cached;
+    }
+    const anchor = node_path_1.default.join(rootDir, 'package.json');
+    let loader;
+    try {
+        loader = (0, node_module_1.createRequire)(anchor);
+    }
+    catch {
+        loader = (0, node_module_1.createRequire)(node_path_1.default.join(process.cwd(), 'package.json'));
+    }
+    projectRequireCache.set(rootDir, loader);
+    return loader;
+}
+async function runGenerateTypesCli(argv = process.argv.slice(2)) {
+    let parsed;
+    try {
+        parsed = parseCliArgs(argv);
+    }
+    catch (error) {
+        console.error(`[knighted-css] ${formatErrorMessage(error)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (parsed.help) {
+        printHelp();
+        return;
+    }
+    try {
+        const result = await generateTypes({
+            rootDir: parsed.rootDir,
+            include: parsed.include,
+            outDir: parsed.outDir,
+            typesRoot: parsed.typesRoot,
+            stableNamespace: parsed.stableNamespace,
+        });
+        reportCliResult(result);
+    }
+    catch (error) {
+        console.error('[knighted-css] generate-types failed.');
+        console.error(error);
+        process.exitCode = 1;
+    }
+}
+function parseCliArgs(argv) {
+    let rootDir = process.cwd();
+    const include = [];
+    let outDir;
+    let typesRoot;
+    let stableNamespace;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--help' || arg === '-h') {
+            return { rootDir, include, outDir, typesRoot, stableNamespace, help: true };
+        }
+        if (arg === '--root' || arg === '-r') {
+            const value = argv[++i];
+            if (!value) {
+                throw new Error('Missing value for --root');
+            }
+            rootDir = node_path_1.default.resolve(value);
+            continue;
+        }
+        if (arg === '--include' || arg === '-i') {
+            const value = argv[++i];
+            if (!value) {
+                throw new Error('Missing value for --include');
+            }
+            include.push(value);
+            continue;
+        }
+        if (arg === '--out-dir') {
+            const value = argv[++i];
+            if (!value) {
+                throw new Error('Missing value for --out-dir');
+            }
+            outDir = value;
+            continue;
+        }
+        if (arg === '--types-root') {
+            const value = argv[++i];
+            if (!value) {
+                throw new Error('Missing value for --types-root');
+            }
+            typesRoot = value;
+            continue;
+        }
+        if (arg === '--stable-namespace') {
+            const value = argv[++i];
+            if (!value) {
+                throw new Error('Missing value for --stable-namespace');
+            }
+            stableNamespace = value;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        include.push(arg);
+    }
+    return { rootDir, include, outDir, typesRoot, stableNamespace };
+}
+function printHelp() {
+    console.log(`Usage: knighted-css-generate-types [options]
+
+Options:
+  -r, --root <path>              Project root directory (default: cwd)
+  -i, --include <path>           Additional directories/files to scan (repeatable)
+      --out-dir <path>           Output directory for generated declarations
+      --types-root <path>        Directory for generated @types entrypoint
+      --stable-namespace <name>  Stable namespace prefix for generated selector maps
+  -h, --help                     Show this help message
+`);
+}
+function reportCliResult(result) {
+    if (result.written === 0 && result.removed === 0) {
+        console.log('[knighted-css] No changes to ?knighted-css&types declarations (cache is up to date).');
+    }
+    else {
+        console.log(`[knighted-css] Updated ${result.written} declaration(s), removed ${result.removed}, output in ${result.outDir}.`);
+    }
+    console.log(`[knighted-css] Type references: ${result.typesIndexPath}`);
+    for (const warning of result.warnings) {
+        console.warn(`[knighted-css] ${warning}`);
+    }
+}
+exports.__generateTypesInternals = {
+    stripInlineLoader,
+    splitResourceAndQuery,
+    buildDeclarationFileName,
+    formatModuleDeclaration,
+    formatSelectorType,
+    normalizeIncludeOptions,
+    parseCliArgs,
+    printHelp,
+    reportCliResult,
+};

package/dist/cjs/generateTypes.d.cts

@@ -0,0 +1,54 @@
+import { type SelectorTypeVariant } from './loaderInternals.cjs';
+interface DeclarationRecord {
+    specifier: string;
+    filePath: string;
+}
+export interface GenerateTypesResult {
+    written: number;
+    removed: number;
+    declarations: DeclarationRecord[];
+    warnings: string[];
+    outDir: string;
+    typesIndexPath: string;
+}
+export interface GenerateTypesOptions {
+    rootDir?: string;
+    include?: string[];
+    outDir?: string;
+    typesRoot?: string;
+    stableNamespace?: string;
+}
+export declare function generateTypes(options?: GenerateTypesOptions): Promise<GenerateTypesResult>;
+declare function normalizeIncludeOptions(include: string[] | undefined, rootDir: string): string[];
+declare function stripInlineLoader(specifier: string): string;
+declare function splitResourceAndQuery(specifier: string): {
+    resource: string;
+    query: string;
+};
+declare function buildDeclarationFileName(specifier: string): string;
+declare function formatModuleDeclaration(specifier: string, variant: SelectorTypeVariant, selectors: Map<string, string>): string;
+declare function formatSelectorType(selectors: Map<string, string>): string;
+export declare function runGenerateTypesCli(argv?: string[]): Promise<void>;
+export interface ParsedCliArgs {
+    rootDir: string;
+    include?: string[];
+    outDir?: string;
+    typesRoot?: string;
+    stableNamespace?: string;
+    help?: boolean;
+}
+declare function parseCliArgs(argv: string[]): ParsedCliArgs;
+declare function printHelp(): void;
+declare function reportCliResult(result: GenerateTypesResult): void;
+export declare const __generateTypesInternals: {
+    stripInlineLoader: typeof stripInlineLoader;
+    splitResourceAndQuery: typeof splitResourceAndQuery;
+    buildDeclarationFileName: typeof buildDeclarationFileName;
+    formatModuleDeclaration: typeof formatModuleDeclaration;
+    formatSelectorType: typeof formatSelectorType;
+    normalizeIncludeOptions: typeof normalizeIncludeOptions;
+    parseCliArgs: typeof parseCliArgs;
+    printHelp: typeof printHelp;
+    reportCliResult: typeof reportCliResult;
+};
+export {};