@ia-qa/qa-discovery 0.1.0

package/dist/capture/page.d.ts

@@ -0,0 +1,128 @@
+import type { Page } from 'playwright';
+import type { Candidate } from '@ia-qa/self-healing';
+import { type ApiCall } from '../network';
+export interface PageMeta {
+    title: string;
+    description: string;
+    lang: string;
+}
+export interface Heading {
+    level: number;
+    text: string;
+}
+export interface FormField {
+    type: string;
+    name: string;
+    selector: string;
+    /**
+     * False when the field carries no durable identity (no test-id, id or name)
+     * and `selector` is a positional fallback scoped to the form — it resolves to
+     * exactly one element today, and breaks the moment a field is inserted above
+     * it. A field with `stableSelector: false` is also a testability finding
+     * about the app, not just a caveat about this capture.
+     */
+    /**
+     * What a human reads to know what this field is — the <label>, an aria-label,
+     * or failing those the placeholder. Absent when the app labels the field
+     * nowhere, which is itself a finding: a field with no label cannot be
+     * understood by a screen reader, by a later stage, or by whoever writes the
+     * test.
+     */
+    label?: string;
+    /**
+     * Where the label came from.  means it was read from text sitting
+     * near the field rather than declared by the app — useful, but a guess, and a
+     * later stage should weigh it accordingly.
+     */
+    labelSource?: 'aria-label' | 'aria-labelledby' | 'label-for' | 'label-wrapping' | 'placeholder' | 'title' | 'proximity';
+    stableSelector: boolean;
+    /**
+     * Present (and true) only when `selector` could NOT be made to resolve to
+     * exactly one element — verified in the page, not assumed. Nothing
+     * downstream may act on such a field: it is a locator coin flip.
+     */
+    ambiguousSelector?: boolean;
+    required: boolean;
+    /**
+     * The click path that reveals this field, when it was not visible at load
+     * (`--deep`). Absent on a field the page shows on its own. Never part of
+     * identity — a field that stops being hidden is the same field — but a test
+     * author cannot reach it without knowing this.
+     */
+    via?: string[];
+    /**
+     * Nearest landmark and/or heading above the field. Present on loose fields
+     * only — without it, a page's hundred un-grouped inputs are one blob.
+     */
+    context?: string;
+}
+export interface CapturedForm {
+    selector: string;
+    /** null when the form states no `method` — a JS-handled submit, not a GET to self. */
+    method: string | null;
+    /** null when the form states no `action`. Never synthesized from the page URL. */
+    action: string | null;
+    /** Present only when there is an `action` to classify. */
+    sameOriginAction?: boolean;
+    hasSubmit: boolean;
+    fields: FormField[];
+}
+export declare const PAGE_CAPTURE_SCHEMA = "qa-discovery-page@1";
+export interface PageCapture {
+    schema: typeof PAGE_CAPTURE_SCHEMA;
+    page: string;
+    url: string;
+    finalUrl: string;
+    source: Candidate['source'];
+    capturedAt: string;
+    http: {
+        status: number;
+        redirected: boolean;
+    };
+    meta: PageMeta;
+    headings: Heading[];
+    forms: CapturedForm[];
+    /**
+     * Input fields outside any `<form>` — the majority of the input surface in a
+     * modern React/Vue app, which submits in JS and wraps nothing. Capturing only
+     * `<form>` descendants reported "0 fields" on an app with 464 inputs.
+     */
+    looseFields: FormField[];
+    apiCalls: ApiCall[];
+    /**
+     * State exploration, when `--deep` ran. `openable` is counted on EVERY scan
+     * even without `--deep`, because a page with 64 clickable controls and 2
+     * visible fields must not report those 2 as its input surface.
+     */
+    exploration: {
+        /** Controls that could reveal more, counted before any click. */
+        openable: number;
+        /** False when only the loaded state was captured. */
+        explored: boolean;
+        clicked?: number;
+        revealed?: number;
+        collided?: number;
+        truncated?: boolean;
+        blockedMutations?: number;
+    };
+}
+export interface CapturePageOptions {
+    /** Observe API/network calls. Default true. */
+    network?: boolean;
+    safeQueryParams?: string[];
+    timeout?: number;
+    /** Click one level of disclosures and capture what they reveal. Default false. */
+    deep?: boolean;
+    /** Max controls clicked per page. Default 60. */
+    deepBudget?: number;
+}
+/**
+ * Capture one page's structural surface: meta/headings/forms via a single
+ * `page.evaluate`, and — unless disabled — observed API calls via a passive
+ * `page.on('response')` listener attached for the duration of this navigation
+ * only (see network.ts for why never `page.route()`).
+ *
+ * `candidate.url` is a path (self-healing's `Candidate` shape), resolved here
+ * against `baseUrl` before navigating.
+ */
+export declare function capturePage(page: Page, candidate: Candidate, baseUrl: string, options?: CapturePageOptions): Promise<PageCapture>;

