119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
# Semantic lifecycle workflows
|
|
|
|
`drawio-tools` keeps editable Draw.io XML and semantic Diagram IR v2 synchronized without requiring Draw.io Desktop, a browser, network access, Python, Graphviz, or ELK.
|
|
|
|
All examples run from `scripts/` after `pnpm install --frozen-lockfile` and `task build`. Results are YAML on standard output. Commands that write files require an explicit `--output` and use an atomic temporary-file rename. Input files cannot be used as output aliases.
|
|
|
|
## Import and round trip
|
|
|
|
```bash
|
|
node dist/cli/commands.js --action import \
|
|
--file architecture.drawio \
|
|
--output architecture.yaml
|
|
|
|
node dist/cli/commands.js --action build \
|
|
--file architecture.yaml \
|
|
--output rebuilt.drawio
|
|
```
|
|
|
|
Import accepts bare `mxGraphModel` documents and multi-page `mxfile` wrappers. It preserves stable cell IDs, labels (including deliberately empty labels), parent relationships, styles, geometry, waypoints, semantic metadata, wrapper/page/model attributes, and unknown XML children in `$drawio` preservation envelopes. Dangling endpoints and ambiguous identities fail closed. Import output must use `.yaml`, `.yml`, or `.json`.
|
|
|
|
## Transactional editing
|
|
|
|
```bash
|
|
node dist/cli/commands.js --action edit \
|
|
--file architecture.yaml \
|
|
--spec ../examples/edit-batch.yaml \
|
|
--dry-run
|
|
|
|
node dist/cli/commands.js --action edit \
|
|
--file architecture.yaml \
|
|
--spec ../examples/edit-batch.yaml \
|
|
--output edited.drawio
|
|
```
|
|
|
|
A batch targets one page and supports typed `add`, `update`, `move`, `delete`, and `connect` operations. Supported preconditions are `exists`, `not-exists`, and `property-equals`, each expressed with a `type` and `id`. Unknown precondition or operation types, update payloads that attempt to change `id`, duplicate identifiers, invalid parents/endpoints, and non-cascading deletion of referenced elements fail closed and abort the entire batch. Dry runs return a preview and write nothing.
|
|
|
|
## Linked audience views
|
|
|
|
```bash
|
|
node dist/cli/commands.js --action views \
|
|
--file architecture.yaml \
|
|
--views executive,system,deployment,dataflow,security \
|
|
--output linked-views.drawio
|
|
```
|
|
|
|
Views preserve source model identifiers and provenance. A sparse view records an explicit fallback reason and modeling hint rather than pretending complete coverage. Unknown view names fail closed.
|
|
|
|
## Query and paths
|
|
|
|
```bash
|
|
node dist/cli/commands.js --action query --file architecture.yaml --kind service
|
|
node dist/cli/commands.js --action query --file architecture.yaml \
|
|
--property owner=platform --property 'production=true'
|
|
node dist/cli/commands.js --action query --file architecture.yaml \
|
|
--from client --to database
|
|
```
|
|
|
|
Queries filter by semantic kind and exact properties. `--from` plus `--to` returns a deterministic shortest directed path. Semantic operations require globally unambiguous node IDs across pages.
|
|
|
|
## Architecture policy tests
|
|
|
|
```bash
|
|
node dist/cli/commands.js --action test --file architecture.yaml
|
|
node dist/cli/commands.js --action test --file architecture.yaml \
|
|
--spec ../examples/policy-rules.yaml --strict
|
|
```
|
|
|
|
Built-in policy identifiers:
|
|
|
|
- `no-direct-internet-to-database`
|
|
- `no-cycles`
|
|
- `no-orphans`
|
|
- `every-service-has-owner`
|
|
- `production-has-observability`
|
|
- `external-dependencies-have-timeouts`
|
|
- `trust-boundaries-use-protocol`
|
|
|
|
Errors always fail. With `--strict`, warnings also fail. Unknown policy identifiers fail closed.
|
|
|
|
## Failure what-if analysis
|
|
|
|
```bash
|
|
node dist/cli/commands.js --action what-if \
|
|
--file architecture.yaml --fail api
|
|
```
|
|
|
|
The simulation follows outgoing dependencies and stops propagation at an edge with `properties.isolates_failure: true`. It never mutates the source model.
|
|
|
|
## Three-way synchronization
|
|
|
|
```bash
|
|
node dist/cli/commands.js --action sync \
|
|
--base generated-before.yaml \
|
|
--file manually-edited.yaml \
|
|
--spec generated-after.yaml \
|
|
--output synchronized.drawio
|
|
```
|
|
|
|
The base is the previous generated model, `--file` is the manually edited model, and `--spec` is the newly generated model. Synchronization preserves manual geometry/style, adds incoming identities, and reports semantic conflicts. Removed elements and pages are retained with lifecycle metadata by default; use `--prune` to remove them explicitly. Add `--dry-run` to return a preview without writing.
|
|
|
|
## Offline story
|
|
|
|
```bash
|
|
node dist/cli/commands.js --action story \
|
|
--file architecture.yaml \
|
|
--fail api \
|
|
--output architecture-story.html
|
|
```
|
|
|
|
The output is one self-contained HTML file with a restrictive Content Security Policy, escaped labels, keyboard navigation, a complete text alternative, provenance, and an optional what-if overlay. It makes no external requests and uses square corners.
|
|
|
|
## Doctor
|
|
|
|
```bash
|
|
node dist/cli/commands.js --action doctor
|
|
```
|
|
|
|
Doctor reports availability of optional local backends without launching them and confirms that the native core does not require network access.
|