@likec4/leanix-bridge 1.53.0 → 1.55.0

package/dist/index.d.mts

@@ -5,7 +5,7 @@
  * Uses readFileSync (not require) so when bundled into likec4 CLI the bundler
  * does not emit require('../package.json') which fails in the tarball layout.
  */
-/** Single source of truth: must match package.json version. */
+/** Bridge version; must match package version (from package.json when available). */
 declare const BRIDGE_VERSION: string;
 /** Semantic anchor: LikeC4 FQN (e.g. cloud.backend.api) */
 type CanonicalId = string;
@@ -86,6 +86,11 @@ interface LeanixMappingConfig {
 declare const FALLBACK_FACT_SHEET_TYPE = "Application";
 /** Fallback when relation kind is unknown (G25: named constant). */
 declare const FALLBACK_RELATION_TYPE = "depends on";
+/**
+ * Parses and validates a partial LeanIX mapping from untrusted input (e.g. YAML/JSON).
+ * Returns `null`/`undefined` unchanged. Throws with a clear message on invalid shape or unknown keys.
+ */
+declare function parseLeanixMappingInput(input: unknown): LeanixMappingConfig | null | undefined;
 /** Default mapping: actor → Provider; override factSheetTypes/relationTypes as needed */
 declare const DEFAULT_LEANIX_MAPPING: Required<LeanixMappingConfig>;
 /**
@@ -142,6 +147,7 @@ interface BridgeModelInput {
 }
 //#endregion
 //#region src/to-bridge-manifest.d.ts
+/** Optional overrides when building a bridge manifest (versions, timestamp, mapping profile). */
 interface ToBridgeManifestOptions {
   manifestVersion?: string;
   generatedAt?: string;
@@ -524,6 +530,7 @@ interface GovernanceCheckResult {
   passed: boolean;
   message?: string;
 }
+/** Aggregated governance outcome (passed, timestamp, per-check results). */
 interface GovernanceReport {
   passed: boolean;
   generatedAt: string;
@@ -556,4 +563,4 @@ declare function isBridgeManifest(obj: unknown): obj is BridgeManifest;
  */
 declare function isLeanixInventorySnapshot(obj: unknown): obj is LeanixInventorySnapshot;
 //#endregion
-export { type AdrGenerationOptions, type AmbiguousMatch, BRIDGE_MANIFEST_VERSION, BRIDGE_VERSION, type BridgeElementLike, type BridgeManifest, type BridgeModelInput, type RelationId as BridgeRelationId, type BridgeRelationLike, type BridgeReport, type BridgeVersion, type ViewId as BridgeViewId, type BridgeViewLike, type CanonicalId, DEFAULT_LEANIX_MAPPING, type DrawioLeanixMapping, type DriftAdrGenerationOptions, type DriftReport, type DriftStatus, type ExternalId, FALLBACK_FACT_SHEET_TYPE, FALLBACK_RELATION_TYPE, type FetchLeanixInventorySnapshotOptions, type GeneratedAt, type GovernanceCheckOptions, type GovernanceCheckResult, type GovernanceReport, type GraphQLResponse, type ImpactReport, LEANIX_PROVIDER, LeanixApiClient, type LeanixApiClientConfig, LeanixApiError, type LeanixFactSheetDryRun, type LeanixFactSheetSnapshotItem, type LeanixInventoryDryRun, type LeanixInventorySnapshot, type LeanixMappingConfig, type LeanixRelationDryRun, type LeanixRelationSnapshotItem, type ManifestEntity, type ManifestRelation, type ManifestVersion, type ManifestView, type MappingProfile, type MatchedPair, type PlanSyncToLeanixOptions, type Provider, type ProviderExternalIds, type ReconcileOptions, type ReconciliationResult, type SyncPlan, type SyncPlanFactSheetEntry, type SyncPlanRelationEntry, type SyncPlanSummary, type SyncToLeanixOptions, type SyncToLeanixResult, type ToBridgeManifestOptions, type ToLeanixInventoryDryRunOptions, type UnmatchedInLeanix, type UnmatchedInLikec4, buildBridgeReport, buildDriftReport, fetchLeanixInventorySnapshot, generateAdrFromDriftReport, generateAdrFromReconciliation, getFactSheetType, getRelationType, impactReportFromSyncPlan, isBridgeManifest, isLeanixInventorySnapshot, manifestToDrawioLeanixMapping, mergeWithDefault, planSyncToLeanix, reconcileInventoryWithManifest, runGovernanceChecks, syncToLeanix, toBridgeManifest, toLeanixInventoryDryRun };
+export { type AdrGenerationOptions, type AmbiguousMatch, BRIDGE_MANIFEST_VERSION, BRIDGE_VERSION, type BridgeElementLike, type BridgeManifest, type BridgeModelInput, type RelationId as BridgeRelationId, type BridgeRelationLike, type BridgeReport, type BridgeVersion, type ViewId as BridgeViewId, type BridgeViewLike, type CanonicalId, DEFAULT_LEANIX_MAPPING, type DrawioLeanixMapping, type DriftAdrGenerationOptions, type DriftReport, type DriftStatus, type ExternalId, FALLBACK_FACT_SHEET_TYPE, FALLBACK_RELATION_TYPE, type FetchLeanixInventorySnapshotOptions, type GeneratedAt, type GovernanceCheckOptions, type GovernanceCheckResult, type GovernanceReport, type GraphQLResponse, type ImpactReport, LEANIX_PROVIDER, LeanixApiClient, type LeanixApiClientConfig, LeanixApiError, type LeanixFactSheetDryRun, type LeanixFactSheetSnapshotItem, type LeanixInventoryDryRun, type LeanixInventorySnapshot, type LeanixMappingConfig, type LeanixRelationDryRun, type LeanixRelationSnapshotItem, type ManifestEntity, type ManifestRelation, type ManifestVersion, type ManifestView, type MappingProfile, type MatchedPair, type PlanSyncToLeanixOptions, type Provider, type ProviderExternalIds, type ReconcileOptions, type ReconciliationResult, type SyncPlan, type SyncPlanFactSheetEntry, type SyncPlanRelationEntry, type SyncPlanSummary, type SyncToLeanixOptions, type SyncToLeanixResult, type ToBridgeManifestOptions, type ToLeanixInventoryDryRunOptions, type UnmatchedInLeanix, type UnmatchedInLikec4, buildBridgeReport, buildDriftReport, fetchLeanixInventorySnapshot, generateAdrFromDriftReport, generateAdrFromReconciliation, getFactSheetType, getRelationType, impactReportFromSyncPlan, isBridgeManifest, isLeanixInventorySnapshot, manifestToDrawioLeanixMapping, mergeWithDefault, parseLeanixMappingInput, planSyncToLeanix, reconcileInventoryWithManifest, runGovernanceChecks, syncToLeanix, toBridgeManifest, toLeanixInventoryDryRun };

package/dist/index.mjs

@@ -8,14 +8,24 @@ import { fileURLToPath } from "node:url";
 * does not emit require('../package.json') which fails in the tarball layout.
 */
 const _dir = dirname(fileURLToPath(import.meta.url));
+/** Last-resort fallback when no package.json is readable (e.g. CI test layout). */
+const DEFAULT_BRIDGE_VERSION = "0.1.0";
+/**
+* Resolves bridge version from package.json so BRIDGE_VERSION stays in sync with the published package.
+* 1) @likec4/leanix-bridge package (when not bundled). 2) likec4 CLI package (when bridge is bundled into CLI; versions are kept in sync). 3) Default only when neither is readable.
+*/
 function readVersion() {
 	try {
-		return JSON.parse(readFileSync(join(_dir, "..", "package.json"), "utf8")).version ?? "0.1.0";
-	} catch {
-		return JSON.parse(readFileSync(join(_dir, "..", "..", "package.json"), "utf8")).version ?? "0.1.0";
-	}
+		const pkg = JSON.parse(readFileSync(join(_dir, "..", "package.json"), "utf8"));
+		if (pkg.version) return pkg.version;
+	} catch {}
+	try {
+		const pkg = JSON.parse(readFileSync(join(_dir, "..", "..", "package.json"), "utf8"));
+		if (pkg.version) return pkg.version;
+	} catch {}
+	return DEFAULT_BRIDGE_VERSION;
 }
-/** Single source of truth: must match package.json version. */
+/** Bridge version; must match package version (from package.json when available). */
 const BRIDGE_VERSION = readVersion();
 /** Manifest schema version (semantic; must match parser). */
 const BRIDGE_MANIFEST_VERSION = "1.0";
@@ -25,6 +35,31 @@ const LEANIX_PROVIDER = "leanix";
 const FALLBACK_FACT_SHEET_TYPE = "Application";
 /** Fallback when relation kind is unknown (G25: named constant). */
 const FALLBACK_RELATION_TYPE = "depends on";
+const MAPPING_TOP_KEYS = new Set([
+	"factSheetTypes",
+	"relationTypes",
+	"metadataToFields"
+]);
+/** True when `value` is a non-array object whose values are all strings. */
+function isPlainObjectRecordOfStrings(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	for (const v of Object.values(value)) if (typeof v !== "string") return false;
+	return true;
+}
+/**
+* Parses and validates a partial LeanIX mapping from untrusted input (e.g. YAML/JSON).
+* Returns `null`/`undefined` unchanged. Throws with a clear message on invalid shape or unknown keys.
+*/
+function parseLeanixMappingInput(input) {
+	if (input === null || input === void 0) return input;
+	if (typeof input !== "object" || Array.isArray(input)) throw new Error("LeanIX mapping must be a plain object (not an array or primitive)");
+	const obj = input;
+	for (const key of Object.keys(obj)) if (!MAPPING_TOP_KEYS.has(key)) throw new Error(`LeanIX mapping has unknown key "${key}". Allowed: factSheetTypes, relationTypes, metadataToFields`);
+	if (obj["factSheetTypes"] !== void 0 && !isPlainObjectRecordOfStrings(obj["factSheetTypes"])) throw new Error("LeanIX mapping \"factSheetTypes\" must be an object with string keys and string values");
+	if (obj["relationTypes"] !== void 0 && !isPlainObjectRecordOfStrings(obj["relationTypes"])) throw new Error("LeanIX mapping \"relationTypes\" must be an object with string keys and string values");
+	if (obj["metadataToFields"] !== void 0 && !isPlainObjectRecordOfStrings(obj["metadataToFields"])) throw new Error("LeanIX mapping \"metadataToFields\" must be an object with string keys and string values");
+	return input;
+}
 /** Default mapping: actor → Provider; override factSheetTypes/relationTypes as needed */
 const DEFAULT_LEANIX_MAPPING = {
 	factSheetTypes: {
@@ -44,24 +79,25 @@ const DEFAULT_LEANIX_MAPPING = {
 * Merges partial mapping config with DEFAULT_LEANIX_MAPPING; returns a full Required<LeanixMappingConfig>.
 */
 function mergeWithDefault(partial) {
+	const normalized = parseLeanixMappingInput(partial);
 	const base = {
 		factSheetTypes: { ...DEFAULT_LEANIX_MAPPING.factSheetTypes },
 		relationTypes: { ...DEFAULT_LEANIX_MAPPING.relationTypes },
 		metadataToFields: { ...DEFAULT_LEANIX_MAPPING.metadataToFields }
 	};
-	if (!partial) return base;
+	if (!normalized) return base;
 	return {
 		factSheetTypes: {
 			...base.factSheetTypes,
-			...partial.factSheetTypes
+			...normalized.factSheetTypes
 		},
 		relationTypes: {
 			...base.relationTypes,
-			...partial.relationTypes
+			...normalized.relationTypes
 		},
 		metadataToFields: {
 			...base.metadataToFields,
-			...partial.metadataToFields
+			...normalized.metadataToFields
 		}
 	};
 }
@@ -318,8 +354,13 @@ async function findFactSheetByNameAndType(client, name, type) {
 	return (edges[0]?.node)?.id ?? null;
 }
 /**
-* Search fact sheets by custom attribute (e.g. likec4Id) for idempotent lookup.
-* Returns null when not found; throws on API/network error.
+* Search LeanIX fact sheets by custom attribute (e.g. likec4Id) for idempotent lookup after bridge sync.
+*
+* @param client - Authenticated LeanIX GraphQL client.
+* @param attributeKey - Custom attribute facet key (e.g. workspace-specific likec4 id field).
+* @param likec4Id - Canonical LikeC4 element id stored in LeanIX.
+* @returns Fact sheet id when exactly one match exists; `null` when none found.
+* @throws Error when multiple matches, network failure, or GraphQL error.
 */
 async function findFactSheetByLikec4IdAttribute(client, attributeKey, likec4Id) {
 	const query = `
@@ -1107,4 +1148,4 @@ function isLeanixInventorySnapshot(obj) {
 	for (const rel of obj["relations"]) if (!isLeanixRelationSnapshotItem(rel)) return false;
 	return true;
 }
-export { BRIDGE_MANIFEST_VERSION, BRIDGE_VERSION, DEFAULT_LEANIX_MAPPING, FALLBACK_FACT_SHEET_TYPE, FALLBACK_RELATION_TYPE, LEANIX_PROVIDER, LeanixApiClient, LeanixApiError, buildBridgeReport, buildDriftReport, fetchLeanixInventorySnapshot, generateAdrFromDriftReport, generateAdrFromReconciliation, getFactSheetType, getRelationType, impactReportFromSyncPlan, isBridgeManifest, isLeanixInventorySnapshot, manifestToDrawioLeanixMapping, mergeWithDefault, planSyncToLeanix, reconcileInventoryWithManifest, runGovernanceChecks, syncToLeanix, toBridgeManifest, toLeanixInventoryDryRun };
+export { BRIDGE_MANIFEST_VERSION, BRIDGE_VERSION, DEFAULT_LEANIX_MAPPING, FALLBACK_FACT_SHEET_TYPE, FALLBACK_RELATION_TYPE, LEANIX_PROVIDER, LeanixApiClient, LeanixApiError, buildBridgeReport, buildDriftReport, fetchLeanixInventorySnapshot, generateAdrFromDriftReport, generateAdrFromReconciliation, getFactSheetType, getRelationType, impactReportFromSyncPlan, isBridgeManifest, isLeanixInventorySnapshot, manifestToDrawioLeanixMapping, mergeWithDefault, parseLeanixMappingInput, planSyncToLeanix, reconcileInventoryWithManifest, runGovernanceChecks, syncToLeanix, toBridgeManifest, toLeanixInventoryDryRun };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@likec4/leanix-bridge",
-  "version": "1.53.0",
+  "version": "1.55.0",
   "license": "MIT",
   "bugs": "https://github.com/likec4/likec4/issues",
   "homepage": "https://likec4.dev",
@@ -37,16 +37,16 @@
     "access": "public"
   },
   "dependencies": {
-    "remeda": "^2.33.6",
-    "@likec4/core": "1.53.0"
+    "remeda": "^2.33.7",
+    "@likec4/core": "1.55.0"
   },
   "devDependencies": {
     "@types/node": "~22.19.15",
     "typescript": "5.9.3",
     "obuild": "0.4.31",
-    "vitest": "4.1.0",
-    "@likec4/devops": "1.42.0",
-    "@likec4/tsconfig": "1.53.0"
+    "vitest": "4.1.3",
+    "@likec4/tsconfig": "1.55.0",
+    "@likec4/devops": "1.42.0"
   },
   "scripts": {
     "typecheck": "tsc -b --verbose",

package/src/contracts.ts

@@ -10,16 +10,31 @@ import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const _dir = dirname(fileURLToPath(import.meta.url))
+
+/** Last-resort fallback when no package.json is readable (e.g. CI test layout). */
+const DEFAULT_BRIDGE_VERSION = '0.1.0'
+
+/**
+ * Resolves bridge version from package.json so BRIDGE_VERSION stays in sync with the published package.
+ * 1) @likec4/leanix-bridge package (when not bundled). 2) likec4 CLI package (when bridge is bundled into CLI; versions are kept in sync). 3) Default only when neither is readable.
+ */
 function readVersion(): string {
   try {
     const pkg = JSON.parse(readFileSync(join(_dir, '..', 'package.json'), 'utf8')) as { version?: string }
-    return pkg.version ?? '0.1.0'
+    if (pkg.version) return pkg.version
   } catch {
+    // Bundled CLI: import.meta.url is under packages/likec4/dist/cli, so ../package.json is missing; use ../../ (CLI package).
+  }
+  try {
     const pkg = JSON.parse(readFileSync(join(_dir, '..', '..', 'package.json'), 'utf8')) as { version?: string }
-    return pkg.version ?? '0.1.0'
+    if (pkg.version) return pkg.version
+  } catch {
+    // Neither readable (e.g. test env).
   }
+  return DEFAULT_BRIDGE_VERSION
 }
-/** Single source of truth: must match package.json version. */
+
+/** Bridge version; must match package version (from package.json when available). */
 export const BRIDGE_VERSION: string = readVersion()
 
 /** Semantic anchor: LikeC4 FQN (e.g. cloud.backend.api) */

package/src/governance-checks.ts

@@ -13,6 +13,7 @@ export interface GovernanceCheckResult {
   message?: string
 }
 
+/** Aggregated governance outcome (passed, timestamp, per-check results). */
 export interface GovernanceReport {
   passed: boolean
   generatedAt: string

package/src/index.ts

@@ -35,6 +35,7 @@ export {
   getFactSheetType,
   getRelationType,
   mergeWithDefault,
+  parseLeanixMappingInput,
 } from './mapping'
 export type { LeanixMappingConfig } from './mapping'
 

package/src/leanix-graphql-operations.ts

@@ -38,8 +38,13 @@ export async function findFactSheetByNameAndType(
 }
 
 /**
- * Search fact sheets by custom attribute (e.g. likec4Id) for idempotent lookup.
- * Returns null when not found; throws on API/network error.
+ * Search LeanIX fact sheets by custom attribute (e.g. likec4Id) for idempotent lookup after bridge sync.
+ *
+ * @param client - Authenticated LeanIX GraphQL client.
+ * @param attributeKey - Custom attribute facet key (e.g. workspace-specific likec4 id field).
+ * @param likec4Id - Canonical LikeC4 element id stored in LeanIX.
+ * @returns Fact sheet id when exactly one match exists; `null` when none found.
+ * @throws Error when multiple matches, network failure, or GraphQL error.
  */
 export async function findFactSheetByLikec4IdAttribute(
   client: LeanixApiClient,

package/src/mapping.ts

@@ -19,6 +19,58 @@ export const FALLBACK_FACT_SHEET_TYPE = 'Application'
 /** Fallback when relation kind is unknown (G25: named constant). */
 export const FALLBACK_RELATION_TYPE = 'depends on'
 
+const MAPPING_TOP_KEYS = new Set(['factSheetTypes', 'relationTypes', 'metadataToFields'])
+
+/** True when `value` is a non-array object whose values are all strings. */
+function isPlainObjectRecordOfStrings(value: unknown): value is Record<string, string> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false
+  }
+  for (const v of Object.values(value as Record<string, unknown>)) {
+    if (typeof v !== 'string') {
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Parses and validates a partial LeanIX mapping from untrusted input (e.g. YAML/JSON).
+ * Returns `null`/`undefined` unchanged. Throws with a clear message on invalid shape or unknown keys.
+ */
+export function parseLeanixMappingInput(input: unknown): LeanixMappingConfig | null | undefined {
+  if (input === null || input === undefined) {
+    return input
+  }
+  if (typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('LeanIX mapping must be a plain object (not an array or primitive)')
+  }
+  const obj = input as Record<string, unknown>
+  for (const key of Object.keys(obj)) {
+    if (!MAPPING_TOP_KEYS.has(key)) {
+      throw new Error(
+        `LeanIX mapping has unknown key "${key}". Allowed: factSheetTypes, relationTypes, metadataToFields`,
+      )
+    }
+  }
+  if (obj['factSheetTypes'] !== undefined && !isPlainObjectRecordOfStrings(obj['factSheetTypes'])) {
+    throw new Error(
+      'LeanIX mapping "factSheetTypes" must be an object with string keys and string values',
+    )
+  }
+  if (obj['relationTypes'] !== undefined && !isPlainObjectRecordOfStrings(obj['relationTypes'])) {
+    throw new Error(
+      'LeanIX mapping "relationTypes" must be an object with string keys and string values',
+    )
+  }
+  if (obj['metadataToFields'] !== undefined && !isPlainObjectRecordOfStrings(obj['metadataToFields'])) {
+    throw new Error(
+      'LeanIX mapping "metadataToFields" must be an object with string keys and string values',
+    )
+  }
+  return input as LeanixMappingConfig
+}
+
 /** Default mapping: actor → Provider; override factSheetTypes/relationTypes as needed */
 export const DEFAULT_LEANIX_MAPPING: Required<LeanixMappingConfig> = {
   factSheetTypes: {
@@ -41,18 +93,19 @@ export const DEFAULT_LEANIX_MAPPING: Required<LeanixMappingConfig> = {
  * Merges partial mapping config with DEFAULT_LEANIX_MAPPING; returns a full Required<LeanixMappingConfig>.
  */
 export function mergeWithDefault(partial?: LeanixMappingConfig | null): Required<LeanixMappingConfig> {
+  const normalized = parseLeanixMappingInput(partial)
   const base = {
     factSheetTypes: { ...DEFAULT_LEANIX_MAPPING.factSheetTypes },
     relationTypes: { ...DEFAULT_LEANIX_MAPPING.relationTypes },
     metadataToFields: { ...DEFAULT_LEANIX_MAPPING.metadataToFields },
   }
-  if (!partial) {
+  if (!normalized) {
     return base
   }
   return {
-    factSheetTypes: { ...base.factSheetTypes, ...partial.factSheetTypes },
-    relationTypes: { ...base.relationTypes, ...partial.relationTypes },
-    metadataToFields: { ...base.metadataToFields, ...partial.metadataToFields },
+    factSheetTypes: { ...base.factSheetTypes, ...normalized.factSheetTypes },
+    relationTypes: { ...base.relationTypes, ...normalized.relationTypes },
+    metadataToFields: { ...base.metadataToFields, ...normalized.metadataToFields },
   }
 }
 

package/src/to-bridge-manifest.ts

@@ -12,6 +12,7 @@ import {
 } from './contracts'
 import type { BridgeModelInput } from './model-input'
 
+/** Optional overrides when building a bridge manifest (versions, timestamp, mapping profile). */
 export interface ToBridgeManifestOptions {
   manifestVersion?: string
   generatedAt?: string