package/dist/capture/page.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAGE_CAPTURE_SCHEMA = void 0;
+exports.capturePage = capturePage;
+const extractPage_1 = require("../browser/extractPage");
+const network_1 = require("../network");
+const explore_1 = require("../explore");
+exports.PAGE_CAPTURE_SCHEMA = 'qa-discovery-page@1';
+/**
+ * Capture one page's structural surface: meta/headings/forms via a single
+ * `page.evaluate`, and — unless disabled — observed API calls via a passive
+ * `page.on('response')` listener attached for the duration of this navigation
+ * only (see network.ts for why never `page.route()`).
+ *
+ * `candidate.url` is a path (self-healing's `Candidate` shape), resolved here
+ * against `baseUrl` before navigating.
+ */
+async function capturePage(page, candidate, baseUrl, options = {}) {
+    const network = options.network !== false;
+    const timeout = options.timeout ?? 30000;
+    const absoluteUrl = new URL(candidate.url, baseUrl).toString();
+    const responses = [];
+    const detach = network ? (0, network_1.attachNetworkListener)(page, (r) => responses.push(r)) : null;
+    try {
+        const response = await page.goto(absoluteUrl, { waitUntil: 'networkidle', timeout });
+        const finalUrl = page.url();
+        const status = response ? response.status() : 0;
+        const redirected = response ? response.request().redirectedFrom() !== null : false;
+        const extracted = (await page.evaluate(extractPage_1.extractPageInPage));
+        const pageOrigin = new URL(finalUrl).origin;
+        const apiCalls = network
+            ? (0, network_1.aggregateApiCalls)(responses, pageOrigin, options.safeQueryParams ?? network_1.DEFAULT_SAFE_QUERY_PARAMS)
+            : [];
+        // LAST, and after the network listener has been read: exploration clicks
+        // around and leaves the page in an arbitrary state, so everything that
+        // reads the loaded DOM must already have run. See explore.ts rule 3.
+        let looseFields = extracted.looseFields ?? [];
+        let exploration;
+        if (options.deep) {
+            const { revealed, stats } = await (0, explore_1.exploreFields)(page, { budget: options.deepBudget });
+            looseFields = [...looseFields, ...revealed];
+            exploration = {
+                openable: stats.openable,
+                explored: true,
+                clicked: stats.clicked,
+                revealed: stats.revealed,
+                collided: stats.collided,
+                truncated: stats.truncated,
+                blockedMutations: stats.blockedMutations,
+            };
+        }
+        else {
+            // Counted even when not exploring: this is what makes "2 fields" honest
+            // on a page that hides the rest behind 64 buttons.
+            exploration = { openable: await (0, explore_1.countOpenables)(page), explored: false };
+        }
+        return {
+            schema: exports.PAGE_CAPTURE_SCHEMA,
+            page: candidate.name,
+            url: absoluteUrl,
+            finalUrl,
+            source: candidate.source,
+            capturedAt: new Date().toISOString(),
+            http: { status, redirected },
+            meta: extracted.meta,
+            headings: extracted.headings,
+            forms: extracted.forms,
+            looseFields,
+            apiCalls,
+            exploration,
+        };
+    }
+    finally {
+        if (detach)
+            detach();
+    }
+}
+//# sourceMappingURL=page.js.map

package/dist/capture/page.js.map

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

package/dist/citations.d.ts

