@diagc/cli 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/README.md +1 -1
  2. package/assets/guide/compose.md +84 -0
  3. package/assets/guide/index.md +9 -1
  4. package/assets/skill/SKILL.md +2 -1
  5. package/assets/studio/assets/{index-DzVDK5uD.css → index-CAVbaTgv.css} +1 -1
  6. package/assets/studio/assets/index-Cgkqoymm.js +112 -0
  7. package/assets/studio/index.html +2 -2
  8. package/assets/viewer/shared/caveat-cyrillic-500-normal.woff +0 -0
  9. package/assets/viewer/shared/caveat-cyrillic-500-normal.woff2 +0 -0
  10. package/assets/viewer/shared/caveat-cyrillic-700-normal.woff +0 -0
  11. package/assets/viewer/shared/caveat-cyrillic-700-normal.woff2 +0 -0
  12. package/assets/viewer/shared/caveat-cyrillic-ext-500-normal.woff +0 -0
  13. package/assets/viewer/shared/caveat-cyrillic-ext-500-normal.woff2 +0 -0
  14. package/assets/viewer/shared/caveat-cyrillic-ext-700-normal.woff +0 -0
  15. package/assets/viewer/shared/caveat-cyrillic-ext-700-normal.woff2 +0 -0
  16. package/assets/viewer/shared/caveat-latin-500-normal.woff +0 -0
  17. package/assets/viewer/shared/caveat-latin-500-normal.woff2 +0 -0
  18. package/assets/viewer/shared/caveat-latin-700-normal.woff +0 -0
  19. package/assets/viewer/shared/caveat-latin-700-normal.woff2 +0 -0
  20. package/assets/viewer/shared/caveat-latin-ext-500-normal.woff +0 -0
  21. package/assets/viewer/shared/caveat-latin-ext-500-normal.woff2 +0 -0
  22. package/assets/viewer/shared/caveat-latin-ext-700-normal.woff +0 -0
  23. package/assets/viewer/shared/caveat-latin-ext-700-normal.woff2 +0 -0
  24. package/assets/viewer/shared/chakra-petch-latin-500-normal.woff2 +0 -0
  25. package/assets/viewer/shared/chakra-petch-latin-600-normal.woff2 +0 -0
  26. package/assets/viewer/shared/inter-latin-400-normal.woff2 +0 -0
  27. package/assets/viewer/shared/inter-latin-600-normal.woff2 +0 -0
  28. package/assets/viewer/shared/jetbrains-mono-latin-400-normal.woff2 +0 -0
  29. package/assets/viewer/shared/jetbrains-mono-latin-600-normal.woff2 +0 -0
  30. package/assets/viewer/shared/kalam-devanagari-400-normal.woff +0 -0
  31. package/assets/viewer/shared/kalam-devanagari-400-normal.woff2 +0 -0
  32. package/assets/viewer/shared/kalam-devanagari-700-normal.woff +0 -0
  33. package/assets/viewer/shared/kalam-devanagari-700-normal.woff2 +0 -0
  34. package/assets/viewer/shared/kalam-latin-400-normal.woff +0 -0
  35. package/assets/viewer/shared/kalam-latin-400-normal.woff2 +0 -0
  36. package/assets/viewer/shared/kalam-latin-700-normal.woff +0 -0
  37. package/assets/viewer/shared/kalam-latin-700-normal.woff2 +0 -0
  38. package/assets/viewer/shared/kalam-latin-ext-400-normal.woff +0 -0
  39. package/assets/viewer/shared/kalam-latin-ext-400-normal.woff2 +0 -0
  40. package/assets/viewer/shared/kalam-latin-ext-700-normal.woff +0 -0
  41. package/assets/viewer/shared/kalam-latin-ext-700-normal.woff2 +0 -0
  42. package/assets/viewer/shared/viewer.css +2 -0
  43. package/assets/viewer/shared/viewer.js +46 -0
  44. package/dist/api/diagrams.d.ts +20 -0
  45. package/dist/api/diagrams.js +69 -3
  46. package/dist/api/handlers.d.ts +1 -1
  47. package/dist/api/handlers.js +1 -1
  48. package/dist/api/routes.js +13 -0
  49. package/dist/cli/parse.d.ts +1 -0
  50. package/dist/cli/parse.js +1 -0
  51. package/dist/cli.js +2 -0
  52. package/dist/commands/compile.d.ts +1 -1
  53. package/dist/commands/compile.js +5 -6
  54. package/dist/commands/lint.js +4 -5
  55. package/dist/commands/publish.d.ts +1 -1
  56. package/dist/commands/publish.js +15 -7
  57. package/dist/commands/shared.d.ts +9 -0
  58. package/dist/commands/shared.js +30 -1
  59. package/dist/compile.d.ts +11 -1
  60. package/dist/compile.js +25 -6
  61. package/dist/guide.js +22 -10
  62. package/dist/home.d.ts +5 -1
  63. package/dist/home.js +2 -0
  64. package/dist/init.d.ts +1 -1
  65. package/dist/init.js +1 -1
  66. package/dist/lint.js +2 -1
  67. package/dist/loadHints.d.ts +8 -0
  68. package/dist/loadHints.js +36 -0
  69. package/dist/names.js +1 -1
  70. package/dist/publish/html.d.ts +13 -0
  71. package/dist/publish/html.js +54 -2
  72. package/dist/publish/publish.d.ts +10 -0
  73. package/dist/publish/publish.js +45 -23
  74. package/dist/publish/snapshot.d.ts +21 -2
  75. package/dist/publish/snapshot.js +95 -18
  76. package/dist/watch.js +23 -7
  77. package/package.json +2 -2
  78. package/assets/studio/assets/index-CB6jjAka.js +0 -112
