agent-device-lab 0.0.0-stage → 0.3.1

package/dist/core/reproduction.js

@@ -0,0 +1,36 @@
+/** How many of the most recent steps a session's reproduction history keeps (the first step is always kept). */
+export const HISTORY_KEEP = 200;
+/** How many console errors and failed requests a session keeps in memory (counters stay exact). */
+export const EVENTS_KEEP = 500;
+const OMITTED = /^… (\d+) earlier steps omitted$/;
+/**
+ * Append a reproduction step, keeping the first step (the `open …` line) and the latest `keep`, with one
+ * "… N earlier steps omitted" line between them. The array is edited in place: findings, sweeps and
+ * scans hold it by reference and copy it when they record a finding.
+ */
+export function appendStep(history, step, keep = HISTORY_KEEP) {
+    history.push(step);
+    const marker = history.length > 1 ? OMITTED.exec(history[1]) : null;
+    const tailStart = marker ? 2 : 1;
+    const drop = history.length - tailStart - keep;
+    if (drop <= 0)
+        return;
+    history.splice(tailStart, drop);
+    const text = `… ${(marker ? Number(marker[1]) : 0) + drop} earlier steps omitted`;
+    if (marker)
+        history[1] = text;
+    else
+        history.splice(1, 0, text);
+}
+/** Add to a list that keeps only the latest `keep` entries; the caller counts the true total. */
+export function pushCapped(list, item, keep = EVENTS_KEEP) {
+    list.push(item);
+    if (list.length > keep)
+        list.splice(0, list.length - keep);
+}
+/** Entries added after `mark` (a total taken earlier), as far as the capped list still holds them. */
+export function since(list, total, mark) {
+    const n = Math.min(total - mark, list.length);
+    return n > 0 ? list.slice(-n) : [];
+}
+//# sourceMappingURL=reproduction.js.map

package/dist/core/scan-policy.js

