@likec4/leanix-bridge 1.53.0

package/src/to-bridge-manifest.ts

@@ -0,0 +1,85 @@
+import type {
+  BridgeManifest,
+  CanonicalId,
+  ManifestEntity,
+  ManifestRelation,
+  ManifestView,
+  ViewId,
+} from './contracts'
+import {
+  BRIDGE_MANIFEST_VERSION,
+  BRIDGE_VERSION,
+} from './contracts'
+import type { BridgeModelInput } from './model-input'
+
+export interface ToBridgeManifestOptions {
+  manifestVersion?: string
+  generatedAt?: string
+  bridgeVersion?: string
+  mappingProfile?: string
+}
+
+const defaultOptions: Omit<Required<ToBridgeManifestOptions>, 'generatedAt'> = {
+  manifestVersion: BRIDGE_MANIFEST_VERSION,
+  bridgeVersion: BRIDGE_VERSION,
+  mappingProfile: 'default',
+}
+
+/** Builds manifest entities map from model elements (canonicalId + empty external). */
+function buildManifestEntities(model: BridgeModelInput): Record<CanonicalId, ManifestEntity> {
+  const entities: Record<CanonicalId, ManifestEntity> = {}
+  for (const el of model.elements()) {
+    entities[el.id] = { canonicalId: el.id, external: {} }
+  }
+  return entities
+}
+
+/** Builds manifest views map from model views (viewId + empty external). */
+function buildManifestViews(model: BridgeModelInput): Record<ViewId, ManifestView> {
+  const views: Record<ViewId, ManifestView> = {}
+  for (const v of model.views()) {
+    views[v.id] = { viewId: v.id, external: {} }
+  }
+  return views
+}
+
+/** Builds manifest relations array from model relationships (compositeKey + empty external). */
+function buildManifestRelations(model: BridgeModelInput): ManifestRelation[] {
+  const relations: ManifestRelation[] = []
+  for (const rel of model.relationships()) {
+    relations.push({
+      relationId: rel.id,
+      sourceFqn: rel.source.id,
+      targetFqn: rel.target.id,
+      compositeKey: `${rel.source.id}|${rel.target.id}|${rel.id}`,
+      external: {},
+    })
+  }
+  return relations
+}
+
+/**
+ * Produces the identity manifest from a LikeC4 model (canonical IDs + placeholders for external IDs).
+ * Pure function; no live API calls.
+ */
+export function toBridgeManifest(
+  model: BridgeModelInput,
+  options: ToBridgeManifestOptions = {},
+): BridgeManifest {
+  const opts: Required<ToBridgeManifestOptions> = {
+    ...defaultOptions,
+    ...options,
+    generatedAt: options.generatedAt ?? new Date().toISOString(),
+  }
+
+  return {
+    manifestVersion: opts.manifestVersion,
+    generatedAt: opts.generatedAt,
+    bridgeVersion: opts.bridgeVersion,
+    mappingProfile: opts.mappingProfile,
+    projectId: model.projectId,
+    entities: buildManifestEntities(model),
+    views: buildManifestViews(model),
+    relations: buildManifestRelations(model),
+  }
+}

package/src/to-leanix-inventory-dry-run.ts

