@frontera-sdk/cli 0.1.0 → 1.43.5

package/src/blueprint/diff.ts

@@ -0,0 +1,223 @@
+import { toFiles } from './projection'
+import {
+  ARTIFACT_KINDS,
+  type ArtifactKind,
+  type AuthoredFile,
+  type DefinitionBundle,
+} from './model'
+
+/**
+ * The plan: what the files say that the live draft does not, expressed as typed
+ * operations the executor dispatches one by one.
+ *
+ * Comparison is by `apiName`, the only key both sides share — the files carry no ids
+ * (see `model.ts`). It runs over PARSED structures rather than serialised text, so
+ * reformatting a YAML file, reordering its keys or requoting a string never shows up
+ * as a change.
+ */
+
+export type OperationKind = 'create' | 'update' | 'delete'
+
+export interface ModelOperation {
+  operation: OperationKind
+  kind: ArtifactKind
+  apiName: string
+  /** The authored document, for a create or an update. Absent on a delete. */
+  document?: Record<string, unknown>
+  /** One line of human-readable detail, e.g. `+1 property (tier)`. */
+  detail?: string
+  /**
+   * The artifact as the draft currently has it, on an update.
+   *
+   * Carried on the operation because the executor has to know what ALREADY agrees:
+   * the service refuses a command that would change nothing, so sending an unchanged
+   * field is not merely wasteful, it fails the run.
+   */
+  liveDocument?: Record<string, unknown>
+}
+
+export interface BindingDrift {
+  objectApiName: string
+  datasetRevisionId: string
+  pinnedDigest: string
+}
+
+export interface Plan {
+  /** The draft revision this plan was computed against. */
+  revision: number
+  operations: ModelOperation[]
+  /** Artifacts in the draft but absent from the tree. Applied only with `--prune`. */
+  prunes: ModelOperation[]
+  drift: BindingDrift[]
+  unchanged: number
+}
+
+export function isEmpty(plan: Plan): boolean {
+  return plan.operations.length === 0 && plan.prunes.length === 0
+}
+
+/**
+ * Does the live artifact already say everything the file declares?
+ *
+ * A SUBSET comparison, not an equality one, and this is the difference between a
+ * tool that converges and one that reports a change forever. The service normalises
+ * on creation: it derives each property's `baseType` from the pinned column, decides
+ * `unique` and `uniqueBasis` from what the source vouches for (ADR 0009 decision 5),
+ * and defaults `status` and `visibility`. None of that is in a hand-authored file,
+ * and none of it should be — a file that had to restate every derived value would
+ * have to be regenerated after every apply.
+ *
+ * So a field the file does not mention is a field the file has no opinion about.
+ * What that costs is stated rather than hidden: DELETING a line from a file is not a
+ * change this can see. Removing a property is done by removing it from
+ * `properties`, which IS seen, because the property set is compared by name below.
+ *
+ * Exported because the EXECUTOR must answer the same question with the same predicate:
+ * the plan decides an artifact changed with this, so the executor deciding WHICH field
+ * changed has to agree. A second comparison there — a `JSON.stringify` equality, say —
+ * disagrees about key order and about fields the file omits, and refuses a run naming a
+ * field the plan never called changed.
+ */
+export function satisfies(local: unknown, live: unknown, key?: string): boolean {
+  // `backing` is owned by `bind`, which travels the probe and the contract-change
+  // gate. Letting it into the plan would mean `apply` silently rebinding a type
+  // because somebody edited a column name in a file.
+  if (key === 'backing') return true
+
+  if (Array.isArray(local)) {
+    if (!Array.isArray(live)) return false
+    const named = local.every((entry) => isNamed(entry))
+    if (!named) return canonical(local) === canonical(live)
+    // Compared by apiName, so reordering `properties:` is not a change and adding
+    // or removing one is.
+    const liveByName = new Map(
+      live.filter(isNamed).map((entry) => [entry.apiName, entry as Record<string, unknown>]),
+    )
+    const localNames = local.filter(isNamed).map((entry) => entry.apiName)
+    if (localNames.length !== liveByName.size) return false
+    return localNames.every((name) => {
+      const counterpart = liveByName.get(name)
+      return counterpart !== undefined
+        && satisfies(local.find((entry) => isNamed(entry) && entry.apiName === name), counterpart)
+    })
+  }
+
+  if (local && typeof local === 'object') {
+    if (!live || typeof live !== 'object') return false
+    return Object.entries(local as Record<string, unknown>).every(([field, value]) =>
+      satisfies(value, (live as Record<string, unknown>)[field], field))
+  }
+
+  return canonical(local) === canonical(live)
+}
+
+function isNamed(value: unknown): value is { apiName: string } {
+  return Boolean(value) && typeof value === 'object'
+    && typeof (value as { apiName?: unknown }).apiName === 'string'
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`)
+    return `{${entries.join(',')}}`
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+function propertyNames(document: Record<string, unknown>): string[] {
+  const properties = document.properties
+  if (!Array.isArray(properties)) return []
+  return properties
+    .map((property) => (property as { apiName?: unknown }).apiName)
+    .filter((name): name is string => typeof name === 'string')
+}
+
+/** `+1 property (tier)` / `-1 property (legacyCode)`, or a bare field count. */
+function describeUpdate(local: Record<string, unknown>, live: Record<string, unknown>): string {
+  const before = new Set(propertyNames(live))
+  const after = propertyNames(local)
+  const added = after.filter((name) => !before.has(name))
+  const removed = [...before].filter((name) => !after.includes(name))
+  const parts: string[] = []
+  if (added.length) parts.push(`+${added.length} propert${added.length === 1 ? 'y' : 'ies'} (${added.join(', ')})`)
+  if (removed.length) parts.push(`-${removed.length} propert${removed.length === 1 ? 'y' : 'ies'} (${removed.join(', ')})`)
+  return parts.length ? parts.join(', ') : 'fields changed'
+}
+
+export function diff(
+  localFiles: AuthoredFile[],
+  live: DefinitionBundle,
+  revision: number,
+): Plan {
+  const liveModel = toFiles(live)
+  const liveByKey = new Map(liveModel.files.map((file) => [`${file.kind}:${file.apiName}`, file]))
+  const localByKey = new Map(localFiles.map((file) => [`${file.kind}:${file.apiName}`, file]))
+
+  const operations: ModelOperation[] = []
+  const prunes: ModelOperation[] = []
+  let unchanged = 0
+
+  // Fixed kind order so the plan reads the same way every run, and so creations of
+  // a kind that others reference come first within the listing.
+  for (const kind of ARTIFACT_KINDS) {
+    for (const file of localFiles.filter((candidate) => candidate.kind === kind)) {
+      const key = `${kind}:${file.apiName}`
+      const existing = liveByKey.get(key)
+      if (!existing) {
+        operations.push({
+          operation: 'create',
+          kind,
+          apiName: file.apiName,
+          document: file.document,
+          ...(kind === 'object-type'
+            ? { detail: `${propertyNames(file.document).length} properties` }
+            : {}),
+        })
+        continue
+      }
+      if (satisfies(file.document, existing.document)) {
+        unchanged += 1
+        continue
+      }
+      operations.push({
+        operation: 'update',
+        kind,
+        apiName: file.apiName,
+        document: file.document,
+        liveDocument: existing.document,
+        detail: describeUpdate(file.document, existing.document),
+      })
+    }
+    for (const file of liveModel.files.filter((candidate) => candidate.kind === kind)) {
+      if (localByKey.has(`${kind}:${file.apiName}`)) continue
+      prunes.push({ operation: 'delete', kind, apiName: file.apiName })
+    }
+  }
+
+  return { revision, operations, prunes, drift: driftOf(live), unchanged }
+}
+
+/**
+ * Bound object types whose pinned schema digest can be checked against the dataset's
+ * current revision. The comparison itself needs the dataset read, so this only
+ * collects the pins; `plan` fills in the verdict.
+ */
+export function driftOf(live: DefinitionBundle): BindingDrift[] {
+  const pins: BindingDrift[] = []
+  for (const object of live.objects) {
+    const mapping = object.governance.sourceMappings[0] as
+      | { datasetRevisionId?: string; datasetSchemaDigest?: string }
+      | undefined
+    if (!mapping?.datasetRevisionId || !mapping.datasetSchemaDigest) continue
+    pins.push({
+      objectApiName: object.apiName,
+      datasetRevisionId: mapping.datasetRevisionId,
+      pinnedDigest: mapping.datasetSchemaDigest,
+    })
+  }
+  return pins
+}

package/src/blueprint/model.ts

@@ -0,0 +1,227 @@
+/**
+ * The two shapes this package moves between: the DEFINITION BUNDLE the service
+ * speaks, and the AUTHORED MODEL a person keeps in files.
+ *
+ * They differ in exactly one way, and every rule in `projection.ts` follows from it:
+ * the bundle is UUID-keyed, and the files carry no UUID at all. The service mints
+ * every identifier — object ids, property ids, and a source system for an
+ * organization's first object type — so a UUID written into a shared tree would be
+ * correct in the deployment that minted it and wrong in every other. `apiName` is
+ * the only key that means the same thing everywhere.
+ *
+ * The bundle types here are deliberately loose where the CLI does not reason about
+ * the contents. `unknown` on a field means "carried through untouched", which is
+ * what a projection must do with anything it does not itself interpret — the
+ * alternative is a second copy of the service's schema that silently drops a field
+ * the day the service adds one.
+ */
+
+/** A property as the bundle carries it. */
+export interface BundleProperty {
+  id: string
+  apiName: string
+  [field: string]: unknown
+}
+
+/** An object type as the bundle carries it. */
+export interface BundleObject {
+  id: string
+  apiName: string
+  properties: BundleProperty[]
+  primaryKeyPropertyId: string
+  titlePropertyId: string
+  governance: {
+    sourceMappings: unknown[]
+    [field: string]: unknown
+  }
+  [field: string]: unknown
+}
+
+/** A link type (`relationships[]` in the bundle) as the bundle carries it. */
+export interface BundleRelationship {
+  id: string
+  apiName: string
+  fromObjectId: string
+  toObjectId: string
+  fromPropertyId: string
+  toPropertyId: string
+  [field: string]: unknown
+}
+
+export interface BundleNamed {
+  id: string
+  apiName: string
+  [field: string]: unknown
+}
+
+export interface DefinitionBundle {
+  schemaVersion: number
+  objects: BundleObject[]
+  sourceSystems: BundleNamed[]
+  relationships: BundleRelationship[]
+  metrics: BundleNamed[]
+  /**
+   * Optional in both bundle versions: an organization that has never authored one
+   * carries no key at all, and the schemas are strict.
+   */
+  sharedProperties?: BundleNamed[]
+  /** v2 only. Absent on a v1 bundle rather than empty — the schemas are strict. */
+  actions?: BundleNamed[]
+}
+
+/**
+ * The authorable kinds, in the order a reader meets them — which is also the order
+ * `apply` writes them in, so a kind that others reference comes first. A property
+ * names its shared field, so shared fields are created before object types.
+ *
+ * Two things are deliberately absent, for the same reason: a file the CLI can write
+ * but never apply is worse than no file, because it breaks the round trip the tree
+ * promises and fails only at the end of a deployment.
+ *
+ * **Source systems** have no route of their own — `createDraftObjectType` synthesises
+ * one for an organization's first object type and nothing else ever creates one.
+ *
+ * **Actions** carry several uuid references the projection cannot turn into names:
+ * `subject.objectTypeId`, `effect.authoritySourceSystemId` and `compensationActionId`
+ * at least. Emitting them as raw uuids makes the tree unportable — the identifiers are
+ * per-deployment — and the create route takes the contract whole, so there is nowhere
+ * to resolve them back. `blueprint create|update|delete action` still authors them
+ * imperatively; only the FILE path is withheld, and withheld visibly rather than
+ * shipped broken.
+ */
+export const ARTIFACT_KINDS = [
+  'shared-field',
+  'object-type',
+  'link-type',
+  'metric',
+] as const
+
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number]
+
+/** `object-type` → `object-types/`. Plural directory, singular command word. */
+export const KIND_DIRECTORY: Record<ArtifactKind, string> = {
+  'shared-field': 'shared-fields',
+  'object-type': 'object-types',
+  'link-type': 'link-types',
+  metric: 'metrics',
+}
+
+export const DIRECTORY_KIND: Record<string, ArtifactKind> = Object.fromEntries(
+  Object.entries(KIND_DIRECTORY).map(([kind, directory]) => [directory, kind as ArtifactKind]),
+) as Record<string, ArtifactKind>
+
+/**
+ * What an `apiName` may be, per kind — the same rules the service enforces
+ * (`catalog-types.ts:258-259`): object types are PascalCase, everything else is
+ * camelCase.
+ *
+ * Checked in the CLI as well as the service, and not only to fail earlier: an apiName
+ * becomes a FILE NAME here, so `../../escaped` wrote outside the tree root before this
+ * existed. A name that cannot name a file is refused before anything is written.
+ */
+export const API_NAME_RULE: Record<ArtifactKind, RegExp> = {
+  'shared-field': /^[a-z][A-Za-z0-9]{0,99}$/,
+  'object-type': /^[A-Z][A-Za-z0-9]{0,99}$/,
+  'link-type': /^[a-z][A-Za-z0-9]{0,99}$/,
+  metric: /^[a-z][A-Za-z0-9]{0,99}$/,
+}
+
+export function describeApiNameRule(kind: ArtifactKind): string {
+  return kind === 'object-type'
+    ? 'PascalCase: a capital letter, then letters and digits'
+    : 'camelCase: a lowercase letter, then letters and digits'
+}
+
+/** One authored file: its kind, its apiName, and the document itself. */
+export interface AuthoredFile {
+  kind: ArtifactKind
+  apiName: string
+  /** Path relative to the tree root, e.g. `object-types/Customer.yaml`. */
+  path: string
+  document: Record<string, unknown>
+}
+
+export interface AuthoredModel {
+  schemaVersion: number
+  files: AuthoredFile[]
+}
+
+/** Everything the compiler needs from the live draft to resolve apiName → UUID. */
+export interface LiveIndex {
+  objectIdByApiName: Map<string, string>
+  /** `<objectApiName>.<propertyApiName>` → property id. */
+  propertyIdByPath: Map<string, string>
+  sourceSystemIdByApiName: Map<string, string>
+  relationshipIdByApiName: Map<string, string>
+  metricIdByApiName: Map<string, string>
+  actionIdByApiName: Map<string, string>
+  /**
+   * The one reference a FILE writes by name that the wire takes as a uuid.
+   *
+   * A property entry says `sharedField: accountCode`; the object-create body and
+   * the field commands say `sharedPropertyId`. The authored tree speaks FIELD and
+   * the wire speaks property — this map is where the two meet, and it is the only
+   * reference a file writes that is not addressed by name on both sides.
+   */
+  sharedPropertyIdByApiName: Map<string, string>
+  /** The live object, by apiName — the merge reads `governance.sourceMappings` off it. */
+  objectByApiName: Map<string, BundleObject>
+  relationshipByApiName: Map<string, BundleRelationship>
+}
+
+export function emptyIndex(): LiveIndex {
+  return {
+    objectIdByApiName: new Map(),
+    propertyIdByPath: new Map(),
+    sourceSystemIdByApiName: new Map(),
+    relationshipIdByApiName: new Map(),
+    metricIdByApiName: new Map(),
+    actionIdByApiName: new Map(),
+    sharedPropertyIdByApiName: new Map(),
+    objectByApiName: new Map(),
+    relationshipByApiName: new Map(),
+  }
+}
+
+export function indexBundle(bundle: DefinitionBundle): LiveIndex {
+  const index = emptyIndex()
+  for (const object of bundle.objects) {
+    index.objectIdByApiName.set(object.apiName, object.id)
+    index.objectByApiName.set(object.apiName, object)
+    for (const property of object.properties) {
+      index.propertyIdByPath.set(`${object.apiName}.${property.apiName}`, property.id)
+    }
+  }
+  for (const system of bundle.sourceSystems) index.sourceSystemIdByApiName.set(system.apiName, system.id)
+  for (const link of bundle.relationships) {
+    index.relationshipIdByApiName.set(link.apiName, link.id)
+    index.relationshipByApiName.set(link.apiName, link)
+  }
+  for (const metric of bundle.metrics) index.metricIdByApiName.set(metric.apiName, metric.id)
+  for (const action of bundle.actions ?? []) index.actionIdByApiName.set(action.apiName, action.id)
+  for (const shared of bundle.sharedProperties ?? []) {
+    index.sharedPropertyIdByApiName.set(shared.apiName, shared.id)
+  }
+  return index
+}
+
+/**
+ * An unresolved reference, collected rather than thrown.
+ *
+ * All of them are reported at once: fixing references one error per run is the
+ * failure mode that makes a declarative tool feel worse than the imperative commands
+ * it replaces.
+ */
+export interface RefError {
+  /** The file the reference is written in. */
+  path: string
+  /** Where in that file, dotted — e.g. `from.property`. */
+  field: string
+  /** The name that resolved to nothing. */
+  name: string
+  message: string
+}
+
+export type Result<T> =
+  | { ok: true; value: T }
+  | { ok: false; errors: RefError[] }