@@ -0,0 +1,80 @@
+import type { PageCapture } from './capture/page';
+import type { SharedCallsFile } from './sharedCalls';
+/**
+ * Citation resolution — the mechanism the whole pipeline's honesty rests on.
+ *
+ * Written and tested BEFORE anything that produces claims, deliberately: this is
+ * the judge, and a judge built after the accused tends to be shaped to acquit.
+ * Nothing here calls an LLM, opens a browser, or touches the network.
+ *
+ * A later stage may assert whatever it likes about the app, but each assertion
+ * carries a path into F1's capture. This module resolves that path and checks
+ * that what is there is what the claim said is there. A claim whose citation
+ * does not resolve — or resolves to something else — is **dropped**, and the
+ * drop is reported rather than quietly swallowed.
+ *
+ * THE LIMIT, restated here because this is the file people will read to
+ * understand it: this proves the **premise**, never the **conclusion**. A model
+ * can cite a password field that genuinely exists and still call the page a
+ * checkout. What is mechanised is "the thing you leaned on is real"; whether the
+ * inference follows is a human's call, which is why every surviving claim keeps
+ * a readable sentence and a visible confidence next to it.
+ */
+/** Page name → its capture. Plus the cross-page file, addressable as `_shared-calls.json`. */
+export interface CaptureIndex {
+    pages: Map<string, PageCapture>;
+    shared?: SharedCallsFile;
+}
+export declare const SHARED_REF = "_shared-calls.json";
+/**
+ * A citation. The bare string form only asserts existence; the object form also
+ * states what the citing stage believes is there, which is strictly stronger —
+ * it catches a model that points at a real element while being wrong about it.
+ */
+export type Citation = string | {
+    path: string;
+    expect?: Record<string, unknown>;
+};
+export type CitationFailure = 
+/** Not a `<file>#<path>` reference at all. */
+'malformed'
+/** `pages/x.json` — the capture holds no such page. */
+ | 'unknown-page'
+/** The file is right but the path does not resolve inside it. */
+ | 'no-such-node'
+/** It resolves, but not to what the claim said was there. */
+ | 'mismatch';
+export type CitationVerdict = {
+    ok: true;
+    path: string;
+    value: unknown;
+} | {
+    ok: false;
+    path: string;
+    reason: CitationFailure;
+    detail: string;
+};
+export declare function verifyCitation(citation: Citation, index: CaptureIndex): CitationVerdict;
+export interface VerifiedClaim<T> {
+    claim: T;
+    kept: boolean;
+    supported: CitationVerdict[];
+    rejected: Array<Extract<CitationVerdict, {
+        ok: false;
+    }>>;
+    /** Why a dropped claim was dropped, in one sentence a human can act on. */
+    reason?: string;
+}
+/**
+ * Keep a claim only if it cites, and every citation resolves.
+ *
+ * All-or-nothing on purpose: a claim standing on three facts and one invention
+ * is not three-quarters true. Letting it through with the bad citation stripped
+ * would hide exactly the failure this check exists to surface — and the stage
+ * that produced it would never learn.
+ */
+export declare function verifyClaim<T extends {
+    evidence?: Citation[];
+}>(claim: T, index: CaptureIndex): VerifiedClaim<T>;
+/** Load the capture written by `scan` into an index the verifier can use. */
+export declare function loadCaptureIndex(dir?: string): CaptureIndex;

package/dist/citations.js

