@ia-qa/self-healing 1.3.4 → 1.4.0

package/dist/discovery/safety.d.ts

@@ -0,0 +1,99 @@
+import type { PageTarget } from '../config';
+/**
+ * The safety floor shared by both discovery sources (sitemap + crawl).
+ *
+ * Discovery only ever *proposes* pages to add to `config.pages`; it never maps,
+ * heals, or edits a test. But the crawler navigates real URLs on a real (often
+ * authenticated) app, so the one thing that must be airtight is *which URLs it is
+ * allowed to touch at all*. That decision lives here, as pure functions, so it is
+ * unit-tested in isolation rather than trusted inside a browser loop.
+ *
+ * Two rules, both erring toward doing nothing:
+ *  1. Never leave the app's own origin.
+ *  2. Never touch a URL whose path or query reads like an action — logout, delete,
+ *     pay, unsubscribe… A crawler that visits `/logout` kills the session for every
+ *     page after it; one that visits `/orders/42/delete` (a GET that mutates — bad
+ *     REST, but real) destroys data. Both are same-origin GETs a naive BFS would
+ *     happily follow, so the guard is a denylist on the URL itself, not on a verb.
+ */
+/**
+ * A path or query segment that names an action rather than a view. Matched against
+ * the full href (pathname + search), case-insensitive, on word-ish boundaries so
+ * `/deleted-items` (a view) is not caught by `delete` but `/item/delete` is.
+ *
+ * Deliberately broad: a false positive costs one un-discovered page (the user can
+ * add it by hand); a false negative can log the crawler out or mutate data. On an
+ * "ultra-safe" tool that trade is not close.
+ */
+export declare const UNSAFE_URL_RE: RegExp;
+export interface HostOptions {
+    /**
+     * Require the host to match `baseUrl`'s exactly. Off by default: `www.` is
+     * stripped from both sides first, so an apex `baseUrl` and a `www.` sitemap (or a
+     * `www.`→apex 301) are treated as one site. Turn this on to keep them distinct.
+     */
+    strictHost?: boolean;
+}
+/**
+ * The "same site" key of a URL: protocol + host, with a leading `www.` folded away
+ * unless `strictHost`. This is the whole apex/`www.` fix — comparing raw `origin`
+ * drops every `www.` sitemap URL when `baseUrl` is the apex (or vice versa), which
+ * is the single most common way a real `baseUrl` and a real sitemap differ. Protocol
+ * and port stay significant: `http` vs `https` is a real difference, not a `www.`.
+ */
+export declare function siteKey(u: URL, strictHost?: boolean): string;
+/** Why a URL was not kept — `host` is the one worth surfacing to the user. */
+export type SkipReason = 'scheme' | 'host' | 'download' | 'action' | 'unparseable';
+export interface UrlVerdict {
+    ok: boolean;
+    reason?: SkipReason;
+    /** The URL's host when it parsed — lets the caller name the mismatched host. */
+    host?: string;
+}
+/**
+ * Classify a URL against `baseUrl`, returning *why* it was rejected — so a caller
+ * can tell "on a different host" (worth a warning) from "a PDF" (silently skipped).
+ * The order matters: an off-host download reports `host`, the more actionable cause.
+ */
+export declare function classifyUrl(href: string, baseUrl: string, opts?: HostOptions): UrlVerdict;
+/**
+ * May the crawler touch this href, resolved against `baseUrl`?
+ *
+ * Returns false for anything off-site (see `siteKey` for the apex/`www.` rule),
+ * non-http, a download, or matching `UNSAFE_URL_RE`. Unparseable input is unsafe by
+ * default — the whole point is to be conservative about what gets a navigation.
+ */
+export declare function isSafeCandidateUrl(href: string, baseUrl: string, opts?: HostOptions): boolean;
+/**
+ * Compare two URLs by pathname alone — query and hash do not make another page,
+ * and a trailing slash is not a distinction. This is the dedup key for candidates,
+ * and mirrors `normalizePath` in overview.ts and `samePath` in map.ts so discovery,
+ * the nav graph, and `assertLanded` all agree on when two URLs are one page.
+ */
+export declare function normalizedPath(href: string, baseUrl: string): string;
+export interface Candidate {
+    name: string;
+    url: string;
+    /** Where this candidate came from — shown in the summary, never written to config. */
+    source: 'sitemap' | 'crawl';
+}
+/**
+ * Turn a raw URL into a candidate page, or null if it is not safe to propose.
+ *
+ * The stored `url` is the same shape the rest of the config uses: a path for
+ * same-origin (`/dashboard`), so a contract stays comparable across environments.
+ */
+export declare function toCandidate(href: string, baseUrl: string, source: Candidate['source'], opts?: HostOptions): Candidate | null;
+/**
+ * Fold candidates into the pages already in config, dropping duplicates and
+ * anything already configured, and making every new page name unique.
+ *
+ * A page name is a contract's filename ([[config.mappingPath]]), so a collision is
+ * not cosmetic — two pages would overwrite each other's mapping. Existing pages win
+ * their name; a new candidate that slugs to a taken name gets a numeric suffix.
+ * Dedup is by normalized path so `/x`, `/x/`, and `/x?ref=nav` are one page.
+ *
+ * Returns only the *new* pages to add, in discovery order, so the caller can show
+ * "found N, M new" and append them without disturbing the author's ordering.
+ */
+export declare function mergePages(existing: PageTarget[], candidates: Candidate[], baseUrl: string): Candidate[];

