@brad-frost-web/eddie-brain 0.32.0

package/dist/knowledge-graph/learning-history.js

@@ -0,0 +1,187 @@
+/**
+ * LearningHistory — Track feedback and learn from interactions
+ *
+ * Records suggestions that were accepted, rejected, or modified,
+ * and computes statistics about the agent's accuracy and user preferences.
+ */
+import { readFileSync, writeFileSync } from 'fs';
+export class LearningHistory {
+    entries = [];
+    /**
+     * Record a learning entry
+     */
+    record(entry) {
+        this.entries.push(entry);
+    }
+    /**
+     * Get all entries
+     */
+    getAll() {
+        return [...this.entries];
+    }
+    /**
+     * Get entries for a specific target (component, token, file, etc.)
+     */
+    getForTarget(target) {
+        return this.entries.filter((e) => e.suggestion.target === target);
+    }
+    /**
+     * Get entries by type
+     */
+    getByType(type) {
+        return this.entries.filter((e) => e.suggestion.type === type);
+    }
+    /**
+     * Get entries by decision
+     */
+    getByDecision(decision) {
+        return this.entries.filter((e) => e.decision === decision);
+    }
+    /**
+     * Get entries by tag
+     */
+    getByTag(tag) {
+        return this.entries.filter((e) => e.tags.includes(tag));
+    }
+    /**
+     * Get entries within a time range
+     */
+    getByDateRange(startTime, endTime) {
+        const start = new Date(startTime).getTime();
+        const end = new Date(endTime).getTime();
+        return this.entries.filter((e) => {
+            const eTime = new Date(e.timestamp).getTime();
+            return eTime >= start && eTime <= end;
+        });
+    }
+    /**
+     * Compute statistics about learning
+     */
+    getStats() {
+        const total = this.entries.length;
+        if (total === 0) {
+            return {
+                totalSuggestions: 0,
+                acceptanceRate: 0,
+                rejectionRate: 0,
+                modificationRate: 0,
+                acceptedCount: 0,
+                rejectedCount: 0,
+                modifiedCount: 0,
+                accuracyTrend: [],
+                mostRejectedType: '',
+                mostAcceptedType: '',
+            };
+        }
+        const accepted = this.entries.filter((e) => e.decision === 'accepted').length;
+        const rejected = this.entries.filter((e) => e.decision === 'rejected').length;
+        const modified = this.entries.filter((e) => e.decision === 'modified').length;
+        const acceptanceRate = accepted / total;
+        const rejectionRate = rejected / total;
+        const modificationRate = modified / total;
+        // Compute trend by week
+        const byWeek = new Map();
+        for (const entry of this.entries) {
+            const date = new Date(entry.timestamp);
+            const weekStart = new Date(date);
+            weekStart.setDate(date.getDate() - date.getDay());
+            const weekKey = weekStart.toISOString().split('T')[0];
+            if (!byWeek.has(weekKey)) {
+                byWeek.set(weekKey, { accepted: 0, total: 0 });
+            }
+            const week = byWeek.get(weekKey);
+            week.total++;
+            if (entry.decision === 'accepted') {
+                week.accepted++;
+            }
+        }
+        const accuracyTrend = Array.from(byWeek.entries())
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([week, stats]) => ({
+            week,
+            accuracy: stats.accepted / stats.total,
+        }));
+        // Find most rejected and accepted types
+        const typeStats = new Map();
+        for (const entry of this.entries) {
+            if (!typeStats.has(entry.suggestion.type)) {
+                typeStats.set(entry.suggestion.type, { accepted: 0, rejected: 0 });
+            }
+            const stats = typeStats.get(entry.suggestion.type);
+            if (entry.decision === 'accepted') {
+                stats.accepted++;
+            }
+            else if (entry.decision === 'rejected') {
+                stats.rejected++;
+            }
+        }
+        let mostRejectedType = '';
+        let maxRejections = 0;
+        for (const [type, stats] of typeStats) {
+            if (stats.rejected > maxRejections) {
+                maxRejections = stats.rejected;
+                mostRejectedType = type;
+            }
+        }
+        let mostAcceptedType = '';
+        let maxAcceptances = 0;
+        for (const [type, stats] of typeStats) {
+            if (stats.accepted > maxAcceptances) {
+                maxAcceptances = stats.accepted;
+                mostAcceptedType = type;
+            }
+        }
+        return {
+            totalSuggestions: total,
+            acceptanceRate,
+            rejectionRate,
+            modificationRate,
+            acceptedCount: accepted,
+            rejectedCount: rejected,
+            modifiedCount: modified,
+            accuracyTrend,
+            mostRejectedType,
+            mostAcceptedType,
+        };
+    }
+    /**
+     * Clear all entries
+     */
+    clear() {
+        this.entries = [];
+    }
+    /**
+     * Save to a JSON file
+     */
+    save(filePath) {
+        writeFileSync(filePath, JSON.stringify(this.toJSON(), null, 2), 'utf-8');
+    }
+    /**
+     * Load from a JSON file
+     */
+    static load(filePath) {
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            const data = JSON.parse(content);
+            return LearningHistory.fromJSON(data);
+        }
+        catch {
+            return new LearningHistory();
+        }
+    }
+    /**
+     * Serialize to JSON
+     */
+    toJSON() {
+        return [...this.entries];
+    }
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(arr) {
+        const history = new LearningHistory();
+        history.entries = [...arr];
+        return history;
+    }
+}
+//# sourceMappingURL=learning-history.js.map