@@ -7,6 +7,10 @@ export interface DiagramEntry {
7
7
  message: string;
8
8
  }[];
9
9
  editable: boolean;
10
+ /** the `.diagram.ts` a compiled diagram comes from, relative to the sources dir
11
+ * (`team/arch.diagram.ts`), when it is there: what the studio names on its
12
+ * read-only chip and opens on request */
13
+ source?: string;
10
14
  }
11
15
  /** Render-ready models for the studio boot: JSON sources (editable) served from
12
16
  * `diagramsDir`, compiled TS artifacts from `artifactsDir`. A source shadows its
@@ -17,6 +21,13 @@ export declare function listDiagramModels(diagramsDir: string, artifactsDir: str
17
21
  * spelling, is what keeps it inside the two directories: a compiled diagram's name
18
22
  * comes from its `.diagram.ts` file and need not pass `isSafeName`. */
19
23
  export declare function diagramAsShown(diagramsDir: string, artifactsDir: string, name: string): Promise<DiagramEntry | undefined>;
24
+ /** The TypeScript a compiled diagram comes from, as plain text: what the studio's
25
+ * read-only chip opens. Only `.diagram.ts` is served — a JSON source is the
26
+ * studio's own, read through `readDiagram`. */
27
+ export declare function readDiagramSource(diagramsDir: string, name: string): Promise<HandlerResult & {
28
+ bytes?: Buffer;
29
+ contentType?: string;
30
+ }>;
20
31
  /** the JSON source (+ sibling layout and drawings) of a designer-owned diagram — the studio
21
32
  * reads these directly so it never depends on a compile watcher for its own files */
22
33
  export declare function readDiagram(diagramsDir: string, name: string): Promise<HandlerResult>;
@@ -27,6 +38,15 @@ export declare function saveDiagram(diagramsDir: string, name: string, payload:
27
38
  /** Move a designer-owned diagram (and its sibling layout, if any) to a new name,
28
39
  * rewriting the model's id to match so the file stays self-consistent. */
29
40
  export declare function renameDiagram(diagramsDir: string, from: string, to: string): Promise<HandlerResult>;
41
+ /**
42
+ * Remove a studio-owned diagram: its JSON source, its layout and drawings sidecars,
43
+ * and its compiled artifact — the watcher's copy, which would otherwise list the
44
+ * diagram again, read-only, the next time the studio starts without a watcher
45
+ * having seen the deletion. A diagram with a `.diagram.ts` is TypeScript's: the
46
+ * studio never offers to delete it, and the route refuses too (409). Published
47
+ * pages and PNGs are left where they are; `diagc publish` regenerates them.
48
+ */
49
+ export declare function deleteDiagram(diagramsDir: string, artifactsDir: string, name: string): Promise<HandlerResult>;
30
50
  /** Promote a JSON-owned diagram to a generated `.diagram.ts`. See `ejectDiagram`
31
51
  * for the round-trip guarantee; this just maps its failure codes to statuses. */
32
52
  export declare function ejectDiagramSource(diagramsDir: string, artifactsDir: string, name: string): Promise<HandlerResult>;
@@ -1,4 +1,4 @@
1
- import { access, mkdir, readFile, rename, unlink } from 'node:fs/promises';
1
+ import { access, mkdir, readFile, rename, rm, unlink } from 'node:fs/promises';
2
2
  import path from 'node:path';
3
3
  import { composeIncludes, errMessage, validate } from '@diagc/core/internal';
4
4
  import { writeFileAtomic } from '../atomic-write.js';
@@ -42,9 +42,12 @@ async function loadEntry(diagramsDir, artifactsDir, name, isSource) {
42
42
  const issues = [];
43
43
  if (isSource && !editable) {
44
44
  issues.push({
45
- message: `'${name}' is read-only here: the studio saves names of lowercase letters, digits, '-' and '/', none ending in /rename, /eject or /composed. Rename the file to edit it.`,
45
+ message: `'${name}' is read-only here: the studio saves names of lowercase letters, digits, '-' and '/', none ending in /rename, /eject, /composed or /source. Rename the file to edit it.`,
46
46
  });
47
47
  }
48
+ // A compiled diagram names the TypeScript it comes from, when it is beside the
49
+ // sources: an artifact with no source here (a build output copied in) names none.
50
+ const source = isSource ? undefined : await tsSourceOf(diagramsDir, name);
48
51
  try {
49
52
  model = JSON.parse(await readFile(file, 'utf8'));
50
53
  }
@@ -53,7 +56,32 @@ async function loadEntry(diagramsDir, artifactsDir, name, isSource) {
53
56
  }
54
57
  if (isSource && hasIncludes(model))
55
58
  model = await composedForList(model, file, diagramsDir, issues);
56
- return { name, model, issues, editable };
59
+ return { name, model, issues, editable, ...(source !== undefined ? { source } : {}) };
60
+ }
61
+ /** `<name>.diagram.ts` relative to `diagramsDir` when that file exists, else undefined. */
62
+ async function tsSourceOf(diagramsDir, name) {
63
+ const rel = `${name}.diagram.ts`;
64
+ try {
65
+ await access(path.join(diagramsDir, rel));
66
+ return rel;
67
+ }
68
+ catch {
69
+ return undefined;
70
+ }
71
+ }
72
+ /** The TypeScript a compiled diagram comes from, as plain text: what the studio's
73
+ * read-only chip opens. Only `.diagram.ts` is served — a JSON source is the
74
+ * studio's own, read through `readDiagram`. */
75
+ export async function readDiagramSource(diagramsDir, name) {
76
+ if (!isSafeName(name))
77
+ return refuse(400, `Unsafe name '${name}'`);
78
+ try {
79
+ const bytes = await readFile(path.join(diagramsDir, `${name}.diagram.ts`));
80
+ return { status: 200, body: undefined, bytes, contentType: 'text/plain; charset=utf-8' };
81
+ }
82
+ catch {
83
+ return refuse(404, `No TypeScript source '${name}'`);
84
+ }
57
85
  }
58
86
  /** `model` with its includes expanded for the list, or `model` itself when they
59
87
  * cannot be, with what went wrong added to `issues`. */
@@ -263,6 +291,44 @@ async function moveIfPresent(src, dst) {
263
291
  throw e;
264
292
  }
265
293
  }
