@diagc/cli 1.1.7 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,7 +9,8 @@ export interface PublishOptions {
9
9
  assetsDir: string;
10
10
  images: boolean;
11
11
  names?: string[];
12
- renderPng?: (htmlPath: string, pngPath: string) => Promise<void>;
12
+ /** takes `htmlPath`'s picture of `plane` (the first plane when absent) into `pngPath` */
13
+ renderPng?: (htmlPath: string, pngPath: string, plane?: string) => Promise<void>;
13
14
  /** an http(s) address for the gallery's header — never put on a diagram page */
14
15
  link?: string;
15
16
  /** where a warning goes, one line each: `console.warn` by default, so a caller with
@@ -30,4 +31,17 @@ export interface PublishResult {
30
31
  * diagram in the warnings for refs it has to leave as they are.
31
32
  */
32
33
  export declare function inlineAssets(model: DiagramModel, opts: Pick<PublishOptions, 'libraryDir' | 'assetsDir' | 'warn'>, cache: Map<string, Buffer>, label: string): Promise<DiagramModel>;
34
+ /** One picture of a diagram: its plane (absent = the first) and what goes between
35
+ * the diagram's name and `.png`. */
36
+ export interface PlanePicture {
37
+ plane?: string;
38
+ suffix: string;
39
+ }
40
+ /**
41
+ * The pictures publish takes of a model, one per plane. The first plane's is
42
+ * `<name>.png`, the picture docs and READMEs already link; each further plane's
43
+ * is `<name>.<slug>.png`, its id made safe for a file name by the one slug rule
44
+ * (`Target VPC` -> `target-vpc`; ids that slug alike get `-2`, `-3`…).
45
+ */
46
+ export declare function planePictures(model: DiagramModel): PlanePicture[];
33
47
  export declare function publishDiagrams(opts: PublishOptions): Promise<PublishResult>;
@@ -1,7 +1,7 @@
1
1
  import { existsSync } from 'node:fs';
2
2
  import { mkdir, readFile, writeFile } from 'node:fs/promises';
3
3
  import path from 'node:path';
4
- import { errMessage, isDrawings } from '@diagc/core/internal';
4
+ import { errMessage, isDrawings, uniqueSlug } from '@diagc/core/internal';
5
5
  import { classifyAssetRef, rewriteAssetRefs, safeAssetPath } from './assets.js';
6
6
  import { buildGallery } from './gallery.js';
7
7
  import { discoverDiagrams } from './discover.js';
@@ -60,6 +60,37 @@ export async function inlineAssets(model, opts, cache, label) {
60
60
  }
61
61
  return rewriteAssetRefs(model, (ref) => cache.get(ref));
62
62
  }
