@topogram/cli 0.3.63 → 0.3.65

package/src/generator/context/shared/summaries.js

@@ -0,0 +1,263 @@
+import {
+  defaultOwnershipBoundary,
+  reviewBoundaryForCapability as reviewBoundaryForCapabilityPolicy,
+  reviewBoundaryForEntity as reviewBoundaryForEntityPolicy,
+  reviewBoundaryForJourneyDoc as reviewBoundaryForJourneyDocPolicy,
+  reviewBoundaryForProjection as reviewBoundaryForProjectionPolicy,
+  reviewBoundaryForWorkflowDoc as reviewBoundaryForWorkflowDocPolicy
+} from "../../../policy/review-boundaries.js";
+import { docIds, refIds, stableSortedStrings } from "./primitives.js";
+
+/**
+ * @param {import("./types.d.ts").ContextField} field
+ * @returns {any}
+ */
+export function summarizeField(field) {
+  return {
+    name: field.name || null,
+    type: field.fieldType || null,
+    requiredness: field.requiredness || null,
+    defaultValue: field.defaultValue ?? null
+  };
+}
+
+/**
+ * @param {import("./types.d.ts").ContextProjection} projection
+ * @returns {any}
+ */
+export function summarizeProjection(projection) {
+  return {
+    id: projection.id,
+    kind: projection.kind,
+    name: projection.name || projection.id,
+    description: projection.description || null,
+    type: projection.type || null,
+    realizes: refIds(projection.realizes),
+    outputs: stableSortedStrings(projection.outputs || []),
+    uiScreens: stableSortedStrings((projection.uiScreens || []).map(/** @param {any} screen */ (screen) => screen.id)),
+    widgetBindings: stableSortedStrings((projection.widgetBindings || []).map(/** @param {any} entry */ (entry) => entry.widget?.id).filter(Boolean)),
+    dbTables: stableSortedStrings((projection.dbTables || []).map(/** @param {any} table */ (table) => table.table || table.entity?.id)),
+    httpCapabilities: stableSortedStrings((projection.http || []).map(/** @param {any} entry */ (entry) => entry.capability?.id)),
+    reviewBoundary: reviewBoundaryForProjectionPolicy(projection),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+/**
+ * @param {import("./types.d.ts").ContextStatement} rule
+ * @returns {any}
+ */
+export function summarizeRule(rule) {
+  return {
+    id: rule.id,
+    kind: rule.kind,
+    name: rule.name || rule.id,
+    description: rule.description || null,
+    appliesTo: refIds(rule.appliesTo),
+    actors: refIds(rule.actors),
+    roles: refIds(rule.roles),
+    severity: rule.severity || null,
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+/**
+ * @param {import("./types.d.ts").ContextStatement} verification
+ * @returns {any}
+ */
+export function summarizeVerification(verification) {
+  return {
+    id: verification.id,
+    kind: verification.kind,
+    name: verification.name || verification.id,
+    description: verification.description || null,
+    method: verification.method || null,
+    validates: refIds(verification.validates),
+    scenarios: stableSortedStrings(verification.scenarios || []),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+/**
+ * @param {import("./types.d.ts").ContextDoc} doc
+ * @returns {any}
+ */
+export function summarizeJourneyDoc(doc) {
+  return {
+    id: doc.id,
+    kind: doc.kind,
+    title: doc.title || doc.id,
+    summary: doc.summary || null,
+    relatedCapabilities: stableSortedStrings(doc.relatedCapabilities || []),
+    relatedWorkflows: stableSortedStrings(doc.relatedWorkflows || []),
+    relatedProjections: stableSortedStrings(doc.relatedProjections || []),
+    reviewRequired: Boolean(doc.reviewRequired),
+    reviewBoundary: doc.kind === "workflow" ? reviewBoundaryForWorkflowDocPolicy(doc) : reviewBoundaryForJourneyDocPolicy(doc),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+/**
+ * @param {import("./types.d.ts").ContextStatement} statement
+ * @returns {any}
+ */
+export function summarizeComponent(statement) {
+  return {
+    id: statement.id,
+    kind: statement.kind,
+    name: statement.name || statement.id,
+    description: statement.description || null,
+    category: statement.category || null,
+    version: statement.version || null,
+    status: statement.status || null,
+    props: (statement.props || []).map(/** @param {any} prop */ (prop) => ({
+      name: prop.name ?? null,
+      type: prop.fieldType ?? null,
+      requiredness: prop.requiredness ?? null,
+      defaultValue: prop.defaultValue ?? null
+    })),
+    events: (statement.events || []).map(/** @param {any} event */ (event) => ({
+      id: event.id ?? null,
+      shape: event.shape?.id ?? null
+    })),
+    slots: (statement.slots || []).map(/** @param {any} slot */ (slot) => ({
+      id: slot.id ?? null,
+      description: slot.description ?? null
+    })),
+    behavior: stableSortedStrings(statement.behavior || []),
+    behaviors: (statement.behaviors || []).map(/** @param {any} behavior */ (behavior) => ({
+      kind: behavior.kind || null,
+      directives: behavior.directives || {},
+      source: behavior.source || null
+    })),
+    patterns: stableSortedStrings(statement.patterns || []),
+    regions: stableSortedStrings(statement.regions || []),
+    approvals: stableSortedStrings(statement.approvals || []),
+    lookups: refIds(statement.lookups),
+    dependencies: refIds(statement.dependencies),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
+/**
+ * @param {import("./types.d.ts").ContextStatement} statement
+ * @returns {any}
+ */
+export function summarizeStatement(statement) {
+  switch (statement.kind) {
+    case "entity":
+      return {
+        id: statement.id,
+        kind: statement.kind,
+        name: statement.name || statement.id,
+        description: statement.description || null,
+        fields: (statement.fields || []).map(summarizeField),
+        relations: (statement.relations || []).map(/** @param {any} relation */ (relation) => ({
+          type: relation.type || null,
+          sourceField: relation.sourceField || null,
+          target: relation.target?.id || null
+        })),
+        keys: stableSortedStrings((statement.keys || []).map(/** @param {any} key */ (key) => key.name)),
+        reviewBoundary: reviewBoundaryForEntityPolicy(statement),
+        ownership_boundary: defaultOwnershipBoundary()
+      };
+    case "widget":
+      return summarizeComponent(statement);
+    case "shape":
+      return {
+        id: statement.id,
+        kind: statement.kind,
+        name: statement.name || statement.id,
+        description: statement.description || null,
+        derivedFrom: refIds(statement.derivedFrom),
+        include: stableSortedStrings(statement.include || []),
+        exclude: stableSortedStrings(statement.exclude || []),
+        fields: (statement.projectedFields || statement.fields || []).map(summarizeField),
+        ownership_boundary: defaultOwnershipBoundary()
+      };
+    case "capability":
+      return {
+        id: statement.id,
+        kind: statement.kind,
+        name: statement.name || statement.id,
+        description: statement.description || null,
+        actors: refIds(statement.actors),
+        roles: refIds(statement.roles),
+        reads: refIds(statement.reads),
+        creates: refIds(statement.creates),
+        updates: refIds(statement.updates),
+        deletes: refIds(statement.deletes),
+        input: refIds(statement.input),
+        output: refIds(statement.output),
+        reviewBoundary: reviewBoundaryForCapabilityPolicy(statement),
+        ownership_boundary: defaultOwnershipBoundary()
+      };
+    case "rule":
+      return summarizeRule(statement);
+    case "projection":
+      return summarizeProjection(statement);
+    case "verification":
+      return summarizeVerification(statement);
+    case "enum":
+      return {
+        id: statement.id,
+        kind: statement.kind,
+        name: statement.name || statement.id,
+        values: stableSortedStrings(statement.values || []),
+        ownership_boundary: defaultOwnershipBoundary()
+      };
+    case "actor":
+    case "role":
+      return {
+        id: statement.id,
+        kind: statement.kind,
+        name: statement.name || statement.id,
+        description: statement.description || null,
+        ownership_boundary: defaultOwnershipBoundary()
+      };
+    default:
+      return {
+        id: statement.id,
+        kind: statement.kind,
+        name: statement.name || statement.id,
+        description: statement.description || null,
+        ownership_boundary: defaultOwnershipBoundary()
+      };
+  }
+}
+
+/**
+ * @param {import("./types.d.ts").ContextCapability} capability
+ * @returns {any}
+ */
+export function reviewBoundaryForCapability(capability) {
+  return reviewBoundaryForCapabilityPolicy(capability);
+}
+
+/**
+ * @param {import("./types.d.ts").ContextProjection} projection
+ * @returns {any}
+ */
+export function reviewBoundaryForProjection(projection) {
+  return reviewBoundaryForProjectionPolicy(projection);
+}
+
+/**
+ * @param {import("./types.d.ts").ContextEntity} entity
+ * @returns {any}
+ */
+export function reviewBoundaryForEntity(entity) {
+  return reviewBoundaryForEntityPolicy(entity);
+}
+
+/**
+ * @param {import("./types.d.ts").ContextGraph} graph
+ * @returns {any}
+ */
+export function graphCounts(graph) {
+  return Object.fromEntries(
+    Object.entries(graph.byKind || {})
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([kind, statements]) => [kind, statements.length])
+  );
+}

package/src/generator/context/shared/types.d.ts

@@ -0,0 +1,207 @@
+export type ContextReference = {
+  id?: string;
+  kind?: string;
+  target?: {
+    id?: string;
+    kind?: string;
+  };
+  [key: string]: any;
+};
+
+export type ContextField = {
+  name?: string;
+  fieldType?: string;
+  requiredness?: string;
+  defaultValue?: unknown;
+  [key: string]: any;
+};
+
+export type ContextProjection = ContextStatement & {
+  type?: string;
+  realizes?: ContextReference[];
+  outputs?: string[];
+  uiScreens?: any[];
+  uiRoutes?: any[];
+  uiScreenRegions?: any[];
+  uiCollections?: any[];
+  uiActions?: any[];
+  uiVisibility?: any[];
+  uiLookups?: any[];
+  uiDesign?: any[];
+  widgetBindings?: ContextWidgetUsage[];
+  dbTables?: any[];
+  dbColumns?: any[];
+  dbRelations?: any[];
+  http?: any[];
+  httpResponses?: any[];
+};
+
+export type ContextCapability = ContextStatement & {
+  actors?: ContextReference[];
+  roles?: ContextReference[];
+  reads?: ContextReference[];
+  creates?: ContextReference[];
+  updates?: ContextReference[];
+  deletes?: ContextReference[];
+  input?: ContextReference[];
+  output?: ContextReference[];
+};
+
+export type ContextEntity = ContextStatement & {
+  fields?: ContextField[];
+  relations?: any[];
+  keys?: any[];
+};
+
+export type ContextShape = ContextStatement & {
+  derivedFrom?: ContextReference[];
+  include?: string[];
+  exclude?: string[];
+  fields?: ContextField[];
+  projectedFields?: ContextField[];
+};
+
+export type ContextWidget = ContextStatement & {
+  category?: string;
+  version?: string;
+  status?: string;
+  widgetContract?: {
+    patterns?: string[];
+    regions?: string[];
+    behaviors?: any[];
+    [key: string]: any;
+  };
+  props?: ContextField[];
+  events?: any[];
+  slots?: any[];
+  behavior?: string[];
+  behaviors?: any[];
+  patterns?: string[];
+  regions?: string[];
+  approvals?: string[];
+  lookups?: ContextReference[];
+  dependencies?: ContextReference[];
+};
+
+export type ContextWidgetUsage = {
+  widget?: ContextReference;
+  screenId?: string;
+  region?: string;
+  dataBindings?: any[];
+  eventBindings?: any[];
+  [key: string]: any;
+};
+
+export type ContextStatement = {
+  id: string;
+  kind?: string;
+  name?: string;
+  description?: string;
+  loc?: {
+    file?: string;
+  };
+  resolvedDomain?: {
+    id?: string;
+  };
+  [key: string]: any;
+};
+
+export type ContextDoc = {
+  id: string;
+  kind?: string;
+  title?: string;
+  loc?: {
+    file?: string;
+  };
+  metadata?: any;
+  relatedCapabilities?: string[];
+  relatedWorkflows?: string[];
+  [key: string]: any;
+};
+
+export type ContextGraph = {
+  root?: string;
+  workspaceRoot?: string;
+  repoRoot?: string;
+  statements: ContextStatement[];
+  docs: ContextDoc[];
+  byKind: Record<string, any[]>;
+  [key: string]: any;
+};
+
+export type ContextSelectionOptions = {
+  capabilityId?: string | null;
+  workflowId?: string | null;
+  projectionId?: string | null;
+  widgetId?: string | null;
+  componentId?: string | null;
+  entityId?: string | null;
+  journeyId?: string | null;
+  surfaceId?: string | null;
+  domainId?: string | null;
+  pitchId?: string | null;
+  requirementId?: string | null;
+  acceptanceId?: string | null;
+  taskId?: string | null;
+  bugId?: string | null;
+  documentId?: string | null;
+  [key: string]: any;
+};
+
+export type ContextSelection = {
+  kind: string;
+  id: string;
+};
+
+export type VerificationTargets = {
+  verification_ids?: string[];
+  generated_checks?: string[];
+  maintained_app_checks?: string[];
+  rationale?: string | null;
+  [key: string]: any;
+};
+
+export type MaintainedSeam = {
+  seam_id?: string;
+  label?: string;
+  maintained_modules?: string[];
+  emitted_dependencies?: string[];
+  [key: string]: any;
+};
+
+export type MaintainedOutput = {
+  output_id?: string;
+  label?: string;
+  kind?: string;
+  maintained_files_in_scope?: string[];
+  seams: MaintainedSeam[];
+  proof_stories: any[];
+  [key: string]: any;
+};
+
+export type MaintainedProofStory = {
+  classification?: string;
+  maintainedFiles?: string[];
+  emittedDependencies?: string[];
+  humanOwnedSeams?: string[];
+  seamFamilyId?: string | null;
+  seamFamilyLabel?: string | null;
+  relativePath?: string;
+  absolutePath?: string;
+  reviewBoundary?: any;
+  ownership_boundary?: any;
+  [key: string]: any;
+};
+
+export type MaintainedBoundaryOptions = {
+  proofStories?: MaintainedProofStory[];
+  verificationTargets?: VerificationTargets | null;
+  graph?: ContextGraph | null;
+  [key: string]: any;
+};
+
+export type VerificationTargetOptions = {
+  rationale?: string | null;
+  includeMaintainedApp?: boolean;
+  [key: string]: any;
+};

package/src/generator/context/shared.d.ts

@@ -0,0 +1,44 @@
+export function recommendedVerificationTargets(...args: any[]): any;
+export function acceptanceCriterionById(...args: any[]): any;
+export function bugById(...args: any[]): any;
+export function buildDefaultWriteScope(...args: any[]): any;
+export function documentById(...args: any[]): any;
+export function domainById(...args: any[]): any;
+export function ensureContextSelection(...args: any[]): any;
+export function getJourneyDoc(...args: any[]): any;
+export function getStatement(...args: any[]): any;
+export function getWorkflowDoc(...args: any[]): any;
+export function pitchById(...args: any[]): any;
+export function relatedCapabilitiesForEntity(...args: any[]): any;
+export function relatedCapabilitiesForProjection(...args: any[]): any;
+export function relatedEntitiesForDomain(...args: any[]): any;
+export function relatedEntitiesForProjection(...args: any[]): any;
+export function relatedJourneysForCapability(...args: any[]): any;
+export function relatedProjectionsForCapability(...args: any[]): any;
+export function relatedProjectionsForDomain(...args: any[]): any;
+export function relatedProjectionsForEntity(...args: any[]): any;
+export function relatedProjectionsForWidget(...args: any[]): any;
+export function relatedRulesForDomain(...args: any[]): any;
+export function relatedRulesForTarget(...args: any[]): any;
+export function relatedShapesForEntity(...args: any[]): any;
+export function relatedShapesForProjection(...args: any[]): any;
+export function relatedShapesForWidget(...args: any[]): any;
+export function relatedVerificationsForDomain(...args: any[]): any;
+export function relatedWidgetsForProjection(...args: any[]): any;
+export function relatedWorkflowDocsForCapability(...args: any[]): any;
+export function requirementById(...args: any[]): any;
+export function summarizeAcceptanceCriterion(...args: any[]): any;
+export function summarizeBug(...args: any[]): any;
+export function summarizeById(...args: any[]): any;
+export function summarizeDocsByIds(...args: any[]): any;
+export function summarizeDocument(...args: any[]): any;
+export function summarizeDomain(...args: any[]): any;
+export function summarizePitch(...args: any[]): any;
+export function summarizeProjection(...args: any[]): any;
+export function summarizeRequirement(...args: any[]): any;
+export function summarizeStatementsByIds(...args: any[]): any;
+export function summarizeTask(...args: any[]): any;
+export function taskById(...args: any[]): any;
+export function verificationIdsForTarget(...args: any[]): any;
+export function widgetById(...args: any[]): any;
+export function buildLocalMaintainedBoundaryArtifact(...args: any[]): any;