@diagc/cli 1.1.6 → 1.2.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.
Files changed (88) hide show
  1. package/assets/guide/index.md +2 -2
  2. package/assets/studio/assets/index-B-KI19Kg.js +110 -0
  3. package/assets/studio/index.html +1 -1
  4. package/assets/viewer/index.html +33 -33
  5. package/dist/api/assets.d.ts +8 -0
  6. package/dist/api/assets.js +54 -0
  7. package/dist/api/diagrams.d.ts +27 -0
  8. package/dist/api/diagrams.js +269 -0
  9. package/dist/api/files.d.ts +7 -0
  10. package/dist/api/files.js +30 -0
  11. package/dist/api/handlers.d.ts +7 -62
  12. package/dist/api/handlers.js +10 -488
  13. package/dist/api/library.d.ts +5 -0
  14. package/dist/api/library.js +88 -0
  15. package/dist/api/result.d.ts +8 -0
  16. package/dist/api/result.js +5 -0
  17. package/dist/api/sidecars.d.ts +13 -0
  18. package/dist/api/sidecars.js +78 -0
  19. package/dist/cli/command.d.ts +26 -0
  20. package/dist/cli/command.js +1 -0
  21. package/dist/cli/io.d.ts +13 -0
  22. package/dist/cli/io.js +7 -0
  23. package/dist/cli/parse.d.ts +51 -0
  24. package/dist/cli/parse.js +109 -0
  25. package/dist/cli/run.d.ts +10 -0
  26. package/dist/cli/run.js +67 -0
  27. package/dist/cli.d.ts +1 -52
  28. package/dist/cli.js +5 -475
  29. package/dist/commands/compile.d.ts +3 -0
  30. package/dist/commands/compile.js +38 -0
  31. package/dist/commands/diff.d.ts +10 -0
  32. package/dist/commands/diff.js +96 -0
  33. package/dist/commands/eject.d.ts +3 -0
  34. package/dist/commands/eject.js +32 -0
  35. package/dist/commands/guide.d.ts +3 -0
  36. package/dist/commands/guide.js +13 -0
  37. package/dist/commands/init.d.ts +3 -0
  38. package/dist/commands/init.js +23 -0
  39. package/dist/commands/lint.d.ts +3 -0
  40. package/dist/commands/lint.js +27 -0
  41. package/dist/commands/publish.d.ts +11 -0
  42. package/dist/commands/publish.js +83 -0
  43. package/dist/commands/shared.d.ts +19 -0
  44. package/dist/commands/shared.js +34 -0
  45. package/dist/commands/studio.d.ts +3 -0
  46. package/dist/commands/studio.js +14 -0
  47. package/dist/commands/watch.d.ts +8 -0
  48. package/dist/commands/watch.js +45 -0
  49. package/dist/compile.d.ts +4 -1
  50. package/dist/compile.js +8 -13
  51. package/dist/diff/compare.d.ts +36 -0
  52. package/dist/diff/compare.js +36 -0
  53. package/dist/diff/describe.d.ts +8 -0
  54. package/dist/diff/describe.js +70 -0
  55. package/dist/diff/index.d.ts +4 -0
  56. package/dist/diff/index.js +6 -0
  57. package/dist/diff/load.d.ts +22 -0
  58. package/dist/diff/load.js +62 -0
  59. package/dist/diff/overview.d.ts +17 -0
  60. package/dist/diff/overview.js +86 -0
  61. package/dist/diff/pages.d.ts +27 -0
  62. package/dist/diff/pages.js +55 -0
  63. package/dist/diff/summary.d.ts +18 -0
  64. package/dist/diff/summary.js +26 -0
  65. package/dist/eject.js +2 -6
  66. package/dist/git-ref.js +21 -3
  67. package/dist/glob.d.ts +5 -0
  68. package/dist/glob.js +7 -0
  69. package/dist/init.d.ts +0 -3
  70. package/dist/init.js +14 -15
  71. package/dist/names.d.ts +3 -0
  72. package/dist/names.js +8 -0
  73. package/dist/paths.d.ts +29 -0
  74. package/dist/paths.js +25 -0
  75. package/dist/publish/discover.js +2 -1
  76. package/dist/publish/publish.d.ts +21 -5
  77. package/dist/publish/publish.js +46 -12
  78. package/dist/publish/snapshot.d.ts +4 -1
  79. package/dist/publish/snapshot.js +8 -3
  80. package/dist/snapshots.d.ts +11 -0
  81. package/dist/snapshots.js +20 -3
  82. package/dist/studio.js +8 -8
  83. package/package.json +2 -2
  84. package/assets/studio/assets/index-Cn03lgc3.js +0 -110
  85. package/dist/command-args.d.ts +0 -9
  86. package/dist/command-args.js +0 -56
  87. package/dist/diff.d.ts +0 -61
  88. package/dist/diff.js +0 -244
