@ztothez/design-engineering 2.0.0

package/dist/src/heuristics/schema.js

@@ -0,0 +1,197 @@
+import { z } from "zod";
+const idSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,47}$/);
+const boundedText = (maximum) => z.string().trim().min(1).max(maximum);
+export const heuristicEvidenceLevelSchema = z.enum([
+    "automated",
+    "ai-assisted-expert",
+    "human-expert",
+    "representative-user",
+]);
+const heuristicEvidenceSchema = z
+    .object({
+    level: heuristicEvidenceLevelSchema,
+    source: boundedText(1_024),
+    detail: boundedText(2_048),
+    contributor: boundedText(256).optional(),
+    recordedAt: z.string().datetime({ offset: true }).optional(),
+})
+    .strict()
+    .superRefine((evidence, context) => {
+    if ((evidence.level === "human-expert" || evidence.level === "representative-user") &&
+        (!evidence.contributor || !evidence.recordedAt)) {
+        context.addIssue({
+            code: "custom",
+            message: "Human-expert and representative-user evidence require contributor and recordedAt fields.",
+        });
+    }
+});
+const heuristicTaskSchema = z
+    .object({
+    id: idSchema,
+    actor: boundedText(256),
+    scenario: boundedText(1_024),
+    successCriteria: z.array(boundedText(512)).min(1).max(20),
+    modes: z.array(idSchema).min(1).max(20),
+})
+    .strict();
+const heuristicResolutionSchema = z
+    .object({
+    rationale: boundedText(2_048),
+    decidedBy: boundedText(256),
+    decidedAt: z.string().datetime({ offset: true }),
+})
+    .strict();
+const heuristicFindingSchema = z
+    .object({
+    id: idSchema,
+    title: boundedText(160),
+    task: idSchema,
+    heuristic: z
+        .object({
+        id: idSchema,
+        name: boundedText(256),
+    })
+        .strict(),
+    location: boundedText(1_024),
+    trigger: boundedText(1_024),
+    observation: boundedText(2_048),
+    impact: boundedText(2_048),
+    evidence: z.array(heuristicEvidenceSchema).min(1).max(50),
+    severity: z.number().int().min(0).max(4),
+    confidence: z.enum(["high", "medium", "low"]),
+    status: z.enum(["open", "resolved", "accepted-risk"]),
+    remediation: boundedText(2_048),
+    validation: z
+        .object({
+        method: z.enum([
+            "runtime",
+            "accessibility",
+            "screenshot-review",
+            "expert-review",
+            "representative-user-test",
+            "analytics",
+        ]),
+        procedure: boundedText(2_048),
+    })
+        .strict(),
+    resolution: heuristicResolutionSchema.optional(),
+})
+    .strict()
+    .superRefine((finding, context) => {
+    if (finding.status === "open" && finding.resolution) {
+        context.addIssue({
+            code: "custom",
+            path: ["resolution"],
+            message: "Open findings must not contain a resolution decision.",
+        });
+    }
+    if (finding.status !== "open" && !finding.resolution) {
+        context.addIssue({
+            code: "custom",
+            path: ["resolution"],
+            message: "Resolved and accepted-risk findings require a recorded resolution decision.",
+        });
+    }
+});
+function duplicateValues(values) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            duplicates.add(value);
+        seen.add(value);
+    }
+    return [...duplicates];
+}
+export const heuristicReviewSchema = z
+    .object({
+    version: z.literal("1.0"),
+    id: idSchema,
+    product: boundedText(256),
+    target: boundedText(1_024),
+    preparedAt: z.string().datetime({ offset: true }),
+    preparedBy: z
+        .object({
+        type: z.enum(["agent", "human", "mixed"]),
+        name: boundedText(256),
+    })
+        .strict(),
+    tasks: z.array(heuristicTaskSchema).min(1).max(100),
+    findings: z.array(heuristicFindingSchema).max(1_000),
+})
+    .strict()
+    .superRefine((review, context) => {
+    for (const duplicate of duplicateValues(review.tasks.map((task) => task.id))) {
+        context.addIssue({
+            code: "custom",
+            path: ["tasks"],
+            message: `Duplicate task identifier: ${duplicate}`,
+        });
+    }
+    for (const duplicate of duplicateValues(review.findings.map((finding) => finding.id))) {
+        context.addIssue({
+            code: "custom",
+            path: ["findings"],
+            message: `Duplicate finding identifier: ${duplicate}`,
+        });
+    }
+    const taskIds = new Set(review.tasks.map((task) => task.id));
+    for (const [index, finding] of review.findings.entries()) {
+        if (!taskIds.has(finding.task)) {
+            context.addIssue({
+                code: "custom",
+                path: ["findings", index, "task"],
+                message: `Unknown task identifier: ${finding.task}`,
+            });
+        }
+    }
+});
+const acceptanceCandidateSchema = z
+    .object({
+    sourceFinding: idSchema,
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/),
+    title: boundedText(160),
+    severity: z.literal("blocker"),
+    requirement: boundedText(2_048),
+    evidence: z
+        .array(z.enum([
+        "contract",
+        "runtime",
+        "screenshot",
+        "network",
+        "accessibility",
+        "export",
+        "manual-review",
+    ]))
+        .min(1),
+    appliesToModes: z.array(z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/)).min(1),
+})
+    .strict();
+export const heuristicReviewReportSchema = z
+    .object({
+    version: z.string(),
+    generatedAt: z.string(),
+    sourcePath: z.string(),
+    reviewId: z.string(),
+    product: z.string(),
+    findings: z.array(heuristicFindingSchema),
+    acceptanceCandidates: z.array(acceptanceCandidateSchema),
+    evidenceLevels: z.object({
+        automated: z.number().int().nonnegative(),
+        aiAssistedExpert: z.number().int().nonnegative(),
+        humanExpert: z.number().int().nonnegative(),
+        representativeUser: z.number().int().nonnegative(),
+    }),
+    summary: z.object({
+        total: z.number().int().nonnegative(),
+        open: z.number().int().nonnegative(),
+        resolved: z.number().int().nonnegative(),
+        acceptedRisk: z.number().int().nonnegative(),
+        severity3: z.number().int().nonnegative(),
+        severity4: z.number().int().nonnegative(),
+        acceptanceCandidates: z.number().int().nonnegative(),
+    }),
+    requiresAcceptanceWork: z.boolean(),
+})
+    .strict();
+//# sourceMappingURL=schema.js.map

