@likec4/config 1.48.0 → 1.49.0

package/src/node/load-config.ts

@@ -1,54 +1,128 @@
 import { invariant } from '@likec4/core'
-import { rootLogger } from '@likec4/log'
+import { logger, wrapError } from '@likec4/log'
 import { bundleRequire } from 'bundle-require'
+import { defu } from 'defu'
+import { formatMessagesSync } from 'esbuild'
+import JSON5 from 'json5'
 import * as fs from 'node:fs/promises'
-import { dirname } from 'node:path'
-import { defineConfig } from '../define-config'
+import { basename, dirname, resolve } from 'node:path'
+import { hasAtLeast, isNonNullish, last, omit } from 'remeda'
+import z from 'zod/v4'
 import { isLikeC4JsonConfig, isLikeC4NonJsonConfig } from '../filenames'
 import type { LikeC4ProjectConfig, VscodeURI } from '../schema'
-import { validateProjectConfig } from '../schema'
+import { LikeC4ProjectJsonConfigSchema, validateProjectConfig } from '../schema'
+
+const JsonConfigInputSchema = LikeC4ProjectJsonConfigSchema.pick({
+  extends: true,
+  styles: true,
+}).loose()
+
+type JsonConfigInput = z.infer<typeof JsonConfigInputSchema>
+type JsonConfigStyles = NonNullable<JsonConfigInput['styles']>
+
+const normalizeExtends = (value: JsonConfigInput['extends']): string[] => {
+  if (!value) {
+    return []
+  }
+  return Array.isArray(value) ? value : [value]
+}
+
+const parseJsonConfig = async (filepath: string): Promise<JsonConfigInput> => {
+  const content = await fs.readFile(filepath, 'utf-8')
+  let parsed: unknown
+  try {
+    parsed = JSON5.parse(content.trim() || '{}')
+  } catch (e) {
+    throw wrapError(e, `${filepath}:`)
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${filepath}: Config must be a JSON object`)
+  }
+  const result = JsonConfigInputSchema.safeParse(parsed)
+  if (!result.success) {
+    throw new Error(`${filepath}: Invalid config\n` + z.prettifyError(result.error))
+  }
+  return result.data
+}
+
+const loadJsonConfigs = async (filepath: string, stack: string[]): Promise<[...JsonConfigInput[], JsonConfigInput]> => {
+  if (stack.includes(filepath)) {
+    const cycleStart = stack.indexOf(filepath)
+    const cycle = [...stack.slice(cycleStart), filepath].join(' -> ')
+    throw new Error(`Config extends cycle detected: ${cycle}`)
+  }
+
+  const parsed = await parseJsonConfig(filepath)
+  const extendsPaths = normalizeExtends(parsed.extends)
+  const nextStack = [...stack, filepath]
+
+  const configs: JsonConfigInput[] = []
+  for (const extendPath of extendsPaths) {
+    const resolvedPath = resolve(dirname(filepath), extendPath)
+    configs.push(...await loadJsonConfigs(resolvedPath, nextStack))
+  }
+  return [...configs, parsed]
+}
 
 /**
  * Load LikeC4 Project config file.
  * If filepath is a non-JSON file, it will be bundled and required
  */
-export async function loadConfig(filepath: VscodeURI): Promise<LikeC4ProjectConfig> {
-  const logger = rootLogger.getChild('config')
-  logger.debug`Loading config file: ${filepath.fsPath}`
-  if (isLikeC4JsonConfig(filepath.fsPath)) {
-    try {
-      const content = await fs.readFile(filepath.fsPath, 'utf-8')
-      return validateProjectConfig(content)
-    } catch (err) {
-      logger.error(`Failed to load json config file: ${filepath.fsPath}`, { err })
-      throw err
-    }
+export async function loadConfig(filepath: VscodeURI | string): Promise<LikeC4ProjectConfig> {
+  filepath = typeof filepath === 'string' ? filepath : filepath.fsPath
+  logger.getChild('config').debug`Loading config: ${filepath}`
+
+  const folder = dirname(filepath)
+  const filename = basename(filepath)
+  const implicitcfg = { name: basename(folder) }
+
+  if (isLikeC4JsonConfig(filename)) {
+    const configs = await loadJsonConfigs(resolve(filepath), [])
+    invariant(hasAtLeast(configs, 1), 'Expect at least one config')
+    const rootConfig = omit(last(configs), ['extends', 'styles'])
+    const stylesChain = configs
+      .map(config => config.styles)
+      .filter(isNonNullish)
+
+    const mergedStyles = stylesChain.length > 0
+      ? defu({}, ...stylesChain.reverse())
+      : undefined
+
+    return validateProjectConfig({
+      ...implicitcfg,
+      ...rootConfig,
+      ...(mergedStyles ? { styles: mergedStyles } : {}),
+    })
   }
 
-  invariant(isLikeC4NonJsonConfig(filepath.fsPath), `Invalid config file: ${filepath.fsPath}`)
-  try {
-    const cwd = dirname(filepath.fsPath)
-    const { mod } = await bundleRequire({
-      filepath: filepath.fsPath,
-      cwd,
-      esbuildOptions: {
-        resolveExtensions: ['.ts', '.mts', '.cts', '.mjs', '.js', '.cjs'],
-        plugins: [{
-          name: 'likec4-config',
-          setup(build) {
-            /**
-             * Intercept @likec4/config and likec4/config imports
-             */
-            build.onResolve({ filter: /^@?likec4\/config$/ }, (args) => ({
-              path: args.path,
-              namespace: 'likec4-config',
-            }))
-            /**
-             * Mock implementation, this allows to skip redundant bundling @likec4/config
-             */
-            build.onLoad({ filter: /.*/, namespace: 'likec4-config' }, (_args) => {
-              return {
-                contents: `
+  invariant(isLikeC4NonJsonConfig(filename), `Invalid name for config file: ${filepath}`)
+  const { mod } = await bundleRequire({
+    filepath,
+    cwd: folder,
+    esbuildOptions: {
+      resolveExtensions: ['.ts', '.mts', '.cts', '.mjs', '.js', '.cjs'],
+      plugins: [{
+        name: 'likec4-config',
+        setup(build) {
+          /**
+           * Intercept @likec4/config and likec4/config imports
+           */
+          build.onResolve({ filter: /^@?likec4\/config$/ }, (args) => ({
+            path: args.path,
+            namespace: 'likec4-config',
+          }))
+          build.onEnd((result) => {
+            const messages = formatMessagesSync(result.errors, { kind: 'error' })
+            for (const message of messages) {
+              logger.error(message)
+            }
+          })
+          /**
+           * Mock implementation, this allows to skip redundant bundling @likec4/config
+           */
+          build.onLoad({ filter: /.*/, namespace: 'likec4-config' }, (_args) => {
+            return {
+              contents: `
 // Mock implementation to allow loading config files without bundling @likec4/config
 function mock(x) { return x }
 export {
@@ -58,16 +132,12 @@ export {
   mock as defineTheme,
   mock as defineThemeColor,
 }`,
-                loader: 'js',
-              }
-            })
-          },
-        }],
-      },
-    })
-    return defineConfig(mod?.default ?? mod)
-  } catch (err) {
-    logger.error(`Failed to load config file: ${filepath.fsPath}`, { err })
-    throw err
-  }
+              loader: 'js',
+            }
+          })
+        },
+      }],
+    },
+  })
+  return validateProjectConfig(Object.assign(implicitcfg, mod?.default ?? mod))
 }

