@fulldotdev/scan 0.1.0

package/dist/engine/types.d.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+export declare const version: string;
+export declare const optionsSchema: z.ZodObject<{
+    deepScan: z.ZodDefault<z.ZodBoolean>;
+    lighthouseRepeatBelow: z.ZodOptional<z.ZodNumber>;
+    lighthouseMaxRuns: z.ZodDefault<z.ZodNumber>;
+    maxPages: z.ZodOptional<z.ZodNumber>;
+    maxDiscoveredUrls: z.ZodOptional<z.ZodNumber>;
+    maxResources: z.ZodOptional<z.ZodNumber>;
+    maxBrowserPages: z.ZodOptional<z.ZodNumber>;
+    maxSitemaps: z.ZodOptional<z.ZodNumber>;
+    maxQueryVariantsPerPath: z.ZodOptional<z.ZodNumber>;
+    requestTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxResponseBytes: z.ZodDefault<z.ZodNumber>;
+    maxResourceBytes: z.ZodDefault<z.ZodNumber>;
+    maxSitemapBytes: z.ZodDefault<z.ZodNumber>;
+    requestDelayMs: z.ZodDefault<z.ZodNumber>;
+    browser: z.ZodDefault<z.ZodBoolean>;
+    lighthouse: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        off: "off";
+        templates: "templates";
+    }>>;
+    lighthousePerTemplate: z.ZodDefault<z.ZodNumber>;
+    external: z.ZodDefault<z.ZodBoolean>;
+    allowLocal: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type Options = z.infer<typeof optionsSchema>;
+export type JobKind = "discover" | "sitemap" | "page" | "resource" | "browser" | "lighthouse" | "analysis";
+export type JobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+export interface Job {
+    kind: JobKind;
+    key: string;
+    status: JobStatus;
+    attempts: number;
+    error?: string;
+    durationMs?: number;
+}
+export interface ScanCoverage {
+    omittedCandidates: number;
+    templates?: number;
+    lighthouseEligible?: number;
+    lighthouseSelected?: string[];
+    lighthouseSelection?: string;
+    jobs?: {
+        kind: string;
+        status: string;
+        count: number;
+    }[];
+    expired?: boolean;
+}
+export interface Scan {
+    id: string;
+    url: string;
+    status: "running" | "completed" | "partial";
+    options: Options;
+    createdAt: string;
+    finishedAt?: string | null;
+    rotation: number;
+    coverage: ScanCoverage;
+}
+export interface Observation {
+    kind: string;
+    key: string;
+    data: any;
+}
+export interface Artifact {
+    kind: string;
+    key: string;
+    contentType: string;
+    body: string | Buffer;
+}
+export interface Candidate {
+    url: string;
+    source: string;
+    kind: "page" | "resource" | "sitemap";
+}
+export interface JobResult {
+    observations: Observation[];
+    artifacts?: Artifact[];
+    candidates?: Candidate[];
+}
+export interface UrlRow {
+    url: string;
+    kind: Candidate["kind"];
+    sources: string[];
+    scheduled: boolean;
+    skipReason: string | null;
+}
+export interface HttpResult {
+    url: string;
+    finalUrl: string;
+    status: number | null;
+    headers: Record<string, string>;
+    redirects: {
+        url: string;
+        status: number;
+        location: string;
+    }[];
+    body: string;
+    raw?: Buffer;
+    bytes: number;
+    durationMs: number;
+    fetchedAt: string;
+    outcome: "ok" | "http-error" | "inconclusive" | "blocked" | "error";
+    error?: string;
+    truncated?: boolean;
+    attempts: number;
+}
+export declare function httpEvidence(result: HttpResult): {
+    url: string;
+    finalUrl: string;
+    status: number | null;
+    headers: Record<string, string>;
+    redirects: {
+        url: string;
+        status: number;
+        location: string;
+    }[];
+    bytes: number;
+    durationMs: number;
+    fetchedAt: string;
+    outcome: "ok" | "http-error" | "inconclusive" | "blocked" | "error";
+    error?: string;
+    truncated?: boolean;
+    attempts: number;
+};
+export declare function errorMessage(error: unknown): string;