package/dist/src/heuristics/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/heuristics/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;AAC/D,MAAM,WAAW,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAE/E,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,IAAI,CAAC;IACjD,WAAW;IACX,oBAAoB;IACpB,cAAc;IACd,qBAAqB;CACtB,CAAC,CAAC;AAEH,MAAM,uBAAuB,GAAG,CAAC;KAC9B,MAAM,CAAC;IACN,KAAK,EAAE,4BAA4B;IACnC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC;IAC1B,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IACxC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC7D,CAAC;KACD,MAAM,EAAE;KACR,WAAW,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE;IACjC,IACE,CAAC,QAAQ,CAAC,KAAK,KAAK,cAAc,IAAI,QAAQ,CAAC,KAAK,KAAK,qBAAqB,CAAC;QAC/E,CAAC,CAAC,QAAQ,CAAC,WAAW,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAC/C,CAAC;QACD,OAAO,CAAC,QAAQ,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,OAAO,EACL,0FAA0F;SAC7F,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,MAAM,mBAAmB,GAAG,CAAC;KAC1B,MAAM,CAAC;IACN,EAAE,EAAE,QAAQ;IACZ,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC;IACvB,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;CACxC,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,yBAAyB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,SAAS,EAAE,WAAW,CAAC,KAAK,CAAC;IAC7B,SAAS,EAAE,WAAW,CAAC,GAAG,CAAC;IAC3B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;CACjD,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,sBAAsB,GAAG,CAAC;KAC7B,MAAM,CAAC;IACN,EAAE,EAAE,QAAQ;IACZ,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC;IACvB,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,CAAC;SACT,MAAM,CAAC;QACN,EAAE,EAAE,QAAQ;QACZ,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC;KACvB,CAAC;SACD,MAAM,EAAE;IACX,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC;IAC5B,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC;IAC/B,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC;IAC1B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxC,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC7C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;IACrD,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC;IAC/B,UAAU,EAAE,CAAC;SACV,MAAM,CAAC;QACN,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC;YACb,SAAS;YACT,eAAe;YACf,mBAAmB;YACnB,eAAe;YACf,0BAA0B;YAC1B,WAAW;SACZ,CAAC;QACF,SAAS,EAAE,WAAW,CAAC,KAAK,CAAC;KAC9B,CAAC;SACD,MAAM,EAAE;IACX,UAAU,EAAE,yBAAyB,CAAC,QAAQ,EAAE;CACjD,CAAC;KACD,MAAM,EAAE;KACR,WAAW,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;IAChC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACpD,OAAO,CAAC,QAAQ,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,YAAY,CAAC;YACpB,OAAO,EAAE,uDAAuD;SACjE,CAAC,CAAC;IACL,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACrD,OAAO,CAAC,QAAQ,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,YAAY,CAAC;YACpB,OAAO,EAAE,6EAA6E;SACvF,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,SAAS,eAAe,CAAC,MAAgB;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC;KACnC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACzB,EAAE,EAAE,QAAQ;IACZ,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC;IACzB,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC;IAC1B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACjD,UAAU,EAAE,CAAC;SACV,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC;KACvB,CAAC;SACD,MAAM,EAAE;IACX,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACnD,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;CACrD,CAAC;KACD,MAAM,EAAE;KACR,WAAW,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;IAC/B,KAAK,MAAM,SAAS,IAAI,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QAC7E,OAAO,CAAC,QAAQ,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,OAAO,CAAC;YACf,OAAO,EAAE,8BAA8B,SAAS,EAAE;SACnD,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,SAAS,IAAI,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACtF,OAAO,CAAC,QAAQ,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,UAAU,CAAC;YAClB,OAAO,EAAE,iCAAiC,SAAS,EAAE;SACtD,CAAC,CAAC;IACL,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7D,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QACzD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,OAAO,CAAC,QAAQ,CAAC;gBACf,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC;gBACjC,OAAO,EAAE,4BAA4B,OAAO,CAAC,IAAI,EAAE;aACpD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,MAAM,yBAAyB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,aAAa,EAAE,QAAQ;IACvB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,2BAA2B,CAAC;IACjD,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC;IACvB,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC9B,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC;IAC/B,QAAQ,EAAE,CAAC;SACR,KAAK,CACJ,CAAC,CAAC,IAAI,CAAC;QACL,UAAU;QACV,SAAS;QACT,YAAY;QACZ,SAAS;QACT,eAAe;QACf,QAAQ;QACR,eAAe;KAChB,CAAC,CACH;SACA,GAAG,CAAC,CAAC,CAAC;IACT,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC9E,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC;KACzC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC;IACzC,oBAAoB,EAAE,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC;IACxD,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC;QACvB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACzC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC3C,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACnD,CAAC;IACF,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACrC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACpC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACxC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACzC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QACzC,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;KACrD,CAAC;IACF,sBAAsB,EAAE,CAAC,CAAC,OAAO,EAAE;CACpC,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/src/information-design/loader.d.ts