@@ -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';
@@ -30,7 +30,8 @@ async function readMaybe(p) {
30
30
  * (refs are content hashes, so one read serves them all); `label` names the
31
31
  * diagram in the warnings for refs it has to leave as they are.
32
32
  */
33
- export async function inlineAssets(model, dirs, cache, label) {
33
+ export async function inlineAssets(model, opts, cache, label) {
34
+ const warn = opts.warn ?? console.warn;
34
35
  // Pre-read every inlinable ref so the rewrite can stay a pure sync function.
35
36
  for (const n of model.nodes) {
36
37
  for (const ref of [n.image, n.shape]) {
@@ -39,7 +40,7 @@ export async function inlineAssets(model, dirs, cache, label) {
39
40
  const kind = classifyAssetRef(ref);
40
41
  if (kind === 'skip')
41
42
  continue;
42
- const base = kind === 'library' ? dirs.libraryDir : dirs.assetsDir;
43
+ const base = kind === 'library' ? opts.libraryDir : opts.assetsDir;
43
44
  const rel = kind === 'library'
44
45
  ? ref.slice('/library/'.length)
45
46
  : kind === 'api-assets'
@@ -47,25 +48,58 @@ export async function inlineAssets(model, dirs, cache, label) {
47
48
  : ref;
48
49
  const filePath = safeAssetPath(base, rel);
49
50
  if (filePath === undefined) {
50
- console.warn(`publish: refusing out-of-root asset "${ref}" for ${label}; leaving ref as-is.`);
51
+ warn(`publish: refusing out-of-root asset "${ref}" for ${label}; leaving ref as-is.`);
51
52
  continue;
52
53
  }
53
54
  const bytes = await readMaybe(filePath);
54
55
  if (bytes !== undefined)
55
56
  cache.set(ref, bytes);
56
57
  else
57
- console.warn(`publish: could not read asset "${ref}" for ${label} (looked in ${filePath}); leaving ref as-is.`);
58
+ warn(`publish: could not read asset "${ref}" for ${label} (looked in ${filePath}); leaving ref as-is.`);
58
59
  }
59
60
  }
60
61
  return rewriteAssetRefs(model, (ref) => cache.get(ref));
61
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
+ }
62
94
  export async function publishDiagrams(opts) {
95
+ const warn = opts.warn ?? console.warn;
63
96
  const shell = await readFile(opts.shellPath, 'utf8');
64
97
  await mkdir(opts.htmlDir, { recursive: true });
65
98
  if (opts.images)
66
99
  await mkdir(opts.staticDir, { recursive: true });
67
100
  const cache = new Map();
68
101
  const all = await discoverDiagrams(opts.artifactsDir, opts.srcDir);
102
+ const discovered = new Set(all.map((d) => d.name));
69
103
  let chosen = all;
70
104
  if (opts.names !== undefined && opts.names.length > 0) {
71
105
  const want = new Set(opts.names);
@@ -73,6 +107,7 @@ export async function publishDiagrams(opts) {
73
107
  }
74
108
  const pages = [];
75
109
  const images = [];
110
+ const skipped = [];
76
111
  // diagram name → the model's display name, for the index cards
77
112
  const titles = new Map();
78
113
  for (const d of chosen) {
@@ -91,7 +126,7 @@ export async function publishDiagrams(opts) {
91
126
  if (isDrawings(parsed))
92
127
  drawings = parsed;
93
128
  else
94
- console.warn(`publish: ignoring malformed drawings sidecar for diagram "${d.name}" (${d.drawingsPath}); the page ships without ink.`);
129
+ warn(`publish: ignoring malformed drawings sidecar for diagram "${d.name}" (${d.drawingsPath}); the page ships without ink.`);
95
130
  }
96
131
  const inlined = await inlineAssets(modelRaw, opts, cache, `diagram "${d.name}"`);
97
132
  const pagePath = path.join(opts.htmlDir, `${d.name}.html`);
@@ -99,14 +134,13 @@ export async function publishDiagrams(opts) {
99
134
  await writeFile(pagePath, stampHtml(shell, { model: inlined, layout, drawings }));
100
135
  pages.push(pagePath);
101
136
  if (opts.images && opts.renderPng !== undefined) {
102
- const pngPath = path.join(opts.staticDir, `${d.name}.png`);
103
- await mkdir(path.dirname(pngPath), { recursive: true });
104
- await opts.renderPng(pagePath, pngPath);
105
- 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)));
106
139
  }
107
140
  }
108
141
  catch (e) {
109
- console.warn(`publish: skipping diagram "${d.name}": ${errMessage(e)}`);
142
+ warn(`publish: skipping diagram "${d.name}": ${errMessage(e)}`);
143
+ skipped.push(d.name);
110
144
  continue;
111
145
  }
112
146
  }
@@ -134,5 +168,5 @@ export async function publishDiagrams(opts) {
134
168
  }
135
169
  const galleryPath = path.join(opts.htmlDir, 'index.html');
136
170
  await writeFile(galleryPath, buildGallery(entries, opts.link !== undefined ? { link: opts.link } : {}));
137
- return { pages, images, gallery: galleryPath };
171
+ return { pages, images, gallery: galleryPath, skipped };
138
172
  }
@@ -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
  });
