context-mapper 0.20.2__py3-none-any.whl

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,47 @@
1
+ :root {
2
+ --bg: #ffffff; --panel: #f7f7f7; --ink: #1a1a1a; --muted: #595959;
3
+ --line: #e7e7e7; --edge: #313131; --accent: #305bab;
4
+ }
5
+ * { box-sizing: border-box; }
6
+ body { margin: 0; font: 15px/1.45 system-ui, -apple-system, "Segoe UI", sans-serif; color: var(--ink); background: var(--bg); }
7
+ header { display: flex; flex-wrap: wrap; gap: 12px 20px; align-items: center; padding: 12px 16px; border-bottom: 1px solid var(--line); }
8
+ header h1 { font-size: 18px; margin: 0 8px 0 0; }
9
+ label { display: inline-flex; gap: 6px; align-items: center; color: var(--muted); }
10
+ select, button { font: inherit; padding: 4px 8px; border: 1px solid #b0b0b0; border-radius: 6px; background: #fff; color: var(--ink); }
11
+ button { cursor: pointer; }
12
+ main { display: grid; grid-template-columns: 1fr 320px; height: calc(100vh - 58px); }
13
+ #graph { min-height: 400px; overflow: auto; padding: 16px; }
14
+ #graph svg { max-width: 100%; height: auto; }
15
+ #graph a, #graph a *, #graph .clickable, #graph .clickable * { cursor: pointer; }
16
+ /* Hovering an arrow lights it up and dims the rest. The wide transparent copy is what catches the mouse. */
17
+ #graph .edge-hit { fill: none; stroke: transparent; stroke-width: 14px; pointer-events: stroke; cursor: pointer; }
18
+ #graph svg.hovering .flowchart-link:not(.edge-on) { opacity: .15; }
19
+ #graph svg.hovering .edgeLabel:not(.edge-on) { opacity: .25; }
20
+ #graph svg.hovering .box:not(.node-on) { opacity: .45; }
21
+ #graph .flowchart-link.edge-on { stroke: var(--accent) !important; stroke-width: 3.5px !important; }
22
+ #graph .flowchart-link, #graph .box, #graph .edgeLabel { transition: opacity .12s; }
23
+ #tip { display: none; position: fixed; z-index: 10; max-width: 320px; padding: 8px 10px; border-radius: 6px; background: var(--ink); color: #fff; font-size: 13px; pointer-events: none; box-shadow: 0 2px 8px rgba(0,0,0,.25); }
24
+ #tip p { margin: 0; }
25
+ #tip p + p { margin-top: 6px; }
26
+ aside { border-left: 1px solid var(--line); background: var(--panel); padding: 16px; overflow: auto; }
27
+ aside h2 { font-size: 20px; margin: 0 0 4px; }
28
+ aside h3 { font-size: 13px; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); margin: 18px 0 6px; }
29
+ aside ul { margin: 0; padding-left: 18px; }
30
+ aside a { color: var(--accent); text-decoration: none; cursor: pointer; }
31
+ aside a:hover { text-decoration: underline; }
32
+ .chip { display: inline-block; padding: 1px 8px; border-radius: 10px; font-size: 12px; border: 1px solid; }
33
+ .legend { display: flex; flex-wrap: wrap; gap: 6px; }
34
+ .hint { color: var(--muted); font-size: 13px; }
35
+ /* The panel's "Show & hide" form: a name on the left, its control on the right. */
36
+ #display h4 { font-size: 12px; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); margin: 14px 0 4px; }
37
+ #display .row { display: flex; justify-content: space-between; align-items: center; gap: 8px; padding: 2px 0; font-size: 13px; }
38
+ #display .row .name { color: var(--ink); }
39
+ #display .row select { font-size: 13px; padding: 2px 6px; }
40
+ #display .row.off .name { color: var(--muted); }
41
+ #display .cluster { border-bottom: 2px dashed var(--muted); }
42
+ aside .toggle { color: var(--muted); font-size: 13px; }
43
+ aside .toggle::before { content: "· "; color: var(--line); }
44
+ @media (max-width: 800px) {
45
+ main { grid-template-columns: 1fr; grid-template-rows: 60vh auto; height: auto; }
46
+ aside { border-left: 0; border-top: 1px solid var(--line); }
47
+ }
@@ -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,15 @@
1
+ context_mapper/__init__.py,sha256=jrE4ccjNmdHa3IhgT6sMizGq7PRjWu-e6jIrOq648Zo,67
2
+ context_mapper/__main__.py,sha256=XMDYjlf0PhFejEvIhgF59qmapcI1doLvE09PD4yknjo,131
3
+ context_mapper/build.py,sha256=azlEU0y_go-PXXuEAifjzs0U461T9k_FCgs2ktvNXeI,5336
4
+ context_mapper/graph.py,sha256=_jxJb7lmFfK5RxD8ksfLauvQPVftKo70FpphClth7Do,21401
5
+ context_mapper/mermaid.py,sha256=pn4iZ0B2G9w06SwvB6Uu-xvVz0iHaYmojFLaYyBJdQA,30531
6
+ context_mapper/serve.py,sha256=cLvWqJV7FM0E9skMWWG8nbPjLEk9vVVDBnCP9XW-pPc,6340
7
+ context_mapper/template/app.js,sha256=oqwqEx6_ov-MFcwfJZwtbopKzPdFXJJAI8NlS3K27iE,29119
8
+ context_mapper/template/index.html,sha256=RFzAHb_BoHogPlkY1mETGujjYdth_h4L1nAuc6T396s,1161
9
+ context_mapper/template/style.css,sha256=04S2riMZQPyydf9u6O0hTb8PMmKXrszsslUNmgoH-is,3372
10
+ context_mapper-0.20.2.dist-info/licenses/LICENSE,sha256=zE4wPzJJtZeY5In13bhdbo7J4neWz-3RWxhwahO5W7k,771
11
+ context_mapper-0.20.2.dist-info/METADATA,sha256=rWH_3FR2t5UuzUwTCA5CqNT8CQvo53YH4gcYr-R8WvY,13124
12
+ context_mapper-0.20.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
13
+ context_mapper-0.20.2.dist-info/entry_points.txt,sha256=eKy6x6HLEpV8bBiD9ogiHFDM4AmjJi8V6D49vgGyWYo,61
14
+ context_mapper-0.20.2.dist-info/top_level.txt,sha256=U9YyEBhWiYiOiR8j-Tuy0BDIqkh2tP2eyYrEdGUwovA,15
15
+ context_mapper-0.20.2.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ context-mapper = context_mapper.build:main
@@ -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 @@
1
+ context_mapper