@ia-qa/qa-discovery 0.1.0

package/dist/overviewFile.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Rewrite `_overview.md` from what is already on disk.
+ *
+ * `scan` writes it at capture time, which means a classification produced
+ * afterwards would never appear in it fresh — it would first show up on the
+ * *next* scan, by which point it is stale by construction. So the AI CLI
+ * regenerates it, and this is the one place that knows how.
+ *
+ * Its own module rather than a function in either neighbour: `overview.ts` is a
+ * pure renderer that touches no filesystem, and `classificationView.ts` is
+ * imported *by* the renderer — putting this in either creates an import cycle
+ * for no gain.
+ */
+export interface RefreshResult {
+    ok: boolean;
+    file?: string;
+    /** Why nothing was written. Always a sentence someone can act on. */
+    reason?: string;
+}
+/**
+ * Refuse rather than write an overview that has lost its warnings.
+ *
+ * `coverage` (login wall, href blindness, the page cap, the sitemap count) is
+ * persisted in `surface.json` precisely so this function can rebuild the file
+ * faithfully. A manifest written before that field existed cannot supply it,
+ * and defaulting it to "nothing was missed" would turn a scan that measured a
+ * login wall into an overview that reports a clean public surface — a false
+ * green manufactured by a cosmetic refresh. So an old manifest is a refusal
+ * with a one-line remedy, never a silent downgrade.
+ */
+export declare function refreshOverview(dir?: string): RefreshResult;

package/dist/overviewFile.js

