@qa-ai-stlc/explorer 0.3.0 → 0.5.0

package/dist/analyze-static-source.d.ts

@@ -0,0 +1,24 @@
+import { type Clock } from '@qa-ai-stlc/core';
+import type { SelectorElement } from '@qa-ai-stlc/schemas';
+export interface StaticSourceFile {
+    /** Project-relative, forward-slash path (`RelativePathSchema`), recorded on every finding. */
+    readonly filePath: string;
+    readonly content: string;
+}
+export interface AnalyzeStaticSourceOptions {
+    readonly files: readonly StaticSourceFile[];
+    readonly clock?: Clock;
+}
+export interface AnalyzeStaticSourceResult {
+    readonly elements: readonly SelectorElement[];
+}
+/**
+ * Extracts `data-testid`, `aria-label` and `role` from literal (never dynamically bound) HTML-shaped
+ * attributes across React, Angular and Vue sources (development plan 6.1.2), and turns each finding
+ * into a `SelectorElement` with `source: 'static'` and a `sourceLocation` the "missing test ID"
+ * report (P1-13) can point a developer at. Never touches routes (P1-19) or a live page: `kind` comes
+ * only from the tag name or, for a custom component, a `role` of `'button'`/`'link'`; every other
+ * element the source contains and does not name through one of those signals is not observed at all.
+ */
+export declare function analyzeStaticSource(options: AnalyzeStaticSourceOptions): AnalyzeStaticSourceResult;
+//# sourceMappingURL=analyze-static-source.d.ts.map

package/dist/analyze-static-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-static-source.d.ts","sourceRoot":"","sources":["../src/analyze-static-source.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAA4C,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGrG,MAAM,WAAW,gBAAgB;IAC/B,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AA4HD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,yBAAyB,CAuBlG"}

package/dist/analyze-static-source.js

