@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.
- package/assets/guide/index.md +2 -2
- package/assets/studio/assets/index-B-KI19Kg.js +110 -0
- package/assets/studio/index.html +1 -1
- package/assets/viewer/index.html +33 -33
- package/dist/api/assets.d.ts +8 -0
- package/dist/api/assets.js +54 -0
- package/dist/api/diagrams.d.ts +27 -0
- package/dist/api/diagrams.js +269 -0
- package/dist/api/files.d.ts +7 -0
- package/dist/api/files.js +30 -0
- package/dist/api/handlers.d.ts +7 -62
- package/dist/api/handlers.js +10 -488
- package/dist/api/library.d.ts +5 -0
- package/dist/api/library.js +88 -0
- package/dist/api/result.d.ts +8 -0
- package/dist/api/result.js +5 -0
- package/dist/api/sidecars.d.ts +13 -0
- package/dist/api/sidecars.js +78 -0
- package/dist/cli/command.d.ts +26 -0
- package/dist/cli/command.js +1 -0
- package/dist/cli/io.d.ts +13 -0
- package/dist/cli/io.js +7 -0
- package/dist/cli/parse.d.ts +51 -0
- package/dist/cli/parse.js +109 -0
- package/dist/cli/run.d.ts +10 -0
- package/dist/cli/run.js +67 -0
- package/dist/cli.d.ts +1 -52
- package/dist/cli.js +5 -475
- package/dist/commands/compile.d.ts +3 -0
- package/dist/commands/compile.js +38 -0
- package/dist/commands/diff.d.ts +10 -0
- package/dist/commands/diff.js +96 -0
- package/dist/commands/eject.d.ts +3 -0
- package/dist/commands/eject.js +32 -0
- package/dist/commands/guide.d.ts +3 -0
- package/dist/commands/guide.js +13 -0
- package/dist/commands/init.d.ts +3 -0
- package/dist/commands/init.js +23 -0
- package/dist/commands/lint.d.ts +3 -0
- package/dist/commands/lint.js +27 -0
- package/dist/commands/publish.d.ts +11 -0
- package/dist/commands/publish.js +83 -0
- package/dist/commands/shared.d.ts +19 -0
- package/dist/commands/shared.js +34 -0
- package/dist/commands/studio.d.ts +3 -0
- package/dist/commands/studio.js +14 -0
- package/dist/commands/watch.d.ts +8 -0
- package/dist/commands/watch.js +45 -0
- package/dist/compile.d.ts +4 -1
- package/dist/compile.js +8 -13
- package/dist/diff/compare.d.ts +36 -0
- package/dist/diff/compare.js +36 -0
- package/dist/diff/describe.d.ts +8 -0
- package/dist/diff/describe.js +70 -0
- package/dist/diff/index.d.ts +4 -0
- package/dist/diff/index.js +6 -0
- package/dist/diff/load.d.ts +22 -0
- package/dist/diff/load.js +62 -0
- package/dist/diff/overview.d.ts +17 -0
- package/dist/diff/overview.js +86 -0
- package/dist/diff/pages.d.ts +27 -0
- package/dist/diff/pages.js +55 -0
- package/dist/diff/summary.d.ts +18 -0
- package/dist/diff/summary.js +26 -0
- package/dist/eject.js +2 -6
- package/dist/git-ref.js +21 -3
- package/dist/glob.d.ts +5 -0
- package/dist/glob.js +7 -0
- package/dist/init.d.ts +0 -3
- package/dist/init.js +14 -15
- package/dist/names.d.ts +3 -0
- package/dist/names.js +8 -0
- package/dist/paths.d.ts +29 -0
- package/dist/paths.js +25 -0
- package/dist/publish/discover.js +2 -1
- package/dist/publish/publish.d.ts +21 -5
- package/dist/publish/publish.js +46 -12
- package/dist/publish/snapshot.d.ts +4 -1
- package/dist/publish/snapshot.js +8 -3
- package/dist/snapshots.d.ts +11 -0
- package/dist/snapshots.js +20 -3
- package/dist/studio.js +8 -8
- package/package.json +2 -2
- package/assets/studio/assets/index-Cn03lgc3.js +0 -110
- package/dist/command-args.d.ts +0 -9
- package/dist/command-args.js +0 -56
- package/dist/diff.d.ts +0 -61
- package/dist/diff.js +0 -244
package/dist/publish/publish.js
CHANGED
|
@@ -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,
|
|
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' ?
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
103
|
-
await
|
|
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
|
-
|
|
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
|
-
|
|
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>;
|
package/dist/publish/snapshot.js
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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/dist/snapshots.d.ts
CHANGED
|
@@ -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
|
-
|
|
6
|
-
|
|
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 .
|
|
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
|
|
4
|
-
import { resolveInclude } from './includes.js';
|
|
3
|
+
import { projectPaths } from './paths.js';
|
|
5
4
|
import { startStudioServer } from './serve.js';
|
|
6
|
-
import {
|
|
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:
|
|
12
|
-
ARTIFACTS_DIR:
|
|
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
|
-
//
|
|
55
|
-
//
|
|
56
|
-
const
|
|
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.
|
|
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.
|
|
47
|
+
"@diagc/core": "1.2.0"
|
|
48
48
|
},
|
|
49
49
|
"publishConfig": {
|
|
50
50
|
"access": "public"
|