@@ -0,0 +1,105 @@
+import { getFactSheetType, getRelationType, mergeWithDefault } from './mapping'
+import type { LeanixMappingConfig } from './mapping'
+import type { BridgeModelInput } from './model-input'
+
+/** Single LeanIX fact sheet in dry-run shape (no IDs from live API) */
+export interface LeanixFactSheetDryRun {
+  type: string
+  likec4Id: string
+  name: string
+  description?: string
+  technology?: string
+  tags?: string[]
+  metadata?: Record<string, unknown>
+}
+
+/** Single LeanIX relation in dry-run shape */
+export interface LeanixRelationDryRun {
+  type: string
+  likec4RelationId: string
+  sourceLikec4Id: string
+  targetLikec4Id: string
+  title?: string
+}
+
+/** Dry-run inventory: fact sheets and relations as would be sent to LeanIX, without live IDs */
+export interface LeanixInventoryDryRun {
+  generatedAt: string
+  projectId: string
+  mappingProfile: string
+  factSheets: LeanixFactSheetDryRun[]
+  relations: LeanixRelationDryRun[]
+}
+
+/** Options for toLeanixInventoryDryRun (mapping, mappingProfile, generatedAt). */
+export interface ToLeanixInventoryDryRunOptions {
+  mapping?: LeanixMappingConfig | null
+  mappingProfile?: string
+  generatedAt?: string
+}
+
+/** Builds LeanIX fact sheet dry-run list from model elements and mapping. */
+function buildFactSheetsFromModel(
+  model: BridgeModelInput,
+  mapping: ReturnType<typeof mergeWithDefault>,
+): LeanixFactSheetDryRun[] {
+  const factSheets: LeanixFactSheetDryRun[] = []
+  for (const el of model.elements()) {
+    const fsType = getFactSheetType(el.kind, mapping)
+    const meta = el.getMetadata()
+    const desc = typeof meta['description'] === 'string' ? meta['description'] : undefined
+    const tech = el.technology ?? (typeof meta['technology'] === 'string' ? meta['technology'] : undefined)
+    factSheets.push({
+      type: fsType,
+      likec4Id: el.id,
+      name: el.title,
+      ...(desc !== undefined && { description: desc }),
+      ...(tech !== undefined && { technology: tech }),
+      ...(el.tags.length > 0 && { tags: [...el.tags] }),
+      ...(Object.keys(meta).length > 0 && { metadata: { ...meta } }),
+    })
+  }
+  factSheets.sort((a, b) => a.likec4Id.localeCompare(b.likec4Id))
+  return factSheets
+}
+
+/** Builds LeanIX relation dry-run list from model relationships and mapping. */
+function buildRelationsFromModel(
+  model: BridgeModelInput,
+  mapping: ReturnType<typeof mergeWithDefault>,
+): LeanixRelationDryRun[] {
+  const relations: LeanixRelationDryRun[] = []
+  for (const rel of model.relationships()) {
+    const titleVal = rel.title ?? rel.kind
+    relations.push({
+      type: getRelationType(rel.kind, mapping),
+      likec4RelationId: rel.id,
+      sourceLikec4Id: rel.source.id,
+      targetLikec4Id: rel.target.id,
+      ...(titleVal != null && titleVal !== '' && { title: String(titleVal) }),
+    })
+  }
+  relations.sort((a, b) => a.likec4RelationId.localeCompare(b.likec4RelationId))
+  return relations
+}
+
+/**
+ * Produces LeanIX-shaped inventory artifacts (fact sheets + relations) from a LikeC4 model.
+ * Pure function; no live API. Use for dry-run and planning.
+ */
+export function toLeanixInventoryDryRun(
+  model: BridgeModelInput,
+  options: ToLeanixInventoryDryRunOptions = {},
+): LeanixInventoryDryRun {
+  const mapping = mergeWithDefault(options.mapping)
+  const generatedAt = options.generatedAt ?? new Date().toISOString()
+  const mappingProfile = options.mappingProfile ?? (options.mapping ? 'custom' : 'default')
+
+  return {
+    generatedAt,
+    projectId: model.projectId,
+    mappingProfile,
+    factSheets: buildFactSheetsFromModel(model, mapping),
+    relations: buildRelationsFromModel(model, mapping),
+  }
+}

package/src/validate.ts