63
+ /**
64
+ * The pictures publish takes of a model, one per plane. The first plane's is
65
+ * `<name>.png`, the picture docs and READMEs already link; each further plane's
66
+ * is `<name>.<slug>.png`, its id made safe for a file name by the one slug rule
67
+ * (`Target VPC` -> `target-vpc`; ids that slug alike get `-2`, `-3`…).
68
+ */
69
+ export function planePictures(model) {
70
+ const taken = new Set();
71
+ const others = model.planes.slice(1).map((p) => {
72
+ const slug = uniqueSlug(p.id, taken, 'plane');
73
+ taken.add(slug);
74
+ return { plane: p.id, suffix: `.${slug}` };
75
+ });
76
+ return [{ suffix: '' }, ...others];
77
+ }
78
+ /** Takes a diagram's pictures from its page; the files it wrote. */
79
+ async function renderPictures(name, model, pagePath, run) {
80
+ const written = [];
81
+ for (const picture of planePictures(model)) {
82
+ const file = `${name}${picture.suffix}`;
83
+ if (picture.plane !== undefined && run.diagrams.has(file)) {
84
+ run.warn(`publish: no picture of plane "${picture.plane}" of diagram "${name}": ${file}.png is diagram "${file}"'s.`);
85
+ continue;
86
+ }
87
+ const pngPath = path.join(run.staticDir, `${file}.png`);
88
+ await mkdir(path.dirname(pngPath), { recursive: true });
89
+ await run.render(pagePath, pngPath, picture.plane);
90
+ written.push(pngPath);
91
+ }
92
+ return written;
93
+ }
63
94
  export async function publishDiagrams(opts) {
64
95
  const warn = opts.warn ?? console.warn;
65
96
  const shell = await readFile(opts.shellPath, 'utf8');
@@ -68,6 +99,7 @@ export async function publishDiagrams(opts) {
68
99
  await mkdir(opts.staticDir, { recursive: true });
69
100
  const cache = new Map();
70
101
  const all = await discoverDiagrams(opts.artifactsDir, opts.srcDir);
102
+ const discovered = new Set(all.map((d) => d.name));
71
103
  let chosen = all;
72
104
  if (opts.names !== undefined && opts.names.length > 0) {
73
105
  const want = new Set(opts.names);
@@ -102,10 +134,8 @@ export async function publishDiagrams(opts) {
102
134
  await writeFile(pagePath, stampHtml(shell, { model: inlined, layout, drawings }));
103
135
  pages.push(pagePath);
104
136
  if (opts.images && opts.renderPng !== undefined) {
105
- const pngPath = path.join(opts.staticDir, `${d.name}.png`);
106
- await mkdir(path.dirname(pngPath), { recursive: true });
107
- await opts.renderPng(pagePath, pngPath);
108
- images.push(pngPath);
137
+ const run = { render: opts.renderPng, staticDir: opts.staticDir, diagrams: discovered, warn };
138
+ images.push(...(await renderPictures(d.name, modelRaw, pagePath, run)));
109
139
  }
110
140
  }
111
141
  catch (e) {
@@ -1,3 +1,6 @@
1
1
  /** Locate an installed Chrome/Chromium; undefined means "no browser available". */
2
2
  export declare function findChrome(): string | undefined;
3
- export declare function renderPng(htmlPath: string, pngPath: string): Promise<void>;
3
+ /** The page's export render: `?export=1` unfolds every group for a full overview,
4
+ * and `plane` names the plane to draw (the first when absent). */
5
+ export declare function exportUrl(htmlPath: string, plane?: string): string;
6
+ export declare function renderPng(htmlPath: string, pngPath: string, plane?: string): Promise<void>;
@@ -20,7 +20,13 @@ export function findChrome() {
20
20
  }
21
21
  /** Frame padding around the graph, in screen px. */
22
22
  const FRAME_PADDING = 32;
23
- export async function renderPng(htmlPath, pngPath) {
23
+ /** The page's export render: `?export=1` unfolds every group for a full overview,
24
+ * and `plane` names the plane to draw (the first when absent). */
25
+ export function exportUrl(htmlPath, plane) {
26
+ const query = new URLSearchParams({ export: '1', ...(plane !== undefined ? { plane } : {}) });
27
+ return `${pathToFileURL(path.resolve(htmlPath)).href}?${query.toString()}`;
28
+ }
29
+ export async function renderPng(htmlPath, pngPath, plane) {
24
30
  const executablePath = findChrome();
25
31
  if (executablePath === undefined) {
26
32
  throw new Error('No Chrome found for image export. Install Google Chrome/Chromium, set CHROME_PATH, or run with --no-images.');
@@ -34,8 +40,7 @@ export async function renderPng(htmlPath, pngPath) {
34
40
  deviceScaleFactor: 2,
35
41
  colorScheme: 'light',
36
42
  });
37
- // `?export=1` tells the viewer to unfold every group for a full overview.
38
- await page.goto(`${pathToFileURL(path.resolve(htmlPath)).href}?export=1`);
43
+ await page.goto(exportUrl(htmlPath, plane));
39
44
  await page.waitForFunction(() => window.__DG_READY__ === true, null, {
40
45
  timeout: 15_000,
41
46
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@diagc/cli",
3
- "version": "1.1.7",
3
+ "version": "1.3.0",
4
4
  "description": "Author software-architecture diagrams as code, compile them to a validated model, edit them in a local studio, and publish pages and images.",
5
5
  "license": "AGPL-3.0-only",
6
6
  "author": "Bogdan Frankovskyi",
@@ -44,7 +44,7 @@
44
44
  "fast-glob": "^3.3.0",
45
45
  "jiti": "^2.0.0",
46
46
  "playwright-core": "^1.62.0",
47
- "@diagc/core": "1.1.7"
47
+ "@diagc/core": "1.3.0"
48
48
  },
49
49
  "publishConfig": {
50
50
  "access": "public"