package/dist/knowledge-graph/learning-history.js.map

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

package/dist/knowledge-graph/relationship-map.d.ts

@@ -0,0 +1,55 @@
+/**
+ * RelationshipMap — Track component composition recipes
+ *
+ * Stores canonical composition recipes and analyzes component relationships
+ * to understand how components work together.
+ */
+import type { CompositionRecipe } from '../types.js';
+import type { ComponentIndex } from './component-index.js';
+export declare class RelationshipMap {
+    private recipes;
+    /**
+     * Add a composition recipe
+     */
+    addRecipe(recipe: CompositionRecipe): void;
+    /**
+     * Get a recipe by name
+     */
+    getRecipe(name: string): CompositionRecipe | undefined;
+    /**
+     * Find all recipes that involve a component
+     */
+    findRecipesFor(tagName: string): CompositionRecipe[];
+    /**
+     * Get all recipes
+     */
+    getAll(): CompositionRecipe[];
+    /**
+     * Get recipes by status
+     */
+    getByStatus(status: 'canonical' | 'candidate' | 'deprecated'): CompositionRecipe[];
+    /**
+     * Build relationships from component analysis
+     *
+     * Scans component properties and slots to infer composition recipes.
+     * This is a starting point for recipe discovery.
+     */
+    buildFromComponents(componentIndex: ComponentIndex): Promise<void>;
+    /**
+     * Infer composition recipes from component metadata
+     */
+    private inferRecipes;
+    /**
+     * Infer the role of a card child component
+     */
+    private inferCardChildRole;
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): Record<string, CompositionRecipe>;
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(obj: Record<string, CompositionRecipe>): RelationshipMap;
+}
+//# sourceMappingURL=relationship-map.d.ts.map

package/dist/knowledge-graph/relationship-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-map.d.ts","sourceRoot":"","sources":["../../src/knowledge-graph/relationship-map.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAmC,MAAM,aAAa,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAA6C;IAE5D;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAI1C;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAItD;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAMpD;;OAEG;IACH,MAAM,IAAI,iBAAiB,EAAE;IAI7B;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,iBAAiB,EAAE;IAIlF;;;;;OAKG;IACG,mBAAmB,CAAC,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxE;;OAEG;IACH,OAAO,CAAC,YAAY;IAoKpB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAQ3C;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,eAAe;CAOzE"}

package/dist/knowledge-graph/relationship-map.js