@@ -0,0 +1,156 @@
+// Pure scan policy: suppression matching, grouping by fingerprint and the pass/fail verdict.
+export const DEFAULT_POLICY = { failOn: 'high', failOnErrors: false, failOnHeuristic: false };
+export const KIND_TITLES = {
+    'horizontal-overflow': 'Page is wider than the screen',
+    'control-clipped': 'Control cut off by the screen edge',
+    'horizontal-pan-required': 'Sideways scrolling needed to reach a control',
+    'control-obstructed': 'Control covered by another element',
+    'container-clipped': 'Clipped by its container',
+    'text-clipped': 'Text cut off',
+    'text-truncated': 'Text truncated',
+    'fixed-collision': 'Fixed elements collide',
+    'content-under-fixed': 'Content hidden behind a fixed bar',
+    'modal-overflow': 'Dialog or drawer overflows the screen',
+    'unreachable-content': 'Content cannot be scrolled to',
+    'outside-container': 'Control sticks out of its container',
+    'content-scroll-x': 'Unexpected horizontal scrolling',
+    'tap-target': 'Tap target too small or too close',
+    'layout-shift': 'Layout shifts while the state settles',
+    'text-wrap-change': 'Label wraps at a narrower width',
+};
+const SEVERITY_RANK = { high: 3, medium: 2, low: 1 };
+function globToRegExp(glob) {
+    const body = glob.split('*').map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[\\s\\S]*');
+    return new RegExp(`^${body}$`);
+}
+/** Exact, or a glob where `*` matches any run of characters (including `/`), anchored at both ends. */
+function globMatch(pattern, value) {
+    return pattern.includes('*') ? globToRegExp(pattern).test(value) : pattern === value;
+}
+function ruleMatches(rule, f) {
+    if (rule.kind !== undefined) {
+        const kinds = Array.isArray(rule.kind) ? rule.kind : [rule.kind];
+        if (!kinds.includes(f.kind))
+            return false;
+    }
+    if (rule.fingerprint !== undefined && rule.fingerprint !== f.fingerprint)
+        return false;
+    if (rule.route !== undefined && !globMatch(rule.route, f.route))
+        return false;
+    if (rule.target?.role !== undefined && f.target?.role !== rule.target.role)
+        return false;
+    if (rule.target?.name !== undefined && (f.target === undefined || !globMatch(rule.target.name, f.target.name)))
+        return false;
+    if (rule.scenario !== undefined && f.scenario !== rule.scenario)
+        return false;
+    if (rule.device !== undefined && f.device !== rule.device)
+        return false;
+    return true;
+}
+export function matchSuppressions(findings, rules, ctx) {
+    const applied = new Map();
+    const statuses = [];
+    rules.forEach((rule, index) => {
+        const base = { rule: index, reason: rule.reason, ...(rule.expires ? { expires: rule.expires } : {}) };
+        if (rule.expires !== undefined && rule.expires < ctx.today) {
+            statuses.push({ ...base, status: 'expired', matched: [] });
+            return;
+        }
+        const matched = [];
+        for (const f of findings) {
+            if (!ruleMatches(rule, f))
+                continue;
+            matched.push(f.id);
+            if (!applied.has(f.id))
+                applied.set(f.id, { ...base, rule: index });
+        }
+        if (matched.length) {
+            statuses.push({ ...base, status: 'applied', matched });
+            return;
+        }
+        const outOfScope = (rule.scenario !== undefined && !ctx.scenarios.includes(rule.scenario))
+            || (rule.device !== undefined && !ctx.devices.includes(rule.device));
+        statuses.push({ ...base, status: outOfScope ? 'not-evaluated' : 'unmatched', matched });
+    });
+    return { statuses, applied };
+}
+const idNumber = (id) => Number.parseInt(id.replace(/\D+/g, ''), 10) || 0;
+export function groupFindings(findings) {
+    const byFingerprint = new Map();
+    for (const f of findings) {
+        const list = byFingerprint.get(f.fingerprint);
+        if (list)
+            list.push(f);
+        else
+            byFingerprint.set(f.fingerprint, [f]);
+    }
+    const groups = [];
+    for (const [fingerprint, members] of byFingerprint) {
+        const live = members.filter((f) => !f.suppressed);
+        const counted = live.length ? live : members;
+        const severity = counted.reduce((max, f) => (SEVERITY_RANK[f.severity] > SEVERITY_RANK[max] ? f.severity : max), 'low');
+        const confidence = counted.some((f) => f.confidence === 'confirmed') ? 'confirmed' : 'heuristic';
+        // The most severe member (confirmed first, then input order) speaks for the group.
+        const lead = members.reduce((best, f) => {
+            const a = SEVERITY_RANK[f.severity] * 2 + (f.confidence === 'confirmed' ? 1 : 0);
+            const b = SEVERITY_RANK[best.severity] * 2 + (best.confidence === 'confirmed' ? 1 : 0);
+            return a > b ? f : best;
+        });
+        const target = lead.target ? (({ ref: _ref, ...rest }) => rest)(lead.target) : undefined;
+        groups.push({
+            fingerprint,
+            kind: lead.kind,
+            title: `${KIND_TITLES[lead.kind]}: ${target ? `${target.role} "${target.name}"` : lead.route}`,
+            severity,
+            confidence,
+            route: lead.route,
+            ...(target ? { target } : {}),
+            scenarios: [...new Set(members.map((f) => f.scenario ?? 'session'))].sort(),
+            devices: [...new Set(members.map((f) => f.device))].sort(),
+            findings: members.map((f) => f.id),
+            suppressed: members.every((f) => f.suppressed !== undefined),
+        });
+    }
+    groups.sort((a, b) => Number(a.suppressed) - Number(b.suppressed)
+        || SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]
+        || Number(b.confidence === 'confirmed') - Number(a.confidence === 'confirmed')
+        || idNumber(a.findings[0] ?? '') - idNumber(b.findings[0] ?? ''));
+    return groups.map((g, i) => ({ id: `G${i + 1}`, ...g }));
+}
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+export function evaluatePolicy(findings, runs, policy) {
+    const live = findings.filter((f) => !f.suppressed);
+    const suppressedCount = findings.length - live.length;
+    const threshold = policy.failOn === 'none' ? Infinity : SEVERITY_RANK[policy.failOn];
+    const eligible = live.filter((f) => policy.failOnHeuristic || f.confidence === 'confirmed');
+    const failing = eligible.filter((f) => SEVERITY_RANK[f.severity] >= threshold);
+    const failedRuns = runs.filter((r) => r.status === 'failed');
+    const errorsFail = policy.failOnErrors && failedRuns.length > 0;
+    const reasons = [];
+    if (failing.length) {
+        const noun = policy.failOnHeuristic ? plural(failing.length, 'finding', 'findings') : plural(failing.length, 'confirmed finding', 'confirmed findings');
+        reasons.push(`${noun} at or above ${policy.failOn} severity (${failing.map((f) => f.id).join(', ')})`);
+    }
+    if (failedRuns.length) {
+        const list = failedRuns.map((r) => `"${r.scenario}" on ${r.device}${r.failedAt ? ` (${r.failedAt})` : ''}`).join(', ');
+        reasons.push(policy.failOnErrors
+            ? `${plural(failedRuns.length, 'scenario run', 'scenario runs')} failed: ${list}`
+            : `${plural(failedRuns.length, 'scenario run', 'scenario runs')} failed but failOnErrors is off: ${list}`);
+    }
+    const notFailing = eligible.filter((f) => !failing.includes(f));
+    if (notFailing.length) {
+        reasons.push(policy.failOn === 'none'
+            ? `${plural(notFailing.length, 'finding', 'findings')} not counted (failOn is none)`
+            : `${policy.failOnHeuristic ? plural(notFailing.length, 'finding', 'findings') : plural(notFailing.length, 'confirmed finding', 'confirmed findings')} below ${policy.failOn} severity ${notFailing.length === 1 ? 'does' : 'do'} not fail the scan (failOn is ${policy.failOn})`);
+    }
+    const heuristic = live.filter((f) => f.confidence === 'heuristic');
+    if (!policy.failOnHeuristic && heuristic.length) {
+        reasons.push(`${plural(heuristic.length, 'heuristic warning', 'heuristic warnings')} ${heuristic.length === 1 ? 'is' : 'are'} not counted (failOnHeuristic is off)`);
+    }
+    if (suppressedCount)
+        reasons.push(`${plural(suppressedCount, 'suppressed finding', 'suppressed findings')} ${suppressedCount === 1 ? 'is' : 'are'} not counted`);
+    if (!reasons.length)
+        reasons.push('no findings and no failed scenario runs');
+    return { result: failing.length || errorsFail ? 'fail' : 'pass', reasons, policy };
+}
+//# sourceMappingURL=scan-policy.js.map

