@decantr/verifier 2.5.0 → 2.5.1

package/README.md

@@ -15,6 +15,8 @@ npm install @decantr/verifier
 
 - `auditProject()` for project-level Decantr audits
 - `auditBuiltDist()` for built-output runtime verification against emitted HTML, assets, and route hints
+- `scanProject()` for read-only Brownfield reconnaissance of framework, routes, components, styling, static-hosting hints, Decantr presence, and assistant-rule files
+- `resolveGitHubScanInput()` and `probePublishedSite()` for hosted scan inputs and HTML-only published-site metadata probes
 - `critiqueFile()` for file-level review against compiled review-pack contracts
 - `createContractAssertions()` for explicit route, shell, accessibility, context, and design-token assertions derived from Essence/context
 - `createEvidenceBundle()` for privacy-redacted local evidence artifacts used by AI repair loops and CI
@@ -45,9 +47,11 @@ import {
   createContractAssertions,
   createEvidenceBundle,
   critiqueFile,
+  scanProject,
   type ProjectHealthReport,
 } from '@decantr/verifier';
 
+const scan = await scanProject(process.cwd());
 const audit = await auditProject(process.cwd());
 const assertions = createContractAssertions(process.cwd(), audit);
 const critique = await critiqueFile('./src/pages/overview.tsx', process.cwd());
