@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
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { errMessage } from '@diagc/core/internal';
|
|
2
|
+
import { ejectDiagram } from '../eject.js';
|
|
3
|
+
import { diagramName } from '../names.js';
|
|
4
|
+
import { RELATIVE_PATHS } from '../paths.js';
|
|
5
|
+
import { LOCKED } from './shared.js';
|
|
6
|
+
/** `diagc eject <name>`: a JSON diagram as a generated TypeScript source. */
|
|
7
|
+
export const eject = {
|
|
8
|
+
flags: ['--out'],
|
|
9
|
+
positionals: { max: 1, what: 'one diagram name' },
|
|
10
|
+
whyNot: LOCKED,
|
|
11
|
+
async run({ positionals, flags }, { io, usage, home }) {
|
|
12
|
+
// ejectDiagram's post-swap recompile always resolves includes locked (see
|
|
13
|
+
// eject.ts) — same reasoning as watch's.
|
|
14
|
+
const name = positionals[0] === undefined ? undefined : diagramName(positionals[0]);
|
|
15
|
+
if (name === undefined || name === '') {
|
|
16
|
+
io.err('diagc: eject needs a diagram name.');
|
|
17
|
+
io.err(usage);
|
|
18
|
+
return 1;
|
|
19
|
+
}
|
|
20
|
+
try {
|
|
21
|
+
const res = await ejectDiagram(RELATIVE_PATHS.srcDir, flags['--out'] ?? RELATIVE_PATHS.artifactsDir, name, {
|
|
22
|
+
coreEntry: home.coreEntry,
|
|
23
|
+
});
|
|
24
|
+
io.out(`✓ ${res.tsPath}`);
|
|
25
|
+
return 0;
|
|
26
|
+
}
|
|
27
|
+
catch (e) {
|
|
28
|
+
io.err(errMessage(e));
|
|
29
|
+
return 1;
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
};
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { runGuide } from '../guide.js';
|
|
2
|
+
import { cliVersion } from '../home.js';
|
|
3
|
+
/** `diagc guide [topic]`: how to write a diagram, as Markdown on stdout. */
|
|
4
|
+
export const guide = {
|
|
5
|
+
flags: [],
|
|
6
|
+
async run({ positionals }, { io, home }) {
|
|
7
|
+
// The guide is tens of kilobytes and is read through a pipe by an agent. It goes
|
|
8
|
+
// out as one plain write, as guide.ts's own default writes it, and the run ends
|
|
9
|
+
// only once the pipe has taken all of it: a page that stops mid-sentence would
|
|
10
|
+
// read as the whole guide.
|
|
11
|
+
return runGuide(positionals, { guideDir: home.guideDir, startersDir: home.startersDir, version: cliVersion(home.root) }, { out: (text) => io.write(`${text}\n`), err: io.err });
|
|
12
|
+
},
|
|
13
|
+
};
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { cliVersion } from '../home.js';
|
|
2
|
+
import { runInit } from '../init.js';
|
|
3
|
+
/** `diagc init [name]`: set a repository up for diagc. */
|
|
4
|
+
export const init = {
|
|
5
|
+
flags: ['--type', '--agents'],
|
|
6
|
+
async run({ positionals, flags }, { io, home, snapshots }) {
|
|
7
|
+
if (positionals.length > 1) {
|
|
8
|
+
io.err(`diagc: init takes one name, got ${positionals.length} — e.g. diagc init shop --type c4`);
|
|
9
|
+
return 1;
|
|
10
|
+
}
|
|
11
|
+
return runInit({
|
|
12
|
+
cwd: process.cwd(),
|
|
13
|
+
...(positionals[0] !== undefined ? { name: positionals[0] } : {}),
|
|
14
|
+
...(flags['--type'] !== undefined ? { type: flags['--type'] } : {}),
|
|
15
|
+
agents: flags['--agents'] === true,
|
|
16
|
+
startersDir: home.startersDir,
|
|
17
|
+
skillFile: home.skillFile,
|
|
18
|
+
version: cliVersion(home.root),
|
|
19
|
+
coreEntry: home.coreEntry,
|
|
20
|
+
resolver: snapshots.resolver,
|
|
21
|
+
}, io);
|
|
22
|
+
},
|
|
23
|
+
};
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { formatLintReport, lintFile } from '../lint.js';
|
|
2
|
+
import { globSorted } from '../glob.js';
|
|
3
|
+
import { RELATIVE_PATHS } from '../paths.js';
|
|
4
|
+
import { SOURCES, warnNoSources } from './shared.js';
|
|
5
|
+
/** `diagc lint [files...] [--json]`: every finding, and exit 1 on any. */
|
|
6
|
+
export const lint = {
|
|
7
|
+
flags: ['--json'],
|
|
8
|
+
async run({ positionals, flags }, { io, home, snapshots }) {
|
|
9
|
+
const files = positionals.length > 0 ? positionals : await globSorted(SOURCES);
|
|
10
|
+
if (positionals.length === 0 && files.length === 0)
|
|
11
|
+
warnNoSources(io);
|
|
12
|
+
const reports = [];
|
|
13
|
+
for (const file of files) {
|
|
14
|
+
reports.push(...(await lintFile(file, {
|
|
15
|
+
rootDir: RELATIVE_PATHS.srcDir,
|
|
16
|
+
coreEntry: home.coreEntry,
|
|
17
|
+
resolver: snapshots.resolver,
|
|
18
|
+
})));
|
|
19
|
+
}
|
|
20
|
+
if (flags['--json'] === true)
|
|
21
|
+
io.out(JSON.stringify(reports, null, 2));
|
|
22
|
+
else
|
|
23
|
+
for (const r of reports)
|
|
24
|
+
io.out(formatLintReport(r));
|
|
25
|
+
return reports.length > 0 ? 1 : 0;
|
|
26
|
+
},
|
|
27
|
+
};
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { Command } from '../cli/command.js';
|
|
2
|
+
import { type PublishOptions } from '../publish/publish.js';
|
|
3
|
+
type PublishDirs = Pick<PublishOptions, 'srcDir' | 'artifactsDir' | 'htmlDir' | 'staticDir' | 'assetsDir'>;
|
|
4
|
+
/** Where `publish` compiles to and builds pages from. One object for both steps, so
|
|
5
|
+
* the pages are always made from the artifacts this run just wrote. `--out` moves the
|
|
6
|
+
* artifacts only: the pages and PNGs stay where `.gitignore`, the docs and the READMEs
|
|
7
|
+
* that embed them expect to find them. */
|
|
8
|
+
export declare function publishDirs(out: string): PublishDirs;
|
|
9
|
+
/** `diagc publish [names...]`: compile, then a page per diagram, the gallery, and PNGs. */
|
|
10
|
+
export declare const publish: Command<'--out' | '--no-images' | '--link' | '--update-includes'>;
|
|
11
|
+
export {};
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs';
|
|
2
|
+
import { errMessage } from '@diagc/core/internal';
|
|
3
|
+
import { compileFile } from '../compile.js';
|
|
4
|
+
import { globSorted } from '../glob.js';
|
|
5
|
+
import { RELATIVE_PATHS } from '../paths.js';
|
|
6
|
+
import { discoverDiagrams } from '../publish/discover.js';
|
|
7
|
+
import { publishDiagrams } from '../publish/publish.js';
|
|
8
|
+
import { formatCompileEvent } from '../watch.js';
|
|
9
|
+
import { diagramNames, pngRenderer, warnNoSources } from './shared.js';
|
|
10
|
+
/** Where `publish` compiles to and builds pages from. One object for both steps, so
|
|
11
|
+
* the pages are always made from the artifacts this run just wrote. `--out` moves the
|
|
12
|
+
* artifacts only: the pages and PNGs stay where `.gitignore`, the docs and the READMEs
|
|
13
|
+
* that embed them expect to find them. */
|
|
14
|
+
export function publishDirs(out) {
|
|
15
|
+
const { srcDir, htmlDir, staticDir, assetsDir } = RELATIVE_PATHS;
|
|
16
|
+
return { srcDir, artifactsDir: out, htmlDir, staticDir, assetsDir };
|
|
17
|
+
}
|
|
18
|
+
/** Compile every source first, so the pages reflect the sources as they are (TS and
|
|
19
|
+
* include expansion), each failure on stderr in compile's form. Says whether one failed. */
|
|
20
|
+
async function compileSources(dirs, { io, home, snapshots }) {
|
|
21
|
+
const sources = await globSorted('**/*.diagram.{ts,json}', { cwd: dirs.srcDir, absolute: true });
|
|
22
|
+
if (sources.length === 0)
|
|
23
|
+
warnNoSources(io, dirs.srcDir);
|
|
24
|
+
let failed = false;
|
|
25
|
+
for (const f of sources) {
|
|
26
|
+
try {
|
|
27
|
+
await compileFile(f, dirs.artifactsDir, {
|
|
28
|
+
rootDir: dirs.srcDir,
|
|
29
|
+
coreEntry: home.coreEntry,
|
|
30
|
+
resolver: snapshots.resolver,
|
|
31
|
+
warn: io.err,
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
catch (e) {
|
|
35
|
+
failed = true;
|
|
36
|
+
io.err(formatCompileEvent({ file: f, ok: false, error: errMessage(e) }));
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
return failed;
|
|
40
|
+
}
|
|
41
|
+
/** `diagc publish [names...]`: compile, then a page per diagram, the gallery, and PNGs. */
|
|
42
|
+
export const publish = {
|
|
43
|
+
flags: ['--out', '--no-images', '--link', '--update-includes'],
|
|
44
|
+
async run({ positionals, flags }, ctx) {
|
|
45
|
+
const { io, home, snapshots } = ctx;
|
|
46
|
+
if (!existsSync(home.viewerShell)) {
|
|
47
|
+
// Only a checkout can be missing it; an installed package ships the shell,
|
|
48
|
+
// so there the message would send the reader off to build a repo they
|
|
49
|
+
// do not have.
|
|
50
|
+
io.err(home.layout === 'monorepo'
|
|
51
|
+
? 'viewer shell not built — run `pnpm --filter @diagc/viewer build` in the monorepo.'
|
|
52
|
+
: `viewer shell missing from this install (${home.viewerShell}) — reinstall diagc.`);
|
|
53
|
+
return 1;
|
|
54
|
+
}
|
|
55
|
+
const dirs = publishDirs(flags['--out'] ?? RELATIVE_PATHS.artifactsDir);
|
|
56
|
+
const failed = await compileSources(dirs, ctx);
|
|
57
|
+
// publish compiles every source whatever names it is given (they only scope which
|
|
58
|
+
// rendered pages come out below), so an update run here is always full-tree; like
|
|
59
|
+
// compile's, its prune waits until every source compiles.
|
|
60
|
+
if (flags['--update-includes'] === true && !failed)
|
|
61
|
+
await snapshots.prune();
|
|
62
|
+
const discovered = await discoverDiagrams(dirs.artifactsDir, dirs.srcDir);
|
|
63
|
+
const names = diagramNames(io, positionals, new Set(discovered.map((d) => d.name)));
|
|
64
|
+
if (names === undefined)
|
|
65
|
+
return 1;
|
|
66
|
+
const renderPng = await pngRenderer(io, flags['--no-images'] !== true);
|
|
67
|
+
const res = await publishDiagrams({
|
|
68
|
+
...dirs,
|
|
69
|
+
shellPath: home.viewerShell,
|
|
70
|
+
libraryDir: home.libraryDir,
|
|
71
|
+
images: renderPng !== undefined,
|
|
72
|
+
names,
|
|
73
|
+
...(renderPng !== undefined ? { renderPng } : {}),
|
|
74
|
+
...(flags['--link'] !== undefined ? { link: flags['--link'] } : {}),
|
|
75
|
+
warn: io.err,
|
|
76
|
+
});
|
|
77
|
+
io.out(`✓ ${res.pages.length} page(s) -> ${dirs.htmlDir}`);
|
|
78
|
+
if (res.images.length > 0)
|
|
79
|
+
io.out(`✓ ${res.images.length} image(s) -> ${dirs.staticDir}`);
|
|
80
|
+
io.out(`✓ gallery -> ${res.gallery}`);
|
|
81
|
+
return failed || res.skipped.length > 0 ? 1 : 0;
|
|
82
|
+
},
|
|
83
|
+
};
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { CliIo } from '../cli/io.js';
|
|
2
|
+
import type { PublishOptions } from '../publish/publish.js';
|
|
3
|
+
/** The sources compile and lint read when they are named none. */
|
|
4
|
+
export declare const SOURCES: string;
|
|
5
|
+
/** Why watch, studio and eject refuse --update-includes. */
|
|
6
|
+
export declare const LOCKED: {
|
|
7
|
+
'--update-includes': string;
|
|
8
|
+
};
|
|
9
|
+
/** The one message a repository with no diagrams gets, on stderr: `lint --json`'s
|
|
10
|
+
* stdout stays an array and the exit codes hold, so CI without diagrams passes. */
|
|
11
|
+
export declare function warnNoSources(io: CliIo, dir?: string): void;
|
|
12
|
+
/** `files...` as diagram names, read as eject reads one (`.diagrams/src/shop.diagram.json`
|
|
13
|
+
* is `shop`). A name that matches nothing in `known` is an error on stderr, and the
|
|
14
|
+
* result is then undefined: an empty selection would look like nothing to do. */
|
|
15
|
+
export declare function diagramNames(io: CliIo, files: readonly string[], known: ReadonlySet<string>): string[] | undefined;
|
|
16
|
+
/** The PNG renderer, when images are wanted and a Chrome is found. Without a Chrome it
|
|
17
|
+
* says so on stderr, and the pages go out as HTML only. Playwright loads only when a
|
|
18
|
+
* picture is wanted. */
|
|
19
|
+
export declare function pngRenderer(io: CliIo, images: boolean): Promise<NonNullable<PublishOptions['renderPng']> | undefined>;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { diagramName } from '../names.js';
|
|
2
|
+
import { RELATIVE_PATHS } from '../paths.js';
|
|
3
|
+
/** The sources compile and lint read when they are named none. */
|
|
4
|
+
export const SOURCES = `${RELATIVE_PATHS.srcDir}/**/*.diagram.{ts,json}`;
|
|
5
|
+
/** Why watch, studio and eject refuse --update-includes. */
|
|
6
|
+
export const LOCKED = { '--update-includes': 'it always resolves includes locked' };
|
|
7
|
+
/** The one message a repository with no diagrams gets, on stderr: `lint --json`'s
|
|
8
|
+
* stdout stays an array and the exit codes hold, so CI without diagrams passes. */
|
|
9
|
+
export function warnNoSources(io, dir = RELATIVE_PATHS.srcDir) {
|
|
10
|
+
io.err(`No diagrams under ${dir} — run 'diagc init' to create one.`);
|
|
11
|
+
}
|
|
12
|
+
/** `files...` as diagram names, read as eject reads one (`.diagrams/src/shop.diagram.json`
|
|
13
|
+
* is `shop`). A name that matches nothing in `known` is an error on stderr, and the
|
|
14
|
+
* result is then undefined: an empty selection would look like nothing to do. */
|
|
15
|
+
export function diagramNames(io, files, known) {
|
|
16
|
+
const names = files.map(diagramName);
|
|
17
|
+
const unknown = names.filter((n) => !known.has(n));
|
|
18
|
+
for (const n of unknown)
|
|
19
|
+
io.err(`diagc: no diagram '${n}'`);
|
|
20
|
+
return unknown.length === 0 ? names : undefined;
|
|
21
|
+
}
|
|
22
|
+
/** The PNG renderer, when images are wanted and a Chrome is found. Without a Chrome it
|
|
23
|
+
* says so on stderr, and the pages go out as HTML only. Playwright loads only when a
|
|
24
|
+
* picture is wanted. */
|
|
25
|
+
export async function pngRenderer(io, images) {
|
|
26
|
+
if (!images)
|
|
27
|
+
return undefined;
|
|
28
|
+
const snapshot = await import('../publish/snapshot.js');
|
|
29
|
+
if (snapshot.findChrome() === undefined) {
|
|
30
|
+
io.err('No Chrome found — writing HTML only; install Chrome / set CHROME_PATH, or use --no-images.');
|
|
31
|
+
return undefined;
|
|
32
|
+
}
|
|
33
|
+
return snapshot.renderPng;
|
|
34
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { runStudio } from '../studio.js';
|
|
2
|
+
import { LOCKED } from './shared.js';
|
|
3
|
+
/** `diagc studio`: the studio against the current directory, until it is stopped. */
|
|
4
|
+
export const studio = {
|
|
5
|
+
flags: [],
|
|
6
|
+
positionals: { max: 0, what: 'no arguments' },
|
|
7
|
+
whyNot: LOCKED,
|
|
8
|
+
async run(_args, { home }) {
|
|
9
|
+
// Studio's own compile-watch loop always resolves includes locked (see
|
|
10
|
+
// studio.ts) — same reasoning as watch's.
|
|
11
|
+
await runStudio(home, process.cwd());
|
|
12
|
+
return 0;
|
|
13
|
+
},
|
|
14
|
+
};
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { Command, CommandArgs, Context } from '../cli/command.js';
|
|
2
|
+
/** Watch's start: the check for sources, the watcher, and the line that says it is
|
|
3
|
+
* watching. Returns the watcher, which a test closes. */
|
|
4
|
+
export declare function startWatching({ positionals, flags }: CommandArgs<'--out'>, { io, home }: Context): Promise<{
|
|
5
|
+
close(): Promise<void>;
|
|
6
|
+
}>;
|
|
7
|
+
/** `diagc watch [dir]`: recompile on every change until the process is stopped. */
|
|
8
|
+
export declare const watch: Command<'--out'>;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { existsSync, statSync } from 'node:fs';
|
|
2
|
+
import fg from 'fast-glob';
|
|
3
|
+
import { RELATIVE_PATHS } from '../paths.js';
|
|
4
|
+
import { lockedResolverFor } from '../snapshots.js';
|
|
5
|
+
import { formatCompileEvent, startWatch } from '../watch.js';
|
|
6
|
+
import { LOCKED, warnNoSources } from './shared.js';
|
|
7
|
+
/** Watch's start: the check for sources, the watcher, and the line that says it is
|
|
8
|
+
* watching. Returns the watcher, which a test closes. */
|
|
9
|
+
export async function startWatching({ positionals, flags }, { io, home }) {
|
|
10
|
+
const dir = positionals[0] ?? RELATIVE_PATHS.srcDir;
|
|
11
|
+
// A directory that does not exist holds no diagrams either; a file is left alone.
|
|
12
|
+
if (!existsSync(dir) ||
|
|
13
|
+
(statSync(dir).isDirectory() && (await fg('**/*.diagram.{ts,json}', { cwd: dir })).length === 0))
|
|
14
|
+
warnNoSources(io, dir);
|
|
15
|
+
// Always locked, and --update-includes is refused here: watch is a long-running
|
|
16
|
+
// live loop with no point at which "refetch and rewrite the lock" makes
|
|
17
|
+
// sense, so it resolves through a locked resolver of its own rather than the run's
|
|
18
|
+
// session (as the studio's watch loop does).
|
|
19
|
+
const watcher = startWatch(dir, flags['--out'] ?? RELATIVE_PATHS.artifactsDir, {
|
|
20
|
+
coreEntry: home.coreEntry,
|
|
21
|
+
resolver: lockedResolverFor(RELATIVE_PATHS.srcDir),
|
|
22
|
+
onEvent: (e) => {
|
|
23
|
+
// Success goes to stdout, failure to stderr, so the streams stay parsed
|
|
24
|
+
// separately by anyone piping them.
|
|
25
|
+
if (e.ok)
|
|
26
|
+
io.out(formatCompileEvent(e));
|
|
27
|
+
else
|
|
28
|
+
io.err(formatCompileEvent(e));
|
|
29
|
+
},
|
|
30
|
+
});
|
|
31
|
+
io.out(`Watching ${dir} for *.diagram.{ts,json} changes...`);
|
|
32
|
+
return watcher;
|
|
33
|
+
}
|
|
34
|
+
/** `diagc watch [dir]`: recompile on every change until the process is stopped. */
|
|
35
|
+
export const watch = {
|
|
36
|
+
flags: ['--out'],
|
|
37
|
+
positionals: { max: 1, what: 'one directory' },
|
|
38
|
+
whyNot: LOCKED,
|
|
39
|
+
async run(args, ctx) {
|
|
40
|
+
await startWatching(args, ctx);
|
|
41
|
+
// No exit code ever comes: the run is never over on its own account, and the
|
|
42
|
+
// watcher's handles keep the process alive until it is stopped.
|
|
43
|
+
return new Promise(() => { });
|
|
44
|
+
},
|
|
45
|
+
};
|
package/dist/compile.d.ts
CHANGED
|
@@ -35,8 +35,11 @@ export interface LoadOptions {
|
|
|
35
35
|
coreEntry?: string;
|
|
36
36
|
resolver?: IncludeResolver;
|
|
37
37
|
/** what composing the includes warns about, one warning at a time; by default each
|
|
38
|
-
*
|
|
38
|
+
* goes to `warn` as `<file>: <warning>` */
|
|
39
39
|
onWarning?: (warning: string) => void;
|
|
40
|
+
/** where a warning goes, one line each: `console.warn` by default, so a caller with
|
|
41
|
+
* streams of its own (the CLI's) passes its stderr */
|
|
42
|
+
warn?: (line: string) => void;
|
|
40
43
|
}
|
|
41
44
|
/**
|
|
42
45
|
* Read a source, validate it, expand its includes and validate the result: the
|
package/dist/compile.js
CHANGED
|
@@ -4,7 +4,7 @@ import path from 'node:path';
|
|
|
4
4
|
import { createJiti } from 'jiti';
|
|
5
5
|
import { composeIncludes, DiagramValidationError, diagramWarnings, errMessage, validate, } from '@diagc/core/internal';
|
|
6
6
|
import { resolveInclude } from './includes.js';
|
|
7
|
-
import {
|
|
7
|
+
import { lockedResolverFor } from './snapshots.js';
|
|
8
8
|
/**
|
|
9
9
|
* Shape guard: with `{ default: true }` jiti returns the module NAMESPACE when
|
|
10
10
|
* there is no default export, so a default-less file would otherwise be written
|
|
@@ -131,22 +131,17 @@ export async function loadModel(file, opts) {
|
|
|
131
131
|
if (sourceIssues.length > 0)
|
|
132
132
|
throw new DiagramValidationError(sourceIssues);
|
|
133
133
|
if (model.nodes.some((n) => n.include !== undefined)) {
|
|
134
|
-
// Default to
|
|
135
|
-
//
|
|
136
|
-
//
|
|
137
|
-
//
|
|
138
|
-
|
|
139
|
-
// resolver remain the fallback.
|
|
140
|
-
const resolver = opts?.resolver ??
|
|
141
|
-
(opts?.rootDir !== undefined
|
|
142
|
-
? snapshotSession(resolveInclude, path.dirname(path.resolve(opts.rootDir)), 'locked').resolver
|
|
143
|
-
: resolveInclude);
|
|
134
|
+
// Default to the locked resolver: a call site that forgets to pass `resolver`
|
|
135
|
+
// must fail on an unsnapshotted remote include, not silently reintroduce live
|
|
136
|
+
// fetching. Local includes pass through either way; only without a rootDir to
|
|
137
|
+
// anchor the vendor dir does the raw resolver remain the fallback.
|
|
138
|
+
const resolver = opts?.resolver ?? (opts?.rootDir !== undefined ? lockedResolverFor(path.resolve(opts.rootDir)) : resolveInclude);
|
|
144
139
|
const { model: composed, warnings } = await composeIncludes(model, path.resolve(file), resolver);
|
|
145
140
|
for (const w of warnings) {
|
|
146
141
|
if (opts?.onWarning !== undefined)
|
|
147
142
|
opts.onWarning(w);
|
|
148
143
|
else
|
|
149
|
-
console.warn(`${file}: ${w}`);
|
|
144
|
+
(opts?.warn ?? console.warn)(`${file}: ${w}`);
|
|
150
145
|
}
|
|
151
146
|
model = composed;
|
|
152
147
|
const issues = validate(model);
|
|
@@ -161,7 +156,7 @@ export async function compileFile(file, outDir, opts) {
|
|
|
161
156
|
// type): say so, and compile anyway — the studio saves the same model without
|
|
162
157
|
// complaint. `diagc lint` is the strict reading of the same list.
|
|
163
158
|
for (const w of diagramWarnings(model))
|
|
164
|
-
console.warn(`${file}: ${w.message}`);
|
|
159
|
+
(opts?.warn ?? console.warn)(`${file}: ${w.message}`);
|
|
165
160
|
const base = path.basename(file).replace(/\.diagram\.(ts|json)$/, '');
|
|
166
161
|
const artifactDir = path.join(outDir, relativeSubdir(file, opts?.rootDir));
|
|
167
162
|
await mkdir(artifactDir, { recursive: true });
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { type ModelDiff } from '@diagc/core/internal';
|
|
2
|
+
import type { DiagramSet, DiagramVersion } from './load.js';
|
|
3
|
+
export type DiagramDiffStatus = DiagramDiff['status'];
|
|
4
|
+
/** A diagram only the later side has. Its `diff` is against an empty model, as a
|
|
5
|
+
* removed diagram's is, so the marks cover the whole picture the same way. */
|
|
6
|
+
export interface AddedDiagram {
|
|
7
|
+
name: string;
|
|
8
|
+
status: 'added';
|
|
9
|
+
after: DiagramVersion;
|
|
10
|
+
diff: ModelDiff;
|
|
11
|
+
}
|
|
12
|
+
export interface RemovedDiagram {
|
|
13
|
+
name: string;
|
|
14
|
+
status: 'removed';
|
|
15
|
+
before: DiagramVersion;
|
|
16
|
+
diff: ModelDiff;
|
|
17
|
+
}
|
|
18
|
+
/** A diagram both sides have, changed or not. */
|
|
19
|
+
export interface ComparedDiagram {
|
|
20
|
+
name: string;
|
|
21
|
+
status: 'changed' | 'unchanged';
|
|
22
|
+
before: DiagramVersion;
|
|
23
|
+
after: DiagramVersion;
|
|
24
|
+
diff: ModelDiff;
|
|
25
|
+
}
|
|
26
|
+
/** A diagram whose source did not compile on a side: there is nothing to compare, only
|
|
27
|
+
* why. */
|
|
28
|
+
export interface UncomparedDiagram {
|
|
29
|
+
name: string;
|
|
30
|
+
status: 'error';
|
|
31
|
+
error: string;
|
|
32
|
+
}
|
|
33
|
+
/** One diagram across the two sides; its status says what it carries. */
|
|
34
|
+
export type DiagramDiff = AddedDiagram | RemovedDiagram | ComparedDiagram | UncomparedDiagram;
|
|
35
|
+
/** Pair the two sets by name. `names` narrows the result to those diagrams. */
|
|
36
|
+
export declare function compareDiagramSets(before: DiagramSet, after: DiagramSet, names?: readonly string[]): DiagramDiff[];
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { diffModels, isEmptyDiff } from '@diagc/core/internal';
|
|
2
|
+
const EMPTY = {
|
|
3
|
+
version: 1,
|
|
4
|
+
id: '',
|
|
5
|
+
name: '',
|
|
6
|
+
nodes: [],
|
|
7
|
+
containment: [],
|
|
8
|
+
relations: [],
|
|
9
|
+
layers: [],
|
|
10
|
+
planes: [],
|
|
11
|
+
};
|
|
12
|
+
/** Pair the two sets by name. `names` narrows the result to those diagrams. */
|
|
13
|
+
export function compareDiagramSets(before, after, names = []) {
|
|
14
|
+
const all = new Set([
|
|
15
|
+
...before.versions.keys(),
|
|
16
|
+
...before.errors.keys(),
|
|
17
|
+
...after.versions.keys(),
|
|
18
|
+
...after.errors.keys(),
|
|
19
|
+
]);
|
|
20
|
+
const wanted = names.length > 0 ? names.filter((n) => all.has(n)) : [...all].sort();
|
|
21
|
+
return wanted.map((name) => {
|
|
22
|
+
const b = before.versions.get(name);
|
|
23
|
+
const a = after.versions.get(name);
|
|
24
|
+
const err = after.errors.get(name) ?? before.errors.get(name);
|
|
25
|
+
if (err !== undefined) {
|
|
26
|
+
const at = after.errors.has(name) ? after.label : before.label;
|
|
27
|
+
return { name, status: 'error', error: `does not compile at ${at}: ${err}` };
|
|
28
|
+
}
|
|
29
|
+
if (b === undefined)
|
|
30
|
+
return { name, status: 'added', after: a, diff: diffModels(EMPTY, a.model) };
|
|
31
|
+
if (a === undefined)
|
|
32
|
+
return { name, status: 'removed', before: b, diff: diffModels(b.model, EMPTY) };
|
|
33
|
+
const diff = diffModels(b.model, a.model);
|
|
34
|
+
return { name, status: isEmptyDiff(diff) ? 'unchanged' : 'changed', before: b, after: a, diff };
|
|
35
|
+
});
|
|
36
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { DiagramDiff } from './compare.js';
|
|
2
|
+
/** The change list for one diagram, one line each, `+`/`-`/`~` first. */
|
|
3
|
+
export declare function describeDiff(d: DiagramDiff): string[];
|
|
4
|
+
/** `diff --json`'s text: each diagram's status, with its changes or why it was not
|
|
5
|
+
* compared. The versions stay out: they are whole models, what the pictures are drawn
|
|
6
|
+
* from, not the change. */
|
|
7
|
+
export declare function formatDiffJson(diffs: readonly DiagramDiff[], from: string, to: string): string;
|
|
8
|
+
export declare function formatDiffSummary(diffs: readonly DiagramDiff[], from: string, to: string): string;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
function nameIn(m, id) {
|
|
2
|
+
const n = m.nodes.find((x) => x.id === id);
|
|
3
|
+
return n === undefined || n.name === '' ? id : n.name;
|
|
4
|
+
}
|
|
5
|
+
/** The change list for one diagram, one line each, `+`/`-`/`~` first. */
|
|
6
|
+
export function describeDiff(d) {
|
|
7
|
+
if (d.status === 'error')
|
|
8
|
+
return [];
|
|
9
|
+
if (d.status === 'added')
|
|
10
|
+
return [
|
|
11
|
+
`+ new diagram: ${d.after.model.name} (${d.diff.nodes.added.length} nodes, ${d.diff.relations.added.length} relations)`,
|
|
12
|
+
];
|
|
13
|
+
if (d.status === 'removed')
|
|
14
|
+
return [`- diagram removed: ${d.before.model.name}`];
|
|
15
|
+
const before = d.before.model;
|
|
16
|
+
const after = d.after.model;
|
|
17
|
+
const rel = (m, r) => `${nameIn(m, r.from)} -> ${nameIn(m, r.to)} (${r.kind}${r.label !== undefined && r.label !== '' ? `: ${r.label}` : ''})`;
|
|
18
|
+
const x = d.diff;
|
|
19
|
+
return [
|
|
20
|
+
...x.nodes.added.map((n) => `+ ${n.name !== '' ? n.name : n.id}${n.type !== undefined ? ` [${n.type}]` : ''}`),
|
|
21
|
+
...x.nodes.removed.map((n) => `- ${n.name !== '' ? n.name : n.id}${n.type !== undefined ? ` [${n.type}]` : ''}`),
|
|
22
|
+
...x.nodes.changed.map((n) => {
|
|
23
|
+
// A rename reads better as the two names than as the word "name".
|
|
24
|
+
const was = nameIn(before, n.id);
|
|
25
|
+
const now = nameIn(after, n.id);
|
|
26
|
+
const rest = n.fields.filter((f) => f !== 'name');
|
|
27
|
+
const head = n.fields.includes('name') ? `${was} -> ${now} (renamed)` : now;
|
|
28
|
+
return `~ ${head}${rest.length > 0 ? `: ${rest.join(', ')}` : ''}`;
|
|
29
|
+
}),
|
|
30
|
+
...x.relations.added.map((r) => `+ ${rel(after, r)}`),
|
|
31
|
+
...x.relations.removed.map((r) => `- ${rel(before, r)}`),
|
|
32
|
+
...x.relations.changed.map((r) => {
|
|
33
|
+
const now = after.relations.find((y) => y.id === r.after);
|
|
34
|
+
return `~ ${now !== undefined ? rel(after, now) : r.after}: ${r.fields.join(', ')}`;
|
|
35
|
+
}),
|
|
36
|
+
...x.layers.added.map((id) => `+ layer ${id}`),
|
|
37
|
+
...x.layers.removed.map((id) => `- layer ${id}`),
|
|
38
|
+
...x.planes.added.map((id) => `+ plane ${id}`),
|
|
39
|
+
...x.planes.removed.map((id) => `- plane ${id}`),
|
|
40
|
+
];
|
|
41
|
+
}
|
|
42
|
+
/** `diff --json`'s text: each diagram's status, with its changes or why it was not
|
|
43
|
+
* compared. The versions stay out: they are whole models, what the pictures are drawn
|
|
44
|
+
* from, not the change. */
|
|
45
|
+
export function formatDiffJson(diffs, from, to) {
|
|
46
|
+
// Built key by key, so the printed order is the one written here, whatever order the
|
|
47
|
+
// diff's own fields are in.
|
|
48
|
+
const diagrams = diffs.map((d) => d.status === 'error'
|
|
49
|
+
? { name: d.name, status: d.status, error: d.error }
|
|
50
|
+
: { name: d.name, status: d.status, diff: d.diff });
|
|
51
|
+
return JSON.stringify({ from, to, diagrams }, null, 2);
|
|
52
|
+
}
|
|
53
|
+
export function formatDiffSummary(diffs, from, to) {
|
|
54
|
+
const lines = [`diagc diff ${from} -> ${to}`];
|
|
55
|
+
for (const d of diffs) {
|
|
56
|
+
if (d.status === 'unchanged')
|
|
57
|
+
continue;
|
|
58
|
+
if (d.status === 'error') {
|
|
59
|
+
lines.push(`! ${d.name}: ${d.error}`);
|
|
60
|
+
continue;
|
|
61
|
+
}
|
|
62
|
+
lines.push(`${d.name}:`);
|
|
63
|
+
for (const l of describeDiff(d))
|
|
64
|
+
lines.push(` ${l}`);
|
|
65
|
+
}
|
|
66
|
+
const changed = diffs.filter((d) => d.status !== 'unchanged' && d.status !== 'error').length;
|
|
67
|
+
const same = diffs.filter((d) => d.status === 'unchanged').length;
|
|
68
|
+
lines.push(changed === 0 ? `no diagram changed (${same} compared)` : `${changed} diagram(s) changed, ${same} unchanged`);
|
|
69
|
+
return lines.join('\n');
|
|
70
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { loadDiagramSet, type DiagramSet, type DiagramVersion } from './load.js';
|
|
2
|
+
export { compareDiagramSets, type DiagramDiff, type DiagramDiffStatus } from './compare.js';
|
|
3
|
+
export { describeDiff, formatDiffJson, formatDiffSummary } from './describe.js';
|
|
4
|
+
export { writeDiffPages, type DiffPagesOptions, type DiffPagesResult } from './pages.js';
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
// `diagc diff`: load each side's diagrams, compare them by name, describe the changes,
|
|
2
|
+
// and write the pages, the side-by-side overview and the summary.
|
|
3
|
+
export { loadDiagramSet } from './load.js';
|
|
4
|
+
export { compareDiagramSets } from './compare.js';
|
|
5
|
+
export { describeDiff, formatDiffJson, formatDiffSummary } from './describe.js';
|
|
6
|
+
export { writeDiffPages } from './pages.js';
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { type DiagramModel, type Drawings, type LayoutOverlay } 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
|
+
/** sidecars left out of the pictures because they could not be read, each named */
|
|
19
|
+
warnings: string[];
|
|
20
|
+
}
|
|
21
|
+
/** Compile every source under `diagramsDir/src` in memory — nothing is written. */
|
|
22
|
+
export declare function loadDiagramSet(label: string, diagramsDir: string, coreEntry?: string): Promise<DiagramSet>;
|