package/src/schema.image-alias.ts

@@ -5,6 +5,14 @@ const IMAGE_ALIAS_KEY_REGEX = /^@[A-Za-z0-9_-]*$/
 // Relative path (no leading slash, drive letter, or protocol)
 const IMAGE_ALIAS_VALUE_REGEX = /^(?!\/|[A-Za-z]:[\\\/])(?!.*:\/\/).*$/
 
+const ImageAliasKey = z
+  .string()
+  .min(1, 'Image alias key cannot be empty')
+  .regex(
+    IMAGE_ALIAS_KEY_REGEX,
+    'Image alias key must match /^@\\w+$/',
+  )
+
 // Schema for an image alias value: must be a non-empty string representing a relative path (no leading slash, drive letter, or protocol).
 const ImageAliasValue = z
   .string()
@@ -15,54 +23,10 @@ const ImageAliasValue = z
   )
 
 export const ImageAliasesSchema = z.record(
-  z.string(), // PLAIN key schema - zod JSON schema export-safe.
+  ImageAliasKey, // PLAIN key schema - zod JSON schema export-safe.
   ImageAliasValue,
 ).meta({
+  id: 'ImageAliases',
   description:
     'Map of image alias prefixes to relative paths (keys must match /^@\\w+$/; values must be relative paths without protocol or leading slash).',
 })
