.gitignore (1)

138-139: Optional: Remove redundant pattern.

The pattern docs/PR-*-REVIEW.md on line 138 is redundant since docs/PR-*.md on line 139 already matches files like PR-123-REVIEW.md. You can safely remove line 138 to simplify the ignore rules.

♻️ Simplify by removing redundant pattern

-docs/PR-*-REVIEW.md
 docs/PR-*.md

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.gitignore around lines 138 - 139, The .gitignore contains a redundant
pattern: remove the specific pattern "docs/PR-*-REVIEW.md" because the broader
pattern "docs/PR-*.md" already matches those files; delete the
"docs/PR-*-REVIEW.md" entry so only "docs/PR-*.md" remains.

packages/likec4/src/cli/codegen/leanix-reconcile.ts (1)

79-85: Promote dry-run enrichment fallback from debug to warn.

If workspace enrichment fails, reconciliation still runs but with reduced matching quality; warn makes that degradation visible to normal users.

🔎 Suggested tweak

-      logger.debug(
+      logger.warn(
         `Could not load workspace for dryRun enrichment; proceeding without it: ${
           err instanceof Error ? err.message : String(err)
         }`,
       )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/src/cli/codegen/leanix-reconcile.ts` around lines 79 - 85, In
the catch block that currently logs "Could not load workspace for dryRun
enrichment; proceeding without it..." using logger.debug and then sets dryRun =
undefined, change the log call to logger.warn so the failure is visible to
normal users; keep the existing error formatting (err instanceof Error ?
err.message : String(err)) and preserve setting dryRun = undefined and
surrounding behavior in the same catch block to maintain functionality.

e2e/src/likec4-cli-bridge.spec.ts (1)

12-63: Consider extracting shared e2e artifact assertions.

Both tests repeat the same cleanup, directory listing, and JSON validation flow; a small helper would reduce duplication and future drift.

♻️ Refactor sketch

+function resetOutDir() {
+  rmSync(outDirAbs, { recursive: true, force: true })
+  mkdirSync(outDirAbs, { recursive: true })
+}
+
+function expectBridgeArtifacts(expect: any) {
+  const entries = readdirSync(outDirAbs, { withFileTypes: true }).map(e => e.name).sort()
+  expect(entries).toContain('manifest.json')
+  expect(entries).toContain('leanix-dry-run.json')
+  expect(entries).toContain('report.json')
+}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@e2e/src/likec4-cli-bridge.spec.ts` around lines 12 - 63, The two tests
'LikeC4 CLI - gen leanix-dry-run produces manifest, leanix-dry-run, report' and
'LikeC4 CLI - sync leanix --dry-run produces same artifacts and does not require
token' duplicate cleanup, dir creation, listing and JSON assertions; extract
that logic into a small helper (e.g., createCleanOutDir(outDirAbs) for
rmSync/mkdirSync and assertE2EArtifacts(outDirAbs) for checking entries and
parsing manifest/leanix-dry-run/report) and call those helpers from both test
bodies (replace the repeated rmSync/mkdirSync, readdirSync checks and JSON
parse/assert blocks). Ensure helper names are unique (createCleanOutDir,
assertE2EArtifacts) so you can locate and replace the repeated code in the
tests.

packages/leanix-bridge/src/governance-checks.ts (1)

43-49: Consider simplifying the nested ternary for readability.

The nested ternary on line 47 works correctly but is flagged for complexity. A minor refactor would improve clarity.

♻️ Simplified buildCheck return

 function buildCheck(
   id: string,
   name: string,
   passed: boolean,
   failedMessage?: string,
 ): GovernanceCheckResult {
-  return {
-    id,
-    name,
-    passed,
-    ...(passed ? {} : failedMessage !== undefined ? { message: failedMessage } : {}),
-  }
+  const result: GovernanceCheckResult = { id, name, passed }
+  if (!passed && failedMessage !== undefined) {
+    result.message = failedMessage
+  }
+  return result
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/leanix-bridge/src/governance-checks.ts` around lines 43 - 49, The
return object in the function that produces the governance check (the block
returning id, name, passed, ...(passed ? {} : failedMessage !== undefined ? {
message: failedMessage } : {})) is using a nested ternary that hurts
readability; replace it with a simple conditional before the return (e.g.,
compute a messageProps variable if !passed and failedMessage exists, or set it
to an empty object) and then spread messageProps into the returned object,
referencing the same identifiers id, name, passed, and failedMessage to locate
the code.

packages/leanix-bridge/src/reconcile.ts (1)

73-160: Consider extracting helper functions to reduce cognitive complexity.

SonarCloud flags this function with cognitive complexity of 34 (allowed: 30). The matching logic is sound, but the function could be more maintainable if split into smaller helpers.

♻️ Suggested refactoring approach

Extract the three matching strategies into separate functions:

+function tryMatchByManifestFactSheetId(
+  entity: ManifestEntity,
+  canonicalId: CanonicalId,
+  snapshotById: Map<string, LeanixFactSheetSnapshotItem>,
+  usedFactSheetIds: Set<string>,
+): MatchedPair | null {
+  const leanixExternal = entity.external?.[LEANIX_PROVIDER]
+  const manifestFactSheetId = leanixExternal?.factSheetId ?? leanixExternal?.externalId
+  if (manifestFactSheetId != null) {
+    const fs = snapshotById.get(manifestFactSheetId)
+    if (fs) {
+      usedFactSheetIds.add(fs.id)
+      return { canonicalId, factSheetId: fs.id, name: fs.name, type: fs.type }
+    }
+  }
+  return null
+}
+
+function tryMatchByLikec4Id(
+  canonicalId: CanonicalId,
+  snapshotByLikec4Id: Map<string, LeanixFactSheetSnapshotItem>,
+  usedFactSheetIds: Set<string>,
+): MatchedPair | null {
+  const byLikec4 = snapshotByLikec4Id.get(canonicalId)
+  if (byLikec4 && !usedFactSheetIds.has(byLikec4.id)) {
+    usedFactSheetIds.add(byLikec4.id)
+    return { canonicalId, factSheetId: byLikec4.id, name: byLikec4.name, type: byLikec4.type }
+  }
+  return null
+}

Then call these helpers in sequence within the main loop.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/leanix-bridge/src/reconcile.ts` around lines 73 - 160, The function
reconcileInventoryWithManifest is too complex; extract the three matching
strategies into small helpers to reduce cognitive complexity: create
matchByManifestFactSheetId(manifestFactSheetId, snapshotById, matched,
usedFactSheetIds) to handle the manifest.external LEANIX_PROVIDER lookup and
immediate match, matchByLikec4Id(canonicalId, snapshotByLikec4Id, matched,
usedFactSheetIds) to handle the snapshotByLikec4Id lookup and match, and
matchByNameAndType(canonicalId, dryRunByCanonicalId, snapshotByNameAndType,
usedFactSheetIds, unmatchedInLikec4, ambiguous, matched) to compute
entityName/entityType, build nameTypeKey, filter unused candidates and push
either unmatchedInLikec4, a single matched entry, or ambiguous; then simplify
the main loop in reconcileInventoryWithManifest to call these three helpers in
order (short-circuiting when a match is made) and pass in the maps/sets
(snapshotById, snapshotByLikec4Id, snapshotByNameAndType, dryRunByCanonicalId,
usedFactSheetIds) and arrays (matched, unmatchedInLikec4, ambiguous) so the
top-level function becomes a thin orchestrator and the complex matching logic
lives in the new functions.

packages/leanix-bridge/src/reconcile.ts (1)

109-119: Redundant null check after length validation.

After confirming candidates.length === 1, the element at index 0 is guaranteed to exist. The if (candidate) check on line 111 is defensive but unnecessary.

♻️ Simplified version

   } else if (candidates.length === 1) {
-    const candidate = candidates[0]
-    if (candidate) {
-      matched.push({
-        canonicalId,
-        factSheetId: candidate.id,
-        name: candidate.name,
-        type: candidate.type,
-      })
-      usedFactSheetIds.add(candidate.id)
-    }
+    const candidate = candidates[0]!
+    matched.push({
+      canonicalId,
+      factSheetId: candidate.id,
+      name: candidate.name,
+      type: candidate.type,
+    })
+    usedFactSheetIds.add(candidate.id)
   } else {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/leanix-bridge/src/reconcile.ts` around lines 109 - 119, The check
`if (candidate)` is redundant because you already confirmed `candidates.length
=== 1`; remove the unnecessary `if (candidate)` guard and directly use `const
candidate = candidates[0]` to push into `matched` and add to `usedFactSheetIds`
(update the block around the `candidates.length === 1` branch that defines
`candidate`, the `matched.push({...})` call, and the
`usedFactSheetIds.add(candidate.id)` call).

packages/leanix-bridge/src/governance-checks.ts (1)

95-100: Consider using a fresh timestamp for the governance report.

The generatedAt field is copied from reconciliation.generatedAt, which reflects when the reconciliation was performed, not when the governance checks ran. If these can happen at different times (e.g., reconciliation is cached and governance checks run later), consider using a fresh timestamp for traceability.

♻️ Suggested change

+export function runGovernanceChecks(
+  reconciliation: ReconciliationResult,
+  options: GovernanceCheckOptions = {},
+): GovernanceReport {
+  const opts = { ...DEFAULT_OPTIONS, ...options }
+  const checks: GovernanceCheckResult[] = []
+  const { summary } = reconciliation
   // ... checks logic ...
   const passed = checks.every(c => c.passed)
   return {
     passed,
-    generatedAt: reconciliation.generatedAt,
+    generatedAt: new Date().toISOString(),
     checks,
   }
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/leanix-bridge/src/governance-checks.ts` around lines 95 - 100, The
governance report currently returns generatedAt: reconciliation.generatedAt
which uses the reconciliation timestamp; update the return in the function that
builds the report (the object containing passed, generatedAt, checks) to set
generatedAt to a fresh timestamp (e.g., Date.now() or new Date().toISOString())
so the governance-checks.ts report reflects when checks were run rather than
when reconciliation occurred; keep the rest of the structure (passed, checks)
unchanged.

packages/likec4/src/cli/codegen/leanix-reconcile.ts (1)

97-107: ⚠️ Potential issue | 🟠 Major

Don't silently degrade when explicit workspace/project loading fails.

This catch block turns every workspace/project load error into a warning. If the user asked for a specific project and typoed it, the command still exits successfully with a lower-fidelity reconciliation report, which hides the real configuration problem.

🛠️ Proposed fix

     let dryRun: LeanixInventoryDryRun | undefined
     try {
       dryRun = await loadDryRunFromWorkspace(workspacePath, project, useDotBin)
     } catch (err) {
-      logger.warn(
-        `Could not load workspace for dryRun enrichment; proceeding without it: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      )
-      dryRun = undefined
+      const msg = err instanceof Error ? err.message : String(err)
+      if (project) {
+        logger.error(`Failed to load workspace for dryRun enrichment: ${msg}`)
+        throw err
+      }
+      logger.warn(`Could not load workspace for dryRun enrichment; proceeding without it: ${msg}`)
+      dryRun = undefined
     }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/likec4/src/cli/codegen/leanix-reconcile.ts` around lines 97 - 107,
The catch currently swallows all errors from loadDryRunFromWorkspace which hides
real config issues; update the catch in the block around
loadDryRunFromWorkspace(workspacePath, project, useDotBin) to only degrade to a
warning when the project argument was not explicitly provided, but if project
(or any explicit workspace selector) was passed, rethrow the error (or return a
non-zero failure) instead of assigning dryRun = undefined; use the existing
logger.warn for the non-fatal case and preserve the original error when
rethrowing so callers can fail fast and surface typos or bad configuration.

packages/config/src/schema.ts (1)

300-329: Consider omitting landingPage from the main parse to avoid double validation.

The current approach validates landingPage twice: once explicitly via LandingPageSchema.safeParse (line 304) and again as part of LikeC4ProjectJsonConfigSchema.safeParse (line 310). While the workaround for Zod v4 stripping optional union keys is documented, you could use .omit({ landingPage: true }) on the main schema parse to avoid redundant validation.

Also, the cast on line 314 (as unknown as LikeC4ProjectConfig) bypasses type safety. This is necessary because generators isn't part of LikeC4ProjectJsonConfigSchema, but it's worth noting the coupling.

♻️ Optional: Avoid double validation

-  const parsed = LikeC4ProjectJsonConfigSchema.safeParse(config)
+  const parsed = LikeC4ProjectJsonConfigSchema.omit({ landingPage: true }).safeParse(config)

This ensures landingPage is validated only once via the explicit LandingPageSchema.safeParse call.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/config/src/schema.ts` around lines 300 - 329, validateProjectConfig
currently validates landingPage twice—once with LandingPageSchema.safeParse and
again when parsing LikeC4ProjectJsonConfigSchema—so change the main parse to
omit landingPage before safeParse (use LikeC4ProjectJsonConfigSchema.omit({
landingPage: true }).safeParse(config)) and then merge the previously
validatedLandingPage into the resulting data; keep the existing GeneratorsSchema
branch but remove the unsafe broad cast (`as unknown as LikeC4ProjectConfig`) by
tightening the inferred type from the omitted-schema parse (use the z.infer
result of the omitted schema) so types line up when you spread in landingPage
and generators.

packages/core/src/types/guards.ts (1)

15-15: Replace the as cast with a record type guard.

Line 15 still depends on a cast, which weakens narrowing and conflicts with the repo’s TS guidance.

♻️ Proposed refactor

+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object'
+}
+
 function _hasProp(value: unknown, path: string): boolean {
   invariant(typeof path === 'string', 'Path must be string')
-  return value != null && typeof value === 'object' && (value as Record<string, unknown>)[path] != null
+  return isRecord(value) && value[path] != null
 }

As per coding guidelines: “TypeScript-first repo; use explicit types. Avoid using any, casts with as.”

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/types/guards.ts` at line 15, The expression in guards.ts
uses a cast "(value as Record<string, unknown>)[path]" which violates the
TS-first rule; instead add and use a proper type guard (e.g., export function
isRecord(v: unknown): v is Record<string, unknown>) and replace the cast with a
runtime check like "isRecord(value) && value[path] != null" inside the existing
predicate (the function that currently returns value != null && typeof value ===
'object' && (value as Record<string, unknown>)[path] != null). Ensure the new
isRecord guard is exported from the same module and used in place of the as-cast
to allow correct narrowing.

packages/leanix-bridge/src/sync-to-leanix.spec.ts (1)

35-83: Expose the updateFactSheet branch in this mock.

The new likec4IdAttribute path can fall back to name/type and then backfill the attribute, but this mock currently discards updateFactSheet, so the suite can't assert that branch. Recording those calls and adding one focused test would protect the new idempotency path from regressing.

Based on learnings, "Aim to cover new features with relevant tests; keep test names descriptive."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/leanix-bridge/src/sync-to-leanix.spec.ts` around lines 35 - 83, The
mock in createSyncMockClient discards updateFactSheet calls so tests can't
assert backfill behavior; modify the graphql handler inside createSyncMockClient
to capture updateFactSheet variables (id and patches) into a local map or array
(e.g., updatedPatchesById) and return the existing updateFactSheet response
(updateFactSheet: { factSheet: { id: variables?.['id'] } }); then expose an
accessor on the returned object (e.g., getUpdatedPatches(id) or getAllUpdates())
so tests can assert that updateFactSheet was called with the expected id and
likec4IdAttribute patches; keep the existing createFactSheet/createRelation
flows intact and update types for the new accessor.

packages/leanix-bridge/src/adr-generation.ts (1)

77-80: Reuse the exported ADR options shape.

This public API redefines the same title/status pair that AdrGenerationOptions already owns, so the two ADR generators can drift apart. Reuse Pick<AdrGenerationOptions, 'title' | 'status'> (or an exported sibling type) here.

♻️ Proposed refactor

+type DriftAdrGenerationOptions = Pick<AdrGenerationOptions, 'title' | 'status'>
+
 export function generateAdrFromDriftReport(
   drift: DriftReport,
-  options: { title?: string; status?: string } = {},
+  options: DriftAdrGenerationOptions = {},
 ): string {

As per coding guidelines, 'Agent types and interfaces should be defined separately and reused across the codebase.'

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/leanix-bridge/src/adr-generation.ts` around lines 77 - 80, The
function generateAdrFromDriftReport currently redefines the { title?: string;
status?: string } shape in its options parameter; update its signature to reuse
the exported AdrGenerationOptions type (e.g., use Pick<AdrGenerationOptions,
'title' | 'status'> or an exported sibling type) so both ADR generators share
the same option shape and cannot drift apart—locate generateAdrFromDriftReport
and replace the inline options type with the reused AdrGenerationOptions-derived
type.

packages/config/src/schema.ts (1)

302-326: Remove unsafe casts and type the parsed values directly.

At Line 314 and Line 326, as casts bypass type safety. Prefer typed schema outputs (or exported aliases) so data and generators are inferred without coercion.

Refactor sketch

+export type LandingPageConfig = z.infer<typeof LandingPageSchema>
+
-  let validatedLandingPage: z.infer<typeof LandingPageSchema> | null = null
+  let validatedLandingPage: LandingPageConfig | null = null

-  let data = parsed.data as unknown as LikeC4ProjectConfig
+  let data: LikeC4ProjectConfig = parsed.data

// outside this hunk, to avoid cast at Line 326:
const GeneratorFnSchema = z.custom<GeneratorFn>((v): v is GeneratorFn => typeof v === 'function')
export const GeneratorsSchema = z.record(z.string(), GeneratorFnSchema)

As per coding guidelines: TypeScript-first repo; use explicit types and avoid casts with as.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/config/src/schema.ts` around lines 302 - 326, The code uses unsafe
"as" casts for parsed results (data and generators); update the Zod schemas and
parsing usage so TypeScript infers correct types instead of coercing: export a
GeneratorFnSchema (e.g., z.custom<GeneratorFn>(...)) and make GeneratorsSchema a
z.record(z.string(), GeneratorFnSchema), ensure LikeC4ProjectJsonConfigSchema is
typed to return LikeC4ProjectConfig via z.infer, then replace the casts around
parsed.data and genParsed.data by using those inferred types (assign parsed.data
directly to a typed variable and return generators as genParsed.data) so no "as"
coerce remains in the logic that builds `data` and the returned object.

packages/config/build.config.ts (1)

10-12: Avoid as cast; prefer a type-safe approach.

The cast as string[] assumes config.external is always a string array, but rolldown supports multiple types for this field. Consider a safer pattern:

🔧 Suggested improvement

     rolldownConfig: (config) => {
-      config.external = [...(config.external as string[]), '@likec4/config']
+      const existing = Array.isArray(config.external) ? config.external : []
+      config.external = [...existing, '@likec4/config']
     },

As per coding guidelines: "Avoid using any, casts with as".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/config/build.config.ts` around lines 10 - 12, The current
rolldownConfig uses an unsafe cast on config.external; update rolldownConfig to
normalize config.external in a type-safe way instead of using "as string[]":
inspect config.external in rolldownConfig (the config.external field may be
undefined, a string, or an array), then produce a new external value that
preserves non-string/array types but safely appends '@likec4/config' when
external is a string or array; use Array.isArray and typeof checks to branch and
assign back to config.external (refer to rolldownConfig and config.external).

devops/vitest.ts (1)

24-26: Consider using distDir helper for consistency.

Line 25 manually constructs the path while line 26 uses the new distEntry helper. For consistency, consider refactoring line 25 to use distDir:

♻️ Suggested refactor

       // More specific first so subpath resolves
-      '@likec4/config/node': resolve(packages('config', 'dist', 'node')),
+      '@likec4/config/node': resolve(distDir('config'), 'node'),
       '@likec4/config': distEntry('config'),

This alias resolves to a directory with an entry defined in package.json exports (./dist/node/index.mjs), which the resolver will find automatically. Line 26 explicitly specifies the entry file, making this intentional asymmetry that works as designed.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@devops/vitest.ts` around lines 24 - 26, Refactor the alias for
'@likec4/config/node' to use the distDir helper instead of manually resolving
packages('config', 'dist', 'node'); specifically replace the
resolve(packages('config', 'dist', 'node')) usage with distDir('config', 'node')
so it consistently mirrors the distEntry('config') pattern and lets the resolver
pick the package export (keep the '@likec4/config' entry using
distEntry('config') unchanged).

packages/generators/src/likec4/operators/base.ts (1)

819-824: Replace cast-based narrowing with a proper type guard.

Lines 824 and 832 use as casts which violates the repo guideline to avoid type assertions. Line 824 can be replaced with a type guard function instead.

♻️ Proposed refactor

+function isZodSchemaCondition(value: unknown): value is z.ZodSchema {
+  return value !== null && typeof value === 'object' && 'safeParse' in value
+}
+
 export function guard(
   condition: Function | z.ZodSchema,
   ...ops: Ops<any>
 ) {
   return operation('guard', ({ ctx, out }) => {
-    if (
-      condition !== null &&
-      typeof condition === 'object' &&
-      'safeParse' in condition
-    ) {
-      const parsed = (condition as z.ZodSchema).safeParse(ctx)
+    if (isZodSchemaCondition(condition)) {
+      const parsed = condition.safeParse(ctx)
       if (parsed.success) {
         executeOnCtx({ ctx: parsed.data, out }, ops)
       } else {
         throw new Error(`Guard failed: ${z.prettifyError(parsed.error)}`)
       }
       return
     }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/generators/src/likec4/operators/base.ts` around lines 819 - 824,
Replace the cast-based narrowing around the "condition" checks with a proper
type guard: implement a predicate like isZodSchema(value): value is z.ZodSchema
and use it where currently checking 'safeParse' in condition and when calling
safeParse, replacing both occurrences of (condition as z.ZodSchema) so the
compiler understands the narrowed type without using "as" casts; update the
logic in the block that uses safeParse and any subsequent branches that relied
on the cast (e.g., the parsed handling) to use the new isZodSchema guard before
invoking condition.safeParse.