@forkpoint/agent-lighthouse-core 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,713 @@
+import { CheerioAPI } from 'cheerio';
+import { z } from 'zod';
+
+interface FetchOptions {
+    url: string;
+    timeout?: number;
+    followRedirects?: boolean;
+    acceptHeader?: string;
+    method?: 'GET' | 'POST' | 'OPTIONS' | 'HEAD';
+    body?: string;
+    contentType?: string;
+    /** External abort (e.g. the per-scan deadline). Combined with the per-request timeout. */
+    signal?: AbortSignal;
+}
+interface FetchResult {
+    url: string;
+    finalUrl: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+    ttfbMs: number;
+    totalMs: number;
+    contentType: string;
+    contentLength: number;
+    error?: string;
+}
+/**
+ * Validates that a URL is safe to fetch (http/https scheme, non-private IP).
+ * Use before fetching any URL extracted from scanned site content.
+ */
+declare function isSafeUrl(url: string): Promise<boolean>;
+declare function createFetcher(): {
+    fetch: (options: FetchOptions) => Promise<FetchResult>;
+};
+
+interface WafProtection {
+    isBlocked: boolean;
+    provider?: 'akamai' | 'cloudflare' | 'datadome' | 'perimeterx' | 'imperva' | 'kasada' | 'aws-waf' | 'generic-waf' | 'connection-drop';
+    name: string;
+    reason: string;
+    statusCode?: number;
+}
+/**
+ * Analyzes fetch results (homepage, root files, extra pages) to determine
+ * if the target website is behind a bot protection wall or WAF that drops
+ * or challenges automated AI agents.
+ */
+declare function detectWafProtection(targetUrl: string, homepageResult: FetchResult | null, rootFiles: Record<string, FetchResult>, scannedPagesCount: number): WafProtection | null;
+
+type PageType = 'homepage' | 'category' | 'product' | 'content';
+declare const PAGE_TYPE_LABELS: Record<PageType, string>;
+/**
+ * A user-supplied page to scan with an explicit type.
+ */
+interface PageOverride {
+    url: string;
+    pageType: PageType;
+}
+/** Per-field presence in a product page's structured data. */
+type FieldStatus = 'found' | 'partial' | 'missing';
+/**
+ * Field-level verification of a product page, read directly from its structured
+ * data (JSON-LD + Microdata + RDFa).
+ */
+interface ProductFieldVerification {
+    sku: FieldStatus;
+    gtin: FieldStatus;
+    brand: FieldStatus;
+    category: FieldStatus;
+    availability: FieldStatus;
+    priceCurrency: FieldStatus;
+    stockLevel: FieldStatus;
+    reviewCount: FieldStatus;
+    sourceUrl?: string;
+}
+type FixEffort = 'trivial' | 'easy' | 'moderate' | 'complex';
+interface AuditGuidance {
+    /** Customer-facing explanation of business impact when this audit fails */
+    impact: string;
+    /** Actionable, concise instructions to fix the issue */
+    fix: string;
+    /** Canonical code snippet showing the correct implementation */
+    code?: string;
+    /** Estimated effort to implement the fix */
+    effort: FixEffort;
+    /** Link to external documentation or spec */
+    docsUrl?: string;
+    /** Tags for filtering/grouping in the report UI */
+    tags?: string[];
+}
+type ScoreDisplayMode = 'binary' | 'ternary' | 'informative';
+interface AuditMeta {
+    id: string;
+    category: string;
+    title: string;
+    failureTitle: string;
+    description: string;
+    scoreDisplayMode: ScoreDisplayMode;
+    weight: number;
+    applicablePageTypes?: PageType[];
+    defaultPriority: CheckPriority;
+    guidance?: AuditGuidance;
+}
+interface AuditResult {
+    status: CheckStatus;
+    score: number;
+    displayValue?: string;
+    explanation?: string;
+    expected?: string;
+    found?: string;
+    message?: string;
+    details?: {
+        expected?: string;
+        found?: string;
+        code?: string;
+        [key: string]: unknown;
+    };
+    pageUrl?: string;
+    priority?: CheckPriority;
+}
+type CheckStatus = 'pass' | 'warn' | 'fail' | 'na';
+type CheckPriority = 'critical' | 'high' | 'medium' | 'low';
+interface CheckRecommendation {
+    priority: CheckPriority;
+    description: string;
+    code?: string;
+    docsUrl?: string;
+}
+interface CheckResult {
+    id: string;
+    category: string;
+    title: string;
+    description: string;
+    status: CheckStatus;
+    score: number;
+    scoreDisplayMode: ScoreDisplayMode;
+    displayValue?: string;
+    explanation?: string;
+    pageUrl?: string;
+    priority: CheckPriority;
+    impact: string;
+    fix: string;
+    details?: {
+        expected?: string;
+        found?: string;
+        code?: string;
+        docsUrl?: string;
+        [key: string]: unknown;
+    };
+    tags?: string[];
+}
+interface CategoryResult {
+    id: string;
+    name: string;
+    weight: number;
+    score: number;
+    checks: CheckResult[];
+    passCount: number;
+    warnCount: number;
+    failCount: number;
+}
+type ScoreTier = 'agent-ready' | 'partially-ready' | 'needs-work' | 'not-ready';
+interface ScanReport {
+    scanId: string;
+    url: string;
+    domain: string;
+    overallScore: number;
+    scoreTier: ScoreTier;
+    summary?: string;
+    categories: CategoryResult[];
+    topPasses: CheckResult[];
+    topFails: CheckResult[];
+    categoryScores?: Record<string, number>;
+    checkResults?: CheckResult[];
+    recommendations: CheckRecommendation[];
+    pagesScanned: Array<{
+        url: string;
+        pageType: PageType;
+    }>;
+    pagesData?: Array<{
+        url: string;
+        pageType: PageType;
+    }>;
+    scannedAt: string;
+    createdAt?: string;
+    durationMs: number;
+    previousScore?: number;
+    scoreDelta?: number;
+    readinessScore?: number;
+    readinessVitals?: ReadinessVitals;
+    productFields?: ProductFieldVerification;
+    wafProtection?: WafProtection;
+}
+interface ReadinessVitals {
+    commerce: number;
+    content: number;
+    botAccessibility: number;
+    technical: number;
+}
+
+type ProgressCallback = (pct: number, phase: string) => void | Promise<void>;
+declare function runScan(url: string, onProgress?: ProgressCallback, pageOverrides?: PageOverride[] | null, signal?: AbortSignal): Promise<ScanReport>;
+
+interface A11yNodeFinding {
+    target: string;
+    summary: string;
+}
+type A11yStatus = 'pass' | 'fail' | 'incomplete' | 'inapplicable';
+interface A11yRuleResult {
+    status: A11yStatus;
+    nodes: A11yNodeFinding[];
+}
+/** ruleId → result for a single page. */
+type A11yPageResult = Record<string, A11yRuleResult>;
+
+interface PageContext {
+    url: string;
+    pageType: PageType;
+    fetchResult: FetchResult;
+    $: CheerioAPI;
+    /** Parsed JSON-LD blocks only (used by JSON-LD-specific audits). */
+    jsonLd: object[];
+    /**
+     * Union of all structured data: JSON-LD + Microdata + RDFa, normalized to
+     * schema.org-shaped objects. Product/commerce audits read this so they detect
+     * data regardless of the markup format. Optional for backward compatibility;
+     * audits fall back to `jsonLd` when absent.
+     */
+    structuredData?: object[];
+    meta: Record<string, string>;
+    headLinks: Array<{
+        rel: string;
+        type: string;
+        href: string;
+        title: string;
+    }>;
+    /**
+     * Accessibility rule results for this page (ruleId → status + offending
+     * nodes), populated by the orchestrator. Consumed by the accessibility
+     * audits. Absent if the a11y run failed or was skipped.
+     */
+    a11yResults?: A11yPageResult;
+}
+interface CheckContext {
+    rootFiles: Record<string, FetchResult>;
+    pages: PageContext[];
+    domain: string;
+    baseUrl: string;
+    fetch: (options: FetchOptions) => Promise<FetchResult>;
+    wafProtection?: WafProtection;
+}
+type CheckFn = (ctx: CheckContext) => CheckResult | Promise<CheckResult>;
+
+/**
+ * Base class for all audits. Follows the Lighthouse pattern:
+ * each audit is a class with a static `meta` descriptor and
+ * an `audit()` method that receives the scan context.
+ */
+declare abstract class Audit {
+    static meta: AuditMeta;
+    private static readonly PRIORITY_MAP;
+    /** Validate an audit result against the schema. */
+    protected validate(result: AuditResult): AuditResult;
+    /** Run the audit and return a result. */
+    abstract audit(ctx: CheckContext): AuditResult | Promise<AuditResult>;
+    /** Create a passing result. */
+    protected pass(message: string, expected: string, found: string, pageUrl?: string): AuditResult;
+    /**
+     * Create a not-applicable result. Use when the audit's precondition is
+     * absent (e.g. a quality check on a feature the site doesn't implement at
+     * all). Excluded from score aggregation so it neither inflates nor deflates
+     * the category score — unlike a vacuous `pass()`, which rewards absence.
+     */
+    protected notApplicable(message: string, expected: string, found: string, pageUrl?: string): AuditResult;
+    /** Create a warning result. */
+    protected warn(message: string, expected: string, found: string, recommendationOrPriority?: {
+        priority: CheckPriority;
+        [key: string]: unknown;
+    } | string, pageUrl?: string): AuditResult;
+    /** Create a failing result. */
+    protected fail(message: string, expected: string, found: string, recommendationOrPriority?: {
+        priority: CheckPriority;
+        [key: string]: unknown;
+    } | string, pageUrl?: string): AuditResult;
+    /** Merge static meta with the runtime result to produce a CheckResult. */
+    toCheckResult(rawResult: AuditResult): CheckResult;
+}
+
+interface CategoryConfig {
+    id: string;
+    name: string;
+    /** Weight in the overall score (all weights should sum to 1.0). */
+    weight: number;
+}
+interface AuditRegistration {
+    /** Construct an audit instance. */
+    create: () => Audit;
+    /** The audit's static meta (copied here for fast access without instantiation). */
+    meta: AuditMeta;
+}
+interface ScanConfig {
+    categories: CategoryConfig[];
+    /** categoryId → list of audit registrations */
+    audits: Record<string, AuditRegistration[]>;
+}
+declare const defaultConfig: ScanConfig;
+
+interface AuditRunResult {
+    checks: CheckResult[];
+    categories: CategoryResult[];
+    overallScore: number;
+}
+type ProgressFn = (completed: number, total: number) => void;
+/**
+ * Execute all audits registered in the config against the scan context.
+ * Returns check results grouped into categories with weighted scores.
+ */
+declare function runAudits(ctx: CheckContext, config: ScanConfig, onProgress?: ProgressFn): Promise<AuditRunResult>;
+
+declare function parseHtml(html: string): CheerioAPI;
+declare function extractJsonLd($: CheerioAPI): object[];
+/**
+ * Flatten parsed JSON-LD into a flat list of schema.org nodes.
+ *
+ * Real-world JSON-LD nests the interesting types arbitrarily: a top-level
+ * `[{...}]` array (common on Shopify), an `@graph` container, and properties
+ * like `Product.aggregateRating`, `ProductGroup.hasVariant[].aggregateRating`,
+ * `mainEntity`, `itemReviewed`, `offers`. The previous per-audit flatteners
+ * only descended into `@graph`, so anything array-wrapped or nested was
+ * invisible — producing false "schema not found" verdicts. This walks every
+ * object and array value so type/property lookups see the whole graph.
+ */
+declare function flattenJsonLd(blocks: object[]): object[];
+/**
+ * Extract links from Markdown-ish text (llms.txt, READMEs).
+ *
+ * Real llms.txt files use many shapes the old line-anchored
+ * `^-\s*\[label\](url)` regex missed entirely: inline links inside prose,
+ * bare-URL bullets (`- **Privacy**: https://…`), `*`/`+`/numbered bullets, and
+ * indented/nested items. Returns `{ url, label, description }`, trimming the
+ * trailing punctuation/markup (backticks, brackets, periods) that otherwise
+ * corrupts the URL.
+ */
+declare function extractMarkdownLinks(body: string): Array<{
+    url: string;
+    label: string;
+    description: string;
+}>;
+declare function extractMetaTags($: CheerioAPI): Record<string, string>;
+interface HeadLink {
+    rel: string;
+    type: string;
+    href: string;
+    title: string;
+}
+declare function extractHeadLinks($: CheerioAPI): HeadLink[];
+declare function extractHeadings($: CheerioAPI): Array<{
+    level: number;
+    text: string;
+}>;
+declare function getMainContentText($: CheerioAPI): string;
+declare function getWordCount($: CheerioAPI): number;
+declare function extractImages($: CheerioAPI): Array<{
+    src: string;
+    alt: string;
+    hasAlt: boolean;
+    width?: string;
+    height?: string;
+    loading?: string;
+    role?: string;
+}>;
+declare function extractForms($: CheerioAPI): Array<{
+    action: string;
+    method: string;
+    inputs: Array<{
+        name: string;
+        type: string;
+        label?: string;
+        required: boolean;
+    }>;
+}>;
+declare function extractInternalLinks($: CheerioAPI, domain: string): string[];
+declare function extractNavLinks($: CheerioAPI): string[];
+declare function extractScripts($: CheerioAPI): Array<{
+    src?: string;
+    async: boolean;
+    defer: boolean;
+    type?: string;
+    isModule: boolean;
+    noModule: boolean;
+    inline: boolean;
+}>;
+declare function extractStylesheetUrls($: CheerioAPI): string[];
+/**
+ * Detect whether a page is a Homepage, Category Page, Product Details Page,
+ * or Content Page based on URL patterns, JSON-LD schemas, meta tags, and
+ * HTML signals typical of ecommerce websites.
+ */
+declare function detectPageType(url: string, $: CheerioAPI, jsonLd: object[], meta: Record<string, string>, isFirstPage: boolean): PageType;
+
+declare const DEFAULT_SCAN_LIMIT = 5;
+declare const MAX_PAGES_PER_SCAN = 6;
+declare const REQUEST_TIMEOUT_MS = 10000;
+declare const SCAN_TIMEOUT_MS = 60000;
+declare const MAX_RESPONSE_BODY_BYTES: number;
+declare const MAX_CONCURRENT_REQUESTS = 10;
+declare const SCANNER_USER_AGENT = "AgentLighthouse/1.0 (+https://github.com/ForkPoint/agent-lighthouse)";
+declare const TAG_SKIPPED_PAGE_TYPE = "skipped:page-type";
+declare const TAG_SCAN_ERROR = "scan-error";
+declare const CATEGORY_WEIGHTS: Record<string, number>;
+declare const CATEGORY_NAMES: Record<string, string>;
+declare const READINESS_WEIGHTS: {
+    readonly commerce: 0.4;
+    readonly content: 0.25;
+    readonly botAccessibility: 0.2;
+    readonly technical: 0.15;
+};
+declare function getScoreTier(score: number): ScoreTier;
+declare const SCORE_TIER_LABELS: Record<ScoreTier, string>;
+declare function getTierLabel(tier: string | null): string;
+declare function getTierColor(tier: string | null): string;
+
+declare function calculateCategoryScore(checks: CheckResult[]): number;
+declare function buildCategoryResult(id: string, checks: CheckResult[]): CategoryResult;
+declare function calculateOverallScore(categories: CategoryResult[]): number;
+
+/**
+ * Read product fields straight from the scanned product page(s)' structured
+ * data. Looks only at pages typed `product` (the user-supplied product page in
+ * full-report mode), mirroring how a search engine parses that page.
+ */
+declare function extractProductFieldVerification(pages: PageContext[]): ProductFieldVerification;
+
+declare const CheckStatusSchema: z.ZodEnum<["pass", "warn", "fail", "na"]>;
+declare const CheckPrioritySchema: z.ZodEnum<["critical", "high", "medium", "low"]>;
+declare const AuditResultSchema: z.ZodObject<{
+    status: z.ZodEnum<["pass", "warn", "fail", "na"]>;
+    score: z.ZodNumber;
+    displayValue: z.ZodOptional<z.ZodString>;
+    explanation: z.ZodOptional<z.ZodString>;
+    expected: z.ZodOptional<z.ZodString>;
+    found: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodObject<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        code?: string | undefined;
+        found?: string | undefined;
+        expected?: string | undefined;
+    }, {
+        code?: string | undefined;
+        found?: string | undefined;
+        expected?: string | undefined;
+    }>>;
+    pageUrl: z.ZodUnion<[z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>, z.ZodString]>;
+    priority: z.ZodOptional<z.ZodEnum<["critical", "high", "medium", "low"]>>;
+    code: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "warn" | "pass" | "fail" | "na";
+    score: number;
+    code?: string | undefined;
+    found?: string | undefined;
+    expected?: string | undefined;
+    details?: {
+        code?: string | undefined;
+        found?: string | undefined;
+        expected?: string | undefined;
+    } | undefined;
+    message?: string | undefined;
+    displayValue?: string | undefined;
+    explanation?: string | undefined;
+    pageUrl?: string | undefined;
+    priority?: "critical" | "high" | "medium" | "low" | undefined;
+}, {
+    status: "warn" | "pass" | "fail" | "na";
+    score: number;
+    code?: string | undefined;
+    found?: string | undefined;
+    expected?: string | undefined;
+    details?: {
+        code?: string | undefined;
+        found?: string | undefined;
+        expected?: string | undefined;
+    } | undefined;
+    message?: string | undefined;
+    displayValue?: string | undefined;
+    explanation?: string | undefined;
+    pageUrl?: string | undefined;
+    priority?: "critical" | "high" | "medium" | "low" | undefined;
+}>;
+declare const FixEffortSchema: z.ZodEnum<["trivial", "easy", "moderate", "complex"]>;
+declare const AuditGuidanceSchema: z.ZodObject<{
+    impact: z.ZodString;
+    fix: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    effort: z.ZodEnum<["trivial", "easy", "moderate", "complex"]>;
+    docsUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    impact: string;
+    fix: string;
+    effort: "trivial" | "easy" | "moderate" | "complex";
+    code?: string | undefined;
+    docsUrl?: string | undefined;
+    tags?: string[] | undefined;
+}, {
+    impact: string;
+    fix: string;
+    effort: "trivial" | "easy" | "moderate" | "complex";
+    code?: string | undefined;
+    docsUrl?: string | undefined;
+    tags?: string[] | undefined;
+}>;
+declare const ScoreDisplayModeSchema: z.ZodEnum<["binary", "ternary", "informative"]>;
+declare const AuditMetaSchema: z.ZodObject<{
+    id: z.ZodString;
+    category: z.ZodString;
+    title: z.ZodString;
+    failureTitle: z.ZodString;
+    description: z.ZodString;
+    scoreDisplayMode: z.ZodEnum<["binary", "ternary", "informative"]>;
+    weight: z.ZodNumber;
+    applicablePageTypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    defaultPriority: z.ZodEnum<["critical", "high", "medium", "low"]>;
+    guidance: z.ZodOptional<z.ZodObject<{
+        impact: z.ZodString;
+        fix: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
+        effort: z.ZodEnum<["trivial", "easy", "moderate", "complex"]>;
+        docsUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        impact: string;
+        fix: string;
+        effort: "trivial" | "easy" | "moderate" | "complex";
+        code?: string | undefined;
+        docsUrl?: string | undefined;
+        tags?: string[] | undefined;
+    }, {
+        impact: string;
+        fix: string;
+        effort: "trivial" | "easy" | "moderate" | "complex";
+        code?: string | undefined;
+        docsUrl?: string | undefined;
+        tags?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    category: string;
+    title: string;
+    id: string;
+    failureTitle: string;
+    description: string;
+    scoreDisplayMode: "binary" | "ternary" | "informative";
+    weight: number;
+    defaultPriority: "critical" | "high" | "medium" | "low";
+    applicablePageTypes?: string[] | undefined;
+    guidance?: {
+        impact: string;
+        fix: string;
+        effort: "trivial" | "easy" | "moderate" | "complex";
+        code?: string | undefined;
+        docsUrl?: string | undefined;
+        tags?: string[] | undefined;
+    } | undefined;
+}, {
+    category: string;
+    title: string;
+    id: string;
+    failureTitle: string;
+    description: string;
+    scoreDisplayMode: "binary" | "ternary" | "informative";
+    weight: number;
+    defaultPriority: "critical" | "high" | "medium" | "low";
+    applicablePageTypes?: string[] | undefined;
+    guidance?: {
+        impact: string;
+        fix: string;
+        effort: "trivial" | "easy" | "moderate" | "complex";
+        code?: string | undefined;
+        docsUrl?: string | undefined;
+        tags?: string[] | undefined;
+    } | undefined;
+}>;
+declare const CheckResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    category: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodEnum<["pass", "warn", "fail", "na"]>;
+    score: z.ZodNumber;
+    scoreDisplayMode: z.ZodEnum<["binary", "ternary", "informative"]>;
+    displayValue: z.ZodOptional<z.ZodString>;
+    explanation: z.ZodOptional<z.ZodString>;
+    pageUrl: z.ZodUnion<[z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>, z.ZodString]>;
+    priority: z.ZodEnum<["critical", "high", "medium", "low"]>;
+    impact: z.ZodString;
+    fix: z.ZodString;
+    details: z.ZodOptional<z.ZodObject<{
+        expected: z.ZodOptional<z.ZodString>;
+        found: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        docsUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodString]>;
+    }, "strip", z.ZodTypeAny, {
+        code?: string | undefined;
+        found?: string | undefined;
+        expected?: string | undefined;
+        docsUrl?: string | undefined;
+    }, {
+        code?: string | undefined;
+        found?: string | undefined;
+        expected?: string | undefined;
+        docsUrl?: string | undefined;
+    }>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    status: "warn" | "pass" | "fail" | "na";
+    category: string;
+    title: string;
+    id: string;
+    score: number;
+    priority: "critical" | "high" | "medium" | "low";
+    impact: string;
+    fix: string;
+    description: string;
+    scoreDisplayMode: "binary" | "ternary" | "informative";
+    details?: {
+        code?: string | undefined;
+        found?: string | undefined;
+        expected?: string | undefined;
+        docsUrl?: string | undefined;
+    } | undefined;
+    displayValue?: string | undefined;
+    explanation?: string | undefined;
+    pageUrl?: string | undefined;
+    tags?: string[] | undefined;
+}, {
+    status: "warn" | "pass" | "fail" | "na";
+    category: string;
+    title: string;
+    id: string;
+    score: number;
+    priority: "critical" | "high" | "medium" | "low";
+    impact: string;
+    fix: string;
+    description: string;
+    scoreDisplayMode: "binary" | "ternary" | "informative";
+    details?: {
+        code?: string | undefined;
+        found?: string | undefined;
+        expected?: string | undefined;
+        docsUrl?: string | undefined;
+    } | undefined;
+    displayValue?: string | undefined;
+    explanation?: string | undefined;
+    pageUrl?: string | undefined;
+    tags?: string[] | undefined;
+}>;
+
+declare function normalizeUrl(input: string): string;
+declare function joinUrl(base: string, path: string): string;
+declare function extractDomain(url: string): string;
+declare function isPrivateIp(ip: string): boolean;
+
+type PresetName = 'ecommerce' | 'saas' | 'content' | 'quick' | 'full';
+interface PresetOptions {
+    name: PresetName;
+    description: string;
+    categoryFilter?: string[];
+    customWeights?: Record<string, number>;
+    maxPages?: number;
+}
+declare const PRESETS: Record<PresetName, PresetOptions>;
+declare function getPreset(name?: string | null): PresetOptions;
+
+interface AgentLighthouseConfig {
+    /** Target URL (if not supplied via CLI) */
+    url?: string;
+    /** Audit preset profile */
+    preset?: PresetName;
+    /** Categories to execute (default: all) */
+    categories?: string[];
+    /** Minimum score threshold (0-100) to fail CI */
+    minScore?: number;
+    /** Per-category minimum score assertions */
+    assertCategories?: Record<string, number>;
+    /** Output report formats (terminal, html, json, md) */
+    output?: Array<'terminal' | 'html' | 'json' | 'md'>;
+    /** Output directory for reports */
+    outputDir?: string;
+    /** Maximum number of pages to discover & scan */
+    maxPages?: number;
+}
+/** Helper function for type-safe configuration files */
+declare function defineConfig(config: AgentLighthouseConfig): AgentLighthouseConfig;
+/**
+ * Loads Agent Lighthouse configuration from a file.
+ */
+declare function loadConfigFile(customPath?: string): AgentLighthouseConfig;
+
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+declare class Logger {
+    level: LogLevel;
+    private shouldLog;
+    debug(msg: string | Record<string, unknown>, ...args: unknown[]): void;
+    info(msg: string | Record<string, unknown>, ...args: unknown[]): void;
+    warn(msg: string | Record<string, unknown>, ...args: unknown[]): void;
+    error(msg: string | Record<string, unknown>, ...args: unknown[]): void;
+}
+declare const logger: Logger;
+
+export { type AgentLighthouseConfig, Audit, type AuditGuidance, AuditGuidanceSchema, type AuditMeta, AuditMetaSchema, type AuditRegistration, type AuditResult, AuditResultSchema, type AuditRunResult, CATEGORY_NAMES, CATEGORY_WEIGHTS, type CategoryConfig, type CategoryResult, type CheckContext, type CheckFn, type CheckPriority, CheckPrioritySchema, type CheckRecommendation, type CheckResult, CheckResultSchema, type CheckStatus, CheckStatusSchema, DEFAULT_SCAN_LIMIT, type FetchOptions, type FetchResult, type FieldStatus, type FixEffort, FixEffortSchema, MAX_CONCURRENT_REQUESTS, MAX_PAGES_PER_SCAN, MAX_RESPONSE_BODY_BYTES, PAGE_TYPE_LABELS, PRESETS, type PageContext, type PageOverride, type PageType, type PresetName, type PresetOptions, type ProductFieldVerification, READINESS_WEIGHTS, REQUEST_TIMEOUT_MS, type ReadinessVitals, SCANNER_USER_AGENT, SCAN_TIMEOUT_MS, SCORE_TIER_LABELS, type ScanConfig, type ScanReport, type ScoreDisplayMode, ScoreDisplayModeSchema, type ScoreTier, TAG_SCAN_ERROR, TAG_SKIPPED_PAGE_TYPE, type WafProtection, buildCategoryResult, calculateCategoryScore, calculateOverallScore, createFetcher, defaultConfig, defineConfig, detectPageType, detectWafProtection, extractDomain, extractForms, extractHeadLinks, extractHeadings, extractImages, extractInternalLinks, extractJsonLd, extractMarkdownLinks, extractMetaTags, extractNavLinks, extractProductFieldVerification, extractScripts, extractStylesheetUrls, flattenJsonLd, getMainContentText, getPreset, getScoreTier, getTierColor, getTierLabel, getWordCount, isPrivateIp, isSafeUrl, joinUrl, loadConfigFile, logger, normalizeUrl, parseHtml, runAudits, runScan };