@@ -0,0 +1,2 @@
+import { type InformationDesignContract } from "./schema.js";
+export declare function loadInformationDesignContract(path: string): Promise<InformationDesignContract>;

package/dist/src/information-design/loader.js

@@ -0,0 +1,21 @@
+import { readFile, stat } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import { parse } from "yaml";
+import { informationDesignContractSchema } from "./schema.js";
+const MAX_CONTRACT_BYTES = 2 * 1024 * 1024;
+export async function loadInformationDesignContract(path) {
+    const resolvedPath = resolve(path);
+    if (!/^\.(?:json|ya?ml)$/i.test(extname(resolvedPath))) {
+        throw new Error("Information-design contracts must end in .json, .yaml, or .yml");
+    }
+    const fileStats = await stat(resolvedPath);
+    if (!fileStats.isFile())
+        throw new Error("Information-design contract path is not a regular file");
+    if (fileStats.size > MAX_CONTRACT_BYTES) {
+        throw new Error(`Information-design contract exceeds ${MAX_CONTRACT_BYTES} bytes`);
+    }
+    const text = await readFile(resolvedPath, "utf8");
+    const content = resolvedPath.endsWith(".json") ? JSON.parse(text) : parse(text);
+    return informationDesignContractSchema.parse(content);
+}
+//# sourceMappingURL=loader.js.map

