agentic-mermaid 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (340) hide show
  1. package/AGENT_NATIVE.md +155 -91
  2. package/CHANGELOG.md +163 -4
  3. package/Instructions_for_agents.md +10 -10
  4. package/LICENSES/Apache-2.0.txt +202 -0
  5. package/README.md +31 -38
  6. package/THIRD_PARTY_NOTICES.md +29 -0
  7. package/assets/hero.png +0 -0
  8. package/dist/agent-core.d.ts +463 -0
  9. package/dist/agent-core.js +397 -0
  10. package/dist/agent.d.ts +73 -1868
  11. package/dist/agent.js +336 -37325
  12. package/dist/agentic-mermaid-mcp.js +7 -38399
  13. package/dist/am.js +33626 -40446
  14. package/dist/chunk-2P5FKUQC.js +3485 -0
  15. package/dist/chunk-2S3VSS6I.js +149 -0
  16. package/dist/chunk-2SILJDW2.js +37 -0
  17. package/dist/chunk-BJYMBT4I.js +61963 -0
  18. package/dist/chunk-FDM43XU7.js +615 -0
  19. package/dist/chunk-MYPDVZCO.js +4702 -0
  20. package/dist/index-DWPa2MJs.d.ts +6780 -0
  21. package/dist/index.d.ts +1 -1
  22. package/dist/index.js +310 -33014
  23. package/dist/mcp-cli-5J47WEY3.js +17 -0
  24. package/docs/README.md +39 -31
  25. package/docs/agent-api-cookbook.md +44 -35
  26. package/docs/agent-mutation-policy.md +1 -1
  27. package/docs/agent-workflow-examples.md +2 -2
  28. package/docs/api.md +284 -77
  29. package/docs/ascii.md +26 -16
  30. package/docs/code-mode-impact.md +214 -0
  31. package/docs/comparison.md +23 -11
  32. package/docs/computational-aesthetics-prototype-plan.md +252 -0
  33. package/docs/config.md +26 -10
  34. package/docs/custom-fonts.md +265 -0
  35. package/docs/custom-style-cookbook.md +130 -9
  36. package/docs/diagram-families.md +48 -23
  37. package/docs/features.md +59 -52
  38. package/docs/fork-differences.md +6 -3
  39. package/docs/getting-started.md +23 -16
  40. package/docs/issue-derived-test-cases.md +29 -22
  41. package/docs/mcp-code-mode-rationale.md +13 -6
  42. package/docs/mcp-http-transport.md +20 -13
  43. package/docs/mermaid-layout-complaints.md +66 -52
  44. package/docs/mutation-testing.md +145 -66
  45. package/docs/quality.md +23 -14
  46. package/docs/react.md +2 -2
  47. package/docs/schemas/style-spec.schema.json +1221 -30
  48. package/docs/style-authoring.md +241 -38
  49. package/docs/svg-semantic-contract.md +49 -0
  50. package/docs/testing-strategy.md +166 -58
  51. package/docs/theming.md +19 -32
  52. package/examples/styles/catalog.json +54 -0
  53. package/examples/styles/cloudflare-workers-inspired-prototype.mmd +9 -0
  54. package/examples/styles/cloudflare-workers-inspired-prototype.style.json +110 -0
  55. package/examples/styles/cupertino-prototype.mmd +10 -0
  56. package/examples/styles/cupertino-prototype.style.json +63 -0
  57. package/examples/styles/mid-century-report.style.json +2 -2
  58. package/examples/styles/star-chart-atlas.style.json +2 -1
  59. package/examples/styles/transit-route-map.style.json +2 -2
  60. package/examples/styles/vercel-inspired-prototype.mmd +6 -0
  61. package/examples/styles/vercel-inspired-prototype.style.json +87 -0
  62. package/package.json +85 -45
  63. package/server.json +2 -2
  64. package/skills/agentic-mermaid-diagram-workflow/SKILL.md +17 -36
  65. package/skills/agentic-mermaid-diagram-workflow/references/cli.md +4 -5
  66. package/skills/agentic-mermaid-diagram-workflow/references/code-mode.md +15 -31
  67. package/skills/agentic-mermaid-diagram-workflow/references/sequence.md +10 -14
  68. package/skills/agentic-mermaid-live-editor/SKILL.md +100 -206
  69. package/TODO.md +0 -684
  70. package/dist/index-wjRjbsP-.d.ts +0 -1102
  71. package/docs/assets/improvements/box-start-connector.png +0 -0
  72. package/docs/assets/improvements/comment-dropped-lint.png +0 -0
  73. package/docs/assets/improvements/er-content-loss.png +0 -0
  74. package/docs/assets/improvements/fan-in-trunks.png +0 -0
  75. package/docs/assets/improvements/gantt-family.png +0 -0
  76. package/docs/assets/improvements/gantt-milestone-clamp.png +0 -0
  77. package/docs/assets/improvements/gantt-verify-seam.png +0 -0
  78. package/docs/assets/improvements/subgraph-container-edges.png +0 -0
  79. package/docs/assets/improvements/wrapper-frontmatter.png +0 -0
  80. package/docs/assets/improvements/wrapper-init-directive.png +0 -0
  81. package/docs/assets/improvements/wrapper-leading-comment.png +0 -0
  82. package/docs/assets/style-cookbook/mid-century-report.png +0 -0
  83. package/docs/assets/style-cookbook/star-chart-atlas.png +0 -0
  84. package/docs/assets/style-cookbook/transit-route-map.png +0 -0
  85. package/docs/contributing/adding-diagram-types.md +0 -144
  86. package/docs/contributing/diagram-family-citizenship.matrix.json +0 -2127
  87. package/docs/contributing/diagram-family-citizenship.md +0 -82
  88. package/docs/contributing/harvesting-upstream-tests.md +0 -126
  89. package/docs/contributing/lessons-learned.md +0 -276
  90. package/docs/contributing/releasing.md +0 -82
  91. package/docs/contributing/visual-review-evidence.md +0 -53
  92. package/docs/design/families/README.md +0 -26
  93. package/docs/design/families/architecture-beta.md +0 -48
  94. package/docs/design/families/flowchart-parser-conformance.md +0 -22
  95. package/docs/design/families/gantt-research.md +0 -137
  96. package/docs/design/families/gantt.md +0 -329
  97. package/docs/design/families/journey-agentic-cards-before.png +0 -0
  98. package/docs/design/families/journey-experience-curve-implementation.png +0 -0
  99. package/docs/design/families/journey-mermaid-classic-implementation.png +0 -0
  100. package/docs/design/families/journey-mermaid-classic-prototype.png +0 -0
  101. package/docs/design/families/journey-mermaid-classic-prototype.svg +0 -163
  102. package/docs/design/families/journey-mermaid-classic-prototype.svg.png +0 -0
  103. package/docs/design/families/journey-migration-parity.md +0 -439
  104. package/docs/design/families/journey-section-overlap-after.png +0 -0
  105. package/docs/design/families/journey-section-overlap-before.png +0 -0
  106. package/docs/design/families/journey-usage-research.md +0 -423
  107. package/docs/design/families/journey.md +0 -153
  108. package/docs/design/families/xychart.md +0 -85
  109. package/docs/design/system/README.md +0 -45
  110. package/docs/design/system/abstraction-audit.md +0 -224
  111. package/docs/design/system/abstraction-recommendations.md +0 -655
  112. package/docs/design/system/architecture.mmd +0 -29
  113. package/docs/design/system/architecture.svg +0 -137
  114. package/docs/design/system/layout-guarantees-and-robustness.md +0 -351
  115. package/docs/design/system/layout-rubric.md +0 -138
  116. package/docs/design/system/route-contracts.md +0 -848
  117. package/docs/design/system/source-preservation-ladder.md +0 -52
  118. package/docs/design/system/styles-rollout.md +0 -216
  119. package/docs/design/system/ugly-layouts.md +0 -119
  120. package/docs/layout-characterization/README.md +0 -245
  121. package/docs/layout-characterization/contact-sheet-families.md +0 -498
  122. package/docs/layout-characterization/contact-sheet.md +0 -638
  123. package/docs/layout-characterization/properties.md +0 -281
  124. package/docs/layout-characterization/visual-quality.md +0 -160
  125. package/docs/layout-characterization/visual-snapshots/architecture.svg +0 -79
  126. package/docs/layout-characterization/visual-snapshots/class.svg +0 -60
  127. package/docs/layout-characterization/visual-snapshots/er.svg +0 -61
  128. package/docs/layout-characterization/visual-snapshots/flowchart.svg +0 -58
  129. package/docs/layout-characterization/visual-snapshots/gantt.svg +0 -52
  130. package/docs/layout-characterization/visual-snapshots/journey.svg +0 -98
  131. package/docs/layout-characterization/visual-snapshots/pie.svg +0 -36
  132. package/docs/layout-characterization/visual-snapshots/quadrant.svg +0 -47
  133. package/docs/layout-characterization/visual-snapshots/sequence.svg +0 -59
  134. package/docs/layout-characterization/visual-snapshots/state.svg +0 -52
  135. package/docs/layout-characterization/visual-snapshots/timeline.svg +0 -64
  136. package/docs/layout-characterization/visual-snapshots/xychart.svg +0 -97
  137. package/docs/project/divergences.md +0 -98
  138. package/docs/project/dogfooding-docs-strategy.md +0 -66
  139. package/docs/project/hosted-mcp-cloudflare-plan.md +0 -338
  140. package/docs/project/lessons-learned.md +0 -1019
  141. package/docs/project/remove-role-styling-plan.md +0 -176
  142. package/examples/agent-improve-auth-flow.ts +0 -206
  143. package/examples/agent-loop.ts +0 -53
  144. package/examples/mcp-vs-cli-complex-diagrams.ts +0 -133
  145. package/llms.txt +0 -104
  146. package/skill-evals/README.md +0 -77
  147. package/skill-evals/fixtures/architecture-cache/input.mmd +0 -5
  148. package/skill-evals/fixtures/class-payment/input.mmd +0 -4
  149. package/skill-evals/fixtures/er-orders/input.mmd +0 -10
  150. package/skill-evals/fixtures/flowchart-cache/input.mmd +0 -3
  151. package/skill-evals/fixtures/gantt-release/input.mmd +0 -7
  152. package/skill-evals/fixtures/journey-checkout/input.mmd +0 -6
  153. package/skill-evals/fixtures/pie-exports/input.mmd +0 -5
  154. package/skill-evals/fixtures/quadrant-priorities/input.mmd +0 -11
  155. package/skill-evals/fixtures/sequence-retry/input.mmd +0 -8
  156. package/skill-evals/fixtures/state-lifecycle/input.mmd +0 -5
  157. package/skill-evals/fixtures/timeline-release/input.mmd +0 -6
  158. package/skill-evals/fixtures/xychart-growth/input.mmd +0 -5
  159. package/skill-evals/shared-benchmark.json +0 -510
  160. package/src/agent/analyze.ts +0 -157
  161. package/src/agent/apply.ts +0 -146
  162. package/src/agent/architecture-body.ts +0 -458
  163. package/src/agent/certificates.ts +0 -110
  164. package/src/agent/class-body.ts +0 -319
  165. package/src/agent/core.ts +0 -207
  166. package/src/agent/create.ts +0 -106
  167. package/src/agent/describe.ts +0 -368
  168. package/src/agent/er-body.ts +0 -224
  169. package/src/agent/facts.ts +0 -360
  170. package/src/agent/families-builtin.ts +0 -920
  171. package/src/agent/families.ts +0 -232
  172. package/src/agent/family-layouts.ts +0 -832
  173. package/src/agent/flowchart-body.ts +0 -372
  174. package/src/agent/flowchart-unsupported.ts +0 -243
  175. package/src/agent/font-coverage.ts +0 -288
  176. package/src/agent/gantt-body.ts +0 -495
  177. package/src/agent/index.ts +0 -10
  178. package/src/agent/journey-body.ts +0 -374
  179. package/src/agent/label-metrics.ts +0 -28
  180. package/src/agent/layout-to-rendered.ts +0 -63
  181. package/src/agent/mutate.ts +0 -97
  182. package/src/agent/mutation-ops.ts +0 -51
  183. package/src/agent/op-schema.ts +0 -443
  184. package/src/agent/parse.ts +0 -223
  185. package/src/agent/pie-body.ts +0 -270
  186. package/src/agent/png.ts +0 -171
  187. package/src/agent/quadrant-body.ts +0 -336
  188. package/src/agent/quality.ts +0 -363
  189. package/src/agent/readability-audit.ts +0 -92
  190. package/src/agent/rendered-route-audit.ts +0 -61
  191. package/src/agent/sequence-body.ts +0 -345
  192. package/src/agent/serialize.ts +0 -214
  193. package/src/agent/state-body.ts +0 -589
  194. package/src/agent/structural-count.ts +0 -150
  195. package/src/agent/timeline-body.ts +0 -280
  196. package/src/agent/trace-log.ts +0 -43
  197. package/src/agent/types.ts +0 -995
  198. package/src/agent/verify.ts +0 -603
  199. package/src/agent/xychart-body.ts +0 -472
  200. package/src/architecture/config.ts +0 -282
  201. package/src/architecture/layout.ts +0 -496
  202. package/src/architecture/parser.ts +0 -375
  203. package/src/architecture/renderer.ts +0 -611
  204. package/src/architecture/types.ts +0 -113
  205. package/src/ascii/ansi.ts +0 -423
  206. package/src/ascii/architecture.ts +0 -210
  207. package/src/ascii/canvas.ts +0 -443
  208. package/src/ascii/class-diagram.ts +0 -697
  209. package/src/ascii/converter.ts +0 -475
  210. package/src/ascii/draw.ts +0 -1693
  211. package/src/ascii/edge-bundling.ts +0 -328
  212. package/src/ascii/edge-routing.ts +0 -330
  213. package/src/ascii/er-diagram.ts +0 -439
  214. package/src/ascii/gantt.ts +0 -276
  215. package/src/ascii/grid.ts +0 -747
  216. package/src/ascii/index.ts +0 -196
  217. package/src/ascii/journey.ts +0 -169
  218. package/src/ascii/meta.ts +0 -244
  219. package/src/ascii/multiline-utils.ts +0 -80
  220. package/src/ascii/pathfinder.ts +0 -301
  221. package/src/ascii/pie.ts +0 -67
  222. package/src/ascii/quadrant.ts +0 -158
  223. package/src/ascii/reverse.ts +0 -216
  224. package/src/ascii/sequence.ts +0 -499
  225. package/src/ascii/shapes/circle.ts +0 -27
  226. package/src/ascii/shapes/corners.ts +0 -143
  227. package/src/ascii/shapes/diamond.ts +0 -27
  228. package/src/ascii/shapes/hexagon.ts +0 -27
  229. package/src/ascii/shapes/index.ts +0 -106
  230. package/src/ascii/shapes/rectangle.ts +0 -168
  231. package/src/ascii/shapes/rounded.ts +0 -27
  232. package/src/ascii/shapes/special.ts +0 -332
  233. package/src/ascii/shapes/stadium.ts +0 -110
  234. package/src/ascii/shapes/state.ts +0 -192
  235. package/src/ascii/shapes/types.ts +0 -73
  236. package/src/ascii/timeline.ts +0 -141
  237. package/src/ascii/types.ts +0 -312
  238. package/src/ascii/validate.ts +0 -120
  239. package/src/ascii/width.ts +0 -81
  240. package/src/ascii/wrap.ts +0 -131
  241. package/src/ascii/xychart.ts +0 -919
  242. package/src/browser.ts +0 -29
  243. package/src/class/layout.ts +0 -240
  244. package/src/class/parser.ts +0 -332
  245. package/src/class/renderer.ts +0 -638
  246. package/src/class/types.ts +0 -129
  247. package/src/cli/agent-instructions.ts +0 -1
  248. package/src/cli/am-bin.ts +0 -6
  249. package/src/cli/exit-codes.ts +0 -18
  250. package/src/cli/index.ts +0 -1132
  251. package/src/cli/init-agent.ts +0 -147
  252. package/src/cli/run-entrypoint.ts +0 -10
  253. package/src/color-resolver.ts +0 -152
  254. package/src/elk-instance.ts +0 -114
  255. package/src/er/layout.ts +0 -187
  256. package/src/er/parser.ts +0 -226
  257. package/src/er/renderer.ts +0 -792
  258. package/src/er/types.ts +0 -99
  259. package/src/family-rubric.ts +0 -425
  260. package/src/font-manifest.ts +0 -31
  261. package/src/gantt/layout.ts +0 -365
  262. package/src/gantt/parser.ts +0 -282
  263. package/src/gantt/pipeline.ts +0 -27
  264. package/src/gantt/renderer.ts +0 -414
  265. package/src/gantt/schedule.ts +0 -513
  266. package/src/gantt/types.ts +0 -255
  267. package/src/index.ts +0 -368
  268. package/src/journey/layout.ts +0 -554
  269. package/src/journey/parse-core.ts +0 -251
  270. package/src/journey/parser.ts +0 -101
  271. package/src/journey/renderer.ts +0 -917
  272. package/src/journey/types.ts +0 -144
  273. package/src/layout/geometry.ts +0 -182
  274. package/src/layout/pass.ts +0 -142
  275. package/src/layout/passes/index.ts +0 -3916
  276. package/src/layout-engine.ts +0 -1565
  277. package/src/layout-rubric.ts +0 -659
  278. package/src/mcp/artifacts.ts +0 -137
  279. package/src/mcp/dynamic-harness.ts +0 -31
  280. package/src/mcp/dynamic-modules.d.ts +0 -7
  281. package/src/mcp/facade.ts +0 -608
  282. package/src/mcp/harness-runtime.ts +0 -203
  283. package/src/mcp/hosted-server.ts +0 -468
  284. package/src/mcp/mcp-bin.ts +0 -3
  285. package/src/mcp/mcp-cli.ts +0 -82
  286. package/src/mcp/protocol.ts +0 -13
  287. package/src/mcp/sandbox.ts +0 -195
  288. package/src/mcp/sdk-decl.ts +0 -391
  289. package/src/mcp/server.ts +0 -362
  290. package/src/mcp/tool-surface.ts +0 -146
  291. package/src/mermaid-source.ts +0 -655
  292. package/src/multiline-utils.ts +0 -228
  293. package/src/parser.ts +0 -1031
  294. package/src/pie/layout.ts +0 -168
  295. package/src/pie/parser.ts +0 -136
  296. package/src/pie/renderer.ts +0 -234
  297. package/src/pie/types.ts +0 -82
  298. package/src/quadrant/layout.ts +0 -191
  299. package/src/quadrant/parser.ts +0 -183
  300. package/src/quadrant/renderer.ts +0 -322
  301. package/src/quadrant/types.ts +0 -113
  302. package/src/render-family-hooks.ts +0 -244
  303. package/src/renderer.ts +0 -1099
  304. package/src/route-contracts.ts +0 -2723
  305. package/src/scene/backend.ts +0 -76
  306. package/src/scene/fidelity.ts +0 -183
  307. package/src/scene/hybrid-backend.ts +0 -174
  308. package/src/scene/ir.ts +0 -181
  309. package/src/scene/marks.ts +0 -127
  310. package/src/scene/rough-backend.ts +0 -378
  311. package/src/scene/seed.ts +0 -46
  312. package/src/scene/style-registry.ts +0 -556
  313. package/src/sequence/layout.ts +0 -456
  314. package/src/sequence/parser.ts +0 -255
  315. package/src/sequence/renderer.ts +0 -604
  316. package/src/sequence/types.ts +0 -154
  317. package/src/shape-clipping.ts +0 -351
  318. package/src/shared/accessibility-directives.ts +0 -22
  319. package/src/shared/batched.ts +0 -61
  320. package/src/shared/color-math.ts +0 -93
  321. package/src/shared/svg-a11y.ts +0 -29
  322. package/src/shared/syntax-error.ts +0 -17
  323. package/src/shared/unicode-ranges.ts +0 -135
  324. package/src/styles.ts +0 -318
  325. package/src/svg-paths.ts +0 -28
  326. package/src/text-metrics.ts +0 -248
  327. package/src/theme.ts +0 -710
  328. package/src/timeline/layout.ts +0 -381
  329. package/src/timeline/parser.ts +0 -215
  330. package/src/timeline/renderer.ts +0 -538
  331. package/src/timeline/types.ts +0 -105
  332. package/src/types.ts +0 -462
  333. package/src/website-worker-modules.d.ts +0 -18
  334. package/src/xychart/axis-utils.ts +0 -109
  335. package/src/xychart/colors.ts +0 -124
  336. package/src/xychart/config.ts +0 -88
  337. package/src/xychart/layout.ts +0 -656
  338. package/src/xychart/parser.ts +0 -504
  339. package/src/xychart/renderer.ts +0 -640
  340. package/src/xychart/types.ts +0 -282
