@brad-frost-web/eddie-brain 0.32.0

package/dist/knowledge-graph/component-index.js

@@ -0,0 +1,1033 @@
+/**
+ * ComponentIndex — Auto-discover and catalog Eddie components
+ *
+ * Scans the Eddie monorepo to build a registry of all components,
+ * extracting metadata from TypeScript decorators and Storybook stories.
+ */
+import fg from 'fast-glob';
+const { globSync } = fg;
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+export class ComponentIndex {
+    components = new Map();
+    /**
+     * Build the component registry by scanning the Eddie codebase.
+     *
+     * Scans four packages:
+     *
+     *   eddie-web-components  — core Lit components (depth 1: <name>/<name>.ts)
+     *   eddie-recipes         — recipe components (depth 2: <project>/<name>/<name>.ts)
+     *   eddie-pages           — full-page templates (depth 2: <project>/<name>/<name>.ts)
+     *   eddie-charts          — chart recipe components (depth 2: <project>/<name>/<name>.ts)
+     *
+     * All four are walked by scanPackage, which handles depth-agnostic traversal
+     * and enforces the basename-matches-containing-dir convention. eddie-charts
+     * is a category recipe library: its components share the `ed-r-*` tag prefix
+     * and `ed-r-*` CSS class prefix with eddie-recipes, but live in a separate
+     * package so that the Chart.js runtime is opt-in for consumers who don't
+     * need chart surfaces.
+     */
+    async build(rootDir) {
+        this.components.clear();
+        const webComponentsDir = join(rootDir, 'packages', 'eddie-web-components', 'components');
+        const recipesDir = join(rootDir, 'packages', 'eddie-recipes', 'recipes');
+        const pagesDir = join(rootDir, 'packages', 'eddie-pages', 'pages');
+        const chartsDir = join(rootDir, 'packages', 'eddie-charts', 'charts');
+        await this.scanPackage(webComponentsDir, 'eddie-web-components', rootDir);
+        await this.scanPackage(recipesDir, 'eddie-recipes', rootDir);
+        await this.scanPackage(pagesDir, 'eddie-pages', rootDir);
+        await this.scanPackage(chartsDir, 'eddie-charts', rootDir);
+    }
+    /**
+     * Scan a package directory for components.
+     *
+     * Walks any depth under the package root and picks up files that follow
+     * the Eddie component convention: every component file lives at
+     * `<component-dir>/<component-name>.ts` where the file's basename matches
+     * its containing directory's basename. That gives us:
+     *
+     *   eddie-web-components: components/button/button.ts
+     *                         components/card/card.ts
+     *                         → depth 1 under pkgDir
+     *
+     *   eddie-recipes:        recipes/common/project-card/project-card.ts
+     *                         recipes/we-are-here/wah-logo/wah-logo.ts
+     *                         → depth 2 under pkgDir (extra project-name level)
+     *
+     * Historic bug: the previous glob was a two-level pattern (star slash star
+     * dot ts) which only matched depth 1, so the entire eddie-recipes catalog
+     * was invisible to the indexer. `ed-r-project-card` and 11 other real,
+     * shipping recipe components never made it into components.json. Fix: walk
+     * any depth via a double-star glob, then enforce the basename-matches-
+     * containing-directory convention to filter helpers, types, and barrel
+     * files that happen to sit next to real components.
+     */
+    async scanPackage(pkgDir, pkgName, rootDir) {
+        // Walk any depth. Ignore base classes, test files, stories, and
+        // declaration files. Everything else is a candidate for being a component.
+        const tsFiles = globSync('**/*.ts', {
+            cwd: pkgDir,
+            ignore: [
+                'EdElement.ts',
+                'EdFormElement.ts',
+                '**/EdElement.ts',
+                '**/EdFormElement.ts',
+                '**/test/**',
+                '**/*.stories.ts',
+                '**/*.d.ts',
+            ],
+        });
+        for (const relativeFile of tsFiles) {
+            // relativeFile is pkgDir-relative, e.g. "button/button.ts" or
+            // "common/project-card/project-card.ts"
+            const parts = relativeFile.split('/');
+            const fileName = parts[parts.length - 1];
+            const componentName = fileName.replace(/\.ts$/, '');
+            // Enforce the Eddie <name>/<name>.ts convention. If the containing
+            // directory's name doesn't match the file's name, this isn't a
+            // component — it's a helper, a shared type, or a barrel file.
+            // Skip silently.
+            if (parts.length < 2)
+                continue;
+            const dirName = parts[parts.length - 2];
+            if (dirName !== componentName)
+                continue;
+            // relativeDir is the path from pkgDir to the component's own directory,
+            // without the filename. E.g. "button" or "common/project-card".
+            const relativeDir = parts.slice(0, -1).join('/');
+            const absoluteComponentDir = join(pkgDir, relativeDir);
+            const absoluteFilePath = join(pkgDir, relativeFile);
+            try {
+                const entry = await this.parseComponent(componentName, absoluteFilePath, absoluteComponentDir, relativeDir, pkgName, rootDir);
+                if (entry) {
+                    this.components.set(entry.tagName, entry);
+                }
+            }
+            catch (err) {
+                // Silently skip unparseable files
+            }
+        }
+    }
+    /**
+     * Parse a single component file and extract metadata.
+     *
+     * @param componentName   The component's base name (e.g. "button", "project-card")
+     * @param filePath        Absolute path to the component's .ts file
+     * @param componentDir    Absolute path to the component's own directory
+     *                        (contains the .ts, .scss, .stories.ts, and test/)
+     * @param relativeDir     Path from the package root to the component dir,
+     *                        e.g. "button" (eddie-web-components) or
+     *                        "common/project-card" (eddie-recipes)
+     * @param pkgName         Which package this component lives in
+     * @param rootDir         Repo root (unused today but passed for future use)
+     */
+    async parseComponent(componentName, filePath, componentDir, relativeDir, pkgName, rootDir) {
+        const content = readFileSync(filePath, 'utf-8');
+        // Extract tag name from @customElement decorator or customElements.define().
+        //
+        // eddie-pages are structurally different: they're reusable Lit templates
+        // that extend LitElement directly, render into light DOM, and are NOT
+        // registered as custom elements. They have no `customElements.define()`
+        // call and no `@customElement` decorator. For pages, we synthesize an
+        // identifier of the form `ed-p-<name>` from the file name so they can
+        // live in the component index alongside real custom elements. Consumers
+        // can tell them apart by checking `atomicLevel === 'page'`.
+        const tagNameMatch = content.match(/@customElement\(['"]([^'"]+)['"]\)/) ||
+            content.match(/customElements\.define\(['"]([^'"]+)['"]/);
+        let tagName;
+        if (tagNameMatch) {
+            tagName = tagNameMatch[1];
+        }
+        else if (pkgName === 'eddie-pages') {
+            // Synthesize a stable identifier from the component name.
+            // e.g. "app-dashboard" → "ed-p-app-dashboard"
+            tagName = `ed-p-${componentName}`;
+        }
+        else {
+            return null; // Not a custom element and not a page
+        }
+        // Extract class name
+        const classMatch = content.match(/export class\s+(\w+)/);
+        if (!classMatch) {
+            return null;
+        }
+        const className = classMatch[1];
+        const displayName = this.classNameToDisplayName(className);
+        // Determine CSS class name (follows BEM convention).
+        // The category letter distinguishes core components, recipes, and pages:
+        //   core components: `ed-c-<name>`   (c = component)
+        //   recipes:         `ed-r-<name>`   (r = recipe)
+        //   pages:           `ed-p-<name>`   (p = page)
+        //
+        // Historic bug: the previous derivation emitted `ed-r-c-<name>` and
+        // `ed-p-c-<name>` (from PRs #497 and #499), double-encoding the
+        // category with an extra `-c-`. The recipe source files also use
+        // `ed-r-c-*` today (tracked as #505 for a source-side rename). Once
+        // that rename lands, the source and the indexer will agree. In the
+        // meantime, the indexer reflects the correct target convention, not
+        // the temporary source state.
+        const nameAsClass = componentName
+            .replace(/([A-Z])/g, '-$1')
+            .toLowerCase()
+            .replace(/^-/, '');
+        let cssClassName;
+        if (pkgName === 'eddie-recipes' || pkgName === 'eddie-charts') {
+            // eddie-charts components are recipes in every sense except their
+            // runtime dep on Chart.js — they use the same `ed-r-*` tag and class
+            // prefix as eddie-recipes.
+            cssClassName = `ed-r-${nameAsClass}`;
+        }
+        else if (pkgName === 'eddie-pages') {
+            cssClassName = `ed-p-${nameAsClass}`;
+        }
+        else {
+            cssClassName = `ed-c-${nameAsClass}`;
+        }
+        // Extract base class
+        const baseClassMatch = content.match(/extends\s+(EdElement|EdFormElement)/);
+        const baseClass = baseClassMatch ? baseClassMatch[1] : 'EdElement';
+        // Extract properties
+        const properties = this.extractProperties(content);
+        // Extract slots
+        const slots = this.extractSlots(content);
+        // Extract events
+        const events = this.extractEvents(content);
+        // Extract CSS custom properties used
+        const cssCustomProperties = this.extractCssCustomProperties(content);
+        // Determine atomic level from stories file (uses componentDir directly —
+        // previously this constructed the stories path from a hardcoded
+        // "components/<name>" template which broke for eddie-recipes).
+        const atomicLevel = await this.getAtomicLevel(componentName, componentDir);
+        // Extract component intent from JSDoc
+        const intent = this.extractIntent(content);
+        // Extract guidelines (use / dontUse / accessibility) from JSDoc tags
+        const guidelines = this.extractGuidelines(content);
+        // Determine parent/child relationships
+        const { parentComponent, childComponents } = this.determineCompoundRelationship(tagName, componentName);
+        // Relative paths for cross-referencing. Previously hardcoded to
+        // `components/<name>/...` which only worked for eddie-web-components.
+        // Now derived from the component's actual relative directory within
+        // its package, with a package-specific subdir:
+        //   eddie-web-components → components/<relativeDir>/...
+        //   eddie-recipes        → recipes/<relativeDir>/...
+        //   eddie-pages          → pages/<relativeDir>/...
+        //
+        // Each sibling-file path (styles, stories, test) is filesystem-verified
+        // before being emitted — the previous implementation emitted all four
+        // unconditionally, so consumers querying eddie-brain saw paths like
+        // `pages/common/homepage/homepage.scss` for components that have no
+        // .scss file at all. The `component` path is always emitted because we
+        // just read it.
+        let pkgSubdir;
+        if (pkgName === 'eddie-recipes') {
+            pkgSubdir = 'recipes';
+        }
+        else if (pkgName === 'eddie-pages') {
+            pkgSubdir = 'pages';
+        }
+        else if (pkgName === 'eddie-charts') {
+            pkgSubdir = 'charts';
+        }
+        else {
+            pkgSubdir = 'components';
+        }
+        const paths = {
+            component: `${pkgSubdir}/${relativeDir}/${componentName}.ts`,
+        };
+        const stylesAbs = join(componentDir, `${componentName}.scss`);
+        if (existsSync(stylesAbs)) {
+            paths.styles = `${pkgSubdir}/${relativeDir}/${componentName}.scss`;
+        }
+        const storiesAbs = join(componentDir, `${componentName}.stories.ts`);
+        if (existsSync(storiesAbs)) {
+            paths.stories = `${pkgSubdir}/${relativeDir}/${componentName}.stories.ts`;
+        }
+        const testAbs = join(componentDir, 'test', `${componentName}.test.ts`);
+        if (existsSync(testAbs)) {
+            paths.test = `${pkgSubdir}/${relativeDir}/test/${componentName}.test.ts`;
+        }
+        // Extract composesWith from import statements in the source. This turns
+        // the previously-empty array into a real list of `<ed-*>` / `<ed-r-*>` /
+        // `<ed-p-*>` tag names that the component or template imports — the
+        // catalog answer to "what does this thing combine?". Imports that don't
+        // resolve to an Eddie component path are ignored.
+        const composesWith = this.extractComposesWith(content);
+        // Extract the component's customization surface (slots/props marked
+        // `@overridableSlot` / `@overridableProp`) and its canonical invocation
+        // (prose from `@canonicalUsage` + markup from the Default story). Both
+        // are optional — components that don't declare these tags simply get
+        // `undefined` for the corresponding field. See #642.
+        const overridableSurface = this.extractOverridableSurface(content);
+        const canonicalUsage = this.extractCanonicalUsage(content, componentDir, componentName);
+        const contentApi = this.extractContentApi(content);
+        return {
+            tagName,
+            displayName,
+            cssClassName,
+            atomicLevel,
+            package: pkgName,
+            intent,
+            baseClass,
+            properties,
+            slots,
+            cssCustomProperties,
+            events,
+            composesWith,
+            parentComponent,
+            childComponents,
+            guidelines,
+            overridableSurface,
+            canonicalUsage,
+            contentApi,
+            paths,
+        };
+    }
+    /**
+     * Extract the list of Eddie component tag names referenced via `import`
+     * statements in the source.
+     *
+     * Recognizes the canonical Eddie import paths:
+     *
+     *   import '@brad-frost-web/eddie-web-components/components/button/button';
+     *     → ed-button
+     *   import '@brad-frost-web/eddie-recipes/recipes/common/site-header/site-header';
+     *     → ed-r-site-header
+     *   import '@brad-frost-web/eddie-pages/pages/common/homepage/homepage';
+     *     → ed-p-homepage
+     *
+     * The trailing `/<name>/<name>` segment is the convention enforced by
+     * scanPackage (component basename matches its containing directory). We
+     * map the basename to a tag name using the same package → prefix table
+     * the indexer uses for cssClassName.
+     *
+     * Imports that don't match this shape (e.g. `import { html } from 'lit'`,
+     * `import styles from './foo.scss?inline'`, EdElement base-class imports)
+     * are ignored. Side-effect imports without a `from` (the most common form
+     * for Eddie component registration) and named/default imports are both
+     * matched.
+     *
+     * The resulting list is deduplicated and sorted for stable output across
+     * builds (eliminates a class of dirty-diff in the catalog snapshot).
+     */
+    extractComposesWith(content) {
+        const tagNames = new Set();
+        // Match the bare-specifier import form used everywhere in the codebase:
+        //   import '@brad-frost-web/<pkg>/<path>';
+        //   import { x } from '@brad-frost-web/<pkg>/<path>';
+        //   import x from '@brad-frost-web/<pkg>/<path>';
+        const importRegex = /import\s+(?:[^'"`;]+\s+from\s+)?['"]@brad-frost-web\/([^'"`]+)['"]/g;
+        let match;
+        while ((match = importRegex.exec(content)) !== null) {
+            const importPath = match[1];
+            const tagName = this.importPathToTagName(importPath);
+            if (tagName)
+                tagNames.add(tagName);
+        }
+        return Array.from(tagNames).sort();
+    }
+    /**
+     * Map a `@brad-frost-web/<pkg>/<path>` import specifier to its Eddie tag
+     * name, or return null if the specifier doesn't resolve to a component.
+     *
+     * Handles the three component-bearing packages:
+     *
+     *   eddie-web-components/components/<X>/<X>           → ed-<X>
+     *   eddie-recipes/recipes/<scope>/<X>/<X>             → ed-r-<X>
+     *   eddie-pages/pages/<scope>/<X>/<X>                 → ed-p-<X>
+     *
+     * Returns null for non-component imports such as the `EdElement` base
+     * class, theme/token CSS, asset paths, or any other shape we don't
+     * recognize as a registered Eddie tag.
+     */
+    importPathToTagName(importPath) {
+        const segments = importPath.split('/');
+        if (segments.length < 3)
+            return null;
+        const [pkg, ...rest] = segments;
+        // Convention: the last two path segments are `<name>/<name>` for any
+        // valid Eddie component registration import. If they don't match, it's
+        // not a component import.
+        const last = rest[rest.length - 1];
+        const beforeLast = rest[rest.length - 2];
+        if (!last || !beforeLast || last !== beforeLast)
+            return null;
+        // Skip the EdElement base class explicitly; its path is
+        // `eddie-web-components/components/EdElement` which doesn't fit the
+        // <name>/<name> convention anyway, so the check above usually catches it,
+        // but be defensive.
+        if (last === 'EdElement' || last === 'EdFormElement')
+            return null;
+        if (pkg === 'eddie-web-components' && rest[0] === 'components') {
+            return `ed-${last}`;
+        }
+        if (pkg === 'eddie-recipes' && rest[0] === 'recipes') {
+            return `ed-r-${last}`;
+        }
+        if (pkg === 'eddie-pages' && rest[0] === 'pages') {
+            return `ed-p-${last}`;
+        }
+        if (pkg === 'eddie-charts' && rest[0] === 'charts') {
+            // eddie-charts shares the `ed-r-*` tag prefix with eddie-recipes.
+            return `ed-r-${last}`;
+        }
+        return null;
+    }
+    /**
+     * Extract `use` / `dontUse` / `accessibility` guidelines from the class-level
+     * JSDoc. Recognizes three custom tag forms:
+     *
+     *   @use <text>       → adds one entry to guidelines.use
+     *   @dontuse <text>   → adds one entry to guidelines.dontUse
+     *   @a11y <text>      → adds one entry to guidelines.accessibility
+     *
+     * Tags can appear multiple times in the same JSDoc block, with each
+     * occurrence becoming a separate bullet in the corresponding array. The
+     * tag text is everything from after the tag name to the end of the line.
+     * Trailing-line continuations are not currently supported — each guideline
+     * must fit on one line.
+     *
+     * This is the counterpart to authoring-side guidelines in the component
+     * source files. Today the Eddie catalog is sparse on guidelines; this
+     * parser is the mechanism that lets new guidelines actually land in
+     * eddie-brain's output.
+     */
+    extractGuidelines(content) {
+        const jsDocMatch = content.match(/\/\*\*[\s\S]*?\*\/\s*export class/);
+        if (!jsDocMatch) {
+            return { use: [], dontUse: [], accessibility: [] };
+        }
+        const jsDocText = jsDocMatch[0];
+        const extractTag = (tag) => {
+            // Case-insensitive to tolerate @DontUse / @dontUse variations
+            const regex = new RegExp(`@${tag}\\s+([^\\n]+)`, 'gi');
+            const items = [];
+            let m;
+            while ((m = regex.exec(jsDocText)) !== null) {
+                const text = m[1].trim();
+                if (text.length > 0)
+                    items.push(text);
+            }
+            return items;
+        };
+        return {
+            use: extractTag('use'),
+            dontUse: extractTag('dontuse'),
+            accessibility: extractTag('a11y'),
+        };
+    }
+    /**
+     * Extract `@overridableSlot` and `@overridableProp` tags from class-level
+     * JSDoc. These mark the specific slots/props a consumer is expected to use
+     * to customize the component — distinct from `slots` (which lists every
+     * slot that exists) and `properties` (which lists everything the class
+     * declares). See #642 for why we need both.
+     *
+     * Tag shapes:
+     *   `@overridableSlot name — purpose`
+     *   `@overridableSlot `name` purpose`
+     *   `@overridableProp name — purpose`
+     *   (any of em-dash, en-dash, or hyphen between name and purpose; optional)
+     */
+    extractOverridableSurface(content) {
+        const jsDocMatch = content.match(/\/\*\*[\s\S]*?\*\/\s*export class/);
+        if (!jsDocMatch)
+            return undefined;
+        const jsDocText = jsDocMatch[0];
+        const slots = [];
+        const props = [];
+        const slotRegex = /@overridableSlot\s+`?([\w-]+)`?\s*[-—–]?\s*([^\n]*)/gi;
+        let m;
+        while ((m = slotRegex.exec(jsDocText)) !== null) {
+            const name = m[1];
+            const purpose = m[2].trim();
+            if (name)
+                slots.push({ name, purpose });
+        }
+        const propRegex = /@overridableProp\s+`?([\w-]+)`?\s*[-—–]?\s*([^\n]*)/gi;
+        while ((m = propRegex.exec(jsDocText)) !== null) {
+            const name = m[1];
+            const purpose = m[2].trim();
+            if (name)
+                props.push({ name, purpose });
+        }
+        if (slots.length === 0 && props.length === 0)
+            return undefined;
+        return { slots, props };
+    }
+    /**
+     * Extract the canonical invocation of the component.
+     *
+     * Sourced from two places:
+     *   - Optional `@canonicalUsage` JSDoc tag on the class → prose `note`
+     *   - The `Default` export in the component's stories file → `default`
+     *     markup (only when the story uses `html\`...\`` — imperative
+     *     `document.createElement` stories are skipped because they have no
+     *     static markup to extract)
+     *
+     * The goal (per #642): when a consumer asks "use the default site header",
+     * an agent can call `eddie_get_component` and get back the exact markup to
+     * paste. No interpretation, no guessing.
+     */
+    extractCanonicalUsage(content, componentDir, componentName) {
+        let note;
+        const jsDocMatch = content.match(/\/\*\*[\s\S]*?\*\/\s*export class/);
+        if (jsDocMatch) {
+            const tagMatch = jsDocMatch[0].match(/@canonicalUsage\s+([^\n]+)/i);
+            if (tagMatch)
+                note = tagMatch[1].trim();
+        }
+        const storiesPath = join(componentDir, `${componentName}.stories.ts`);
+        const markup = this.extractDefaultStoryMarkup(storiesPath);
+        if (!note && !markup)
+            return undefined;
+        return { default: markup, note };
+    }
+    /**
+     * Extract a `@contentApi { ... }` JSDoc tag from the class-level comment.
+     *
+     * The tag value is a JSON-ish object literal (single quotes or double quotes
+     * accepted, trailing commas tolerated). Three keys are recognized:
+     *
+     *   contentVia       — string description of the primary content path
+     *   labelVia         — "prop" | "slot" | "none"
+     *   labelVisibility  — "visible" | "hidden" | "accessible-only"
+     *
+     * Components that don't declare the tag get `undefined`. See #627: this is
+     * the structural answer to "where does this component's content come from?",
+     * letting consumers and validators detect prop-vs-slot mismatches before
+     * they render as silent drops.
+     */
+    extractContentApi(content) {
+        const jsDocMatch = content.match(/\/\*\*[\s\S]*?\*\/\s*export class/);
+        if (!jsDocMatch)
+            return undefined;
+        const tagMatch = jsDocMatch[0].match(/@contentApi\s*(\{[\s\S]*?\})/i);
+        if (!tagMatch)
+            return undefined;
+        // The tag body is JSON-ish but lenient: bare keys, single or double
+        // quotes, and trailing commas are all acceptable. Pull out each known
+        // field by name with a tolerant per-key regex rather than relying on
+        // JSON.parse — the JSDoc continuation asterisks make the body messy
+        // enough that strict parsing isn't worth it.
+        const body = tagMatch[1].replace(/^\s*\*\s?/gm, '');
+        const result = {};
+        const contentVia = body.match(/\bcontentVia\s*:\s*['"]([^'"]+)['"]/);
+        if (contentVia)
+            result.contentVia = contentVia[1];
+        const labelVia = body.match(/\blabelVia\s*:\s*['"](prop|slot|none)['"]/);
+        if (labelVia)
+            result.labelVia = labelVia[1];
+        const labelVisibility = body.match(/\blabelVisibility\s*:\s*['"](visible|hidden|accessible-only)['"]/);
+        if (labelVisibility) {
+            result.labelVisibility = labelVisibility[1];
+        }
+        if (Object.keys(result).length === 0)
+            return undefined;
+        return result;
+    }
+    /**
+     * Parse the `Default` story template literal out of a stories file.
+     *
+     * Recognizes the common Eddie story shape:
+     *
+     *   export const Default = () => html`<ed-foo></ed-foo>`;
+     *   export const Default = (args: Args) => html`<ed-foo>...</ed-foo>`;
+     *   export const Default = () => html`
+     *     <ed-foo>
+     *       ...
+     *     </ed-foo>
+     *   `;
+     *
+     * Returns undefined for imperative stories (`document.createElement(...)`)
+     * which have no extractable markup — consumers of those recipes interact
+     * via JS properties rather than markup and don't benefit from a canonical
+     * markup string.
+     */
+    extractDefaultStoryMarkup(storiesPath) {
+        if (!existsSync(storiesPath))
+            return undefined;
+        let content;
+        try {
+            content = readFileSync(storiesPath, 'utf-8');
+        }
+        catch {
+            return undefined;
+        }
+        const match = content.match(/export\s+const\s+Default[^=]*=\s*(?:\([^)]*\)\s*=>\s*)?(?:\{\s*return\s+)?html`([^`]*)`/);
+        if (!match)
+            return undefined;
+        return match[1].trim();
+    }
+    /**
+     * Extract @property decorated properties
+     */
+    extractProperties(content) {
+        const properties = [];
+        // Match @property decorators and following property declarations.
+        //
+        // IMPORTANT: `[^=;\n]*` (not `[^=]*`) constrains the between-name-and-equals
+        // match so it cannot cross statement terminators. Previously the regex used
+        // `[^=]*` which is greedy and newline-permissive, so after matching a
+        // property declaration with no default (e.g. `variant?: 'bare';`) the
+        // engine would continue across newlines looking for the next `=` sign
+        // anywhere in the file — typically landing inside the render method on
+        // something like `const componentClassNames = this.componentClassNames(...)`
+        // and capturing truncated method-call text as the "default value". The
+        // tighter character class prevents that cross-statement leakage.
+        const propRegex = /@property\s*\(\s*({[^}]*})?\s*\)\s*(?:declare\s+)?(\w+)[^=;\n]*(?:=\s*([^;\n]+))?/g;
+        let match;
+        while ((match = propRegex.exec(content)) !== null) {
+            const decoratorConfig = match[1] || '';
+            const propName = match[2];
+            const rawDefault = match[3]?.trim();
+            // Sanity-check the captured default: if it has unbalanced parens/braces
+            // it's a truncated expression (multi-line method call, template literal,
+            // object initializer that extends past the line) and should not be
+            // emitted as a "default value". Emit nothing in that case.
+            const defaultValue = rawDefault && this.hasBalancedDelimiters(rawDefault)
+                ? rawDefault
+                : undefined;
+            // Extract type from property context
+            const contextStart = Math.max(0, match.index - 500);
+            const contextEnd = match.index + 300;
+            const context = content.substring(contextStart, contextEnd);
+            const typeMatch = context.match(new RegExp(`${propName}\\s*:\\s*([^;=\n]+)`));
+            const propType = typeMatch ? typeMatch[1].trim().split(/[{|}]/)[0].trim() : 'string';
+            // Check if required
+            const required = !decoratorConfig.includes('type: Boolean') && !defaultValue;
+            // Extract the JSDoc comment IMMEDIATELY preceding this @property decorator.
+            //
+            // Historic bug (#642): the previous implementation used a forward regex
+            // `/\/\*\*[\s\S]*?\*\/\s*@property/` on a 500-char-back context window.
+            // Non-greedy matching starts at the earliest `/**` in the window, so
+            // when property A's JSDoc + declaration fits into the window preceding
+            // property B, the regex finds A's `/** ... */ @property a: ...` and
+            // returns A's description for B. Reproducible on `ed-logo`: the
+            // `accent` property was getting `href`'s description.
+            //
+            // Fix: walk backward from the @property match to find the closest `*/`,
+            // verify there's only whitespace between that `*/` and the @property
+            // (so we know this JSDoc actually belongs to THIS property), then find
+            // the matching `/**`.
+            const before = content.substring(0, match.index);
+            const jsDocEnd = before.lastIndexOf('*/');
+            let description = '';
+            if (jsDocEnd !== -1) {
+                const between = before.substring(jsDocEnd + 2);
+                if (/^\s*$/.test(between)) {
+                    const jsDocStart = before.lastIndexOf('/**', jsDocEnd);
+                    if (jsDocStart !== -1) {
+                        description = before
+                            .substring(jsDocStart, jsDocEnd + 2)
+                            .replace(/\/\*\*/, '')
+                            .replace(/\*\//, '')
+                            .split('\n')
+                            .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+                            .filter((line) => line.length > 0)
+                            .join(' ');
+                    }
+                }
+            }
+            // Extract enum options if present
+            const options = this.extractEnumOptions(propType);
+            properties.push({
+                name: propName,
+                type: propType.split('|')[0].trim(),
+                default: defaultValue,
+                description,
+                options,
+                required,
+            });
+        }
+        return properties;
+    }
+    /**
+     * Extract enum options from union types
+     */
+    extractEnumOptions(type) {
+        const unionMatch = type.match(/['"]([^'"]+)['"]\s*\|\s*['"]([^'"]+)['"]/g);
+        if (unionMatch) {
+            return unionMatch.map((opt) => opt.replace(/['"]/g, ''));
+        }
+        return undefined;
+    }
+    /**
+     * Extract slot definitions from JSDoc comments.
+     *
+     * Parses the Eddie JSDoc slot convention, which comes in these forms:
+     *
+     *   @slot - The default slot description.        (default slot, leading dash)
+     *   @slot header - Optional header content       (named slot, name before dash)
+     *   @slot `header` Optional header content       (named slot, backticked name)
+     *   @slot Just a default description             (default slot, no dash, bare prose)
+     *
+     * Also looks for `<slot name="x">` in the render template as a secondary
+     * source for slots that weren't explicitly documented in JSDoc.
+     *
+     * Historic bug: the previous regex `/@slot\s*(?:-\s*)?([^\n]*)/` consumed
+     * the optional leading `- ` and then an inner regex `/^`?(\w+)`?/` grabbed
+     * the first word of the remaining text as the slot name. For a default slot
+     * like `@slot - The grid items`, this produced slot name "The" (the first
+     * word of "The grid items") instead of "default". Bug fix: distinguish the
+     * four cases above explicitly.
+     */
+    extractSlots(content) {
+        const slots = [];
+        // Grab each @slot JSDoc line individually
+        const slotLineRegex = /@slot\s+([^\n]*)/g;
+        let match;
+        while ((match = slotLineRegex.exec(content)) !== null) {
+            const rest = match[1].trim();
+            let name;
+            let description;
+            if (rest.startsWith('-')) {
+                // Form: "@slot - description"  → default slot
+                name = 'default';
+                description = rest.slice(1).trim();
+            }
+            else {
+                const backtickMatch = rest.match(/^`(\w+)`\s*-?\s*(.*)$/);
+                const dashMatch = rest.match(/^(\w+)\s+-\s+(.*)$/);
+                if (backtickMatch) {
+                    // Form: "@slot `name` description"  → named slot, backticked
+                    name = backtickMatch[1];
+                    description = backtickMatch[2].trim();
+                }
+                else if (dashMatch) {
+                    // Form: "@slot name - description"  → named slot, dash-separated
+                    name = dashMatch[1];
+                    description = dashMatch[2].trim();
+                }
+                else {
+                    // Form: "@slot Just a description"  → default slot, bare prose.
+                    // We do NOT pluck the first word as a name — that was the historic
+                    // bug. If the author wanted a named slot they would have used one
+                    // of the explicit forms above.
+                    name = 'default';
+                    description = rest;
+                }
+            }
+            slots.push({ name, description });
+        }
+        // Supplement with any slots declared in the render template that weren't
+        // caught by JSDoc (e.g., when the author named a slot but didn't document
+        // it with @slot).
+        const renderSlotRegex = /<slot\s+name=["']([^"']+)["']/g;
+        let renderMatch;
+        while ((renderMatch = renderSlotRegex.exec(content)) !== null) {
+            const slotName = renderMatch[1];
+            if (!slots.find((s) => s.name === slotName)) {
+                slots.push({ name: slotName, description: '' });
+            }
+        }
+        return slots;
+    }
+    /**
+     * Returns true if the given string has balanced parens, braces, and
+     * brackets. Used to reject truncated expressions (like multi-line method
+     * calls that span past the regex capture boundary) from being emitted as
+     * property default values.
+     */
+    hasBalancedDelimiters(s) {
+        let paren = 0;
+        let brace = 0;
+        let bracket = 0;
+        for (const c of s) {
+            if (c === '(')
+                paren++;
+            else if (c === ')')
+                paren--;
+            else if (c === '{')
+                brace++;
+            else if (c === '}')
+                brace--;
+            else if (c === '[')
+                bracket++;
+            else if (c === ']')
+                bracket--;
+            if (paren < 0 || brace < 0 || bracket < 0)
+                return false;
+        }
+        return paren === 0 && brace === 0 && bracket === 0;
+    }
+    /**
+     * Extract custom events from dispatch calls
+     */
+    extractEvents(content) {
+        const events = [];
+        // Look for dispatchEvent or dispatch calls
+        const dispatchRegex = /dispatch\(['"]([^'"]+)['"]/g;
+        let match;
+        while ((match = dispatchRegex.exec(content)) !== null) {
+            const eventName = match[1];
+            if (!events.find((e) => e.name === eventName)) {
+                events.push({
+                    name: eventName,
+                    description: '',
+                });
+            }
+        }
+        return events;
+    }
+    /**
+     * Extract CSS custom properties referenced
+     */
+    extractCssCustomProperties(content) {
+        const props = new Set();
+        // Look for var(--ed-*) in SCSS content
+        const varRegex = /var\((--ed[^)]+)\)/g;
+        let match;
+        while ((match = varRegex.exec(content)) !== null) {
+            props.add(match[1]);
+        }
+        return Array.from(props).sort();
+    }
+    /**
+     * Extract intent/purpose from JSDoc comment.
+     *
+     * Parses the class-level JSDoc preceding `export class` and returns the
+     * first real description paragraph. A "paragraph" is a sequence of
+     * consecutive non-blank, non-@tag lines joined with spaces.
+     *
+     * Heading detection: Eddie components sometimes begin their JSDoc with a
+     * one-word title line (e.g. "Grid", "Button") on its own, separated from
+     * the actual description by a blank line. In that case the first paragraph
+     * is just the single heading word, which is not a useful intent. If the
+     * first paragraph is a short heading-like line AND a second paragraph
+     * exists, return the second paragraph instead.
+     *
+     * Historic bug: the previous implementation used `.slice(0, 1)` on the
+     * filtered lines, which returned only the first non-blank non-@ line
+     * regardless of context — so `ed-grid`'s intent came back as literally the
+     * single word "Grid" while its real description lived on the next
+     * paragraph. Bug fix: paragraph-aware extraction.
+     */
+    extractIntent(content) {
+        const jsDocMatch = content.match(/\/\*\*[\s\S]*?\*\/\s*export class/);
+        if (!jsDocMatch) {
+            return '';
+        }
+        const lines = jsDocMatch[0]
+            .replace(/\/\*\*/, '')
+            .replace(/\*\//, '')
+            .split('\n')
+            .map((line) => line.replace(/^\s*\*\s?/, '').trim());
+        // Group lines into paragraphs. Blank lines and @tag lines act as
+        // paragraph separators.
+        const paragraphs = [];
+        let current = [];
+        for (const line of lines) {
+            if (line.length === 0 || line.startsWith('@')) {
+                if (current.length > 0) {
+                    paragraphs.push(current);
+                    current = [];
+                }
+            }
+            else {
+                current.push(line);
+            }
+        }
+        if (current.length > 0)
+            paragraphs.push(current);
+        if (paragraphs.length === 0)
+            return '';
+        // Heading-detection heuristic: if the first paragraph is a single line
+        // of at most 3 words, treat it as a heading and prefer the next
+        // paragraph (if one exists). This handles components whose JSDoc starts
+        // with a title like "Grid" before the real description.
+        const firstParagraph = paragraphs[0].join(' ');
+        const looksLikeHeading = paragraphs[0].length === 1 && firstParagraph.split(/\s+/).filter(Boolean).length <= 3;
+        if (looksLikeHeading && paragraphs.length > 1) {
+            return paragraphs[1].join(' ');
+        }
+        return firstParagraph;
+    }
+    /**
+     * Get atomic level from the component's own stories file.
+     *
+     * `componentDir` is the component's actual directory (e.g.
+     * `packages/eddie-web-components/components/button` or
+     * `packages/eddie-recipes/recipes/common/project-card`). The stories file
+     * lives directly inside it as `<componentName>.stories.ts`.
+     */
+    async getAtomicLevel(componentName, componentDir) {
+        try {
+            const storiesPath = join(componentDir, `${componentName}.stories.ts`);
+            const stories = readFileSync(storiesPath, 'utf-8');
+            // Extract title from default export
+            const titleMatch = stories.match(/title:\s*['"]([^'"]+)['"]/);
+            if (!titleMatch) {
+                return 'atom';
+            }
+            const title = titleMatch[1].toLowerCase();
+            if (title.includes('atoms'))
+                return 'atom';
+            if (title.includes('molecules'))
+                return 'molecule';
+            if (title.includes('organisms'))
+                return 'organism';
+            if (title.includes('recipes'))
+                return 'recipe';
+            if (title.includes('charts'))
+                return 'recipe';
+            if (title.includes('pages'))
+                return 'page';
+            return 'atom';
+        }
+        catch {
+            return 'atom';
+        }
+    }
+    /**
+     * Determine parent/child relationships for compound components
+     */
+    determineCompoundRelationship(tagName, componentName) {
+        // Check if this is a child component (starts with a parent name)
+        const parentMatch = Array.from(this.components.values()).find((comp) => tagName !== comp.tagName && tagName.startsWith(comp.tagName + '-'));
+        if (parentMatch) {
+            return {
+                parentComponent: parentMatch.tagName,
+            };
+        }
+        // Check if this is a parent with children
+        const children = Array.from(this.components.values())
+            .filter((comp) => comp.tagName.startsWith(tagName + '-'))
+            .map((comp) => comp.tagName);
+        if (children.length > 0) {
+            return {
+                childComponents: children,
+            };
+        }
+        return {};
+    }
+    /**
+     * Convert class name to display name
+     */
+    classNameToDisplayName(className) {
+        return className
+            .replace(/^Ed/, '')
+            .replace(/([A-Z])/g, ' $1')
+            .trim();
+    }
+    /**
+     * Get a component by tag name
+     */
+    getComponent(tagName) {
+        return this.components.get(tagName);
+    }
+    /**
+     * Get all components
+     */
+    getAll() {
+        return Array.from(this.components.values());
+    }
+    /**
+     * Search components by query string
+     */
+    /**
+     * Search components by natural-language query.
+     *
+     * Historic bug (#610): used naive `.includes()` substring matching against
+     * only tagName / displayName / intent. A multi-word query like "marketing
+     * homepage" never matched `ed-p-marketing-homepage` because the literal
+     * substring "marketing homepage" (with a space) is not anywhere in the
+     * tagName, displayName, or single-sentence intent. Pages were effectively
+     * invisible to any query an agent would actually type.
+     *
+     * Fix: tokenize the query, drop stopwords and very short terms, and score
+     * each candidate against the full set of fields that carry meaning —
+     * tagName, displayName, intent, guidelines.use, property names and
+     * descriptions, slot names and descriptions. Pages get a ranking boost
+     * when the query contains page-intent keywords ("page", "template",
+     * "dashboard", "homepage", "login", "article", etc.) because in that
+     * case the agent is looking for a full composition starting point, not
+     * a primitive.
+     */
+    search(query) {
+        const STOPWORDS = new Set([
+            'a', 'an', 'the', 'of', 'in', 'on', 'at', 'to', 'for', 'by',
+            'is', 'it', 'as', 'or', 'and', 'with', 'that', 'this', 'from',
+            'how', 'what', 'which', 'use', 'using', 'build', 'make',
+        ]);
+        const PAGE_KEYWORDS = new Set([
+            'page', 'pages', 'template', 'starter', 'shell', 'layout',
+            'homepage', 'dashboard', 'article', 'login', 'authentication',
+            'auth', 'checkout', 'form', 'grid',
+        ]);
+        const terms = query
+            .toLowerCase()
+            .split(/\s+/)
+            .map((t) => t.replace(/[^a-z0-9-]/g, ''))
+            .filter((t) => t.length > 2 && !STOPWORDS.has(t));
+        if (terms.length === 0)
+            return [];
+        const queryWantsPage = terms.some((t) => PAGE_KEYWORDS.has(t));
+        const scoreEntry = (comp) => {
+            const haystack = {
+                tagName: comp.tagName.toLowerCase(),
+                displayName: comp.displayName.toLowerCase(),
+                intent: comp.intent.toLowerCase(),
+                useGuidelines: comp.guidelines.use.join(' ').toLowerCase(),
+                propNames: comp.properties.map((p) => p.name.toLowerCase()).join(' '),
+                propDescriptions: comp.properties.map((p) => p.description.toLowerCase()).join(' '),
+                slotNames: comp.slots.map((s) => s.name.toLowerCase()).join(' '),
+                slotDescriptions: comp.slots.map((s) => s.description.toLowerCase()).join(' '),
+            };
+            let score = 0;
+            for (const t of terms) {
+                if (haystack.tagName.includes(t))
+                    score += 5;
+                if (haystack.displayName.includes(t))
+                    score += 3;
+                if (haystack.intent.includes(t))
+                    score += 3;
+                if (haystack.useGuidelines.includes(t))
+                    score += 2;
+                if (haystack.slotNames.includes(t))
+                    score += 2;
+                if (haystack.propNames.includes(t))
+                    score += 1;
+                if (haystack.slotDescriptions.includes(t))
+                    score += 1;
+                if (haystack.propDescriptions.includes(t))
+                    score += 1;
+            }
+            // Boost pages when the query reads like it wants a page template.
+            if (queryWantsPage && comp.atomicLevel === 'page')
+                score += 6;
+            return score;
+        };
+        return this.getAll()
+            .map((comp) => ({ comp, score: scoreEntry(comp) }))
+            .filter((r) => r.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .map((r) => r.comp);
+    }
+    /**
+     * Get components by atomic level
+     */
+    getByAtomicLevel(level) {
+        return this.getAll().filter((comp) => comp.atomicLevel === level);
+    }
+    /**
+     * Serialize to JSON
+     */
+    toJSON() {
+        const obj = {};
+        for (const [tagName, entry] of this.components) {
+            obj[tagName] = entry;
+        }
+        return obj;
+    }
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(obj) {
+        const index = new ComponentIndex();
+        for (const [tagName, entry] of Object.entries(obj)) {
+            index.components.set(tagName, entry);
+        }
+        return index;
+    }
+}
+//# sourceMappingURL=component-index.js.map