@@ -0,0 +1,238 @@
+/**
+ * RelationshipMap — Track component composition recipes
+ *
+ * Stores canonical composition recipes and analyzes component relationships
+ * to understand how components work together.
+ */
+export class RelationshipMap {
+    recipes = new Map();
+    /**
+     * Add a composition recipe
+     */
+    addRecipe(recipe) {
+        this.recipes.set(recipe.name, recipe);
+    }
+    /**
+     * Get a recipe by name
+     */
+    getRecipe(name) {
+        return this.recipes.get(name);
+    }
+    /**
+     * Find all recipes that involve a component
+     */
+    findRecipesFor(tagName) {
+        return this.getAll().filter((recipe) => recipe.components.some((comp) => comp.tagName === tagName));
+    }
+    /**
+     * Get all recipes
+     */
+    getAll() {
+        return Array.from(this.recipes.values());
+    }
+    /**
+     * Get recipes by status
+     */
+    getByStatus(status) {
+        return this.getAll().filter((r) => r.status === status);
+    }
+    /**
+     * Build relationships from component analysis
+     *
+     * Scans component properties and slots to infer composition recipes.
+     * This is a starting point for recipe discovery.
+     */
+    async buildFromComponents(componentIndex) {
+        const components = componentIndex.getAll();
+        // Detect common recipes
+        const recipes = this.inferRecipes(components);
+        for (const recipe of recipes) {
+            this.addRecipe(recipe);
+        }
+    }
+    /**
+     * Infer composition recipes from component metadata
+     */
+    inferRecipes(components) {
+        const recipes = [];
+        // Recipe: Button with Icon
+        const button = components.find((c) => c.tagName === 'ed-button');
+        const icon = components.find((c) => c.tagName === 'ed-icon');
+        if (button && icon) {
+            recipes.push({
+                name: 'button-with-icon',
+                intent: 'A button that displays an icon alongside or above the text',
+                components: [
+                    {
+                        tagName: 'ed-button',
+                        role: 'container',
+                        required: true,
+                    },
+                    {
+                        tagName: 'ed-icon',
+                        role: 'icon',
+                        required: false,
+                    },
+                ],
+                tokens: {},
+                rules: [
+                    'Icon should have aria-hidden="true" to avoid announcing to screen readers',
+                    'Button must have text content for accessibility',
+                ],
+                confidence: 0.9,
+                status: 'canonical',
+            });
+        }
+        // Recipe: Card with Content
+        const card = components.find((c) => c.tagName === 'ed-card');
+        if (card && card.childComponents) {
+            recipes.push({
+                name: 'card-section-structure',
+                intent: 'A card layout with header, body, and footer sections',
+                components: [
+                    {
+                        tagName: 'ed-card',
+                        role: 'container',
+                        required: true,
+                    },
+                    ...card.childComponents.map((tagName) => ({
+                        tagName,
+                        role: this.inferCardChildRole(tagName),
+                        required: false,
+                    })),
+                ],
+                tokens: {},
+                rules: ['Sections should follow logical reading order'],
+                confidence: 0.85,
+                status: 'canonical',
+            });
+        }
+        // Recipe: Accordion with Items
+        const accordion = components.find((c) => c.tagName === 'ed-accordion');
+        if (accordion && accordion.childComponents) {
+            recipes.push({
+                name: 'accordion-structure',
+                intent: 'An accordion with collapsible items',
+                components: [
+                    {
+                        tagName: 'ed-accordion',
+                        role: 'container',
+                        required: true,
+                    },
+                    {
+                        tagName: 'ed-accordion-panel',
+                        role: 'item',
+                        required: true,
+                    },
+                ],
+                tokens: {},
+                rules: ['Each panel must have a unique ID', 'Only one panel can be open at a time'],
+                confidence: 0.9,
+                status: 'canonical',
+            });
+        }
+        // Recipe: Navigation structure
+        const nav = components.find((c) => c.tagName === 'ed-primary-nav');
+        if (nav) {
+            recipes.push({
+                name: 'navigation-structure',
+                intent: 'A hierarchical navigation menu',
+                components: [
+                    {
+                        tagName: 'ed-primary-nav',
+                        role: 'navigation',
+                        required: true,
+                    },
+                ],
+                tokens: {},
+                rules: ['Must use semantic nav element', 'Links should be keyboard navigable'],
+                confidence: 0.85,
+                status: 'candidate',
+            });
+        }
+        // Recipe: Form with fields
+        const textField = components.find((c) => c.tagName === 'ed-text-input');
+        const checkboxField = components.find((c) => c.tagName === 'ed-checkbox-field');
+        if (textField || checkboxField) {
+            const formFieldComponents = [];
+            if (textField) {
+                formFieldComponents.push({
+                    tagName: 'ed-text-input',
+                    role: 'input',
+                    required: false,
+                });
+            }
+            if (checkboxField) {
+                formFieldComponents.push({
+                    tagName: 'ed-checkbox-field',
+                    role: 'input',
+                    required: false,
+                });
+            }
+            recipes.push({
+                name: 'form-fields',
+                intent: 'Form inputs with labels and validation',
+                components: formFieldComponents,
+                tokens: {},
+                rules: ['All inputs must have associated labels', 'Validation messages should be announced to screen readers'],
+                confidence: 0.8,
+                status: 'candidate',
+            });
+        }
+        // Recipe: Modal/Dialog
+        const modal = components.find((c) => c.tagName === 'ed-modal');
+        if (modal) {
+            recipes.push({
+                name: 'modal-dialog',
+                intent: 'A modal dialog with header, body, and footer',
+                components: [
+                    {
+                        tagName: 'ed-modal',
+                        role: 'container',
+                        required: true,
+                    },
+                ],
+                tokens: {},
+                rules: [
+                    'Focus must be managed and returned when modal closes',
+                    'Must support Escape key to close',
+                    'Should use role="dialog"',
+                ],
+                confidence: 0.85,
+                status: 'candidate',
+            });
+        }
+        return recipes;
+    }
+    /**
+     * Infer the role of a card child component
+     */
+    inferCardChildRole(tagName) {
+        if (tagName.includes('header'))
+            return 'header';
+        if (tagName.includes('footer'))
+            return 'footer';
+        return 'content';
+    }
+    /**
+     * Serialize to JSON
+     */
+    toJSON() {
+        const obj = {};
+        for (const [name, recipe] of this.recipes) {
+            obj[name] = recipe;
+        }
+        return obj;
+    }
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(obj) {
+        const map = new RelationshipMap();
+        for (const [name, recipe] of Object.entries(obj)) {
+            map.recipes.set(name, recipe);
+        }
+        return map;
+    }
+}
+//# sourceMappingURL=relationship-map.js.map