package/dist/discovery/safety.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNSAFE_URL_RE = void 0;
+exports.siteKey = siteKey;
+exports.classifyUrl = classifyUrl;
+exports.isSafeCandidateUrl = isSafeCandidateUrl;
+exports.normalizedPath = normalizedPath;
+exports.toCandidate = toCandidate;
+exports.mergePages = mergePages;
+const pageName_1 = require("../pageName");
+/**
+ * The safety floor shared by both discovery sources (sitemap + crawl).
+ *
+ * Discovery only ever *proposes* pages to add to `config.pages`; it never maps,
+ * heals, or edits a test. But the crawler navigates real URLs on a real (often
+ * authenticated) app, so the one thing that must be airtight is *which URLs it is
+ * allowed to touch at all*. That decision lives here, as pure functions, so it is
+ * unit-tested in isolation rather than trusted inside a browser loop.
+ *
+ * Two rules, both erring toward doing nothing:
+ *  1. Never leave the app's own origin.
+ *  2. Never touch a URL whose path or query reads like an action — logout, delete,
+ *     pay, unsubscribe… A crawler that visits `/logout` kills the session for every
+ *     page after it; one that visits `/orders/42/delete` (a GET that mutates — bad
+ *     REST, but real) destroys data. Both are same-origin GETs a naive BFS would
+ *     happily follow, so the guard is a denylist on the URL itself, not on a verb.
+ */
+/**
+ * A path or query segment that names an action rather than a view. Matched against
+ * the full href (pathname + search), case-insensitive, on word-ish boundaries so
+ * `/deleted-items` (a view) is not caught by `delete` but `/item/delete` is.
+ *
+ * Deliberately broad: a false positive costs one un-discovered page (the user can
+ * add it by hand); a false negative can log the crawler out or mutate data. On an
+ * "ultra-safe" tool that trade is not close.
+ */
+exports.UNSAFE_URL_RE = /(?:^|[/_.?=&-])(?:log[\s_-]?out|sign[\s_-]?out|logout|signout|delete|destroy|remove|deactivate|disable|unsubscribe|revoke|cancel|purchase|checkout|payment|pay|buy|order|confirm|approve|reject|reset|logoff)(?:[/_.?=&-]|$)/i;
+/** File extensions that are downloads, not pages — never worth mapping. */
+const DOWNLOAD_EXT_RE = /\.(?:pdf|zip|gz|tar|rar|7z|csv|xlsx?|docx?|pptx?|png|jpe?g|gif|svg|webp|ico|mp[34]|mov|avi|woff2?|ttf|eot|dmg|exe|apk|pkg)(?:$|[?#])/i;
+/**
+ * The "same site" key of a URL: protocol + host, with a leading `www.` folded away
+ * unless `strictHost`. This is the whole apex/`www.` fix — comparing raw `origin`
+ * drops every `www.` sitemap URL when `baseUrl` is the apex (or vice versa), which
+ * is the single most common way a real `baseUrl` and a real sitemap differ. Protocol
+ * and port stay significant: `http` vs `https` is a real difference, not a `www.`.
+ */
+function siteKey(u, strictHost = false) {
+    const host = strictHost ? u.host : u.host.replace(/^www\./i, '');
+    return `${u.protocol}//${host}`;
+}
+/**
+ * Classify a URL against `baseUrl`, returning *why* it was rejected — so a caller
+ * can tell "on a different host" (worth a warning) from "a PDF" (silently skipped).
+ * The order matters: an off-host download reports `host`, the more actionable cause.
+ */
+function classifyUrl(href, baseUrl, opts = {}) {
+    let url;
+    let base;
+    try {
+        base = new URL(baseUrl);
+        url = new URL(href, baseUrl);
+    }
+    catch {
+        return { ok: false, reason: 'unparseable' };
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return { ok: false, reason: 'scheme' };
+    if (siteKey(url, opts.strictHost) !== siteKey(base, opts.strictHost)) {
+        return { ok: false, reason: 'host', host: url.host };
+    }
+    if (DOWNLOAD_EXT_RE.test(url.pathname + url.search))
+        return { ok: false, reason: 'download', host: url.host };
+    if (exports.UNSAFE_URL_RE.test(url.pathname + url.search))
+        return { ok: false, reason: 'action', host: url.host };
+    return { ok: true, host: url.host };
+}
+/**
+ * May the crawler touch this href, resolved against `baseUrl`?
+ *
+ * Returns false for anything off-site (see `siteKey` for the apex/`www.` rule),
+ * non-http, a download, or matching `UNSAFE_URL_RE`. Unparseable input is unsafe by
+ * default — the whole point is to be conservative about what gets a navigation.
+ */
+function isSafeCandidateUrl(href, baseUrl, opts = {}) {
+    return classifyUrl(href, baseUrl, opts).ok;
+}
+/**
+ * Compare two URLs by pathname alone — query and hash do not make another page,
+ * and a trailing slash is not a distinction. This is the dedup key for candidates,
+ * and mirrors `normalizePath` in overview.ts and `samePath` in map.ts so discovery,
+ * the nav graph, and `assertLanded` all agree on when two URLs are one page.
+ */
+function normalizedPath(href, baseUrl) {
+    let url;
+    try {
+        url = new URL(href, baseUrl);
+    }
+    catch {
+        return href;
+    }
+    const p = url.pathname;
+    return p.length > 1 && p.endsWith('/') ? p.slice(0, -1) : p;
+}
+/**
+ * Turn a raw URL into a candidate page, or null if it is not safe to propose.
+ *
+ * The stored `url` is the same shape the rest of the config uses: a path for
+ * same-origin (`/dashboard`), so a contract stays comparable across environments.
+ */
+function toCandidate(href, baseUrl, source, opts = {}) {
+    if (!isSafeCandidateUrl(href, baseUrl, opts))
+        return null;
+    const path = normalizedPath(href, baseUrl);
+    return { name: (0, pageName_1.pageNameFromUrl)(new URL(href, baseUrl).toString()), url: path, source };
+}
+/**
+ * Fold candidates into the pages already in config, dropping duplicates and
+ * anything already configured, and making every new page name unique.
+ *
+ * A page name is a contract's filename ([[config.mappingPath]]), so a collision is
+ * not cosmetic — two pages would overwrite each other's mapping. Existing pages win
+ * their name; a new candidate that slugs to a taken name gets a numeric suffix.
+ * Dedup is by normalized path so `/x`, `/x/`, and `/x?ref=nav` are one page.
+ *
+ * Returns only the *new* pages to add, in discovery order, so the caller can show
+ * "found N, M new" and append them without disturbing the author's ordering.
+ */
+function mergePages(existing, candidates, baseUrl) {
+    const takenPaths = new Set(existing
+        .filter((p) => !p.steps?.length)
+        .map((p) => normalizedPath(p.url, baseUrl)));
+    const takenNames = new Set(existing.map((p) => p.name));
+    const added = [];
+    for (const c of candidates) {
+        const key = normalizedPath(c.url, baseUrl);
+        if (takenPaths.has(key))
+            continue;
+        takenPaths.add(key);
+        let name = c.name;
+        if (takenNames.has(name)) {
+            let n = 2;
+            while (takenNames.has(`${name}-${n}`))
+                n++;
+            name = `${name}-${n}`;
+        }
+        takenNames.add(name);
+        added.push({ ...c, name });
+    }
+    return added;
+}
+//# sourceMappingURL=safety.js.map

package/dist/discovery/safety.js.map

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

package/dist/discovery/sitemap.d.ts

@@ -0,0 +1,69 @@
+import { Candidate, HostOptions } from './safety';
+/**
+ * Sitemap discovery — the zero-risk source.
+ *
+ * A sitemap is a manifest the site *publishes about itself*, so reading it is a
+ * single GET and never touches the app's state: no browser, no login, no clicks.
+ * Its blind spot is the mirror image of the crawler's: it sees the public, SEO
+ * surface and stops exactly where the authenticated app begins. That is why the
+ * two exist side by side rather than one replacing the other.
+ *
+ * Dependency-free by the same rule as `browser/extract.js`: `<loc>` extraction is a
+ * regex, not an XML library, because namespaces vary between generators and the
+ * data we need is trivial. `fetch` is injectable so the parser is tested without a
+ * network.
+ */
+export type FetchLike = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    text: () => Promise<string>;
+}>;
+export interface SitemapOptions extends HostOptions {
+    /** Explicit sitemap URL. Defaults to `<baseUrl>/sitemap.xml`, then robots.txt. */
+    sitemapUrl?: string;
+    /** Injected for tests; defaults to the global `fetch` (Node 18+). */
+    fetchImpl?: FetchLike;
+    /** Hard cap on URLs returned, to keep a 10k-URL catalogue from flooding config. */
+    maxUrls?: number;
+    /** Bound on nested sitemap files followed from an index. */
+    maxSitemaps?: number;
+}
+/**
+ * An honest account of what the sitemap held versus what survived — the fix for the
+ * silent "0 URLs" that a host mismatch used to produce. `parsed` is every page
+ * `<loc>` seen; the three skip buckets say why the rest did not make it, and
+ * `otherHosts` names the hosts behind a `host` skip so the CLI can point at the
+ * apex/`www.` mismatch by name instead of leaving the user to guess.
+ */
+export interface SitemapStats {
+    parsed: number;
+    retained: number;
+    skippedHost: number;
+    skippedOther: number;
+    otherHosts: string[];
+}
+export interface SitemapResult {
+    candidates: Candidate[];
+    stats: SitemapStats;
+}
+/** Pull every `<loc>` out of a sitemap or sitemap-index document. Pure. */
+export declare function extractLocs(xml: string): string[];
+/** A sitemap index points at other sitemaps rather than at pages. */
+export declare function isSitemapIndex(xml: string): boolean;
+/** `Sitemap:` directives in a robots.txt — the standard way to advertise one. */
+export declare function sitemapsFromRobots(robots: string): string[];
+/**
+ * Discover candidate pages from a site's sitemap(s).
+ *
+ * Resolution: the explicit `sitemapUrl` if given, else `/sitemap.xml`; if that
+ * 404s, the `Sitemap:` lines in `/robots.txt`. A sitemap index is followed one
+ * level into its child sitemaps (bounded by `maxSitemaps`). Every page URL is
+ * classified (see `classifyUrl`), so off-site, unsafe, and download URLs never
+ * survive — but the count of what was dropped, and why, comes back in `stats` so
+ * the caller can tell a host mismatch from "nothing there" instead of printing a
+ * silent "0 URLs".
+ *
+ * Never throws on a missing or malformed sitemap: absence is the common case
+ * (SPAs, staging), and it is a "found nothing", not an error.
+ */
+export declare function discoverFromSitemap(baseUrl: string, options?: SitemapOptions): Promise<SitemapResult>;

package/dist/discovery/sitemap.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLocs = extractLocs;
+exports.isSitemapIndex = isSitemapIndex;
+exports.sitemapsFromRobots = sitemapsFromRobots;
+exports.discoverFromSitemap = discoverFromSitemap;
+const safety_1 = require("./safety");
+const pageName_1 = require("../pageName");
+const LOC_RE = /<loc>\s*([^<\s][^<]*?)\s*<\/loc>/gi;
+/** Pull every `<loc>` out of a sitemap or sitemap-index document. Pure. */
+function extractLocs(xml) {
+    const out = [];
+    let m;
+    LOC_RE.lastIndex = 0;
+    while ((m = LOC_RE.exec(xml)) !== null) {
+        const loc = decodeEntities(m[1].trim());
+        if (loc)
+            out.push(loc);
+    }
+    return out;
+}
+/** A sitemap index points at other sitemaps rather than at pages. */
+function isSitemapIndex(xml) {
+    return /<sitemapindex[\s>]/i.test(xml);
+}
+function decodeEntities(s) {
+    return s
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'");
+}
+/** `Sitemap:` directives in a robots.txt — the standard way to advertise one. */
+function sitemapsFromRobots(robots) {
+    const out = [];
+    for (const line of robots.split(/\r?\n/)) {
+        const m = /^\s*sitemap:\s*(\S+)/i.exec(line);
+        if (m)
+            out.push(m[1].trim());
+    }
+    return out;
+}
+/**
+ * Discover candidate pages from a site's sitemap(s).
+ *
+ * Resolution: the explicit `sitemapUrl` if given, else `/sitemap.xml`; if that
+ * 404s, the `Sitemap:` lines in `/robots.txt`. A sitemap index is followed one
+ * level into its child sitemaps (bounded by `maxSitemaps`). Every page URL is
+ * classified (see `classifyUrl`), so off-site, unsafe, and download URLs never
+ * survive — but the count of what was dropped, and why, comes back in `stats` so
+ * the caller can tell a host mismatch from "nothing there" instead of printing a
+ * silent "0 URLs".
+ *
+ * Never throws on a missing or malformed sitemap: absence is the common case
+ * (SPAs, staging), and it is a "found nothing", not an error.
+ */
+async function discoverFromSitemap(baseUrl, options = {}) {
+    const fetchImpl = options.fetchImpl || globalThis.fetch;
+    if (!fetchImpl)
+        throw new Error('No fetch implementation available (Node 18+ or pass fetchImpl).');
+    const maxUrls = options.maxUrls ?? 200;
+    const maxSitemaps = options.maxSitemaps ?? 20;
+    const roots = options.sitemapUrl
+        ? [options.sitemapUrl]
+        : await resolveSitemapUrls(baseUrl, fetchImpl);
+    const seenSitemaps = new Set();
+    const pageUrls = [];
+    const queue = [...roots];
+    while (queue.length > 0 && seenSitemaps.size < maxSitemaps && pageUrls.length < maxUrls) {
+        const url = queue.shift();
+        if (seenSitemaps.has(url))
+            continue;
+        seenSitemaps.add(url);
+        const xml = await safeText(fetchImpl, url);
+        if (!xml)
+            continue;
+        if (isSitemapIndex(xml)) {
+            for (const child of extractLocs(xml)) {
+                if (!seenSitemaps.has(child))
+                    queue.push(child);
+            }
+        }
+        else {
+            pageUrls.push(...extractLocs(xml));
+        }
+    }
+    const candidates = [];
+    const seenPaths = new Set();
+    const otherHosts = new Set();
+    const stats = { parsed: 0, retained: 0, skippedHost: 0, skippedOther: 0, otherHosts: [] };
+    for (const raw of pageUrls) {
+        stats.parsed++;
+        const verdict = (0, safety_1.classifyUrl)(raw, baseUrl, { strictHost: options.strictHost });
+        if (!verdict.ok) {
+            if (verdict.reason === 'host') {
+                stats.skippedHost++;
+                if (verdict.host)
+                    otherHosts.add(verdict.host);
+            }
+            else {
+                stats.skippedOther++;
+            }
+            continue;
+        }
+        const path = (0, safety_1.normalizedPath)(raw, baseUrl);
+        if (seenPaths.has(path)) {
+            stats.skippedOther++;
+            continue;
+        }
+        seenPaths.add(path);
+        candidates.push({ name: (0, pageName_1.pageNameFromUrl)(new URL(raw, baseUrl).toString()), url: path, source: 'sitemap' });
+        stats.retained++;
+        if (candidates.length >= maxUrls)
+            break;
+    }
+    stats.otherHosts = Array.from(otherHosts).slice(0, 5);
+    return { candidates, stats };
+}
+async function resolveSitemapUrls(baseUrl, fetchImpl) {
+    const primary = new URL('/sitemap.xml', baseUrl).toString();
+    const head = await safeText(fetchImpl, primary);
+    if (head)
+        return [primary];
+    const robots = await safeText(fetchImpl, new URL('/robots.txt', baseUrl).toString());
+    if (robots) {
+        const advertised = sitemapsFromRobots(robots);
+        if (advertised.length > 0)
+            return advertised;
+    }
+    return [primary];
+}
+async function safeText(fetchImpl, url) {
+    try {
+        const res = await fetchImpl(url);
+        if (!res.ok)
+            return null;
+        return await res.text();
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=sitemap.js.map

package/dist/discovery/sitemap.js.map

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

package/dist/index.d.ts

@@ -9,6 +9,12 @@ export type { MappedElement, PageMapping } from './aom';
 export { renderPageContract, saveMarkdown, markdownPath } from './markdown';
 export { mapUrl, pageNameFromUrl } from './mapUrl';
 export { resolvePageName } from './pageName';
+export { isSafeCandidateUrl, normalizedPath, toCandidate, mergePages, UNSAFE_URL_RE, } from './discovery/safety';
+export type { Candidate, HostOptions } from './discovery/safety';
+export { discoverFromSitemap, extractLocs, isSitemapIndex, sitemapsFromRobots, } from './discovery/sitemap';
+export type { SitemapOptions, SitemapResult, SitemapStats, FetchLike } from './discovery/sitemap';
+export { crawlApp } from './crawl';
+export type { CrawlOptions } from './crawl';
 export type { PageNameResolution } from './pageName';
 export { scanText, ingestPaths, saveUsage, loadUsage, usageFiles, usagePath } from './ingest';
 export type { Usage, SelectorSite, SelectorShape } from './ingest';

package/dist/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.navigationGraph = exports.layoutGraph = exports.renderNavigationSvg = exports.renderNavigation = exports.renderOverview = exports.buildOverview = exports.minPagesForLayout = exports.stripLayoutFromPages = exports.extractLayout = exports.LAYOUT_DIRNAME = exports.layoutPath = exports.layoutDir = exports.resolveSecret = exports.loadConfig = exports.replaceQuoted = exports.collectFiles = exports.applyRewrites = exports.computeRewrites = exports.launchBrowser = exports.CAPTURE_DIRNAME = exports.captureDir = exports.unionElements = exports.mergeCaptures = exports.usagePath = exports.usageFiles = exports.loadUsage = exports.saveUsage = exports.ingestPaths = exports.scanText = exports.resolvePageName = exports.pageNameFromUrl = exports.mapUrl = exports.markdownPath = exports.saveMarkdown = exports.renderPageContract = exports.saveMapping = exports.loadMapping = exports.extractInteractiveElements = exports.renderModelList = exports.defaultKeyEnv = exports.findProvider = exports.AI_PROVIDERS = exports.parseModelJson = exports.buildPrompt = exports.prefilter = exports.aiResolve = exports.createAiResolver = exports.llmResolverStub = exports.aiFill = exports.aiClick = void 0;
-exports.NAVIGATION_SVG_FILENAME = exports.NAVIGATION_FILENAME = exports.OVERVIEW_FILENAME = exports.navigationSvgPath = exports.navigationPath = exports.overviewPath = exports.writeOverview = void 0;
+exports.layoutPath = exports.layoutDir = exports.resolveSecret = exports.loadConfig = exports.replaceQuoted = exports.collectFiles = exports.applyRewrites = exports.computeRewrites = exports.launchBrowser = exports.CAPTURE_DIRNAME = exports.captureDir = exports.unionElements = exports.mergeCaptures = exports.usagePath = exports.usageFiles = exports.loadUsage = exports.saveUsage = exports.ingestPaths = exports.scanText = exports.crawlApp = exports.sitemapsFromRobots = exports.isSitemapIndex = exports.extractLocs = exports.discoverFromSitemap = exports.UNSAFE_URL_RE = exports.mergePages = exports.toCandidate = exports.normalizedPath = exports.isSafeCandidateUrl = exports.resolvePageName = exports.pageNameFromUrl = exports.mapUrl = exports.markdownPath = exports.saveMarkdown = exports.renderPageContract = exports.saveMapping = exports.loadMapping = exports.extractInteractiveElements = exports.renderModelList = exports.defaultKeyEnv = exports.findProvider = exports.AI_PROVIDERS = exports.parseModelJson = exports.buildPrompt = exports.prefilter = exports.aiResolve = exports.createAiResolver = exports.llmResolverStub = exports.aiFill = exports.aiClick = void 0;
+exports.NAVIGATION_SVG_FILENAME = exports.NAVIGATION_FILENAME = exports.OVERVIEW_FILENAME = exports.navigationSvgPath = exports.navigationPath = exports.overviewPath = exports.writeOverview = exports.navigationGraph = exports.layoutGraph = exports.renderNavigationSvg = exports.renderNavigation = exports.renderOverview = exports.buildOverview = exports.minPagesForLayout = exports.stripLayoutFromPages = exports.extractLayout = exports.LAYOUT_DIRNAME = void 0;
 var healer_1 = require("./playwright/healer");
 Object.defineProperty(exports, "aiClick", { enumerable: true, get: function () { return healer_1.aiClick; } });
 Object.defineProperty(exports, "aiFill", { enumerable: true, get: function () { return healer_1.aiFill; } });
@@ -30,6 +30,19 @@ Object.defineProperty(exports, "mapUrl", { enumerable: true, get: function () {
 Object.defineProperty(exports, "pageNameFromUrl", { enumerable: true, get: function () { return mapUrl_1.pageNameFromUrl; } });
 var pageName_1 = require("./pageName");
 Object.defineProperty(exports, "resolvePageName", { enumerable: true, get: function () { return pageName_1.resolvePageName; } });
+var safety_1 = require("./discovery/safety");
+Object.defineProperty(exports, "isSafeCandidateUrl", { enumerable: true, get: function () { return safety_1.isSafeCandidateUrl; } });
+Object.defineProperty(exports, "normalizedPath", { enumerable: true, get: function () { return safety_1.normalizedPath; } });
+Object.defineProperty(exports, "toCandidate", { enumerable: true, get: function () { return safety_1.toCandidate; } });
+Object.defineProperty(exports, "mergePages", { enumerable: true, get: function () { return safety_1.mergePages; } });
+Object.defineProperty(exports, "UNSAFE_URL_RE", { enumerable: true, get: function () { return safety_1.UNSAFE_URL_RE; } });
+var sitemap_1 = require("./discovery/sitemap");
+Object.defineProperty(exports, "discoverFromSitemap", { enumerable: true, get: function () { return sitemap_1.discoverFromSitemap; } });
+Object.defineProperty(exports, "extractLocs", { enumerable: true, get: function () { return sitemap_1.extractLocs; } });
+Object.defineProperty(exports, "isSitemapIndex", { enumerable: true, get: function () { return sitemap_1.isSitemapIndex; } });
+Object.defineProperty(exports, "sitemapsFromRobots", { enumerable: true, get: function () { return sitemap_1.sitemapsFromRobots; } });
+var crawl_1 = require("./crawl");
+Object.defineProperty(exports, "crawlApp", { enumerable: true, get: function () { return crawl_1.crawlApp; } });
 var ingest_1 = require("./ingest");
 Object.defineProperty(exports, "scanText", { enumerable: true, get: function () { return ingest_1.scanText; } });
 Object.defineProperty(exports, "ingestPaths", { enumerable: true, get: function () { return ingest_1.ingestPaths; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;AAAA,8CAAyF;AAAhF,iGAAA,OAAO,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,yGAAA,eAAe,OAAA;AAAE,0GAAA,gBAAgB,OAAA;AAE3D,0CAAkF;AAAzE,qGAAA,SAAS,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,0GAAA,cAAc,OAAA;AAE1D,sCAAyF;AAAhF,sGAAA,YAAY,OAAA;AAAE,sGAAA,YAAY,OAAA;AAAE,uGAAA,aAAa,OAAA;AAAE,yGAAA,eAAe,OAAA;AAEnE,6BAA6E;AAApE,iHAAA,0BAA0B,OAAA;AAAE,kGAAA,WAAW,OAAA;AAAE,kGAAA,WAAW,OAAA;AAE7D,uCAA4E;AAAnE,8GAAA,kBAAkB,OAAA;AAAE,wGAAA,YAAY,OAAA;AAAE,wGAAA,YAAY,OAAA;AACvD,mCAAmD;AAA1C,gGAAA,MAAM,OAAA;AAAE,yGAAA,eAAe,OAAA;AAChC,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AAExB,mCAA8F;AAArF,kGAAA,QAAQ,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,mGAAA,SAAS,OAAA;AAAE,mGAAA,SAAS,OAAA;AAAE,oGAAA,UAAU,OAAA;AAAE,mGAAA,SAAS,OAAA;AAE3E,+CAA2F;AAAlF,6GAAA,aAAa,OAAA;AAAE,6GAAA,aAAa,OAAA;AAAE,0GAAA,UAAU,OAAA;AAAE,+GAAA,eAAe,OAAA;AAElE,uCAA2C;AAAlC,yGAAA,aAAa,OAAA;AAGtB,yCAA0F;AAAjF,4GAAA,eAAe,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,yGAAA,YAAY,OAAA;AAAE,0GAAA,aAAa,OAAA;AACpE,mCAA4F;AAAnF,oGAAA,UAAU,OAAA;AAAE,uGAAA,aAAa,OAAA;AAAE,mGAAA,SAAS,OAAA;AAAE,oGAAA,UAAU,OAAA;AAAE,wGAAA,cAAc,OAAA;AAEzE,mCAAkF;AAAzE,uGAAA,aAAa,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AAAE,2GAAA,iBAAiB,OAAA;AAE/D,uCAcoB;AAblB,yGAAA,aAAa,OAAA;AACb,0GAAA,cAAc,OAAA;AACd,4GAAA,gBAAgB,OAAA;AAChB,+GAAA,mBAAmB,OAAA;AACnB,uGAAA,WAAW,OAAA;AACX,2GAAA,eAAe,OAAA;AACf,yGAAA,aAAa,OAAA;AACb,wGAAA,YAAY,OAAA;AACZ,0GAAA,cAAc,OAAA;AACd,6GAAA,iBAAiB,OAAA;AACjB,6GAAA,iBAAiB,OAAA;AACjB,+GAAA,mBAAmB,OAAA;AACnB,mHAAA,uBAAuB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;AAAA,8CAAyF;AAAhF,iGAAA,OAAO,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,yGAAA,eAAe,OAAA;AAAE,0GAAA,gBAAgB,OAAA;AAE3D,0CAAkF;AAAzE,qGAAA,SAAS,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,0GAAA,cAAc,OAAA;AAE1D,sCAAyF;AAAhF,sGAAA,YAAY,OAAA;AAAE,sGAAA,YAAY,OAAA;AAAE,uGAAA,aAAa,OAAA;AAAE,yGAAA,eAAe,OAAA;AAEnE,6BAA6E;AAApE,iHAAA,0BAA0B,OAAA;AAAE,kGAAA,WAAW,OAAA;AAAE,kGAAA,WAAW,OAAA;AAE7D,uCAA4E;AAAnE,8GAAA,kBAAkB,OAAA;AAAE,wGAAA,YAAY,OAAA;AAAE,wGAAA,YAAY,OAAA;AACvD,mCAAmD;AAA1C,gGAAA,MAAM,OAAA;AAAE,yGAAA,eAAe,OAAA;AAChC,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AACxB,6CAM4B;AAL1B,4GAAA,kBAAkB,OAAA;AAClB,wGAAA,cAAc,OAAA;AACd,qGAAA,WAAW,OAAA;AACX,oGAAA,UAAU,OAAA;AACV,uGAAA,aAAa,OAAA;AAGf,+CAK6B;AAJ3B,8GAAA,mBAAmB,OAAA;AACnB,sGAAA,WAAW,OAAA;AACX,yGAAA,cAAc,OAAA;AACd,6GAAA,kBAAkB,OAAA;AAGpB,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AAGjB,mCAA8F;AAArF,kGAAA,QAAQ,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,mGAAA,SAAS,OAAA;AAAE,mGAAA,SAAS,OAAA;AAAE,oGAAA,UAAU,OAAA;AAAE,mGAAA,SAAS,OAAA;AAE3E,+CAA2F;AAAlF,6GAAA,aAAa,OAAA;AAAE,6GAAA,aAAa,OAAA;AAAE,0GAAA,UAAU,OAAA;AAAE,+GAAA,eAAe,OAAA;AAElE,uCAA2C;AAAlC,yGAAA,aAAa,OAAA;AAGtB,yCAA0F;AAAjF,4GAAA,eAAe,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,yGAAA,YAAY,OAAA;AAAE,0GAAA,aAAa,OAAA;AACpE,mCAA4F;AAAnF,oGAAA,UAAU,OAAA;AAAE,uGAAA,aAAa,OAAA;AAAE,mGAAA,SAAS,OAAA;AAAE,oGAAA,UAAU,OAAA;AAAE,wGAAA,cAAc,OAAA;AAEzE,mCAAkF;AAAzE,uGAAA,aAAa,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AAAE,2GAAA,iBAAiB,OAAA;AAE/D,uCAcoB;AAblB,yGAAA,aAAa,OAAA;AACb,0GAAA,cAAc,OAAA;AACd,4GAAA,gBAAgB,OAAA;AAChB,+GAAA,mBAAmB,OAAA;AACnB,uGAAA,WAAW,OAAA;AACX,2GAAA,eAAe,OAAA;AACf,yGAAA,aAAa,OAAA;AACb,wGAAA,YAAY,OAAA;AACZ,0GAAA,cAAc,OAAA;AACd,6GAAA,iBAAiB,OAAA;AACjB,6GAAA,iBAAiB,OAAA;AACjB,+GAAA,mBAAmB,OAAA;AACnB,mHAAA,uBAAuB,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ia-qa/self-healing",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Local-first self-healing for UI tests: a local MCP server + CLI that map your app's pages to a role/name/selector contract, diff selector drift (PASS/FIX/BLOCK), and apply deterministic fixes to Cypress/Playwright/Selenium tests. Runs on your machine — nothing leaves it.",
   "keywords": [
     "self-healing",