294
+ /**
295
+ * Remove a studio-owned diagram: its JSON source, its layout and drawings sidecars,
296
+ * and its compiled artifact — the watcher's copy, which would otherwise list the
297
+ * diagram again, read-only, the next time the studio starts without a watcher
298
+ * having seen the deletion. A diagram with a `.diagram.ts` is TypeScript's: the
299
+ * studio never offers to delete it, and the route refuses too (409). Published
300
+ * pages and PNGs are left where they are; `diagc publish` regenerates them.
301
+ */
302
+ export async function deleteDiagram(diagramsDir, artifactsDir, name) {
303
+ if (!isSafeName(name))
304
+ return refuse(400, `Unsafe name '${name}'`);
305
+ const tsPath = path.join(diagramsDir, `${name}.diagram.ts`);
306
+ try {
307
+ await access(tsPath);
308
+ return refuse(409, `'${name}' is TypeScript-owned (${tsPath}) — delete its source`);
309
+ }
310
+ catch {
311
+ /* no TypeScript source — the studio's to delete */
312
+ }
313
+ const source = path.join(diagramsDir, `${name}.diagram.json`);
314
+ try {
315
+ await access(source);
316
+ }
317
+ catch {
318
+ return refuse(404, `No diagram source '${name}'`);
319
+ }
320
+ // The sidecars and the artifact first, the source last: a failure part-way
321
+ // leaves a diagram the studio still lists and can retry on.
322
+ for (const file of [
323
+ path.join(diagramsDir, `${name}.layout.json`),
324
+ path.join(diagramsDir, `${name}.drawings.json`),
325
+ path.join(artifactsDir, `${name}.diagram.json`),
326
+ ]) {
327
+ await rm(file, { force: true });
328
+ }
329
+ await unlink(source);
330
+ return { status: 200, body: { ok: true } };
331
+ }
266
332
  /** Promote a JSON-owned diagram to a generated `.diagram.ts`. See `ejectDiagram`
267
333
  * for the round-trip guarantee; this just maps its failure codes to statuses. */
