@decantr/verifier 1.0.2 → 1.0.4

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { EssenceFile } from '@decantr/essence-spec';
 import { ReviewExecutionPack } from '@decantr/core';
+import { EssenceFile } from '@decantr/essence-spec';
 
 interface RuntimeAudit {
     distPresent: boolean;
@@ -53,6 +53,68 @@ interface BuiltDistAuditOptions {
 declare function emptyRuntimeAudit(failures?: string[]): RuntimeAudit;
 declare function auditBuiltDist(projectRoot: string, options?: BuiltDistAuditOptions): Promise<RuntimeAudit>;
 
+/**
+ * v2.1 Tier C4 — Experiential interaction verifier.
+ *
+ * Scans generated source files for evidence that declared `interactions[]`
+ * (from pattern.v2.json) are actually implemented. This is the enforcement
+ * layer that converts the structural-vs-experiential gap (user audit:
+ * "experiential reads like guidance, nothing fails when I skip it") into
+ * a hard-edged structural check, on par with the other guard rules.
+ *
+ * Scanner is intentionally simple: regex/substring signal matching, not
+ * full AST analysis. Each interaction defines one or more signals that
+ * MUST appear somewhere in the project source. A signal is either:
+ *   - a CSS class name (e.g., `d-pulse` for status-pulse)
+ *   - a regex (e.g., /onPointer(Down|Move)/ for drag-nodes)
+ * If no signal matches, the interaction is marked as "missing" and the
+ * guard rule emits a violation.
+ *
+ * Why grep, not AST: scaffolds use diverse file shapes (JSX, MDX, plain
+ * HTML in marketing sites). A regex scan handles all of them; a real AST
+ * matcher would need framework-specific parsers per blueprint kind. Grep
+ * gets us 80% of the value at 10% of the complexity.
+ */
+/** Either a literal substring or a regex pattern. */
+type InteractionSignal = string | RegExp;
+interface InteractionRequirement {
+    /** The interaction name from pattern.v2.json's enum. */
+    interaction: string;
+    /**
+     * One or more signals; ANY match satisfies the requirement. Allows
+     * authors flexibility — e.g., either `d-pulse` class OR a custom
+     * `@keyframes pulse` declaration both count for status-pulse.
+     */
+    signals: InteractionSignal[];
+    /** Human-readable suggestion when signals don't match. */
+    suggestion: string;
+}
+/**
+ * Mapping from canonical interaction name (pattern.v2.json enum) to its
+ * required signals. Add entries as new interactions are introduced.
+ */
+declare const INTERACTION_SIGNALS: Record<string, InteractionRequirement>;
+interface InteractionMissingFinding {
+    interaction: string;
+    suggestion: string;
+}
+/**
+ * Scan a source-tree map (file path → file contents) for evidence of each
+ * declared interaction. Returns a list of interactions whose signals were
+ * not found anywhere in the source.
+ *
+ * @param interactions Declared interactions from one or more page packs.
+ *                     Duplicates collapse to a single check.
+ * @param sources Map of file path → file contents to scan.
+ * @returns List of interactions that have no matching signal.
+ */
+declare function verifyInteractionsInSource(interactions: string[], sources: Map<string, string>): InteractionMissingFinding[];
+/**
+ * Convenience: list every recognized interaction name. Useful for
+ * documentation, validation, and surfacing the canonical enum.
+ */
+declare function listKnownInteractions(): string[];
+
 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";
@@ -235,4 +297,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, 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 };
+export { type BuiltDistAuditOptions, type CritiqueSourceInput, type FileCritiqueReport, INTERACTION_SIGNALS, type InteractionMissingFinding, type InteractionRequirement, type InteractionSignal, 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, listKnownInteractions, verifyInteractionsInSource };