@diagc/cli 1.1.6 → 1.1.7
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/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 +6 -4
- package/dist/publish/publish.js +11 -7
- 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/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
|
@@ -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,19 +48,20 @@ 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
|
}
|
|
62
63
|
export async function publishDiagrams(opts) {
|
|
64
|
+
const warn = opts.warn ?? console.warn;
|
|
63
65
|
const shell = await readFile(opts.shellPath, 'utf8');
|
|
64
66
|
await mkdir(opts.htmlDir, { recursive: true });
|
|
65
67
|
if (opts.images)
|
|
@@ -73,6 +75,7 @@ export async function publishDiagrams(opts) {
|
|
|
73
75
|
}
|
|
74
76
|
const pages = [];
|
|
75
77
|
const images = [];
|
|
78
|
+
const skipped = [];
|
|
76
79
|
// diagram name → the model's display name, for the index cards
|
|
77
80
|
const titles = new Map();
|
|
78
81
|
for (const d of chosen) {
|
|
@@ -91,7 +94,7 @@ export async function publishDiagrams(opts) {
|
|
|
91
94
|
if (isDrawings(parsed))
|
|
92
95
|
drawings = parsed;
|
|
93
96
|
else
|
|
94
|
-
|
|
97
|
+
warn(`publish: ignoring malformed drawings sidecar for diagram "${d.name}" (${d.drawingsPath}); the page ships without ink.`);
|
|
95
98
|
}
|
|
96
99
|
const inlined = await inlineAssets(modelRaw, opts, cache, `diagram "${d.name}"`);
|
|
97
100
|
const pagePath = path.join(opts.htmlDir, `${d.name}.html`);
|
|
@@ -106,7 +109,8 @@ export async function publishDiagrams(opts) {
|
|
|
106
109
|
}
|
|
107
110
|
}
|
|
108
111
|
catch (e) {
|
|
109
|
-
|
|
112
|
+
warn(`publish: skipping diagram "${d.name}": ${errMessage(e)}`);
|
|
113
|
+
skipped.push(d.name);
|
|
110
114
|
continue;
|
|
111
115
|
}
|
|
112
116
|
}
|
|
@@ -134,5 +138,5 @@ export async function publishDiagrams(opts) {
|
|
|
134
138
|
}
|
|
135
139
|
const galleryPath = path.join(opts.htmlDir, 'index.html');
|
|
136
140
|
await writeFile(galleryPath, buildGallery(entries, opts.link !== undefined ? { link: opts.link } : {}));
|
|
137
|
-
return { pages, images, gallery: galleryPath };
|
|
141
|
+
return { pages, images, gallery: galleryPath, skipped };
|
|
138
142
|
}
|
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.1.
|
|
3
|
+
"version": "1.1.7",
|
|
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.
|
|
47
|
+
"@diagc/core": "1.1.7"
|
|
48
48
|
},
|
|
49
49
|
"publishConfig": {
|
|
50
50
|
"access": "public"
|
package/dist/command-args.d.ts
DELETED
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
import type { Args } from './cli.js';
|
|
2
|
-
/** Thrown by {@link checkCommandArgs} for a flag or an argument the command does not
|
|
3
|
-
* take; `main` reports it the same way as an unknown flag. */
|
|
4
|
-
export declare class ArgNotTakenError extends Error {
|
|
5
|
-
constructor(message: string);
|
|
6
|
-
}
|
|
7
|
-
/** Refuse a flag or an argument `args.command` does not take. Ignored, it would be a
|
|
8
|
-
* wrong file set or an output the user never sees (`init --out build`). */
|
|
9
|
-
export declare function checkCommandArgs(args: Args): void;
|
package/dist/command-args.js
DELETED
|
@@ -1,56 +0,0 @@
|
|
|
1
|
-
/** Thrown by {@link checkCommandArgs} for a flag or an argument the command does not
|
|
2
|
-
* take; `main` reports it the same way as an unknown flag. */
|
|
3
|
-
export class ArgNotTakenError extends Error {
|
|
4
|
-
constructor(message) {
|
|
5
|
-
super(message);
|
|
6
|
-
this.name = 'ArgNotTakenError';
|
|
7
|
-
}
|
|
8
|
-
}
|
|
9
|
-
const LOCKED = { '--update-includes': 'it always resolves includes locked' };
|
|
10
|
-
/** What each command takes: the flags the reference's flag table lists for it, and a
|
|
11
|
-
* cap on positional arguments where the command has no message of its own for extra
|
|
12
|
-
* ones. `why` says why a flag another command takes means nothing here. */
|
|
13
|
-
const TAKES = {
|
|
14
|
-
compile: { flags: ['--out', '--update-includes'] },
|
|
15
|
-
lint: { flags: ['--json'] },
|
|
16
|
-
watch: { flags: ['--out'], max: [1, 'one directory'], why: LOCKED },
|
|
17
|
-
publish: { flags: ['--out', '--no-images', '--link', '--update-includes'] },
|
|
18
|
-
studio: { flags: [], max: [0, 'no arguments'], why: LOCKED },
|
|
19
|
-
eject: { flags: ['--out'], max: [1, 'one diagram name'], why: LOCKED },
|
|
20
|
-
diff: { flags: ['--out', '--no-images', '--json', '--labels', '--image-url'] },
|
|
21
|
-
guide: { flags: [] },
|
|
22
|
-
init: { flags: ['--type', '--agents'] },
|
|
23
|
-
};
|
|
24
|
-
/** The flags `args` says were passed. */
|
|
25
|
-
function flagsGiven(args) {
|
|
26
|
-
const given = [
|
|
27
|
-
[args.outGiven, '--out'],
|
|
28
|
-
[!args.images, '--no-images'],
|
|
29
|
-
[args.link !== undefined, '--link'],
|
|
30
|
-
[args.json, '--json'],
|
|
31
|
-
[args.labels !== undefined, '--labels'],
|
|
32
|
-
[args.imageUrl !== undefined, '--image-url'],
|
|
33
|
-
[args.updateIncludes, '--update-includes'],
|
|
34
|
-
[args.type !== undefined, '--type'],
|
|
35
|
-
[args.agents, '--agents'],
|
|
36
|
-
];
|
|
37
|
-
return given.filter(([on]) => on).map(([, flag]) => flag);
|
|
38
|
-
}
|
|
39
|
-
/** Refuse a flag or an argument `args.command` does not take. Ignored, it would be a
|
|
40
|
-
* wrong file set or an output the user never sees (`init --out build`). */
|
|
41
|
-
export function checkCommandArgs(args) {
|
|
42
|
-
const takes = TAKES[args.command];
|
|
43
|
-
if (takes === undefined)
|
|
44
|
-
return; // an unknown command has its own message
|
|
45
|
-
for (const flag of flagsGiven(args)) {
|
|
46
|
-
if (takes.flags.includes(flag))
|
|
47
|
-
continue;
|
|
48
|
-
const takers = Object.keys(TAKES).filter((c) => TAKES[c].flags.includes(flag));
|
|
49
|
-
const list = takers.length === 1 ? takers[0] : `${takers.slice(0, -1).join(', ')} and ${takers.at(-1)}`;
|
|
50
|
-
const why = takes.why?.[flag] === undefined ? '' : ` (${takes.why[flag]})`;
|
|
51
|
-
throw new ArgNotTakenError(`${args.command} does not take ${flag}${why}; ${list} ${takers.length === 1 ? 'does' : 'do'}.`);
|
|
52
|
-
}
|
|
53
|
-
const extra = takes.max === undefined ? undefined : args.files[takes.max[0]];
|
|
54
|
-
if (extra !== undefined)
|
|
55
|
-
throw new ArgNotTakenError(`${args.command} takes ${takes.max[1]}; '${extra}' is one too many.`);
|
|
56
|
-
}
|
package/dist/diff.d.ts
DELETED
|
@@ -1,61 +0,0 @@
|
|
|
1
|
-
import { type DiagramModel, type Drawings, type LayoutOverlay, type ModelDiff } from '@diagc/core/internal';
|
|
2
|
-
/** One diagram as a version of the repo had it: the compiled model plus the
|
|
3
|
-
* sidecars a picture of it needs. */
|
|
4
|
-
export interface DiagramVersion {
|
|
5
|
-
model: DiagramModel;
|
|
6
|
-
layout?: LayoutOverlay;
|
|
7
|
-
drawings?: Drawings;
|
|
8
|
-
}
|
|
9
|
-
/** Every diagram under one `.diagrams/` directory, by name (its path under
|
|
10
|
-
* `src/` without the extension — the names `publish` uses). */
|
|
11
|
-
export interface DiagramSet {
|
|
12
|
-
/** shown in the summary and on the pictures: a ref, or "working tree" */
|
|
13
|
-
label: string;
|
|
14
|
-
diagramsDir: string;
|
|
15
|
-
versions: Map<string, DiagramVersion>;
|
|
16
|
-
/** diagrams whose source did not compile at this version, with why */
|
|
17
|
-
errors: Map<string, string>;
|
|
18
|
-
}
|
|
19
|
-
export type DiagramDiffStatus = 'added' | 'removed' | 'changed' | 'unchanged' | 'error';
|
|
20
|
-
export interface DiagramDiff {
|
|
21
|
-
name: string;
|
|
22
|
-
status: DiagramDiffStatus;
|
|
23
|
-
before?: DiagramVersion;
|
|
24
|
-
after?: DiagramVersion;
|
|
25
|
-
/** against an empty model for an added or removed diagram, so the marks
|
|
26
|
-
* cover the whole picture the same way */
|
|
27
|
-
diff?: ModelDiff;
|
|
28
|
-
error?: string;
|
|
29
|
-
}
|
|
30
|
-
/** Compile every source under `diagramsDir/src` in memory — nothing is written. */
|
|
31
|
-
export declare function loadDiagramSet(label: string, diagramsDir: string, coreEntry?: string): Promise<DiagramSet>;
|
|
32
|
-
/** Pair the two sets by name. `names` narrows the result to those diagrams. */
|
|
33
|
-
export declare function compareDiagramSets(before: DiagramSet, after: DiagramSet, names?: readonly string[]): DiagramDiff[];
|
|
34
|
-
/** The change list for one diagram, one line each, `+`/`-`/`~` first. */
|
|
35
|
-
export declare function describeDiff(d: DiagramDiff): string[];
|
|
36
|
-
export declare function formatDiffSummary(diffs: readonly DiagramDiff[], from: string, to: string): string;
|
|
37
|
-
export interface DiffPagesOptions {
|
|
38
|
-
outDir: string;
|
|
39
|
-
shellPath: string;
|
|
40
|
-
libraryDir: string;
|
|
41
|
-
before: DiagramSet;
|
|
42
|
-
after: DiagramSet;
|
|
43
|
-
renderPng?: (htmlPath: string, pngPath: string) => Promise<void>;
|
|
44
|
-
/** where `summary.md`'s images will be served from, `{path}` standing for
|
|
45
|
-
* each PNG's path under `outDir` — for a summary posted somewhere else (a PR
|
|
46
|
-
* comment), where the relative links would not resolve */
|
|
47
|
-
imageUrl?: string;
|
|
48
|
-
}
|
|
49
|
-
export interface DiffPagesResult {
|
|
50
|
-
pages: string[];
|
|
51
|
-
images: string[];
|
|
52
|
-
index: string;
|
|
53
|
-
summary: string;
|
|
54
|
-
}
|
|
55
|
-
/**
|
|
56
|
-
* A page per side of every diagram that changed — the same single-file viewer
|
|
57
|
-
* `publish` writes, with the changes outlined — plus a PNG of each when
|
|
58
|
-
* `renderPng` is given, an `index.html` showing the two sides next to each
|
|
59
|
-
* other, and a `summary.md` laid out to paste into an ADR.
|
|
60
|
-
*/
|
|
61
|
-
export declare function writeDiffPages(diffs: readonly DiagramDiff[], opts: DiffPagesOptions): Promise<DiffPagesResult>;
|
package/dist/diff.js
DELETED
|
@@ -1,244 +0,0 @@
|
|
|
1
|
-
import { existsSync } from 'node:fs';
|
|
2
|
-
import { mkdir, readFile, writeFile } from 'node:fs/promises';
|
|
3
|
-
import path from 'node:path';
|
|
4
|
-
import fg from 'fast-glob';
|
|
5
|
-
import { diffMarks, diffModels, errMessage, isDrawings, isEmptyDiff, } from '@diagc/core/internal';
|
|
6
|
-
import { loadModel } from './compile.js';
|
|
7
|
-
import { inlineAssets } from './publish/publish.js';
|
|
8
|
-
import { stampHtml } from './publish/html.js';
|
|
9
|
-
import { THEME_HEAD_SCRIPT, THEME_SWITCH, themeCss } from './publish/pageTheme.js';
|
|
10
|
-
const EMPTY = {
|
|
11
|
-
version: 1,
|
|
12
|
-
id: '',
|
|
13
|
-
name: '',
|
|
14
|
-
nodes: [],
|
|
15
|
-
containment: [],
|
|
16
|
-
relations: [],
|
|
17
|
-
layers: [],
|
|
18
|
-
planes: [],
|
|
19
|
-
};
|
|
20
|
-
async function readJson(file) {
|
|
21
|
-
return existsSync(file) ? JSON.parse(await readFile(file, 'utf8')) : undefined;
|
|
22
|
-
}
|
|
23
|
-
/** Compile every source under `diagramsDir/src` in memory — nothing is written. */
|
|
24
|
-
export async function loadDiagramSet(label, diagramsDir, coreEntry) {
|
|
25
|
-
const srcDir = path.join(diagramsDir, 'src');
|
|
26
|
-
const versions = new Map();
|
|
27
|
-
const errors = new Map();
|
|
28
|
-
const files = existsSync(srcDir) ? await fg('**/*.diagram.{ts,json}', { cwd: srcDir }) : [];
|
|
29
|
-
for (const rel of files.sort()) {
|
|
30
|
-
const name = rel.replace(/\.diagram\.(ts|json)$/, '');
|
|
31
|
-
try {
|
|
32
|
-
const model = await loadModel(path.join(srcDir, rel), {
|
|
33
|
-
rootDir: srcDir,
|
|
34
|
-
...(coreEntry !== undefined ? { coreEntry } : {}),
|
|
35
|
-
});
|
|
36
|
-
const layout = (await readJson(path.join(srcDir, `${name}.layout.json`)));
|
|
37
|
-
const drawings = await readJson(path.join(srcDir, `${name}.drawings.json`));
|
|
38
|
-
versions.set(name, {
|
|
39
|
-
model,
|
|
40
|
-
...(layout !== undefined ? { layout } : {}),
|
|
41
|
-
...(drawings !== undefined && isDrawings(drawings) ? { drawings } : {}),
|
|
42
|
-
});
|
|
43
|
-
}
|
|
44
|
-
catch (e) {
|
|
45
|
-
errors.set(name, errMessage(e));
|
|
46
|
-
}
|
|
47
|
-
}
|
|
48
|
-
return { label, diagramsDir, versions, errors };
|
|
49
|
-
}
|
|
50
|
-
/** Pair the two sets by name. `names` narrows the result to those diagrams. */
|
|
51
|
-
export function compareDiagramSets(before, after, names = []) {
|
|
52
|
-
const all = new Set([
|
|
53
|
-
...before.versions.keys(),
|
|
54
|
-
...before.errors.keys(),
|
|
55
|
-
...after.versions.keys(),
|
|
56
|
-
...after.errors.keys(),
|
|
57
|
-
]);
|
|
58
|
-
const wanted = names.length > 0 ? names.filter((n) => all.has(n)) : [...all].sort();
|
|
59
|
-
return wanted.map((name) => {
|
|
60
|
-
const b = before.versions.get(name);
|
|
61
|
-
const a = after.versions.get(name);
|
|
62
|
-
const err = after.errors.get(name) ?? before.errors.get(name);
|
|
63
|
-
if (err !== undefined) {
|
|
64
|
-
const at = after.errors.has(name) ? after.label : before.label;
|
|
65
|
-
return { name, status: 'error', error: `does not compile at ${at}: ${err}` };
|
|
66
|
-
}
|
|
67
|
-
if (b === undefined)
|
|
68
|
-
return { name, status: 'added', after: a, diff: diffModels(EMPTY, a.model) };
|
|
69
|
-
if (a === undefined)
|
|
70
|
-
return { name, status: 'removed', before: b, diff: diffModels(b.model, EMPTY) };
|
|
71
|
-
const diff = diffModels(b.model, a.model);
|
|
72
|
-
return { name, status: isEmptyDiff(diff) ? 'unchanged' : 'changed', before: b, after: a, diff };
|
|
73
|
-
});
|
|
74
|
-
}
|
|
75
|
-
function nameIn(m, id) {
|
|
76
|
-
const n = m?.nodes.find((x) => x.id === id);
|
|
77
|
-
return n === undefined || n.name === '' ? id : n.name;
|
|
78
|
-
}
|
|
79
|
-
/** The change list for one diagram, one line each, `+`/`-`/`~` first. */
|
|
80
|
-
export function describeDiff(d) {
|
|
81
|
-
if (d.diff === undefined)
|
|
82
|
-
return [];
|
|
83
|
-
if (d.status === 'added')
|
|
84
|
-
return [
|
|
85
|
-
`+ new diagram: ${d.after.model.name} (${d.diff.nodes.added.length} nodes, ${d.diff.relations.added.length} relations)`,
|
|
86
|
-
];
|
|
87
|
-
if (d.status === 'removed')
|
|
88
|
-
return [`- diagram removed: ${d.before.model.name}`];
|
|
89
|
-
const before = d.before?.model;
|
|
90
|
-
const after = d.after?.model;
|
|
91
|
-
const rel = (m, r) => `${nameIn(m, r.from)} -> ${nameIn(m, r.to)} (${r.kind}${r.label !== undefined && r.label !== '' ? `: ${r.label}` : ''})`;
|
|
92
|
-
const x = d.diff;
|
|
93
|
-
return [
|
|
94
|
-
...x.nodes.added.map((n) => `+ ${n.name !== '' ? n.name : n.id}${n.type !== undefined ? ` [${n.type}]` : ''}`),
|
|
95
|
-
...x.nodes.removed.map((n) => `- ${n.name !== '' ? n.name : n.id}${n.type !== undefined ? ` [${n.type}]` : ''}`),
|
|
96
|
-
...x.nodes.changed.map((n) => {
|
|
97
|
-
// A rename reads better as the two names than as the word "name".
|
|
98
|
-
const was = nameIn(before, n.id);
|
|
99
|
-
const now = nameIn(after, n.id);
|
|
100
|
-
const rest = n.fields.filter((f) => f !== 'name');
|
|
101
|
-
const head = n.fields.includes('name') ? `${was} -> ${now} (renamed)` : now;
|
|
102
|
-
return `~ ${head}${rest.length > 0 ? `: ${rest.join(', ')}` : ''}`;
|
|
103
|
-
}),
|
|
104
|
-
...x.relations.added.map((r) => `+ ${rel(after, r)}`),
|
|
105
|
-
...x.relations.removed.map((r) => `- ${rel(before, r)}`),
|
|
106
|
-
...x.relations.changed.map((r) => {
|
|
107
|
-
const now = after?.relations.find((y) => y.id === r.after);
|
|
108
|
-
return `~ ${now !== undefined ? rel(after, now) : r.after}: ${r.fields.join(', ')}`;
|
|
109
|
-
}),
|
|
110
|
-
...x.layers.added.map((id) => `+ layer ${id}`),
|
|
111
|
-
...x.layers.removed.map((id) => `- layer ${id}`),
|
|
112
|
-
...x.planes.added.map((id) => `+ plane ${id}`),
|
|
113
|
-
...x.planes.removed.map((id) => `- plane ${id}`),
|
|
114
|
-
];
|
|
115
|
-
}
|
|
116
|
-
export function formatDiffSummary(diffs, from, to) {
|
|
117
|
-
const lines = [`diagc diff ${from} -> ${to}`];
|
|
118
|
-
for (const d of diffs) {
|
|
119
|
-
if (d.status === 'unchanged')
|
|
120
|
-
continue;
|
|
121
|
-
if (d.status === 'error') {
|
|
122
|
-
lines.push(`! ${d.name}: ${d.error}`);
|
|
123
|
-
continue;
|
|
124
|
-
}
|
|
125
|
-
lines.push(`${d.name}:`);
|
|
126
|
-
for (const l of describeDiff(d))
|
|
127
|
-
lines.push(` ${l}`);
|
|
128
|
-
}
|
|
129
|
-
const changed = diffs.filter((d) => d.status !== 'unchanged' && d.status !== 'error').length;
|
|
130
|
-
const same = diffs.filter((d) => d.status === 'unchanged').length;
|
|
131
|
-
lines.push(changed === 0 ? `no diagram changed (${same} compared)` : `${changed} diagram(s) changed, ${same} unchanged`);
|
|
132
|
-
return lines.join('\n');
|
|
133
|
-
}
|
|
134
|
-
const escapeHtml = (s) => s.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"');
|
|
135
|
-
/**
|
|
136
|
-
* A page per side of every diagram that changed — the same single-file viewer
|
|
137
|
-
* `publish` writes, with the changes outlined — plus a PNG of each when
|
|
138
|
-
* `renderPng` is given, an `index.html` showing the two sides next to each
|
|
139
|
-
* other, and a `summary.md` laid out to paste into an ADR.
|
|
140
|
-
*/
|
|
141
|
-
export async function writeDiffPages(diffs, opts) {
|
|
142
|
-
const shell = await readFile(opts.shellPath, 'utf8');
|
|
143
|
-
await mkdir(opts.outDir, { recursive: true });
|
|
144
|
-
const caches = { before: new Map(), after: new Map() };
|
|
145
|
-
const pages = [];
|
|
146
|
-
const images = [];
|
|
147
|
-
const shown = diffs.filter((d) => d.status === 'added' || d.status === 'removed' || d.status === 'changed');
|
|
148
|
-
const files = new Map();
|
|
149
|
-
for (const d of shown) {
|
|
150
|
-
const entry = { png: opts.renderPng !== undefined };
|
|
151
|
-
for (const side of ['before', 'after']) {
|
|
152
|
-
const v = d[side];
|
|
153
|
-
if (v === undefined)
|
|
154
|
-
continue;
|
|
155
|
-
const set = opts[side];
|
|
156
|
-
const model = await inlineAssets(v.model, { libraryDir: opts.libraryDir, assetsDir: path.join(set.diagramsDir, 'src', 'assets') }, caches[side], `diagram "${d.name}" at ${set.label}`);
|
|
157
|
-
const rel = `${d.name}.${side}`;
|
|
158
|
-
const pagePath = path.join(opts.outDir, `${rel}.html`);
|
|
159
|
-
await mkdir(path.dirname(pagePath), { recursive: true });
|
|
160
|
-
await writeFile(pagePath, stampHtml(shell, {
|
|
161
|
-
model,
|
|
162
|
-
...(v.layout !== undefined ? { layout: v.layout } : {}),
|
|
163
|
-
...(v.drawings !== undefined ? { drawings: v.drawings } : {}),
|
|
164
|
-
diff: { marks: diffMarks(d.diff, side) },
|
|
165
|
-
}));
|
|
166
|
-
pages.push(pagePath);
|
|
167
|
-
entry[side] = rel;
|
|
168
|
-
if (opts.renderPng !== undefined) {
|
|
169
|
-
const pngPath = path.join(opts.outDir, `${rel}.png`);
|
|
170
|
-
await opts.renderPng(pagePath, pngPath);
|
|
171
|
-
images.push(pngPath);
|
|
172
|
-
}
|
|
173
|
-
}
|
|
174
|
-
files.set(d.name, entry);
|
|
175
|
-
}
|
|
176
|
-
const from = opts.before.label;
|
|
177
|
-
const to = opts.after.label;
|
|
178
|
-
const index = path.join(opts.outDir, 'index.html');
|
|
179
|
-
await writeFile(index, indexHtml(shown, files, from, to));
|
|
180
|
-
const summary = path.join(opts.outDir, 'summary.md');
|
|
181
|
-
await writeFile(summary, summaryMarkdown(diffs, files, from, to, opts.imageUrl));
|
|
182
|
-
return { pages, images, index, summary };
|
|
183
|
-
}
|
|
184
|
-
// The frames load each page unfolded (`?export=1`, the PNG's own mode): side by
|
|
185
|
-
// side, the whole picture is the point. The headings link the interactive pages.
|
|
186
|
-
// The overview's two palettes. The frames are export renders and stay light in both, and
|
|
187
|
-
// so do the swatches of the key, which show the outline colours drawn in those pictures.
|
|
188
|
-
const OVERVIEW_LIGHT = '--bg:#fff;--card:#fff;--border:#d0d7de;--text:#1f2328;--muted:#57606a;--faint:#8c959f;--add:#16a34a;--del:#dc2626;--chg:#b45309';
|
|
189
|
-
const OVERVIEW_DARK = '--bg:#12161b;--card:#1b222b;--border:#2d3743;--text:#e6ebf0;--muted:#a3afbb;--faint:#8b98a5;--add:#4ade80;--del:#f87171;--chg:#fbbf24';
|
|
190
|
-
function indexHtml(shown, files, from, to) {
|
|
191
|
-
const side = (rel, label) => rel === undefined
|
|
192
|
-
? `<div class="side empty"><h3>${escapeHtml(label)}</h3><p>not present</p></div>`
|
|
193
|
-
: `<div class="side"><h3><a href="${escapeHtml(rel)}.html">${escapeHtml(label)}</a></h3><iframe src="${escapeHtml(rel)}.html?export=1" title="${escapeHtml(label)}"></iframe></div>`;
|
|
194
|
-
const sections = shown.map((d) => {
|
|
195
|
-
const f = files.get(d.name) ?? {};
|
|
196
|
-
const list = describeDiff(d)
|
|
197
|
-
.map((l) => `<li class="${l[0] === '+' ? 'add' : l[0] === '-' ? 'del' : 'chg'}">${escapeHtml(l)}</li>`)
|
|
198
|
-
.join('');
|
|
199
|
-
return `<section><h2>${escapeHtml(d.name)}</h2><ul>${list}</ul><div class="pair">${side(f.before, `Before · ${from}`)}${side(f.after, `After · ${to}`)}</div></section>`;
|
|
200
|
-
});
|
|
201
|
-
return `<!doctype html>
|
|
202
|
-
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
|
|
203
|
-
<title>Diagram diff ${escapeHtml(from)} → ${escapeHtml(to)}</title>
|
|
204
|
-
${THEME_HEAD_SCRIPT}
|
|
205
|
-
<style>
|
|
206
|
-
${themeCss(OVERVIEW_LIGHT, OVERVIEW_DARK)}
|
|
207
|
-
body { font: 14px/1.45 system-ui, sans-serif; margin: 0 auto; padding: 16px 24px 48px; max-width: 1800px; color: var(--text); background: var(--bg); }
|
|
208
|
-
header { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; }
|
|
209
|
-
h1 { font-size: 20px; } h2 { font-size: 16px; margin: 32px 0 6px; } h3 { font-size: 13px; margin: 0 0 6px; color: var(--muted); }
|
|
210
|
-
ul { margin: 0 0 12px; padding-left: 18px; font-family: ui-monospace, monospace; font-size: 12.5px; }
|
|
211
|
-
li.add { color: var(--add); } li.del { color: var(--del); } li.chg { color: var(--chg); }
|
|
212
|
-
.key span { display: inline-block; margin-right: 14px; } .key i { display: inline-block; width: 12px; height: 12px; border: 3px solid; border-radius: 3px; vertical-align: -2px; margin-right: 4px; }
|
|
213
|
-
.pair { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
|
|
214
|
-
.side iframe { width: 100%; height: 70vh; border: 1px solid var(--border); border-radius: 6px; }
|
|
215
|
-
.side.empty p { height: 70vh; margin: 0; display: grid; place-items: center; border: 1px dashed var(--border); border-radius: 6px; color: var(--faint); }
|
|
216
|
-
@media (max-width: 900px) { .pair { grid-template-columns: 1fr; } }
|
|
217
|
-
</style></head><body>
|
|
218
|
-
<header><h1>Diagram diff · ${escapeHtml(from)} → ${escapeHtml(to)}</h1>${THEME_SWITCH}</header>
|
|
219
|
-
<p class="key"><span><i style="border-color:#16a34a"></i>added</span><span><i style="border-color:#dc2626;border-style:dashed"></i>removed</span><span><i style="border-color:#d97706"></i>changed</span><span><i style="border-color:#d97706;border-style:dashed"></i>holds a change (folded box, on the linked pages)</span></p>
|
|
220
|
-
${sections.length > 0 ? sections.join('\n') : '<p>No diagram changed.</p>'}
|
|
221
|
-
</body></html>
|
|
222
|
-
`;
|
|
223
|
-
}
|
|
224
|
-
function summaryMarkdown(diffs, files, from, to, imageUrl) {
|
|
225
|
-
const png = (rel) => (imageUrl !== undefined ? imageUrl.split('{path}').join(`${rel}.png`) : `${rel}.png`);
|
|
226
|
-
const out = [`# Diagram changes: ${from} → ${to}`, ''];
|
|
227
|
-
const shown = diffs.filter((d) => d.status !== 'unchanged');
|
|
228
|
-
if (shown.length === 0)
|
|
229
|
-
out.push('No diagram changed.', '');
|
|
230
|
-
for (const d of shown) {
|
|
231
|
-
out.push(`## ${d.name}`, '');
|
|
232
|
-
if (d.status === 'error') {
|
|
233
|
-
out.push(`Not compared: ${d.error}`, '');
|
|
234
|
-
continue;
|
|
235
|
-
}
|
|
236
|
-
const f = files.get(d.name);
|
|
237
|
-
const cell = (rel, label) => rel === undefined ? '—' : f?.png === true ? `})` : `[${label}](${rel}.html)`;
|
|
238
|
-
out.push(`| Before (${from}) | After (${to}) |`, '| --- | --- |', `| ${cell(f?.before, 'before')} | ${cell(f?.after, 'after')} |`, '');
|
|
239
|
-
for (const l of describeDiff(d))
|
|
240
|
-
out.push(`- \`${l[0]}\` ${l.slice(2)}`);
|
|
241
|
-
out.push('');
|
|
242
|
-
}
|
|
243
|
-
return out.join('\n');
|
|
244
|
-
}
|