-
-// This just allows us to have a typed validate function.
-type LikeC4ImageAliasConfig = z.infer<typeof ImageAliasesSchema>
-
-export function validateImageAliases(imageAliases?: LikeC4ImageAliasConfig) {
-  const invalidKeys: string[] = []
-  const invalidValues: string[] = []
-
-  if (imageAliases) {
-    for (const [key, value] of Object.entries(imageAliases)) {
-      if (!IMAGE_ALIAS_KEY_REGEX.test(key)) {
-        invalidKeys.push(key)
-      }
-      // Value regex is technically already enforced by zod,
-      // so this check is purely defensive.
-      if (!IMAGE_ALIAS_VALUE_REGEX.test(value)) {
-        invalidValues.push(`${key} -> ${value}`)
-      }
-    }
-  }
-
-  if (invalidKeys.length || invalidValues.length) {
-    const parts: string[] = []
-    if (invalidKeys.length) {
-      parts.push(
-        `Invalid image alias key(s): ${
-          invalidKeys
-            .map((k) => JSON.stringify(k))
-            .join(', ')
-        } (must match ${IMAGE_ALIAS_KEY_REGEX})`,
-      )
-    }
-    if (invalidValues.length) {
-      parts.push(
-        `Invalid image alias value(s): ${
-          invalidValues
-            .map((kv) => JSON.stringify(kv))
-            .join(', ')
-        } (must match ${IMAGE_ALIAS_VALUE_REGEX})`,
-      )
-    }
-
-    throw new Error(parts.join(' | '))
-  }
-}

package/src/schema.include.ts

@@ -13,85 +13,47 @@ const IncludePathValue = z
     'Include path must be a relative path (no leading slash, drive letter, or protocol)',
   )
 
