businesslens 0.2.2

package/packages/report-schema/schemas/report.schema.json

@@ -0,0 +1,235 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://businesslens.dev/schemas/report.schema.json",
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "codeRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "symbol": { "type": "string", "minLength": 1 },
+        "line": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "taxonomy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "description"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "colorSlot": { "type": "integer", "minimum": 1, "maximum": 12 }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "id",
+    "title",
+    "description",
+    "tags",
+    "generatedAt",
+    "source",
+    "generator",
+    "summary",
+    "limitations",
+    "model",
+    "coverage"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "2.0.0" },
+    "id": { "$ref": "#/$defs/id" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "generatedAt": { "type": "string", "format": "date" },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repository", "repositoryUrl", "branch", "commit", "analyzedAt"],
+      "properties": {
+        "repository": { "type": "string", "minLength": 1 },
+        "repositoryUrl": { "type": "string", "format": "uri" },
+        "logoUrl": { "type": "string", "format": "uri" },
+        "branch": { "type": "string", "minLength": 1 },
+        "commit": { "type": "string", "pattern": "^[a-f0-9]{7,64}$" },
+        "analyzedAt": { "type": "string", "format": "date" }
+      }
+    },
+    "generator": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["actors", "domains", "journeys", "scenarios"],
+      "properties": {
+        "actors": { "type": "integer", "minimum": 0 },
+        "domains": { "type": "integer", "minimum": 0 },
+        "journeys": { "type": "integer", "minimum": 0 },
+        "scenarios": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "limitations": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "model": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["taxonomies", "actors", "domains", "journeys", "scenarios"],
+      "properties": {
+        "taxonomies": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["scenarioKinds"],
+          "properties": {
+            "scenarioKinds": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/taxonomy" }
+            }
+          }
+        },
+        "actors": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "name", "description"],
+            "properties": {
+              "id": { "$ref": "#/$defs/id" },
+              "name": { "type": "string", "minLength": 1 },
+              "description": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "domains": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "name", "description"],
+            "properties": {
+              "id": { "$ref": "#/$defs/id" },
+              "name": { "type": "string", "minLength": 1 },
+              "description": { "type": "string", "minLength": 1 },
+              "colorSlot": { "type": "integer", "minimum": 1, "maximum": 12 }
+            }
+          }
+        },
+        "journeys": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "summary", "domainId", "actorIds", "entryPoints", "codeRefs"],
+            "properties": {
+              "id": { "$ref": "#/$defs/id" },
+              "title": { "type": "string", "minLength": 1 },
+              "summary": { "type": "string", "minLength": 1 },
+              "domainId": { "$ref": "#/$defs/id" },
+              "actorIds": {
+                "type": "array",
+                "items": { "$ref": "#/$defs/id" },
+                "minItems": 1,
+                "uniqueItems": true
+              },
+              "entryPoints": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["type", "path"],
+                  "properties": {
+                    "type": { "type": "string", "minLength": 1 },
+                    "path": { "type": "string", "minLength": 1 }
+                  }
+                }
+              },
+              "codeRefs": {
+                "type": "array",
+                "items": { "$ref": "#/$defs/codeRef" },
+                "minItems": 1
+              }
+            }
+          }
+        },
+        "scenarios": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "journeyId", "title", "kindId", "trigger", "steps", "outcome", "edgeCases"],
+            "properties": {
+              "id": { "$ref": "#/$defs/id" },
+              "journeyId": { "$ref": "#/$defs/id" },
+              "title": { "type": "string", "minLength": 1 },
+              "kindId": { "$ref": "#/$defs/id" },
+              "trigger": { "type": "string", "minLength": 1 },
+              "steps": {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string", "minLength": 1 }
+              },
+              "outcome": { "type": "string", "minLength": 1 },
+              "edgeCases": {
+                "type": "array",
+                "items": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "method", "sourceAreas", "counts", "mapped", "unmapped", "limitations"],
+      "properties": {
+        "status": { "enum": ["complete", "partial", "draft"] },
+        "method": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "sourceAreas": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "counts": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        },
+        "mapped": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        },
+        "unmapped": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "limitations": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/packages/report-schema/types/index.ts

@@ -0,0 +1 @@
+export type * from "./report";

package/packages/report-schema/types/report.ts

