@likec4/config 1.39.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2025 Denis Davydkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# `@likec4/config`
+
+<a href="https://www.npmjs.com/package/%40likec4%2Fconfig" target="_blank">![NPM Version](https://img.shields.io/npm/v/%40likec4%2Fconfig)</a>
+<a href="https://www.npmjs.com/package/%40likec4%2Fconfig" target="_blank">![NPM Downloads](https://img.shields.io/npm/dm/%40likec4%2Fconfig)</a>
+
+Configuration utilities and schema for LikeC4 projects.
+
+Provides:
+
+- Project config schema (Zod) and JSON Schema for editors
+- Helpers to define TypeScript configs and reusable generators
+- Runtime parsers/validators for JSON/JSON5 configs
+- Node helper to load config files from disk
+- Filename predicates to detect config files
+
+Docs – https://likec4.dev/
+
+## Install
+
+```bash
+pnpm add -D @likec4/config
+```
+
+## Recognized filenames
+
+These are treated as LikeC4 project configuration files:
+
+- `.likec4rc`
+- `.likec4.config.json`
+- `likec4.config.json`
+- `likec4.config.js`
+- `likec4.config.mjs`
+- `likec4.config.ts`
+- `likec4.config.mts`
+
+See `ConfigFilenames` in `@likec4/config` and helpers `isLikeC4Config(...)`, `isLikeC4JsonConfig(...)`, `isLikeC4NonJsonConfig(...)`.
+
+## Quick start
+
+### JSON/JSON5 config (e.g. `.likec4rc`)
+
+```json5
+{
+  // optional: reference JSON Schema for editor validation
+  "$schema": "node_modules/@likec4/config/schema.json",
+  "name": "my-project",
+  "title": "My Project",
+  "exclude": ["**/node_modules/**", "**/.cache/**"]
+}
+```
+
+### TypeScript/JavaScript Config
+
+You can define a config using TypeScript or JavaScript. The config file can be any of the following:
+
+- `likec4.config.js`
+- `likec4.config.mjs`
+- `likec4.config.ts`
+- `likec4.config.mts`
+
+These config files allow you to define custom generators:
+
+```ts
+import { defineConfig } from '@likec4/config'
+
+export default defineConfig({
+  name: 'my-project',
+  title: 'My Project',
+  generators: {
+    'hello': async ({ likec4model, ctx }) => {
+      for (const view of likec4model.views()) {
+        // resolve folder containing the source file of the view
+        const { folder } = ctx.locate(view)
+        // write view to a JSON file
+        await ctx.write({
+          path: [folder, 'views', `${view.id}.json`],
+          content: JSON.stringify(view.$view),
+        })
+      }
+    },
+  },
+})
+```
+
+You can run your generator via CLI:
+
+```bash
+likec4 gen hello
+```
+
+In multi-project workspace use:
+
+```bash
+likec4 gen hello --project my-project
+# Other options
+likec4 gen hello --project my-project --use-dot
+```
+
+There is also helper function `defineGenerators` to define reusable generators:
+
+```ts
+// shared_generators.ts
+import { defineGenerators } from '@likec4/config'
+
+export default defineGenerators({
+  'hello': async ({ likec4model, ctx }) => {
+    await ctx.write({
+      path: 'hello.txt', // relative to the project root
+      content: `Project: ${likec4model.project.id}`,
+    })
+  },
+})
+
+// likec4.config.ts
+import { defineConfig } from '@likec4/config'
+import generators from './shared_generators'
+
+export default defineConfig({
+  name: 'my-project',
+  title: 'My Project',
+  generators,
+})
+```
+
+## Programmatic usage
+
+### Validate/parse JSON config
+
+```ts
+import { validateProjectConfig } from '@likec4/config'
+
+const json = `
+{
+  name: "my-project" // JSON5 is supported
+}
+`
+const cfg = validateProjectConfig(json)
+// or
+const cfg2 = validateProjectConfig({ name: 'my-project' })
+```
+
+### Load config from TypeScript/JavaScript
+
+Available only in Node.js via `@likec4/config/node`:
+
+```ts
+import { loadConfig } from '@likec4/config/node'
+import { URI } from 'vscode-uri'
+
+const uri = URI.file('/path/to/likec4.config.ts')
+const project = await loadConfig(uri)
+```
+
+### Detect config filenames
+
+```ts
+import { ConfigFilenames, isLikeC4Config, isLikeC4JsonConfig, isLikeC4NonJsonConfig } from '@likec4/config'
+
+for (const name of ConfigFilenames) {
+  if (!isLikeC4Config(name)) {
+    // handle other files
+  }
+  if (isLikeC4JsonConfig(name)) {
+    // handle JSON config
+  }
+  if (isLikeC4NonJsonConfig(name)) {
+    // handle TS/JS config
+  }
+}
+```
+
+## JSON Schema
+
+The JSON Schema is published at `@likec4/config/schema.json` and mirrors the Zod schema.
+
+Fields:
+
+- `name` (required): unique project id within the workspace
+- `title` (optional): human-readable project title
+- `contactPerson` (optional): maintainer/author
+- `exclude` (optional): array of glob patterns (picomatch) to exclude (defaults to `['**/node_modules/**']`)
+
+## Getting help
+
+We are always happy to help you get started:
+
+- [Join Discord community](https://discord.gg/86ZSpjKAdA) – it is the easiest way to get help
+- [GitHub Discussions](https://github.com/likec4/likec4/discussions) – ask anything about the project or give feedback
+
+## Contributors
+
+<a href="https://github.com/likec4/likec4/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=likec4/likec4" />
+</a>
+
+[Become a contributor](../../CONTRIBUTING.md)
+
+## Support development
+
+LikeC4 is a MIT-licensed open source project with its ongoing development made possible entirely by your support.\
+If you like the project, please consider contributing financially to help grow and improve it.\
+You can support us via [OpenCollective](https://opencollective.com/likec4) or [GitHub Sponsors](https://github.com/sponsors/likec4).
+
+## License
+
+This project is released under the [MIT License](LICENSE)

package/dist/define-config.d.ts

@@ -0,0 +1,45 @@
+import { type GeneratorFn, type LikeC4ProjectConfig } from './schema';
+/**
+ * Defines LikeC4 Project, allows custom generators that can be executed using CLI:
+ *
+ * `$ likec4 gen <generator-name>`
+ *
+ * or VSCode command `LikeC4: Run code generator`
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   name: 'my-project',
+ *   title: 'My Project',
+ *   exclude: ['picomatch pattern'],
+ *   generators: {
+ *     'my-generator': async ({ likec4model, ctx }) => {
+ *       await ctx.write('my-generator.txt', likec4model.project.id)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function defineConfig<const C extends LikeC4ProjectConfig>(config: C): C;
+/**
+ * Define reusable custom generators
+ *
+ * @example
+ * ```ts
+ * // generators.ts
+ * export default defineGenerators({
+ *   'my-generator': async ({ likec4model, ctx }) => {
+ *     await ctx.write('my-generator.txt', likec4model.project.id)
+ *   }
+ * })
+ *
+ * // likec4.config.ts
+ * import generators from './generators'
+ *
+ * export default defineConfig({
+ *   name: 'my-project',
+ *   generators,
+ * })
+ * ```
+ */
+export declare function defineGenerators<const G extends Record<string, GeneratorFn>>(generators: G): G;

package/dist/define-config.mjs

@@ -0,0 +1,7 @@
+import { GeneratorsSchema, LikeC4ProjectConfigSchema } from "./schema.mjs";
+export function defineConfig(config) {
+  return LikeC4ProjectConfigSchema.parse(config);
+}
+export function defineGenerators(generators) {
+  return GeneratorsSchema.parse(generators);
+}

package/dist/filenames.d.ts

@@ -0,0 +1,16 @@
+declare const configJsonFilenames: readonly [".likec4rc", ".likec4.config.json", "likec4.config.json"];
+declare const configNonJsonFilenames: readonly ["likec4.config.js", "likec4.config.mjs", "likec4.config.ts", "likec4.config.mts"];
+export declare const ConfigFilenames: readonly [".likec4rc", ".likec4.config.json", "likec4.config.json", "likec4.config.js", "likec4.config.mjs", "likec4.config.ts", "likec4.config.mts"];
+/**
+ * Checks if the given filename is a LikeC4 JSON config file (JSON, RC).
+ */
+export declare function isLikeC4JsonConfig(filename: string): filename is typeof configJsonFilenames[number];
+/**
+ * Checks if the given filename is a LikeC4 non-JSON config file (JS, MJS, TS, MTS)
+ */
+export declare function isLikeC4NonJsonConfig(filename: string): filename is typeof configNonJsonFilenames[number];
+/**
+ * Checks if the given filename is a LikeC4 config file (JSON or non-JSON)
+ */
+export declare function isLikeC4Config(filename: string): filename is typeof ConfigFilenames[number];
+export {};

package/dist/filenames.mjs

@@ -0,0 +1,34 @@
+const configJsonFilenames = [
+  ".likec4rc",
+  ".likec4.config.json",
+  "likec4.config.json"
+];
+const configNonJsonFilenames = [
+  "likec4.config.js",
+  "likec4.config.mjs",
+  "likec4.config.ts",
+  "likec4.config.mts"
+];
+export const ConfigFilenames = [
+  ...configJsonFilenames,
+  ...configNonJsonFilenames
+];
+export function isLikeC4JsonConfig(filename) {
+  for (const ext of configJsonFilenames) {
+    if (filename.endsWith(ext)) {
+      return true;
+    }
+  }
+  return false;
+}
+export function isLikeC4NonJsonConfig(filename) {
+  for (const ext of configNonJsonFilenames) {
+    if (filename.endsWith(ext)) {
+      return true;
+    }
+  }
+  return false;
+}
+export function isLikeC4Config(filename) {
+  return isLikeC4JsonConfig(filename) || isLikeC4NonJsonConfig(filename);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { GeneratorFn, GeneratorFnContext, GeneratorFnParams, LikeC4ProjectConfig, LikeC4ProjectJsonConfig, } from './schema';
+export { serializableLikeC4ProjectConfig, validateProjectConfig } from './schema';
+export { ConfigFilenames, isLikeC4Config, isLikeC4JsonConfig, isLikeC4NonJsonConfig, } from './filenames';
+export { defineConfig, defineGenerators, } from './define-config';

package/dist/index.mjs

@@ -0,0 +1,11 @@
+export { serializableLikeC4ProjectConfig, validateProjectConfig } from "./schema.mjs";
+export {
+  ConfigFilenames,
+  isLikeC4Config,
+  isLikeC4JsonConfig,
+  isLikeC4NonJsonConfig
+} from "./filenames.mjs";
+export {
+  defineConfig,
+  defineGenerators
+} from "./define-config.mjs";

package/dist/logger.d.ts

@@ -0,0 +1 @@
+export declare const logger: any;

package/dist/logger.mjs

@@ -0,0 +1,2 @@
+import { rootLogger } from "@likec4/log";
+export const logger = rootLogger.getChild("config");

package/dist/node/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../index';
+export { loadConfig } from './load-config';

package/dist/node/index.mjs

@@ -0,0 +1,2 @@
+export * from "../index.mjs";
+export { loadConfig } from "./load-config.mjs";

package/dist/node/load-config.d.ts

@@ -0,0 +1,7 @@
+import type { URI } from 'vscode-uri';
+import { type LikeC4ProjectConfig } from '../schema';
+/**
+ * Load LikeC4 Project config file.
+ * If filepath is a non-JSON file, it will be bundled and required
+ */
+export declare function loadConfig(filepath: URI): Promise<LikeC4ProjectConfig>;

package/dist/node/load-config.mjs

@@ -0,0 +1,29 @@
+import { invariant } from "@likec4/core";
+import { bundleNRequire } from "bundle-n-require";
+import * as fs from "node:fs/promises";
+import { defineConfig } from "../define-config.mjs";
+import { isLikeC4JsonConfig, isLikeC4NonJsonConfig } from "../filenames.mjs";
+import { logger } from "../logger.mjs";
+import { validateProjectConfig } from "../schema.mjs";
+export async function loadConfig(filepath) {
+  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;
+    }
+  }
+  invariant(isLikeC4NonJsonConfig(filepath.fsPath), `Invalid config file: ${filepath.fsPath}`);
+  try {
+    const { mod } = await bundleNRequire(filepath.fsPath, {
+      interopDefault: true
+    });
+    return defineConfig(mod?.default ?? mod);
+  } catch (err) {
+    logger.error(`Failed to load config file: ${filepath.fsPath}`, { err });
+    throw err;
+  }
+}

package/dist/schema.d.ts

@@ -0,0 +1,149 @@
+import type { DeploymentElementModel, DeploymentRelationModel, ElementModel, LikeC4Model, LikeC4ViewModel, RelationshipModel } from '@likec4/core/model';
+import type { aux, ProjectId } from '@likec4/core/types';
+import type Stream from 'node:stream';
+import type { URI } from 'vscode-uri';
+import * as z from 'zod';
+export declare const LikeC4ProjectJsonConfigSchema: z.ZodObject<{
+    name: z.ZodPipe<z.ZodString, z.ZodTransform<any, string>>;
+    title: z.ZodOptional<z.ZodString>;
+    contactPerson: z.ZodOptional<z.ZodString>;
+    imageAliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.z.core.$strip>;
+export type LikeC4ProjectJsonConfig = z.input<typeof LikeC4ProjectJsonConfigSchema>;
+export declare const GeneratorsSchema: z.ZodRecord<z.ZodString, z.ZodCustom<Function, Function>>;
+export declare const LikeC4ProjectConfigSchema: z.ZodObject<{
+    name: z.ZodPipe<z.ZodString, z.ZodTransform<any, string>>;
+    title: z.ZodOptional<z.ZodString>;
+    contactPerson: z.ZodOptional<z.ZodString>;
+    imageAliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    generators: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<Function, Function>>>;
+}, z.z.core.$strip>;
+export interface GeneratorFnContext {
+    /**
+     * Workspace root directory
+     */
+    readonly workspace: URI;
+    /**
+     * Current project
+     */
+    readonly project: {
+        /**
+         * Project name
+         */
+        readonly id: ProjectId;
+        readonly title?: string;
+        /**
+         * Project folder
+         */
+        readonly folder: URI;
+    };
+    /**
+     * Returns the location of the specified element, relation, view or deployment element
+     */
+    locate(target: ElementModel | RelationshipModel | DeploymentRelationModel | LikeC4ViewModel | DeploymentElementModel): {
+        /**
+         * Range inside the source file
+         */
+        range: {
+            start: {
+                line: number;
+                character: number;
+            };
+            end: {
+                line: number;
+                character: number;
+            };
+        };
+        /**
+         * Full path to the source file
+         */
+        document: URI;
+        /**
+         * Document path relative to the project folder
+         */
+        relativePath: string;
+        /**
+         * Folder, containing the source file ("dirname" of document)
+         */
+        folder: string;
+        /**
+         * Source file name ("basename" of document)
+         */
+        filename: string;
+    };
+    /**
+     * Write a file
+     * @param path - Path to the file, either absolute or relative to the project folder
+     *               All folders will be created automatically
+     * @param content - Content of the file
+     */
+    write(file: {
+        path: string | string[] | URI;
+        content: string | NodeJS.ArrayBufferView | Iterable<string | NodeJS.ArrayBufferView> | AsyncIterable<string | NodeJS.ArrayBufferView> | Stream;
+    }): Promise<void>;
+    /**
+     * Abort the process
+     */
+    abort(reason?: string): never;
+}
+export type GeneratorFnParams = {
+    /**
+     * LikeC4 model
+     */
+    likec4model: LikeC4Model<aux.UnknownLayouted>;
+    /**
+     * Generator context
+     */
+    ctx: GeneratorFnContext;
+};
+export interface GeneratorFn {
+    (params: GeneratorFnParams): Promise<void> | void;
+}
+/**
+ * LikeC4 project configuration
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   name: 'my-project',
+ *   generators: {
+ *     'my-generator': async ({ likec4model, ctx }) => {
+ *       await ctx.write('my-generator.txt', likec4model.project.id)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export type LikeC4ProjectConfig = z.input<typeof LikeC4ProjectJsonConfigSchema> & {
+    /**
+     * Add custom generators to the project
+     * @example
+     * ```ts
+     * export default defineConfig({
+     *   name: 'my-project',
+     *   generators: {
+     *     'my-generator': async ({ likec4model, ctx }) => {
+     *       await ctx.write('my-generator.txt', likec4model.project.id)
+     *     }
+     *   }
+     * })
+     * ```
+     *
+     * Execute generator:
+     * ```bash
+     * likec4 gen my-generator
+     * ```
+     */
+    generators?: Record<string, GeneratorFn> | undefined;
+};
+/**
+ * Validates JSON string or JSON object into a LikeC4ProjectConfig object.
+ */
+export declare function validateProjectConfig<C extends string | Record<string, unknown>>(config: C): LikeC4ProjectConfig;
+/**
+ * Converts a LikeC4ProjectConfig object into a LikeC4ProjectJsonConfig object.
+ * Omit generators property (as it is not serializable)
+ */
+export declare function serializableLikeC4ProjectConfig({ generators, ...config }: LikeC4ProjectConfig): LikeC4ProjectJsonConfig;

package/dist/schema.image-alias.d.ts

@@ -0,0 +1,5 @@
+import * as z from 'zod';
+export declare const ImageAliasesSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+type LikeC4ImageAliasConfig = z.infer<typeof ImageAliasesSchema>;
+export declare function validateImageAliases(imageAliases?: LikeC4ImageAliasConfig): void;
+export {};

package/dist/schema.image-alias.mjs

@@ -0,0 +1,42 @@
+import * as z from "zod";
+const IMAGE_ALIAS_KEY_REGEX = /^@[A-Za-z0-9_-]*$/;
+const IMAGE_ALIAS_VALUE_REGEX = /^(?!\/|[A-Za-z]:[\\\/])(?!.*:\/\/).*$/;
+const ImageAliasValue = z.string().nonempty("Image alias value cannot be empty").regex(
+  IMAGE_ALIAS_VALUE_REGEX,
+  "Image alias value must be a relative path (no leading slash or protocol)"
+);
+export const ImageAliasesSchema = z.record(
+  z.string(),
+  // PLAIN key schema - valibot JSON schema export-safe.
+  ImageAliasValue
+).meta({
+  description: "Map of image alias prefixes to relative paths (keys must match /^@\\w+$/; values must be relative paths without protocol or leading slash)."
+});
+export function validateImageAliases(imageAliases) {
+  const invalidKeys = [];
+  const invalidValues = [];
+  if (imageAliases) {
+    for (const [key, value] of Object.entries(imageAliases)) {
+      if (!IMAGE_ALIAS_KEY_REGEX.test(key)) {
+        invalidKeys.push(key);
+      }
+      if (!IMAGE_ALIAS_VALUE_REGEX.test(value)) {
+        invalidValues.push(`${key} -> ${value}`);
+      }
+    }
+  }
+  if (invalidKeys.length || invalidValues.length) {
+    const parts = [];
+    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/dist/schema.mjs

@@ -0,0 +1,38 @@
+import JSON5 from "json5";
+import * as z from "zod";
+import { ImageAliasesSchema, validateImageAliases } from "./schema.image-alias.mjs";
+export const LikeC4ProjectJsonConfigSchema = z.object({
+  name: z.string().nonempty("Project name cannot be empty").refine((value) => value !== "default", {
+    abort: true,
+    error: 'Project name cannot be "default"'
+  }).refine((value) => !value.includes(".") && !value.includes("@") && !value.includes("#"), {
+    abort: true,
+    error: 'Project name cannot contain ".", "@" or "#", try to use A-z, 0-9, _ and -'
+  }).transform((value) => value).meta({ description: "Project name, must be unique in the workspace" }),
+  title: z.string().nonempty("Project title cannot be empty if specified").optional().meta({ description: "A human readable title for the project" }),
+  contactPerson: z.string().nonempty("Contact person cannot be empty if specified").optional().meta({ description: "A person who has been involved in creating or maintaining this project" }),
+  imageAliases: ImageAliasesSchema.optional(),
+  exclude: z.array(z.string()).optional().meta({ description: 'List of file patterns to exclude from the project, default is ["**/node_modules/**"]' })
+}).meta({
+  description: "LikeC4 project configuration"
+});
+const FunctionType = z.instanceof(Function);
+export const GeneratorsSchema = z.record(z.string(), FunctionType);
+export const LikeC4ProjectConfigSchema = LikeC4ProjectJsonConfigSchema.extend({
+  generators: GeneratorsSchema.optional()
+});
+export function validateProjectConfig(config) {
+  const parsed = LikeC4ProjectConfigSchema.safeParse(
+    typeof config === "string" ? JSON5.parse(config) : config
+  );
+  if (!parsed.success) {
+    throw new Error("Config validation failed:\n" + z.prettifyError(parsed.error));
+  }
+  if (parsed.data.imageAliases) {
+    validateImageAliases(parsed.data.imageAliases);
+  }
+  return parsed.data;
+}
+export function serializableLikeC4ProjectConfig({ generators, ...config }) {
+  return LikeC4ProjectJsonConfigSchema.parse(config);
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@likec4/config",
+  "version": "1.39.0",
+  "license": "MIT",
+  "homepage": "https://likec4.dev",
+  "author": "Denis Davydkov <denis@davydkov.com>",
+  "description": "A configuration package for LikeC4.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/likec4/likec4.git",
+    "directory": "packages/config"
+  },
+  "bugs": "https://github.com/likec4/likec4/issues",
+  "files": [
+    "dist",
+    "src",
+    "schema.json",
+    "!**/*.spec.ts",
+    "!**/*.test-d.ts",
+    "!**/__*/*",
+    "!**/*.map"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "node": {
+        "sources": "./src/node/index.ts",
+        "default": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.mjs"
+        }
+      },
+      "sources": "./src/index.ts",
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./node": {
+      "sources": "./src/node/index.ts",
+      "default": {
+        "types": "./dist/node/index.d.ts",
+        "default": "./dist/node/index.mjs"
+      }
+    },
+    "./src": "./src/index.ts",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./schema.json": "./schema.json"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "bundle-n-require": "^1.1.2",
+    "defu": "^6.1.4",
+    "json5": "^2.2.3",
+    "remeda": "^2.23.1",
+    "type-fest": "^4.41.0",
+    "vscode-uri": "3.1.0",
+    "zod": "^4.0.17",
+    "@likec4/log": "1.39.0",
+    "@likec4/core": "1.39.0"
+  },
+  "devDependencies": {
+    "@types/node": "~20.19.11",
+    "tsx": "4.20.3",
+    "turbo": "2.5.6",
+    "typescript": "5.9.2",
+    "unbuild": "3.5.0",
+    "vitest": "3.2.4",
+    "@likec4/tsconfig": "1.39.0"
+  },
+  "scripts": {
+    "generate": "tsx scripts/generate.mts",
+    "typecheck": "tsc -b --verbose",
+    "build": "unbuild",
+    "lint:package": "pnpx publint ./package.tgz",
+    "clean": "pnpm rimraf dist lib",
+    "pack": "pnpm pack"
+  }
+}

package/schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "LikeC4 project configuration",
+  "type": "object",
+  "properties": {
+    "name": {
+      "description": "Project name, must be unique in the workspace",
+      "type": "string",
+      "minLength": 1
+    },
+    "title": {
+      "description": "A human readable title for the project",
+      "type": "string",
+      "minLength": 1
+    },
+    "contactPerson": {
+      "description": "A person who has been involved in creating or maintaining this project",
+      "type": "string",
+      "minLength": 1
+    },
+    "imageAliases": {
+      "description": "Map of image alias prefixes to relative paths (keys must match /^@\\w+$/; values must be relative paths without protocol or leading slash).",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^(?!\\/|[A-Za-z]:[\\\\\\/])(?!.*:\\/\\/).*$"
+      }
+    },
+    "exclude": {
+      "description": "List of file patterns to exclude from the project, default is [\"**/node_modules/**\"]",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "name"
+  ]
+}

package/src/define-config.ts

@@ -0,0 +1,51 @@
+import { type GeneratorFn, type LikeC4ProjectConfig, GeneratorsSchema, LikeC4ProjectConfigSchema } from './schema'
+
+/**
+ * Defines LikeC4 Project, allows custom generators that can be executed using CLI:
+ *
+ * `$ likec4 gen <generator-name>`
+ *
+ * or VSCode command `LikeC4: Run code generator`
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   name: 'my-project',
+ *   title: 'My Project',
+ *   exclude: ['picomatch pattern'],
+ *   generators: {
+ *     'my-generator': async ({ likec4model, ctx }) => {
+ *       await ctx.write('my-generator.txt', likec4model.project.id)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export function defineConfig<const C extends LikeC4ProjectConfig>(config: C): C {
+  return LikeC4ProjectConfigSchema.parse(config) as unknown as C
+}
+
+/**
+ * Define reusable custom generators
+ *
+ * @example
+ * ```ts
+ * // generators.ts
+ * export default defineGenerators({
+ *   'my-generator': async ({ likec4model, ctx }) => {
+ *     await ctx.write('my-generator.txt', likec4model.project.id)
+ *   }
+ * })
+ *
+ * // likec4.config.ts
+ * import generators from './generators'
+ *
+ * export default defineConfig({
+ *   name: 'my-project',
+ *   generators,
+ * })
+ * ```
+ */
+export function defineGenerators<const G extends Record<string, GeneratorFn>>(generators: G): G {
+  return GeneratorsSchema.parse(generators) as unknown as G
+}

package/src/filenames.ts

@@ -0,0 +1,48 @@
+const configJsonFilenames = [
+  '.likec4rc',
+  '.likec4.config.json',
+  'likec4.config.json',
+] as const
+
+const configNonJsonFilenames = [
+  'likec4.config.js',
+  'likec4.config.mjs',
+  'likec4.config.ts',
+  'likec4.config.mts',
+] as const
+
+export const ConfigFilenames = [
+  ...configJsonFilenames,
+  ...configNonJsonFilenames,
+] as const
+
+/**
+ * Checks if the given filename is a LikeC4 JSON config file (JSON, RC).
+ */
+export function isLikeC4JsonConfig(filename: string): filename is typeof configJsonFilenames[number] {
+  for (const ext of configJsonFilenames) {
+    if (filename.endsWith(ext)) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Checks if the given filename is a LikeC4 non-JSON config file (JS, MJS, TS, MTS)
+ */
+export function isLikeC4NonJsonConfig(filename: string): filename is typeof configNonJsonFilenames[number] {
+  for (const ext of configNonJsonFilenames) {
+    if (filename.endsWith(ext)) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Checks if the given filename is a LikeC4 config file (JSON or non-JSON)
+ */
+export function isLikeC4Config(filename: string): filename is typeof ConfigFilenames[number] {
+  return isLikeC4JsonConfig(filename) || isLikeC4NonJsonConfig(filename)
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export type {
+  GeneratorFn,
+  GeneratorFnContext,
+  GeneratorFnParams,
+  LikeC4ProjectConfig,
+  LikeC4ProjectJsonConfig,
+} from './schema'
+
+export { serializableLikeC4ProjectConfig, validateProjectConfig } from './schema'
+
+export {
+  ConfigFilenames,
+  isLikeC4Config,
+  isLikeC4JsonConfig,
+  isLikeC4NonJsonConfig,
+} from './filenames'
+
+export {
+  defineConfig,
+  defineGenerators,
+} from './define-config'

package/src/logger.ts

@@ -0,0 +1,3 @@
+import { rootLogger } from '@likec4/log'
+
+export const logger = rootLogger.getChild('config')

package/src/node/index.ts

@@ -0,0 +1,2 @@
+export * from '../index'
+export { loadConfig } from './load-config'

package/src/node/load-config.ts

@@ -0,0 +1,36 @@
+import { invariant } from '@likec4/core'
+import { bundleNRequire } from 'bundle-n-require'
+import * as fs from 'node:fs/promises'
+import type { URI } from 'vscode-uri'
+import { defineConfig } from '../define-config'
+import { isLikeC4JsonConfig, isLikeC4NonJsonConfig } from '../filenames'
+import { logger } from '../logger'
+import { type LikeC4ProjectConfig, validateProjectConfig } from '../schema'
+
+/**
+ * Load LikeC4 Project config file.
+ * If filepath is a non-JSON file, it will be bundled and required
+ */
+export async function loadConfig(filepath: URI): Promise<LikeC4ProjectConfig> {
+  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
+    }
+  }
+
+  invariant(isLikeC4NonJsonConfig(filepath.fsPath), `Invalid config file: ${filepath.fsPath}`)
+  try {
+    const { mod } = await bundleNRequire(filepath.fsPath, {
+      interopDefault: true,
+    })
+    return defineConfig(mod?.default ?? mod)
+  } catch (err) {
+    logger.error(`Failed to load config file: ${filepath.fsPath}`, { err })
+    throw err
+  }
+}

package/src/schema.image-alias.ts

@@ -0,0 +1,68 @@
+import * as z from 'zod'
+
+// Key must be prefixed with "@" and contain only allowed characters
+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]:[\\\/])(?!.*:\/\/).*$/
+
+// 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()
+  .nonempty('Image alias value cannot be empty')
+  .regex(
+    IMAGE_ALIAS_VALUE_REGEX,
+    'Image alias value must be a relative path (no leading slash or protocol)',
+  )
+
+export const ImageAliasesSchema = z.record(
+  z.string(), // PLAIN key schema - valibot JSON schema export-safe.
+  ImageAliasValue,
+).meta({
+  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 Valibot,
+      // 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.ts

@@ -0,0 +1,226 @@
+import type {
+  DeploymentElementModel,
+  DeploymentRelationModel,
+  ElementModel,
+  LikeC4Model,
+  LikeC4ViewModel,
+  RelationshipModel,
+} from '@likec4/core/model'
+import type {
+  aux,
+  ProjectId,
+} from '@likec4/core/types'
+import JSON5 from 'json5'
+import type Stream from 'node:stream'
+import type { URI } from 'vscode-uri'
+import * as z from 'zod'
+import { ImageAliasesSchema, validateImageAliases } from './schema.image-alias'
+
+export const LikeC4ProjectJsonConfigSchema = z.object({
+  name: z.string()
+    .nonempty('Project name cannot be empty')
+    .refine((value) => value !== 'default', {
+      abort: true,
+      error: 'Project name cannot be "default"',
+    })
+    .refine((value) => !value.includes('.') && !value.includes('@') && !value.includes('#'), {
+      abort: true,
+      error: 'Project name cannot contain ".", "@" or "#", try to use A-z, 0-9, _ and -',
+    })
+    .transform((value) => value as ProjectId)
+    .meta({ description: 'Project name, must be unique in the workspace' }),
+  title: z.string()
+    .nonempty('Project title cannot be empty if specified')
+    .optional()
+    .meta({ description: 'A human readable title for the project' }),
+  contactPerson: z.string()
+    .nonempty('Contact person cannot be empty if specified')
+    .optional()
+    .meta({ description: 'A person who has been involved in creating or maintaining this project' }),
+  imageAliases: ImageAliasesSchema
+    .optional(),
+  exclude: z.array(z.string())
+    .optional()
+    .meta({ description: 'List of file patterns to exclude from the project, default is ["**/node_modules/**"]' }),
+})
+  .meta({
+    description: 'LikeC4 project configuration',
+  })
+
+export type LikeC4ProjectJsonConfig = z.input<typeof LikeC4ProjectJsonConfigSchema>
+
+const FunctionType = z.instanceof(Function)
+export const GeneratorsSchema = z.record(z.string(), FunctionType)
+export const LikeC4ProjectConfigSchema = LikeC4ProjectJsonConfigSchema.extend({
+  generators: GeneratorsSchema.optional(),
+})
+
+export interface GeneratorFnContext {
+  /**
+   * Workspace root directory
+   */
+  readonly workspace: URI
+
+  /**
+   * Current project
+   */
+  readonly project: {
+    /**
+     * Project name
+     */
+    readonly id: ProjectId
+
+    readonly title?: string
+
+    /**
+     * Project folder
+     */
+    readonly folder: URI
+  }
+
+  /**
+   * Returns the location of the specified element, relation, view or deployment element
+   */
+  locate(
+    target:
+      | ElementModel
+      | RelationshipModel
+      | DeploymentRelationModel
+      | LikeC4ViewModel
+      | DeploymentElementModel,
+  ): {
+    /**
+     * Range inside the source file
+     */
+    range: {
+      start: {
+        line: number
+        character: number
+      }
+      end: {
+        line: number
+        character: number
+      }
+    }
+    /**
+     * Full path to the source file
+     */
+    document: URI
+    /**
+     * Document path relative to the project folder
+     */
+    relativePath: string
+    /**
+     * Folder, containing the source file ("dirname" of document)
+     */
+    folder: string
+    /**
+     * Source file name ("basename" of document)
+     */
+    filename: string
+  }
+
+  /**
+   * Write a file
+   * @param path - Path to the file, either absolute or relative to the project folder
+   *               All folders will be created automatically
+   * @param content - Content of the file
+   */
+  write(file: {
+    path: string | string[] | URI
+    content:
+      | string
+      | NodeJS.ArrayBufferView
+      | Iterable<string | NodeJS.ArrayBufferView>
+      | AsyncIterable<string | NodeJS.ArrayBufferView>
+      | Stream
+  }): Promise<void>
+
+  /**
+   * Abort the process
+   */
+  abort(reason?: string): never
+}
+
+export type GeneratorFnParams = {
+  /**
+   * LikeC4 model
+   */
+  likec4model: LikeC4Model<aux.UnknownLayouted>
+
+  /**
+   * Generator context
+   */
+  ctx: GeneratorFnContext
+}
+
+export interface GeneratorFn {
+  (params: GeneratorFnParams): Promise<void> | void
+}
+
+/**
+ * LikeC4 project configuration
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   name: 'my-project',
+ *   generators: {
+ *     'my-generator': async ({ likec4model, ctx }) => {
+ *       await ctx.write('my-generator.txt', likec4model.project.id)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export type LikeC4ProjectConfig = z.input<typeof LikeC4ProjectJsonConfigSchema> & {
+  /**
+   * Add custom generators to the project
+   * @example
+   * ```ts
+   * export default defineConfig({
+   *   name: 'my-project',
+   *   generators: {
+   *     'my-generator': async ({ likec4model, ctx }) => {
+   *       await ctx.write('my-generator.txt', likec4model.project.id)
+   *     }
+   *   }
+   * })
+   * ```
+   *
+   * Execute generator:
+   * ```bash
+   * likec4 gen my-generator
+   * ```
+   */
+  generators?: Record<string, GeneratorFn> | undefined
+}
+
+/**
+ * Validates JSON string or JSON object into a LikeC4ProjectConfig object.
+ */
+export function validateProjectConfig<C extends string | Record<string, unknown>>(
+  config: C,
+): LikeC4ProjectConfig {
+  const parsed = LikeC4ProjectConfigSchema.safeParse(
+    typeof config === 'string' ? JSON5.parse(config) : config,
+  )
+  if (!parsed.success) {
+    throw new Error('Config validation failed:\n' + z.prettifyError(parsed.error))
+  }
+  // TODO: rewrite with zod refine
+  if (parsed.data.imageAliases) {
+    validateImageAliases(parsed.data.imageAliases)
+  }
+  return parsed.data as unknown as LikeC4ProjectConfig
+}
+
+/**
+ * Converts a LikeC4ProjectConfig object into a LikeC4ProjectJsonConfig object.
+ * Omit generators property (as it is not serializable)
+ */
+export function serializableLikeC4ProjectConfig(
+  { generators, ...config }: LikeC4ProjectConfig,
+): LikeC4ProjectJsonConfig {
+  return LikeC4ProjectJsonConfigSchema.parse(config) as unknown as LikeC4ProjectJsonConfig
+}