package/dist/src/information-design/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../src/information-design/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAE7B,OAAO,EAAE,+BAA+B,EAAkC,MAAM,aAAa,CAAC;AAE9F,MAAM,kBAAkB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAAC,IAAY;IAC9D,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IACnG,IAAI,SAAS,CAAC,IAAI,GAAG,kBAAkB,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,uCAAuC,kBAAkB,QAAQ,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,OAAO,GAAY,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzF,OAAO,+BAA+B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACxD,CAAC"}

package/dist/src/information-design/report.d.ts

@@ -0,0 +1,2 @@
+import type { InformationDesignReport } from "./schema.js";
+export declare function formatInformationDesignReport(report: InformationDesignReport): string;

package/dist/src/information-design/report.js

@@ -0,0 +1,27 @@
+export function formatInformationDesignReport(report) {
+    const coveredQuestions = Object.entries(report.coverage.answerFlow)
+        .filter(([, covered]) => covered)
+        .map(([question]) => question)
+        .join(", ");
+    const lines = [
+        "# ZtotheZ Information Design Validation",
+        "",
+        `- Contract: \`${report.contractId}\``,
+        `- Product: ${report.product}`,
+        `- Source: \`${report.sourcePath}\``,
+        `- Coverage: ${report.coverage.contexts} contexts, ${report.coverage.metrics} metrics, ${report.coverage.findings} findings, ${report.coverage.charts} charts, ${report.coverage.collections} collections`,
+        `- Hierarchy levels: ${report.coverage.hierarchyLevels}/8`,
+        `- Answer flow: ${coveredQuestions || "none"}`,
+        `- Findings: ${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.info} info`,
+        `- Result: ${report.passed ? "PASS" : "FAIL"}`,
+    ];
+    if (report.findings.length > 0) {
+        lines.push("", "## Findings");
+        for (const finding of report.findings) {
+            lines.push("", `### ${finding.severity.toUpperCase()}: ${finding.ruleId}`, "", `- Path: \`${finding.path}\``, `- Finding: ${finding.message}`, `- Remediation: ${finding.remediation}`);
+        }
+    }
+    lines.push("", "## Limitations", "", ...report.limitations.map((entry) => `- ${entry}`));
+    return lines.join("\n");
+}
+//# sourceMappingURL=report.js.map

package/dist/src/information-design/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/information-design/report.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,6BAA6B,CAAC,MAA+B;IAC3E,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;SAChE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC;SAC7B,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,KAAK,GAAG;QACZ,yCAAyC;QACzC,EAAE;QACF,iBAAiB,MAAM,CAAC,UAAU,IAAI;QACtC,cAAc,MAAM,CAAC,OAAO,EAAE;QAC9B,eAAe,MAAM,CAAC,UAAU,IAAI;QACpC,eAAe,MAAM,CAAC,QAAQ,CAAC,QAAQ,cAAc,MAAM,CAAC,QAAQ,CAAC,OAAO,aAAa,MAAM,CAAC,QAAQ,CAAC,QAAQ,cAAc,MAAM,CAAC,QAAQ,CAAC,MAAM,YAAY,MAAM,CAAC,QAAQ,CAAC,WAAW,cAAc;QAC1M,uBAAuB,MAAM,CAAC,QAAQ,CAAC,eAAe,IAAI;QAC1D,kBAAkB,gBAAgB,IAAI,MAAM,EAAE;QAC9C,eAAe,MAAM,CAAC,OAAO,CAAC,MAAM,YAAY,MAAM,CAAC,OAAO,CAAC,QAAQ,cAAc,MAAM,CAAC,OAAO,CAAC,IAAI,OAAO;QAC/G,aAAa,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE;KAC/C,CAAC;IAEF,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;QAC9B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CACR,EAAE,EACF,OAAO,OAAO,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,EAC1D,EAAE,EACF,aAAa,OAAO,CAAC,IAAI,IAAI,EAC7B,cAAc,OAAO,CAAC,OAAO,EAAE,EAC/B,kBAAkB,OAAO,CAAC,WAAW,EAAE,CACxC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,gBAAgB,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC;IACzF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/src/information-design/schema.d.ts

