@decantr/verifier 2.0.0 → 2.1.0

package/README.md

@@ -16,7 +16,9 @@ npm install @decantr/verifier
 - `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, Project Health, file critiques, and showcase verification
+- `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
+- schema-backed report types for project audits, Project Health, Evidence Bundles, Workspace Health, file critiques, and showcase verification
 - `ProjectHealthReport`, `ProjectHealthFinding`, and `ProjectHealthRemediation` types for the CLI's end-user health surface
 - 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:
@@ -31,9 +33,16 @@ npm install @decantr/verifier
 ## Example
 
 ```ts
-import { auditProject, critiqueFile, type ProjectHealthReport } from '@decantr/verifier';
+import {
+  auditProject,
+  createContractAssertions,
+  createEvidenceBundle,
+  critiqueFile,
+  type ProjectHealthReport,
+} from '@decantr/verifier';
 
 const audit = await auditProject(process.cwd());
+const assertions = createContractAssertions(process.cwd(), audit);
 const critique = await critiqueFile('./src/pages/overview.tsx', process.cwd());
 
 function isBlocking(report: ProjectHealthReport) {
@@ -46,6 +55,8 @@ function isBlocking(report: ProjectHealthReport) {
 - `@decantr/verifier/schema/verification-report.common.v1.json`
 - `@decantr/verifier/schema/project-audit-report.v1.json`
 - `@decantr/verifier/schema/project-health-report.v1.json`
+- `@decantr/verifier/schema/evidence-bundle.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`
 

package/dist/index.d.ts

@@ -119,12 +119,14 @@ 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 evidenceBundle: "https://decantr.ai/schemas/evidence-bundle.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";
 };
 type VerificationSeverity = 'error' | 'warn' | 'info';
 type ProjectHealthStatus = 'healthy' | 'warning' | 'error';
-type ProjectHealthFindingSource = 'audit' | 'check' | 'brownfield' | 'runtime' | 'pack' | 'interaction';
+type ProjectHealthFindingSource = 'audit' | 'assertion' | 'browser' | 'check' | 'brownfield' | 'design-token' | 'runtime' | 'pack' | 'interaction';
 interface VerificationFinding {
     id: string;
     category: string;
@@ -248,6 +250,98 @@ interface ProjectHealthReport {
     };
     findings: ProjectHealthFinding[];
 }
+type ContractAssertionCategory = 'route' | 'shell' | 'region' | 'interaction' | 'accessibility' | 'design-token' | 'context' | 'policy';
+interface ContractAssertion {
+    id: string;
+    category: ContractAssertionCategory;
+    status: 'passed' | 'failed' | 'not_applicable';
+    severity: VerificationSeverity;
+    message: string;
+    evidence: string[];
+    target?: string;
+    rule: string;
+    suggestedFix?: string;
+}
+interface EvidenceProvenanceEntry {
+    path: string;
+    present: boolean;
+    hash: string | null;
+    generatedAt: string | null;
+}
+interface EvidenceBundle {
+    $schema: string;
+    generatedAt: string;
+    project: {
+        id: string;
+        rootLabel: string;
+    };
+    toolchain: {
+        verifierVersion: string | null;
+    };
+    privacy: {
+        localOnly: boolean;
+        redactedFields: string[];
+        screenshotsLocalOnly: boolean;
+    };
+    health: {
+        status: ProjectHealthStatus;
+        score: number;
+        errorCount: number;
+        warnCount: number;
+        infoCount: number;
+        findingCount: number;
+    };
+    provenance: {
+        essence: EvidenceProvenanceEntry;
+        packManifest: EvidenceProvenanceEntry;
+        reviewPack: EvidenceProvenanceEntry;
+        workspaceConfig?: EvidenceProvenanceEntry;
+        designTokens?: EvidenceProvenanceEntry;
+    };
+    assertions: ContractAssertion[];
+    findings: Array<{
+        id: string;
+        source: ProjectHealthFindingSource;
+        category: string;
+        severity: VerificationSeverity;
+        message: string;
+        evidence: string[];
+        target?: string;
+        rule?: string;
+        suggestedFix?: string;
+        remediationSummary: string;
+        commands: string[];
+        promptCommand: string;
+    }>;
+    browser?: {
+        enabled: boolean;
+        status: 'not_requested' | 'unavailable' | 'passed' | 'failed';
+        baseUrl: string | null;
+        screenshots: string[];
+        findings: string[];
+    };
+    designTokens?: {
+        source: string;
+        status: 'not_requested' | 'passed' | 'warning' | 'error';
+        compared: number;
+        matched: number;
+        missing: string[];
+    };
+}
+interface EvidenceBundleInput {
+    projectRoot: string;
+    report: ProjectHealthReport;
+    audit?: ProjectAuditReport | null;
+    assertions?: ContractAssertion[];
+    verifierVersion?: string | null;
+    workspaceConfigPath?: string | null;
+    designTokensPath?: string | null;
+    browser?: EvidenceBundle['browser'];
+    designTokens?: EvidenceBundle['designTokens'];
+}
+declare const EVIDENCE_BUNDLE_SCHEMA_URL = "https://decantr.ai/schemas/evidence-bundle.v1.json";
+declare function createContractAssertions(projectRoot: string, audit?: ProjectAuditReport | null): ContractAssertion[];
+declare function createEvidenceBundle(input: EvidenceBundleInput): EvidenceBundle;
 interface FileCritiqueReport {
     $schema: string;
     file: string;
@@ -362,4 +456,4 @@ 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, INTERACTION_SIGNALS, type InteractionMissingFinding, type InteractionRequirement, type InteractionSignal, 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, 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, INTERACTION_SIGNALS, type InteractionMissingFinding, type InteractionRequirement, type InteractionSignal, 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, createContractAssertions, createEvidenceBundle, critiqueFile, critiqueSource, emptyRuntimeAudit, extractRouteHintsFromEssence, listKnownInteractions, verifyInteractionsInSource };

package/dist/index.js

@@ -1,7 +1,8 @@
 // src/index.ts
-import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, realpathSync } from "fs";
+import { createHash } from "crypto";
+import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, realpathSync, statSync as statSync2 } from "fs";
 import { readFile } from "fs/promises";
-import { dirname, extname as extname2, isAbsolute, join as join2, relative, resolve } from "path";
+import { basename, dirname, extname as extname2, isAbsolute, join as join2, relative, resolve } from "path";
 import { evaluateGuard, isV4, validateEssence } from "@decantr/essence-spec";
 import * as ts from "typescript";
 
@@ -730,9 +731,249 @@ var VERIFICATION_SCHEMA_URLS = {
   common: "https://decantr.ai/schemas/verification-report.common.v1.json",
   projectAudit: "https://decantr.ai/schemas/project-audit-report.v1.json",
   projectHealth: "https://decantr.ai/schemas/project-health-report.v1.json",
+  evidenceBundle: "https://decantr.ai/schemas/evidence-bundle.v1.json",
+  workspaceHealth: "https://decantr.ai/schemas/workspace-health-report.v1.json",
   fileCritique: "https://decantr.ai/schemas/file-critique-report.v1.json",
   showcaseShortlist: "https://decantr.ai/schemas/showcase-shortlist-report.v1.json"
 };
+var EVIDENCE_BUNDLE_SCHEMA_URL = "https://decantr.ai/schemas/evidence-bundle.v1.json";
+function hashString(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function hashFile(path) {
+  if (!existsSync2(path)) return null;
+  try {
+    return createHash("sha256").update(readFileSync2(path)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+function provenanceEntry(projectRoot, relativePath) {
+  const path = join2(projectRoot, relativePath);
+  if (!existsSync2(path)) {
+    return {
+      path: relativePath,
+      present: false,
+      hash: null,
+      generatedAt: null
+    };
+  }
+  let generatedAt = null;
+  try {
+    generatedAt = statSync2(path).mtime.toISOString();
+  } catch {
+    generatedAt = null;
+  }
+  return {
+    path: relativePath,
+    present: true,
+    hash: hashFile(path),
+    generatedAt
+  };
+}
+function provenanceForPath(projectRoot, path) {
+  const rel = isAbsolute(path) ? relative(projectRoot, path).replace(/\\/g, "/") : path;
+  return provenanceEntry(projectRoot, rel && !rel.startsWith("..") ? rel : basename(path));
+}
+function redactEvidenceText(projectRoot, value) {
+  const normalizedRoot = projectRoot.replace(/\\/g, "/");
+  const normalized = value.replace(/\\/g, "/");
+  if (normalized.includes(normalizedRoot)) {
+    return normalized.split(normalizedRoot).join("<project>");
+  }
+  return normalized.replace(/\/Users\/[^/\s]+/g, "~").replace(/\/home\/[^/\s]+/g, "~");
+}
+function redactEvidenceList(projectRoot, evidence) {
+  return evidence.map((entry) => redactEvidenceText(projectRoot, entry));
+}
+function assertion(input) {
+  return {
+    status: "passed",
+    ...input
+  };
+}
+function createContractAssertions(projectRoot, audit) {
+  const assertions = [];
+  const essence = audit?.essence;
+  const v4 = essence && isV4(essence) ? essence : null;
+  const contextDir = join2(projectRoot, ".decantr", "context");
+  const packManifest = audit?.packManifest ?? null;
+  assertions.push(
+    assertion({
+      id: "contract.essence.present",
+      category: "context",
+      severity: "error",
+      rule: "essence-present",
+      status: essence ? "passed" : "failed",
+      message: essence ? "Decantr Essence contract is present." : "No Decantr Essence contract was found.",
+      evidence: [redactEvidenceText(projectRoot, join2(projectRoot, "decantr.essence.json"))],
+      suggestedFix: essence ? void 0 : "Run `decantr init` or restore decantr.essence.json."
+    })
+  );
+  assertions.push(
+    assertion({
+      id: "contract.essence.v4",
+      category: "context",
+      severity: "error",
+      rule: "essence-v4",
+      status: v4 ? "passed" : essence ? "failed" : "not_applicable",
+      message: v4 ? "Essence uses the active v4.0.0 contract." : essence ? "Essence is not the active v4.0.0 contract." : "Essence version could not be checked.",
+      evidence: [essence ? `version=${String(essence.version)}` : "essence missing"],
+      suggestedFix: v4 ? void 0 : "Run `decantr migrate --to v4` before reliability checks."
+    })
+  );
+  if (v4) {
+    const declaredRoutes = Object.keys(v4.blueprint.routes ?? {}).sort();
+    for (const route of declaredRoutes) {
+      const routeTarget = (v4.blueprint.routes ?? {})[route];
+      const section = v4.blueprint.sections.find((entry) => entry.id === routeTarget.section);
+      const page = section?.pages.find((entry) => entry.id === routeTarget.page);
+      assertions.push(
+        assertion({
+          id: `contract.route.${hashString(route)}`,
+          category: "route",
+          severity: page ? "info" : "warn",
+          rule: "declared-route-resolves",
+          status: page ? "passed" : "failed",
+          target: route,
+          message: page ? `Declared route ${route} resolves to a section page.` : `Declared route ${route} does not resolve to an existing section page.`,
+          evidence: [`section=${routeTarget.section}`, `page=${routeTarget.page}`],
+          suggestedFix: page ? void 0 : "Update blueprint.routes or add the missing section/page before running AI repair."
+        })
+      );
+    }
+    for (const section of v4.blueprint.sections) {
+      assertions.push(
+        assertion({
+          id: `contract.shell.${section.id}`,
+          category: "shell",
+          severity: section.shell && section.shell !== "inherit" ? "info" : "warn",
+          rule: "section-shell-concrete",
+          status: section.shell && section.shell !== "inherit" ? "passed" : "failed",
+          target: section.id,
+          message: section.shell && section.shell !== "inherit" ? `Section ${section.id} uses concrete shell ${section.shell}.` : `Section ${section.id} does not declare a concrete shell.`,
+          evidence: [`shell=${section.shell || "missing"}`],
+          suggestedFix: section.shell && section.shell !== "inherit" ? void 0 : "Resolve inherited shells during composition so AI agents get concrete layout intent."
+        })
+      );
+    }
+    assertions.push(
+      assertion({
+        id: "contract.accessibility.focus-visible",
+        category: "accessibility",
+        severity: v4.dna.accessibility.focus_visible ? "info" : "warn",
+        rule: "focus-visible-enabled",
+        status: v4.dna.accessibility.focus_visible ? "passed" : "failed",
+        message: v4.dna.accessibility.focus_visible ? "DNA requires visible focus states." : "DNA does not require visible focus states.",
+        evidence: [`focus_visible=${String(v4.dna.accessibility.focus_visible)}`],
+        suggestedFix: v4.dna.accessibility.focus_visible ? void 0 : "Set dna.accessibility.focus_visible=true for stronger UI reliability gates."
+      })
+    );
+  }
+  assertions.push(
+    assertion({
+      id: "contract.context.pack-manifest",
+      category: "context",
+      severity: packManifest ? "info" : "warn",
+      rule: "pack-manifest-present",
+      status: packManifest ? "passed" : "failed",
+      message: packManifest ? "Compiled execution pack manifest is present." : "Compiled execution pack manifest is missing.",
+      evidence: [redactEvidenceText(projectRoot, join2(contextDir, "pack-manifest.json"))],
+      suggestedFix: packManifest ? void 0 : "Run `decantr refresh` to regenerate context packs."
+    })
+  );
+  assertions.push(
+    assertion({
+      id: "contract.context.review-pack",
+      category: "context",
+      severity: audit?.reviewPack ? "info" : "warn",
+      rule: "review-pack-present",
+      status: audit?.reviewPack ? "passed" : "failed",
+      message: audit?.reviewPack ? "Compiled review pack is present." : "Compiled review pack is missing.",
+      evidence: [redactEvidenceText(projectRoot, join2(contextDir, "review-pack.json"))],
+      suggestedFix: audit?.reviewPack ? void 0 : "Run `decantr refresh` or hydrate the review pack from the registry."
+    })
+  );
+  const tokensPath = join2(projectRoot, "src", "styles", "tokens.css");
+  assertions.push(
+    assertion({
+      id: "contract.design-token.tokens-file",
+      category: "design-token",
+      severity: existsSync2(tokensPath) ? "info" : "warn",
+      rule: "tokens-file-present",
+      status: existsSync2(tokensPath) ? "passed" : "failed",
+      message: existsSync2(tokensPath) ? "Decantr token CSS file is present." : "Decantr token CSS file was not found.",
+      evidence: [redactEvidenceText(projectRoot, tokensPath)],
+      suggestedFix: existsSync2(tokensPath) ? void 0 : "Run `decantr refresh` or map Decantr tokens into the existing styling system."
+    })
+  );
+  return assertions;
+}
+function createEvidenceBundle(input) {
+  const assertions = input.assertions ?? createContractAssertions(input.projectRoot, input.audit);
+  let resolvedProjectRoot = input.projectRoot;
+  try {
+    resolvedProjectRoot = realpathSync(input.projectRoot);
+  } catch {
+    resolvedProjectRoot = resolve(input.projectRoot);
+  }
+  const projectId = `project_${hashString(resolvedProjectRoot)}`;
+  return {
+    $schema: EVIDENCE_BUNDLE_SCHEMA_URL,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    project: {
+      id: projectId,
+      rootLabel: basename(input.projectRoot) || "project"
+    },
+    toolchain: {
+      verifierVersion: input.verifierVersion ?? null
+    },
+    privacy: {
+      localOnly: true,
+      redactedFields: [
+        "source",
+        "prompt",
+        "secret",
+        "environment",
+        "absolute_path",
+        "repository_name"
+      ],
+      screenshotsLocalOnly: true
+    },
+    health: {
+      status: input.report.status,
+      score: input.report.score,
+      errorCount: input.report.summary.errorCount,
+      warnCount: input.report.summary.warnCount,
+      infoCount: input.report.summary.infoCount,
+      findingCount: input.report.summary.findingCount
+    },
+    provenance: {
+      essence: provenanceEntry(input.projectRoot, "decantr.essence.json"),
+      packManifest: provenanceEntry(input.projectRoot, ".decantr/context/pack-manifest.json"),
+      reviewPack: provenanceEntry(input.projectRoot, ".decantr/context/review-pack.json"),
+      ...input.workspaceConfigPath ? { workspaceConfig: provenanceForPath(input.projectRoot, input.workspaceConfigPath) } : {},
+      ...input.designTokensPath ? { designTokens: provenanceForPath(input.projectRoot, input.designTokensPath) } : {}
+    },
+    assertions,
+    findings: input.report.findings.map((finding) => ({
+      id: finding.id,
+      source: finding.source,
+      category: finding.category,
+      severity: finding.severity,
+      message: redactEvidenceText(input.projectRoot, finding.message),
+      evidence: redactEvidenceList(input.projectRoot, finding.evidence),
+      target: finding.target ? redactEvidenceText(input.projectRoot, finding.target) : void 0,
+      rule: finding.rule,
+      suggestedFix: finding.suggestedFix,
+      remediationSummary: finding.remediation.summary,
+      commands: finding.remediation.commands,
+      promptCommand: `decantr health --prompt ${finding.id}`
+    })),
+    ...input.browser ? { browser: input.browser } : {},
+    ...input.designTokens ? { designTokens: input.designTokens } : {}
+  };
+}
 var DEFAULT_FOCUS_AREAS = [
   "route-topology",
   "theme-consistency",
@@ -1463,7 +1704,13 @@ function guardViolationToFinding(violation) {
 }
 function countPages(essence) {
   if (!essence) return 0;
-  return essence.blueprint.sections.reduce((sum, section) => sum + section.pages.length, 0);
+  const blueprint = essence.blueprint;
+  const sectionPages = Array.isArray(blueprint.sections) ? blueprint.sections.reduce(
+    (sum, section) => sum + (Array.isArray(section.pages) ? section.pages.length : 0),
+    0
+  ) : 0;
+  const flatPages = Array.isArray(blueprint.pages) ? blueprint.pages.length : 0;
+  return sectionPages + flatPages;
 }
 function makeFinding(input) {
   return input;
@@ -3884,6 +4131,23 @@ function isNavigationLandmark(tagName, attributes) {
 function hasNavigationLabel(attributes) {
   return Boolean(getJsxAttribute(attributes, "aria-label", "aria-labelledby", "title"));
 }
+function getJsxAttributeOwner(attribute) {
+  const attributes = attribute.parent;
+  if (!attributes || !ts.isJsxAttributes(attributes)) return null;
+  const owner = attributes.parent;
+  if (ts.isJsxOpeningElement(owner) || ts.isJsxSelfClosingElement(owner)) {
+    return owner;
+  }
+  return null;
+}
+function isSafeJsonLdDangerouslySetInnerHtml(attribute) {
+  const owner = getJsxAttributeOwner(attribute);
+  if (!owner || getJsxTagName(owner) !== "script") return false;
+  const typeValue = getJsxAttributeLiteralValue(getJsxAttribute(owner.attributes, "type"))?.trim().toLowerCase();
+  if (typeValue !== "application/ld+json") return false;
+  const sourceText = attribute.getText();
+  return /\bJSON\.stringify\s*\(/.test(sourceText) && /\\u003c/i.test(sourceText);
+}
 function hasInsecureFormAction(attributes) {
   const actionValue = getJsxAttributeLiteralValue(getJsxAttribute(attributes, "action"));
   const normalized = actionValue?.trim().toLowerCase() ?? "";
@@ -9406,7 +9670,7 @@ function analyzeAstSignals(filePath, code) {
           signals.inlineStyleAttributeCount += 1;
         }
       }
-      if (isPropertyNamed(node.name, "dangerouslySetInnerHTML")) {
+      if (isPropertyNamed(node.name, "dangerouslySetInnerHTML") && !isSafeJsonLdDangerouslySetInnerHtml(node)) {
         signals.dangerousHtmlCount += 1;
       }
       if (isPropertyNamed(node.name, "href", "to") && node.initializer && ts.isJsxExpression(node.initializer) && expressionContainsOpenRedirectSource(
@@ -11036,10 +11300,7 @@ function critiqueSource({
       })
     );
   }
-  const dangerousHtmlCount = Math.max(
-    astSignals.dangerousHtmlCount,
-    /dangerouslySetInnerHTML\s*=/.test(code) ? 1 : 0
-  );
+  const dangerousHtmlCount = astSignals.dangerousHtmlCount;
   const rawHtmlInjectionCount = Math.max(
     astSignals.rawHtmlInjectionCount,
     /\binnerHTML\s*=|\binsertAdjacentHTML\s*\(|\bdocument\.write\s*\(/.test(code) ? 1 : 0
@@ -11666,10 +11927,13 @@ async function critiqueFile(filePath, projectRoot) {
   });
 }
 export {
+  EVIDENCE_BUNDLE_SCHEMA_URL,
   INTERACTION_SIGNALS,
   VERIFICATION_SCHEMA_URLS,
   auditBuiltDist,
   auditProject,
+  createContractAssertions,
+  createEvidenceBundle,
   critiqueFile,
   critiqueSource,
   emptyRuntimeAudit,