@forkpoint/agent-lighthouse-core 0.4.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/dist/index.d.mts +67 -1
  2. package/dist/index.d.ts +67 -1
  3. package/dist/index.js +226 -1587
  4. package/dist/index.js.map +1 -1
  5. package/dist/index.mjs +224 -1587
  6. package/dist/index.mjs.map +1 -1
  7. package/migration-map.json +110 -0
  8. package/package.json +5 -3
package/dist/index.d.mts CHANGED
@@ -89,6 +89,13 @@ interface AuditGuidance {
89
89
  tags?: string[];
90
90
  }
91
91
  type ScoreDisplayMode = 'binary' | 'ternary' | 'informative';
92
+ /** Public sunset notice for a deprecated audit (see docs/evidence/sunset/NOT-A-FACTOR.md). */
93
+ interface DeprecationNotice {
94
+ /** One sentence: why this signal is not a factor. */
95
+ notice: string;
96
+ /** Public rationale URL (NOT-A-FACTOR.md anchor). */
97
+ link: string;
98
+ }
92
99
  interface AuditMeta {
93
100
  id: string;
94
101
  category: string;
@@ -100,6 +107,8 @@ interface AuditMeta {
100
107
  applicablePageTypes?: PageType[];
101
108
  defaultPriority: CheckPriority;
102
109
  guidance?: AuditGuidance;
110
+ /** Present when the audit is sunset: shown as a notice, excluded from scores. */
111
+ deprecated?: DeprecationNotice;
103
112
  }
104
113
  interface AuditResult {
105
114
  status: CheckStatus;
@@ -148,6 +157,8 @@ interface CheckResult {
148
157
  [key: string]: unknown;
149
158
  };
150
159
  tags?: string[];
160
+ /** Present when the audit is sunset: shown as a notice, excluded from scores. */
161
+ deprecated?: DeprecationNotice;
151
162
  }
152
163
  interface CategoryResult {
153
164
  id: string;
@@ -527,6 +538,15 @@ declare const SCORE_TIER_LABELS: Record<ScoreTier, string>;
527
538
  declare function getTierLabel(tier: string | null): string;
528
539
  declare function getTierColor(tier: string | null): string;
529
540
 
541
+ /**
542
+ * Single source of truth for "this check is advisory only".
543
+ *
544
+ * Informative checks (deprecated audits / no proven consumer) are still shown
545
+ * to the user, but they must never influence scores, recommendations, top
546
+ * fails/passes or readiness vitals. Every surface that ranks or scores checks
547
+ * filters through this predicate so the rule cannot drift per package.
548
+ */
549
+ declare function isInformative(check: Pick<CheckResult, 'scoreDisplayMode'>): boolean;
530
550
  declare function calculateCategoryScore(checks: CheckResult[]): number;
531
551
  declare function buildCategoryResult(id: string, checks: CheckResult[]): CategoryResult;
532
552
  declare function calculateOverallScore(categories: CategoryResult[]): number;
@@ -621,6 +641,16 @@ declare const AuditGuidanceSchema: z.ZodObject<{
621
641
  tags?: string[] | undefined;
622
642
  }>;
623
643
  declare const ScoreDisplayModeSchema: z.ZodEnum<["binary", "ternary", "informative"]>;
644
+ declare const DeprecationNoticeSchema: z.ZodObject<{
645
+ notice: z.ZodString;
646
+ link: z.ZodString;
647
+ }, "strip", z.ZodTypeAny, {
648
+ link: string;
649
+ notice: string;
650
+ }, {
651
+ link: string;
652
+ notice: string;
653
+ }>;
624
654
  declare const AuditMetaSchema: z.ZodObject<{
625
655
  id: z.ZodString;
626
656
  category: z.ZodString;
@@ -653,6 +683,16 @@ declare const AuditMetaSchema: z.ZodObject<{
653
683
  docsUrl?: string | undefined;
654
684
  tags?: string[] | undefined;
655
685
  }>>;
686
+ deprecated: z.ZodOptional<z.ZodObject<{
687
+ notice: z.ZodString;
688
+ link: z.ZodString;
689
+ }, "strip", z.ZodTypeAny, {
690
+ link: string;
691
+ notice: string;
692
+ }, {
693
+ link: string;
694
+ notice: string;
695
+ }>>;
656
696
  }, "strip", z.ZodTypeAny, {
657
697
  category: string;
658
698
  title: string;
@@ -671,6 +711,10 @@ declare const AuditMetaSchema: z.ZodObject<{
671
711
  docsUrl?: string | undefined;
672
712
  tags?: string[] | undefined;
673
713
  } | undefined;
714
+ deprecated?: {
715
+ link: string;
716
+ notice: string;
717
+ } | undefined;
674
718
  }, {
675
719
  category: string;
676
720
  title: string;
@@ -689,6 +733,10 @@ declare const AuditMetaSchema: z.ZodObject<{
689
733
  docsUrl?: string | undefined;
690
734
  tags?: string[] | undefined;
691
735
  } | undefined;
736
+ deprecated?: {
737
+ link: string;
738
+ notice: string;
739
+ } | undefined;
692
740
  }>;
693
741
  declare const CheckResultSchema: z.ZodObject<{
694
742
  id: z.ZodString;
@@ -721,6 +769,16 @@ declare const CheckResultSchema: z.ZodObject<{
721
769
  docsUrl?: string | undefined;
722
770
  }>>;
723
771
  tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
772
+ deprecated: z.ZodOptional<z.ZodObject<{
773
+ notice: z.ZodString;
774
+ link: z.ZodString;
775
+ }, "strip", z.ZodTypeAny, {
776
+ link: string;
777
+ notice: string;
778
+ }, {
779
+ link: string;
780
+ notice: string;
781
+ }>>;
724
782
  }, "strip", z.ZodTypeAny, {
725
783
  status: "warn" | "pass" | "fail" | "na";
726
784
  category: string;
@@ -742,6 +800,10 @@ declare const CheckResultSchema: z.ZodObject<{
742
800
  explanation?: string | undefined;
743
801
  pageUrl?: string | undefined;
744
802
  tags?: string[] | undefined;
803
+ deprecated?: {
804
+ link: string;
805
+ notice: string;
806
+ } | undefined;
745
807
  }, {
746
808
  status: "warn" | "pass" | "fail" | "na";
747
809
  category: string;
@@ -763,6 +825,10 @@ declare const CheckResultSchema: z.ZodObject<{
763
825
  explanation?: string | undefined;
764
826
  pageUrl?: string | undefined;
765
827
  tags?: string[] | undefined;
828
+ deprecated?: {
829
+ link: string;
830
+ notice: string;
831
+ } | undefined;
766
832
  }>;
767
833
 
768
834
  declare function normalizeUrl(input: string): string;
@@ -817,4 +883,4 @@ declare class Logger {
817
883
  }
818
884
  declare const logger: Logger;
819
885
 
820
- 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 };
886
+ 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 DeprecationNotice, DeprecationNoticeSchema, 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, isInformative, isPrivateIp, isSafeUrl, joinUrl, loadConfigFile, logger, normalizeUrl, parseHtml, planAudits, runAudits, runScan };
package/dist/index.d.ts CHANGED
@@ -89,6 +89,13 @@ interface AuditGuidance {
89
89
  tags?: string[];
90
90
  }
91
91
  type ScoreDisplayMode = 'binary' | 'ternary' | 'informative';
92
+ /** Public sunset notice for a deprecated audit (see docs/evidence/sunset/NOT-A-FACTOR.md). */
93
+ interface DeprecationNotice {
94
+ /** One sentence: why this signal is not a factor. */
95
+ notice: string;
96
+ /** Public rationale URL (NOT-A-FACTOR.md anchor). */
97
+ link: string;
98
+ }
92
99
  interface AuditMeta {
93
100
  id: string;
94
101
  category: string;
@@ -100,6 +107,8 @@ interface AuditMeta {
100
107
  applicablePageTypes?: PageType[];
101
108
  defaultPriority: CheckPriority;
102
109
  guidance?: AuditGuidance;
110
+ /** Present when the audit is sunset: shown as a notice, excluded from scores. */
111
+ deprecated?: DeprecationNotice;
103
112
  }
104
113
  interface AuditResult {
105
114
  status: CheckStatus;
@@ -148,6 +157,8 @@ interface CheckResult {
148
157
  [key: string]: unknown;
149
158
  };
150
159
  tags?: string[];
160
+ /** Present when the audit is sunset: shown as a notice, excluded from scores. */
161
+ deprecated?: DeprecationNotice;
151
162
  }
152
163
  interface CategoryResult {
153
164
  id: string;
@@ -527,6 +538,15 @@ declare const SCORE_TIER_LABELS: Record<ScoreTier, string>;
527
538
  declare function getTierLabel(tier: string | null): string;
528
539
  declare function getTierColor(tier: string | null): string;
529
540
 
541
+ /**
542
+ * Single source of truth for "this check is advisory only".
543
+ *
544
+ * Informative checks (deprecated audits / no proven consumer) are still shown
545
+ * to the user, but they must never influence scores, recommendations, top
546
+ * fails/passes or readiness vitals. Every surface that ranks or scores checks
547
+ * filters through this predicate so the rule cannot drift per package.
548
+ */
549
+ declare function isInformative(check: Pick<CheckResult, 'scoreDisplayMode'>): boolean;
530
550
  declare function calculateCategoryScore(checks: CheckResult[]): number;
531
551
  declare function buildCategoryResult(id: string, checks: CheckResult[]): CategoryResult;
532
552
  declare function calculateOverallScore(categories: CategoryResult[]): number;
@@ -621,6 +641,16 @@ declare const AuditGuidanceSchema: z.ZodObject<{
621
641
  tags?: string[] | undefined;
622
642
  }>;
623
643
  declare const ScoreDisplayModeSchema: z.ZodEnum<["binary", "ternary", "informative"]>;
644
+ declare const DeprecationNoticeSchema: z.ZodObject<{
645
+ notice: z.ZodString;
646
+ link: z.ZodString;
647
+ }, "strip", z.ZodTypeAny, {
648
+ link: string;
649
+ notice: string;
650
+ }, {
651
+ link: string;
652
+ notice: string;
653
+ }>;
624
654
  declare const AuditMetaSchema: z.ZodObject<{
625
655
  id: z.ZodString;
626
656
  category: z.ZodString;
@@ -653,6 +683,16 @@ declare const AuditMetaSchema: z.ZodObject<{
653
683
  docsUrl?: string | undefined;
654
684
  tags?: string[] | undefined;
655
685
  }>>;
686
+ deprecated: z.ZodOptional<z.ZodObject<{
687
+ notice: z.ZodString;
688
+ link: z.ZodString;
689
+ }, "strip", z.ZodTypeAny, {
690
+ link: string;
691
+ notice: string;
692
+ }, {
693
+ link: string;
694
+ notice: string;
695
+ }>>;
656
696
  }, "strip", z.ZodTypeAny, {
657
697
  category: string;
658
698
  title: string;
@@ -671,6 +711,10 @@ declare const AuditMetaSchema: z.ZodObject<{
671
711
  docsUrl?: string | undefined;
672
712
  tags?: string[] | undefined;
673
713
  } | undefined;
714
+ deprecated?: {
715
+ link: string;
716
+ notice: string;
717
+ } | undefined;
674
718
  }, {
675
719
  category: string;
676
720
  title: string;
@@ -689,6 +733,10 @@ declare const AuditMetaSchema: z.ZodObject<{
689
733
  docsUrl?: string | undefined;
690
734
  tags?: string[] | undefined;
691
735
  } | undefined;
736
+ deprecated?: {
737
+ link: string;
738
+ notice: string;
739
+ } | undefined;
692
740
  }>;
693
741
  declare const CheckResultSchema: z.ZodObject<{
694
742
  id: z.ZodString;
@@ -721,6 +769,16 @@ declare const CheckResultSchema: z.ZodObject<{
721
769
  docsUrl?: string | undefined;
722
770
  }>>;
723
771
  tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
772
+ deprecated: z.ZodOptional<z.ZodObject<{
773
+ notice: z.ZodString;
774
+ link: z.ZodString;
775
+ }, "strip", z.ZodTypeAny, {
776
+ link: string;
777
+ notice: string;
778
+ }, {
779
+ link: string;
780
+ notice: string;
781
+ }>>;
724
782
  }, "strip", z.ZodTypeAny, {
725
783
  status: "warn" | "pass" | "fail" | "na";
726
784
  category: string;
@@ -742,6 +800,10 @@ declare const CheckResultSchema: z.ZodObject<{
742
800
  explanation?: string | undefined;
743
801
  pageUrl?: string | undefined;
744
802
  tags?: string[] | undefined;
803
+ deprecated?: {
804
+ link: string;
805
+ notice: string;
806
+ } | undefined;
745
807
  }, {
746
808
  status: "warn" | "pass" | "fail" | "na";
747
809
  category: string;
@@ -763,6 +825,10 @@ declare const CheckResultSchema: z.ZodObject<{
763
825
  explanation?: string | undefined;
764
826
  pageUrl?: string | undefined;
765
827
  tags?: string[] | undefined;
828
+ deprecated?: {
829
+ link: string;
830
+ notice: string;
831
+ } | undefined;
766
832
  }>;
767
833
 
768
834
  declare function normalizeUrl(input: string): string;
@@ -817,4 +883,4 @@ declare class Logger {
817
883
  }
818
884
  declare const logger: Logger;
819
885
 
820
- 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 };
886
+ 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 DeprecationNotice, DeprecationNoticeSchema, 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, isInformative, isPrivateIp, isSafeUrl, joinUrl, loadConfigFile, logger, normalizeUrl, parseHtml, planAudits, runAudits, runScan };