package/dist/core/scan-report.js

@@ -0,0 +1,145 @@
+import path from 'node:path';
+// The scan's HTML report: one self-contained document, no scripts, no external resources.
+// Everything that came from the app under test is untrusted, so every string goes through esc().
+export const esc = (v) => String(v).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+export const CSS = `
+:root{--bg:#fafaf9;--fg:#1c1917;--muted:#78716c;--line:#e7e5e4;--card:#fff;--high:#b91c1c;--med:#b45309;--low:#57534e;--ok:#15803d;--warn-bg:#fef3c7}
+@media (prefers-color-scheme:dark){:root{--bg:#171717;--fg:#e7e5e4;--muted:#a8a29e;--line:#3f3f46;--card:#202020;--high:#f87171;--med:#fbbf24;--low:#a8a29e;--ok:#4ade80;--warn-bg:#3a2f0b}}
+body{margin:0;padding:24px;background:var(--bg);color:var(--fg);font:14px/1.5 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
+main{max-width:1100px;margin:0 auto}
+h1{margin:0 0 4px;font-size:24px}h2{margin:32px 0 8px;font-size:18px;border-bottom:1px solid var(--line);padding-bottom:4px}h3{margin:0 0 4px;font-size:15px}
+table{border-collapse:collapse;width:100%;margin:8px 0;background:var(--card)}
+th,td{border:1px solid var(--line);padding:4px 8px;text-align:left;vertical-align:top;font-size:13px}th{color:var(--muted);font-weight:600}
+code{font:12px ui-monospace,SFMono-Regular,Menlo,monospace;overflow-wrap:anywhere}
+.verdict{display:inline-block;padding:2px 12px;border-radius:4px;font-weight:700;font-size:20px;color:#fff}
+.verdict.pass{background:var(--ok)}.verdict.fail{background:var(--high)}
+.muted{color:var(--muted)}
+.group{border:1px solid var(--line);border-radius:6px;background:var(--card);padding:12px;margin:12px 0}
+.group.quiet{opacity:.85;border-style:dashed}
+.badge{display:inline-block;padding:0 6px;border-radius:3px;font-size:12px;font-weight:600;border:1px solid currentColor}
+.badge.high{color:var(--high)}.badge.medium{color:var(--med)}.badge.low{color:var(--low)}
+.frames{display:flex;flex-wrap:wrap;gap:8px;margin:8px 0}
+figure{margin:0;flex:0 1 220px;max-width:100%}figure img{max-width:100%;height:auto;border:1px solid var(--line);display:block}
+figcaption{font-size:12px;color:var(--muted);overflow-wrap:anywhere}
+td.failed{background:var(--warn-bg);color:var(--high)}td.ok{color:var(--ok)}
+ol{margin:4px 0;padding-left:24px}
+details{margin:6px 0}
+`;
+/** Path relative to the run directory, or undefined when the file is outside it. */
+function relInside(dir, file) {
+    const rel = path.relative(dir, file);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+        return undefined;
+    return rel.split(path.sep).map(encodeURIComponent).join('/');
+}
+function figure(dir, file, caption) {
+    if (!file)
+        return '';
+    const rel = relInside(dir, file);
+    if (!rel)
+        return '';
+    return `<figure><img src="${esc(rel)}" alt="${esc(caption)}" loading="lazy"><figcaption>${esc(caption)}</figcaption></figure>`;
+}
+export const badge = (sev) => `<span class="badge ${esc(sev)}">${esc(sev)}</span>`;
+const evidenceText = (e) => Object.entries(e).map(([k, v]) => `${k}=${v}`).join(' ');
+export function findingsTable(fs) {
+    const rows = fs.map((f) => `<tr><td>${esc(f.id)}</td><td>${esc(f.device)}</td><td>${esc(f.viewportWidth)}</td><td>${esc(f.scenario ?? 'session')}</td>` +
+        `<td>${esc(f.state ?? '')}${f.states && f.states.length > 1 ? ` <span class="muted">(${esc(f.states.join(', '))})</span>` : ''}</td>` +
+        `<td>${badge(f.severity)}</td><td>${esc(f.confidence)}</td><td>${esc(f.confidenceScore.toFixed(2))}</td>` +
+        `<td><code>${esc(evidenceText(f.evidence))}</code></td><td>${esc(f.message)}</td>` +
+        (f.suppressed ? `<td>rule ${esc(f.suppressed.rule)}: ${esc(f.suppressed.reason)}${f.suppressed.expires ? ` (expires ${esc(f.suppressed.expires)})` : ''}</td>` : '') + '</tr>');
+    const suppressed = fs.some((f) => f.suppressed);
+    return `<table><thead><tr><th>Id</th><th>Device</th><th>Width</th><th>Scenario</th><th>State</th><th>Severity</th><th>Confidence</th><th>Score</th><th>Evidence</th><th>Message</th>${suppressed ? '<th>Suppression</th>' : ''}</tr></thead><tbody>${rows.join('')}</tbody></table>`;
+}
+function framesRow(dir, fs) {
+    const items = [];
+    for (const f of fs) {
+        items.push(figure(dir, f.frame, `${f.device} · ${f.state ?? 'session'}`));
+        for (const fr of f.frames ?? [])
+            items.push(figure(dir, fr.path, fr.label));
+    }
+    const html = items.join('');
+    return html ? `<div class="frames">${html}</div>` : '';
+}
+export function groupHtml(dir, g, byId, quiet) {
+    const fs = g.findings.map((id) => byId.get(id)).filter((f) => !!f);
+    const first = fs[0];
+    const det = first ? `${first.detector.name} v${first.detector.version}` : '';
+    const steps = first ? `<details><summary>Reproduction steps (${esc(first.id)})</summary><ol>${first.reproduction.map((s) => `<li>${esc(s)}</li>`).join('')}</ol></details>` : '';
+    return `<div class="group${quiet ? ' quiet' : ''}" id="${esc(g.id)}">` +
+        `<h3>${esc(g.id)} · ${esc(g.title)} ${badge(g.severity)}</h3>` +
+        `<div class="muted">kind <code>${esc(g.kind)}</code> · detector <code>${esc(det)}</code> · route <code>${esc(g.route)}</code></div>` +
+        `<div class="muted">scenarios: ${esc(g.scenarios.join(', '))} · devices: ${esc(g.devices.join(', '))}</div>` +
+        (g.target?.selector ? `<div class="muted">target <code>${esc(g.target.selector)}</code></div>` : '') +
+        findingsTable(fs) + framesRow(dir, fs) + steps + '</div>';
+}
+function matrix(r) {
+    const scenarios = [...new Set(r.runs.map((x) => x.scenario))];
+    const cell = (run) => {
+        if (!run)
+            return '<td class="muted">not run</td>';
+        if (run.status === 'ok')
+            return `<td class="ok">ok · ${esc(run.states.length)} states · ${esc(run.findings.length)} findings</td>`;
+        const early = run.failedAt === 'context' || run.failedAt === 'load' || run.failedAt === 'setup';
+        return `<td class="failed"><strong>failed at ${esc(run.failedAt ?? 'unknown')}</strong>${early ? ' · failed before checks completed' : ''}: ${esc(run.error?.message ?? 'no message')}</td>`;
+    };
+    const rows = scenarios.map((s) => `<tr><th>${esc(s)}</th>${r.devices.map((d) => cell(r.runs.find((x) => x.scenario === s && x.device === d))).join('')}</tr>`);
+    return `<table><thead><tr><th>Scenario</th>${r.devices.map((d) => `<th>${esc(d)}</th>`).join('')}</tr></thead><tbody>${rows.join('')}</tbody></table>`;
+}
+function exploration(r) {
+    const runs = r.runs.filter((x) => x.states.some((s) => s.id !== 's0') || x.decisions.length);
+    if (!runs.length)
+        return '';
+    const parts = runs.map((run) => {
+        const states = run.states.map((s) => `<tr><td>${esc(s.id)}</td><td>${esc(s.label)}</td><td>${esc(s.path.join(' → '))}</td><td>${esc(s.status)}</td><td>${esc(s.restore ?? '')}</td><td>${esc(s.findings.join(', '))}</td><td>${esc((s.blocked ?? []).join(', '))}</td></tr>`).join('');
+        const skipped = run.decisions.filter((d) => d.verdict === 'skip').map((d) => `<tr><td>${esc(d.role)}</td><td>${esc(d.name)}</td><td>${esc(d.context ?? '')}</td><td>${esc(d.reason)}</td></tr>`).join('');
+        return `<h3>${esc(run.scenario)} @ ${esc(run.device)}</h3>` +
+            `<table><thead><tr><th>State</th><th>Label</th><th>Path</th><th>Status</th><th>Restore</th><th>Findings</th><th>Blocked requests</th></tr></thead><tbody>${states}</tbody></table>` +
+            (skipped ? `<p class="muted">Skipped controls${run.decisionsOmitted ? ` (${esc(run.decisionsOmitted)} more decisions omitted)` : ''}</p><table><thead><tr><th>Role</th><th>Name</th><th>Context</th><th>Reason</th></tr></thead><tbody>${skipped}</tbody></table>` : '') +
+            (run.limits.length ? `<ul>${run.limits.map((l) => `<li>${esc(l)}</li>`).join('')}</ul>` : '');
+    });
+    return `<h2>Exploration</h2>${parts.join('')}`;
+}
+export function scanReportHtml(result, dir) {
+    const r = result;
+    const byId = new Map(r.findings.map((f) => [f.id, f]));
+    const confirmed = r.groups.filter((g) => !g.suppressed && g.confidence === 'confirmed');
+    const heuristic = r.groups.filter((g) => !g.suppressed && g.confidence === 'heuristic');
+    const suppressed = r.groups.filter((g) => g.suppressed);
+    const failedRuns = r.runs.filter((x) => x.status === 'failed').length;
+    const p = r.verdict.policy;
+    const list = (gs, quiet, none) => gs.length ? gs.map((g) => groupHtml(dir, g, byId, quiet)).join('') : `<p class="muted">${esc(none)}</p>`;
+    const suppressedFindings = r.findings.filter((f) => f.suppressed);
+    const suppressedSection = suppressed.length
+        ? suppressed.map((g) => groupHtml(dir, g, byId, true)).join('')
+        : '<p class="muted">No group is fully suppressed.</p>';
+    // A partly suppressed group appears above with its live members; list its suppressed findings here too.
+    const partial = suppressedFindings.filter((f) => !suppressed.some((g) => g.findings.includes(f.id)));
+    const partialHtml = partial.length ? `<h3>Suppressed findings in groups that are still reported</h3>${findingsTable(partial)}` : '';
+    const supRows = r.suppressions.map((s) => {
+        const label = s.status === 'applied' ? `applied to ${s.matched.length} findings (${s.matched.join(', ')})`
+            : s.status === 'unmatched' ? 'stale — matched nothing in this run'
+                : s.status === 'expired' ? `expired on ${s.expires ?? 'an earlier date'}`
+                    : 'not evaluated (scope not in this run)';
+        return `<tr><td>${esc(s.rule)}</td><td>${esc(s.reason)}</td><td>${esc(label)}</td><td>${esc(s.expires ?? '')}</td></tr>`;
+    }).join('');
+    const jsonRel = relInside(dir, r.reports.json) ?? r.reports.json;
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Scan ${esc(r.id)}</title><style>${CSS}</style></head><body><main>
+<h1>Scan ${esc(r.id)} <span class="verdict ${r.verdict.result === 'pass' ? 'pass' : 'fail'}">${r.verdict.result.toUpperCase()}</span></h1>
+<ul>${r.verdict.reasons.map((x) => `<li>${esc(x)}</li>`).join('')}</ul>
+<p class="muted">Policy: failOn=${esc(p.failOn)}, failOnErrors=${esc(p.failOnErrors)}, failOnHeuristic=${esc(p.failOnHeuristic)}<br>
+Started ${esc(r.startedAt)} · ${esc(r.ms)} ms · devices: ${esc(r.devices.join(', '))} · exploration ${r.explore ? 'on' : 'off'}<br>
+${esc(confirmed.length)} confirmed, ${esc(heuristic.length)} heuristic, ${esc(suppressed.length)} suppressed groups · ${esc(failedRuns)} failed runs</p>
+<h2>Scenario matrix</h2>${matrix(r)}
+<h2>Confirmed problems</h2>${list(confirmed, false, 'None.')}
+<h2>Heuristic warnings</h2>${list(heuristic, true, 'None.')}
+<h2>Suppressed findings</h2>${suppressedSection}${partialHtml}
+<h2>Suppressions</h2>${r.suppressions.length ? `<table><thead><tr><th>Rule</th><th>Reason</th><th>Status</th><th>Expires</th></tr></thead><tbody>${supRows}</tbody></table>` : '<p class="muted">No suppressions configured.</p>'}
+${exploration(r)}
+<p class="muted">Full data, including every measurement and reproduction, is in the JSON report: <code>${esc(jsonRel)}</code></p>
+</main></body></html>
+`;
+}
+//# sourceMappingURL=scan-report.js.map