@selfcure/analyzer 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# @selfcure/analyzer
+
+> Testability scorer for **selfcure** — classifies interactive elements and computes a 0–100 score per component.
+
+Takes `ComponentMeta[]` from [`@selfcure/crawler`](https://www.npmjs.com/package/@selfcure/crawler), builds a `selectorRanking` per element (`data-testid` → `id` → `aria-label` → `name` → CSS → XPath), detects **ambiguous locators** (when the best selector for an element also matches a sibling), and emits a testability score plus a dedup-aware suggested `data-testid`.
+
+Internal library powering [`@selfcure/cli`](https://www.npmjs.com/package/@selfcure/cli) and [`@selfcure/mcp`](https://www.npmjs.com/package/@selfcure/mcp).
+
+## Install
+
+```bash
+npm install @selfcure/analyzer
+```
+
+## Docs
+
+Full documentation: https://github.com/ricardofrancocustodio/selfcure#readme

package/dist/index.d.ts

@@ -0,0 +1,550 @@
+import { TestIdUsage, A11yFileEvidence, ComponentMeta } from '@selfcure/crawler';
+
+type TagMaturityLevel = 0 | 1 | 2 | 3 | 4;
+type TagMaturityLabel = 'unusable' | 'fragile' | 'usable' | 'stable' | 'governed';
+declare const TML_LABELS: Record<TagMaturityLevel, TagMaturityLabel>;
+type TagMaturityReasonCode = 'stable-testid' | 'missing-testid' | 'invalid-testid-name' | 'duplicate-testid' | 'deprecated-testid' | 'strong-role-name' | 'generic-accessible-name' | 'missing-accessible-name' | 'ambiguous-selector' | 'weak-css-selector' | 'runtime-not-observed' | 'runtime-unique' | 'missing-owner' | 'missing-intent';
+interface TagMaturityReason {
+    code: TagMaturityReasonCode;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    evidence?: string[];
+}
+type TagMaturityChangeType = 'add-testid' | 'rename-testid' | 'dedupe-testid' | 'add-accessible-name' | 'add-inventory-entry' | 'add-owner' | 'add-intent' | 'replace-selector' | 'confirm-runtime-state';
+interface TagMaturityChange {
+    type: TagMaturityChangeType;
+    priority: 'low' | 'medium' | 'high';
+    description: string;
+    suggestedValue?: string;
+    /** True when selfcure can auto-patch this without user review */
+    patchAvailable?: boolean;
+}
+interface TagMaturityResult {
+    level: TagMaturityLevel;
+    label: TagMaturityLabel;
+    /** Mirrors the element's testabilityScore at assessment time */
+    score: number;
+    reasons: TagMaturityReason[];
+    requiredChanges: TagMaturityChange[];
+    /** 0–1 confidence in this assessment (lower when evidence is ambiguous) */
+    confidence: number;
+}
+interface TmlInventoryEntry {
+    hasOwner: boolean;
+    hasIntent: boolean;
+    hasRoute: boolean;
+    isDeprecated: boolean;
+    isDuplicate: boolean;
+    namingValid: boolean;
+}
+interface TagMaturityInput {
+    /** 0–100 testability score (after ambiguity penalties) */
+    testabilityScore: number;
+    /** True when the best selector matches multiple siblings in the same component */
+    ambiguous: boolean;
+    /** Best selector strategy (from selectorRanking[0].strategy) */
+    bestStrategy: 'data-testid' | 'id' | 'aria-label' | 'name' | 'css' | 'xpath';
+    /** Label for testid suggestion (label → id → aria-label) */
+    label?: string;
+    /** Element tag for suggestion building */
+    elementType: string;
+    /** Inventory metadata — only set when TestId Inventory Phase 3 is wired up */
+    inventory?: TmlInventoryEntry;
+    /** Runtime data — only set when agentic discovery Phase 7 is wired up */
+    runtime?: {
+        observed: boolean;
+        unique: boolean;
+    };
+}
+
+type InventoryElementStatus = 'active' | 'deprecated' | 'removed';
+type InventoryElementStability = 'stable' | 'unstable' | 'dynamic';
+interface InventoryElement {
+    testId: string;
+    component?: string;
+    elementType?: string;
+    intent?: string;
+    label?: string;
+    sourceFile?: string;
+    status: InventoryElementStatus;
+    stability: InventoryElementStability;
+    firstSeenAt?: string;
+    lastSeenAt?: string;
+    /** For dynamic IDs: pattern template, e.g. "users.table.row.{userId}.{action}-button" */
+    pattern?: string;
+    /** Owning team — overrides route-level owner when set */
+    owner?: string;
+}
+interface InventoryRoute {
+    path: string;
+    screen?: string;
+    owner?: string;
+    elements: InventoryElement[];
+}
+interface TestIdInventory {
+    version: string;
+    app: string;
+    generatedAt: string;
+    routes: InventoryRoute[];
+}
+
+type ParseResult = {
+    ok: true;
+    inventory: TestIdInventory;
+} | {
+    ok: false;
+    errors: string[];
+};
+declare function parseInventory(raw: string): ParseResult;
+declare function loadInventory(filePath: string): Promise<ParseResult>;
+/**
+ * Return all testId strings from a parsed inventory in insertion order,
+ * deduplicating across routes.
+ */
+declare function allTestIds(inventory: TestIdInventory): string[];
+
+type AuditRuleId = 'duplicate-testid' | 'missing-inventory' | 'orphaned-inventory' | 'test-only-selector' | 'invalid-name' | 'generic-name' | 'missing-owner' | 'deprecated-used';
+type IssueSeverity = 'error' | 'warning';
+interface AuditIssue {
+    rule: AuditRuleId;
+    severity: IssueSeverity;
+    testId: string;
+    locations?: string[];
+    message?: string;
+}
+interface AuditSummary {
+    totalObserved: number;
+    duplicates: number;
+    missingInventory: number;
+    orphaned: number;
+    testOnlySelectors: number;
+    invalidNames: number;
+}
+interface AuditResult$1 {
+    summary: AuditSummary;
+    issues: AuditIssue[];
+}
+/**
+ * Audit a scanned set of usages against a governed inventory.
+ * Returns all detected issues plus a summary.
+ */
+declare function audit(inventory: TestIdInventory, usages: TestIdUsage[]): AuditResult$1;
+
+interface NamingViolation {
+    testId: string;
+    rule: 'invalid-name' | 'generic-name';
+    reason: string;
+}
+/**
+ * Validate a single testId against the naming convention.
+ * Returns null when the name is valid, or a violation descriptor when not.
+ */
+declare function checkNaming(testId: string): NamingViolation | null;
+/** Return true when the testId conforms to the naming convention. */
+declare function isValidTestId(testId: string): boolean;
+
+type WcagLevel = 'A' | 'AA' | 'AAA';
+type A11ySeverity = 'info' | 'minor' | 'major' | 'critical';
+type A11yCategory = 'perceivable' | 'operable' | 'understandable' | 'robust';
+type A11ySource = 'static' | 'dynamic' | 'hybrid';
+type FindingStatus = 'open' | 'resolved' | 'suppressed';
+interface AccessibilityRule {
+    id: string;
+    wcag: string[];
+    level: WcagLevel;
+    category: A11yCategory;
+    severity: A11ySeverity;
+    source: A11ySource;
+    paid: boolean;
+    title: string;
+    description: string;
+    remediation: string;
+}
+interface AccessibilityFinding {
+    id: string;
+    ruleId: string;
+    wcag: string[];
+    level: WcagLevel;
+    severity: A11ySeverity;
+    status: FindingStatus;
+    route?: string;
+    component?: string;
+    sourceFile: string;
+    line: number;
+    column: number;
+    selector?: string;
+    testId?: string;
+    accessibleName?: string;
+    message: string;
+    remediation: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    owner?: string;
+}
+interface FindingInventory {
+    version: string;
+    app: string;
+    standard: 'WCAG';
+    targetLevel: WcagLevel;
+    generatedAt: string;
+    findings: AccessibilityFinding[];
+}
+/** Requires a reason, owner, and expiration — suppressions without expiry are invalid in CI mode. */
+interface FindingSuppression {
+    findingId: string;
+    reason: string;
+    owner: string;
+    expiresAt: string;
+}
+
+/** Severity levels in ascending order. */
+declare const SEVERITY_ORDER: ReadonlyArray<A11ySeverity>;
+/**
+ * WCAG level hierarchy: targeting AA means checking A + AA rules.
+ * Targeting AAA means checking all levels.
+ */
+declare const LEVEL_HIERARCHY: Readonly<Record<WcagLevel, ReadonlyArray<WcagLevel>>>;
+declare const accessibilityRules: ReadonlyArray<AccessibilityRule>;
+declare function getRuleById(id: string): AccessibilityRule | undefined;
+/** Return all rules applicable to the given WCAG target level (inclusive of lower levels). */
+declare function getRulesByLevel(targetLevel: WcagLevel): AccessibilityRule[];
+/** Return all rules at or above the given severity. */
+declare function getRulesBySeverity(minSeverity: A11ySeverity): AccessibilityRule[];
+interface RuleFilterOptions {
+    /** Include only rules applicable to this WCAG level and below. */
+    level?: WcagLevel;
+    /** Include only rules at or above this severity. */
+    minSeverity?: A11ySeverity;
+    /** Filter by paid status. */
+    paid?: boolean;
+    /** Filter by analysis source (static / dynamic / hybrid). */
+    source?: AccessibilityRule['source'];
+    /** Filter by WCAG principle category. */
+    category?: AccessibilityRule['category'];
+}
+declare function filterRules(opts?: RuleFilterOptions): AccessibilityRule[];
+
+interface StaticAnalysisOptions {
+    /** WCAG target level — rules above this level are excluded. Default: 'AA'. */
+    level?: WcagLevel;
+}
+/**
+ * Run static accessibility analysis against JSX/TSX evidence extracted by the crawler.
+ * Returns findings sorted by file path then line number.
+ */
+declare function runStaticAnalysis(evidenceList: A11yFileEvidence[], opts?: StaticAnalysisOptions): AccessibilityFinding[];
+
+interface RuntimeElement {
+    tag: string;
+    role?: string;
+    /** Accessible name — aria-label or visible text */
+    name?: string;
+    /** Best selector available */
+    selector: string;
+    testId?: string;
+    /** Testability score 0–100 */
+    score: number;
+}
+interface RuntimeRouteEvidence {
+    url: string;
+    route: string;
+    status: 'reachable' | 'error' | 'timeout' | 'auth-required';
+    title?: string;
+    domSnapshotPath?: string;
+    accessibilityTreePath?: string;
+    screenshotPath?: string;
+    interactiveElements: RuntimeElement[];
+    consoleErrors: string[];
+    loadTimeMs: number;
+}
+interface RuntimeDiscoveryResult {
+    routes: RuntimeRouteEvidence[];
+    scannedRoutes: number;
+    reachable: number;
+    errored: number;
+}
+interface TestabilityFinding {
+    route: string;
+    url: string;
+    element: RuntimeElement;
+    score: number;
+    issues: string[];
+}
+interface RouteTestabilityResult {
+    route: string;
+    url: string;
+    status: RuntimeRouteEvidence['status'];
+    score: number;
+    totalElements: number;
+    flaggedCount: number;
+    findings: TestabilityFinding[];
+}
+interface TestabilityReport {
+    generatedAt: string;
+    minimumScore: number;
+    routes: RouteTestabilityResult[];
+    overall: {
+        score: number;
+        totalElements: number;
+        flaggedCount: number;
+    };
+}
+/**
+ * Compute a testability report from Playwright runtime discovery evidence.
+ * Only elements with score < minimumScore are reported as findings.
+ */
+declare function buildTestabilityReport(result: RuntimeDiscoveryResult, minimumScore?: number): TestabilityReport;
+/**
+ * Group findings by severity bucket for quick summary display.
+ */
+declare function summarizeReport(report: TestabilityReport): {
+    critical: RouteTestabilityResult[];
+    warning: RouteTestabilityResult[];
+    healthy: RouteTestabilityResult[];
+};
+
+declare function deriveTestIdSuggestion(label: string | undefined, elementType: string): string;
+/**
+ * Compute the Tag Maturity Level for a single interactive element.
+ *
+ * The function is pure — it does not read files or call external APIs.
+ * Inventory and runtime signals are optional; when absent the assessment
+ * is based entirely on static selector evidence.
+ */
+declare function assessTagMaturity(input: TagMaturityInput): TagMaturityResult;
+
+/** Build a set of testId values that appear more than once in the inventory. */
+declare function buildDuplicateSet(inventory: TestIdInventory): Set<string>;
+declare function isValidTmlNaming(testId: string): boolean;
+/**
+ * Find inventory metadata for a given testId across all routes.
+ * Returns undefined when the testId is not registered.
+ */
+declare function buildTmlInventoryEntry(testId: string, inventory: TestIdInventory, duplicateIds: Set<string>): TmlInventoryEntry | undefined;
+interface EnrichableElement$1 {
+    testabilityScore: number;
+    ambiguous: boolean;
+    label?: string;
+    type: string;
+    selectors: {
+        dataTestId?: string;
+    };
+    selectorRanking: Array<{
+        strategy: string;
+    }>;
+    tml?: unknown;
+}
+/**
+ * Re-compute TML for all elements, enriching with inventory metadata.
+ * Mutates each element's `tml` field in place.
+ *
+ * Call this after `analyze()` when a TestId Inventory is available.
+ */
+declare function enrichTmlWithInventory(results: Array<{
+    interactiveElements: EnrichableElement$1[];
+}>, inventory: TestIdInventory): void;
+
+interface RuntimeEl {
+    tag: string;
+    testId?: string;
+    name?: string;
+    selector: string;
+}
+interface RouteEvidence {
+    route: string;
+    status: string;
+    interactiveElements: RuntimeEl[];
+}
+interface RuntimeMap {
+    routes: RouteEvidence[];
+}
+interface EnrichableSelector {
+    dataTestId?: string;
+    ariaLabel?: string;
+    id?: string;
+}
+interface EnrichableElement {
+    testabilityScore: number;
+    ambiguous: boolean;
+    label?: string;
+    type: string;
+    selectors: EnrichableSelector;
+    selectorRanking: Array<{
+        strategy: string;
+    }>;
+    tml?: unknown;
+}
+/**
+ * Re-compute TML for all elements using Playwright runtime evidence from
+ * `selfcure discover --runtime`. Mutates each element's `tml` field in place.
+ *
+ * Pass the same `inventory` used in `enrichTmlWithInventory()` to preserve
+ * governance signals while adding runtime caps.
+ *
+ * Effects per element:
+ *  - Observed + unique    → confidence boost; static/inventory level preserved.
+ *  - Observed + not unique → cap at TML 1 (locator ambiguous in live page).
+ *  - Not observed          → cap at TML 2 (element absent in rendered DOM).
+ */
+declare function enrichTmlWithRuntime(results: Array<{
+    interactiveElements: EnrichableElement[];
+}>, runtimeMap: RuntimeMap, inventory?: TestIdInventory): void;
+declare function loadRuntimeMap(filePath: string): Promise<RuntimeMap>;
+
+type FindingsParseResult = {
+    ok: true;
+    inventory: FindingInventory;
+} | {
+    ok: false;
+    errors: string[];
+};
+declare function parseFindings(raw: string): FindingsParseResult;
+declare function loadFindings(filePath: string): Promise<FindingsParseResult>;
+declare function saveFindings(filePath: string, inventory: FindingInventory): Promise<void>;
+declare function emptyInventory(opts: {
+    app: string;
+    targetLevel?: WcagLevel;
+}): FindingInventory;
+/**
+ * Merge findings from a new static scan into the existing inventory.
+ *
+ * Rules:
+ * - Suppressed findings are never touched.
+ * - Existing open/resolved findings that still appear → status 'open', lastSeenAt updated.
+ * - Existing open findings that no longer appear → status 'resolved'.
+ * - Previously resolved findings that reappear → status 'open', lastSeenAt updated.
+ * - New findings not in inventory → appended as 'open'.
+ *
+ * Match key: ruleId + sourceFile + line + column.
+ */
+declare function mergeFindings(existing: FindingInventory, newFindings: AccessibilityFinding[]): FindingInventory;
+
+type SeverityCounts = Record<A11ySeverity, number>;
+interface AuditCounts {
+    open: number;
+    resolved: number;
+    suppressed: number;
+    bySeverity: SeverityCounts;
+}
+interface AuditResult {
+    /** All findings (open + resolved + suppressed) from the inventory. */
+    findings: AccessibilityFinding[];
+    counts: AuditCounts;
+    /**
+     * True when at least one open finding has severity >= failOn.
+     * Use this to decide the CI exit code.
+     */
+    wouldFailCI: boolean;
+}
+interface AuditOptions {
+    /**
+     * Minimum severity that triggers a CI failure.
+     * Findings below this threshold are reported but do not fail.
+     * Default: 'major'.
+     */
+    failOn?: A11ySeverity;
+}
+/**
+ * Audit a findings inventory: compute lifecycle counts and determine whether
+ * the build should fail in CI mode.
+ */
+declare function runAudit(inventory: FindingInventory, opts?: AuditOptions): AuditResult;
+
+/** One flagged element, normalised from a lint issue. */
+interface IdePromptIssue {
+    /** Path to the source file containing the element. */
+    filePath: string;
+    /** Component the element belongs to, when known. */
+    componentName?: string;
+    /** Element kind: button / input / link / form / custom. */
+    elementType: string;
+    /** The element's current best selector (helps the agent locate it). */
+    selector?: string;
+    /** 1-based source line, when known. */
+    line?: number;
+    /**
+     * Why it was flagged:
+     *   • 'ambiguous'  — best selector also matches a sibling.
+     *   • 'low-score'  — no stable selector (testability below threshold).
+     */
+    kind: 'ambiguous' | 'low-score';
+    /** Human-readable reason when kind === 'ambiguous'. */
+    ambiguityReason?: string;
+    /** The data-testid selfcure suggests for this element. */
+    suggestedTestId: string;
+}
+interface IdePromptOptions {
+    /** Naming convention shown to the agent. Has a sensible default. */
+    convention?: string;
+    /** Relativise file paths against this directory (e.g. the project root). */
+    baseDir?: string;
+}
+/**
+ * Build a paste-ready prompt instructing an IDE AI agent (Copilot, Cursor,
+ * Claude Code, …) to add `data-testid` attributes to the flagged elements.
+ * Returns an empty string when there are no issues.
+ */
+declare function buildIdePrompt(issues: IdePromptIssue[], opts?: IdePromptOptions): string;
+
+type ElementType = 'button' | 'input' | 'link' | 'form' | 'custom';
+type Complexity = 'low' | 'medium' | 'high';
+interface SelectorCandidate {
+    strategy: 'data-testid' | 'id' | 'aria-label' | 'name' | 'css' | 'xpath';
+    /** Ready-to-use selector string */
+    value: string;
+    /** Stability score 0–100: higher = less likely to break on UI changes */
+    score: number;
+    /** How many elements within the same component match this selector value */
+    matchCount?: number;
+    /** How many elements across all analysed components match this selector value */
+    crossMatchCount?: number;
+    /** True when the selector matches more than one element in the same component */
+    ambiguous?: boolean;
+}
+interface ElementSelectors {
+    dataTestId?: string;
+    id?: string;
+    ariaLabel?: string;
+    name?: string;
+    /** Best CSS selector (may alias one of the above) */
+    cssSelector: string;
+    /** XPath expression */
+    xpath: string;
+}
+interface InteractiveElement {
+    type: ElementType;
+    /** Best selector — always equals selectorRanking[0].value */
+    selector: string;
+    label?: string;
+    /** e.g. ['click', 'fill', 'check'] */
+    actions: string[];
+    /** All available selectors for this element */
+    selectors: ElementSelectors;
+    /** Candidates sorted from most stable (index 0) to least stable */
+    selectorRanking: SelectorCandidate[];
+    /** Testability score for this element 0–100 */
+    testabilityScore: number;
+    /**
+     * True when the best available selector also matches another element in
+     * the same component — Playwright would resolve to multiple nodes.
+     */
+    ambiguous: boolean;
+    /** Human-readable explanation when {@link ambiguous} is true */
+    ambiguityReason?: string;
+    /** Tag Maturity Level assessment — populated by analyze() */
+    tml?: TagMaturityResult;
+}
+interface AnalysisResult {
+    component: ComponentMeta;
+    /** Testability score 0–100 — average of per-element testabilityScore values */
+    score: number;
+    interactiveElements: InteractiveElement[];
+    complexity: Complexity;
+}
+/**
+ * Analyse crawled components: classify their interactive elements, compute a
+ * testability score, and flag overall complexity.
+ */
+declare function analyze(components: ComponentMeta[]): Promise<AnalysisResult[]>;
+
+export { type AuditResult as A11yAuditResult, type A11yCategory, type A11ySeverity, type A11ySource, type AccessibilityFinding, type AccessibilityRule, type AnalysisResult, type AuditCounts, type AuditIssue, type AuditOptions, type AuditRuleId, type AuditSummary, type Complexity, type ElementSelectors, type ElementType, type FindingInventory, type FindingStatus, type FindingSuppression, type FindingsParseResult, type IdePromptIssue, type IdePromptOptions, type InteractiveElement, type InventoryElement, type InventoryElementStability, type InventoryElementStatus, type InventoryRoute, type IssueSeverity, LEVEL_HIERARCHY, type NamingViolation, type ParseResult, type RouteTestabilityResult, type RuleFilterOptions, type RuntimeMap, SEVERITY_ORDER, type SelectorCandidate, type SeverityCounts, type StaticAnalysisOptions, TML_LABELS, type TagMaturityChange, type TagMaturityInput, type TagMaturityLabel, type TagMaturityLevel, type TagMaturityReason, type TagMaturityReasonCode, type TagMaturityResult, type AuditResult$1 as TestIdAuditResult, type TestIdInventory, type TestabilityFinding, type TestabilityReport, type TmlInventoryEntry, type WcagLevel, accessibilityRules, allTestIds, analyze, assessTagMaturity, audit, buildDuplicateSet, buildIdePrompt, buildTestabilityReport, buildTmlInventoryEntry, checkNaming, analyze as default, deriveTestIdSuggestion, emptyInventory, enrichTmlWithInventory, enrichTmlWithRuntime, filterRules, getRuleById, getRulesByLevel, getRulesBySeverity, isValidTestId, isValidTmlNaming, loadFindings, loadInventory, loadRuntimeMap, mergeFindings, parseFindings, parseInventory, runAudit, runStaticAnalysis, saveFindings, summarizeReport };