@lyse-labs/lyse 0.1.0-alpha.2

package/dist/loaders/stories.js

@@ -0,0 +1,231 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import fg from "fast-glob";
+import { parse } from "@babel/parser";
+import _traverse from "@babel/traverse";
+// Babel CJS-vs-ESM interop: the callable lives at .default in some environments.
+const traverse = (_traverse.default ??
+    _traverse);
+/**
+ * Extract a simple literal value (string | number | boolean) from an AST node.
+ * Returns undefined for complex expressions (template literals, function calls, etc.).
+ */
+function extractLiteralValue(node) {
+    if (node.type === "StringLiteral")
+        return node.value;
+    if (node.type === "NumericLiteral")
+        return node.value;
+    if (node.type === "BooleanLiteral")
+        return node.value;
+    return undefined;
+}
+/**
+ * Extract simple literal args from an ObjectExpression.
+ * Only { key: literal } properties are extracted — computed keys, spread, or complex
+ * values are silently skipped (better to under-extract than mis-extract).
+ */
+function extractArgs(obj) {
+    const args = {};
+    for (const prop of obj.properties) {
+        if (prop.type !== "ObjectProperty")
+            continue;
+        const objProp = prop;
+        // Skip computed properties ([key]: value)
+        if (objProp.computed)
+            continue;
+        // Extract the key as a string
+        let key;
+        if (objProp.key.type === "Identifier") {
+            key = objProp.key.name;
+        }
+        else if (objProp.key.type === "StringLiteral") {
+            key = objProp.key.value;
+        }
+        if (!key)
+            continue;
+        const val = extractLiteralValue(objProp.value);
+        if (val !== undefined) {
+            args[key] = val;
+        }
+    }
+    return args;
+}
+/**
+ * Parse a single story file (CSF v3) and extract:
+ * - componentName from `export default { component: Button }`
+ * - named story exports and their args from `export const Primary = { args: { variant: "primary" } }`
+ *
+ * Returns undefined on parse failure.
+ *
+ * Limitation: factory-pattern stories (`export const Primary = makeStory(...)`)
+ * are skipped — the function call's args are too varied to safely extract.
+ * Cross-file variable references in `component:` are not resolved (v0.2).
+ */
+function parseStoryFile(source) {
+    let ast;
+    try {
+        ast = parse(source, {
+            sourceType: "module",
+            plugins: ["typescript", "jsx"],
+            errorRecovery: true,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    let componentName;
+    const stories = [];
+    try {
+        traverse(ast, {
+            // Extract default export: `export default { component: Button, title: "..." }`
+            ExportDefaultDeclaration(path) {
+                const decl = path.node.declaration;
+                if (decl.type !== "ObjectExpression")
+                    return;
+                const obj = decl;
+                for (const prop of obj.properties) {
+                    if (prop.type !== "ObjectProperty")
+                        continue;
+                    const objProp = prop;
+                    if (objProp.computed)
+                        continue;
+                    if (objProp.key.type !== "Identifier")
+                        continue;
+                    const keyName = objProp.key.name;
+                    if (keyName === "component") {
+                        // Only capture direct identifier references, not expressions
+                        if (objProp.value.type === "Identifier") {
+                            componentName = objProp.value.name;
+                        }
+                    }
+                }
+            },
+            // Extract named exports: `export const Primary = { args: { variant: "primary" } }`
+            // Also handles: `export const Primary: StoryObj = { args: {...} }` (TS type annotation)
+            ExportNamedDeclaration(path) {
+                const decl = path.node.declaration;
+                if (!decl)
+                    return;
+                if (decl.type !== "VariableDeclaration")
+                    return;
+                const varDecl = decl;
+                for (const declarator of varDecl.declarations) {
+                    if (declarator.id.type !== "Identifier")
+                        continue;
+                    const exportName = declarator.id.name;
+                    // Skip `default` re-export patterns
+                    if (exportName === "default")
+                        continue;
+                    const init = declarator.init;
+                    if (!init)
+                        continue;
+                    // Skip factory calls: `makeStory(...)`, `defineMeta(...)`, etc.
+                    // Only extract plain object expressions.
+                    if (init.type !== "ObjectExpression")
+                        continue;
+                    const storyObj = init;
+                    let args;
+                    // Look for `args:` property in the story object
+                    for (const prop of storyObj.properties) {
+                        if (prop.type !== "ObjectProperty")
+                            continue;
+                        const objProp = prop;
+                        if (objProp.computed)
+                            continue;
+                        if (objProp.key.type !== "Identifier")
+                            continue;
+                        if (objProp.key.name !== "args")
+                            continue;
+                        if (objProp.value.type === "ObjectExpression") {
+                            args = extractArgs(objProp.value);
+                        }
+                    }
+                    const storyExport = {
+                        name: exportName,
+                        ...(args !== undefined && Object.keys(args).length > 0 && { args }),
+                    };
+                    stories.push(storyExport);
+                }
+            },
+        });
+    }
+    catch {
+        // Partial extraction is fine — return what we got
+    }
+    return {
+        ...(componentName !== undefined && { componentName }),
+        stories,
+    };
+}
+export async function loadStories(root) {
+    const indexPath = join(root, "storybook-static", "index.json");
+    if (existsSync(indexPath)) {
+        try {
+            const data = JSON.parse(readFileSync(indexPath, "utf8"));
+            const byTitle = new Map();
+            // Group entries by title leaf so we can aggregate story exports per component
+            const titleToEntries = new Map();
+            for (const e of Object.values(data.entries)) {
+                if (e.type !== "story")
+                    continue;
+                const leaf = e.title.split("/").pop() ?? e.title;
+                if (!titleToEntries.has(leaf))
+                    titleToEntries.set(leaf, []);
+                titleToEntries.get(leaf).push(e);
+            }
+            for (const [leaf, entries] of titleToEntries) {
+                // Use the first entry's importPath to parse the story file
+                const firstEntry = entries[0];
+                const importPath = firstEntry.importPath;
+                const storyEntry = { id: firstEntry.id, importPath };
+                // Attempt to parse the source file for CSF v3 exports
+                const absPath = join(root, importPath);
+                if (existsSync(absPath)) {
+                    const src = readFileSync(absPath, "utf8");
+                    const parsed = parseStoryFile(src);
+                    if (parsed) {
+                        if (parsed.componentName !== undefined) {
+                            storyEntry.componentName = parsed.componentName;
+                        }
+                        if (parsed.stories.length > 0) {
+                            storyEntry.stories = parsed.stories;
+                        }
+                    }
+                }
+                byTitle.set(leaf, storyEntry);
+            }
+            if (byTitle.size > 0)
+                return { byTitle };
+        }
+        catch { /* fall through */ }
+    }
+    const files = await fg(["**/*.stories.{ts,tsx,js,jsx}"], { cwd: root, absolute: true, ignore: ["**/node_modules/**"] });
+    if (files.length === 0)
+        return null;
+    const byTitle = new Map();
+    for (const f of files) {
+        const src = readFileSync(f, "utf8");
+        const titleMatch = src.match(/title\s*:\s*["'`]([^"'`]+)["'`]/);
+        if (!titleMatch || !titleMatch[1])
+            continue;
+        const leaf = titleMatch[1].split("/").pop() ?? titleMatch[1];
+        const importPath = f.replace(root + "/", "");
+        const storyEntry = {
+            id: leaf.toLowerCase(),
+            importPath,
+        };
+        // Parse CSF v3 exports from source
+        const parsed = parseStoryFile(src);
+        if (parsed) {
+            if (parsed.componentName !== undefined) {
+                storyEntry.componentName = parsed.componentName;
+            }
+            if (parsed.stories.length > 0) {
+                storyEntry.stories = parsed.stories;
+            }
+        }
+        byTitle.set(leaf, storyEntry);
+    }
+    return byTitle.size > 0 ? { byTitle } : null;
+}
+//# sourceMappingURL=stories.js.map

package/dist/loaders/stories.js.map

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

package/dist/loaders/token-graph.d.ts

@@ -0,0 +1,39 @@
+/**
+ * token-graph.ts — Theme parity checker for light/dark mode token analysis.
+ *
+ * Detects light/dark token naming conventions and flags tokens that exist in one
+ * mode but are missing in the other. This is a pure helper (no rule yet) — it
+ * will be consumed by:
+ *   - Sprint 1 Step 6: LLM prompt themes section (richer signal for Layer 4)
+ *   - v0.2 planned rule: themes/parity-check
+ *
+ * Detection strategy (convention-based, NOT DTCG-mode-based):
+ *   - Suffix pattern:   `<base>-light` / `<base>-dark`
+ *   - Prefix pattern:   `light-<base>` / `dark-<base>`
+ *   - Path segment:     tokens containing `/light/` and `/dark/` in their path
+ *
+ * For each base token detected, if only one mode variant exists, it is flagged
+ * as missing in the opposite mode.
+ *
+ * Limitation: DTCG multi-mode overrides (using $modes / $extensions) are not
+ * analysed in v0.1. These require the full DTCG tree, not just the flattened
+ * TokenMap. Planned for v0.2.
+ */
+import type { TokenMap } from "../types.js";
+export interface ThemeParityCheck {
+    /** Token base names defined in light mode but missing in dark mode. */
+    missingInDark: string[];
+    /** Token base names defined in dark mode but missing in light mode. */
+    missingInLight: string[];
+    /** True when both light and dark mode tokens were detected in the TokenMap. */
+    hasMultipleModes: boolean;
+}
+/**
+ * Analyse the TokenMap for light/dark mode parity.
+ *
+ * The function tries three naming conventions in order (suffix, prefix, path-segment)
+ * and uses the FIRST one that detects any dual-mode tokens.
+ *
+ * If no convention is detected, returns `hasMultipleModes: false` with empty arrays.
+ */
+export declare function checkThemeParity(tokenMap: TokenMap): ThemeParityCheck;

package/dist/loaders/token-graph.js

@@ -0,0 +1,146 @@
+/**
+ * token-graph.ts — Theme parity checker for light/dark mode token analysis.
+ *
+ * Detects light/dark token naming conventions and flags tokens that exist in one
+ * mode but are missing in the other. This is a pure helper (no rule yet) — it
+ * will be consumed by:
+ *   - Sprint 1 Step 6: LLM prompt themes section (richer signal for Layer 4)
+ *   - v0.2 planned rule: themes/parity-check
+ *
+ * Detection strategy (convention-based, NOT DTCG-mode-based):
+ *   - Suffix pattern:   `<base>-light` / `<base>-dark`
+ *   - Prefix pattern:   `light-<base>` / `dark-<base>`
+ *   - Path segment:     tokens containing `/light/` and `/dark/` in their path
+ *
+ * For each base token detected, if only one mode variant exists, it is flagged
+ * as missing in the opposite mode.
+ *
+ * Limitation: DTCG multi-mode overrides (using $modes / $extensions) are not
+ * analysed in v0.1. These require the full DTCG tree, not just the flattened
+ * TokenMap. Planned for v0.2.
+ */
+/**
+ * All token paths from every map in the TokenMap, collected as a flat string array.
+ * TokenMap maps are value → [tokenPaths], so we iterate values to get paths.
+ */
+function collectAllTokenPaths(tokenMap) {
+    const paths = [];
+    const maps = [
+        tokenMap.colors,
+        tokenMap.spacing,
+        tokenMap.typography,
+        tokenMap.radii,
+        tokenMap.shadows,
+        tokenMap.motion,
+        tokenMap.breakpoints,
+        tokenMap.zIndex,
+        tokenMap.opacity,
+        tokenMap.borderWidth,
+    ];
+    for (const map of maps) {
+        for (const tokenPaths of map.values()) {
+            for (const p of tokenPaths) {
+                paths.push(p);
+            }
+        }
+    }
+    return paths;
+}
+/**
+ * Detect light/dark pairs using suffix pattern (`<base>-light` / `<base>-dark`).
+ * Returns sets of base names found in each mode.
+ */
+function detectSuffixPattern(paths) {
+    const lightBases = new Set();
+    const darkBases = new Set();
+    for (const path of paths) {
+        if (path.endsWith("-light"))
+            lightBases.add(path.slice(0, -"-light".length));
+        else if (path.endsWith("-dark"))
+            darkBases.add(path.slice(0, -"-dark".length));
+    }
+    if (lightBases.size === 0 && darkBases.size === 0)
+        return null;
+    return { light: lightBases, dark: darkBases };
+}
+/**
+ * Detect light/dark pairs using prefix pattern (`light-<base>` / `dark-<base>`).
+ * Returns sets of base names found in each mode.
+ */
+function detectPrefixPattern(paths) {
+    const lightBases = new Set();
+    const darkBases = new Set();
+    for (const path of paths) {
+        // Match at the segment level: "light-<base>" or "dark-<base>"
+        // Also handles paths like "theme/light-primary" → base "theme/primary"
+        const segments = path.split("/");
+        const last = segments[segments.length - 1];
+        const prefix = segments.slice(0, -1).join("/");
+        const sep = prefix ? "/" : "";
+        if (last.startsWith("light-")) {
+            lightBases.add(prefix + sep + last.slice("light-".length));
+        }
+        else if (last.startsWith("dark-")) {
+            darkBases.add(prefix + sep + last.slice("dark-".length));
+        }
+    }
+    if (lightBases.size === 0 && darkBases.size === 0)
+        return null;
+    return { light: lightBases, dark: darkBases };
+}
+/**
+ * Detect light/dark pairs using path-segment pattern (`/light/` / `/dark/`).
+ * E.g. "color/light/primary" and "color/dark/primary" → base "color/primary".
+ * Returns sets of base names found in each mode.
+ */
+function detectPathSegmentPattern(paths) {
+    const lightBases = new Set();
+    const darkBases = new Set();
+    for (const path of paths) {
+        const lightIdx = path.indexOf("/light/");
+        const darkIdx = path.indexOf("/dark/");
+        if (lightIdx !== -1) {
+            // Replace "/light/" segment with "/" to get base path
+            lightBases.add(path.slice(0, lightIdx) + "/" + path.slice(lightIdx + "/light/".length));
+        }
+        else if (darkIdx !== -1) {
+            darkBases.add(path.slice(0, darkIdx) + "/" + path.slice(darkIdx + "/dark/".length));
+        }
+    }
+    if (lightBases.size === 0 && darkBases.size === 0)
+        return null;
+    return { light: lightBases, dark: darkBases };
+}
+/**
+ * Given light/dark base sets, compute which bases are missing in each mode.
+ */
+function computeMissing(light, dark) {
+    const missingInDark = [...light].filter((b) => !dark.has(b)).sort();
+    const missingInLight = [...dark].filter((b) => !light.has(b)).sort();
+    return { missingInDark, missingInLight };
+}
+/**
+ * Analyse the TokenMap for light/dark mode parity.
+ *
+ * The function tries three naming conventions in order (suffix, prefix, path-segment)
+ * and uses the FIRST one that detects any dual-mode tokens.
+ *
+ * If no convention is detected, returns `hasMultipleModes: false` with empty arrays.
+ */
+export function checkThemeParity(tokenMap) {
+    const paths = collectAllTokenPaths(tokenMap);
+    // Try detection strategies in order — first match wins
+    const detected = detectSuffixPattern(paths) ??
+        detectPrefixPattern(paths) ??
+        detectPathSegmentPattern(paths);
+    if (!detected) {
+        return { missingInDark: [], missingInLight: [], hasMultipleModes: false };
+    }
+    const { missingInDark, missingInLight } = computeMissing(detected.light, detected.dark);
+    return {
+        missingInDark,
+        missingInLight,
+        hasMultipleModes: true,
+    };
+}
+//# sourceMappingURL=token-graph.js.map

package/dist/loaders/token-graph.js.map

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

package/dist/loaders/tokens.d.ts

@@ -0,0 +1,2 @@
+import type { TokenMap } from "../types.js";
+export declare function loadTokens(root: string): Promise<TokenMap | null>;