mindheal 1.0.0

package/dist/types/rag/context-retriever.d.ts

@@ -0,0 +1,69 @@
+/**
+ * RAG Context Retriever — collects relevant context from all knowledge sources.
+ *
+ * Before the AI healing strategy runs, the retriever searches the knowledge store
+ * for entries that are relevant to the current broken locator. The returned
+ * context chunks are injected into the AI prompt so the model can make better
+ * decisions based on project-specific knowledge.
+ *
+ * Six knowledge sources are supported:
+ *   1. healing-history  — previously healed locators for the same page/selector
+ *   2. page-objects     — POM class metadata (selectors, method names, file paths)
+ *   3. git-changes      — recent git diffs that may explain why a locator broke
+ *   4. dom-snapshots    — historical DOM snapshots of the same page
+ *   5. component-docs   — component library / design system documentation
+ *   6. test-specs       — test file context (describe blocks, step descriptions)
+ */
+import type { RAGConfig, RAGContextChunk, LocatorInfo, HealingEvent } from '../types/index';
+import { KnowledgeStore } from './knowledge-store';
+export declare class ContextRetriever {
+    private readonly config;
+    private readonly store;
+    constructor(config: RAGConfig, store: KnowledgeStore);
+    /**
+     * Retrieve relevant context for a broken locator.
+     *
+     * Builds a search query from the locator info + page URL, queries the
+     * knowledge store, and returns ranked context chunks that meet the
+     * similarity threshold.
+     */
+    retrieve(originalLocator: LocatorInfo, pageUrl: string, action: string, errorMessage: string): RAGContextChunk[];
+    /**
+     * Ingest a completed healing event into the knowledge store so future
+     * healings can learn from it.
+     */
+    ingestHealingEvent(event: HealingEvent): void;
+    /**
+     * Ingest page object metadata into the knowledge store.
+     * Call this when scanning page object files during initialization.
+     */
+    ingestPageObject(filePath: string, selectors: string[], className: string): void;
+    /**
+     * Ingest git diff context into the knowledge store.
+     * Call this when a git change is detected that might affect locators.
+     */
+    ingestGitChange(filePath: string, diff: string, commitMessage: string): void;
+    /**
+     * Ingest a DOM snapshot into the knowledge store.
+     * Stores a condensed version for future reference.
+     */
+    ingestDOMSnapshot(pageUrl: string, html: string, title: string): void;
+    /**
+     * Ingest component/design-system documentation.
+     */
+    ingestComponentDoc(componentName: string, doc: string, filePath: string): void;
+    /**
+     * Ingest test spec context (describe blocks, test titles, step descriptions).
+     */
+    ingestTestSpec(testFile: string, testTitle: string, steps: string[]): void;
+    /**
+     * Build a rich search query from the healing context.
+     * Combines locator info, URL, action, and error for best TF-IDF matching.
+     */
+    private buildQuery;
+    /**
+     * Get the knowledge store instance (for direct access / testing).
+     */
+    getStore(): KnowledgeStore;
+}
+//# sourceMappingURL=context-retriever.d.ts.map

package/dist/types/rag/context-retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-retriever.d.ts","sourceRoot":"","sources":["../../../src/rag/context-retriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EAEf,WAAW,EACX,YAAY,EACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAE3B,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc;IAKpD;;;;;;OAMG;IACH,QAAQ,CACN,eAAe,EAAE,WAAW,EAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,eAAe,EAAE;IAsCpB;;;OAGG;IACH,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAyC7C;;;OAGG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IA8BhF;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IA6B5E;;;OAGG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IA8BrE;;OAEG;IACH,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAsB9E;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAgC1E;;;OAGG;IACH,OAAO,CAAC,UAAU;IAmBlB;;OAEG;IACH,QAAQ,IAAI,cAAc;CAG3B"}

package/dist/types/rag/embeddings.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lightweight text similarity engine for RAG retrieval.
+ *
+ * Uses TF-IDF-style term weighting with cosine similarity — no external
+ * embedding model or vector DB required. This is intentionally simple so
+ * MindHeal works offline (e.g. with Ollama) without any extra infrastructure.
+ *
+ * For large knowledge bases, consumers can swap in a real vector DB via the
+ * `ContextRetriever` interface.
+ */
+/**
+ * Tokenizes text into lowercase alphanumeric terms, splitting on non-word
+ * characters. Also generates bigrams for better matching on locator patterns
+ * like "submit-btn" or "getByTestId".
+ */
+export declare function tokenize(text: string): string[];
+export type TermVector = Map<string, number>;
+/**
+ * Builds a term-frequency vector from a list of tokens.
+ */
+export declare function buildTermVector(tokens: string[]): TermVector;
+/**
+ * Computes cosine similarity between two term vectors.
+ * Returns a value between 0 (completely different) and 1 (identical).
+ */
+export declare function cosineSimilarity(a: TermVector, b: TermVector): number;
+/**
+ * Computes similarity between two text strings.
+ * Convenience wrapper over tokenize → buildTermVector → cosineSimilarity.
+ */
+export declare function textSimilarity(textA: string, textB: string): number;
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/types/rag/embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../../src/rag/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/C;AAID,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE7C;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAa5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAmBrE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUnE"}