@@ -0,0 +1,133 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { hashText, systemClock } from '@qa-ai-stlc/core';
+import { createElementNamer } from './naming.js';
+const TAG_KIND = {
+    button: 'button',
+    a: 'link',
+    input: 'input',
+    select: 'select',
+    textarea: 'textarea',
+};
+// A role value that unambiguously identifies its own element kind, for a custom component
+// (`<div role="button">`, common in React/Vue/Angular design systems) that no tag-name mapping
+// above can classify. Other roles (`textbox`, `combobox`, ...) are still captured as a locator
+// candidate below; they just cannot alone decide the schema's fixed `kind` enum.
+const KIND_BY_ROLE = {
+    button: 'button',
+    link: 'link',
+};
+// A literal attribute value only: `(?<=\s)` requires the attribute name be preceded by whitespace
+// (never `:`, `.` or `[`), which is how every plain HTML/JSX attribute is written and how Vue's
+// `:name=`/`v-bind:name=` and Angular's `[attr.name]=`/`[name]=` bindings never are — so a bound,
+// non-literal value (a JS expression, not stable text) is never captured as one. The attrs chunk
+// is padded with a leading space so an attribute at the very start of it still matches.
+function literalAttribute(attrs, name) {
+    const pattern = new RegExp(`(?<=\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, 'u');
+    const match = pattern.exec(` ${attrs}`);
+    return match?.[1] ?? match?.[2];
+}
+function lineNumberAt(content, index) {
+    let line = 1;
+    for (let i = 0; i < index; i += 1) {
+        if (content[i] === '\n') {
+            line += 1;
+        }
+    }
+    return line;
+}
+// Splits `<button data-testid="x">`'s inner text ("button data-testid=\"x\"") into its tag name
+// and the rest, on plain string search/slice rather than a second regex capture group: unlike a
+// capture group, `.search()`/`.slice()` are never `string | undefined` under
+// `noUncheckedIndexedAccess`, and every opening tag genuinely has a name, so there is no real
+// "missing" case here to guard against.
+function splitTag(tagText) {
+    const boundary = tagText.search(/[\s/]/u);
+    const nameEnd = boundary === -1 ? tagText.length : boundary;
+    return { tagName: tagText.slice(0, nameEnd).toLowerCase(), attrs: tagText.slice(nameEnd) };
+}
+// A lexical scan of the raw text for `<tag ...>`, JSX/Vue/Angular alike (React's JSX, Vue's SFC
+// template block and Angular's component template all put literal HTML-shaped attributes on an
+// opening tag the same way), not a per-framework parser. It stops at the first `>` even inside a
+// quoted attribute value, and can match a `<` that starts a string or comment rather than a real
+// tag — an accepted, documented false-positive risk in exchange for needing no `@babel/parser`,
+// `vue/compiler-sfc` or `@angular/compiler` dependency.
+function findStaticElements(file) {
+    const findings = [];
+    let cursor = 0;
+    for (;;) {
+        const tagStart = file.content.indexOf('<', cursor);
+        if (tagStart === -1) {
+            break;
+        }
+        const tagEnd = file.content.indexOf('>', tagStart);
+        if (tagEnd === -1) {
+            break;
+        }
+        cursor = tagEnd + 1;
+        const tagText = file.content.slice(tagStart + 1, tagEnd);
+        if (!/^[A-Za-z]/u.test(tagText)) {
+            continue; // a closing tag, comment, doctype or fragment, never an opening tag with attributes
+        }
+        const { tagName, attrs } = splitTag(tagText);
+        const role = literalAttribute(attrs, 'role');
+        const kind = TAG_KIND[tagName] ?? (role === undefined ? undefined : KIND_BY_ROLE[role]);
+        if (kind === undefined) {
+            continue;
+        }
+        findings.push({
+            kind,
+            tagName,
+            testId: literalAttribute(attrs, 'data-testid'),
+            ariaLabel: literalAttribute(attrs, 'aria-label'),
+            role,
+            filePath: file.filePath,
+            line: lineNumberAt(file.content, tagStart),
+        });
+    }
+    return findings;
+}
+function findingNameSource(finding) {
+    return finding.testId ?? finding.ariaLabel ?? finding.role ?? `${finding.tagName}:${String(finding.line)}`;
+}
+function candidatesFor(finding) {
+    const candidates = [];
+    if (finding.role !== undefined && finding.ariaLabel !== undefined) {
+        candidates.push({
+            strategy: 'role',
+            value: JSON.stringify({ role: finding.role, name: finding.ariaLabel }),
+            fragile: false,
+        });
+    }
+    if (finding.testId !== undefined) {
+        candidates.push({ strategy: 'testId', value: finding.testId, fragile: false });
+    }
+    return candidates;
+}
+/**
+ * Extracts `data-testid`, `aria-label` and `role` from literal (never dynamically bound) HTML-shaped
+ * attributes across React, Angular and Vue sources (development plan 6.1.2), and turns each finding
+ * into a `SelectorElement` with `source: 'static'` and a `sourceLocation` the "missing test ID"
+ * report (P1-13) can point a developer at. Never touches routes (P1-19) or a live page: `kind` comes
+ * only from the tag name or, for a custom component, a `role` of `'button'`/`'link'`; every other
+ * element the source contains and does not name through one of those signals is not observed at all.
+ */
+export function analyzeStaticSource(options) {
+    const clock = options.clock ?? systemClock;
+    const lastVerifiedAt = clock.now().toISOString();
+    const nameFor = createElementNamer();
+    const elements = options.files.flatMap((file) => findStaticElements(file).map((finding) => ({
+        elementId: hashText(`${finding.filePath} ${String(finding.line)} ${finding.kind} ${findingNameSource(finding)}`),
+        name: nameFor(findingNameSource(finding), finding.kind),
+        kind: finding.kind,
+        locatorCandidates: candidatesFor(finding),
+        stabilityScore: 0,
+        lastVerifiedAt,
+        pii: false,
+        dynamicText: false,
+        source: 'static',
+        sourceLocation: { filePath: finding.filePath, line: finding.line },
+    })));
+    return { elements };
+}
+//# sourceMappingURL=analyze-static-source.js.map

package/dist/analyze-static-source.js.map

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

package/dist/build-missing-test-id-report.d.ts

@@ -0,0 +1,16 @@
+import type { MissingTestIdReport, SelectorRegistry } from '@qa-ai-stlc/schemas';
+/**
+ * Lists every non-deprecated registry element with no `testId` locator candidate (development
+ * plan section 6.3 step 9), with its source file and line when the registry knows one — only
+ * `source: 'static'` entries (P1-12) ever do; `crawl`/`manual` entries report no `sourceLocation`
+ * rather than guessing. Entries with a known location sort first, by file then line; the rest sort
+ * by `elementId`, both orders deterministic across runs on an unchanged registry.
+ */
+export declare function buildMissingTestIdReport(registry: SelectorRegistry): MissingTestIdReport;
+/**
+ * Renders a `MissingTestIdReport` to Markdown (ADR-002: Markdown is rendered from JSON, never
+ * hand-written) grouped by source file, with entries whose file is unknown collected under their
+ * own heading rather than mixed in or silently dropped.
+ */
+export declare function renderMissingTestIdReportMarkdown(report: MissingTestIdReport): string;
+//# sourceMappingURL=build-missing-test-id-report.d.ts.map

package/dist/build-missing-test-id-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-missing-test-id-report.d.ts","sourceRoot":"","sources":["../src/build-missing-test-id-report.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAsB,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAwBrG;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,mBAAmB,CAaxF;AAQD;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CA+BrF"}

package/dist/build-missing-test-id-report.js

@@ -0,0 +1,79 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { SCHEMA_VERSION } from '@qa-ai-stlc/schemas';
+function hasTestId(element) {
+    return element.locatorCandidates.some((candidate) => candidate.strategy === 'testId');
+}
+// `sourceLocation` is either present on both `a` and `b`'s underlying type or absent — it comes
+// straight from `SelectorElement.sourceLocation` (selector-registry.ts), whose own two fields are
+// both required together — so once both are known to be present, `a.sourceLocation.line` is never
+// missing and needs no fallback.
+function compareEntries(a, b) {
+    if (a.sourceLocation === undefined || b.sourceLocation === undefined) {
+        if ((a.sourceLocation === undefined) !== (b.sourceLocation === undefined)) {
+            return a.sourceLocation === undefined ? 1 : -1; // a known location sorts first
+        }
+        return a.elementId.localeCompare(b.elementId);
+    }
+    return (a.sourceLocation.filePath.localeCompare(b.sourceLocation.filePath) ||
+        a.sourceLocation.line - b.sourceLocation.line ||
+        a.elementId.localeCompare(b.elementId));
+}
+/**
+ * Lists every non-deprecated registry element with no `testId` locator candidate (development
+ * plan section 6.3 step 9), with its source file and line when the registry knows one — only
+ * `source: 'static'` entries (P1-12) ever do; `crawl`/`manual` entries report no `sourceLocation`
+ * rather than guessing. Entries with a known location sort first, by file then line; the rest sort
+ * by `elementId`, both orders deterministic across runs on an unchanged registry.
+ */
+export function buildMissingTestIdReport(registry) {
+    const entries = registry.elements
+        .filter((element) => element.deprecatedAt === undefined && !hasTestId(element))
+        .map((element) => ({
+        elementId: element.elementId,
+        ...(element.name === undefined ? {} : { name: element.name }),
+        kind: element.kind,
+        source: element.source,
+        ...(element.sourceLocation === undefined ? {} : { sourceLocation: element.sourceLocation }),
+    }))
+        .sort(compareEntries);
+    return { schemaVersion: SCHEMA_VERSION, generatedAt: registry.generatedAt, entries };
+}
+function entryLine(entry) {
+    const label = entry.name === undefined ? entry.kind : `${entry.kind} \`${entry.name}\``;
+    const location = entry.sourceLocation === undefined ? '' : ` — line ${String(entry.sourceLocation.line)}`;
+    return `- ${label} (${entry.source})${location}`;
+}
+/**
+ * Renders a `MissingTestIdReport` to Markdown (ADR-002: Markdown is rendered from JSON, never
+ * hand-written) grouped by source file, with entries whose file is unknown collected under their
+ * own heading rather than mixed in or silently dropped.
+ */
+export function renderMissingTestIdReportMarkdown(report) {
+    const count = report.entries.length;
+    const header = `# Missing test ID report\n\n_Generated ${report.generatedAt} — ${String(count)} element(s) with no test ID._`;
+    if (count === 0) {
+        return `${header}\n\nEvery interactive element has a test ID candidate.\n`;
+    }
+    const sections = [];
+    let currentFilePath;
+    let currentLines = [];
+    const flush = () => {
+        if (currentLines.length === 0) {
+            return;
+        }
+        const heading = currentFilePath ?? 'Unknown source';
+        sections.push(`## ${heading}\n\n${currentLines.join('\n')}`);
+    };
+    for (const entry of report.entries) {
+        if (entry.sourceLocation?.filePath !== currentFilePath) {
+            flush();
+            currentFilePath = entry.sourceLocation?.filePath;
+            currentLines = [];
+        }
+        currentLines.push(entryLine(entry));
+    }
+    flush();
+    return `${header}\n\n${sections.join('\n\n')}\n`;
+}
+//# sourceMappingURL=build-missing-test-id-report.js.map

package/dist/build-missing-test-id-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-missing-test-id-report.js","sourceRoot":"","sources":["../src/build-missing-test-id-report.ts"],"names":[],"mappings":"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"}

package/dist/build-selector-registry.d.ts

@@ -0,0 +1,53 @@
+import { type BrowserLauncher, type Clock, type ViewportSize } from '@qa-ai-stlc/core';
+import { type InteractiveElement, type PageModelSet, type SelectorElement, type SelectorRegistry } from '@qa-ai-stlc/schemas';
+import { type ExplorerIdentity } from './identity.js';
+import { type LocatorPolicy } from './synthesize-locators.js';
+export interface BuildSelectorRegistryOptions {
+    readonly pageModelSet: PageModelSet;
+    readonly browserLauncher: BrowserLauncher;
+    /** Signs in before re-navigating to score candidates. Omit to score anonymously. */
+    readonly identity?: ExplorerIdentity;
+    readonly policy?: LocatorPolicy;
+    readonly viewports?: readonly ViewportSize[];
+    readonly clock?: Clock;
+}
+export interface BuildSelectorRegistryResult {
+    readonly registry: SelectorRegistry;
+    /** Every non-GET request safe mode intercepted and cancelled; always 0 unless something is broken. */
+    readonly blockedRequestCount: number;
+}
+export declare function elementNameForId(element: InteractiveElement): string;
+export declare function computeElementId(url: string, element: InteractiveElement): string;
+/**
+ * Builds a `SelectorRegistry` from a `PageModelSet` produced by `analyzePages()` (development
+ * plan section 6.3 steps 4-6): synthesizes locator candidates for every interactive element under
+ * the configured policy, scores the first (primary) candidate's stability in a fresh live pass
+ * over the same URLs, and assigns each element a stable id. Every entry's `source` is `'crawl'` -
+ * the only source this pipeline produces (`static`/`manual` come from other tasks).
+ */
+export declare function buildSelectorRegistry(options: BuildSelectorRegistryOptions): Promise<BuildSelectorRegistryResult>;
+/**
+ * Merges a freshly built registry onto a previously stored one, keeping history (development plan
+ * section 6.3.6): every element the fresh crawl found replaces its previous entry outright
+ * (un-deprecating it, if it had been). An element the fresh crawl did not find is kept rather than
+ * deleted, with `deprecatedAt` set to `generatedAt` the first time it goes missing; once
+ * deprecated, its `deprecatedAt` is never overwritten by a later run that still does not find it.
+ */
+export declare function mergeSelectorRegistry(previous: SelectorRegistry, fresh: SelectorRegistry, generatedAt: string): SelectorRegistry;
+export interface DegradedSelectorElement {
+    readonly elementId: string;
+    readonly previousScore: number;
+    readonly currentScore: number;
+}
+export interface SelectorRegistryDiff {
+    readonly added: readonly SelectorElement[];
+    readonly removed: readonly SelectorElement[];
+    readonly degraded: readonly DegradedSelectorElement[];
+}
+/**
+ * Compares two crawls' registries by `elementId`: elements only the current crawl found, elements
+ * only the previous crawl found, and elements both found where the current stability score is
+ * lower than before.
+ */
+export declare function diffSelectorRegistry(previous: SelectorRegistry, current: SelectorRegistry): SelectorRegistryDiff;
+//# sourceMappingURL=build-selector-registry.d.ts.map

package/dist/build-selector-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-selector-registry.d.ts","sourceRoot":"","sources":["../src/build-selector-registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyB,KAAK,eAAe,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC9G,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAI3E,OAAO,EAA+B,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE3F,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,sGAAsG;IACtG,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAOD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAQpE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAEjF;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAsDtC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,gBAAgB,EACvB,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAalB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACvD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,gBAAgB,GACxB,oBAAoB,CAoBtB"}

package/dist/build-selector-registry.js

@@ -0,0 +1,116 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { hashText, systemClock } from '@qa-ai-stlc/core';
+import { SCHEMA_VERSION, } from '@qa-ai-stlc/schemas';
+import { resolveStorageState } from './identity.js';
+import { createElementNamer } from './naming.js';
+import { createSafeModeRouteHandler } from './safe-mode.js';
+import { scoreLocatorStability } from './stability-scoring.js';
+import { synthesizeLocatorCandidates } from './synthesize-locators.js';
+// The element's best available human-meaningful name, in the same signal-quality order
+// synthesizeLocatorCandidates already uses: the id changes only when every one of those signals
+// changes too, not on a DOM reorder alone. A position-based fallback is last resort, matching the
+// CSS candidate's own fallback (development plan section 6.3.4). Exported for pick mode (P1-14),
+// which assigns a `source: 'manual'` element the same elementId a crawl would have found for it.
+export function elementNameForId(element) {
+    return (element.accessibleName ??
+        element.label ??
+        element.testId ??
+        element.placeholder ??
+        `${element.tagName}:${String(element.nthOfType)}`);
+}
+export function computeElementId(url, element) {
+    return hashText(`${url} ${element.kind} ${elementNameForId(element)}`);
+}
+/**
+ * Builds a `SelectorRegistry` from a `PageModelSet` produced by `analyzePages()` (development
+ * plan section 6.3 steps 4-6): synthesizes locator candidates for every interactive element under
+ * the configured policy, scores the first (primary) candidate's stability in a fresh live pass
+ * over the same URLs, and assigns each element a stable id. Every entry's `source` is `'crawl'` -
+ * the only source this pipeline produces (`static`/`manual` come from other tasks).
+ */
+export async function buildSelectorRegistry(options) {
+    const clock = options.clock ?? systemClock;
+    const policy = options.policy ?? 'playwright-default';
+    const storageState = await resolveStorageState(options.browserLauncher, options.identity);
+    const browser = await options.browserLauncher.launch();
+    try {
+        const context = await browser.newContext(storageState === undefined ? {} : { storageState });
+        const page = await context.newPage();
+        let blockedRequestCount = 0;
+        await page.route('**/*', createSafeModeRouteHandler(() => {
+            blockedRequestCount += 1;
+        }));
+        const generatedAt = clock.now().toISOString();
+        const elements = [];
+        const nameFor = createElementNamer();
+        for (const pageModel of options.pageModelSet.pages) {
+            await page.goto(pageModel.url);
+            for (const interactiveElement of pageModel.interactiveElements) {
+                const candidates = synthesizeLocatorCandidates(interactiveElement, policy);
+                const primary = candidates[0];
+                const stabilityScore = primary === undefined
+                    ? 0
+                    : await scoreLocatorStability(page, primary, options.viewports === undefined ? {} : { viewports: options.viewports });
+                elements.push({
+                    elementId: computeElementId(pageModel.url, interactiveElement),
+                    name: nameFor(elementNameForId(interactiveElement), interactiveElement.kind),
+                    kind: interactiveElement.kind,
+                    locatorCandidates: candidates,
+                    stabilityScore,
+                    lastVerifiedAt: generatedAt,
+                    pii: false,
+                    dynamicText: false,
+                    source: 'crawl',
+                });
+            }
+        }
+        const registry = { schemaVersion: SCHEMA_VERSION, generatedAt, elements };
+        return { registry, blockedRequestCount };
+    }
+    finally {
+        await browser.close();
+    }
+}
+/**
+ * Merges a freshly built registry onto a previously stored one, keeping history (development plan
+ * section 6.3.6): every element the fresh crawl found replaces its previous entry outright
+ * (un-deprecating it, if it had been). An element the fresh crawl did not find is kept rather than
+ * deleted, with `deprecatedAt` set to `generatedAt` the first time it goes missing; once
+ * deprecated, its `deprecatedAt` is never overwritten by a later run that still does not find it.
+ */
+export function mergeSelectorRegistry(previous, fresh, generatedAt) {
+    const freshIds = new Set(fresh.elements.map((element) => element.elementId));
+    const deprecated = previous.elements
+        .filter((element) => !freshIds.has(element.elementId))
+        .map((element) => element.deprecatedAt === undefined ? { ...element, deprecatedAt: generatedAt } : element);
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        generatedAt,
+        elements: [...fresh.elements, ...deprecated],
+    };
+}
+/**
+ * Compares two crawls' registries by `elementId`: elements only the current crawl found, elements
+ * only the previous crawl found, and elements both found where the current stability score is
+ * lower than before.
+ */
+export function diffSelectorRegistry(previous, current) {
+    const previousById = new Map(previous.elements.map((element) => [element.elementId, element]));
+    const currentIds = new Set(current.elements.map((element) => element.elementId));
+    const added = current.elements.filter((element) => !previousById.has(element.elementId));
+    const removed = previous.elements.filter((element) => !currentIds.has(element.elementId));
+    const degraded = [];
+    for (const element of current.elements) {
+        const before = previousById.get(element.elementId);
+        if (before !== undefined && element.stabilityScore < before.stabilityScore) {
+            degraded.push({
+                elementId: element.elementId,
+                previousScore: before.stabilityScore,
+                currentScore: element.stabilityScore,
+            });
+        }
+    }
+    return { added, removed, degraded };
+}
+//# sourceMappingURL=build-selector-registry.js.map

