@diagc/cli 1.7.0 → 1.8.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.
@@ -13,6 +13,9 @@ A branching history: one lane per branch, commits along it, and the branch-offs
13
13
  - `branch.merge(src, { tag })` adds a commit that absorbs the commit `src` from another lane. It throws if `src` is on the same lane.
14
14
  - `g.stage(id, { name, from, to })` frames a span of columns across every lane. `to` defaults to `from`. Declare it after the commits it names.
15
15
  - Columns are worked out from the links: a commit sits one column after everything it follows, branches from or merges. Do not try to place commits.
16
+ - A column widens to fit what is drawn in it: a commit moves right until its tag clears the tag before it on the lane, and a stage's frame widens to its title. Use `gap` for time passing, not to make room for a label.
17
+ - Branches, commits and stages are nodes, and every node shares one id space. A commit's id defaults to `<branch id>-<n>`. `g.stage('release', …)` after `g.branch('release')` throws at that line: name the stage `release-stage`.
18
+ - Commits may share a tag: two deploys to prod are two commits tagged `deploy = prod`, and lint does not report them.
16
19
 
17
20
  ## Node types
18
21
 
@@ -8,7 +8,7 @@ This guide is for diagc {{version}}.
8
8
 
9
9
  1. Write or edit `.diagrams/src/<name>.diagram.ts`. A folder is allowed: `.diagrams/src/team/app.diagram.ts` is the diagram `team/app`.
10
10
  2. Run `diagc lint --json`. It prints `[]` and exits 0 when everything is clean. Otherwise each finding has `file`, `severity`, `code` and `message`: fix it and run again. An `error` means the diagram does not compile. A `warning` compiles but is probably a mistake, such as a misspelled type.
11
- 3. Run `diagc show <name>` to read the picture as text: the boxes, what sits inside what, and the arrows with their labels, every group open. It needs nothing else. Run `diagc publish <name>` and look at `.diagrams/static/<name>.png` to check the picture itself. It needs Chrome; set `CHROME_PATH` when none is found. The PNG shows the first plane with every group opened and only the layers that plane turns on; each further plane gets `.diagrams/static/<name>.<plane>.png`, and the other layers are on the page `.diagrams/html/<name>.html`.
11
+ 3. Run `diagc show <name>` to read the picture as text: the boxes, what sits inside what, and the arrows with their labels, every group open. It needs nothing else. Run `diagc publish <name>` and look at `.diagrams/static/<name>.png` to check the picture itself; `diagc publish` with no name publishes every diagram. It needs Chrome; set `CHROME_PATH` when none is found. The PNG shows the first plane with every group opened and only the layers that plane turns on; each further plane gets `.diagrams/static/<name>.<plane>.png`, and the other layers are on the page `.diagrams/html/<name>.html`.
12
12
 
13
13
  A person runs `diagc studio` to browse every diagram and to move boxes by hand.
14
14
 
@@ -34,7 +34,7 @@ More node options:
34
34
  | `metadata` | Free-form key and value data. |
35
35
  | `plane`, `layer` | Show the node in one plane only, or put it on a layer. |
36
36
 
37
- More relation options: `layer`, `plane` (drawn on that plane only), `description`, `id`.
37
+ More relation options: `layer`, `plane` (drawn on that plane only), `description`, `id`, and `style`, one arrow's look: `{ color: '#c0392b', line: 'dashed', shape: 'step', end: 'none' }` (`line` is `solid`, `dashed` or `dotted`; `shape` is `curved`, `straight` or `step`; `end` is `arrow`, `dot`, `square`, `diamond` or `none`; `RelationStyle` in `reference/model.md` has the rest). The file is TypeScript, so to give many arrows one look, declare the style once (`const toProd = { color: '#c0392b' }`) and pass `style: toProd` to each.
38
38
 
39
39
  ## Types and kinds
40
40
 
@@ -91,7 +91,7 @@ export default m;
91
91
 
92
92
  ## Rules that catch people
93
93
 
94
- - Calling `m.node` twice with one id is an error (`duplicate-node`). Declare a node once and keep the handle.
94
+ - Declaring an id twice throws at the second declaration, and the message names its line. Every node shares one id space, whatever declares it: `m.node`, a git branch, a commit, a stage. Declare a node once and keep the handle.
95
95
  - `m.relate(a, 'b-id', …)` does not work. Pass the handle that `m.node` returned.
96
96
  - Put what the reader must see in `name`. `description` is not drawn.
97
97
  - Keep a relation `label` to a short phrase. It is cut at about 24 characters.
@@ -17,7 +17,7 @@ A diagram is a TypeScript file under `.diagrams/src/`; `diagc` validates it, lay
17
17
 
18
18
  1. Write or edit `.diagrams/src/<name>.diagram.ts`.
19
19
  2. Run `diagc lint --json` until it prints `[]` and exits 0. Each finding has `file`, `severity`, `code` and `message`: an `error` does not compile, a `warning` compiles but is probably a mistake.
20
- 3. Run `diagc show <name>` and read the picture as text: the boxes, the nesting and the arrows with their labels. Then run `diagc publish <name>` and look at `.diagrams/static/<name>.png`. It needs Chrome (set `CHROME_PATH` when none is found); without one it writes the HTML page only.
20
+ 3. Run `diagc show <name>` and read the picture as text: the boxes, the nesting and the arrows with their labels. Then run `diagc publish <name>` and look at `.diagrams/static/<name>.png`; `diagc publish` with no name does every diagram at once. It needs Chrome (set `CHROME_PATH` when none is found); without one it writes the HTML page only.
21
21
 
22
22
  ## Rules
23
23