@brad-frost-web/eddie-brain 0.32.0

package/dist/knowledge-graph/component-index.d.ts

@@ -0,0 +1,320 @@
+/**
+ * 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 type { AtomicLevel, ComponentEntry } from '../types.js';
+export declare class ComponentIndex {
+    private components;
+    /**
+     * 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.
+     */
+    build(rootDir: string): Promise<void>;
+    /**
+     * 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.
+     */
+    private scanPackage;
+    /**
+     * 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)
+     */
+    private parseComponent;
+    /**
+     * 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).
+     */
+    private extractComposesWith;
+    /**
+     * 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.
+     */
+    private importPathToTagName;
+    /**
+     * 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.
+     */
+    private extractGuidelines;
+    /**
+     * 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)
+     */
+    private extractOverridableSurface;
+    /**
+     * 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.
+     */
+    private extractCanonicalUsage;
+    /**
+     * 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.
+     */
+    private extractContentApi;
+    /**
+     * 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.
+     */
+    private extractDefaultStoryMarkup;
+    /**
+     * Extract @property decorated properties
+     */
+    private extractProperties;
+    /**
+     * Extract enum options from union types
+     */
+    private extractEnumOptions;
+    /**
+     * 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.
+     */
+    private extractSlots;
+    /**
+     * 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.
+     */
+    private hasBalancedDelimiters;
+    /**
+     * Extract custom events from dispatch calls
+     */
+    private extractEvents;
+    /**
+     * Extract CSS custom properties referenced
+     */
+    private extractCssCustomProperties;
+    /**
+     * 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.
+     */
+    private extractIntent;
+    /**
+     * 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`.
+     */
+    private getAtomicLevel;
+    /**
+     * Determine parent/child relationships for compound components
+     */
+    private determineCompoundRelationship;
+    /**
+     * Convert class name to display name
+     */
+    private classNameToDisplayName;
+    /**
+     * Get a component by tag name
+     */
+    getComponent(tagName: string): ComponentEntry | undefined;
+    /**
+     * Get all components
+     */
+    getAll(): ComponentEntry[];
+    /**
+     * 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: string): ComponentEntry[];
+    /**
+     * Get components by atomic level
+     */
+    getByAtomicLevel(level: AtomicLevel): ComponentEntry[];
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): Record<string, ComponentEntry>;
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(obj: Record<string, ComponentEntry>): ComponentIndex;
+}
+//# sourceMappingURL=component-index.d.ts.map

package/dist/knowledge-graph/component-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-index.d.ts","sourceRoot":"","sources":["../../src/knowledge-graph/component-index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EAKf,MAAM,aAAa,CAAC;AAErB,qBAAa,cAAc;IACzB,OAAO,CAAC,UAAU,CAA0C;IAE5D;;;;;;;;;;;;;;;;OAgBG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;YACW,WAAW;IA2DzB;;;;;;;;;;;;OAYG;YACW,cAAc;IAsL5B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,mBAAmB;IA+B3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,iBAAiB;IA8BzB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IA6BjC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,yBAAyB;IAejC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA2FzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,YAAY;IAuDpB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;OAEG;IACH,OAAO,CAAC,aAAa;IAoBrB;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAclC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,aAAa;IA4CrB;;;;;;;OAOG;YACW,cAAc;IA0B5B;;OAEG;IACH,OAAO,CAAC,6BAA6B;IA6BrC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIzD;;OAEG;IACH,MAAM,IAAI,cAAc,EAAE;IAI1B;;OAEG;IACH;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IA2DvC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,cAAc,EAAE;IAItD;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAQxC;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,cAAc;CAOrE"}