package/dist/build-selector-registry.js.map

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

package/dist/generate-locator-module.d.ts

@@ -0,0 +1,24 @@
+import type { SelectorRegistry } from '@qa-ai-stlc/schemas';
+export interface GenerateLocatorModuleOptions {
+    /** Stamped into the module header and `GENERATOR_VERSION` so a stale file can be detected. */
+    readonly generatorVersion: string;
+}
+export interface MissingLocatorElement {
+    readonly elementId: string;
+    readonly kind: string;
+}
+export interface GenerateLocatorModuleResult {
+    /** The `tests/qa/locators.ts` file contents (ADR-006), ready to write as-is. */
+    readonly source: string;
+    /** Elements with no export: no locator candidate, or no export name assigned yet. */
+    readonly missingLocators: readonly MissingLocatorElement[];
+}
+/**
+ * Renders the selector registry into a typed, deterministic `tests/qa/locators.ts` module (ADR-006):
+ * one exported function per element, named after its registry `name`, returning a Playwright
+ * `Locator` built from the element's primary (highest-preference) candidate. An element with no
+ * candidate, or predating the `name` field, gets no export and is reported in `missingLocators`
+ * instead of failing generation.
+ */
+export declare function generateLocatorModule(registry: SelectorRegistry, options: GenerateLocatorModuleOptions): GenerateLocatorModuleResult;
+//# sourceMappingURL=generate-locator-module.d.ts.map