268
334
  export async function ejectDiagramSource(diagramsDir, artifactsDir, name) {
@@ -1,5 +1,5 @@
1
1
  export { MAX_ASSET_BYTES, readAsset, saveAsset } from './assets.js';
2
- export { ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, renameDiagram, saveDiagram, type DiagramEntry, } from './diagrams.js';
2
+ export { deleteDiagram, ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, readDiagramSource, renameDiagram, saveDiagram, type DiagramEntry, } from './diagrams.js';
3
3
  export { walkDiagramJson, walkFiles } from './files.js';
4
4
  export { readLibrary, saveLibrary } from './library.js';
5
5
  export { exportPage } from './pages.js';
@@ -3,7 +3,7 @@
3
3
  // the Obsidian vault host imports the file by path. So each export is named, and a
4
4
  // helper one subject module exports to another does not become part of that type.
5
5
  export { MAX_ASSET_BYTES, readAsset, saveAsset } from './assets.js';
6
- export { ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, renameDiagram, saveDiagram, } from './diagrams.js';
6
+ export { deleteDiagram, ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, readDiagramSource, renameDiagram, saveDiagram, } from './diagrams.js';
7
7
  export { walkDiagramJson, walkFiles } from './files.js';
8
8
  export { readLibrary, saveLibrary } from './library.js';
9
9
  export { exportPage } from './pages.js';
@@ -36,11 +36,24 @@ export const ROUTES = [
36
36
  pattern: /^\/api\/diagrams\/(.+)\/composed$/,
37
37
  handler: (h, c) => h.readComposedDiagram(c.diagramsDir, decodeURIComponent(c.match[1] ?? '')),
38
38
  },
39
+ // The TypeScript a compiled diagram comes from, as text. Before the generic read
40
+ // for the same reason as the composed one.
41
+ {
42
+ method: 'GET',
43
+ pattern: /^\/api\/diagrams\/(.+)\/source$/,
44
+ handler: (h, c) => h.readDiagramSource(c.diagramsDir, decodeURIComponent(c.match[1] ?? '')),
45
+ },
39
46
  {
40
47
  method: 'GET',
41
48
  pattern: /^\/api\/diagrams\/(.+)$/,
42
49
  handler: (h, c) => h.readDiagram(c.diagramsDir, decodeURIComponent(c.match[1] ?? '')),
43
50
  },
51
+ // A diagram the studio owns, with its sidecars and its compiled artifact.
52
+ {
53
+ method: 'DELETE',
54
+ pattern: /^\/api\/diagrams\/(.+)$/,
55
+ handler: (h, c) => h.deleteDiagram(c.diagramsDir, c.artifactsDir, decodeURIComponent(c.match[1] ?? '')),
56
+ },
44
57
  // Rename must be checked before the generic save route, whose `(.+)`
45
58
  // would otherwise swallow `<from>/rename` as a filename.
46
59
  {
@@ -19,6 +19,7 @@ export interface FlagValues {
19
19
  '--ascii': true;
20
20
  '--color': true;
21
21
  '--no-color': true;
22
+ '--single-file': true;
22
23
  }
23
24
  export type Flag = keyof FlagValues;
24
25
  /** What a command takes, as the parser checks it before the command runs. */
package/dist/cli/parse.js CHANGED
@@ -121,6 +121,7 @@ const FLAGS = {
121
121
  '--ascii': null,
122
122
  '--color': null,
123
123
  '--no-color': null,
124
+ '--single-file': null,
124
125
  };
125
126
  const isFlag = (arg) => Object.hasOwn(FLAGS, arg);
126
127
  /** Read argv against every flag there is, whichever command it names: which arguments
package/dist/cli.js CHANGED
@@ -48,6 +48,8 @@ Options:
48
48
  --out dir Artifact output directory (default .diagrams/.artifacts;
49
49
  diff: .diagrams/diff/<from>..<to>)
50
50
  --no-images Publish (or diff) HTML without rendering PNG images
51
+ --single-file Publish every page whole, the viewer inside it, as a file to send
52
+ on its own (default: the pages share one diagc-viewer/ folder)
51
53
  --link url Publish with a link to url in the index header
52
54
  --style id Publish: take the PNGs in this style preset (clean, sketch, …) in
53
55
  place of each diagram's own; tui: draw every diagram in dos or clean
@@ -1,3 +1,3 @@
1
1
  import type { Command } from '../cli/command.js';
2
- /** `diagc compile [files...]`: the files named, or every source, into artifacts. */
2
+ /** `diagc compile [files...]`: the files or diagrams named, or every source, into artifacts. */
3
3
  export declare const compile: Command<'--out' | '--update-includes'>;
@@ -1,16 +1,15 @@
1
1
  import { errMessage } from '@diagc/core/internal';
2
2
  import { compileFile } from '../compile.js';
3
- import { globSorted } from '../glob.js';
4
3
  import { RELATIVE_PATHS } from '../paths.js';
5
4
  import { formatCompileEvent } from '../watch.js';
6
- import { SOURCES, warnNoSources } from './shared.js';
7
- /** `diagc compile [files...]`: the files named, or every source, into artifacts. */
5
+ import { resolveSources } from './shared.js';
6
+ /** `diagc compile [files...]`: the files or diagrams named, or every source, into artifacts. */
8
7
  export const compile = {
9
8
  flags: ['--out', '--update-includes'],
10
9
  async run({ positionals, flags }, { io, home, snapshots }) {
11
- const files = positionals.length > 0 ? positionals : await globSorted(SOURCES);
12
- if (positionals.length === 0 && files.length === 0)
13
- warnNoSources(io);
10
+ const files = await resolveSources(io, positionals);
11
+ if (files === undefined)
12
+ return 1;
14
13
  let failed = false;
15
14
  for (const file of files) {
16
15
  try {
@@ -1,14 +1,13 @@
1
1
  import { formatLintReport, lintFile } from '../lint.js';
2
- import { globSorted } from '../glob.js';
3
2
  import { RELATIVE_PATHS } from '../paths.js';
4
- import { SOURCES, warnNoSources } from './shared.js';
3
+ import { resolveSources } from './shared.js';
5
4
  /** `diagc lint [files...] [--json]`: every finding, and exit 1 on any. */
6
5
  export const lint = {
7
6
  flags: ['--json'],
8
7
  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);
8
+ const files = await resolveSources(io, positionals);
9
+ if (files === undefined)
10
+ return 1;
12
11
  const reports = [];
13
12
  for (const file of files) {
14
13
  reports.push(...(await lintFile(file, {
@@ -7,5 +7,5 @@ type PublishDirs = Pick<PublishOptions, 'srcDir' | 'artifactsDir' | 'htmlDir' |
7
7
  * that embed them expect to find them. */
8
8
  export declare function publishDirs(out: string): PublishDirs;
9
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' | '--style' | '--theme'>;
10
+ export declare const publish: Command<'--out' | '--no-images' | '--link' | '--update-includes' | '--style' | '--theme' | '--single-file'>;
11
11
  export {};
@@ -1,4 +1,5 @@
1
1
  import { existsSync } from 'node:fs';
2
+ import path from 'node:path';
2
3
  import { errMessage } from '@diagc/core/internal';
3
4
  import { compileFile } from '../compile.js';
4
5
  import { globSorted } from '../glob.js';
@@ -40,16 +41,19 @@ async function compileSources(dirs, { io, home, snapshots }) {
40
41
  }
41
42
  /** `diagc publish [names...]`: compile, then a page per diagram, the gallery, and PNGs. */
42
43
  export const publish = {
43
- flags: ['--out', '--no-images', '--link', '--update-includes', '--style', '--theme'],
44
+ flags: ['--out', '--no-images', '--link', '--update-includes', '--style', '--theme', '--single-file'],
44
45
  async run({ positionals, flags }, ctx) {
45
46
  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.
47
+ const singleFile = flags['--single-file'] === true;
48
+ // The shell for whole pages, the folder for pages that share the viewer: one
49
+ // build makes both. Only a checkout can be missing them; an installed package
50
+ // ships both, so there the message would send the reader off to build a repo
51
+ // they do not have.
52
+ const needed = singleFile ? home.viewerShell : path.join(home.viewerDir, 'viewer.js');
53
+ if (!existsSync(needed)) {
50
54
  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.`);
55
+ ? 'viewer not built — run `pnpm --filter @diagc/viewer build` in the monorepo.'
56
+ : `viewer missing from this install (${needed}) — reinstall diagc.`);
53
57
  return 1;
54
58
  }
55
59
  const dirs = publishDirs(flags['--out'] ?? RELATIVE_PATHS.artifactsDir);
@@ -67,6 +71,8 @@ export const publish = {
67
71
  const res = await publishDiagrams({
68
72
  ...dirs,
69
73
  shellPath: home.viewerShell,
74
+ viewerDir: home.viewerDir,
75
+ singleFile,
70
76
  libraryDir: home.libraryDir,
71
77
  images: renderPng !== undefined,
72
78
  names,
@@ -80,6 +86,8 @@ export const publish = {
80
86
  warn: io.err,
81
87
  });
82
88
  io.out(`✓ ${res.pages.length} page(s) -> ${dirs.htmlDir}`);
89
+ if (res.viewer !== undefined)
90
+ io.out(`✓ viewer -> ${res.viewer}`);
83
91
  if (res.images.length > 0)
84
92
  io.out(`✓ ${res.images.length} image(s) -> ${dirs.staticDir}`);
85
93
  io.out(`✓ gallery -> ${res.gallery}`);
@@ -17,6 +17,15 @@ export declare function diagramNames(io: CliIo, files: readonly string[], known:
17
17
  * says so on stderr, and the pages go out as HTML only. Playwright loads only when a
18
18
  * picture is wanted. */
19
19
  export declare function pngRenderer(io: CliIo, images: boolean): Promise<NonNullable<PublishOptions['renderPng']> | undefined>;
20
+ /**
21
+ * The sources `compile` and `lint` read for `files...`: a path as given, or a
22
+ * diagram name read as `publish` reads one (`shop` is `.diagrams/src/shop.diagram.ts`,
23
+ * else its `.diagram.json`). None given means every source, in path order, with
24
+ * the no-sources warning when there is none. An argument that is neither a file
25
+ * nor a diagram is one line on stderr each, and the result is then undefined: an
26
+ * empty selection would look like nothing to do.
27
+ */
28
+ export declare function resolveSources(io: CliIo, args: readonly string[]): Promise<string[] | undefined>;
20
29
  /** The source a diagram name reads from: its `.diagram.ts`, else its `.diagram.json`;
21
30
  * undefined when it has neither. TypeScript first, as the hand-written one of the two
22
31
  * (a `.diagram.json` beside it is the studio's, or a leftover from an eject). */
@@ -1,5 +1,6 @@
1
1
  import { existsSync } from 'node:fs';
2
2
  import path from 'node:path';
3
+ import { globSorted } from '../glob.js';
3
4
  import { diagramName } from '../names.js';
4
5
  import { RELATIVE_PATHS } from '../paths.js';
5
6
  /** The sources compile and lint read when they are named none. */
@@ -29,11 +30,39 @@ export async function pngRenderer(io, images) {
29
30
  return undefined;
30
31
  const snapshot = await import('../publish/snapshot.js');
31
32
  if (snapshot.findChrome() === undefined) {
32
- io.err('No Chrome found — writing HTML only; install Chrome / set CHROME_PATH, or use --no-images.');
33
+ io.err(snapshot.NO_CHROME_MESSAGE);
33
34
  return undefined;
34
35
  }
35
36
  return snapshot.renderPng;
36
37
  }
38
+ /**
39
+ * The sources `compile` and `lint` read for `files...`: a path as given, or a
40
+ * diagram name read as `publish` reads one (`shop` is `.diagrams/src/shop.diagram.ts`,
41
+ * else its `.diagram.json`). None given means every source, in path order, with
42
+ * the no-sources warning when there is none. An argument that is neither a file
43
+ * nor a diagram is one line on stderr each, and the result is then undefined: an
44
+ * empty selection would look like nothing to do.
45
+ */
46
+ export async function resolveSources(io, args) {
47
+ if (args.length === 0) {
48
+ const files = await globSorted(SOURCES);
49
+ if (files.length === 0)
50
+ warnNoSources(io);
51
+ return files;
52
+ }
53
+ const files = [];
54
+ let unknown = false;
55
+ for (const arg of args) {
56
+ const file = existsSync(arg) ? arg : sourceOf(diagramName(arg));
57
+ if (file === undefined) {
58
+ unknown = true;
59
+ io.err(`diagc: no diagram '${arg}' — not a file, and nothing under ${RELATIVE_PATHS.srcDir} is named that`);
60
+ continue;
61
+ }
62
+ files.push(file);
63
+ }
64
+ return unknown ? undefined : files;
65
+ }
37
66
  /** The source a diagram name reads from: its `.diagram.ts`, else its `.diagram.json`;
38
67
  * undefined when it has neither. TypeScript first, as the hand-written one of the two
39
68
  * (a `.diagram.json` beside it is the studio's, or a leftover from an eject). */
package/dist/compile.d.ts CHANGED
@@ -10,12 +10,18 @@ import { type DiagramModel, type IncludeResolver } from '@diagc/core/internal';
10
10
  export declare class LoadError extends Error {
11
11
  readonly file: string;
12
12
  readonly reason: string;
13
+ /** the rule a builder refusal names (`missing-kind`); undefined for a source
14
+ * that simply threw, which lint reports as `load` */
15
+ readonly code?: string | undefined;
13
16
  readonly line: number | undefined;
14
17
  readonly column: number | undefined;
15
18
  constructor(file: string, reason: string, position?: {
16
19
  line: number;
17
20
  column: number;
18
- });
21
+ },
22
+ /** the rule a builder refusal names (`missing-kind`); undefined for a source
23
+ * that simply threw, which lint reports as `load` */
24
+ code?: string | undefined);
19
25
  }
20
26
  /** The line and column of the first `at` frame inside `file`. Matched on the
21
27
  * basename after a path separator: a frame spells the path as it was imported,
@@ -46,4 +52,8 @@ export interface LoadOptions {
46
52
  * model `compile` writes and `lint` inspects. Throws on anything invalid.
47
53
  */
48
54
  export declare function loadModel(file: string, opts?: LoadOptions): Promise<DiagramModel>;
55
+ /** Where `file` compiles to under `outDir`: its name as `.diagram.json`, in the
56
+ * subdirectory it has under `rootDir`. The watcher removes the same path when the
57
+ * source goes. */
58
+ export declare function artifactPathFor(file: string, outDir: string, rootDir?: string): string;
49
59
  export declare function compileFile(file: string, outDir: string, opts?: LoadOptions): Promise<string>;
package/dist/compile.js CHANGED
@@ -4,6 +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 { loadHint } from './loadHints.js';
7
8
  import { lockedResolverFor } from './snapshots.js';
8
9
  /**
9
10
  * Shape guard: with `{ default: true }` jiti returns the module NAMESPACE when
@@ -29,17 +30,30 @@ function assertDiagramShape(model, file) {
29
30
  export class LoadError extends Error {
30
31
  file;
31
32
  reason;
33
+ code;
32
34
  line;
33
35
  column;
34
- constructor(file, reason, position) {
36
+ constructor(file, reason, position,
37
+ /** the rule a builder refusal names (`missing-kind`); undefined for a source
38
+ * that simply threw, which lint reports as `load` */
39
+ code) {
35
40
  super(position !== undefined ? `${file}:${position.line}:${position.column}: ${reason}` : reason);
36
41
  this.file = file;
37
42
  this.reason = reason;
43
+ this.code = code;
38
44
  this.name = 'LoadError';
39
45
  this.line = position?.line;
40
46
  this.column = position?.column;
41
47
  }
42
48
  }
49
+ /** The code a builder refusal carries, or undefined for any other error. By name,
50
+ * not instanceof: the diagram ran in jiti's own copy of core. */
51
+ function builderCode(e) {
52
+ if (!(e instanceof Error) || e.name !== 'BuilderError')
53
+ return undefined;
54
+ const code = e.code;
55
+ return typeof code === 'string' ? code : undefined;
56
+ }
43
57
  /** The line and column of the first `at` frame inside `file`. Matched on the
44
58
  * basename after a path separator: a frame spells the path as it was imported,
45
59
  * which a symlinked temp dir would not equal; the message line is skipped because
@@ -80,7 +94,7 @@ export async function executeDiagramTs(file, coreEntry) {
80
94
  // `issues` by name. Everything else is the source failing to run.
81
95
  if (e instanceof Error && e.name === 'DiagramValidationError')
82
96
  throw e;
83
- throw new LoadError(file, errMessage(e), positionIn(e instanceof Error ? e.stack : undefined, file));
97
+ throw new LoadError(file, loadHint(errMessage(e)), positionIn(e instanceof Error ? e.stack : undefined, file), builderCode(e));
84
98
  }
85
99
  const hasToJSON = typeof def?.toJSON === 'function';
86
100
  const model = (hasToJSON ? def.toJSON() : def);
@@ -150,6 +164,13 @@ export async function loadModel(file, opts) {
150
164
  }
151
165
  return model;
152
166
  }
167
+ /** Where `file` compiles to under `outDir`: its name as `.diagram.json`, in the
168
+ * subdirectory it has under `rootDir`. The watcher removes the same path when the
169
+ * source goes. */
170
+ export function artifactPathFor(file, outDir, rootDir) {
171
+ const base = path.basename(file).replace(/\.diagram\.(ts|json)$/, '');
172
+ return path.join(outDir, relativeSubdir(file, rootDir), `${base}.diagram.json`);
173
+ }
153
174
  export async function compileFile(file, outDir, opts) {
154
175
  const model = await loadModel(file, opts);
155
176
  // Sound but probably not what was meant (a fishbone cause on no bone, a typo'd
@@ -157,10 +178,8 @@ export async function compileFile(file, outDir, opts) {
157
178
  // complaint. `diagc lint` is the strict reading of the same list.
158
179
  for (const w of diagramWarnings(model))
159
180
  (opts?.warn ?? console.warn)(`${file}: ${w.message}`);
160
- const base = path.basename(file).replace(/\.diagram\.(ts|json)$/, '');
161
- const artifactDir = path.join(outDir, relativeSubdir(file, opts?.rootDir));
162
- await mkdir(artifactDir, { recursive: true });
163
- const artifact = path.join(artifactDir, `${base}.diagram.json`);
181
+ const artifact = artifactPathFor(file, outDir, opts?.rootDir);
182
+ await mkdir(path.dirname(artifact), { recursive: true });
164
183
  await writeFile(artifact, `${JSON.stringify(model, null, 2)}\n`);
165
184
  return artifact;
166
185
  }
package/dist/guide.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { existsSync, readdirSync, readFileSync } from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { NODE_TYPES, NOTATION_NODE_TYPES, NOTATION_RELATION_KINDS, RELATION_KINDS } from '@diagc/core/internal';
4
- import { UnknownStarterError, readStarter } from './starters.js';
4
+ import { UnknownStarterError, readStarter, starterTypes } from './starters.js';
5
5
  const INDEX = 'index';
6
6
  /** `diagc guide all`: the index, then every topic — for a reader who cannot ask
7
7
  * for one (the copy published on the website). */
@@ -62,17 +62,27 @@ function nodeTypesFor(page) {
62
62
  function relationKindsFor(page) {
63
63
  return [...new Set([...RELATION_KINDS, ...notationOwn(NOTATION_RELATION_KINDS, page)])];
64
64
  }
65
- /** One bullet per topic: the command that prints it, and its own title. */
66
- function topicList(guideDir) {
67
- return guideTopics(guideDir)
68
- .map((topic) => {
69
- const file = path.join(guideDir, `${topic}.md`);
65
+ /**
66
+ * One bullet per topic of one kind: the command that prints it, and its own title.
67
+ * A topic with a starter is a diagram type (`init --type` offers it); one without is
68
+ * a feature any diagram can use (composition). Every topic's title is read whatever
69
+ * its kind, so a page with none fails here. `at` names the page the placeholder is in.
70
+ */
71
+ function topicList(ctx, kind, placeholder, at) {
72
+ const types = new Set(starterTypes(ctx.startersDir));
73
+ const bullets = [];
74
+ for (const topic of guideTopics(ctx.guideDir)) {
75
+ const file = path.join(ctx.guideDir, `${topic}.md`);
70
76
  const title = /^# (.+)$/m.exec(readFileSync(file, 'utf8'))?.[1];
71
77
  if (title === undefined)
72
78
  throw new Error(`${file}: a topic starts with a '# Title' line`);
73
- return `- \`diagc guide ${topic}\` — ${title.trim()}`;
74
- })
75
- .join('\n');
79
+ if (types.has(topic) === (kind === 'types'))
80
+ bullets.push(`- \`diagc guide ${topic}\` — ${title.trim()}`);
81
+ }
82
+ if (bullets.length === 0) {
83
+ throw new Error(`${at}: ${placeholder} is empty — ${kind === 'types' ? 'no topic has a starter' : 'every topic has a starter'}`);
84
+ }
85
+ return bullets.join('\n');
76
86
  }
77
87
  /** One page with its placeholders filled. The replacer is a function, so what it
78
88
  * returns is taken literally: a starter holding `$&` or a `{{…}}` of its own is
@@ -97,7 +107,9 @@ function renderPage(page, ctx) {
97
107
  case 'relation-kinds':
98
108
  return codeList(relationKindsFor(page));
99
109
  case 'topics':
100
- return topicList(ctx.guideDir);
110
+ return topicList(ctx, 'types', whole, file);
111
+ case 'feature-topics':
112
+ return topicList(ctx, 'features', whole, file);
101
113
  case 'version':
102
114
  return ctx.version;
103
115
  default:
package/dist/home.d.ts CHANGED
@@ -9,8 +9,12 @@ export type HomeLayout = 'monorepo' | 'packaged';
9
9
  export interface HomePaths {
10
10
  root: string;
11
11
  layout: HomeLayout;
12
- /** single-file viewer HTML that `publish` stamps models into */
12
+ /** single-file viewer HTML that `publish --single-file`, the studio's export and
13
+ * `diff` stamp models into */
13
14
  viewerShell: string;
15
+ /** the same viewer as separate files (`viewer.js`, `viewer.css`, fonts), which
16
+ * `publish` copies once beside the pages for them to share */
17
+ viewerDir: string;
14
18
  /** icon/shape library that `publish` inlines `/library/...` refs from */
15
19
  libraryDir: string;
16
20
  /** module `@diagc/core` is aliased to when jiti executes a `.diagram.ts` */
package/dist/home.js CHANGED
@@ -57,6 +57,7 @@ export function homePaths(home, coreEntry = resolveCoreEntry) {
57
57
  root,
58
58
  layout,
59
59
  viewerShell: path.join(root, 'assets', 'viewer', 'index.html'),
60
+ viewerDir: path.join(root, 'assets', 'viewer', 'shared'),
60
61
  // The studio bundle carries its own `public/library` through the Vite
61
62
  // build, so publish and the studio server read one staged copy.
62
63
  libraryDir: path.join(studioDir, 'library'),
@@ -71,6 +72,7 @@ export function homePaths(home, coreEntry = resolveCoreEntry) {
71
72
  root,
72
73
  layout,
73
74
  viewerShell: path.join(root, 'apps', 'viewer', 'dist', 'index.html'),
75
+ viewerDir: path.join(root, 'apps', 'viewer', 'dist', 'shared'),
74
76
  libraryDir: path.join(root, 'apps', 'studio', 'public', 'library'),
75
77
  coreEntry: path.join(root, 'packages', 'core', 'src', 'index.ts'),
76
78
  studioDir: path.join(root, 'apps', 'studio'),
package/dist/init.d.ts CHANGED
@@ -31,7 +31,7 @@ export declare const AGENTS_END = "<!-- diagc:end -->";
31
31
  /** What `--agents` writes. Commands, not DSL: the guide is where the DSL lives, so
32
32
  * this block does not go stale when the DSL grows. The markers let a later run
33
33
  * replace it in place. */
34
- export declare const AGENTS_BLOCK = "<!-- diagc:begin -->\n## Diagrams\n\nDiagrams live in `.diagrams/src/*.diagram.ts` and are built with `diagc`.\n\n- Run `diagc guide` before writing or changing one; `diagc guide <type>` covers one diagram type.\n- Run `diagc lint --json` until it reports nothing.\n- Run `diagc show <name>` to read the picture as text, and `diagc publish <name>` to look at `.diagrams/static/<name>.png`.\n<!-- diagc:end -->\n";
34
+ export declare const AGENTS_BLOCK = "<!-- diagc:begin -->\n## Diagrams\n\nDiagrams live in `.diagrams/src/*.diagram.ts` and are built with `diagc`.\n\n- Run `diagc guide` before writing or changing one; `diagc guide <type>` covers one diagram type, and `diagc guide compose` pulling other diagrams in.\n- Run `diagc lint --json` until it reports nothing.\n- Run `diagc show <name>` to read the picture as text, and `diagc publish <name>` to look at `.diagrams/static/<name>.png`.\n<!-- diagc:end -->\n";
35
35
  /** Where the skill goes: the folder Claude Code reads a repository's skills from. */
36
36
  export declare const SKILL_PATH = ".claude/skills/diagc/SKILL.md";
37
37
  /** `existing` with `block` added at the end, or — when an earlier block is there —
package/dist/init.js CHANGED
@@ -25,7 +25,7 @@ export const AGENTS_BLOCK = `${AGENTS_BEGIN}
25
25
 
26
26
  Diagrams live in \`.diagrams/src/*.diagram.ts\` and are built with \`diagc\`.
27
27
 
28
- - Run \`diagc guide\` before writing or changing one; \`diagc guide <type>\` covers one diagram type.
28
+ - Run \`diagc guide\` before writing or changing one; \`diagc guide <type>\` covers one diagram type, and \`diagc guide compose\` pulling other diagrams in.
29
29
  - Run \`diagc lint --json\` until it reports nothing.
30
30
  - Run \`diagc show <name>\` to read the picture as text, and \`diagc publish <name>\` to look at \`.diagrams/static/<name>.png\`.
31
31
  ${AGENTS_END}
package/dist/lint.js CHANGED
@@ -30,7 +30,8 @@ export async function lintFile(file, opts) {
30
30
  {
31
31
  file,
32
32
  severity: 'error',
33
- code: 'load',
33
+ // a builder refusal names its rule; a source that simply threw is `load`
34
+ code: e.code ?? 'load',
34
35
  message: e.reason,
35
36
  ...(e.line !== undefined && e.column !== undefined ? { line: e.line, column: e.column } : {}),
36
37
  },
@@ -0,0 +1,8 @@
1
+ /**
2
+ * A load error's message with what the author probably meant, when the shape of
3
+ * the message says: `x.y is not a function` is a method that does not exist, so
4
+ * the closest one that does is named, by the lint's own did-you-mean rule — and a
5
+ * composition verb gets told where composition lives instead, since no method is
6
+ * close to what they wanted. Anything else is returned as it is.
7
+ */
8
+ export declare function loadHint(message: string): string;