@@ -0,0 +1,197 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHARED_REF = void 0;
+exports.verifyCitation = verifyCitation;
+exports.verifyClaim = verifyClaim;
+exports.loadCaptureIndex = loadCaptureIndex;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+exports.SHARED_REF = '_shared-calls.json';
+/** `pages/checkout.json#forms[0].fields[1]` → { file, segments }. */
+function parseRef(ref) {
+    if (typeof ref !== 'string')
+        return null;
+    const hash = ref.indexOf('#');
+    if (hash === -1)
+        return null;
+    const file = ref.slice(0, hash).trim();
+    const rest = ref.slice(hash + 1).trim();
+    if (!file)
+        return null;
+    const segments = [];
+    // `forms[0].fields[1]` → ['forms', 0, 'fields', 1]
+    for (const part of rest.split('.')) {
+        if (part === '')
+            continue;
+        const m = /^([A-Za-z_][A-Za-z0-9_]*)((?:\[\d+\])*)$/.exec(part);
+        if (!m)
+            return null;
+        segments.push(m[1]);
+        for (const idx of m[2].matchAll(/\[(\d+)\]/g))
+            segments.push(Number(idx[1]));
+    }
+    return { file, segments };
+}
+function walk(root, segments) {
+    let node = root;
+    const trail = [];
+    for (const seg of segments) {
+        trail.push(typeof seg === 'number' ? `[${seg}]` : (trail.length ? '.' : '') + seg);
+        if (node === null || node === undefined)
+            return { ok: false, at: trail.join('') };
+        if (typeof seg === 'number') {
+            if (!Array.isArray(node) || seg >= node.length)
+                return { ok: false, at: trail.join('') };
+        }
+        else if (typeof node !== 'object' || !(seg in node)) {
+            return { ok: false, at: trail.join('') };
+        }
+        node = node[seg];
+    }
+    return { ok: true, value: node };
+}
+/** `pages/checkout.json` → `checkout`. Tolerates a bare page name too. */
+function pageNameFromRef(file) {
+    const m = /^pages\/(.+)\.json$/.exec(file);
+    if (m)
+        return m[1];
+    if (!file.includes('/') && !file.endsWith('.json'))
+        return file;
+    return null;
+}
+function verifyCitation(citation, index) {
+    const ref = typeof citation === 'string' ? citation : citation?.path;
+    const expect = typeof citation === 'string' ? undefined : citation?.expect;
+    const parsed = parseRef(ref);
+    if (!parsed) {
+        return {
+            ok: false,
+            path: String(ref ?? ''),
+            reason: 'malformed',
+            detail: 'Expected "<file>#<path>", e.g. pages/checkout.json#forms[0].fields[1].',
+        };
+    }
+    let root;
+    if (parsed.file === exports.SHARED_REF) {
+        if (!index.shared) {
+            return { ok: false, path: ref, reason: 'unknown-page', detail: `This capture has no ${exports.SHARED_REF}.` };
+        }
+        root = index.shared;
+    }
+    else {
+        const name = pageNameFromRef(parsed.file);
+        const page = name ? index.pages.get(name) : undefined;
+        if (!page) {
+            const known = [...index.pages.keys()].slice(0, 8).join(', ');
+            return {
+                ok: false,
+                path: ref,
+                reason: 'unknown-page',
+                detail: `No page "${name ?? parsed.file}" in this capture${known ? ` (have: ${known}…)` : ''}.`,
+            };
+        }
+        root = page;
+    }
+    const found = walk(root, parsed.segments);
+    if (!found.ok) {
+        return { ok: false, path: ref, reason: 'no-such-node', detail: `Nothing at "${found.at}" in ${parsed.file}.` };
+    }
+    if (expect && Object.keys(expect).length > 0) {
+        const value = found.value;
+        for (const [key, want] of Object.entries(expect)) {
+            const got = value === null || typeof value !== 'object' ? undefined : value[key];
+            if (got !== want) {
+                return {
+                    ok: false,
+                    path: ref,
+                    reason: 'mismatch',
+                    detail: `Claimed ${key}=${JSON.stringify(want)}, capture has ${JSON.stringify(got)}.`,
+                };
+            }
+        }
+    }
+    return { ok: true, path: ref, value: found.value };
+}
+/**
+ * Keep a claim only if it cites, and every citation resolves.
+ *
+ * All-or-nothing on purpose: a claim standing on three facts and one invention
+ * is not three-quarters true. Letting it through with the bad citation stripped
+ * would hide exactly the failure this check exists to surface — and the stage
+ * that produced it would never learn.
+ */
+function verifyClaim(claim, index) {
+    const citations = claim?.evidence ?? [];
+    if (citations.length === 0) {
+        return { claim, kept: false, supported: [], rejected: [], reason: 'No evidence cited.' };
+    }
+    const verdicts = citations.map((c) => verifyCitation(c, index));
+    const rejected = verdicts.filter((v) => !v.ok);
+    return {
+        claim,
+        kept: rejected.length === 0,
+        supported: verdicts.filter((v) => v.ok),
+        rejected,
+        reason: rejected.length > 0 ? `${rejected.length} of ${verdicts.length} citations did not check out.` : undefined,
+    };
+}
+/** Load the capture written by `scan` into an index the verifier can use. */
+function loadCaptureIndex(dir = (0, config_1.captureDir)()) {
+    const pages = new Map();
+    let shared;
+    if (!fs.existsSync(dir))
+        return { pages };
+    for (const entry of fs.readdirSync(dir)) {
+        if (!entry.endsWith('.json'))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(path.join(dir, entry), 'utf8'));
+        }
+        catch {
+            continue; // an unreadable file is not a citable one
+        }
+        if (entry === exports.SHARED_REF) {
+            shared = parsed;
+        }
+        else if (entry !== 'surface.json' && parsed && typeof parsed.page === 'string') {
+            pages.set(parsed.page, parsed);
+        }
+    }
+    return { pages, ...(shared ? { shared } : {}) };
+}
+//# sourceMappingURL=citations.js.map

package/dist/citations.js.map

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

package/dist/classificationView.d.ts