package/dist/generate-locator-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-locator-module.d.ts","sourceRoot":"","sources":["../src/generate-locator-module.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAqC,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE/F,MAAM,WAAW,4BAA4B;IAC3C,8FAA8F;IAC9F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,2BAA2B;IAC1C,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,QAAQ,CAAC,eAAe,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC5D;AA+DD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,4BAA4B,GACpC,2BAA2B,CAkC7B"}

package/dist/generate-locator-module.js

@@ -0,0 +1,80 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { QaError } from '@qa-ai-stlc/core';
+function roleCall(candidate) {
+    const parsed = JSON.parse(candidate.value);
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !('role' in parsed) ||
+        !('name' in parsed) ||
+        typeof parsed.role !== 'string' ||
+        typeof parsed.name !== 'string') {
+        throw new QaError('explorer.locator_module.invalid_role_candidate', `role candidate value is not a {role, name} pair: ${candidate.value}`);
+    }
+    return `page.getByRole(${JSON.stringify(parsed.role)}, { name: ${JSON.stringify(parsed.name)} })`;
+}
+function locatorCall(candidate) {
+    switch (candidate.strategy) {
+        case 'role':
+            return roleCall(candidate);
+        case 'testId':
+            return `page.getByTestId(${JSON.stringify(candidate.value)})`;
+        case 'label':
+            return `page.getByLabel(${JSON.stringify(candidate.value)})`;
+        case 'placeholder':
+            return `page.getByPlaceholder(${JSON.stringify(candidate.value)})`;
+        case 'text':
+            return `page.getByText(${JSON.stringify(candidate.value)})`;
+        case 'css':
+            return `page.locator(${JSON.stringify(candidate.value)})`;
+        default:
+            throw new QaError('explorer.locator_module.unknown_strategy', `unknown locator strategy: ${candidate.strategy}`);
+    }
+}
+function isGeneratable(element) {
+    return element.name !== undefined && element.deprecatedAt === undefined;
+}
+// Pairs each generatable element with its primary candidate in one pass, narrowing out elements
+// with an empty `locatorCandidates` by the presence of `primary` rather than by re-checking
+// `.length`, so the later render step never needs to handle an "impossible" missing primary.
+function toGeneratableEntry(element) {
+    const primary = element.locatorCandidates[0];
+    return primary === undefined ? undefined : { element, primary };
+}
+function byName(a, b) {
+    return a.element.name.localeCompare(b.element.name);
+}
+/**
+ * Renders the selector registry into a typed, deterministic `tests/qa/locators.ts` module (ADR-006):
+ * one exported function per element, named after its registry `name`, returning a Playwright
+ * `Locator` built from the element's primary (highest-preference) candidate. An element with no
+ * candidate, or predating the `name` field, gets no export and is reported in `missingLocators`
+ * instead of failing generation.
+ */
+export function generateLocatorModule(registry, options) {
+    const active = registry.elements.filter((element) => element.deprecatedAt === undefined);
+    const missingLocators = active
+        .filter((element) => !isGeneratable(element) || element.locatorCandidates.length === 0)
+        .map((element) => ({ elementId: element.elementId, kind: element.kind }))
+        .sort((a, b) => a.elementId.localeCompare(b.elementId));
+    const generatable = active
+        .filter((element) => isGeneratable(element))
+        .map(toGeneratableEntry)
+        .filter((entry) => entry !== undefined)
+        .sort(byName);
+    const functions = generatable.map(({ element, primary }) => `export function ${element.name}(page: Page): Locator {\n  return ${locatorCall(primary)};\n}`);
+    const header = [
+        '// Copyright The QA-AI-STLC Authors',
+        '// SPDX-License-Identifier: Apache-2.0',
+        '',
+        `// Generated by @qa-ai-stlc/explorer@${options.generatorVersion} from the selector registry`,
+        '// (ADR-006). Do not edit by hand; regenerate with `qa explore`.',
+        '',
+        "import type { Locator, Page } from 'playwright';",
+        '',
+        `export const GENERATOR_VERSION = ${JSON.stringify(options.generatorVersion)};`,
+    ].join('\n');
+    const source = `${[header, ...functions].join('\n\n')}\n`;
+    return { source, missingLocators };
+}
+//# sourceMappingURL=generate-locator-module.js.map