package/dist/knowledge-graph/relationship-map.js.map

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

package/dist/knowledge-graph/token-taxonomy.d.ts

@@ -0,0 +1,127 @@
+/**
+ * TokenTaxonomy — Organize and classify design tokens
+ *
+ * Parses token files and classifies tokens by tier (definition/usage/component),
+ * category (color/spacing/typography), and theme.
+ */
+import type { TokenCategory, TokenEntry, TokenTier } from '../types.js';
+export declare class TokenTaxonomy {
+    private tokens;
+    /**
+     * Build the token taxonomy by scanning token files.
+     *
+     * Two-pass build:
+     *  1. Walk the source JSON files in `tier-{1-definitions,2-usage,3-components}/`
+     *     directories to build an authoritative `tokenName → tier` map. The file
+     *     path is the source of truth for tier; relying on CSS-variable name
+     *     heuristics mis-classifies tier-2 blocks like `animation` and `viz`
+     *     because their first segment after `--ed-theme-` isn't a stock CSS
+     *     category name (#680).
+     *  2. Parse the compiled tokens.css per theme for the actual values,
+     *     looking up the tier in the map produced by pass 1.
+     *
+     * Tokens that exist in the compiled CSS but not in any source JSON
+     * (deprecated/leftover) fall through to the legacy name-heuristic
+     * classifier so we never emit an empty tier — but in practice every
+     * compiled token traces back to a JSON definition.
+     */
+    build(rootDir: string): Promise<void>;
+    /**
+     * Build the authoritative `tokenName → tier` map by walking source JSON.
+     *
+     * Looks under any theme directory (`bfw`, `bfw-dark`, `altitude`, etc.)
+     * for these conventional subdirectories:
+     *   - `tier-1-definitions/*.json` → tier "definition"
+     *   - `tier-2-usage/*.json`        → tier "usage"
+     *   - `tier-3-components/*.json`   → tier "component"
+     *
+     * Each leaf node (object with a non-object `value`) becomes a CSS variable
+     * name derived from the path: `--ed-<dot.path.dashed>` for tier 1, and
+     * `--ed-theme-<dot.path.dashed>` for tiers 2 and 3. The tier-1 vs theme
+     * prefix split mirrors how Style Dictionary emits the compiled CSS.
+     *
+     * Earliest tier wins on collision (in practice tokens don't appear in
+     * multiple tiers; this just keeps the result deterministic).
+     */
+    private buildTierMap;
+    /**
+     * Walk a Style-Dictionary-style JSON tree and yield the CSS variable name
+     * for each leaf (object with a non-object `value` property). Non-leaf
+     * objects recurse; primitive/array values are ignored.
+     */
+    private collectCssVarNames;
+    /**
+     * Parse a tokens.css file and extract all tokens
+     */
+    private parseTokenFile;
+    /**
+     * Derive the color subcategory ("background" | "content" | "border") from
+     * a token name. The convention is that the segment immediately after
+     * `color-` in the name is the subcategory:
+     *   --ed-theme-color-background-default → "background"
+     *   --ed-theme-color-content-default    → "content"
+     *   --ed-theme-color-border-subtle      → "border"
+     * Returns undefined for non-color tokens, definition-tier color tokens
+     * (no subcategory in name), and any color-token shape we don't recognize.
+     */
+    private deriveSubcategory;
+    /**
+     * Derive the CSS properties this token is valid to apply to.
+     * Only meaningful for color tokens with a known subcategory; other tokens
+     * return undefined (no `validProperties` field on output).
+     */
+    private deriveValidProperties;
+    /**
+     * Classify a token as tier 1 (definition), tier 2 (usage), or tier 3 (component)
+     *
+     * Tier 1: --ed-{category}-{name} (e.g., --ed-color-brand-blue)
+     * Tier 2: --ed-theme-{category}-{semantic} (e.g., --ed-theme-color-background-default)
+     * Tier 3: --ed-theme-{component}-{property} (e.g., --ed-theme-button-background)
+     */
+    private classifyTier;
+    /**
+     * Classify a token by category
+     */
+    private classifyCategory;
+    /**
+     * Extract intent from token name
+     */
+    private extractIntent;
+    /**
+     * Extract what token this one references (if any)
+     */
+    private extractReferences;
+    /**
+     * Get a token by name
+     */
+    getToken(name: string): TokenEntry | undefined;
+    /**
+     * Get all tokens
+     */
+    getAll(): TokenEntry[];
+    /**
+     * Get tokens by tier
+     */
+    getByTier(tier: TokenTier): TokenEntry[];
+    /**
+     * Get tokens by category
+     */
+    getByCategory(category: TokenCategory): TokenEntry[];
+    /**
+     * Get tokens by theme
+     */
+    getByTheme(theme: string): TokenEntry[];
+    /**
+     * Get available themes
+     */
+    getThemes(): string[];
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): Record<string, TokenEntry>;
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(obj: Record<string, TokenEntry>): TokenTaxonomy;
+}
+//# sourceMappingURL=token-taxonomy.d.ts.map

package/dist/knowledge-graph/token-taxonomy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-taxonomy.d.ts","sourceRoot":"","sources":["../../src/knowledge-graph/token-taxonomy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExE,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAsC;IAEpD;;;;;;;;;;;;;;;;;OAiBG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB3C;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,YAAY;IA0BpB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAgB1B;;OAEG;YACW,cAAc;IA0C5B;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAqBpB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAwBxB;;OAEG;IACH,OAAO,CAAC,aAAa;IAiBrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAU9C;;OAEG;IACH,MAAM,IAAI,UAAU,EAAE;IActB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,EAAE;IAcxC;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,UAAU,EAAE;IAcpD;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE;IAIvC;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAQrB;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;IAepC;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,aAAa;CAOhE"}