@forkpoint/agent-lighthouse-core 0.2.4 → 0.4.0

package/dist/index.d.mts

@@ -198,8 +198,89 @@ interface ReadinessVitals {
     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>;
+type PhaseId = 'fetch-root' | 'fetch-pages' | 'analyze' | 'audits' | 'report';
+type ScanEvent = {
+    type: 'scan:start';
+    url: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:start';
+    phase: PhaseId;
+    totalUnits: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:done';
+    phase: PhaseId;
+    completed: number;
+    total: number;
+    label?: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:fail';
+    phase: PhaseId;
+    label: string;
+    error: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:done';
+    phase: PhaseId;
+    durationMs: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'scan:done';
+    durationMs: number;
+    score: number;
+    fraction: number;
+    elapsedMs: number;
+};
+/**
+ * How much of the overall scan fraction each phase owns. Sums to 1 so the
+ * fraction of a finished scan is exactly 1.
+ */
+declare const PHASE_WEIGHTS: Record<PhaseId, number>;
+/**
+ * Turns scan milestones into {@link ScanEvent}s. Owns the fraction math
+ * (`Σ weights of done phases + current phase weight × completed/total`),
+ * clamps it to be monotonic non-decreasing, and stamps `fraction`/`elapsedMs`
+ * onto every event. Emission is synchronous — throttling is a consumer concern.
+ */
+declare class ProgressTracker {
+    private readonly onEvent;
+    private readonly startMs;
+    private doneWeight;
+    private phase;
+    private phaseStartMs;
+    private totalUnits;
+    private completedUnits;
+    private lastFraction;
+    constructor(onEvent: (event: ScanEvent) => void);
+    /** Fraction of the whole scan that is complete, in [0, 1]. Never decreases. */
+    get fraction(): number;
+    /** Stamp an event with the current fraction/elapsed and advance the floor. */
+    private stamp;
+    private elapsedMs;
+    scanStart(url: string): void;
+    phaseStart(phase: PhaseId, totalUnits: number): void;
+    /** Correct the current phase's unit total (e.g. discovery finds pages mid-phase). */
+    setPhaseTotal(totalUnits: number): void;
+    unitDone(label?: string): void;
+    /** A failed unit still counts as settled work so the phase can complete. */
+    unitFail(label: string, error: string): void;
+    phaseDone(): void;
+    scanDone(score: number): void;
+}
+
+interface ScanOptions {
+    onEvent?: (event: ScanEvent) => void;
+    pages?: PageOverride[] | null;
+    signal?: AbortSignal;
+}
+declare function runScan(url: string, options?: ScanOptions): Promise<ScanReport>;
 
 interface A11yNodeFinding {
     target: string;
@@ -310,12 +391,37 @@ interface AuditRunResult {
     categories: CategoryResult[];
     overallScore: number;
 }
-type ProgressFn = (completed: number, total: number) => void;
+/**
+ * Progress emitted per settled audit. The orchestrator forwards these into the
+ * ProgressTracker, which owns counting and fraction/elapsed stamping.
+ */
+type AuditProgressEvent = {
+    type: 'unit:done';
+    label: string;
+} | {
+    type: 'unit:fail';
+    label: string;
+    error: string;
+};
+interface AuditPlan {
+    runnable: Array<{
+        reg: AuditRegistration;
+        categoryId: string;
+    }>;
+    skipped: CheckResult[];
+}
+/**
+ * Split a scan config into the audits that will actually execute and the
+ * page-type-skipped `na` stubs. Exported so the orchestrator can size the
+ * audits progress phase before running it.
+ */
+declare function planAudits(ctx: CheckContext, config: ScanConfig): AuditPlan;
 /**
  * Execute all audits registered in the config against the scan context.
  * Returns check results grouped into categories with weighted scores.
+ * Pass a precomputed `plan` (from {@link planAudits}) to avoid recomputing it.
  */
-declare function runAudits(ctx: CheckContext, config: ScanConfig, onProgress?: ProgressFn): Promise<AuditRunResult>;
+declare function runAudits(ctx: CheckContext, config: ScanConfig, onEvent?: (event: AuditProgressEvent) => void, plan?: AuditPlan): Promise<AuditRunResult>;
 
 declare function parseHtml(html: string): CheerioAPI;
 declare function extractJsonLd($: CheerioAPI): object[];
@@ -711,4 +817,4 @@ declare class Logger {
 }
 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 };
+export { type AgentLighthouseConfig, Audit, type AuditGuidance, AuditGuidanceSchema, type AuditMeta, AuditMetaSchema, type AuditPlan, type AuditProgressEvent, 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, PHASE_WEIGHTS, PRESETS, type PageContext, type PageOverride, type PageType, type PhaseId, type PresetName, type PresetOptions, type ProductFieldVerification, ProgressTracker, READINESS_WEIGHTS, REQUEST_TIMEOUT_MS, type ReadinessVitals, SCANNER_USER_AGENT, SCAN_TIMEOUT_MS, SCORE_TIER_LABELS, type ScanConfig, type ScanEvent, type ScanOptions, 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, planAudits, runAudits, runScan };

package/dist/index.d.ts

@@ -198,8 +198,89 @@ interface ReadinessVitals {
     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>;
+type PhaseId = 'fetch-root' | 'fetch-pages' | 'analyze' | 'audits' | 'report';
+type ScanEvent = {
+    type: 'scan:start';
+    url: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:start';
+    phase: PhaseId;
+    totalUnits: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:done';
+    phase: PhaseId;
+    completed: number;
+    total: number;
+    label?: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:fail';
+    phase: PhaseId;
+    label: string;
+    error: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:done';
+    phase: PhaseId;
+    durationMs: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'scan:done';
+    durationMs: number;
+    score: number;
+    fraction: number;
+    elapsedMs: number;
+};
+/**
+ * How much of the overall scan fraction each phase owns. Sums to 1 so the
+ * fraction of a finished scan is exactly 1.
+ */
+declare const PHASE_WEIGHTS: Record<PhaseId, number>;
+/**
+ * Turns scan milestones into {@link ScanEvent}s. Owns the fraction math
+ * (`Σ weights of done phases + current phase weight × completed/total`),
+ * clamps it to be monotonic non-decreasing, and stamps `fraction`/`elapsedMs`
+ * onto every event. Emission is synchronous — throttling is a consumer concern.
+ */
+declare class ProgressTracker {
+    private readonly onEvent;
+    private readonly startMs;
+    private doneWeight;
+    private phase;
+    private phaseStartMs;
+    private totalUnits;
+    private completedUnits;
+    private lastFraction;
+    constructor(onEvent: (event: ScanEvent) => void);
+    /** Fraction of the whole scan that is complete, in [0, 1]. Never decreases. */
+    get fraction(): number;
+    /** Stamp an event with the current fraction/elapsed and advance the floor. */
+    private stamp;
+    private elapsedMs;
+    scanStart(url: string): void;
+    phaseStart(phase: PhaseId, totalUnits: number): void;
+    /** Correct the current phase's unit total (e.g. discovery finds pages mid-phase). */
+    setPhaseTotal(totalUnits: number): void;
+    unitDone(label?: string): void;
+    /** A failed unit still counts as settled work so the phase can complete. */
+    unitFail(label: string, error: string): void;
+    phaseDone(): void;
+    scanDone(score: number): void;
+}
+
+interface ScanOptions {
+    onEvent?: (event: ScanEvent) => void;
+    pages?: PageOverride[] | null;
+    signal?: AbortSignal;
+}
+declare function runScan(url: string, options?: ScanOptions): Promise<ScanReport>;
 
 interface A11yNodeFinding {
     target: string;
@@ -310,12 +391,37 @@ interface AuditRunResult {
     categories: CategoryResult[];
     overallScore: number;
 }
-type ProgressFn = (completed: number, total: number) => void;
+/**
+ * Progress emitted per settled audit. The orchestrator forwards these into the
+ * ProgressTracker, which owns counting and fraction/elapsed stamping.
+ */
+type AuditProgressEvent = {
+    type: 'unit:done';
+    label: string;
+} | {
+    type: 'unit:fail';
+    label: string;
+    error: string;
+};
+interface AuditPlan {
+    runnable: Array<{
+        reg: AuditRegistration;
+        categoryId: string;
+    }>;
+    skipped: CheckResult[];
+}
+/**
+ * Split a scan config into the audits that will actually execute and the
+ * page-type-skipped `na` stubs. Exported so the orchestrator can size the
+ * audits progress phase before running it.
+ */
+declare function planAudits(ctx: CheckContext, config: ScanConfig): AuditPlan;
 /**
  * Execute all audits registered in the config against the scan context.
  * Returns check results grouped into categories with weighted scores.
+ * Pass a precomputed `plan` (from {@link planAudits}) to avoid recomputing it.
  */
-declare function runAudits(ctx: CheckContext, config: ScanConfig, onProgress?: ProgressFn): Promise<AuditRunResult>;
+declare function runAudits(ctx: CheckContext, config: ScanConfig, onEvent?: (event: AuditProgressEvent) => void, plan?: AuditPlan): Promise<AuditRunResult>;
 
 declare function parseHtml(html: string): CheerioAPI;
 declare function extractJsonLd($: CheerioAPI): object[];
@@ -711,4 +817,4 @@ declare class Logger {
 }
 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 };
+export { type AgentLighthouseConfig, Audit, type AuditGuidance, AuditGuidanceSchema, type AuditMeta, AuditMetaSchema, type AuditPlan, type AuditProgressEvent, 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, PHASE_WEIGHTS, PRESETS, type PageContext, type PageOverride, type PageType, type PhaseId, type PresetName, type PresetOptions, type ProductFieldVerification, ProgressTracker, READINESS_WEIGHTS, REQUEST_TIMEOUT_MS, type ReadinessVitals, SCANNER_USER_AGENT, SCAN_TIMEOUT_MS, SCORE_TIER_LABELS, type ScanConfig, type ScanEvent, type ScanOptions, 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, planAudits, runAudits, runScan };