@@ -0,0 +1,101 @@
+export type CodeReference = {
+  path: string;
+  symbol?: string;
+  line?: number;
+};
+
+export type TaxonomyEntry = {
+  id: string;
+  name: string;
+  description: string;
+  colorSlot?: number;
+};
+
+export type ReportActor = {
+  id: string;
+  name: string;
+  description: string;
+};
+
+export type ReportDomain = {
+  id: string;
+  name: string;
+  description: string;
+  colorSlot?: number;
+};
+
+export type ReportEntryPoint = {
+  type: string;
+  path: string;
+};
+
+export type ReportJourney = {
+  id: string;
+  title: string;
+  summary: string;
+  domainId: string;
+  actorIds: string[];
+  entryPoints: ReportEntryPoint[];
+  codeRefs: CodeReference[];
+};
+
+export type ReportScenario = {
+  id: string;
+  journeyId: string;
+  title: string;
+  kindId: string;
+  trigger: string;
+  steps: string[];
+  outcome: string;
+  edgeCases: string[];
+};
+
+export type ReportModel = {
+  taxonomies: {
+    scenarioKinds: TaxonomyEntry[];
+  };
+  actors: ReportActor[];
+  domains: ReportDomain[];
+  journeys: ReportJourney[];
+  scenarios: ReportScenario[];
+};
+
+export type ReportCoverage = {
+  status: "complete" | "partial" | "draft";
+  method: string[];
+  sourceAreas: string[];
+  counts: Record<string, number>;
+  mapped: Record<string, number>;
+  unmapped: string[];
+  limitations: string[];
+};
+
+export type BusinessLensReport = {
+  schemaVersion: "2.0.0";
+  id: string;
+  title: string;
+  description: string;
+  tags: string[];
+  generatedAt: string;
+  source: {
+    repository: string;
+    repositoryUrl: string;
+    logoUrl?: string;
+    branch: string;
+    commit: string;
+    analyzedAt: string;
+  };
+  generator: {
+    name: string;
+    version: string;
+  };
+  summary: {
+    actors: number;
+    domains: number;
+    journeys: number;
+    scenarios: number;
+  };
+  limitations: string[];
+  model: ReportModel;
+  coverage: ReportCoverage;
+};

package/packages/report-schema/validate.mjs

@@ -0,0 +1,111 @@
+import { readFile } from "node:fs/promises";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import reportSchema from "./schemas/report.schema.json" with { type: "json" };
+
+let compiledValidator;
+
+async function schemaValidator() {
+  if (compiledValidator) return compiledValidator;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  compiledValidator = ajv.compile(reportSchema);
+  return compiledValidator;
+}
+
+function duplicateIds(items) {
+  const seen = new Set();
+  const duplicates = new Set();
+  for (const item of items) {
+    if (seen.has(item.id)) duplicates.add(item.id);
+    seen.add(item.id);
+  }
+  return [...duplicates];
+}
+
+function requireReferences(ids, available, label, errors) {
+  for (const id of ids) {
+    if (!available.has(id)) errors.push(`${label} references missing id: ${id}`);
+  }
+}
+
+function semanticErrors(report) {
+  const errors = [];
+  const { model } = report;
+  if (!model) return errors;
+
+  const collections = {
+    actors: model.actors || [],
+    domains: model.domains || [],
+    journeys: model.journeys || [],
+    scenarios: model.scenarios || [],
+    scenarioKinds: model.taxonomies?.scenarioKinds || [],
+  };
+  for (const [name, items] of Object.entries(collections)) {
+    for (const id of duplicateIds(items)) errors.push(`${name} contains duplicate id: ${id}`);
+  }
+
+  const actorIds = new Set(collections.actors.map(item => item.id));
+  const domainIds = new Set(collections.domains.map(item => item.id));
+  const journeyIds = new Set(collections.journeys.map(item => item.id));
+  const scenarioKindIds = new Set(collections.scenarioKinds.map(item => item.id));
+
+  for (const journey of collections.journeys) {
+    requireReferences([journey.domainId], domainIds, `journey ${journey.id}`, errors);
+    requireReferences(journey.actorIds || [], actorIds, `journey ${journey.id}`, errors);
+    if (!collections.scenarios.some(scenario => scenario.journeyId === journey.id)) {
+      errors.push(`journey ${journey.id} has no scenarios`);
+    }
+  }
+  for (const scenario of collections.scenarios) {
+    requireReferences([scenario.journeyId], journeyIds, `scenario ${scenario.id}`, errors);
+    requireReferences([scenario.kindId], scenarioKindIds, `scenario ${scenario.id}`, errors);
+  }
+
+  const expectedSummary = {
+    actors: collections.actors.length,
+    domains: collections.domains.length,
+    journeys: collections.journeys.length,
+    scenarios: collections.scenarios.length,
+  };
+  for (const [key, value] of Object.entries(expectedSummary)) {
+    if (report.summary?.[key] !== value) {
+      errors.push(`summary ${key} is ${report.summary?.[key]}, expected ${value}`);
+    }
+    if (report.coverage?.counts?.[key] !== undefined && report.coverage.counts[key] !== value) {
+      errors.push(`coverage count ${key} is ${report.coverage.counts[key]}, expected ${value}`);
+    }
+  }
+  if (
+    report.coverage?.mapped?.journeysWithScenarios !== undefined
+    && report.coverage.mapped.journeysWithScenarios !== collections.journeys.length
+  ) {
+    errors.push(
+      `coverage mapped journeysWithScenarios is ${report.coverage.mapped.journeysWithScenarios}, expected ${collections.journeys.length}`,
+    );
+  }
+
+  return errors;
+}
+
+export async function validateReportData(report) {
+  const validate = await schemaValidator();
+  const errors = [];
+  if (!validate(report)) {
+    for (const issue of validate.errors || []) {
+      errors.push(`report${issue.instancePath || "/"} ${issue.message}`);
+    }
+  }
+  if (!errors.length) errors.push(...semanticErrors(report));
+  return errors;
+}
+
+export async function readReportFile(path) {
+  let report;
+  try {
+    report = JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    return { errors: [`report.json cannot be read: ${error.message}`] };
+  }
+  return { report, errors: await validateReportData(report) };
+}