@@ -11,3 +11,14 @@ export interface SnapshotSession {
11
11
  * detection and nested relative resolution behave exactly as unlocked fetches.
12
12
  */
13
13
  export declare function snapshotSession(base: IncludeResolver, rootDir: string, mode: SnapshotMode): SnapshotSession;
14
+ /**
15
+ * The include resolver for every run that is not an update: a remote include comes
16
+ * from the lock and its vendored copy, never from the network. Only `compile` and
17
+ * `publish` with `--update-includes` fetch and rewrite the lock; the studio's reads,
18
+ * its watch loop, eject's recompile and a `loadModel` call given no resolver must not
19
+ * fetch or vendor on anyone's behalf, so an include the lock does not hold fails.
20
+ *
21
+ * `diagramsDir` is the sources' folder, `.diagrams/src`. The lock and the vendored
22
+ * includes sit in its parent, the `.diagrams` root, where an update run writes them.
23
+ */
24
+ export declare function lockedResolverFor(diagramsDir: string): IncludeResolver;
package/dist/snapshots.js CHANGED
@@ -2,8 +2,12 @@ import { createHash } from 'node:crypto';
2
2
  import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
3
3
  import path from 'node:path';
4
4
  import { IncludeError } from '@diagc/core/internal';
5
- const LOCK_NAME = 'includes.lock.json';
6
- const VENDOR_DIR = 'includes';
5
+ import { resolveInclude } from './includes.js';
6
+ import { RELATIVE_PATHS } from './paths.js';
7
+ /** The lock's and the vendored snapshots' names in the `.diagrams` folder a session is
8
+ * given; the lock names each snapshot by its path from that folder. */
9
+ const LOCK_NAME = path.posix.basename(RELATIVE_PATHS.lockFile);
10
+ const VENDOR_DIR = path.posix.basename(RELATIVE_PATHS.includesDir);
7
11
  const isHttp = (s) => /^https?:\/\//.test(s);
8
12
  const digest = (text) => createHash('sha256').update(text).digest('hex');
9
13
  /** vendor file name: url basename (sanitized) + hash prefix, collision-proof by content */
@@ -56,7 +60,7 @@ export function snapshotSession(base, rootDir, mode) {
56
60
  if (mode === 'locked') {
57
61
  const entry = l.includes[url];
58
62
  if (entry === undefined) {
59
- throw new IncludeError(spec, `Include '${url}' is not snapshotted — run 'diagc compile --update-includes' and commit .diagrams/${VENDOR_DIR}/ + .diagrams/${LOCK_NAME}`);
63
+ throw new IncludeError(spec, `Include '${url}' is not snapshotted — run 'diagc compile --update-includes' and commit ${RELATIVE_PATHS.includesDir}/ + ${RELATIVE_PATHS.lockFile}`);
60
64
  }
61
65
  let text;
62
66
  try {
@@ -111,3 +115,16 @@ export function snapshotSession(base, rootDir, mode) {
111
115
  };
112
116
  return { resolver, prune };
113
117
  }
118
+ /**
119
+ * The include resolver for every run that is not an update: a remote include comes
120
+ * from the lock and its vendored copy, never from the network. Only `compile` and
121
+ * `publish` with `--update-includes` fetch and rewrite the lock; the studio's reads,
122
+ * its watch loop, eject's recompile and a `loadModel` call given no resolver must not
123
+ * fetch or vendor on anyone's behalf, so an include the lock does not hold fails.
124
+ *
125
+ * `diagramsDir` is the sources' folder, `.diagrams/src`. The lock and the vendored
126
+ * includes sit in its parent, the `.diagrams` root, where an update run writes them.
127
+ */
128
+ export function lockedResolverFor(diagramsDir) {
129
+ return snapshotSession(resolveInclude, path.dirname(diagramsDir), 'locked').resolver;
130
+ }
package/dist/studio.js CHANGED
@@ -1,15 +1,15 @@
1
1
  import { spawn } from 'node:child_process';
2
2
  import { mkdir } from 'node:fs/promises';
3
- import path from 'node:path';
4
- import { resolveInclude } from './includes.js';
3
+ import { projectPaths } from './paths.js';
5
4
  import { startStudioServer } from './serve.js';
6
- import { snapshotSession } from './snapshots.js';
5
+ import { lockedResolverFor } from './snapshots.js';
7
6
  import { formatCompileEvent, startWatch } from './watch.js';
8
7
  /** Env that points the monorepo's studio Vite server at the target repo. */
9
8
  export function studioEnv(cwd) {
9
+ const { srcDir, artifactsDir } = projectPaths(cwd);
10
10
  return {
11
- DIAGRAMS_DIR: path.join(cwd, '.diagrams', 'src'),
12
- ARTIFACTS_DIR: path.join(cwd, '.diagrams', '.artifacts'),
11
+ DIAGRAMS_DIR: srcDir,
12
+ ARTIFACTS_DIR: artifactsDir,
13
13
  DIAGRAMS_CWD: cwd,
14
14
  DIAGRAMS_OPEN: '1',
15
15
  };
@@ -51,9 +51,9 @@ export async function runStudio(home, cwd) {
51
51
  // Studio's live watch-compile loop always resolves includes locked, same as
52
52
  // the one-shot `compile`/`watch` commands default to — the studio has no
53
53
  // `--update-includes` surface, so there is no other mode to offer here.
54
- // rootDir is `<cwd>/.diagrams` (not process.cwd()'s `.diagrams`), matching
55
- // env.DIAGRAMS_DIR/ARTIFACTS_DIR above: runStudio targets an arbitrary repo.
56
- const { resolver } = snapshotSession(resolveInclude, path.join(cwd, '.diagrams'), 'locked');
54
+ // The lock is found from env.DIAGRAMS_DIR (not process.cwd()'s `.diagrams`),
55
+ // like the sources and artifacts: runStudio targets an arbitrary repo.
56
+ const resolver = lockedResolverFor(env.DIAGRAMS_DIR);
57
57
  const watcher = startWatch(env.DIAGRAMS_DIR, env.ARTIFACTS_DIR, {
58
58
  coreEntry: home.coreEntry,
59
59
  resolver,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@diagc/cli",
3
- "version": "1.1.6",
3
+ "version": "1.2.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.6"
47
+ "@diagc/core": "1.2.0"
48
48
  },
49
49
  "publishConfig": {
50
50
  "access": "public"