@@ -0,0 +1,101 @@
+"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.refreshOverview = refreshOverview;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const citations_1 = require("./citations");
+const overview_1 = require("./overview");
+const classificationView_1 = require("./classificationView");
+const sharedCalls_1 = require("./sharedCalls");
+/**
+ * Refuse rather than write an overview that has lost its warnings.
+ *
+ * `coverage` (login wall, href blindness, the page cap, the sitemap count) is
+ * persisted in `surface.json` precisely so this function can rebuild the file
+ * faithfully. A manifest written before that field existed cannot supply it,
+ * and defaulting it to "nothing was missed" would turn a scan that measured a
+ * login wall into an overview that reports a clean public surface — a false
+ * green manufactured by a cosmetic refresh. So an old manifest is a refusal
+ * with a one-line remedy, never a silent downgrade.
+ */
+function refreshOverview(dir = (0, config_1.captureDir)()) {
+    const surfaceFile = path.join(dir, 'surface.json');
+    if (!fs.existsSync(surfaceFile)) {
+        return { ok: false, reason: `No ${path.join(dir, 'surface.json')} — run \`ia-qa-discover scan\` first.` };
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(surfaceFile, 'utf8'));
+    }
+    catch (e) {
+        return { ok: false, reason: `surface.json could not be read: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (!manifest.coverage) {
+        return {
+            ok: false,
+            reason: 'This capture predates coverage being recorded in surface.json, so _overview.md cannot be ' +
+                'rebuilt without dropping its coverage warnings (login wall, unreachable pages, the page cap). ' +
+                'Re-run `ia-qa-discover scan` and classify again.',
+        };
+    }
+    const index = (0, citations_1.loadCaptureIndex)(dir);
+    const pages = [...index.pages.values()];
+    if (pages.length === 0)
+        return { ok: false, reason: `No page captures in ${dir}.` };
+    // `_shared-calls.json` is absent for a scan run with --no-network. An empty
+    // file is the right stand-in: zero promoted calls is what actually happened,
+    // and the renderer already words that case ("no XHR/fetch traffic observed —
+    // or the scan ran with --no-network").
+    const shared = index.shared ?? {
+        schema: sharedCalls_1.SHARED_CALLS_SCHEMA,
+        capturedAt: manifest.capturedAt,
+        sourcePages: 0,
+        threshold: 0,
+        calls: [],
+    };
+    const classification = (0, classificationView_1.classificationFor)(pages);
+    const file = path.join(dir, overview_1.OVERVIEW_FILENAME);
+    fs.writeFileSync(file, (0, overview_1.renderOverview)({
+        manifest,
+        pages,
+        shared,
+        ...manifest.coverage,
+        ...(classification ? { classification } : {}),
+    }), 'utf8');
+    return { ok: true, file };
+}
+//# sourceMappingURL=overviewFile.js.map

package/dist/overviewFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overviewFile.js","sourceRoot":"","sources":["../src/overviewFile.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,0CAoDC;AA7FD,uCAAyB;AACzB,2CAA6B;AAC7B,qCAAsC;AACtC,2CAA+C;AAC/C,yCAA+D;AAC/D,6DAAyD;AACzD,+CAA0E;AAwB1E;;;;;;;;;;GAUG;AACH,SAAgB,eAAe,CAAC,MAAc,IAAA,mBAAU,GAAE;IACxD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACnD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAChC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,uCAAuC,EAAE,CAAC;IAC5G,CAAC;IAED,IAAI,QAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAoB,CAAC;IACjF,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mCAAmC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAChH,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACvB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,2FAA2F;gBAC3F,gGAAgG;gBAChG,kDAAkD;SACrD,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,IAAA,4BAAgB,EAAC,GAAG,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,GAAG,GAAG,EAAE,CAAC;IAEpF,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,uCAAuC;IACvC,MAAM,MAAM,GAAoB,KAAK,CAAC,MAAM,IAAI;QAC9C,MAAM,EAAE,iCAAmB;QAC3B,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,WAAW,EAAE,CAAC;QACd,SAAS,EAAE,CAAC;QACZ,KAAK,EAAE,EAAE;KACV,CAAC;IACF,MAAM,cAAc,GAAG,IAAA,sCAAiB,EAAC,KAAK,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,4BAAiB,CAAC,CAAC;IAC/C,EAAE,CAAC,aAAa,CACd,IAAI,EACJ,IAAA,yBAAc,EAAC;QACb,QAAQ;QACR,KAAK;QACL,MAAM;QACN,GAAG,QAAQ,CAAC,QAAQ;QACpB,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC,EACF,MAAM,CACP,CAAC;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC"}

package/dist/scan.d.ts

@@ -0,0 +1,159 @@
+import { type Candidate } from '@ia-qa/self-healing';
+import { type PageCapture } from './capture/page';
+import { SHARED_CALLS_SCHEMA, type SharedCallsFile } from './sharedCalls';
+import { type CaptureDiff } from './diff';
+import { type ScanHistoryEntry } from './history';
+/**
+ * F1 orchestrator — the one verb (`scan`) both the CLI and the MCP server call.
+ *
+ * Two-phase by necessity: `crawlApp` (from `@ia-qa/self-healing`, imported not
+ * reimplemented — it is the safety-critical same-origin BFS crawler) discovers
+ * the page list with its own `Page`, then this function does a second
+ * `page.goto()` per confirmed URL to capture meta/headings/forms/API calls.
+ * Every page loads twice; the tradeoff is accepted in the plan for this slice.
+ */
+export declare const SURFACE_SCHEMA = "qa-discovery-surface@1";
+export interface SurfaceManifest {
+    schema: typeof SURFACE_SCHEMA;
+    baseUrl: string;
+    capturedAt: string;
+    pagesFound: number;
+    pagesCaptured: number;
+    pagesFailed: number;
+    pages: Array<{
+        name: string;
+        url: string;
+        source: Candidate['source'];
+        file: string;
+    }>;
+    sharedCallsFile: string;
+    /**
+     * Every distinct origin the app called, with how many calls and how many
+     * pages hit it. `sameOrigin` alone cannot separate an app's own API host
+     * (an api.* subdomain, a Heroku backend) from a third-party tracker — both
+     * read as cross-origin. This is the observed list; deciding which are
+     * first-party is a later stage's judgment, not F1's.
+     */
+    origins: Array<{
+        origin: string;
+        calls: number;
+        pages: number;
+        sameOrigin: boolean;
+    }>;
+    /**
+     * What this scan could NOT see, persisted with what it could.
+     *
+     * It lives in the manifest because it is the only way any later consumer can
+     * rebuild `_overview.md` without silently dropping its coverage warnings —
+     * and an overview missing the login-wall caveat is a false green, strictly
+     * worse than no overview at all. Also what F2 needs to weigh how much of the
+     * app a classification actually covers.
+     */
+    coverage: {
+        loginWall: string[];
+        hrefBlind: boolean;
+        droppedByCap: number;
+        sitemapDeclared: number | null;
+        session?: string;
+    };
+}
+export interface ScanOptions {
+    url?: string;
+    maxDepth?: number;
+    maxPages?: number;
+    reveal?: boolean;
+    strictHost?: boolean;
+    session?: string;
+    locale?: string;
+    network?: boolean;
+    networkThreshold?: number;
+    safeQueryParams?: string[];
+    /** Read `sitemap.xml` (falling back to robots.txt) as a page source. Default true. */
+    sitemap?: boolean;
+    /** Click one level of disclosures per page and capture what they reveal. Default false. */
+    deep?: boolean;
+    /** Max controls clicked per page under `deep`. Default 60. */
+    deepBudget?: number;
+    /** Persist { baseUrl, ... } to config.json so later runs need no url. */
+    save?: boolean;
+    /** Persist capture/ + history.jsonl to disk. Default true — set false for an in-memory preview (e.g. an agent inspecting an app without writing to the project). */
+    write?: boolean;
+    onProgress?: (message: string) => void;
+}
+export interface ScanResult {
+    baseUrl: string;
+    pagesFound: number;
+    pagesCaptured: number;
+    failed: Array<{
+        name: string;
+        url: string;
+        error: string;
+    }>;
+    diff: CaptureDiff;
+    history: ScanHistoryEntry;
+    /** Empty string when `write: false` (nothing was persisted). */
+    surfacePath: string;
+    /** The captures themselves — always populated, written to disk only when `write` is true. */
+    pages: PageCapture[];
+    sharedCalls: SharedCallsFile;
+    /** The index document, built whether or not it was written — what `--report` renders from. */
+    manifest: SurfaceManifest;
+    /** Whether a saved/〝named〞session was used for this scan, and which file. */
+    session?: string;
+    /**
+     * Captured pages still showing a login form. More than one means the scan
+     * very likely measured the wall, not the app — the page count is then a
+     * false green. See `loginWallPages`.
+     */
+    loginWall: string[];
+    /**
+     * True when the crawl harvested ZERO internal links, so discovery could not
+     * see past the entry URL whatever the app actually contains.
+     *
+     * Discovery follows `<a href>`. A SPA that navigates programmatically —
+     * React Router's `useNavigate()`, a button with an onClick handler — exposes
+     * no href at all, so the crawl finds exactly one page and reports "1 of 1
+     * found", i.e. 100%. Measured on a real app: 11 routes, zero `<Link>`, and
+     * the scan claimed complete coverage of one page. This is the login wall's
+     * false green in another costume, and the count alone can never reveal it.
+     */
+    hrefBlind: boolean;
+    /**
+     * Where the page list came from, and what was left out.
+     *
+     * A page the sitemap declared but the cap skipped is not a page that does
+     * not exist — and the difference has to survive into the report, or the
+     * denominator quietly becomes "what we felt like visiting".
+     */
+    discovery: {
+        sitemap: null | {
+            declared: number;
+            retained: number;
+            skippedHost: number;
+            otherHosts: string[];
+            tried: string[];
+        };
+        crawled: number;
+        declared: number;
+        /** Distinct pages known before `maxPages` was applied. */
+        merged: number;
+        /** How many were dropped by the cap. Zero unless `merged > maxPages`. */
+        droppedByCap: number;
+    };
+}
+/**
+ * Pages that still show a login form.
+ *
+ * The signal is a password field — observed in the DOM, never inferred. It
+ * exists because of a failure this tool met on a real app: a SPA whose
+ * catch-all route renders the login page at EVERY unknown URL, with HTTP 200
+ * and no redirect. Nothing in the status code, the URL or the page count says
+ * anything is wrong — the scan happily reports "3 pages captured" while having
+ * captured the same wall three times. A page-count without this check is the
+ * false green this package exists to avoid.
+ *
+ * One such page is ordinary (an app has a login page). Several means the wall.
+ */
+export declare function loginWallPages(pages: PageCapture[]): string[];
+export declare function scanApp(options?: ScanOptions): Promise<ScanResult>;
+export { SHARED_CALLS_SCHEMA };