@decantr/verifier 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# @decantr/verifier
+
+Support status: `core-supported`  
+Release channel: `stable`
+
+Shared Decantr verification, critique, and report-schema engine used by the CLI, MCP server, and future CI/hosted verification surfaces.
+
+## Install
+
+```bash
+npm install @decantr/verifier
+```
+
+## What It Exports
+
+- `auditProject()` for project-level Decantr audits
+- `auditBuiltDist()` for built-output runtime verification against emitted HTML, assets, and route hints
+- `critiqueFile()` for file-level review against compiled review-pack contracts
+- schema-backed report types for project audits, file critiques, and showcase verification
+- published verifier report schemas are exercised by AJV-backed round-trip tests against real audit, critique, and shortlist-report outputs
+- project audits include runtime evidence when a built `dist/` output is present:
+  - root document
+  - document title
+  - document `lang` and `viewport` metadata
+  - emitted assets
+  - route-document coverage
+  - built asset byte budgets for JS, CSS, and total payload
+  - auth-topology warnings when the essence declares authentication without clear gateway or entry routes
+
+## Example
+
+```ts
+import { auditProject, critiqueFile } from '@decantr/verifier';
+
+const audit = await auditProject(process.cwd());
+const critique = await critiqueFile('./src/pages/overview.tsx', process.cwd());
+```
+
+## Schema Exports
+
+- `@decantr/verifier/schema/verification-report.common.v1.json`
+- `@decantr/verifier/schema/project-audit-report.v1.json`
+- `@decantr/verifier/schema/file-critique-report.v1.json`
+- `@decantr/verifier/schema/showcase-shortlist-report.v1.json`
+
+## Compatibility
+
+`@decantr/verifier` is stable in the `1.x` line for the documented verifier APIs and published report-schema exports.
+
+- new checks and additive report fields may appear in compatible releases
+- breaking report-shape or exported API changes require a major version
+- hosted and CLI verifier consumers should treat the published schemas as the supported contract surface
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+import { EssenceFile } from '@decantr/essence-spec';
+import { ReviewExecutionPack } from '@decantr/core';
+
+interface RuntimeAudit {
+    distPresent: boolean;
+    indexPresent: boolean;
+    checked: boolean;
+    passed: boolean | null;
+    rootDocumentOk: boolean;
+    titleOk: boolean;
+    langOk: boolean;
+    viewportOk: boolean;
+    charsetOk: boolean;
+    cspSignalOk: boolean;
+    inlineScriptCount: number;
+    inlineEventHandlerCount: number;
+    externalScriptsWithoutIntegrityCount: number;
+    externalScriptsWithIntegrityMissingCrossoriginCount: number;
+    externalStylesheetsWithoutIntegrityCount: number;
+    externalStylesheetsWithIntegrityMissingCrossoriginCount: number;
+    externalScriptsWithInsecureTransportCount: number;
+    externalStylesheetsWithInsecureTransportCount: number;
+    externalMediaSourcesWithInsecureTransportCount: number;
+    externalBlankLinksWithoutRelCount: number;
+    externalIframesWithoutSandboxCount: number;
+    externalIframesWithInsecureTransportCount: number;
+    jsEvalSignalCount: number;
+    jsHtmlInjectionSignalCount: number;
+    jsInsecureTransportSignalCount: number;
+    jsSecretSignalCount: number;
+    assetCount: number;
+    assetsPassed: number;
+    routeHintsChecked: string[];
+    routeHintsMatched: number;
+    routeHintsCoverageOk: boolean;
+    routeDocumentsChecked: number;
+    routeDocumentsPassed: number;
+    routeDocumentsHardenedCount: number;
+    routeDocumentsCoverageOk: boolean;
+    routeDocumentsHardeningOk: boolean;
+    fullRouteCoverageOk: boolean;
+    totalAssetBytes: number;
+    jsAssetBytes: number;
+    cssAssetBytes: number;
+    largestAssetPath: string | null;
+    largestAssetBytes: number;
+    failures: string[];
+}
+interface BuiltDistAuditOptions {
+    distDir?: string;
+    routeHints?: string[];
+}
+declare function emptyRuntimeAudit(failures?: string[]): RuntimeAudit;
+declare function auditBuiltDist(projectRoot: string, options?: BuiltDistAuditOptions): Promise<RuntimeAudit>;
+
+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 fileCritique: "https://decantr.ai/schemas/file-critique-report.v1.json";
+    readonly showcaseShortlist: "https://decantr.ai/schemas/showcase-shortlist-report.v1.json";
+};
+type VerificationSeverity = 'error' | 'warn' | 'info';
+interface VerificationFinding {
+    id: string;
+    category: string;
+    severity: VerificationSeverity;
+    message: string;
+    evidence: string[];
+    target?: string;
+    file?: string;
+    rule?: string;
+    suggestedFix?: string;
+}
+interface VerificationScore {
+    category: string;
+    focusArea: string;
+    score: number;
+    details: string;
+    suggestions: string[];
+}
+interface PackManifestEntry {
+    id: string;
+    markdown: string;
+    json: string;
+}
+interface PackManifest {
+    $schema?: string;
+    version: string;
+    generatedAt: string;
+    scaffold: PackManifestEntry | null;
+    review?: PackManifestEntry | null;
+    sections: Array<PackManifestEntry & {
+        pageIds: string[];
+    }>;
+    pages: Array<PackManifestEntry & {
+        sectionId: string | null;
+        sectionRole: string | null;
+    }>;
+    mutations?: Array<PackManifestEntry & {
+        mutationType: string;
+    }>;
+}
+interface ProjectAuditReport {
+    $schema: string;
+    projectRoot: string;
+    valid: boolean;
+    essence: EssenceFile | null;
+    reviewPack: ReviewExecutionPack | null;
+    packManifest: PackManifest | null;
+    runtimeAudit: RuntimeAudit;
+    findings: VerificationFinding[];
+    summary: {
+        errorCount: number;
+        warnCount: number;
+        infoCount: number;
+        essenceVersion: string | null;
+        reviewPackPresent: boolean;
+        packManifestPresent: boolean;
+        runtimeAuditChecked: boolean;
+        runtimePassed: boolean | null;
+        pageCount: number;
+    };
+}
+interface FileCritiqueReport {
+    $schema: string;
+    file: string;
+    overall: number;
+    scores: VerificationScore[];
+    findings: VerificationFinding[];
+    focusAreas: string[];
+    reviewPack: ReviewExecutionPack | null;
+}
+interface CritiqueSourceInput {
+    filePath: string;
+    code: string;
+    reviewPack?: ReviewExecutionPack | null;
+    packManifest?: PackManifest | null;
+    treatmentsCss?: string;
+}
+interface ShowcaseShortlistVerificationEntry {
+    slug: string;
+    target: string | null;
+    classification: 'pending' | 'A' | 'B' | 'C' | 'D';
+    verificationStatus: 'pending' | 'build-green' | 'build-red' | 'smoke-green' | 'smoke-red';
+    build: {
+        passed: boolean | null;
+        durationMs: number;
+    };
+    smoke: {
+        passed: boolean | null;
+        durationMs: number;
+        rootDocumentOk: boolean;
+        titleOk: boolean;
+        langOk: boolean;
+        viewportOk: boolean;
+        charsetOk: boolean;
+        cspSignalOk: boolean;
+        inlineScriptCount: number;
+        inlineEventHandlerCount: number;
+        externalScriptsWithoutIntegrityCount: number;
+        externalScriptsWithIntegrityMissingCrossoriginCount: number;
+        externalStylesheetsWithoutIntegrityCount: number;
+        externalStylesheetsWithIntegrityMissingCrossoriginCount: number;
+        externalScriptsWithInsecureTransportCount: number;
+        externalStylesheetsWithInsecureTransportCount: number;
+        externalMediaSourcesWithInsecureTransportCount: number;
+        externalBlankLinksWithoutRelCount: number;
+        externalIframesWithoutSandboxCount: number;
+        externalIframesWithInsecureTransportCount: number;
+        jsEvalSignalCount: number;
+        jsHtmlInjectionSignalCount: number;
+        jsInsecureTransportSignalCount: number;
+        jsSecretSignalCount: number;
+        assetCount: number;
+        assetsPassed: number;
+        routeHintsChecked: string[];
+        routeHintsMatched: number;
+        routeHintsCoverageOk: boolean;
+        routeDocumentsChecked: number;
+        routeDocumentsPassed: number;
+        routeDocumentsCoverageOk: boolean;
+        fullRouteCoverageOk: boolean;
+        totalAssetBytes: number;
+        jsAssetBytes: number;
+        cssAssetBytes: number;
+        largestAssetPath: string | null;
+        largestAssetBytes: number;
+        failures: string[];
+    };
+    drift: {
+        signal: 'lower' | 'moderate' | 'elevated';
+        penalty: number;
+        inlineStyleCount: number;
+        hardcodedColorCount: number;
+        utilityLeakageCount: number;
+        decantrTreatmentCount: number;
+        hasPackManifest: boolean;
+        hasDist: boolean;
+    };
+}
+interface ShowcaseShortlistVerificationReport {
+    $schema: string;
+    generatedAt: string;
+    dryRun: boolean;
+    summary: {
+        appCount: number;
+        passedBuilds: number;
+        failedBuilds: number;
+        averageDurationMs: number;
+        passedSmokes: number;
+        failedSmokes: number;
+        averageSmokeDurationMs: number;
+        appsWithTitleOkCount: number;
+        appsWithLangOkCount: number;
+        appsWithViewportOkCount: number;
+        appsWithCharsetOkCount: number;
+        appsWithoutInlineScriptsCount: number;
+        appsWithCspSignalCount: number;
+        appsWithExternalScriptIntegrityCount: number;
+        appsWithoutInsecureRemoteAssetTransportCount: number;
+        appsWithRouteCoverageCount: number;
+        appsWithFullRouteCoverageCount: number;
+        averageTotalAssetBytes: number;
+        averageJsAssetBytes: number;
+        averageCssAssetBytes: number;
+        lowerDriftCount: number;
+        moderateDriftCount: number;
+        elevatedDriftCount: number;
+        withPackManifestCount: number;
+    };
+    results: ShowcaseShortlistVerificationEntry[];
+}
+declare function extractRouteHintsFromEssence(essence: EssenceFile | null): string[];
+declare function auditProject(projectRoot: string): Promise<ProjectAuditReport>;
+declare function critiqueSource({ filePath, code, reviewPack, packManifest, treatmentsCss, }: CritiqueSourceInput): FileCritiqueReport;
+declare function critiqueFile(filePath: string, projectRoot: string): Promise<FileCritiqueReport>;
+
+export { type BuiltDistAuditOptions, type CritiqueSourceInput, type FileCritiqueReport, type PackManifest, type ProjectAuditReport, type RuntimeAudit, type ShowcaseShortlistVerificationEntry, type ShowcaseShortlistVerificationReport, VERIFICATION_SCHEMA_URLS, type VerificationFinding, type VerificationScore, type VerificationSeverity, auditBuiltDist, auditProject, critiqueFile, critiqueSource, emptyRuntimeAudit, extractRouteHintsFromEssence };