@@ -64,13 +68,14 @@ function isBlocking(report: ProjectHealthReport) {
 - `@decantr/verifier/schema/project-health-report.v1.json`
 - `@decantr/verifier/schema/decantr-ci-report.v1.json`
 - `@decantr/verifier/schema/evidence-bundle.v1.json`
+- `@decantr/verifier/schema/scan-report.v1.json`
 - `@decantr/verifier/schema/workspace-health-report.v1.json`
 - `@decantr/verifier/schema/file-critique-report.v1.json`
 - `@decantr/verifier/schema/showcase-shortlist-report.v1.json`
 
 ## Security And Permissions
 
-The verifier is a local library. It reads selected project source, Decantr context, and built `dist`/`.next` output when callers request project or runtime audits. Built-output runtime audit starts a temporary loopback static server and fetches from that local server only; it does not contact external hosts. The verifier does not write files, spawn processes, emit telemetry, or upload source by itself. See [security permissions](https://decantr.ai/reference/security-permissions.md).
+The verifier is a local library. It reads selected project source, Decantr context, read-only scan files, and built `dist`/`.next` output when callers request project or runtime audits. `scanProject()` returns relative evidence and does not write artifacts, install dependencies, build projects, execute scripts, or open pull requests. `probePublishedSite()` fetches HTML metadata over HTTP(S) only and does not execute JavaScript or capture screenshots. Built-output runtime audit starts a temporary loopback static server and fetches from that local server. The verifier does not write files, spawn processes, emit telemetry, or upload source by itself. See [security permissions](https://decantr.ai/reference/security-permissions.md).
 
 ## Compatibility
 

package/dist/index.d.ts

@@ -122,12 +122,154 @@ declare function verifyInteractionsInSource(interactions: string[], sources: Map
  */
 declare function listKnownInteractions(): string[];
 
+type ScanInputKind = 'local' | 'github-repo' | 'github-pages';
+type ScanConfidence = 'high' | 'medium' | 'low';
+type ScanApplicabilityStatus = 'strong_fit' | 'partial_fit' | 'not_applicable' | 'unknown';
+type ScanFindingSeverity = 'success' | 'info' | 'warn' | 'error';
+declare const SCAN_REPORT_SCHEMA_URL = "https://decantr.ai/schemas/scan-report.v1.json";
+interface ScanInputV1 {
+    kind: ScanInputKind;
+    value: string;
+}
+interface ScanRepositoryV1 {
+    owner: string;
+    repo: string;
+    url: string;
+    defaultBranch?: string | null;
+}
+interface PublishedSiteProbeV1 {
+    url: string;
+    finalUrl: string | null;
+    checked: boolean;
+    reachable: boolean;
+    status: number | null;
+    title: string | null;
+    description: string | null;
+    canonicalUrl: string | null;
+    assetHints: {
+        rootRelative: number;
+        relative: number;
+        absolute: number;
+        samples: string[];
+    };
+    routingHints: string[];
+    error: string | null;
+}
+interface ScanRouteV1 {
+    path: string;
+    file: string;
+    hasLayout: boolean;
+}
+interface ScanFindingV1 {
+    id: string;
+    severity: ScanFindingSeverity;
+    title: string;
+    message: string;
+    evidence: string[];
+    recommendation?: string;
+}
+interface ScanReportV1 {
+    $schema: typeof SCAN_REPORT_SCHEMA_URL;
+    schemaVersion: 'scan-report.v1';
+    generatedAt: string;
+    input: ScanInputV1;
+    source: {
+        repository: ScanRepositoryV1 | null;
+        publishedSiteUrl: string | null;
+    };
+    confidence: {
+        level: ScanConfidence;
+        score: number;
+        reasons: string[];
+    };
+    applicability: {
+        status: ScanApplicabilityStatus;
+        label: string;
+        reasons: string[];
+    };
+    project: {
+        framework: string;
+        frameworkVersion: string | null;
+        packageManager: string;
+        primaryLanguage: string;
+        hasTypeScript: boolean;
+        hasTailwind: boolean;
+        hasDecantr: boolean;
+        packageName: string | null;
+    };
+    routes: {
+        strategy: string;
+        count: number;
+        items: ScanRouteV1[];
+    };
+    components: {
+        pageCount: number;
+        componentCount: number;
+        directories: string[];
+    };
+    styling: {
+        approach: string;
+        configFile: string | null;
+        cssVariableCount: number;
+        colorTokenCount: number;
+        darkMode: boolean;
+        themeSignals: string[];
+    };
+    staticHosting: {
+        githubPagesLikely: boolean;
+        evidence: string[];
+        homepageUrl: string | null;
+        basePath: string | null;
+        hashRouting: boolean;
+    };
+    assistant: {
+        ruleFiles: string[];
+    };
+    pagesProbe: PublishedSiteProbeV1 | null;
+    findings: ScanFindingV1[];
+    recommendedCommands: string[];
+    privacy: {
+        sourceUploaded: boolean;
+        persistedByDecantr: boolean;
+        notes: string[];
+    };
+}
+interface ScanProjectOptions {
+    input?: ScanInputV1;
+    repository?: ScanRepositoryV1 | null;
+    publishedSiteUrl?: string | null;
+    pagesProbe?: PublishedSiteProbeV1 | null;
+}
+interface GitHubScanInputResolution {
+    inputKind: 'github-repo' | 'github-pages';
+    normalizedInput: string;
+    repository: ScanRepositoryV1;
+    publishedSiteUrl: string | null;
+    warnings: string[];
+}
+declare function scanProject(projectRoot: string, options?: ScanProjectOptions): Promise<ScanReportV1>;
+declare function createUnavailableScanReport(input: {
+    scanInput: ScanInputV1;
+    repository?: ScanRepositoryV1 | null;
+    publishedSiteUrl?: string | null;
+    pagesProbe?: PublishedSiteProbeV1 | null;
+    title: string;
+    message: string;
+    evidence?: string[];
+}): ScanReportV1;
+declare function probePublishedSite(url: string, options?: {
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<PublishedSiteProbeV1>;
+declare function resolveGitHubScanInput(input: string): GitHubScanInputResolution;
+
 declare const VERIFICATION_SCHEMA_URLS: {
     readonly common: "https://decantr.ai/schemas/verification-report.common.v1.json";
     readonly projectAudit: "https://decantr.ai/schemas/project-audit-report.v1.json";
     readonly projectHealth: "https://decantr.ai/schemas/project-health-report.v1.json";
     readonly decantrCi: "https://decantr.ai/schemas/decantr-ci-report.v1.json";
     readonly evidenceBundle: "https://decantr.ai/schemas/evidence-bundle.v1.json";
+    readonly scanReport: "https://decantr.ai/schemas/scan-report.v1.json";
     readonly workspaceHealth: "https://decantr.ai/schemas/workspace-health-report.v1.json";
     readonly fileCritique: "https://decantr.ai/schemas/file-critique-report.v1.json";
     readonly showcaseShortlist: "https://decantr.ai/schemas/showcase-shortlist-report.v1.json";
@@ -473,4 +615,4 @@ declare function auditProject(projectRoot: string): Promise<ProjectAuditReport>;
 declare function critiqueSource({ filePath, code, reviewPack, packManifest, treatmentsCss, adoptionMode, }: CritiqueSourceInput): FileCritiqueReport;
 declare function critiqueFile(filePath: string, projectRoot: string): Promise<FileCritiqueReport>;
 
-export { type BuiltDistAuditOptions, type ContractAssertion, type ContractAssertionCategory, type CritiqueSourceInput, EVIDENCE_BUNDLE_SCHEMA_URL, type EvidenceBundle, type EvidenceBundleInput, type EvidenceProvenanceEntry, type FileCritiqueReport, INTERACTION_SIGNALS, type InteractionMissingFinding, type InteractionRequirement, type InteractionSignal, type MissingPackManifestFile, type PackManifest, type ProjectAuditReport, type ProjectHealthFinding, type ProjectHealthFindingSource, type ProjectHealthPackSummary, type ProjectHealthRemediation, type ProjectHealthReport, type ProjectHealthRouteSummary, type ProjectHealthStatus, type RuntimeAudit, type ShowcaseShortlistVerificationEntry, type ShowcaseShortlistVerificationReport, VERIFICATION_SCHEMA_URLS, type VerificationFinding, type VerificationScore, type VerificationSeverity, auditBuiltDist, auditProject, collectMissingPackManifestFiles, createContractAssertions, createEvidenceBundle, critiqueFile, critiqueSource, emptyRuntimeAudit, extractRouteHintsFromEssence, listKnownInteractions, verifyInteractionsInSource };
+export { type BuiltDistAuditOptions, type ContractAssertion, type ContractAssertionCategory, type CritiqueSourceInput, EVIDENCE_BUNDLE_SCHEMA_URL, type EvidenceBundle, type EvidenceBundleInput, type EvidenceProvenanceEntry, type FileCritiqueReport, type GitHubScanInputResolution, INTERACTION_SIGNALS, type InteractionMissingFinding, type InteractionRequirement, type InteractionSignal, type MissingPackManifestFile, type PackManifest, type ProjectAuditReport, type ProjectHealthFinding, type ProjectHealthFindingSource, type ProjectHealthPackSummary, type ProjectHealthRemediation, type ProjectHealthReport, type ProjectHealthRouteSummary, type ProjectHealthStatus, type PublishedSiteProbeV1, type RuntimeAudit, SCAN_REPORT_SCHEMA_URL, type ScanApplicabilityStatus, type ScanConfidence, type ScanFindingSeverity, type ScanFindingV1, type ScanInputKind, type ScanInputV1, type ScanProjectOptions, type ScanReportV1, type ScanRepositoryV1, type ScanRouteV1, type ShowcaseShortlistVerificationEntry, type ShowcaseShortlistVerificationReport, VERIFICATION_SCHEMA_URLS, type VerificationFinding, type VerificationScore, type VerificationSeverity, auditBuiltDist, auditProject, collectMissingPackManifestFiles, createContractAssertions, createEvidenceBundle, createUnavailableScanReport, critiqueFile, critiqueSource, emptyRuntimeAudit, extractRouteHintsFromEssence, listKnownInteractions, probePublishedSite, resolveGitHubScanInput, scanProject, verifyInteractionsInSource };