@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.
Files changed (81) hide show
  1. package/dist/api/assets.d.ts +8 -0
  2. package/dist/api/assets.js +54 -0
  3. package/dist/api/diagrams.d.ts +27 -0
  4. package/dist/api/diagrams.js +269 -0
  5. package/dist/api/files.d.ts +7 -0
  6. package/dist/api/files.js +30 -0
  7. package/dist/api/handlers.d.ts +7 -62
  8. package/dist/api/handlers.js +10 -488
  9. package/dist/api/library.d.ts +5 -0
  10. package/dist/api/library.js +88 -0
  11. package/dist/api/result.d.ts +8 -0
  12. package/dist/api/result.js +5 -0
  13. package/dist/api/sidecars.d.ts +13 -0
  14. package/dist/api/sidecars.js +78 -0
  15. package/dist/cli/command.d.ts +26 -0
  16. package/dist/cli/command.js +1 -0
  17. package/dist/cli/io.d.ts +13 -0
  18. package/dist/cli/io.js +7 -0
  19. package/dist/cli/parse.d.ts +51 -0
  20. package/dist/cli/parse.js +109 -0
  21. package/dist/cli/run.d.ts +10 -0
  22. package/dist/cli/run.js +67 -0
  23. package/dist/cli.d.ts +1 -52
  24. package/dist/cli.js +5 -475
  25. package/dist/commands/compile.d.ts +3 -0
  26. package/dist/commands/compile.js +38 -0
  27. package/dist/commands/diff.d.ts +10 -0
  28. package/dist/commands/diff.js +96 -0
  29. package/dist/commands/eject.d.ts +3 -0
  30. package/dist/commands/eject.js +32 -0
  31. package/dist/commands/guide.d.ts +3 -0
  32. package/dist/commands/guide.js +13 -0
  33. package/dist/commands/init.d.ts +3 -0
  34. package/dist/commands/init.js +23 -0
  35. package/dist/commands/lint.d.ts +3 -0
  36. package/dist/commands/lint.js +27 -0
  37. package/dist/commands/publish.d.ts +11 -0
  38. package/dist/commands/publish.js +83 -0
  39. package/dist/commands/shared.d.ts +19 -0
  40. package/dist/commands/shared.js +34 -0
  41. package/dist/commands/studio.d.ts +3 -0
  42. package/dist/commands/studio.js +14 -0
  43. package/dist/commands/watch.d.ts +8 -0
  44. package/dist/commands/watch.js +45 -0
  45. package/dist/compile.d.ts +4 -1
  46. package/dist/compile.js +8 -13
  47. package/dist/diff/compare.d.ts +36 -0
  48. package/dist/diff/compare.js +36 -0
  49. package/dist/diff/describe.d.ts +8 -0
  50. package/dist/diff/describe.js +70 -0
  51. package/dist/diff/index.d.ts +4 -0
  52. package/dist/diff/index.js +6 -0
  53. package/dist/diff/load.d.ts +22 -0
  54. package/dist/diff/load.js +62 -0
  55. package/dist/diff/overview.d.ts +17 -0
  56. package/dist/diff/overview.js +86 -0
  57. package/dist/diff/pages.d.ts +27 -0
  58. package/dist/diff/pages.js +55 -0
  59. package/dist/diff/summary.d.ts +18 -0
  60. package/dist/diff/summary.js +26 -0
  61. package/dist/eject.js +2 -6
  62. package/dist/git-ref.js +21 -3
  63. package/dist/glob.d.ts +5 -0
  64. package/dist/glob.js +7 -0
  65. package/dist/init.d.ts +0 -3
  66. package/dist/init.js +14 -15
  67. package/dist/names.d.ts +3 -0
  68. package/dist/names.js +8 -0
  69. package/dist/paths.d.ts +29 -0
  70. package/dist/paths.js +25 -0
  71. package/dist/publish/discover.js +2 -1
  72. package/dist/publish/publish.d.ts +6 -4
  73. package/dist/publish/publish.js +11 -7
  74. package/dist/snapshots.d.ts +11 -0
  75. package/dist/snapshots.js +20 -3
  76. package/dist/studio.js +8 -8
  77. package/package.json +2 -2
  78. package/dist/command-args.d.ts +0 -9
  79. package/dist/command-args.js +0 -56
  80. package/dist/diff.d.ts +0 -61
  81. 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,3 @@
1
+ import type { Command } from '../cli/command.js';
2
+ /** `diagc guide [topic]`: how to write a diagram, as Markdown on stdout. */
3
+ export declare const guide: Command<never>;
@@ -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,3 @@
1
+ import type { Command } from '../cli/command.js';
2
+ /** `diagc init [name]`: set a repository up for diagc. */
3
+ export declare const init: Command<'--type' | '--agents'>;
@@ -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,3 @@
1
+ import type { Command } from '../cli/command.js';
2
+ /** `diagc lint [files...] [--json]`: every finding, and exit 1 on any. */
3
+ export declare const lint: Command<'--json'>;
@@ -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,3 @@
1
+ import type { Command } from '../cli/command.js';
2
+ /** `diagc studio`: the studio against the current directory, until it is stopped. */
3
+ export declare const studio: Command<never>;
@@ -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
- * is printed on stderr as `<file>: <warning>` */
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 { snapshotSession } from './snapshots.js';
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 a locked snapshot resolver rooted at rootDir's parent (the
135
- // .diagrams root, same derivation as eject.ts): a call site that forgets
136
- // to pass `resolver` must fail on an unsnapshotted remote include, not
137
- // silently reintroduce live fetching. Local includes pass through either
138
- // way; only without a rootDir to anchor the vendor dir does the raw
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>;