@amityco/social-plus-vise 0.14.26 → 0.14.27

package/dist/tools/compliance.js

@@ -10,8 +10,11 @@ import { packageVersion } from "../version.js";
 import { DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID, buildDesignBrief, designContractConfirmationFromAnswers, designPreviewPath, readDesignContract, } from "./design.js";
 import { inspectProject, validateSetup } from "./project.js";
 import { readCreativeSelection } from "./creative.js";
+import { assessUxHarness, buildExperienceReport, buildUxHarness, readUxHarness, } from "./uxHarness.js";
 const complianceDirName = "sp-vise";
 const attestationsDirName = "attestations";
+const experienceReportFileName = "experience-report.json";
+const experienceSensorsFileName = "experience-sensors.json";
 const schemaVersion = 1;
 const confidenceRank = { low: 0, medium: 1, high: 2 };
 export const initComplianceTool = {
@@ -57,6 +60,26 @@ export const checkComplianceTool = {
         return textResult(await checkCompliance(stringField(args, "repoPath")));
     },
 };
+export const experienceReportTool = {
+    name: "experience_report",
+    description: "Generate the advisory dimensioned Experience Report from the current compliance, design, UX, and business-alignment evidence.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            write: {
+                type: "boolean",
+                description: "Whether to write sp-vise/experience-report.json. Defaults to true.",
+            },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        return textResult(await generateExperienceReport(stringField(args, "repoPath"), { write: optionalBooleanField(args, "write", true) }));
+    },
+};
 function answersFromInput(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         return {};
@@ -303,6 +326,9 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
     const creativeSelection = storedCreativeSelection && creativeSelectionAppliesToRequest(storedCreativeSelection, request)
         ? storedCreativeSelection
         : undefined;
+    const uxHarness = creativeSelection
+        ? await buildUxHarness({ repoPath: repoRoot, surfacePath, selection: creativeSelection, write: true })
+        : undefined;
     const intake = intakeAuditFor({
         request,
         outcome,
@@ -352,6 +378,7 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
         request,
         outcome,
         ...(creativeSelection ? { creative_selection: creativeSelectionSummary(creativeSelection) } : {}),
+        ...(uxHarness ? { ux_harness: uxHarnessSummary(uxHarness) } : {}),
         design_review: designReview,
         ...intake,
     });
@@ -380,6 +407,7 @@ export async function initCompliance(repoPath, request, surfacePath, answers = {
         rules: refs.length,
         engagement_id: engagement?.engagement_id,
         ...(creativeSelection ? { creative_selection: creativeSelectionSummary(creativeSelection) } : {}),
+        ...(uxHarness ? { ux_harness: uxHarnessSummary(uxHarness) } : {}),
         ...(compliance.design_contract && { design_contract: compliance.design_contract }),
         ...(selectedOptionalCapabilities.length > 0 && { selected_optional_capabilities: selectedOptionalCapabilities }),
         intake: {
@@ -496,6 +524,17 @@ function creativeSelectionSummary(selection) {
         },
     };
 }
+function uxHarnessSummary(harness) {
+    return {
+        status: harness.status,
+        harness_path: "sp-vise/ux-harness.json",
+        variant_id: harness.selectedVariant.id,
+        variant_title: harness.selectedVariant.title,
+        ux_pattern_ids: harness.uxPatterns.map((pattern) => pattern.id),
+        expectation_count: harness.uxPatterns.reduce((sum, pattern) => sum + pattern.expectations.length, 0),
+        advisory_only: "UX Harness guidance does not change deterministic compliance rules or exit codes in the MVP.",
+    };
+}
 function creativeSelectionAppliesToRequest(selection, request) {
     const normalizedRequest = normalizeCreativeRequest(request);
     const original = normalizeCreativeRequest(selection.source.request);
@@ -715,25 +754,133 @@ export async function checkCompliance(repoPath) {
                     : hasSelectedOptionalFailures
                         ? "selected-capability-failures"
                         : "green";
+    const exitCode = hasBlocked
+        ? 3
+        : hasDeterministicFailure
+            ? 2
+            : needsAttestation
+                ? 1
+                : hasCompletenessGap
+                    ? 5
+                    : hasSelectedOptionalFailures
+                        ? 6
+                        : 0;
+    const uxHarness = await readUxHarness(repoRoot);
+    const uxAssessment = await assessUxHarness(inspection.effectiveRoot, uxHarness, compliance.outcome);
+    const experienceReport = buildExperienceReport({
+        checkStatus: status,
+        exitCode,
+        summary,
+        designContract: compliance.design_contract,
+        uxAssessment,
+        uxHarness,
+    });
     return {
         status,
-        exitCode: hasBlocked
-            ? 3
-            : hasDeterministicFailure
-                ? 2
-                : needsAttestation
-                    ? 1
-                    : hasCompletenessGap
-                        ? 5
-                        : hasSelectedOptionalFailures
-                            ? 6
-                            : 0,
+        exitCode,
         outcome: compliance.outcome,
         surfacePath: compliance.surface?.path,
         summary,
         rules: results,
         ...(completeness && (completeness.missing.length > 0 || completeness.optedOut.length > 0 || completeness.present.length > 0) ? { completeness } : {}),
         ...(selectedOptionalCapabilities ? { selectedOptionalCapabilities } : {}),
+        uxHarness: uxAssessment,
+        experienceReport,
+    };
+}
+export async function generateExperienceReport(repoPath, options = {}) {
+    const repoRoot = path.resolve(repoPath);
+    const check = await checkCompliance(repoRoot);
+    const baseReport = check.experienceReport ?? fallbackExperienceReport(check);
+    const experienceSensors = await readExperienceSensorsReportSnapshot(repoRoot);
+    const report = experienceSensors ? { ...baseReport, experienceSensors } : baseReport;
+    const result = {
+        status: options.write === false ? "generated" : "written",
+        checkStatus: check.status,
+        checkExitCode: check.exitCode,
+        advisoryOnly: "Experience Report is advisory. Use `vise check --ci` when the caller needs compliance exit-code semantics.",
+        report,
+    };
+    if (options.write !== false) {
+        const reportPath = experienceReportPath(repoRoot);
+        await writeJson(reportPath, report);
+        result.artifact = path.join(complianceDirName, experienceReportFileName);
+    }
+    return result;
+}
+async function readExperienceSensorsReportSnapshot(repoRoot) {
+    const sidecar = await readJsonIfExists(path.join(sidecarDir(repoRoot), experienceSensorsFileName));
+    if (!sidecar) {
+        return undefined;
+    }
+    return {
+        artifact: "sp-vise/experience-sensors.json",
+        status: typeof sidecar.status === "string" ? sidecar.status : "unknown",
+        dimensions: sensorDimensionStatuses(sidecar.dimensions),
+        reviewGaps: sensorReviewGaps(sidecar.dimensions),
+        score: null,
+    };
+}
+function sensorDimensionStatuses(raw) {
+    const dimensions = objectInput(raw);
+    const result = {};
+    for (const [dimensionId, value] of Object.entries(dimensions)) {
+        const dimension = objectInput(value);
+        result[dimensionId] = typeof dimension.status === "string" ? dimension.status : "unknown";
+    }
+    return result;
+}
+function sensorReviewGaps(raw) {
+    const dimensions = objectInput(raw);
+    const gaps = [];
+    for (const [dimensionId, value] of Object.entries(dimensions)) {
+        const dimension = objectInput(value);
+        const sensors = Array.isArray(dimension.sensors) ? dimension.sensors : [];
+        for (const rawSensor of sensors) {
+            const sensor = objectInput(rawSensor);
+            const status = typeof sensor.status === "string" ? sensor.status : "unknown";
+            if (status !== "needs-review" && status !== "needs-setup") {
+                continue;
+            }
+            gaps.push({
+                dimension: typeof sensor.dimension === "string" ? sensor.dimension : dimensionId,
+                id: typeof sensor.id === "string" ? sensor.id : "unknown",
+                status,
+                title: typeof sensor.title === "string" ? sensor.title : "Unknown sensor",
+                reason: typeof sensor.reason === "string" ? sensor.reason : "No reason recorded.",
+            });
+        }
+    }
+    return gaps.slice(0, 50);
+}
+function fallbackExperienceReport(check) {
+    const uxAssessment = check.uxHarness ?? {
+        status: "absent",
+        advisoryOnly: "UX Harness guidance is advisory in the MVP. It does not change deterministic compliance exit codes until benchmark evidence justifies gating.",
+        assessedExpectations: [],
+        summary: {},
+        nextStep: "No UX Harness assessment is available for this check result.",
+    };
+    return {
+        status: "advisory",
+        dimensions: {
+            technical: {
+                status: check.status,
+                summary: check.summary,
+                exitCode: check.exitCode,
+            },
+            design: {
+                status: "absent",
+                summary: "No accepted design contract is available for this report.",
+            },
+            ux: uxAssessment,
+            businessAlignment: {
+                status: "absent",
+                summary: "No accepted creative variant is available for business-alignment reporting.",
+            },
+        },
+        score: null,
+        nextStep: "Resolve any technical check issue first, then regenerate the report. Do not publish a single Experience Score until repeated dogfood and benchmark evidence calibrates it responsibly.",
     };
 }
 export async function syncCompliance(repoPath) {
@@ -1395,6 +1542,9 @@ function attestationsDir(repoRoot) {
 function compliancePath(repoRoot) {
     return path.join(sidecarDir(repoRoot), "compliance.json");
 }
+function experienceReportPath(repoRoot) {
+    return path.join(sidecarDir(repoRoot), experienceReportFileName);
+}
 function attestationPathFor(ruleId) {
     return `${ruleId.replace(/[^a-zA-Z0-9_.-]/g, "_")}.json`;
 }