-export const IncludeConfigSchema = z.strictObject({
-  paths: z.array(IncludePathValue)
-    .min(1, 'Include paths cannot be empty')
-    .meta({
-      description: [
-        'Additional relative directory paths to include LikeC4 source files from, searched recursively.',
-        'Paths are relative to the project folder (the folder containing this config file).',
-        'Example: ["../shared", "../common/specs"]',
-      ].join('\n'),
-    }),
-  maxDepth: z.number()
-    .int()
-    .min(1)
-    .max(20)
-    .default(3)
-    .meta({
-      description: [
-        'Maximum directory depth to scan when searching for .c4 files in include paths.',
-        'Prevents excessive scanning of deeply nested directories.',
-        'Default: 3',
-      ].join('\n'),
-    }),
-  fileThreshold: z.number()
-    .int()
-    .min(1)
-    .default(30)
-    .meta({
-      description: [
-        'Maximum number of files to load from include paths before warning.',
-        'Helps identify performance issues from accidentally including large directories.',
-        'Default: 30',
-      ].join('\n'),
-    }),
-})
-  .meta({
-    id: 'include-config',
-    description: 'Configuration for including additional LikeC4 source files',
+export const IncludeSchema = z
+  .strictObject({
+    paths: z.array(IncludePathValue)
+      .meta({
+        description: [
+          'Additional relative directory paths to include LikeC4 source files from, searched recursively.',
+          'Paths are relative to the project folder (the folder containing this config file).',
+          'Example: ["../shared", "../common/specs"]',
+        ].join('\n'),
+      }),
+    maxDepth: z.number()
+      .int()
+      .min(1)
+      .max(20)
+      .default(3)
+      .meta({
+        description: [
+          'Maximum directory depth to scan when searching for .c4 files in include paths.',
+          'Prevents excessive scanning of deeply nested directories.',
+          'Default: 3',
+        ].join('\n'),
+      }),
+    fileThreshold: z.number()
+      .int()
+      .min(1)
+      .max(10000)
+      .default(30)
+      .meta({
+        description: [
+          'Maximum number of files to load from include paths before warning.',
+          'Helps identify performance issues from accidentally including large directories.',
+          'Default: 30',
+        ].join('\n'),
+      }),
   })
-
-export type IncludeConfig = z.infer<typeof IncludeConfigSchema>
-
-export const IncludeSchema = IncludeConfigSchema
-  .optional()
   .meta({
+    id: 'include-config',
     description: [
       'Configuration for including additional LikeC4 source files from other directories.',
       'Example: { "paths": ["../shared", "../common/specs"], "maxDepth": 5, "fileThreshold": 50 }',
     ].join('\n'),
   })
 
-type LikeC4IncludeConfig = z.infer<typeof IncludeSchema>
-
-export function normalizeIncludeConfig(include?: LikeC4IncludeConfig): IncludeConfig {
-  if (!include) {
-    return { paths: [], maxDepth: 3, fileThreshold: 30 }
-  }
-  return include
-}
-
-export function validateIncludePaths(include?: LikeC4IncludeConfig): void {
-  if (!include?.paths) {
-    return
-  }
-
-  const invalidPaths: string[] = []
-
-  for (const path of include.paths) {
-    if (!RELATIVE_PATH_REGEX.test(path)) {
-      invalidPaths.push(path)
-    }
-  }
-
-  if (invalidPaths.length > 0) {
-    throw new Error(
-      `Invalid include path(s): ${
-        invalidPaths
-          .map((p) => JSON.stringify(p))
-          .join(', ')
-      } (must be relative paths without leading slash, drive letter, or protocol)`,
-    )
-  }
-}
+export type IncludeConfig = z.infer<typeof IncludeSchema>

package/src/schema.theme.ts

@@ -1,6 +1,5 @@
 // oxlint-disable no-unsafe-type-assertion
 import type {
-  ColorLiteral,
   ElementColorValues,
   RelationshipColorValues,
   ThemeColorValues,
@@ -15,6 +14,7 @@ import {
   ThemeColors,
 } from '@likec4/core/styles'
 import type {
+  ColorLiteral,
   CustomColor,
   LikeC4ProjectStyleDefaults,
   LikeC4ProjectStylesConfig,
@@ -23,7 +23,6 @@ import type {
   ThemeColor,
 } from '@likec4/core/types'
 import { exact } from '@likec4/core/types'
-import { fromKeys } from 'remeda'
 import z from 'zod/v4'
 
 const opacity = z
@@ -36,57 +35,74 @@ const opacity = z
   })
 
 const shape = z
-  .literal(ElementShapes)
+  .enum(ElementShapes)
   .meta({ id: 'ElementShape' })
 
 const border = z
-  .literal(BorderStyles)
+  .enum(BorderStyles)
   .meta({ id: 'BorderStyle' })
 
 const size = z
-  .literal(Sizes)
+  .enum(Sizes)
   .meta({ id: 'ElementSize' })
 
 const iconPosition = z
-  .literal(IconPositions)
+  .enum(IconPositions)
   .meta({ id: 'IconPosition' })
 
 const arrow = z
-  .literal(RelationshipArrowTypes)
+  .enum(RelationshipArrowTypes)
   .meta({ id: 'ArrowType' })
 
 const line = z
-  .literal(['dashed', 'solid', 'dotted'])
+  .enum(['dashed', 'solid', 'dotted'])
   .meta({ id: 'LineType' })
 
 const themeColor = z
-  .literal(ThemeColors)
-  .meta({ id: 'ThemeColor' })
+  .enum(ThemeColors)
+  .meta({ id: 'ThemeColorName' })
 
 const customColor = z
-  .string()
-  .min(1, 'Custom color name cannot be empty')
+  .custom<string & Record<never, never>>()
+  .refine(v => typeof v === 'string', 'Custom color name must be a string')
   .transform(value => value as unknown as CustomColor)
   .meta({ id: 'CustomColorName' })
 
-// type ColorNameLiteral = ThemeColor | string & Record<never, never>
+// const color = z.custom<ColorNameLiteral>(
+//   (v) => {
+//     if (typeof v !== 'string' || v.length === 0) {
+//       throw new Error()
+//     }
+//     return v
+//   },
+//   {
+//     error: 'Invalid color name',
+//   },
+// )
+//   .meta({ id: 'ColorName' })
 
-const color = z
-  // .custom<ColorNameLiteral>(v => typeof v === 'string')
-  .union([
-    themeColor,
-    customColor,
-  ])
+const color = themeColor.or(customColor)
   .transform(value => value as ThemeColor)
   .meta({ id: 'ColorName' })
+// const color = themeColor.or(
+//   // z.never(),
+//   z.string().spa(),
+// ).meta({ id: 'ColorName' })
+// // .custom<ColorNameLiteral>(v => typeof v === 'string')
+// .union([
+//   themeColor,
+//   customColor,
+// ])
+// .transform(value => value as ThemeColor)
+// .meta({ id: 'ColorName' })
 
 const colorValue = z
   .string()
   .min(1, 'Color value cannot be empty')
-  .transform(value => value as ColorLiteral)
+  // .transform(value => value as ColorLiteral)
   .meta({
     id: 'ColorLiteral',
-    description: 'Color value in any valid CSS format: hex, rgb, rgba, hsl, hsla ...',
+    // description: 'Color value in any valid CSS format: hex, rgb, rgba, hsl, hsla ...',
   })
 
 // const ColorSchema = z.union([ColorValue, LightDarkTuple])
@@ -116,51 +132,40 @@ const RelationshipColorValuesSchema = z
   .transform(value => value as RelationshipColorValues)
 
 const StrictThemeColorValuesSchema = z.strictObject({
-  elements: z
-    .union([colorSchema, ElementColorValuesSchema])
-    .meta({ description: 'Element color value (or a breakdown of specific color values)' })
-    .transform((value): ElementColorValues => {
-      if (typeof value === 'string') {
-        return computeColorValues(value).elements
-      }
-      return value
-    }),
-  relationships: z
-    .union([colorSchema, RelationshipColorValuesSchema])
+  elements: ElementColorValuesSchema
+    .or(
+      colorSchema.transform(v => computeColorValues(v as ColorLiteral).elements),
+    )
     .meta({
-      description: 'Relationship color value (or a breakdown of specific color values)',
-    })
-    .transform((value): RelationshipColorValues => {
-      if (typeof value === 'string') {
-        return computeColorValues(value).relationships
-      }
-      return value
+      description: 'Exact color value (hex, rgb, rgba, hsl, hsla ...) or break down of specific color values',
     }),
+  relationships: RelationshipColorValuesSchema
+    .or(
+      colorSchema.transform(v => computeColorValues(v as ColorLiteral).relationships),
+    )
+    .meta({ description: 'Exact color value (hex, rgb, rgba, hsl, hsla ...) or break down of specific color values' }),
 })
-  .meta({ id: 'StrictThemeColorValues' })
+  .transform(value => value as ThemeColorValues)
+  .meta({
+    id: 'StrictThemeColorValues',
+    description: 'Exact color value (hex, rgb, rgba, hsl, hsla ...) or break down of specific color value',
+  })
 
-export const ThemeColorValuesSchema = z
-  .union([
-    colorSchema,
-    StrictThemeColorValuesSchema,
-  ])
+export const ThemeColorValuesSchema = StrictThemeColorValuesSchema.or(
+  colorSchema.transform(v => computeColorValues(v as ColorLiteral)),
+)
+  .transform(value => value as ThemeColorValues)
   .meta({
     id: 'ThemeColorValues',
     description: 'Exact value (hex, rgb, rgba, hsl, hsla ...) or break down of specific color values',
   })
-  .transform((value): ThemeColorValues => {
-    if (typeof value === 'string') {
-      return computeColorValues(value)
-    }
-    return value
-  })
+
 export type ThemeColorValuesInput = z.input<typeof ThemeColorValuesSchema>
 
-const ThemeColorsSchema = z.record(color, ThemeColorValuesSchema)
-  .meta({
-    id: 'ThemeColors',
-    description: 'Override theme colors',
-  })
+const ThemeColorsSchema = z.partialRecord(
+  color,
+  ThemeColorValuesSchema,
+)
   .transform(value => value as Record<ThemeColor, ThemeColorValues>)
 
 const DimensionsSchema = z.strictObject({
@@ -168,26 +173,23 @@ const DimensionsSchema = z.strictObject({
   height: z.number().min(50),
 }).meta({
   id: 'Dimensions',
-  description: 'Dimensions',
+  description: 'Defines dimensions for theme size',
 })
 
-const LikeC4Config_Styles_Theme_Sizes = z
-  .strictObject(
-    fromKeys(Sizes, () => DimensionsSchema.optional()),
-  )
-  .meta({
-    id: 'ThemeSizes',
-    description: 'Override theme sizes',
-  })
+const LikeC4Config_Styles_Theme_Sizes = z.partialRecord(size, DimensionsSchema)
 
 export const LikeC4Config_Styles_Theme = z
   .strictObject({
-    colors: ThemeColorsSchema.optional(),
-    sizes: LikeC4Config_Styles_Theme_Sizes.optional(),
+    colors: ThemeColorsSchema.optional().meta({
+      description: 'Override theme colors',
+    }),
+    sizes: LikeC4Config_Styles_Theme_Sizes.optional().meta({
+      description: 'Override theme sizes',
+    }),
   })
   .meta({
     id: 'ThemeCustomization',
-    description: 'Theme customization',
+    description: 'Customize theme colors and sizes',
   })
   .transform(({ colors, sizes }): LikeC4ProjectTheme => {
     return exact({
@@ -207,8 +209,6 @@ const LikeC4Config_Styles_Defaults_Group = z
   })
   .meta({
     id: 'GroupDefaultStyleValues',
-    description:
-      'Override default values for group style properties\nThese values will be used if such property is not defined',
   })
 
 const LikeC4Config_Styles_Defaults_Relationship = z
@@ -239,15 +239,17 @@ const LikeC4Config_Styles_Defaults = z
     size: size.optional().meta({ description: 'Default size for elements' }),
     shape: shape.optional().meta({ description: 'Default shape for elements' }),
     iconPosition: iconPosition.optional().meta({ description: 'Default icon position for elements' }),
-    group: LikeC4Config_Styles_Defaults_Group.optional().meta({ description: 'Default style values for groups' }),
+    group: LikeC4Config_Styles_Defaults_Group.optional().meta({
+      description:
+        'Override default values for group style properties\nThese values will be used if such property is not defined',
+    }),
     relationship: LikeC4Config_Styles_Defaults_Relationship.optional().meta({
-      description: 'Default style values for relationships',
+      description:
+        'Override default values for relationship style properties\nThese values will be used if such property is not defined',
     }),
   })
   .meta({
     id: 'DefaultStyleValues',
-    description:
-      'Override default values for style properties\nThese values will be used if such property is not defined',
   })
 
 const LikeC4Config_Styles_CustomStylesheets = z
@@ -259,18 +261,20 @@ const LikeC4Config_Styles_CustomStylesheets = z
   ])
   .meta({
     id: 'CustomStylesheets',
-    description: 'Custom CSS (or list of CSS files) to be included in the generated diagrams',
   })
 
 export const LikeC4StylesConfigSchema = z
   .strictObject({
-    theme: LikeC4Config_Styles_Theme.optional(),
-    defaults: LikeC4Config_Styles_Defaults.optional(),
-    customCss: LikeC4Config_Styles_CustomStylesheets.optional(),
-  })
-  .meta({
-    id: 'StylesConfiguration',
-    description: 'Project styles customization',
+    theme: LikeC4Config_Styles_Theme.optional().meta({
+      description: 'Project theme customization',
+    }),
+    defaults: LikeC4Config_Styles_Defaults.optional().meta({
+      description:
+        'Override default values for style properties\nThese values will be used if such property is not defined',
+    }),
+    customCss: LikeC4Config_Styles_CustomStylesheets.optional().meta({
+      description: 'Custom CSS (or list of CSS files) to be included in the generated diagrams',
+    }),
   })
   .transform(({ theme, defaults, customCss }): LikeC4ProjectStylesConfig =>
     exact({
@@ -294,7 +298,7 @@ function normalizeDefaults(
     ...rest,
     relationship: relationship && exact(relationship) satisfies LikeC4ProjectStyleDefaults['relationship'],
     group: group && exact(group) satisfies LikeC4ProjectStyleDefaults['group'],
-  })
+  }) satisfies LikeC4ProjectStyleDefaults
 }
 
 function normalizeStylesheets(