@@ -0,0 +1,118 @@
+import { type Classification, type ClassifyResult } from './ai/classify';
+import type { PageCapture } from './capture/page';
+/**
+ * Classification, as the two reports show it.
+ *
+ * One module because the markdown and the HTML must not be able to word the
+ * same thing differently — the `checkHeadline` rule from `@ia-qa/self-healing`,
+ * for the same reason: two renderers of one artifact are two sources of truth
+ * the day one of them is edited alone.
+ *
+ * Three things this layer owes the reader, none of which the raw file carries.
+ *
+ * **It is not the same kind of evidence as everything around it.** The rest of
+ * both reports is a literal DOM observation; this is a model's reading of one.
+ * Presented in the same table, in the same ink, it inherits a credibility it did
+ * not earn — so it is a section of its own, labelled, carrying the confidence
+ * and the sentence, never the label alone.
+ *
+ * **It expires, and the file cannot say so.** `classification.json` is written
+ * from a capture taken at a moment; `scan` overwrites captures in place. A
+ * classification older than the page it describes may be describing a form that
+ * no longer exists — the confident-wrong-number defect this package keeps
+ * meeting. `stale` is computed here, per page, and stated.
+ *
+ * **Silence has two meanings.** A page with entry points and no classification
+ * was either never sent or its call failed; a page with no entry points was
+ * never a candidate. Collapsing those into "not classified" is the same defect
+ * as reading an empty history as "nothing drifted", so they are counted apart.
+ */
+export interface ClassificationDocument {
+    schema: string;
+    taxonomyVersion: string;
+    classifiedAt: string;
+    model: string;
+    totals: {
+        kept: number;
+        refused: number;
+        dropped: number;
+    };
+    pages: Record<string, ClassifyResult>;
+    written?: boolean;
+}
+export interface ClassifiedPage {
+    page: string;
+    kept: Classification[];
+    refused: Classification[];
+    dropped: number;
+    /** The call did not succeed — a fact about the model, never about the app. */
+    failed?: string;
+    /**
+     * The page was re-captured after it was classified, so this reading describes
+     * a version of the page that is no longer on disk.
+     */
+    stale: boolean;
+}
+export interface ClassificationView {
+    model: string;
+    classifiedAt: string;
+    taxonomyVersion: string;
+    pages: ClassifiedPage[];
+    /** Pages that offer entry points but carry no classification at all. */
+    unclassified: string[];
+    /** Pages with nothing to classify — not a gap, and never counted as one. */
+    noEntryPoints: number;
+    staleCount: number;
+    keptTotal: number;
+    refusedTotal: number;
+    droppedTotal: number;
+    /** Security tools the kept classifications select, deduplicated. */
+    securityTools: Array<{
+        tool: string;
+        pages: string[];
+    }>;
+}
+/** Where `ia-qa-discover-ai` writes. Never `capture/`: that directory is pages. */
+export declare function classificationPath(cwd?: string): string;
+/**
+ * Read the classification, or null when there is none.
+ *
+ * A file whose `schema` is not the one this build understands is treated as
+ * absent rather than parsed optimistically: a report that renders fields it
+ * guessed at is worse than a report with no classification section.
+ */
+export declare function loadClassification(file?: string): ClassificationDocument | null;
+/**
+ * Pair a classification document with the capture the reports are rendering.
+ *
+ * `pages` is the current capture, so every count below is relative to what is on
+ * disk NOW — a classification naming a page that no longer exists is dropped
+ * from the view entirely rather than shown against nothing.
+ */
+export declare function buildClassificationView(doc: ClassificationDocument, pages: PageCapture[]): ClassificationView;
+/**
+ * The one-line summary both renderers put at the top of the section.
+ *
+ * It leads with what was kept and immediately qualifies it, because a bare
+ * "12 classified" is precisely the confident number this package spends its
+ * design on refusing to print.
+ */
+export declare function classificationHeadline(v: ClassificationView): string;
+/**
+ * The reminder, deliberately softer than the deterministic one.
+ *
+ * The tool already refuses a claim whose citation does not resolve, so telling
+ * the reader to check everything again would be alarm fatigue — a warning that
+ * fires on the good rows too is a warning people learn to skip, and then it is
+ * not there when it matters. So it names the exact residual risk instead: the
+ * check proved the citation, never the reading built on it.
+ */
+export declare const CLASSIFICATION_CAVEAT: string;
+/** Why a stale row is not simply out of date. */
+export declare const STALE_CAVEAT: string;
+/**
+ * The whole read-and-pair step, for a caller that has pages and wants the
+ * section. Returns null when there is no classification — the normal case, and
+ * every renderer must be complete without one.
+ */
+export declare function classificationFor(pages: PageCapture[], file?: string): ClassificationView | null;