package/dist/engine/types.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import pkg from "../../package.json" with { type: "json" };
+export const version = pkg.version;
+// Count limits are optional: a scan follows every discovered page, sitemap
+// and resource unless a limit is supplied. Size and time limits always apply.
+export const optionsSchema = z
+    .object({
+    // Deeper measurement: rendering observation, Lighthouse repeats, more
+    // Lighthouse detail. Slower; meant for manual scans.
+    deepScan: z.boolean().default(false),
+    lighthouseRepeatBelow: z.number().int().min(0).max(100).optional(),
+    lighthouseMaxRuns: z.number().int().min(1).max(3).default(3),
+    maxPages: z.number().int().min(1).optional(),
+    maxDiscoveredUrls: z.number().int().min(1).optional(),
+    maxResources: z.number().int().min(0).optional(),
+    // The per-page browser pass runs on every HTML page unless limited.
+    maxBrowserPages: z.number().int().min(0).optional(),
+    maxSitemaps: z.number().int().min(1).optional(),
+    // Query-string variants of one path that are not pagination are followed
+    // up to this many; the rest are recorded as not followed (facet traps).
+    maxQueryVariantsPerPath: z.number().int().min(1).optional(),
+    requestTimeoutMs: z.number().int().min(1000).max(30000).default(12000),
+    maxResponseBytes: z
+        .number()
+        .int()
+        .min(1024)
+        .max(8_000_000)
+        .default(2_000_000),
+    // Resources are hashed and type-sniffed, not read, so a prefix is enough.
+    maxResourceBytes: z
+        .number()
+        .int()
+        .min(1024)
+        .max(8_000_000)
+        .default(500_000),
+    // Large sites ship sitemaps far bigger than a page.
+    maxSitemapBytes: z
+        .number()
+        .int()
+        .min(1024)
+        .max(50_000_000)
+        .default(10_000_000),
+    requestDelayMs: z.number().int().min(100).max(5000).default(200),
+    // The browser pass (rendered comparison, axe, overflow, keyboard).
+    browser: z.boolean().default(true),
+    // Lighthouse on one page per template (rotating), on every page, or off.
+    lighthouse: z.enum(["templates", "all", "off"]).default("templates"),
+    lighthousePerTemplate: z.number().int().min(1).max(10).default(1),
+    // Free external sources: RDAP, Chrome UX Report, Safe Browsing,
+    // SSL Labs, HSTS preload, certificate logs, blocklists.
+    external: z.boolean().default(true),
+    // Loopback and private targets, for a local development server. Every
+    // external source is then reported as not applicable.
+    allowLocal: z.boolean().default(false),
+})
+    .strict();
+export function httpEvidence(result) {
+    const { body, raw, ...evidence } = result;
+    return evidence;
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/engine.d.ts

@@ -0,0 +1 @@
+export { runScan, type RunInput, type RunOutput, type ScanEvent } from "./engine/run.js";

package/dist/engine.js

@@ -0,0 +1 @@
+export { runScan } from "./engine/run.js";

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { RunInput, RunOutput, ScanEvent } from "./engine/run.js";
+export { optionsSchema, version, type Options, type Scan, type Observation, type UrlRow, type Job } from "./engine/types.js";
+export { ScanState, type StoredArtifact } from "./engine/state.js";
+export { normalizeUrl } from "./engine/network.js";
+export { templateKey } from "./engine/select.js";
+export { buildReport, formatReport, diffFindings, type Report, type Finding, type StoredFinding, type Check, type Changes, type PreviousScan, } from "./report/build.js";
+export { rules, topicLabels, topicOrder, publicReport, publicFinding, type Rule, type Topic, type Severity, type Confidence } from "./report/rules.js";
+export { assetInventory, pageRows, incomingLinks, type AssetRow, type PageRow } from "./report/evidence.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { optionsSchema, version } from "./engine/types.js";
+export { ScanState } from "./engine/state.js";
+export { normalizeUrl } from "./engine/network.js";
+export { templateKey } from "./engine/select.js";
+export { buildReport, formatReport, diffFindings, } from "./report/build.js";
+export { rules, topicLabels, topicOrder, publicReport, publicFinding } from "./report/rules.js";
+export { assetInventory, pageRows, incomingLinks } from "./report/evidence.js";

package/dist/report/build.d.ts

@@ -0,0 +1,377 @@
+import { type Confidence, type Severity, type Topic } from "./rules.js";
+import type { Observation, Scan, UrlRow } from "../engine/types.js";
+import type { StoredArtifact } from "../engine/state.js";
+export type { Topic, Severity, Confidence } from "./rules.js";
+export type Area = "availability" | "search" | "performance" | "accessibility" | "quality";
+export interface FindingItem {
+    url: string | null;
+    text: string;
+}
+export interface Finding {
+    id: string;
+    code: string;
+    group?: string;
+    topic: Topic;
+    area?: Area;
+    severity: Severity;
+    confidence: Confidence;
+    title: string;
+    problem: string;
+    impact: string;
+    count: number;
+    pages: number;
+    items: string[];
+    urls: string[];
+    description?: string;
+    action?: string;
+}
+export interface StoredFinding extends Omit<Finding, "items"> {
+    items: FindingItem[];
+}
+export type CheckOutcome = "passed" | "issue" | "review" | "not-applicable" | "unavailable" | "not-checked";
+export interface Check {
+    code: string;
+    topic: Topic;
+    title: string;
+    outcome: CheckOutcome;
+    detail?: string;
+}
+export interface Scores {
+    performance: number | null;
+    accessibility: number | null;
+    bestPractices: number | null;
+    seo: number | null;
+}
+export interface FieldData {
+    available: boolean;
+    level?: "origin" | "url";
+    lcp: number | null;
+    inp: number | null;
+    cls: number | null;
+    verdict: "good" | "needs-improvement" | "poor" | null;
+    period: {
+        from: string;
+        to: string;
+    } | null;
+    note: string;
+    history?: {
+        to: string | null;
+        lcp: number | null;
+        inp: number | null;
+        cls: number | null;
+    }[];
+}
+export interface Security {
+    safeBrowsing: {
+        flagged: boolean;
+        threats: string[];
+    } | null;
+    tlsGrade: string | null;
+    hstsPreload: string | null;
+    blocklists: {
+        listed: string[];
+        clean: string[];
+        unavailable: string[];
+    } | null;
+    certificates: {
+        hostnames: number;
+        issuedLast30Days: number;
+        sample: string[];
+    } | null;
+}
+export interface DomainInfo {
+    name: string;
+    expiresAt: string | null;
+    daysRemaining: number | null;
+    registrar: string | null;
+}
+export interface Indexability {
+    indexable: number;
+    noindex: number;
+    canonicalElsewhere: number;
+    broken: number;
+    blocked: number;
+}
+export interface VisualChange {
+    url: string;
+    changed: number;
+    screenshotId: string | null;
+    previousScreenshotId: string | null;
+}
+export interface FindingChange {
+    id: string;
+    code: string;
+    title: string;
+    severity: Severity;
+    count: number;
+    from?: number;
+    to?: number;
+}
+export interface Changes {
+    previousScanId: string;
+    previousCreatedAt: string;
+    newFindings: Finding[];
+    resolvedFindings: FindingChange[];
+    unverifiedFindings: FindingChange[];
+    recurringFindings: FindingChange[];
+    worsenedFindings: FindingChange[];
+    fixedFindings: FindingChange[];
+    pagesAdded: string[];
+    pagesRemoved: string[];
+    titleChanges: {
+        url: string;
+        from: string;
+        to: string;
+    }[];
+    changedPages: {
+        url: string;
+        changes: string[];
+    }[];
+    infrastructure: string[];
+    scoreDrops: {
+        category: keyof Scores;
+        from: number;
+        to: number;
+    }[];
+    performance: {
+        scores: {
+            category: keyof Scores;
+            from: number;
+            to: number;
+        }[];
+        metrics: {
+            metric: string;
+            from: number;
+            to: number;
+        }[];
+        field: {
+            metric: string;
+            from: number;
+            to: number;
+        }[];
+    };
+    visual: VisualChange[];
+    indexability: {
+        from: number;
+        to: number;
+    } | null;
+}
+export interface TopicSummary {
+    status: "issues" | "review" | "passed" | "unavailable" | "not-checked" | "not-applicable";
+    findings: number;
+    critical: number;
+    warning: number;
+    hint: number;
+    facts: string[];
+}
+export interface Coverage {
+    discovered: number;
+    crawled: number;
+    omitted: number;
+    sampled: boolean;
+    complete: boolean;
+    pages: {
+        discovered: number;
+        followed: number;
+        notFollowed: Record<string, number>;
+        observed: number;
+        ok: number;
+        broken: number;
+        blocked: number;
+        inconclusive: number;
+        notReached: number;
+    };
+    resources: {
+        discovered: number;
+        checked: number;
+        ok: number;
+        broken: number;
+        inconclusive: number;
+        unverifiable: number;
+        notChecked: number;
+    };
+    sitemaps: {
+        discovered: number;
+        fetched: number;
+        valid: number;
+        invalid: number;
+        entries: number;
+        notFetched: number;
+    };
+    browser: {
+        enabled: boolean;
+        eligible: number;
+        completed: number;
+        partial: number;
+        skipped: number;
+        notRun: number;
+    };
+    lighthouse: {
+        enabled: boolean;
+        eligible: number;
+        selected: number;
+        omitted: number;
+        completed: number;
+        partial: number;
+        notRun: number;
+        devices: string[];
+    };
+    interactions: {
+        pagesScrolled: number;
+        loadMoreFound: number;
+        loadMoreClicked: number;
+        notPerformed: string[];
+    };
+    slashVariants?: {
+        expected: number;
+        verified: number;
+        unknown: string[];
+    };
+    remainingWork: {
+        kind: string;
+        status: string;
+        count: number;
+    }[];
+    expired: boolean;
+    external: Record<string, string>;
+    limits: Record<string, number>;
+    notes: string[];
+}
+export interface Report {
+    version?: 2;
+    scanId: string;
+    siteUrl: string;
+    status: string;
+    createdAt: string;
+    finishedAt: string | null;
+    overview?: {
+        characteristics: {
+            technologies: string[];
+            languages: string[];
+            pageTypes: Record<string, number>;
+            ecommerce: boolean;
+            structuredDataTypes: string[];
+            sitemap: boolean;
+            llms: boolean;
+            markdown: boolean;
+            multilingual: boolean;
+        };
+        summary: string;
+        priorities: string[];
+    };
+    health: "healthy" | "attention" | "critical";
+    pages: {
+        observed: number;
+        ok: number;
+        broken: number;
+        tested: number;
+        lighthouse?: number;
+    };
+    coverage: Coverage;
+    indexability: Indexability;
+    security: Security;
+    weight: {
+        averageBytes: number | null;
+        heaviest: {
+            url: string;
+            bytes: number;
+        } | null;
+        carbonGrams: number | null;
+    };
+    scores: {
+        mobile: Scores | null;
+        desktop: Scores | null;
+        measuredAt?: string | null;
+        carried?: boolean;
+    };
+    metrics: {
+        pages: number;
+        ttfb: number | null;
+        fcp: number | null;
+        lcp: number | null;
+        cls: number | null;
+        bytes: number | null;
+        thirdPartyShare: number | null;
+    } | null;
+    field: FieldData | null;
+    fieldPages?: ({
+        url: string;
+    } & FieldData)[];
+    domain: DomainInfo | null;
+    topics?: Record<Topic, TopicSummary>;
+    checks?: Check[];
+    methodology?: {
+        versions: Record<string, string | null>;
+        measuredAt: Record<string, string | null>;
+        notes: string[];
+    };
+    counts: {
+        critical: number;
+        warning: number;
+        hint?: number;
+    };
+    findings: Finding[];
+    changes: Changes | null;
+}
+export interface PreviousPage {
+    key: string;
+    title: string | null;
+    outcome: string | null;
+    status: number | null;
+    words: number | null;
+    canonical: string | null;
+    language: string | null;
+}
+export interface PreviousScan {
+    id: string;
+    createdAt: string;
+    report: Report;
+    findings: StoredFinding[];
+    pages: PreviousPage[];
+    dns?: any;
+    tls?: any;
+    home?: {
+        technologies?: {
+            name: string;
+        }[];
+    } | null;
+    screenshots?: {
+        url: string;
+        id: string;
+        body: Buffer;
+    }[];
+    lastScores?: {
+        mobile: Scores | null;
+        desktop: Scores | null;
+        measuredAt?: string | null;
+    } | null;
+}
+export interface ReportInput {
+    records: Observation[];
+    urls: UrlRow[];
+    artifacts: StoredArtifact[];
+    previous?: PreviousScan;
+}
+export declare function fieldVerdict(d: {
+    lcp?: number | null;
+    inp?: number | null;
+    cls?: number | null;
+}): FieldData["verdict"];
+export declare function diffFindings(before: StoredFinding[] | Finding[], after: StoredFinding[], verified?: (item: FindingItem | string, finding: {
+    code: string;
+    id?: string;
+    group?: string;
+}) => boolean): {
+    newFindings: StoredFinding[];
+    resolvedFindings: FindingChange[];
+    unverifiedFindings: FindingChange[];
+    recurringFindings: FindingChange[];
+    worsenedFindings: FindingChange[];
+};
+export declare function screenshotDifference(a: Buffer, b: Buffer): number | null;
+export declare function buildReport(scan: Scan, input: ReportInput): Promise<{
+    report: Report;
+    findings: StoredFinding[];
+}>;
+export declare const areaLabels: Record<Area, string>;
+export declare function formatReport(report: Report): string;