@@ -0,0 +1,370 @@
+import { z } from "zod";
+export declare const hierarchyLevelSchema: z.ZodEnum<{
+    "context-provenance": "context-provenance";
+    "primary-outcome-action": "primary-outcome-action";
+    "critical-exceptions": "critical-exceptions";
+    "health-impact-metrics": "health-impact-metrics";
+    "prioritized-findings": "prioritized-findings";
+    "operational-telemetry": "operational-telemetry";
+    "evidence-audit-trail": "evidence-audit-trail";
+    "history-exports": "history-exports";
+}>;
+export declare const answerQuestionSchema: z.ZodEnum<{
+    "identify-context": "identify-context";
+    "identify-priority": "identify-priority";
+    "explain-impact": "explain-impact";
+    "inspect-evidence": "inspect-evidence";
+    "identify-next-action": "identify-next-action";
+    "verify-success": "verify-success";
+}>;
+export declare const informationDesignContractSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    id: z.ZodString;
+    product: z.ZodString;
+    preparedAt: z.ZodString;
+    preparedBy: z.ZodObject<{
+        type: z.ZodEnum<{
+            agent: "agent";
+            human: "human";
+            mixed: "mixed";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strict>;
+    sources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            runtime: "runtime";
+            fixture: "fixture";
+            calculation: "calculation";
+            "user-input": "user-input";
+            configuration: "configuration";
+            import: "import";
+            cache: "cache";
+        }>;
+        description: z.ZodString;
+        evidence: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    freshness: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            stale: "stale";
+            unknown: "unknown";
+            "not-applicable": "not-applicable";
+            current: "current";
+        }>;
+        observedAt: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+        sourceRef: z.ZodString;
+    }, z.core.$strict>>;
+    baselines: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            target: "target";
+            benchmark: "benchmark";
+            "previous-period": "previous-period";
+            control: "control";
+        }>;
+        label: z.ZodString;
+        sourceRefs: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    destinations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        kind: z.ZodEnum<{
+            export: "export";
+            action: "action";
+            owner: "owner";
+            history: "history";
+            "drill-down": "drill-down";
+            external: "external";
+        }>;
+        target: z.ZodString;
+    }, z.core.$strict>>;
+    contexts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        environment: z.ZodString;
+        scope: z.ZodString;
+        dataDescription: z.ZodString;
+        sourceRefs: z.ZodArray<z.ZodString>;
+        freshnessRef: z.ZodString;
+        limitations: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    labelPolicies: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        maxVisibleCharacters: z.ZodNumber;
+        overflow: z.ZodEnum<{
+            wrap: "wrap";
+            "truncate-with-reveal": "truncate-with-reveal";
+        }>;
+        accessibleReveal: z.ZodBoolean;
+    }, z.core.$strict>>;
+    valuePolicies: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        states: z.ZodObject<{
+            loading: z.ZodObject<{
+                label: z.ZodString;
+                behavior: z.ZodString;
+            }, z.core.$strict>;
+            available: z.ZodObject<{
+                label: z.ZodString;
+                behavior: z.ZodString;
+            }, z.core.$strict>;
+            missing: z.ZodObject<{
+                label: z.ZodString;
+                behavior: z.ZodString;
+            }, z.core.$strict>;
+            partial: z.ZodObject<{
+                label: z.ZodString;
+                behavior: z.ZodString;
+            }, z.core.$strict>;
+            stale: z.ZodObject<{
+                label: z.ZodString;
+                behavior: z.ZodString;
+            }, z.core.$strict>;
+            error: z.ZodObject<{
+                label: z.ZodString;
+                behavior: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    evidence: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sourceRef: z.ZodString;
+        kind: z.ZodEnum<{
+            log: "log";
+            calculation: "calculation";
+            configuration: "configuration";
+            observation: "observation";
+            "user-report": "user-report";
+            document: "document";
+        }>;
+        description: z.ZodString;
+        location: z.ZodString;
+    }, z.core.$strict>>;
+    metrics: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        definition: z.ZodString;
+        formula: z.ZodString;
+        sourceRefs: z.ZodArray<z.ZodString>;
+        contextRef: z.ZodString;
+        scope: z.ZodString;
+        period: z.ZodObject<{
+            kind: z.ZodEnum<{
+                fixed: "fixed";
+                "not-applicable": "not-applicable";
+                "point-in-time": "point-in-time";
+                rolling: "rolling";
+                lifetime: "lifetime";
+            }>;
+            label: z.ZodString;
+        }, z.core.$strict>;
+        freshnessRef: z.ZodString;
+        baseline: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"available">;
+            reference: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            status: z.ZodEnum<{
+                unknown: "unknown";
+                "not-applicable": "not-applicable";
+            }>;
+            reason: z.ZodString;
+        }, z.core.$strict>], "status">;
+        drilldownRef: z.ZodString;
+        limitations: z.ZodArray<z.ZodString>;
+        supportedDecision: z.ZodObject<{
+            question: z.ZodString;
+            action: z.ZodString;
+        }, z.core.$strict>;
+        labelPolicyRef: z.ZodString;
+        valuePolicyRef: z.ZodString;
+        decorative: z.ZodBoolean;
+    }, z.core.$strict>>;
+    findings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        severity: z.ZodEnum<{
+            info: "info";
+            high: "high";
+            medium: "medium";
+            low: "low";
+            critical: "critical";
+        }>;
+        affectedEntities: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+        observation: z.ZodString;
+        evidenceRefs: z.ZodArray<z.ZodString>;
+        impact: z.ZodObject<{
+            category: z.ZodEnum<{
+                operational: "operational";
+                financial: "financial";
+                security: "security";
+                user: "user";
+                compliance: "compliance";
+                reliability: "reliability";
+            }>;
+            statement: z.ZodString;
+        }, z.core.$strict>;
+        confidence: z.ZodObject<{
+            level: z.ZodEnum<{
+                high: "high";
+                medium: "medium";
+                low: "low";
+            }>;
+            basis: z.ZodString;
+        }, z.core.$strict>;
+        remediation: z.ZodString;
+        destinationRef: z.ZodString;
+        validation: z.ZodObject<{
+            method: z.ZodString;
+            expectedSignal: z.ZodString;
+            evidenceRefs: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+        nonColorCues: z.ZodArray<z.ZodEnum<{
+            value: "value";
+            pattern: "pattern";
+            text: "text";
+            color: "color";
+            position: "position";
+            icon: "icon";
+            shape: "shape";
+        }>>;
+    }, z.core.$strict>>;
+    charts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        purpose: z.ZodString;
+        metricRefs: z.ZodArray<z.ZodString>;
+        supportedDecision: z.ZodString;
+        destinationRef: z.ZodString;
+        decorative: z.ZodBoolean;
+        labeling: z.ZodObject<{
+            titleVisible: z.ZodBoolean;
+            valuesVisible: z.ZodBoolean;
+            legendVisible: z.ZodBoolean;
+            legendReason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        alternative: z.ZodObject<{
+            kind: z.ZodEnum<{
+                text: "text";
+                table: "table";
+            }>;
+            destinationRef: z.ZodString;
+        }, z.core.$strict>;
+        valuePolicyRef: z.ZodString;
+    }, z.core.$strict>>;
+    collections: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        entity: z.ZodString;
+        estimatedMaximumItems: z.ZodNumber;
+        strategy: z.ZodEnum<{
+            bounded: "bounded";
+            pagination: "pagination";
+            virtualization: "virtualization";
+            grouping: "grouping";
+        }>;
+        search: z.ZodBoolean;
+        filter: z.ZodBoolean;
+        sort: z.ZodBoolean;
+        emptyState: z.ZodString;
+        partialState: z.ZodString;
+        staleState: z.ZodString;
+        labelPolicyRef: z.ZodString;
+    }, z.core.$strict>>;
+    hierarchy: z.ZodArray<z.ZodObject<{
+        level: z.ZodEnum<{
+            "context-provenance": "context-provenance";
+            "primary-outcome-action": "primary-outcome-action";
+            "critical-exceptions": "critical-exceptions";
+            "health-impact-metrics": "health-impact-metrics";
+            "prioritized-findings": "prioritized-findings";
+            "operational-telemetry": "operational-telemetry";
+            "evidence-audit-trail": "evidence-audit-trail";
+            "history-exports": "history-exports";
+        }>;
+        order: z.ZodNumber;
+        contextRefs: z.ZodArray<z.ZodString>;
+        metricRefs: z.ZodArray<z.ZodString>;
+        findingRefs: z.ZodArray<z.ZodString>;
+        chartRefs: z.ZodArray<z.ZodString>;
+        destinationRefs: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        question: z.ZodEnum<{
+            "identify-context": "identify-context";
+            "identify-priority": "identify-priority";
+            "explain-impact": "explain-impact";
+            "inspect-evidence": "inspect-evidence";
+            "identify-next-action": "identify-next-action";
+            "verify-success": "verify-success";
+        }>;
+        prompt: z.ZodString;
+        contextRefs: z.ZodArray<z.ZodString>;
+        metricRefs: z.ZodArray<z.ZodString>;
+        findingRefs: z.ZodArray<z.ZodString>;
+        destinationRefs: z.ZodArray<z.ZodString>;
+        expectedAnswer: z.ZodString;
+        nonColorRequired: z.ZodLiteral<true>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const informationDesignFindingSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>;
+    path: z.ZodString;
+    message: z.ZodString;
+    remediation: z.ZodString;
+}, z.core.$strict>;
+export declare const informationDesignReportSchema: z.ZodObject<{
+    version: z.ZodString;
+    generatedAt: z.ZodString;
+    sourcePath: z.ZodString;
+    contractId: z.ZodString;
+    product: z.ZodString;
+    findings: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        severity: z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            info: "info";
+        }>;
+        path: z.ZodString;
+        message: z.ZodString;
+        remediation: z.ZodString;
+    }, z.core.$strict>>;
+    coverage: z.ZodObject<{
+        sources: z.ZodNumber;
+        contexts: z.ZodNumber;
+        metrics: z.ZodNumber;
+        findings: z.ZodNumber;
+        charts: z.ZodNumber;
+        collections: z.ZodNumber;
+        hierarchyLevels: z.ZodNumber;
+        answerFlow: z.ZodRecord<z.ZodEnum<{
+            "identify-context": "identify-context";
+            "identify-priority": "identify-priority";
+            "explain-impact": "explain-impact";
+            "inspect-evidence": "inspect-evidence";
+            "identify-next-action": "identify-next-action";
+            "verify-success": "verify-success";
+        }>, z.ZodBoolean>;
+    }, z.core.$strict>;
+    summary: z.ZodObject<{
+        errors: z.ZodNumber;
+        warnings: z.ZodNumber;
+        info: z.ZodNumber;
+    }, z.core.$strict>;
+    passed: z.ZodBoolean;
+    limitations: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type InformationDesignContract = z.infer<typeof informationDesignContractSchema>;
+export type InformationDesignFinding = z.infer<typeof informationDesignFindingSchema>;
+export type InformationDesignReport = z.infer<typeof informationDesignReportSchema>;