Debian Codegraph @

texmf-dist/doc/latex/corasdiagram/README.md

raw
1 # corasdiagram
2
3 `corasdiagram` is a LaTeX package for authoring CORAS diagrams with reusable
4 notation macros, package-managed icons, semantic diagram environments, and
5 high-level analysis tables.
6
7 The package currently supports the five basic CORAS diagram families:
8
9 - asset diagrams
10 - threat diagrams
11 - risk diagrams
12 - treatment diagrams
13 - treatment overview diagrams
14
15 It also supports high-level analysis risk tables with CORAS header icons.
16
17 For narrow layouts such as a side-by-side `minipage` in Overleaf, the high-level
18 analysis table accepts `icon scale=<factor>` to shrink the header icon groups,
19 for example `icon scale=0.6`.
20
21 The supported TeX engines are `pdflatex` and `lualatex`.
22
23 ## Author and Contact
24
25 - Author and maintainer: Fabian Robert Smith
26 - Contact email: <[email protected]>
27 - Repository and issue tracker:
28 [github.com/smithfabian/corasdiagram](https://github.com/smithfabian/corasdiagram)
29 ([issues](https://github.com/smithfabian/corasdiagram/issues))
30
31 ## How the Project Works
32
33 This repository keeps the package source, documentation, regression tests, and
34 release tooling in one place.
35
36 Canonical sources of truth:
37
38 - [`VERSION`](VERSION) is the canonical repository release number.
39 - [`tex/latex/corasdiagram/corasdiagram-version.tex`](tex/latex/corasdiagram/corasdiagram-version.tex)
40 is the TeX runtime mirror of that version and must match `VERSION`.
41 - the `\ProvidesPackage` date in
42 [`tex/latex/corasdiagram/corasdiagram.sty`](tex/latex/corasdiagram/corasdiagram.sty)
43 must match the current release date in [`CHANGELOG.md`](CHANGELOG.md)
44 - [`assets/icons-src/`](assets/icons-src) holds the canonical icon sources.
45 - [`NOTICE`](NOTICE) records provenance and the upstream MIT notice for the
46 vendored icon sources.
47 - [`tex/latex/corasdiagram/icons/`](tex/latex/corasdiagram/icons) holds the
48 generated runtime icon assets used by the package.
49 - [`tests/corasdiagram/snapshots/`](tests/corasdiagram/snapshots) holds the
50 committed visual regression baselines.
51 - [`ctan/metadata.json`](ctan/metadata.json) holds the committed CTAN metadata
52 used by the release tooling.
53
54 Workflow map:
55
56 - normal development happens on branches and pull requests
57 - merges to `main` trigger CI and deploy the documentation site through the
58 dedicated `Pages` workflow
59 - pushed version tags matching `vX.Y.Z` trigger the `Release` workflow
60 - the release workflow verifies that the tag matches `VERSION` and that the
61 package header date matches the current `CHANGELOG.md` release date, builds
62 the release archive, publishes the GitHub release assets, and waits at the
63 `ctan-release` environment before any CTAN upload can continue
64
65 For the full contributor runbook, change checklists, and release procedure, see
66 [`CONTRIBUTING.md`](CONTRIBUTING.md).
67
68 ## Repository Layout
69
70 The package source lives in [`tex/latex/corasdiagram/`](tex/latex/corasdiagram),
71 examples live in [`examples/`](examples), the manual source lives in
72 [`docs/`](docs), semantic regression tests live in
73 [`tests/corasdiagram/`](tests/corasdiagram), and committed visual baselines
74 live in [`tests/corasdiagram/snapshots/`](tests/corasdiagram/snapshots). CTAN
75 metadata lives in [`ctan/`](ctan), and the helper scripts used by CI, Pages,
76 releases, and local development live in [`tools/`](tools).
77
78 ## Installation
79
80 For local development inside this repository, compile with:
81
82 ```bash
83 TEXINPUTS=tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error examples/corasdiagram-minimal.tex
84 ```
85
86 For a user-level TEXMF installation from a repository checkout, copy
87 [`tex/latex/corasdiagram/`](tex/latex/corasdiagram)
88 to `~/texmf/tex/latex/corasdiagram/` and refresh the TeX filename database if
89 your distribution requires it.
90
91 The release workflow also assembles a CTAN-friendly distribution bundle with
92 runtime files flattened under `tex/`, documentation under `doc/`, and the
93 top-level metadata files such as [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
94 If you are installing from that bundle manually, copy the contents of `tex/`
95 into `~/texmf/tex/latex/corasdiagram/`. Once the package is published to CTAN
96 or TeX Live, installation can happen through the normal package manager for the
97 TeX distribution.
98
99 ## Using In Your Own Project
100
101 The package can be used directly in both Overleaf projects and ordinary local
102 LaTeX projects by copying the package file together with its icon assets.
103
104 ### Overleaf
105
106 Upload these from the repository:
107
108 - [`tex/latex/corasdiagram/corasdiagram.sty`](tex/latex/corasdiagram/corasdiagram.sty)
109 - the full [`tex/latex/corasdiagram/icons/`](tex/latex/corasdiagram/icons) directory
110
111 The simplest Overleaf layout is:
112
113 ```text
114 main.tex
115 corasdiagram.sty
116 icons/
117 corasdiagram-asset.pdf
118 corasdiagram-stakeholder.pdf
119 corasdiagram-risk.pdf
120 ...
121 ```
122
123 Then load the package normally:
124
125 ```latex
126 \usepackage{corasdiagram}
127 ```
128
129 This works because the package resolves the default icon path relative to the
130 location of `corasdiagram.sty`.
131
132 If you prefer to keep the package in a subfolder, keep the `icons/` directory
133 beside the `.sty` file, for example:
134
135 ```text
136 main.tex
137 corasdiagram/
138 corasdiagram.sty
139 icons/
140 corasdiagram-asset.pdf
141 corasdiagram-stakeholder.pdf
142 ...
143 ```
144
145 and load it with:
146
147 ```latex
148 \usepackage{corasdiagram/corasdiagram}
149 ```
150
151 If your icon directory is somewhere else, set it explicitly:
152
153 ```latex
154 \usepackage[icons-path=coras-assets/icons]{corasdiagram}
155 ```
156
157 ### Local LaTeX Projects
158
159 For a normal local project outside this repository, copy the same files into
160 your project tree:
161
162 ```text
163 my-project/
164 main.tex
165 corasdiagram.sty
166 icons/
167 ```
168
169 and load the package with:
170
171 ```latex
172 \usepackage{corasdiagram}
173 ```
174
175 You can also keep the package in a subdirectory and point LaTeX at it in the
176 usual way, either by using a TEXMF tree or by loading the package through its
177 relative path:
178
179 ```latex
180 \usepackage{vendor/corasdiagram/corasdiagram}
181 ```
182
183 In that case, keep the `icons/` folder next to the `.sty` file or pass an
184 explicit `icons-path=...`.
185
186 ## Minimal Example
187
188 ```latex
189 \documentclass{article}
190 \usepackage{corasdiagram}
191
192 \begin{document}
193
194 \begin{corasassetdiagram}[x=1cm,y=1cm]
195 \corasstakeholder[
196 name=stakeholder,
197 scope=asset-scope,
198 order=1,
199 title={Stakeholder}
200 ]
201 \corasasset[
202 name=asset,
203 scope=asset-scope,
204 order=1,
205 title={Asset}
206 ]
207 \corasindirectasset[
208 name=indirect,
209 scope=asset-scope,
210 order=2,
211 title={Indirect\\Asset}
212 ]
213 \corasscope[
214 name=asset-box,
215 scope=asset-scope,
216 kind=asset-scope,
217 stakeholder=stakeholder,
218 stakeholder corner=left
219 ]
220 \corasrelates[from=asset,to=indirect]
221 \end{corasassetdiagram}
222
223 \end{document}
224 ```
225
226 ## Screenshots
227
228 The release workflow publishes the manual PDF and rendered diagram screenshots
229 to GitHub Pages and the release artifacts. The committed source tree keeps only
230 the package sources and example `.tex` files.
231
232 ## Public API
233
234 The current supported semantic package API is:
235
236 - package options: `iconset`, `icons-path`
237 - common node keys such as `perspective=before|before-after|after`
238 - diagram environments:
239 `corasassetdiagram`, `corasthreatdiagram`, `corasriskdiagram`,
240 `corastreatmentdiagram`, `corastreatmentoverviewdiagram`
241 - high-level analysis table environments:
242 `corashighlevelanalysistable`, `corashighlevelrisktable`
243 - concept node macros such as `\corasasset`, `\corasindirectasset`, `\corasstakeholder`,
244 `\corasrisk`, `\corastreatment`, and the threat/vulnerability/scenario
245 family
246 - semantic edge macros such as `\corascauses`, `\corasrelates`,
247 `\corasconcerns`, `\corasassociates`, and `\corastreats`
248 - table row macros:
249 `\corashighlevelanalysisrow`, `\corashighlevelriskrow`
250 - `\corasscope`, including `kind=asset-scope` and the stakeholder corner
251 compartment options
252
253 The `perspective` key applies to the public node macros and mounted-icon body
254 nodes. `before` uses the base icon, `before-after` uses the outlined variant,
255 and `after` uses the shaded variant.
256
257 ```latex
258 \corasasset[
259 name=baseline,
260 title={Asset},
261 perspective=before
262 ]
263 \corasindirectasset[
264 name=transition,
265 title={Indirect\\Asset},
266 perspective=before-after
267 ]
268 \corastreatment[
269 name=target,
270 title={Treatment},
271 perspective=after
272 ]
273 ```
274
275 Low-level primitives such as `\corasnode`, `\corasedge`, and `\corascontainer`
276 remain available for compatibility, but they are documented as advanced
277 interfaces rather than the preferred author-facing API.
278
279 ## Documentation
280
281 The source for the package manual is
282 [`docs/corasdiagram-doc.tex`](docs/corasdiagram-doc.tex).
283 Compile it locally with:
284
285 ```bash
286 (cd docs && TEXINPUTS=../tex/latex//: pdflatex -interaction=nonstopmode -halt-on-error corasdiagram-doc.tex)
287 ```
288
289 The workflows publish the manual PDF and rendered example screenshots as CI
290 artifacts, and the dedicated `Pages` workflow publishes the documentation site
291 to GitHub Pages.
292
293 ## Release and Deployment
294
295 The repository uses separate workflows for CI, Pages, and tagged releases:
296
297 - `CI` validates changes on pull requests and branch pushes
298 - `Pages` builds and deploys the documentation site from `main`
299 - `Release` runs only for pushed `v*` tags and handles versioned release assets
300 plus the gated CTAN publication step
301
302 The `ctan-release` environment is the approval boundary for automated CTAN
303 updates. The first CTAN submission is still expected to be done manually. For
304 the exact release, approval, and versioning procedure, see
305 [`CONTRIBUTING.md`](CONTRIBUTING.md).
306
307 ## Regression Tests
308
309 Run the semantic failure fixtures with:
310
311 ```bash
312 python3 tools/check_negative_tests.py --engine pdflatex
313 ```
314
315 Run the visual regression suite with:
316
317 ```bash
318 python3 tools/check_visual_regressions.py
319 ```
320
321 If a notation or layout change is intentional, regenerate the baselines in the
322 same change with:
323
324 ```bash
325 python3 tools/check_visual_regressions.py --update
326 ```
327
328 ## Anchor Editor
329
330 For interactive tuning of the symbol-table anchor maps, run:
331
332 ```bash
333 python3 tools/coras_anchor_editor.py
334 ```
335
336 This starts a local browser-based editor that lets you drag the directional
337 anchors for `asset`, `stakeholder`, the threat variants, and `vulnerability`,
338 then save the values directly back into
339 [`tex/latex/corasdiagram/corasdiagram.sty`](tex/latex/corasdiagram/corasdiagram.sty).
340
341 The app also shows read-only previews for `scenario`, `treatment`, `incident`,
342 and `risk`, using locally rebuilt images from the anchor regression fixture.
343
344 ## Contributing
345
346 Contribution guidelines are in [`CONTRIBUTING.md`](CONTRIBUTING.md).
347 Please open issues for notation bugs, layout regressions, documentation gaps,
348 or feature ideas. The public issue labels include `good first issue`,
349 `help wanted`, `documentation`, `notation`, `layout`, and `ci`.
350
351 ## License
352
353 This project is licensed under the MIT license. See [`LICENSE`](LICENSE).
354 The vendored CORAS icon sources also carry upstream MIT attribution and
355 provenance in [`NOTICE`](NOTICE).