@@ -1,458 +0,0 @@
1
- // ============================================================================
2
- // Architecture structured body (BUILD-17: promotes architecture-beta from
3
- // opaque-only fallback semantics to structured mutation, following the BUILD-15
4
- // journey pilot).
5
- //
6
- // Modeled grammar (mirrors the legacy renderer parser, src/architecture/parser.ts):
7
- // group <id>(<icon>)[<Label>] [in <parentGroup>]
8
- // service <id>(<icon>)[<Label>] [in <group>]
9
- // junction <id> [in <group>]
10
- // <id>[{group}]:<SIDE> <arrow> <SIDE>:<id>[{group}] (SIDE ∈ L|R|T|B)
11
- // arrows: -- --> <-- <--> and labeled -[label]- forms
12
- //
13
- // Structured-or-opaque: any other non-blank, non-comment line (accTitle,
14
- // accDescr, the {group} boundary modifier, unmodeled syntax) returns null so
15
- // the caller falls back to a lossless opaque body. Render support is unchanged
16
- // — the legacy renderer keeps parsing the canonical source this module emits.
17
- // ============================================================================
18
-
19
- import { unknownOpMessage } from './mutation-ops.ts'
20
- import type {
21
- ArchitectureBody, ArchitectureGroup, ArchitectureService, ArchitectureJunction,
22
- ArchitectureEdge, ArchitectureSide, ArchitectureMutationOp,
23
- MutationError, Result, LayoutWarning, VerifyOptions,
24
- } from './types.ts'
25
- import { ok, err, DEFAULT_LABEL_CHAR_CAP } from './types.ts'
26
- import { labelOverflowWarning } from './label-metrics.ts'
27
-
28
- // ---- Parser -----------------------------------------------------------------
29
-
30
- const IDENT = '[\\w-]+'
31
- const ICON = '\\(([^)]+)\\)'
32
- const LABEL = '\\[(.+)\\]'
33
-
34
- const GROUP_RE = new RegExp(`^group\\s+(${IDENT})(?:${ICON})?(?:${LABEL})?(?:\\s+in\\s+(${IDENT}))?\\s*$`)
35
- const SERVICE_RE = new RegExp(`^service\\s+(${IDENT})(?:${ICON})?(?:${LABEL})?(?:\\s+in\\s+(${IDENT}))?\\s*$`)
36
- const JUNCTION_RE = new RegExp(`^junction\\s+(${IDENT})(?:\\s+in\\s+(${IDENT}))?\\s*$`)
37
- // Endpoints: id:SIDE on the source, SIDE:id on the target. We deliberately do
38
- // NOT model the {group} boundary modifier (id{group}:R) — those lines fall
39
- // back to opaque, preserving the renderer's group-boundary feature losslessly.
40
- const SOURCE_RE = new RegExp(`^(${IDENT}):(L|R|T|B)$`)
41
- const TARGET_RE = new RegExp(`^(L|R|T|B):(${IDENT})$`)
42
-
43
- const SIDES = new Set<ArchitectureSide>(['L', 'R', 'T', 'B'])
44
-
45
- function normalizeText(value: string): string {
46
- return value.split(/\r?\n/).map(part => part.trim()).filter(Boolean).join(' ')
47
- }
48
-
49
- interface ParsedEndpoint { id: string; side: ArchitectureSide }
50
-
51
- /** Parse an edge operator, returning the modeled arrow forms or null. */
52
- function parseArrow(token: string): { label?: string; hasArrowStart: boolean; hasArrowEnd: boolean } | null {
53
- const t = token.trim()
54
- if (t === '<-->') return { hasArrowStart: true, hasArrowEnd: true }
55
- if (t === '-->') return { hasArrowStart: false, hasArrowEnd: true }
56
- if (t === '<--') return { hasArrowStart: true, hasArrowEnd: false }
57
- if (t === '--') return { hasArrowStart: false, hasArrowEnd: false }
58
- const m = t.match(/^(<)?-\[(.*)\]-(>)?$/)
59
- if (!m) return null
60
- const label = normalizeText(m[2] ?? '') || undefined
61
- // A label that contains the bracket delimiter would not round-trip; reject.
62
- if (label && (label.includes('[') || label.includes(']'))) return null
63
- return { label, hasArrowStart: Boolean(m[1]), hasArrowEnd: Boolean(m[3]) }
64
- }
65
-
66
- function parseEdge(line: string): ArchitectureEdge | null {
67
- const m = line.match(/^(\S+)\s+(.+)\s+(\S+)$/)
68
- if (!m) return null
69
- const src = m[1]!.match(SOURCE_RE)
70
- const tgt = m[3]!.match(TARGET_RE)
71
- if (!src || !tgt) return null
72
- const arrow = parseArrow(m[2]!)
73
- if (!arrow) return null
74
- return {
75
- source: { id: src[1]!, side: src[2] as ArchitectureSide },
76
- target: { id: tgt[2]!, side: tgt[1] as ArchitectureSide },
77
- label: arrow.label,
78
- hasArrowStart: arrow.hasArrowStart,
79
- hasArrowEnd: arrow.hasArrowEnd,
80
- }
81
- }
82
-
83
- /**
84
- * Parse architecture body lines (header excluded). Returns a structured body
85
- * only if EVERY non-blank, non-comment line is a modeled group, service,
86
- * junction, or edge, AND the diagram is internally consistent (no duplicate
87
- * ids, every `in` parent and every edge endpoint resolves). Otherwise returns
88
- * null (opaque fallback).
89
- */
90
- export function parseArchitectureBody(lines: string[]): ArchitectureBody | null {
91
- const groups: ArchitectureGroup[] = []
92
- const services: ArchitectureService[] = []
93
- const junctions: ArchitectureJunction[] = []
94
- const edges: ArchitectureEdge[] = []
95
- const ids = new Set<string>()
96
- const groupIds = new Set<string>()
97
- const endpointIds = new Set<string>() // services + junctions (valid edge endpoints)
98
- const pendingParents: Array<{ parent: string }> = []
99
-
100
- for (const raw of lines) {
101
- const line = raw.trim()
102
- if (!line) continue
103
- if (line.startsWith('%%')) continue
104
-
105
- const gm = line.match(GROUP_RE)
106
- if (gm) {
107
- const id = gm[1]!
108
- if (ids.has(id)) return null
109
- ids.add(id)
110
- groupIds.add(id)
111
- const icon = gm[2]?.trim() || undefined
112
- const label = normalizeText(gm[3] ?? id)
113
- const parentId = gm[4] ?? undefined
114
- if (parentId) pendingParents.push({ parent: parentId })
115
- groups.push({ id, label, icon, parentId })
116
- continue
117
- }
118
-
119
- const sm = line.match(SERVICE_RE)
120
- if (sm) {
121
- const id = sm[1]!
122
- if (ids.has(id)) return null
123
- ids.add(id)
124
- endpointIds.add(id)
125
- const icon = sm[2]?.trim() || undefined
126
- const label = normalizeText(sm[3] ?? id)
127
- const parentId = sm[4] ?? undefined
128
- if (parentId) pendingParents.push({ parent: parentId })
129
- services.push({ id, label, icon, parentId })
130
- continue
131
- }
132
-
133
- const jm = line.match(JUNCTION_RE)
134
- if (jm) {
135
- const id = jm[1]!
136
- if (ids.has(id)) return null
137
- ids.add(id)
138
- endpointIds.add(id)
139
- const parentId = jm[2] ?? undefined
140
- if (parentId) pendingParents.push({ parent: parentId })
141
- junctions.push({ id, parentId })
142
- continue
143
- }
144
-
145
- const edge = parseEdge(line)
146
- if (edge) {
147
- edges.push(edge)
148
- continue
149
- }
150
-
151
- // Unmodeled line (accTitle/accDescr/{group} boundary/anything else) → opaque.
152
- return null
153
- }
154
-
155
- // Validation: every `in` parent must be a declared group; every edge endpoint
156
- // must be a declared service or junction. The legacy parser rejects diagrams
157
- // that violate these, so a structured body must satisfy them to round-trip.
158
- for (const { parent } of pendingParents) {
159
- if (!groupIds.has(parent)) return null
160
- }
161
- for (const edge of edges) {
162
- if (!endpointIds.has(edge.source.id) || !endpointIds.has(edge.target.id)) return null
163
- }
164
-
165
- // The legacy renderer rejects an empty architecture diagram; model the same
166
- // floor so a structured body always renders.
167
- if (groups.length === 0 && services.length === 0 && junctions.length === 0) return null
168
-
169
- return { kind: 'architecture', groups, services, junctions, edges }
170
- }
171
-
172
- // ---- Serializer -------------------------------------------------------------
173
-
174
- function renderNode(keyword: 'group' | 'service', id: string, label: string, icon?: string, parentId?: string): string {
175
- const iconPart = icon ? `(${icon})` : ''
176
- const labelPart = `[${label}]`
177
- const inPart = parentId ? ` in ${parentId}` : ''
178
- return ` ${keyword} ${id}${iconPart}${labelPart}${inPart}`
179
- }
180
-
181
- function renderArrow(edge: ArchitectureEdge): string {
182
- if (edge.label !== undefined) {
183
- return `${edge.hasArrowStart ? '<' : ''}-[${edge.label}]-${edge.hasArrowEnd ? '>' : ''}`
184
- }
185
- if (edge.hasArrowStart && edge.hasArrowEnd) return '<-->'
186
- if (edge.hasArrowEnd) return '-->'
187
- if (edge.hasArrowStart) return '<--'
188
- return '--'
189
- }
190
-
191
- export function renderArchitecture(body: ArchitectureBody): string {
192
- const lines: string[] = ['architecture-beta']
193
- for (const g of body.groups) lines.push(renderNode('group', g.id, g.label, g.icon, g.parentId))
194
- for (const s of body.services) lines.push(renderNode('service', s.id, s.label, s.icon, s.parentId))
195
- for (const j of body.junctions) {
196
- lines.push(` junction ${j.id}${j.parentId ? ` in ${j.parentId}` : ''}`)
197
- }
198
- for (const e of body.edges) {
199
- lines.push(` ${e.source.id}:${e.source.side} ${renderArrow(e)} ${e.target.side}:${e.target.id}`)
200
- }
201
- return lines.join('\n') + '\n'
202
- }
203
-
204
- // ---- Mutator ----------------------------------------------------------------
205
-
206
- function cloneArchitecture(b: ArchitectureBody): ArchitectureBody {
207
- return {
208
- kind: 'architecture',
209
- groups: b.groups.map(g => ({ ...g })),
210
- services: b.services.map(s => ({ ...s })),
211
- junctions: b.junctions.map(j => ({ ...j })),
212
- edges: b.edges.map(e => ({
213
- source: { ...e.source }, target: { ...e.target },
214
- label: e.label, hasArrowStart: e.hasArrowStart, hasArrowEnd: e.hasArrowEnd,
215
- })),
216
- }
217
- }
218
-
219
- function allIds(b: ArchitectureBody): Set<string> {
220
- const s = new Set<string>()
221
- for (const g of b.groups) s.add(g.id)
222
- for (const sv of b.services) s.add(sv.id)
223
- for (const j of b.junctions) s.add(j.id)
224
- return s
225
- }
226
-
227
- const ID_RE = /^[\w-]+$/
228
-
229
- function validId(value: unknown, field: string): Result<string, MutationError> {
230
- if (typeof value !== 'string' || !ID_RE.test(value)) {
231
- return err({ code: 'INVALID_OP', message: `Architecture ${field} must match [A-Za-z0-9_-]+, got ${JSON.stringify(value)}` })
232
- }
233
- return ok(value)
234
- }
235
-
236
- function normalizeLabel(value: string, field: string): Result<string, MutationError> {
237
- if (typeof value !== 'string') return err({ code: 'INVALID_OP', message: `Architecture ${field} must be a string` })
238
- const normalized = normalizeText(value)
239
- // Labels are rendered inside [...]; a bracket would break round-trip.
240
- if (!normalized || normalized.includes('[') || normalized.includes(']')) {
241
- return err({ code: 'INVALID_OP', message: `Architecture ${field} must be non-empty and must not contain [ or ]` })
242
- }
243
- return ok(normalized)
244
- }
245
-
246
- function validSide(value: unknown): value is ArchitectureSide {
247
- return typeof value === 'string' && SIDES.has(value as ArchitectureSide)
248
- }
249
-
250
- /** Edge id convention: `<from>-><to>` (matches the flowchart edgeId idiom). */
251
- export function architectureEdgeId(e: ArchitectureEdge): string {
252
- return `${e.source.id}->${e.target.id}`
253
- }
254
-
255
- export function mutateArchitecture(body: ArchitectureBody, op: ArchitectureMutationOp): Result<ArchitectureBody, MutationError> {
256
- const next = cloneArchitecture(body)
257
-
258
- switch (op.kind) {
259
- case 'add_service': {
260
- const id = validId(op.id, 'service id')
261
- if (!id.ok) return id
262
- if (allIds(next).has(id.value)) return err({ code: 'INVALID_OP', message: `Identifier "${id.value}" already exists` })
263
- const label = normalizeLabel(op.label ?? id.value, 'service label')
264
- if (!label.ok) return label
265
- let icon: string | undefined
266
- if (op.icon !== undefined && op.icon !== null) {
267
- if (typeof op.icon !== 'string' || op.icon.includes('(') || op.icon.includes(')')) {
268
- return err({ code: 'INVALID_OP', message: 'Architecture service icon must be a string without parentheses' })
269
- }
270
- icon = op.icon.trim() || undefined
271
- }
272
- if (op.group !== undefined && op.group !== null) {
273
- const g = validId(op.group, 'group id')
274
- if (!g.ok) return g
275
- if (!next.groups.some(grp => grp.id === g.value)) return err({ code: 'GROUP_NOT_FOUND', message: `No group "${g.value}"` })
276
- next.services.push({ id: id.value, label: label.value, icon, parentId: g.value })
277
- } else {
278
- next.services.push({ id: id.value, label: label.value, icon })
279
- }
280
- break
281
- }
282
- case 'remove_service': {
283
- const idx = next.services.findIndex(s => s.id === op.id)
284
- if (idx < 0) return err({ code: 'SERVICE_NOT_FOUND', message: `No service "${op.id}"` })
285
- next.services.splice(idx, 1)
286
- // Cascade: drop every edge that touches the removed service.
287
- next.edges = next.edges.filter(e => e.source.id !== op.id && e.target.id !== op.id)
288
- break
289
- }
290
- case 'rename_service': {
291
- const from = validId(op.from, 'service id')
292
- if (!from.ok) return from
293
- const to = validId(op.to, 'service id')
294
- if (!to.ok) return to
295
- const svc = next.services.find(s => s.id === from.value)
296
- if (!svc) return err({ code: 'SERVICE_NOT_FOUND', message: `No service "${from.value}"` })
297
- if (from.value !== to.value && allIds(next).has(to.value)) {
298
- return err({ code: 'INVALID_OP', message: `Identifier "${to.value}" already exists` })
299
- }
300
- svc.id = to.value
301
- // Keep edges anchored to the renamed service.
302
- for (const e of next.edges) {
303
- if (e.source.id === from.value) e.source.id = to.value
304
- if (e.target.id === from.value) e.target.id = to.value
305
- }
306
- break
307
- }
308
- case 'set_service_label': {
309
- const svc = next.services.find(s => s.id === op.id)
310
- if (!svc) return err({ code: 'SERVICE_NOT_FOUND', message: `No service "${op.id}"` })
311
- const label = normalizeLabel(op.label, 'service label')
312
- if (!label.ok) return label
313
- svc.label = label.value
314
- break
315
- }
316
- case 'set_service_icon': {
317
- const svc = next.services.find(s => s.id === op.id)
318
- if (!svc) return err({ code: 'SERVICE_NOT_FOUND', message: `No service "${op.id}"` })
319
- if (op.icon === null) { delete svc.icon; break }
320
- if (typeof op.icon !== 'string' || op.icon.includes('(') || op.icon.includes(')')) {
321
- return err({ code: 'INVALID_OP', message: 'Architecture service icon must be a string without parentheses' })
322
- }
323
- const icon = op.icon.trim()
324
- if (!icon) return err({ code: 'INVALID_OP', message: 'Architecture service icon must be non-empty (use null to clear)' })
325
- svc.icon = icon
326
- break
327
- }
328
- case 'move_service': {
329
- const svc = next.services.find(s => s.id === op.id)
330
- if (!svc) return err({ code: 'SERVICE_NOT_FOUND', message: `No service "${op.id}"` })
331
- if (op.group === null) { delete svc.parentId; break }
332
- const g = validId(op.group, 'group id')
333
- if (!g.ok) return g
334
- if (!next.groups.some(grp => grp.id === g.value)) return err({ code: 'GROUP_NOT_FOUND', message: `No group "${g.value}"` })
335
- svc.parentId = g.value
336
- break
337
- }
338
- case 'add_group': {
339
- const id = validId(op.id, 'group id')
340
- if (!id.ok) return id
341
- if (allIds(next).has(id.value)) return err({ code: 'INVALID_OP', message: `Identifier "${id.value}" already exists` })
342
- const label = normalizeLabel(op.label ?? id.value, 'group label')
343
- if (!label.ok) return label
344
- let icon: string | undefined
345
- if (op.icon !== undefined && op.icon !== null) {
346
- if (typeof op.icon !== 'string' || op.icon.includes('(') || op.icon.includes(')')) {
347
- return err({ code: 'INVALID_OP', message: 'Architecture group icon must be a string without parentheses' })
348
- }
349
- icon = op.icon.trim() || undefined
350
- }
351
- let parentId: string | undefined
352
- if (op.parent !== undefined && op.parent !== null) {
353
- const p = validId(op.parent, 'group id')
354
- if (!p.ok) return p
355
- if (!next.groups.some(grp => grp.id === p.value)) return err({ code: 'GROUP_NOT_FOUND', message: `No group "${p.value}"` })
356
- parentId = p.value
357
- }
358
- next.groups.push({ id: id.value, label: label.value, icon, parentId })
359
- break
360
- }
361
- case 'remove_group': {
362
- const idx = next.groups.findIndex(g => g.id === op.id)
363
- if (idx < 0) return err({ code: 'GROUP_NOT_FOUND', message: `No group "${op.id}"` })
364
- // Policy: refuse to remove a non-empty group. Removing a group that still
365
- // owns services, junctions, or child groups would orphan members (the
366
- // legacy parser requires every `in <group>` to resolve), so we make the
367
- // caller move/remove members first rather than silently re-parenting or
368
- // cascade-deleting an entire subtree. Tested in agent-architecture.test.ts.
369
- const hasMembers =
370
- next.services.some(s => s.parentId === op.id) ||
371
- next.junctions.some(j => j.parentId === op.id) ||
372
- next.groups.some(g => g.parentId === op.id)
373
- if (hasMembers) return err({ code: 'INVALID_OP', message: `Group "${op.id}" is not empty; move or remove its members first` })
374
- next.groups.splice(idx, 1)
375
- break
376
- }
377
- case 'add_edge': {
378
- const from = validId(op.from, 'service id')
379
- if (!from.ok) return from
380
- const to = validId(op.to, 'service id')
381
- if (!to.ok) return to
382
- const endpoints = new Set([...next.services.map(s => s.id), ...next.junctions.map(j => j.id)])
383
- if (!endpoints.has(from.value)) return err({ code: 'SERVICE_NOT_FOUND', message: `No service/junction "${from.value}"` })
384
- if (!endpoints.has(to.value)) return err({ code: 'SERVICE_NOT_FOUND', message: `No service/junction "${to.value}"` })
385
- if (!validSide(op.fromSide)) return err({ code: 'INVALID_OP', message: `fromSide must be one of L|R|T|B, got ${JSON.stringify(op.fromSide)}` })
386
- if (!validSide(op.toSide)) return err({ code: 'INVALID_OP', message: `toSide must be one of L|R|T|B, got ${JSON.stringify(op.toSide)}` })
387
- let label: string | undefined
388
- if (op.label !== undefined && op.label !== null) {
389
- const l = normalizeLabel(op.label, 'edge label')
390
- if (!l.ok) return l
391
- label = l.value
392
- }
393
- next.edges.push({
394
- source: { id: from.value, side: op.fromSide },
395
- target: { id: to.value, side: op.toSide },
396
- label,
397
- hasArrowStart: op.hasArrowStart ?? false,
398
- hasArrowEnd: op.hasArrowEnd ?? true,
399
- })
400
- break
401
- }
402
- case 'remove_edge': {
403
- if (typeof op.index === 'number') {
404
- if (!next.edges[op.index]) return err({ code: 'EDGE_NOT_FOUND', message: `No edge at index ${op.index}` })
405
- next.edges.splice(op.index, 1)
406
- } else if (typeof op.id === 'string') {
407
- const idx = next.edges.findIndex(e => architectureEdgeId(e) === op.id)
408
- if (idx < 0) return err({ code: 'EDGE_NOT_FOUND', message: `No edge "${op.id}"` })
409
- next.edges.splice(idx, 1)
410
- } else {
411
- return err({ code: 'INVALID_OP', message: 'remove_edge requires index (number) or id (from->to)' })
412
- }
413
- break
414
- }
415
- default: {
416
- const _x: never = op
417
- return err({ code: 'INVALID_OP', message: unknownOpMessage('architecture', _x) })
418
- }
419
- }
420
-
421
- // Preserve the structured floor: an architecture diagram must keep at least
422
- // one node so it always renders.
423
- if (next.groups.length === 0 && next.services.length === 0 && next.junctions.length === 0) {
424
- return err({ code: 'INVALID_OP', message: 'Architecture diagram must keep at least one group, service, or junction' })
425
- }
426
-
427
- return ok(next)
428
- }
429
-
430
- // ---- Verifier (FamilyPlugin.verify hook) ------------------------------------
431
-
432
- export function verifyArchitecture(body: ArchitectureBody, opts: VerifyOptions): LayoutWarning[] {
433
- const cap = opts.labelCharCap ?? DEFAULT_LABEL_CHAR_CAP
434
- const warnings: LayoutWarning[] = []
435
- const overflow = (target: string, text: string) => {
436
- const w = labelOverflowWarning(target, text, cap)
437
- if (w) warnings.push(w)
438
- }
439
- if (body.groups.length === 0 && body.services.length === 0 && body.junctions.length === 0) {
440
- warnings.push({ code: 'EMPTY_DIAGRAM' })
441
- }
442
- for (const g of body.groups) overflow(g.id, g.label)
443
- for (const s of body.services) overflow(s.id, s.label)
444
- body.edges.forEach((e, i) => {
445
- // Anchor any edge whose endpoints no longer resolve (defensive; mutate keeps
446
- // these consistent, but an externally-synthesized body might not).
447
- const ids = new Set([...body.services.map(s => s.id), ...body.junctions.map(j => j.id)])
448
- if (!ids.has(e.source.id) || !ids.has(e.target.id)) {
449
- warnings.push({
450
- code: 'EDGE_MISANCHORED', edge: `edge#${i}:${architectureEdgeId(e)}`,
451
- from: ids.has(e.source.id) ? e.source.id : undefined,
452
- to: ids.has(e.target.id) ? e.target.id : undefined,
453
- })
454
- }
455
- if (e.label !== undefined) overflow(`edge#${i}:${architectureEdgeId(e)}`, e.label)
456
- })
457
- return warnings
458
- }
@@ -1,110 +0,0 @@
1
- import type {
2
- EdgeRouteCertificate,
3
- FamilyEdgeRouteCertificate,
4
- LayoutRouteCertificate,
5
- RegionContainmentCertificate,
6
- RouteCertificate,
7
- } from '../types.ts'
8
-
9
- export type LayoutCertificateProof = 'edge-route' | 'region-containment'
10
-
11
- export function layoutCertificateProof(cert: LayoutRouteCertificate): LayoutCertificateProof {
12
- if ('elementId' in cert) return regionContainmentProof(cert)
13
- return edgeRouteProof(cert)
14
- }
15
-
16
- function edgeRouteProof(cert: EdgeRouteCertificate): LayoutCertificateProof {
17
- if ('family' in cert) return familyEdgeRouteProof(cert)
18
- return flowchartEdgeRouteProof(cert)
19
- }
20
-
21
- function flowchartEdgeRouteProof(cert: RouteCertificate): LayoutCertificateProof {
22
- switch (cert.invariant) {
23
- case 'straight':
24
- case 'explained-detour':
25
- case 'bundle':
26
- case 'outer-feedback':
27
- case 'feedback-detour':
28
- case 'self-loop':
29
- case 'container-attach':
30
- case 'unverified-shape':
31
- return 'edge-route'
32
- default:
33
- return assertNever(cert)
34
- }
35
- }
36
-
37
- function familyEdgeRouteProof(cert: FamilyEdgeRouteCertificate): LayoutCertificateProof {
38
- switch (cert.family) {
39
- case 'class':
40
- case 'er':
41
- return familyBoxRouteProof(cert.invariant)
42
- case 'architecture':
43
- return architectureRouteProof(cert.invariant)
44
- case 'sequence':
45
- return sequenceRouteProof(cert.invariant)
46
- default:
47
- return assertNever(cert)
48
- }
49
- }
50
-
51
- function familyBoxRouteProof(invariant: Extract<FamilyEdgeRouteCertificate, { family: 'class' | 'er' }>['invariant']): LayoutCertificateProof {
52
- switch (invariant) {
53
- case 'orthogonal-box':
54
- case 'unverified-family-route':
55
- return 'edge-route'
56
- default:
57
- return assertNever(invariant)
58
- }
59
- }
60
-
61
- function architectureRouteProof(invariant: Extract<FamilyEdgeRouteCertificate, { family: 'architecture' }>['invariant']): LayoutCertificateProof {
62
- switch (invariant) {
63
- case 'side-anchored':
64
- case 'unverified-family-route':
65
- return 'edge-route'
66
- default:
67
- return assertNever(invariant)
68
- }
69
- }
70
-
71
- function sequenceRouteProof(invariant: Extract<FamilyEdgeRouteCertificate, { family: 'sequence' }>['invariant']): LayoutCertificateProof {
72
- switch (invariant) {
73
- case 'lifeline-message':
74
- case 'self-message':
75
- case 'unverified-family-route':
76
- return 'edge-route'
77
- default:
78
- return assertNever(invariant)
79
- }
80
- }
81
-
82
- function regionContainmentProof(cert: RegionContainmentCertificate): LayoutCertificateProof {
83
- switch (cert.family) {
84
- case 'timeline':
85
- case 'xychart':
86
- case 'pie':
87
- case 'quadrant':
88
- case 'gantt':
89
- return regionInvariantProof(cert.invariant)
90
- default:
91
- return assertNever(cert.family)
92
- }
93
- }
94
-
95
- function regionInvariantProof(invariant: RegionContainmentCertificate['invariant']): LayoutCertificateProof {
96
- switch (invariant) {
97
- case 'timeline-interval':
98
- case 'plot-contained':
99
- case 'legend-contained':
100
- case 'section-contained':
101
- case 'unverified-family-layout':
102
- return 'region-containment'
103
- default:
104
- return assertNever(invariant)
105
- }
106
- }
107
-
108
- function assertNever(value: never): never {
109
- throw new Error(`Unhandled layout certificate variant: ${JSON.stringify(value)}`)
110
- }