package/dist/types/rag/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * RAG (Retrieval-Augmented Generation) module.
+ *
+ * Provides context-aware AI healing by maintaining a knowledge store
+ * of healing history, page objects, git changes, DOM snapshots,
+ * component docs, and test specs.
+ */
+export { KnowledgeStore } from './knowledge-store';
+export { ContextRetriever } from './context-retriever';
+export { tokenize, buildTermVector, cosineSimilarity, textSimilarity } from './embeddings';
+export type { TermVector } from './embeddings';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/rag/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC3F,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/types/rag/knowledge-store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * File-backed knowledge store for RAG context.
+ *
+ * Stores healing history, page object metadata, git diffs, DOM snapshots,
+ * component docs, and test specs as searchable entries. Uses lightweight
+ * TF-IDF similarity for retrieval — no vector DB required.
+ */
+import type { RAGKnowledgeEntry, RAGSourceName, RAGContextChunk } from '../types/index';
+export declare class KnowledgeStore {
+    private readonly storePath;
+    private entries;
+    private loaded;
+    constructor(storePath: string);
+    load(): void;
+    save(): void;
+    add(entry: Omit<RAGKnowledgeEntry, 'id' | 'createdAt' | 'updatedAt'>): RAGKnowledgeEntry;
+    /**
+     * Add or update an entry. If an entry with matching source + tags exists,
+     * update it instead of creating a duplicate.
+     */
+    upsert(entry: Omit<RAGKnowledgeEntry, 'id' | 'createdAt' | 'updatedAt'>): RAGKnowledgeEntry;
+    getAll(): RAGKnowledgeEntry[];
+    getBySource(source: RAGSourceName): RAGKnowledgeEntry[];
+    /**
+     * Search the knowledge store for entries relevant to the query.
+     * Returns ranked results above the similarity threshold.
+     */
+    search(query: string, options?: {
+        sources?: RAGSourceName[];
+        maxResults?: number;
+        similarityThreshold?: number;
+    }): RAGContextChunk[];
+    /**
+     * Get entry count.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=knowledge-store.d.ts.map

package/dist/types/rag/knowledge-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-store.d.ts","sourceRoot":"","sources":["../../../src/rag/knowledge-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAEjB,aAAa,EACb,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAUxB,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,MAAM,CAAU;gBAEZ,SAAS,EAAE,MAAM;IAQ7B,IAAI,IAAI,IAAI;IAkCZ,IAAI,IAAI,IAAI;IAiBZ,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG,iBAAiB;IAuBxF;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG,iBAAiB;IAmB3F,MAAM,IAAI,iBAAiB,EAAE;IAI7B,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,EAAE;IAMvD;;;OAGG;IACH,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;QACP,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;QAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;KACzB,GACL,eAAe,EAAE;IA6CpB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/types/reporters/heal-report.d.ts

@@ -0,0 +1,29 @@
+import type { HealReport } from '../types/index';
+/**
+ * Generates HTML and JSON healing reports summarizing all healing events
+ * from a test run.
+ */
+export declare class HealReportGenerator {
+    /**
+     * Serialize a HealReport to a formatted JSON string.
+     */
+    generateJSON(report: HealReport): string;
+    /**
+     * Generate a self-contained HTML report with inline styles.
+     */
+    generateHTML(report: HealReport): string;
+    /**
+     * Persist the report to disk in JSON and/or HTML format.
+     */
+    saveReport(report: HealReport, outputDir: string, generateHTML: boolean, generateJSON: boolean): Promise<void>;
+    private computeStats;
+    private computeStrategyBreakdown;
+    private renderEventRow;
+    private confidenceColor;
+    private strategyColor;
+    private escapeHTML;
+    private formatDate;
+    private formatDuration;
+    private shortenPath;
+}
+//# sourceMappingURL=heal-report.d.ts.map

package/dist/types/reporters/heal-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heal-report.d.ts","sourceRoot":"","sources":["../../../src/reporters/heal-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAqC,MAAM,gBAAgB,CAAC;AAKpF;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B;;OAEG;IACI,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM;IAI/C;;OAEG;IACI,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM;IAoI/C;;OAEG;IACU,UAAU,CACrB,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,OAAO,EACrB,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,IAAI,CAAC;IAoChB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,wBAAwB;IAYhC,OAAO,CAAC,cAAc;IAmCtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,WAAW;CAKpB"}

package/dist/types/reporters/heal-reporter.d.ts

@@ -0,0 +1,49 @@
+import type { Reporter, FullConfig, Suite, TestCase, TestResult, FullResult } from '@playwright/test/reporter';
+import type { MindHealConfig } from '../types/index';
+/**
+ * Custom Playwright reporter that hooks into the test lifecycle to collect
+ * healing events, generate reports, and optionally create PRs or launch the
+ * interactive review server.
+ *
+ * Usage in `playwright.config.ts`:
+ * ```ts
+ * reporter: [['mindheal/reporter', { ai: { provider: 'anthropic', apiKey: '...' } }]]
+ * ```
+ */
+export default class HealReporter implements Reporter {
+    private config;
+    private startTime;
+    private totalTests;
+    private reportGenerator;
+    constructor(options?: Partial<MindHealConfig>);
+    /**
+     * Called once before tests start running.
+     */
+    onBegin(config: FullConfig, suite: Suite): void;
+    /**
+     * Called after each test finishes. Used to tag healing events with the
+     * test title so the report is more informative.
+     */
+    onTestEnd(test: TestCase, result: TestResult): void;
+    /**
+     * Called once after all tests have completed. Drives report generation,
+     * git operations, and the review server workflow.
+     */
+    onEnd(result: FullResult): Promise<void>;
+    private handleCIWorkflow;
+    private handleLocalWorkflow;
+    /**
+     * Apply approved code modifications using the AST-based CodeModifier.
+     */
+    private applyApprovedModifications;
+    /**
+     * Convert healing events into CodeModification objects for the CodeModifier.
+     * Events without source locations or healed locators are skipped.
+     */
+    private buildModifications;
+    /**
+     * Build a markdown PR description summarizing all modifications.
+     */
+    private buildPRBody;
+}
+//# sourceMappingURL=heal-reporter.d.ts.map

package/dist/types/reporters/heal-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heal-reporter.d.ts","sourceRoot":"","sources":["../../../src/reporters/heal-reporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACV,KAAK,EACL,QAAQ,EACR,UAAU,EACV,UAAU,EACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,cAAc,EAIf,MAAM,gBAAgB,CAAC;AAWxB;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,YAAW,QAAQ;IACnD,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,eAAe,CAAsB;gBAEjC,OAAO,GAAE,OAAO,CAAC,cAAc,CAAM;IAKjD;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAS/C;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAenD;;;OAGG;IACG,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;YAkFhC,gBAAgB;YA0EhB,mBAAmB;IAiDjC;;OAEG;YACW,0BAA0B;IAuBxC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;OAEG;IACH,OAAO,CAAC,WAAW;CA6BpB"}

package/dist/types/server/review-server.d.ts

@@ -0,0 +1,20 @@
+import type { ReviewServerConfig, HealingEvent } from '../types/index';
+export declare class ReviewServer {
+    private readonly config;
+    private events;
+    private app;
+    private httpServer;
+    private wss;
+    private reviewResolve;
+    constructor(config: ReviewServerConfig, events: HealingEvent[]);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    waitForReview(): Promise<HealingEvent[]>;
+    private setupApp;
+    private onEventUpdated;
+    private broadcastUpdate;
+    private broadcastAllReviewed;
+    private allReviewed;
+    private buildSummary;
+}
+//# sourceMappingURL=review-server.d.ts.map

package/dist/types/server/review-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-server.d.ts","sourceRoot":"","sources":["../../../src/server/review-server.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EAEb,MAAM,gBAAgB,CAAC;AAIxB,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,GAAG,CAAsB;IACjC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,aAAa,CAAmD;gBAE5D,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,YAAY,EAAE;IAUxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBrB,aAAa,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAY9C,OAAO,CAAC,QAAQ;IA4BhB,OAAO,CAAC,cAAc;IA4BtB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,oBAAoB;IAe5B,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,YAAY;CAQrB"}

package/dist/types/server/routes.d.ts

@@ -0,0 +1,4 @@
+import express from 'express';
+import type { HealingEvent } from '../types/index';
+export declare function createRoutes(events: HealingEvent[], onUpdate: (event: HealingEvent) => void): express.Router;
+//# sourceMappingURL=routes.d.ts.map

package/dist/types/server/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/server/routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,gBAAgB,CAAC;AAElE,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EAAE,EACtB,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GACtC,OAAO,CAAC,MAAM,CA4GhB"}