@likec4/generators 1.59.2 → 1.59.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@likec4/generators",
-  "version": "1.59.2",
+  "version": "1.59.3",
   "license": "MIT",
   "bugs": "https://github.com/likec4/likec4/issues",
   "homepage": "https://likec4.dev",
@@ -45,27 +45,27 @@
     "access": "public"
   },
   "dependencies": {
+    "@likec4/core": "1.59.3",
+    "@likec4/config": "1.59.3",
+    "@likec4/log": "1.59.3",
     "langium": "3.5.0",
     "pako": "^2.1.0",
-    "remeda": "^2.37.0",
-    "immer": "^11.1.9",
+    "remeda": "^2.45.0",
+    "immer": "^11.1.18",
     "json5": "^2.2.3",
     "type-fest": "^4.41.0",
     "indent-string": "^5.0.0",
     "strip-indent": "^4.1.1",
-    "zod": "^4.4.3",
-    "@likec4/core": "1.59.2",
-    "@likec4/log": "1.59.2",
-    "@likec4/config": "1.59.2"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@likec4/tsconfig": "1.59.3",
+    "@likec4/devops": "1.59.3",
     "@types/node": "~22.19.19",
     "@types/pako": "^2.0.4",
     "typescript": "6.0.3",
     "tsdown": "^0.22.9",
-    "vitest": "4.1.9",
-    "@likec4/tsconfig": "1.59.2",
-    "@likec4/devops": "1.59.2"
+    "vitest": "4.1.11"
   },
   "scripts": {
     "typecheck": "tsc -b --verbose",

package/src/d2/generate-d2.ts

@@ -1,7 +1,8 @@
 import type { LikeC4ViewModel } from '@likec4/core/model'
 import type { aux, ComputedNode, NodeId, ProcessedView as AnyView } from '@likec4/core/types'
-import { CompositeGeneratorNode, joinToNode, NL, toString } from 'langium/generate'
+import { CompositeGeneratorNode, joinToNode } from 'langium/generate'
 import { isNullish as isNil } from 'remeda'
+import { NL, toStringLF } from '../newline'
 
 const capitalizeFirstLetter = (value: string) => value.charAt(0).toLocaleUpperCase() + value.slice(1)
 
@@ -93,7 +94,7 @@ export function generateD2(viewmodel: LikeC4ViewModel<aux.Unknown>) {
       .append(out => edge.label && out.append(': ', JSON.stringify(edge.label)))
   }
 
-  return toString(
+  return toStringLF(
     new CompositeGeneratorNode()
       .append('direction: ', d2direction(view), NL, NL)
       .append(

package/src/index.ts

@@ -17,6 +17,7 @@ export {
   parseDrawioToLikeC4,
   parseDrawioToLikeC4Multi,
 } from './drawio/parse-drawio'
+export { generateMarkdown } from './markdown/generate-markdown'
 export { generateMermaid } from './mmd/generate-mmd'
 export { generateLikeC4Model } from './model/generate-likec4-model'
 export { generatePuml } from './puml/generate-puml'

package/src/likec4/operators/base.ts

@@ -6,8 +6,6 @@ import {
   CompositeGeneratorNode,
   joinToNode,
   NewLineNode,
-  NL,
-  toString,
 } from 'langium/generate'
 import {
   filter,
@@ -28,6 +26,7 @@ import { dedent } from 'strip-indent'
 import type { IfAny, Or } from 'type-fest'
 import * as z from 'zod/v4'
 import type * as z4 from 'zod/v4/core'
+import { NL, toStringLF } from '../../newline'
 
 function hasContent(out: Generated): boolean {
   if (typeof out === 'string') {
@@ -109,7 +108,7 @@ export function fresh(ctx?: unknown) {
  */
 export function materialize(ctx: AnyCtx | Op<any>, defaultIndentation: string | number = 2): string {
   const out = isFunction(ctx) ? executeOnFresh(undefined, [ctx]).out : ctx.out
-  return toString(out, defaultIndentation).replaceAll(/\r\n/g, '\n')
+  return toStringLF(out, defaultIndentation)
 }
 
 /**

package/src/likec4/operators/views.ts

@@ -3,8 +3,9 @@ import {
   invariant,
   nonexhaustive,
 } from '@likec4/core'
-import { CompositeGeneratorNode, NL } from 'langium/generate'
+import { CompositeGeneratorNode } from 'langium/generate'
 import { hasAtLeast, values } from 'remeda'
+import { NL } from '../../newline'
 import { schemas } from '../schemas'
 import {
   type Op,
@@ -187,6 +188,7 @@ export const elementView = zodOp(schemas.views.elementView.partial({ _type: true
         lines(
           tagsProperty(),
           viewTitleProperty(),
+          property('order'),
           descriptionProperty(),
           linksProperty(),
         ),
@@ -237,6 +239,7 @@ export const deploymentView = zodOp(schemas.views.deploymentView.partial({ _type
         lines(
           tagsProperty(),
           viewTitleProperty(),
+          property('order'),
           descriptionProperty(),
           linksProperty(),
         ),
@@ -460,6 +463,7 @@ export const dynamicView = zodOp(schemas.views.dynamicView.partial({ _type: true
         lines(
           tagsProperty(),
           viewTitleProperty(),
+          property('order'),
           descriptionProperty(),
           linksProperty(),
           property('variant'),

package/src/likec4/schemas/specification.ts

@@ -38,11 +38,7 @@ export const relationship = z
 
 export const tagSpec = z
   .object({
-    color: z
-      .string()
-      .regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/)
-      .optional()
-      .catch(undefined),
+    color: common.color.nullable(),
   })
   .partial()
   .transform(pickBy(isNonNullish))

package/src/likec4/schemas/views.ts

@@ -62,7 +62,9 @@ export const viewRuleRank = z
 
 // Manually typed due to recursive z.lazy schema
 export type ViewRuleGroupInput = {
-  groupRules: Array<z.input<typeof viewRulePredicate> | ViewRuleGroupInput>
+  groupRules: Array<
+    z.input<typeof viewRulePredicate> | z.input<typeof viewRuleGlobalPredicate> | ViewRuleGroupInput
+  >
   title: string | null
   color?: z.input<typeof common.color> | undefined
   border?: z.input<typeof common.border> | undefined
@@ -74,7 +76,9 @@ export type ViewRuleGroupInput = {
 }
 
 export type ViewRuleGroupOutput = {
-  groupRules: Array<z.infer<typeof viewRulePredicate> | ViewRuleGroupOutput>
+  groupRules: Array<
+    z.infer<typeof viewRulePredicate> | z.infer<typeof viewRuleGlobalPredicate> | ViewRuleGroupOutput
+  >
   title: string | null
   color?: z.infer<typeof common.color> | undefined
   border?: z.infer<typeof common.border> | undefined
@@ -87,7 +91,7 @@ export type ViewRuleGroupOutput = {
 
 export const viewRuleGroup: z.ZodType<ViewRuleGroupOutput, ViewRuleGroupInput> = z.lazy(() =>
   z.object({
-    groupRules: z.array(z.union([viewRulePredicate, viewRuleGroup])),
+    groupRules: z.array(z.union([viewRulePredicate, viewRuleGlobalPredicate, viewRuleGroup])),
     title: z.string().nullable(),
     color: common.color.optional(),
     border: common.border.optional(),
@@ -114,6 +118,7 @@ const viewProps = z.object({
   id: common.viewId,
   title: z.string().nullish(),
   description: common.markdownOrString.nullish(),
+  order: z.number().int().nonnegative().optional(),
   tags: common.tags.nullish(),
   links: common.links.nullish(),
 })

package/src/markdown/generate-markdown.ts

@@ -0,0 +1,52 @@
+import type { LikeC4Model, LikeC4ViewModel } from '@likec4/core/model'
+import type { aux } from '@likec4/core/types'
+import { CompositeGeneratorNode } from 'langium/generate'
+import { generateMermaid } from '../mmd/generate-mmd'
+import { NL, toStringLF } from '../newline'
+
+type ViewModel = LikeC4ViewModel<aux.Unknown>
+
+/**
+ * Appends a single view to the document as a level-3 heading, its optional
+ * description, and a fenced Mermaid diagram.
+ */
+function appendView(doc: CompositeGeneratorNode, view: ViewModel): void {
+  doc.append('### ', view.titleOrId, NL, NL)
+  if (view.description.nonEmpty) {
+    doc.append(view.description.md, NL, NL)
+  }
+  doc.append('```mermaid', NL, generateMermaid(view).trimEnd(), NL, '```', NL, NL)
+}
+
+export type GenerateMarkdownOptions = {
+  /**
+   * `LikeC4Project` has no description field of its own yet, so callers source this from
+   * wherever they keep it (e.g. the project config's `metadata` bag) and pass it through.
+   * If a first-class description ever lands on `LikeC4Project`, read it from the model
+   * directly instead and drop this option.
+   */
+  description?: string
+}
+
+/**
+ * Renders a LikeC4 model as a Markdown document: the project title, an optional
+ * description, and every authored view as a Mermaid diagram. Views without a
+ * `sourcePath` (e.g. auto-generated index views) are skipped.
+ */
+export function generateMarkdown(
+  model: LikeC4Model<aux.Unknown>,
+  options: GenerateMarkdownOptions = {},
+): string {
+  const doc = new CompositeGeneratorNode()
+  doc.append('# ', model.project.title ?? model.projectId, NL, NL)
+  if (options.description) {
+    doc.append(options.description, NL, NL)
+  }
+
+  for (const view of model.views()) {
+    if (view.$view.sourcePath === undefined) continue
+    appendView(doc, view)
+  }
+
+  return toStringLF(doc)
+}

package/src/markdown/index.ts

@@ -0,0 +1 @@
+export * from './generate-markdown'

package/src/mmd/generate-mmd.ts

@@ -1,8 +1,9 @@
 import { nonexhaustive } from '@likec4/core'
 import type { LikeC4ViewModel } from '@likec4/core/model'
 import type { aux, NodeId, ProcessedView as AnyView } from '@likec4/core/types'
-import { CompositeGeneratorNode, joinToNode, NL, toString } from 'langium/generate'
+import { CompositeGeneratorNode, joinToNode } from 'langium/generate'
 import { isNullish as isNil } from 'remeda'
+import { NL, toStringLF } from '../newline'
 
 const capitalizeFirstLetter = (value: string) => value.charAt(0).toLocaleUpperCase() + value.slice(1)
 
@@ -97,7 +98,7 @@ export function generateMermaid(viewmodel: LikeC4ViewModel<aux.Unknown>) {
     )
   }
 
-  return toString(
+  return toStringLF(
     new CompositeGeneratorNode()
       .append(
         '---',

package/src/newline.ts

@@ -0,0 +1,21 @@
+import type { GeneratorNode } from 'langium/generate'
+import { NewLineNode, toString } from 'langium/generate'
+
+/**
+ * Line separator for all generated output.
+ *
+ * Langium's own `NL` resolves to `os.EOL`, which emits CRLF on Windows and makes
+ * generated artifacts (Markdown, Mermaid, D2, PlantUML, LikeC4 DSL) differ per platform.
+ * Generators must be deterministic, so always emit LF.
+ */
+export const NL = new NewLineNode('\n')
+
+/**
+ * Renders a generator node with LF line endings.
+ *
+ * Some Langium helpers insert `os.EOL` internally (for example `joinToNode`'s
+ * `appendNewLineIfNotEmpty`), so normalize the rendered output as well as using {@link NL}.
+ */
+export function toStringLF(node: GeneratorNode | undefined, defaultIndentation?: string | number): string {
+  return toString(node, defaultIndentation).replaceAll('\r\n', '\n')
+}

package/src/puml/generate-puml.ts

@@ -13,8 +13,9 @@ import type {
   ThemeColor,
 } from '@likec4/core/types'
 import { RichText } from '@likec4/core/types'
-import { CompositeGeneratorNode, joinToNode, NL, toString } from 'langium/generate'
+import { CompositeGeneratorNode, joinToNode } from 'langium/generate'
 import { isEmptyish, isNullish as isNil } from 'remeda'
+import { NL, toStringLF } from '../newline'
 
 const capitalizeFirstLetter = (value: string) => value.charAt(0).toLocaleUpperCase() + value.slice(1)
 
@@ -233,7 +234,7 @@ export function generatePuml(viewmodel: LikeC4ViewModel<aux.Unknown>) {
     return out.append(NL)
   }
 
-  return toString(
+  return toStringLF(
     new CompositeGeneratorNode()
       .append('@startuml', NL)
       .append(printHeader(), NL)

package/src/views-data-ts/generate-views-data.ts

@@ -1,6 +1,7 @@
 import type { DiagramView } from '@likec4/core'
 import JSON5 from 'json5'
-import { CompositeGeneratorNode, expandToNode, joinToNode, NL, toString } from 'langium/generate'
+import { CompositeGeneratorNode, expandToNode, joinToNode } from 'langium/generate'
+import { NL, toStringLF } from '../newline'
 import { generateViewId } from './generateViewId'
 
 /**
@@ -21,7 +22,7 @@ export function generateViewsDataJs(diagrams: Iterable<DiagramView>) {
 
   if (views.length == 0) {
     out.append('export const LikeC4Views = {}', NL)
-    return toString(out)
+    return toStringLF(out)
   }
 
   out.appendTemplate`
@@ -54,7 +55,7 @@ export function generateViewsDataJs(diagrams: Iterable<DiagramView>) {
 
     /* prettier-ignore-end */
   `.append(NL)
-  return toString(out)
+  return toStringLF(out)
 }
 
 /**
@@ -78,7 +79,7 @@ export function generateViewsDataTs(diagrams: Iterable<DiagramView>) {
 
   if (views.length === 0) {
     out.append('export {}', NL)
-    return toString(out)
+    return toStringLF(out)
   }
 
   out.appendTemplate`
@@ -118,7 +119,7 @@ export function generateViewsDataTs(diagrams: Iterable<DiagramView>) {
 
     /* prettier-ignore-end */
   `.append(NL)
-  return toString(out)
+  return toStringLF(out)
 }
 
 /**
@@ -140,7 +141,7 @@ export function generateViewsDataDTs(diagrams: Iterable<DiagramView>) {
 
   if (views.length == 0) {
     out.append('export {}', NL)
-    return toString(out)
+    return toStringLF(out)
   }
 
   out.appendTemplate`
@@ -152,5 +153,5 @@ export function generateViewsDataDTs(diagrams: Iterable<DiagramView>) {
 
     /* prettier-ignore-end */
   `.append(NL)
-  return toString(out)
+  return toStringLF(out)
 }