@@ -0,0 +1,106 @@
+/**
+ * Type guards for bridge artifacts (e.g. parsed JSON).
+ * Keeps validation next to the type definitions (SRP).
+ * Nested shapes are validated to avoid false positives (G2, G3).
+ */
+
+import type { BridgeManifest, ManifestEntity, ManifestRelation, ManifestView } from './contracts'
+import type {
+  LeanixFactSheetSnapshotItem,
+  LeanixInventorySnapshot,
+  LeanixRelationSnapshotItem,
+} from './leanix-inventory-snapshot'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isManifestEntity(value: unknown): value is ManifestEntity {
+  if (!isRecord(value)) return false
+  return typeof value['canonicalId'] === 'string'
+}
+
+function isManifestView(value: unknown): value is ManifestView {
+  if (!isRecord(value)) return false
+  return typeof value['viewId'] === 'string'
+}
+
+function isManifestRelation(value: unknown): value is ManifestRelation {
+  if (!isRecord(value)) return false
+  return (
+    typeof value['relationId'] === 'string' &&
+    typeof value['sourceFqn'] === 'string' &&
+    typeof value['targetFqn'] === 'string' &&
+    typeof value['compositeKey'] === 'string'
+  )
+}
+
+function isLeanixFactSheetSnapshotItem(value: unknown): value is LeanixFactSheetSnapshotItem {
+  if (!isRecord(value)) return false
+  return (
+    typeof value['id'] === 'string' &&
+    typeof value['name'] === 'string' &&
+    typeof value['type'] === 'string'
+  )
+}
+
+function isLeanixRelationSnapshotItem(value: unknown): value is LeanixRelationSnapshotItem {
+  if (!isRecord(value)) return false
+  return (
+    typeof value['sourceFactSheetId'] === 'string' &&
+    typeof value['targetFactSheetId'] === 'string' &&
+    typeof value['type'] === 'string'
+  )
+}
+
+/**
+ * Returns true if the value is a valid BridgeManifest shape (manifestVersion, generatedAt, bridgeVersion, mappingProfile, projectId, entities, relations, views)
+ * and nested entities/views/relations match expected shapes.
+ */
+export function isBridgeManifest(obj: unknown): obj is BridgeManifest {
+  if (!isRecord(obj)) return false
+  if (
+    typeof obj['manifestVersion'] !== 'string' ||
+    typeof obj['generatedAt'] !== 'string' ||
+    typeof obj['bridgeVersion'] !== 'string' ||
+    typeof obj['mappingProfile'] !== 'string' ||
+    typeof obj['projectId'] !== 'string'
+  ) {
+    return false
+  }
+  const entities = obj['entities']
+  if (typeof entities !== 'object' || entities === null || Array.isArray(entities)) return false
+  for (const v of Object.values(entities)) {
+    if (!isManifestEntity(v)) return false
+  }
+  const views = obj['views']
+  if (typeof views !== 'object' || views === null || Array.isArray(views)) return false
+  for (const v of Object.values(views)) {
+    if (!isManifestView(v)) return false
+  }
+  const relations = obj['relations']
+  if (!Array.isArray(relations)) return false
+  for (const r of relations) {
+    if (!isManifestRelation(r)) return false
+  }
+  return true
+}
+
+/**
+ * Returns true if the value is a valid LeanixInventorySnapshot shape (generatedAt, factSheets and relations arrays)
+ * and each fact sheet/relation item has required fields.
+ */
+export function isLeanixInventorySnapshot(obj: unknown): obj is LeanixInventorySnapshot {
+  if (!isRecord(obj)) return false
+  if (typeof obj['generatedAt'] !== 'string') return false
+  if (obj['workspaceId'] !== undefined && typeof obj['workspaceId'] !== 'string') return false
+  if (!Array.isArray(obj['factSheets'])) return false
+  for (const fs of obj['factSheets']) {
+    if (!isLeanixFactSheetSnapshotItem(fs)) return false
+  }
+  if (!Array.isArray(obj['relations'])) return false
+  for (const rel of obj['relations']) {
+    if (!isLeanixRelationSnapshotItem(rel)) return false
+  }
+  return true
+}