context-mapper 0.20.2__tar.gz

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.
@@ -0,0 +1,15 @@
1
+ ISC License
2
+
3
+ Copyright (c) 2026 Henrique Moody <henriquemoody@gmail.com>
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted, provided that the above
7
+ copyright notice and this permission notice appear in all copies.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
12
+ SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
15
+ IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
@@ -0,0 +1,211 @@
1
+ Metadata-Version: 2.4
2
+ Name: context-mapper
3
+ Version: 0.20.2
4
+ Summary: Builds an interactive context map and Mermaid diagrams from a YAML domain model.
5
+ Author-email: Henrique Moody <henriquemoody@gmail.com>
6
+ License-Expression: ISC
7
+ Project-URL: Homepage, https://github.com/henriquemoody/context-mapper
8
+ Project-URL: Documentation, https://github.com/henriquemoody/context-mapper#readme
9
+ Project-URL: Repository, https://github.com/henriquemoody/context-mapper
10
+ Project-URL: Issues, https://github.com/henriquemoody/context-mapper/issues
11
+ Keywords: domain-driven-design,context-map,mermaid,diagrams
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Documentation
21
+ Requires-Python: >=3.9
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: PyYAML
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest; extra == "dev"
27
+ Requires-Dist: ruff; extra == "dev"
28
+ Dynamic: license-file
29
+
30
+ # Context Mapper
31
+
32
+ Builds a context map: an interactive page plus static Mermaid diagrams of your domains, bounded contexts, and the dependencies between them, from two YAML files. `context-map.yml` says what the map describes; `context-map.style.yml` says how it looks.
33
+
34
+ [![Interactive context map](docs/screenshot.png)](https://henriquemoody.github.io/context-mapper/)
35
+
36
+ The interactive page built from the [`example/`](example/) model, published by GitHub Actions — click the picture, or go straight to <https://henriquemoody.github.io/context-mapper/>.
37
+
38
+ The build fails on unknown ids, duplicates, dependency cycles between bounded contexts, and unknown or invalid `context-map.style.yml` options, so a bad change breaks the build instead of the picture. It warns when two domains depend on each other.
39
+
40
+ - `src/context_mapper/build.py` validates the model and builds everything.
41
+ - `src/context_mapper/graph.py` holds the model logic: levels, lifting context dependencies to domains, and the focus walk.
42
+ - `src/context_mapper/mermaid.py` turns views into Mermaid.
43
+ - `src/context_mapper/template/` is the interactive page: `index.html`, `style.css` and `app.js`, spliced into one file when it builds.
44
+ - `example/` is a small working model you can build right away.
45
+
46
+ ## Install
47
+
48
+ Requires Python 3.9+; Mermaid itself is loaded from a CDN when you view a page, so the only build dependency is PyYAML.
49
+
50
+ ```sh
51
+ pip install git+https://github.com/henriquemoody/context-mapper.git
52
+ ```
53
+
54
+ Pin a tag (as above) or a branch, so a change here cannot break your build unannounced.
55
+
56
+ Run `context-mapper` in a directory that has a `context-map.yml` and a `context-map.style.yml`. The paths are flags:
57
+
58
+ ```sh
59
+ context-mapper --model context-map.yml --diagrams context-map.style.yml --out public
60
+ ```
61
+
62
+ While you write the model, `context-mapper serve --watch` serves the site at `http://127.0.0.1:8000/` and rebuilds it whenever you save — the same flags apply.
63
+
64
+ ## The model
65
+
66
+ ```yaml
67
+ types:
68
+ core: { name: Core } # the colors live in context-map.style.yml
69
+ supporting: { name: Supporting }
70
+ generic: { name: Generic }
71
+
72
+ clusters: # a set of domains or contexts treated together
73
+ foundations: { name: Shared Foundations }
74
+
75
+ context-map: # every id is a key, exactly once
76
+ payments: # no `domain:` key: a domain
77
+ name: Payments
78
+ type: generic
79
+ cluster: foundations # a member of the foundations cluster
80
+ downstreams: # who depends on it, and why
81
+ checkout: Charges the payment method and signals whether it went through. # a tooltip on the arrow
82
+ fulfillment: # a bare key: no comment yet
83
+ catalog: # a dependency can point at a whole domain
84
+ name: Catalog
85
+ type: core
86
+ downstreams:
87
+ checkout:
88
+ comment: Reads prices and availability at checkout time.
89
+ style: dotted # or a map, for a styled edge
90
+ checkout: # a `domain:` key makes an entry a bounded context
91
+ name: Checkout
92
+ domain: orders
93
+ description: Takes a cart and turns it into a paid order. # shows as a tooltip on the box
94
+ fulfillment:
95
+ name: Fulfillment
96
+ domain: orders
97
+ type: supporting # a context can override its domain's type
98
+ ```
99
+
100
+ Three kinds of thing, in three sections. `types` is the role vocabulary of the model: a domain or bounded context has one. `clusters` names a set of domains or contexts treated together; members join with `cluster:`, and nothing can depend on a cluster. In `context-map`, an entry with a `domain:` key is a bounded context, and any other entry is a domain — one no context points at is a single bounded context. How anything first renders comes from `defaultDisplay` in the style file: a domain or a cluster takes `expanded` (the box and what it holds), `collapsed` (the box alone), `contents` (what it holds, no box), or `hidden` (neither). A bounded context — one box with nothing inside, and a domain no context points at is one too — takes only `expanded` or `hidden`; writing `collapsed` or `contents` for one fails the build, saying why.
101
+
102
+ Every entry can carry a `description`: the interactive page shows it as a tooltip when you hover over its box, and the item's page shows it under the title.
103
+
104
+ A domain no context points at is a single bounded context with the same name.
105
+
106
+ At domain level, context dependencies are lifted to their domains and merged, and dependencies inside a domain disappear.
107
+
108
+ ## What gets built
109
+
110
+ | Output | What it is |
111
+ | --- | --- |
112
+ | `<out>/index.html` | Interactive view. Switch between bounded contexts and domains, click anything to focus on it, hide anything from the side panel, hover a box or an arrow for the details. |
113
+ | `<out>/mermaid/*.html` | One static Mermaid page per domain, per bounded context, and per named view. Click a box to jump to its page. |
114
+ | `<out>/markdown/*.md` | The same diagrams as Markdown. GitLab renders them natively, and they can go to Confluence. |
115
+
116
+ ## Run locally
117
+
118
+ ```sh
119
+ git clone https://github.com/henriquemoody/context-mapper.git
120
+ cd context-mapper
121
+ pip install .
122
+ cd example
123
+ context-mapper serve --watch
124
+ ```
125
+
126
+ `serve` builds the site and serves it at `http://127.0.0.1:8000/` (`--host` and `--port` to move it, `--out` for the directory). With `--watch`, saving the model or the style file rebuilds the site and the browser reloads the page by itself; a build that fails says why on the terminal and the page keeps showing the last good one, so a broken edit never takes the site down. The reload script is served on the wire only — the files stay exactly what a plain `context-mapper` writes, ready to publish.
127
+
128
+ ## Customize the diagrams
129
+
130
+ `context-map.style.yml` holds all of it. Its sections mirror the model's — `types`, `clusters`, `context-map` — keyed by the same ids, and take Mermaid's own classDef attributes as keys (`fill`, `stroke`, `stroke-width`, ...), so what you write is what Mermaid draws: a domain's entry styles the box around its bounded contexts, a bounded context's entry styles its own box. Any entry also takes `defaultDisplay`, saying how it first renders — a bounded context hidden that way is hidden like `hide` hides it, everywhere except its own page. The build fails if one points at an id that doesn't exist, on an attribute Mermaid doesn't know, or on a type without `fill` and `stroke`.
131
+
132
+ ```yaml
133
+ types:
134
+ core: { fill: "#dedaff", stroke: "#6631d7" } # types need fill and stroke
135
+
136
+ clusters:
137
+ foundations: { fill: "#eaf9ef", stroke: "#067429", stroke-dasharray: "4 3", defaultDisplay: collapsed }
138
+
139
+ context-map:
140
+ orders: { fill: "#eef4ff", stroke: "#305bab" } # overrides mermaid.domain_style
141
+ checkout: { fill: "#fff4f4", defaultDisplay: hidden } # a bounded context styles its own box, and can start hidden
142
+ ```
143
+
144
+ A style also fills in a readable text `color` when you don't set one.
145
+
146
+ The rest lives in the `mermaid` section. Every style in it is a map of the same Mermaid attributes as above, so `focus_style`, `domain_style` and `edge_styles` read like `types`, `clusters` and `context-map`. It styles the interactive page (`index.html`) and the static pages alike, since both are drawn with Mermaid. The interactive page uses the view `defaults` (such as `display` and `hide`) as its starting state. Unknown keys fail the build, so a typo tells you instead of doing nothing.
147
+
148
+ | Option | Values | What it does |
149
+ | --- | --- | --- |
150
+ | `direction` | `BT`, `TB`, `LR`, `RL` | Flow direction. `BT` puts upstream on top. |
151
+ | `theme` | `base`, `default`, `neutral`, `dark`, `forest` | Mermaid theme. |
152
+ | `layout` | `dagre`, `elk` | Layout engine. The HTML pages load ELK when you pick it. |
153
+ | `look` | `classic`, `handDrawn` | Mermaid look. |
154
+ | `curve` | `basis`, `linear`, `step`, `stepBefore`, ... | Line shape. Set on every edge with `linkStyle ... interpolate`, so it works with any layout. |
155
+ | `theme_variables` | map | Passed to Mermaid as-is (fonts, colors). |
156
+ | `config` | map | Any other [Mermaid config](https://mermaid.js.org/config/schema-docs/config.html), merged over the above. For example `elk.nodePlacementStrategy`. |
157
+ | `markdown_config` | map | Merged over everything for `<out>/markdown/*.md` only. GitLab's built-in Mermaid has no ELK, so the example sets `layout: dagre` here. |
158
+ | `focus_style` | map of Mermaid attributes | How the focused item is highlighted. |
159
+ | `domain_style` | map of Mermaid attributes | Style of the box around a domain's bounded contexts. A domain with its own style under `context-map` overrides it — and its type colors, when drawn as one box. |
160
+ | `edge_styles.solid`, `edge_styles.dotted` | map of Mermaid attributes | Line styles. Dotted comes from `style: dotted` on a downstream. |
161
+ | `pages` | `all`, `domains`, `contexts`, or a list of ids | Which items get their own page. |
162
+
163
+ These can be set under `defaults` and overridden per view:
164
+
165
+ | Option | Values | What it does |
166
+ | --- | --- | --- |
167
+ | `level` | `context`, `domain` | Bounded contexts inside domain boxes, or one box per domain. |
168
+ | `depth` | number, `99` for all | Hops out from the focus. |
169
+ | `dir` | `both`, `up`, `down` | Depends on, used by, or both. |
170
+ | `display` | `expanded`, `collapsed`, `contents`, `hidden`, or a map from container id to one of those | How containers first render. A single value applies to every container; a map leaves the rest to their own `defaultDisplay` in the style file. |
171
+ | `hide` | a list of ids | What the view never draws, no matter what: hiding a domain or a cluster takes everything inside it, hiding a bounded context only its own box and arrows. In the whole system that trims domains and clusters; in a domain's view it leaves out bounded contexts; in a cluster's view, members. The focus itself is never hidden. |
172
+ | `child_labels` | `true`, `false` | A collapsed container names what it holds, in the box and on each arrow that reaches it. |
173
+ | `group_by_type` | `true`, `false` | Wrap Core, Supporting and Generic in their own boxes. |
174
+
175
+ A view can also set `id`, `title`, `focus` (a domain, context or cluster id), `description` and `direction`:
176
+
177
+ ```yaml
178
+ - id: catalog-detail
179
+ title: Catalog in detail
180
+ focus: catalog
181
+ display: contents # or { foundations: contents }
182
+ hide: [search] # never draw the Search context here
183
+ direction: LR
184
+ ```
185
+
186
+ ## Use it in another repository
187
+
188
+ Keep only the model in your repository and let CI install this tool. Pin a tag so the build is reproducible; when you want a newer version, bump the tag. This GitLab Pages job is all it takes (the GitHub tag tarball works everywhere, and needs no `git` in the image):
189
+
190
+ ```yaml
191
+ pages:
192
+ image: python:3.12-slim
193
+ script:
194
+ - pip install --quiet https://github.com/henriquemoody/context-mapper/archive/refs/tags/v0.20.2.tar.gz
195
+ - context-mapper
196
+ artifacts:
197
+ paths:
198
+ - public
199
+ rules:
200
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
201
+ ```
202
+
203
+ ## Links
204
+
205
+ - `index.html#focus=checkout`: interactive, Checkout and its direct neighbors
206
+ - `index.html#focus=foundations`: interactive, the foundations cluster, opened, and what its members touch
207
+ - `index.html#level=domain&focus=orders`: interactive, the Orders domain and its neighbors
208
+ - `index.html#focus=orders&hide.fulfillment=1`: interactive, the Orders domain without the Fulfillment context
209
+ - Other hash options: `depth=1|2|99`, `dir=both|up|down`, `display.<domain id>=expanded|collapsed|contents|hidden`, `hide.<id>=1|0`
210
+ - `mermaid/checkout.html`: static diagram for Checkout
211
+ - `mermaid/index.html`: all static diagrams
@@ -0,0 +1,182 @@
1
+ # Context Mapper
2
+
3
+ Builds a context map: an interactive page plus static Mermaid diagrams of your domains, bounded contexts, and the dependencies between them, from two YAML files. `context-map.yml` says what the map describes; `context-map.style.yml` says how it looks.
4
+
5
+ [![Interactive context map](docs/screenshot.png)](https://henriquemoody.github.io/context-mapper/)
6
+
7
+ The interactive page built from the [`example/`](example/) model, published by GitHub Actions — click the picture, or go straight to <https://henriquemoody.github.io/context-mapper/>.
8
+
9
+ The build fails on unknown ids, duplicates, dependency cycles between bounded contexts, and unknown or invalid `context-map.style.yml` options, so a bad change breaks the build instead of the picture. It warns when two domains depend on each other.
10
+
11
+ - `src/context_mapper/build.py` validates the model and builds everything.
12
+ - `src/context_mapper/graph.py` holds the model logic: levels, lifting context dependencies to domains, and the focus walk.
13
+ - `src/context_mapper/mermaid.py` turns views into Mermaid.
14
+ - `src/context_mapper/template/` is the interactive page: `index.html`, `style.css` and `app.js`, spliced into one file when it builds.
15
+ - `example/` is a small working model you can build right away.
16
+
17
+ ## Install
18
+
19
+ Requires Python 3.9+; Mermaid itself is loaded from a CDN when you view a page, so the only build dependency is PyYAML.
20
+
21
+ ```sh
22
+ pip install git+https://github.com/henriquemoody/context-mapper.git
23
+ ```
24
+
25
+ Pin a tag (as above) or a branch, so a change here cannot break your build unannounced.
26
+
27
+ Run `context-mapper` in a directory that has a `context-map.yml` and a `context-map.style.yml`. The paths are flags:
28
+
29
+ ```sh
30
+ context-mapper --model context-map.yml --diagrams context-map.style.yml --out public
31
+ ```
32
+
33
+ While you write the model, `context-mapper serve --watch` serves the site at `http://127.0.0.1:8000/` and rebuilds it whenever you save — the same flags apply.
34
+
35
+ ## The model
36
+
37
+ ```yaml
38
+ types:
39
+ core: { name: Core } # the colors live in context-map.style.yml
40
+ supporting: { name: Supporting }
41
+ generic: { name: Generic }
42
+
43
+ clusters: # a set of domains or contexts treated together
44
+ foundations: { name: Shared Foundations }
45
+
46
+ context-map: # every id is a key, exactly once
47
+ payments: # no `domain:` key: a domain
48
+ name: Payments
49
+ type: generic
50
+ cluster: foundations # a member of the foundations cluster
51
+ downstreams: # who depends on it, and why
52
+ checkout: Charges the payment method and signals whether it went through. # a tooltip on the arrow
53
+ fulfillment: # a bare key: no comment yet
54
+ catalog: # a dependency can point at a whole domain
55
+ name: Catalog
56
+ type: core
57
+ downstreams:
58
+ checkout:
59
+ comment: Reads prices and availability at checkout time.
60
+ style: dotted # or a map, for a styled edge
61
+ checkout: # a `domain:` key makes an entry a bounded context
62
+ name: Checkout
63
+ domain: orders
64
+ description: Takes a cart and turns it into a paid order. # shows as a tooltip on the box
65
+ fulfillment:
66
+ name: Fulfillment
67
+ domain: orders
68
+ type: supporting # a context can override its domain's type
69
+ ```
70
+
71
+ Three kinds of thing, in three sections. `types` is the role vocabulary of the model: a domain or bounded context has one. `clusters` names a set of domains or contexts treated together; members join with `cluster:`, and nothing can depend on a cluster. In `context-map`, an entry with a `domain:` key is a bounded context, and any other entry is a domain — one no context points at is a single bounded context. How anything first renders comes from `defaultDisplay` in the style file: a domain or a cluster takes `expanded` (the box and what it holds), `collapsed` (the box alone), `contents` (what it holds, no box), or `hidden` (neither). A bounded context — one box with nothing inside, and a domain no context points at is one too — takes only `expanded` or `hidden`; writing `collapsed` or `contents` for one fails the build, saying why.
72
+
73
+ Every entry can carry a `description`: the interactive page shows it as a tooltip when you hover over its box, and the item's page shows it under the title.
74
+
75
+ A domain no context points at is a single bounded context with the same name.
76
+
77
+ At domain level, context dependencies are lifted to their domains and merged, and dependencies inside a domain disappear.
78
+
79
+ ## What gets built
80
+
81
+ | Output | What it is |
82
+ | --- | --- |
83
+ | `<out>/index.html` | Interactive view. Switch between bounded contexts and domains, click anything to focus on it, hide anything from the side panel, hover a box or an arrow for the details. |
84
+ | `<out>/mermaid/*.html` | One static Mermaid page per domain, per bounded context, and per named view. Click a box to jump to its page. |
85
+ | `<out>/markdown/*.md` | The same diagrams as Markdown. GitLab renders them natively, and they can go to Confluence. |
86
+
87
+ ## Run locally
88
+
89
+ ```sh
90
+ git clone https://github.com/henriquemoody/context-mapper.git
91
+ cd context-mapper
92
+ pip install .
93
+ cd example
94
+ context-mapper serve --watch
95
+ ```
96
+
97
+ `serve` builds the site and serves it at `http://127.0.0.1:8000/` (`--host` and `--port` to move it, `--out` for the directory). With `--watch`, saving the model or the style file rebuilds the site and the browser reloads the page by itself; a build that fails says why on the terminal and the page keeps showing the last good one, so a broken edit never takes the site down. The reload script is served on the wire only — the files stay exactly what a plain `context-mapper` writes, ready to publish.
98
+
99
+ ## Customize the diagrams
100
+
101
+ `context-map.style.yml` holds all of it. Its sections mirror the model's — `types`, `clusters`, `context-map` — keyed by the same ids, and take Mermaid's own classDef attributes as keys (`fill`, `stroke`, `stroke-width`, ...), so what you write is what Mermaid draws: a domain's entry styles the box around its bounded contexts, a bounded context's entry styles its own box. Any entry also takes `defaultDisplay`, saying how it first renders — a bounded context hidden that way is hidden like `hide` hides it, everywhere except its own page. The build fails if one points at an id that doesn't exist, on an attribute Mermaid doesn't know, or on a type without `fill` and `stroke`.
102
+
103
+ ```yaml
104
+ types:
105
+ core: { fill: "#dedaff", stroke: "#6631d7" } # types need fill and stroke
106
+
107
+ clusters:
108
+ foundations: { fill: "#eaf9ef", stroke: "#067429", stroke-dasharray: "4 3", defaultDisplay: collapsed }
109
+
110
+ context-map:
111
+ orders: { fill: "#eef4ff", stroke: "#305bab" } # overrides mermaid.domain_style
112
+ checkout: { fill: "#fff4f4", defaultDisplay: hidden } # a bounded context styles its own box, and can start hidden
113
+ ```
114
+
115
+ A style also fills in a readable text `color` when you don't set one.
116
+
117
+ The rest lives in the `mermaid` section. Every style in it is a map of the same Mermaid attributes as above, so `focus_style`, `domain_style` and `edge_styles` read like `types`, `clusters` and `context-map`. It styles the interactive page (`index.html`) and the static pages alike, since both are drawn with Mermaid. The interactive page uses the view `defaults` (such as `display` and `hide`) as its starting state. Unknown keys fail the build, so a typo tells you instead of doing nothing.
118
+
119
+ | Option | Values | What it does |
120
+ | --- | --- | --- |
121
+ | `direction` | `BT`, `TB`, `LR`, `RL` | Flow direction. `BT` puts upstream on top. |
122
+ | `theme` | `base`, `default`, `neutral`, `dark`, `forest` | Mermaid theme. |
123
+ | `layout` | `dagre`, `elk` | Layout engine. The HTML pages load ELK when you pick it. |
124
+ | `look` | `classic`, `handDrawn` | Mermaid look. |
125
+ | `curve` | `basis`, `linear`, `step`, `stepBefore`, ... | Line shape. Set on every edge with `linkStyle ... interpolate`, so it works with any layout. |
126
+ | `theme_variables` | map | Passed to Mermaid as-is (fonts, colors). |
127
+ | `config` | map | Any other [Mermaid config](https://mermaid.js.org/config/schema-docs/config.html), merged over the above. For example `elk.nodePlacementStrategy`. |
128
+ | `markdown_config` | map | Merged over everything for `<out>/markdown/*.md` only. GitLab's built-in Mermaid has no ELK, so the example sets `layout: dagre` here. |
129
+ | `focus_style` | map of Mermaid attributes | How the focused item is highlighted. |
130
+ | `domain_style` | map of Mermaid attributes | Style of the box around a domain's bounded contexts. A domain with its own style under `context-map` overrides it — and its type colors, when drawn as one box. |
131
+ | `edge_styles.solid`, `edge_styles.dotted` | map of Mermaid attributes | Line styles. Dotted comes from `style: dotted` on a downstream. |
132
+ | `pages` | `all`, `domains`, `contexts`, or a list of ids | Which items get their own page. |
133
+
134
+ These can be set under `defaults` and overridden per view:
135
+
136
+ | Option | Values | What it does |
137
+ | --- | --- | --- |
138
+ | `level` | `context`, `domain` | Bounded contexts inside domain boxes, or one box per domain. |
139
+ | `depth` | number, `99` for all | Hops out from the focus. |
140
+ | `dir` | `both`, `up`, `down` | Depends on, used by, or both. |
141
+ | `display` | `expanded`, `collapsed`, `contents`, `hidden`, or a map from container id to one of those | How containers first render. A single value applies to every container; a map leaves the rest to their own `defaultDisplay` in the style file. |
142
+ | `hide` | a list of ids | What the view never draws, no matter what: hiding a domain or a cluster takes everything inside it, hiding a bounded context only its own box and arrows. In the whole system that trims domains and clusters; in a domain's view it leaves out bounded contexts; in a cluster's view, members. The focus itself is never hidden. |
143
+ | `child_labels` | `true`, `false` | A collapsed container names what it holds, in the box and on each arrow that reaches it. |
144
+ | `group_by_type` | `true`, `false` | Wrap Core, Supporting and Generic in their own boxes. |
145
+
146
+ A view can also set `id`, `title`, `focus` (a domain, context or cluster id), `description` and `direction`:
147
+
148
+ ```yaml
149
+ - id: catalog-detail
150
+ title: Catalog in detail
151
+ focus: catalog
152
+ display: contents # or { foundations: contents }
153
+ hide: [search] # never draw the Search context here
154
+ direction: LR
155
+ ```
156
+
157
+ ## Use it in another repository
158
+
159
+ Keep only the model in your repository and let CI install this tool. Pin a tag so the build is reproducible; when you want a newer version, bump the tag. This GitLab Pages job is all it takes (the GitHub tag tarball works everywhere, and needs no `git` in the image):
160
+
161
+ ```yaml
162
+ pages:
163
+ image: python:3.12-slim
164
+ script:
165
+ - pip install --quiet https://github.com/henriquemoody/context-mapper/archive/refs/tags/v0.20.2.tar.gz
166
+ - context-mapper
167
+ artifacts:
168
+ paths:
169
+ - public
170
+ rules:
171
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
172
+ ```
173
+
174
+ ## Links
175
+
176
+ - `index.html#focus=checkout`: interactive, Checkout and its direct neighbors
177
+ - `index.html#focus=foundations`: interactive, the foundations cluster, opened, and what its members touch
178
+ - `index.html#level=domain&focus=orders`: interactive, the Orders domain and its neighbors
179
+ - `index.html#focus=orders&hide.fulfillment=1`: interactive, the Orders domain without the Fulfillment context
180
+ - Other hash options: `depth=1|2|99`, `dir=both|up|down`, `display.<domain id>=expanded|collapsed|contents|hidden`, `hide.<id>=1|0`
181
+ - `mermaid/checkout.html`: static diagram for Checkout
182
+ - `mermaid/index.html`: all static diagrams
@@ -0,0 +1,61 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "context-mapper"
7
+ version = "0.20.2"
8
+ description = "Builds an interactive context map and Mermaid diagrams from a YAML domain model."
9
+ readme = "README.md"
10
+ license = "ISC"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.9"
13
+ authors = [
14
+ { name = "Henrique Moody", email = "henriquemoody@gmail.com" },
15
+ ]
16
+ keywords = ["domain-driven-design", "context-map", "mermaid", "diagrams"]
17
+ classifiers = [
18
+ "Development Status :: 4 - Beta",
19
+ "Intended Audience :: Developers",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.9",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Topic :: Software Development :: Documentation",
27
+ ]
28
+ dependencies = [
29
+ "PyYAML",
30
+ ]
31
+
32
+ [project.optional-dependencies]
33
+ dev = [
34
+ "pytest",
35
+ "ruff",
36
+ ]
37
+
38
+ [project.urls]
39
+ Homepage = "https://github.com/henriquemoody/context-mapper"
40
+ Documentation = "https://github.com/henriquemoody/context-mapper#readme"
41
+ Repository = "https://github.com/henriquemoody/context-mapper"
42
+ Issues = "https://github.com/henriquemoody/context-mapper/issues"
43
+
44
+ [project.scripts]
45
+ context-mapper = "context_mapper.build:main"
46
+
47
+ [tool.setuptools.packages.find]
48
+ where = ["src"]
49
+
50
+ [tool.setuptools.package-data]
51
+ context_mapper = ["template/*"]
52
+
53
+ [tool.pytest.ini_options]
54
+ testpaths = ["tests"]
55
+
56
+ [tool.ruff]
57
+ target-version = "py39"
58
+
59
+ [tool.ruff.lint]
60
+ select = ["E", "W", "F", "I", "B", "UP"]
61
+ ignore = ["E501"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1 @@
1
+ """Build a context map site from a model file and a style file."""
@@ -0,0 +1,6 @@
1
+ """Run the build with `python -m context_mapper`."""
2
+
3
+ from context_mapper.build import main
4
+
5
+ if __name__ == "__main__":
6
+ main()
@@ -0,0 +1,137 @@
1
+ """Build the context map from a model file (what it describes) and a style file (how it looks).
2
+
3
+ Writes an interactive page (index.html), one static Mermaid page per view
4
+ (mermaid/*.html) and the same diagrams as Markdown (markdown/*.md), all under
5
+ the output directory.
6
+
7
+ Fails (exit 1) on unknown ids, duplicates, dependency cycles between bounded
8
+ contexts, and unknown or invalid Mermaid options, so a bad change breaks the
9
+ pipeline instead of the picture.
10
+ """
11
+ import argparse
12
+ import json
13
+ import sys
14
+ from pathlib import Path
15
+
16
+ import yaml
17
+
18
+ from . import graph, mermaid
19
+
20
+ TEMPLATE_DIR = Path(__file__).parent / "template"
21
+ DIAGRAMS_KEYS = {"types", "clusters", "context-map", "mermaid"}
22
+
23
+
24
+ class StrictLoader(yaml.SafeLoader):
25
+ """A SafeLoader that refuses duplicate keys, which would otherwise silently overwrite each other."""
26
+
27
+
28
+ def _construct_mapping(loader, node, deep=False):
29
+ loader.flatten_mapping(node)
30
+ mapping = {}
31
+ for key_node, value_node in node.value:
32
+ key = loader.construct_object(key_node, deep=deep)
33
+ if key in mapping:
34
+ raise yaml.constructor.ConstructorError(
35
+ "while constructing a mapping", node.start_mark,
36
+ f"found duplicate key {key!r}", key_node.start_mark)
37
+ mapping[key] = loader.construct_object(value_node, deep=deep)
38
+ return mapping
39
+
40
+
41
+ StrictLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _construct_mapping)
42
+
43
+
44
+ def read_yaml(path):
45
+ try:
46
+ return yaml.load(path.read_text(), Loader=StrictLoader)
47
+ except yaml.YAMLError as err:
48
+ sys.exit(f"error: {path}: {err}")
49
+
50
+
51
+ def add_input_flags(parser):
52
+ """The flags shared by the build and the serve commands."""
53
+ parser.add_argument("--model", type=Path, default=Path("context-map.yml"),
54
+ help="the model file (default: %(default)s)")
55
+ parser.add_argument("--diagrams", type=Path, default=Path("context-map.style.yml"),
56
+ help="the style file (default: %(default)s)")
57
+ parser.add_argument("--out", type=Path, default=Path("public"),
58
+ help="the directory to build into (default: %(default)s)")
59
+
60
+
61
+ def parse_args(argv=None):
62
+ parser = argparse.ArgumentParser(
63
+ prog="context-mapper",
64
+ description="Build a context map site from a model file (what it describes) "
65
+ "and a style file (how it looks).",
66
+ epilog="Run 'context-mapper serve --watch' to serve the site and rebuild it "
67
+ "whenever the YAML files change.")
68
+ add_input_flags(parser)
69
+ return parser.parse_args(argv)
70
+
71
+
72
+ def load(model_path, diagrams_path):
73
+ model = read_yaml(model_path)
74
+ diagrams = read_yaml(diagrams_path) or {}
75
+ data, errors = graph.normalize(model, diagrams)
76
+
77
+ for key in diagrams:
78
+ if key not in DIAGRAMS_KEYS:
79
+ errors.append(f"context-map.style.yml: {key}: unknown section. Known: {', '.join(sorted(DIAGRAMS_KEYS))}")
80
+
81
+ mermaid_cfg, mermaid_errors = mermaid.settings(diagrams.get("mermaid"))
82
+ errors += mermaid_errors
83
+
84
+ if not errors:
85
+ errors += mermaid.check(data, mermaid_cfg)
86
+
87
+ if errors:
88
+ for err in errors:
89
+ print(f"error: {err}", file=sys.stderr)
90
+ sys.exit(1)
91
+
92
+ # Contexts may depend on each other across domains in both directions without
93
+ # forming a context cycle. At domain level that is still worth knowing about.
94
+ cycle = graph.find_cycle(graph.level_graph(data, "domain"))
95
+ if cycle:
96
+ _, _, _, names = graph.index(data)
97
+ print("warning: domains depend on each other: " + " -> ".join(names[node] for node in cycle), file=sys.stderr)
98
+
99
+ return data, diagrams.get("mermaid")
100
+
101
+
102
+ def render_index(payload):
103
+ """The interactive page: the skeleton with the stylesheet, the script and the model spliced in."""
104
+ html = (TEMPLATE_DIR / "index.html").read_text()
105
+ css = (TEMPLATE_DIR / "style.css").read_text().strip()
106
+ js = (TEMPLATE_DIR / "app.js").read_text().replace("/*__MODEL__*/null", payload).strip()
107
+ return html.replace("/*__STYLE__*/", css).replace("/*__SCRIPT__*/", js)
108
+
109
+
110
+ def build_site(args):
111
+ """Build the whole site into args.out. Exits on missing or invalid input."""
112
+ for flag, path in (("--model", args.model), ("--diagrams", args.diagrams)):
113
+ if not path.exists():
114
+ sys.exit(f"error: {path} not found. Pass {flag} to set the path.")
115
+ data, mermaid_section = load(args.model, args.diagrams)
116
+ mermaid_cfg, _ = mermaid.settings(mermaid_section)
117
+ payload = json.dumps({**data, "mermaid": mermaid.client_settings(mermaid_cfg)}, ensure_ascii=False).replace("</", "<\\/")
118
+ html = render_index(payload)
119
+ index = args.out / "index.html"
120
+ args.out.mkdir(parents=True, exist_ok=True)
121
+ index.write_text(html)
122
+ print(f"built {index}: {len(data['domains'])} domains, "
123
+ f"{len(data['contexts'])} bounded contexts, {len(data['edges'])} dependencies")
124
+ count = mermaid.build(data, mermaid_section, args.out)
125
+ print(f"built {count} Mermaid views in {args.out}/mermaid/ and {args.out}/markdown/")
126
+
127
+
128
+ def main(argv=None):
129
+ argv = sys.argv[1:] if argv is None else list(argv)
130
+ if argv and argv[0] == "serve":
131
+ from .serve import serve
132
+ return serve(argv[1:])
133
+ build_site(parse_args(argv))
134
+
135
+
136
+ if __name__ == "__main__":
137
+ main()