package/dist/generate-locator-module.js.map

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

package/dist/index.d.ts

@@ -2,12 +2,19 @@ export * from './accessibility-tree.js';
 export * from './allowlist.js';
 export * from './analyze-page.js';
 export * from './analyze-pages.js';
+export * from './analyze-static-source.js';
+export * from './build-missing-test-id-report.js';
+export * from './build-selector-registry.js';
 export * from './crawl.js';
 export * from './extract-links.js';
+export * from './generate-locator-module.js';
 export * from './identity.js';
+export * from './naming.js';
 export * from './normalize.js';
 export * from './page-elements.js';
+export * from './pick-mode.js';
 export * from './request-log.js';
 export * from './safe-mode.js';
+export * from './stability-scoring.js';
 export * from './synthesize-locators.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -4,12 +4,19 @@ export * from './accessibility-tree.js';
 export * from './allowlist.js';
 export * from './analyze-page.js';
 export * from './analyze-pages.js';
+export * from './analyze-static-source.js';
+export * from './build-missing-test-id-report.js';
+export * from './build-selector-registry.js';
 export * from './crawl.js';
 export * from './extract-links.js';
+export * from './generate-locator-module.js';
 export * from './identity.js';
+export * from './naming.js';
 export * from './normalize.js';
 export * from './page-elements.js';
+export * from './pick-mode.js';
 export * from './request-log.js';
 export * from './safe-mode.js';
+export * from './stability-scoring.js';
 export * from './synthesize-locators.js';
 //# sourceMappingURL=index.js.map