merrow 0.1.1__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.
- merrow/__init__.py +1 -0
- merrow/apply.py +116 -0
- merrow/archive.py +79 -0
- merrow/browser.py +72 -0
- merrow/bundle.py +69 -0
- merrow/cli.py +418 -0
- merrow/compose.py +148 -0
- merrow/config.py +110 -0
- merrow/convert/__init__.py +11 -0
- merrow/convert/opc.py +42 -0
- merrow/convert/pdf.py +136 -0
- merrow/convert/pptx.py +201 -0
- merrow/convert/svg.py +285 -0
- merrow/convert/visio.py +556 -0
- merrow/defaults.yaml +171 -0
- merrow/graph.py +174 -0
- merrow/lint/__init__.py +1 -0
- merrow/lint/diagram_check.py +807 -0
- merrow/lint/icons.py +32 -0
- merrow/model.py +115 -0
- merrow/naming.py +79 -0
- merrow/npm/package-lock.json +1156 -0
- merrow/npm/package.json +7 -0
- merrow/objects.py +143 -0
- merrow/objects.yaml +54 -0
- merrow/packs/starter.LICENSE +201 -0
- merrow/packs/starter.json +1 -0
- merrow/patterns.py +119 -0
- merrow/patterns.yaml +32 -0
- merrow/post.py +115 -0
- merrow/proc.py +58 -0
- merrow/profile.py +348 -0
- merrow/profiles/aws-dark.tokens.json +8 -0
- merrow/profiles/aws.tokens.json +13 -0
- merrow/profiles/house-dark.tokens.json +6 -0
- merrow/profiles/house.tokens.json +51 -0
- merrow/profiles.yaml +219 -0
- merrow/read/__init__.py +27 -0
- merrow/read/dot.py +81 -0
- merrow/read/drawio.py +198 -0
- merrow/read/excalidraw.py +88 -0
- merrow/read/pdf.py +693 -0
- merrow/read/pptx.py +155 -0
- merrow/read/structurizr.py +78 -0
- merrow/read/visio.py +174 -0
- merrow/render.py +147 -0
- merrow/skill/SKILL.md +46 -0
- merrow/sources/__init__.py +1 -0
- merrow/sources/detect.py +169 -0
- merrow/sources/fetch.py +77 -0
- merrow/sources/lock.py +58 -0
- merrow/sources.lock.yaml +87 -0
- merrow/sources.yaml +432 -0
- merrow/spec.py +123 -0
- merrow/write.py +289 -0
- merrow-0.1.1.dist-info/METADATA +110 -0
- merrow-0.1.1.dist-info/RECORD +60 -0
- merrow-0.1.1.dist-info/WHEEL +4 -0
- merrow-0.1.1.dist-info/entry_points.txt +2 -0
- merrow-0.1.1.dist-info/licenses/LICENSE +73 -0
merrow/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""merrow: diagram automation on Mermaid."""
|
merrow/apply.py
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
"""Hand-written Mermaid in a profile's look: its two managed regions.
|
|
2
|
+
|
|
3
|
+
An author writes the body, naming an object as `id:::aws-msk` (the object id
|
|
4
|
+
with dots as hyphens). apply sets the frontmatter, expands a bare object node
|
|
5
|
+
into the profile's label form, and rewrites the class block between the
|
|
6
|
+
markers. Each `:::` stays, so re-running is a no-op and picks up object edits.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import re
|
|
10
|
+
from collections.abc import Mapping
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from merrow.graph import Node
|
|
14
|
+
from merrow.lint.diagram_check import diagram_type, split_front
|
|
15
|
+
from merrow.objects import L1Object
|
|
16
|
+
from merrow.profile import Profile
|
|
17
|
+
from merrow.render import FENCE
|
|
18
|
+
from merrow.write import misfits, profile_label
|
|
19
|
+
|
|
20
|
+
BEGIN = "%% merrow:begin"
|
|
21
|
+
END = "%% merrow:end"
|
|
22
|
+
_REF = re.compile(r"^(?P<id>[A-Za-z_]\w*)(?P<label>[\[(].*[\])])?:::(?P<ref>[\w-]+)$")
|
|
23
|
+
_SUBGRAPH = re.compile(r"^subgraph\s+([A-Za-z_]\w*)")
|
|
24
|
+
# Mermaid kinds that take the frontmatter alone: they can name no object.
|
|
25
|
+
_FRONT_ONLY = ("sequenceDiagram", "erDiagram", "classDiagram")
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _indent(line: str) -> str:
|
|
29
|
+
return line[: len(line) - len(line.lstrip())]
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def apply(source: str, profile: Profile, by_ref: Mapping[str, L1Object]) -> str:
|
|
33
|
+
"""Return one diagram with the profile's frontmatter and class block.
|
|
34
|
+
|
|
35
|
+
`by_ref` is `objects.by_class_name` of the object library.
|
|
36
|
+
|
|
37
|
+
Raises:
|
|
38
|
+
ValueError: An object styles as a class the profile doesn't define.
|
|
39
|
+
"""
|
|
40
|
+
_, body = split_front(source)
|
|
41
|
+
flow = diagram_type(body)[0] in ("flowchart", "graph")
|
|
42
|
+
kept, managed = [], False
|
|
43
|
+
for line in body.splitlines():
|
|
44
|
+
if line.strip() in (BEGIN, END):
|
|
45
|
+
managed = line.strip() == BEGIN
|
|
46
|
+
elif not managed:
|
|
47
|
+
kept.append(line)
|
|
48
|
+
while kept and not kept[-1].strip():
|
|
49
|
+
kept.pop()
|
|
50
|
+
|
|
51
|
+
styles: dict[str, list[str]] = {}
|
|
52
|
+
subgraphs, out = [], []
|
|
53
|
+
for line in kept:
|
|
54
|
+
match = _REF.match(line.strip())
|
|
55
|
+
known = by_ref.get(match["ref"]) if match else None
|
|
56
|
+
if match and known is not None:
|
|
57
|
+
if problems := misfits(profile, known):
|
|
58
|
+
raise ValueError("; ".join(problems))
|
|
59
|
+
node = Node(match["id"], known.label, known.subtitle)
|
|
60
|
+
label = match["label"] or profile_label(profile, node, known.shape)
|
|
61
|
+
line = f"{_indent(line)}{match['id']}{label}:::{match['ref']}"
|
|
62
|
+
styles.setdefault(known.style, []).append(match["id"])
|
|
63
|
+
if found := _SUBGRAPH.match(line.strip()):
|
|
64
|
+
subgraphs.append(found.group(1))
|
|
65
|
+
out.append(line)
|
|
66
|
+
|
|
67
|
+
if flow:
|
|
68
|
+
indent = next((_indent(ln) for ln in out[1:] if ln.strip()), " ")
|
|
69
|
+
order = [ln.split()[1] for ln in profile.class_lines]
|
|
70
|
+
block = [
|
|
71
|
+
f"class {','.join(styles[name])} {name}"
|
|
72
|
+
for name in sorted(styles, key=order.index)
|
|
73
|
+
]
|
|
74
|
+
block += [*profile.class_lines]
|
|
75
|
+
block += [f"style {name} {profile.boundary}" for name in subgraphs]
|
|
76
|
+
out += [f"{indent}{BEGIN}", *(indent + ln for ln in block), f"{indent}{END}"]
|
|
77
|
+
front = profile.fronts["flowchart" if flow else "other"]
|
|
78
|
+
return f"{front}\n" + "\n".join(out) + "\n"
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def managed(source: str, by_ref: Mapping[str, L1Object]) -> bool:
|
|
82
|
+
"""Return whether a diagram takes the profile.
|
|
83
|
+
|
|
84
|
+
It does when it names an object, carries the class block, or is a sequence,
|
|
85
|
+
ER or class diagram, which can name no object.
|
|
86
|
+
"""
|
|
87
|
+
names = {m["ref"] for ln in source.splitlines() if (m := _REF.match(ln.strip()))}
|
|
88
|
+
front_only = diagram_type(split_front(source)[1])[0] in _FRONT_ONLY
|
|
89
|
+
return BEGIN in source or bool(names & set(by_ref)) or front_only
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def apply_file(path: Path, profile: Profile, by_ref: Mapping[str, L1Object]) -> bool:
|
|
93
|
+
"""Apply the profile to a `.mmd` file, or to each managed fence in Markdown.
|
|
94
|
+
|
|
95
|
+
A fence is managed once it names an object or carries the class block. A
|
|
96
|
+
sequence, ER or class diagram is always managed: it can name no object.
|
|
97
|
+
Returns whether the file changed.
|
|
98
|
+
|
|
99
|
+
Raises:
|
|
100
|
+
ValueError: An object styles as a class the profile doesn't define.
|
|
101
|
+
"""
|
|
102
|
+
text = path.read_text(encoding="utf-8")
|
|
103
|
+
if path.suffix != ".md":
|
|
104
|
+
new = apply(text, profile, by_ref)
|
|
105
|
+
else:
|
|
106
|
+
|
|
107
|
+
def one(fence: re.Match[str]) -> str:
|
|
108
|
+
body = fence.group(1)
|
|
109
|
+
if not managed(body, by_ref):
|
|
110
|
+
return fence.group(0)
|
|
111
|
+
return fence.group(0).replace(body, apply(body, profile, by_ref), 1)
|
|
112
|
+
|
|
113
|
+
new = FENCE.sub(one, text)
|
|
114
|
+
if new != text:
|
|
115
|
+
path.write_text(new, encoding="utf-8", newline="\n")
|
|
116
|
+
return new != text
|
merrow/archive.py
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
"""Read the files in a download, whatever it ships as: a directory, zip or tarball.
|
|
2
|
+
|
|
3
|
+
Every converter selects its files with a regex on the path inside the download,
|
|
4
|
+
so a new release that moves or renames folders is a config change, never code.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import re
|
|
8
|
+
import tarfile
|
|
9
|
+
import zipfile
|
|
10
|
+
from collections.abc import Iterator
|
|
11
|
+
from dataclasses import dataclass
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True, slots=True)
|
|
16
|
+
class Member:
|
|
17
|
+
"""One file in a download.
|
|
18
|
+
|
|
19
|
+
Attributes:
|
|
20
|
+
path: The `/`-separated path inside the download.
|
|
21
|
+
data: The bytes, or None when the file is over the size cap and unread.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
path: str
|
|
25
|
+
data: bytes | None
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def members(
|
|
29
|
+
source: Path,
|
|
30
|
+
pattern: re.Pattern[str],
|
|
31
|
+
max_bytes: int,
|
|
32
|
+
ignore: re.Pattern[str] | None = None,
|
|
33
|
+
) -> Iterator[Member]:
|
|
34
|
+
"""Yield every file under `source` whose path matches `pattern`, sorted by path.
|
|
35
|
+
|
|
36
|
+
A plain file is one member, named by its file name.
|
|
37
|
+
|
|
38
|
+
A path matching `ignore` is left out, such as the `__MACOSX/` resource forks
|
|
39
|
+
a zip made on a Mac carries.
|
|
40
|
+
|
|
41
|
+
A file larger than `max_bytes` comes back with no data and is never read, so
|
|
42
|
+
a bad download can't fill memory.
|
|
43
|
+
|
|
44
|
+
Raises:
|
|
45
|
+
ValueError: `source` doesn't exist.
|
|
46
|
+
"""
|
|
47
|
+
if not source.exists():
|
|
48
|
+
raise ValueError(f"{source} is not a file, directory, zip or tarball")
|
|
49
|
+
if source.is_dir():
|
|
50
|
+
for path in sorted(p for p in source.rglob("*") if p.is_file()):
|
|
51
|
+
name = path.relative_to(source).as_posix()
|
|
52
|
+
if _wanted(name, pattern, ignore):
|
|
53
|
+
small = path.stat().st_size <= max_bytes
|
|
54
|
+
yield Member(name, path.read_bytes() if small else None)
|
|
55
|
+
elif zipfile.is_zipfile(source):
|
|
56
|
+
with zipfile.ZipFile(source) as archive:
|
|
57
|
+
for info in sorted(archive.infolist(), key=lambda i: i.filename):
|
|
58
|
+
if not info.is_dir() and _wanted(info.filename, pattern, ignore):
|
|
59
|
+
small = info.file_size <= max_bytes
|
|
60
|
+
yield Member(info.filename, archive.read(info) if small else None)
|
|
61
|
+
elif tarfile.is_tarfile(source):
|
|
62
|
+
with tarfile.open(source) as archive:
|
|
63
|
+
files = sorted(
|
|
64
|
+
(m for m in archive.getmembers() if m.isfile()), key=lambda m: m.name
|
|
65
|
+
)
|
|
66
|
+
for info in files:
|
|
67
|
+
handle = archive.extractfile(info)
|
|
68
|
+
if handle and _wanted(info.name, pattern, ignore):
|
|
69
|
+
small = info.size <= max_bytes
|
|
70
|
+
yield Member(info.name, handle.read() if small else None)
|
|
71
|
+
elif _wanted(source.name, pattern, ignore):
|
|
72
|
+
small = source.stat().st_size <= max_bytes
|
|
73
|
+
yield Member(source.name, source.read_bytes() if small else None)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _wanted(
|
|
77
|
+
path: str, pattern: re.Pattern[str], ignore: re.Pattern[str] | None
|
|
78
|
+
) -> bool:
|
|
79
|
+
return bool(pattern.search(path)) and not (ignore and ignore.search(path))
|
merrow/browser.py
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
"""The browser every laid-out page runs in: render, post-render and lint."""
|
|
2
|
+
|
|
3
|
+
import functools
|
|
4
|
+
import subprocess
|
|
5
|
+
import sys
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from merrow import config, proc
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class BrowserError(RuntimeError):
|
|
12
|
+
"""No browser could be installed or launched."""
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@functools.cache
|
|
16
|
+
def _install(name: str, timeout: float) -> str:
|
|
17
|
+
"""Return "" once playwright has `name`, else its error. A no-op when installed."""
|
|
18
|
+
result = proc.run(
|
|
19
|
+
[sys.executable, "-m", "playwright", "install", name], timeout=timeout
|
|
20
|
+
)
|
|
21
|
+
return "" if result.returncode == 0 else proc.tail(result)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _system_libraries(name: str, timeout: float) -> str:
|
|
25
|
+
"""Return "" once apt has the libraries `name` needs, else why not.
|
|
26
|
+
|
|
27
|
+
Runs on the terminal, so the sudo playwright starts can ask for a password.
|
|
28
|
+
"""
|
|
29
|
+
argv = [sys.executable, "-m", "playwright", "install-deps", name]
|
|
30
|
+
try:
|
|
31
|
+
code = subprocess.run(argv, timeout=timeout, check=False).returncode # noqa: S603
|
|
32
|
+
except subprocess.TimeoutExpired:
|
|
33
|
+
return f"timed out after {timeout:g} s"
|
|
34
|
+
return "" if code == 0 else f"exit {code}"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def ensure(settings: Any, deps: bool = False) -> None:
|
|
38
|
+
"""Install the browser build this playwright release pins, with its system libraries when `deps`.
|
|
39
|
+
|
|
40
|
+
Raises:
|
|
41
|
+
BrowserError: The install failed, for example offline or, with `deps`, without sudo.
|
|
42
|
+
"""
|
|
43
|
+
timeout = config.limits(settings).install_timeout_seconds
|
|
44
|
+
name = str(settings.get("browser"))
|
|
45
|
+
failed = _install(name, timeout)
|
|
46
|
+
if not failed and deps:
|
|
47
|
+
failed = _system_libraries(name, timeout)
|
|
48
|
+
if failed:
|
|
49
|
+
raise BrowserError(f"playwright install {name}: {failed}")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def launch(driver: Any, settings: Any) -> Any:
|
|
53
|
+
"""Return a launched browser: playwright's pinned build, else the host's Chrome.
|
|
54
|
+
|
|
55
|
+
The pinned build lays text out the same on every host, so it comes first.
|
|
56
|
+
|
|
57
|
+
Raises:
|
|
58
|
+
BrowserError: Neither starts.
|
|
59
|
+
"""
|
|
60
|
+
# Imported here so the steps that need no page run without playwright.
|
|
61
|
+
from playwright.sync_api import Error
|
|
62
|
+
|
|
63
|
+
try:
|
|
64
|
+
ensure(settings)
|
|
65
|
+
return driver.chromium.launch()
|
|
66
|
+
except (BrowserError, Error) as pinned:
|
|
67
|
+
try:
|
|
68
|
+
return driver.chromium.launch(channel="chrome")
|
|
69
|
+
except Error as chrome:
|
|
70
|
+
raise BrowserError(
|
|
71
|
+
f"no browser to render with: {pinned}; Chrome: {chrome}"
|
|
72
|
+
) from chrome
|
merrow/bundle.py
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
"""The Mermaid bundle render and lint run in a browser page.
|
|
2
|
+
|
|
3
|
+
npm/package-lock.json pins it and Renovate keeps it current. merrow downloads
|
|
4
|
+
the tarball the lock names, checks it against the lock's sha512 integrity, and
|
|
5
|
+
caches the bundle file from it, so no Node.js install is needed.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import base64
|
|
9
|
+
import hashlib
|
|
10
|
+
import io
|
|
11
|
+
import json
|
|
12
|
+
import tarfile
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
from merrow import config
|
|
17
|
+
from merrow.sources.fetch import download, write_atomic
|
|
18
|
+
|
|
19
|
+
LOCKFILE = Path(__file__).parent / "npm" / "package-lock.json"
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class BundleError(RuntimeError):
|
|
23
|
+
"""The pinned bundle could not be fetched, or didn't match the lock."""
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _pin(package: str) -> dict[str, str]:
|
|
27
|
+
"""Return the lock's `version`, `resolved` and `integrity` for a package."""
|
|
28
|
+
lock = json.loads(LOCKFILE.read_text(encoding="utf-8"))
|
|
29
|
+
return lock["packages"][f"node_modules/{package}"]
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def version(settings: Any) -> str:
|
|
33
|
+
"""Return the Mermaid version the lock pins."""
|
|
34
|
+
return _pin(settings.get("render")["bundle"]["package"])["version"]
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _integrity(data: bytes) -> str:
|
|
38
|
+
return "sha512-" + base64.b64encode(hashlib.sha512(data).digest()).decode("ascii")
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def path(settings: Any) -> Path:
|
|
42
|
+
"""Return the cached bundle file, downloading the pinned tarball when missing.
|
|
43
|
+
|
|
44
|
+
Raises:
|
|
45
|
+
BundleError: The tarball doesn't match the lock, or lacks the bundle file.
|
|
46
|
+
"""
|
|
47
|
+
wanted = settings.get("render")["bundle"]
|
|
48
|
+
pin = _pin(wanted["package"])
|
|
49
|
+
member = str(wanted["file"])
|
|
50
|
+
target = (
|
|
51
|
+
config.cache_dir(settings)
|
|
52
|
+
/ "bundle"
|
|
53
|
+
/ f"{wanted['package']}-{pin['version']}"
|
|
54
|
+
/ Path(member).name
|
|
55
|
+
)
|
|
56
|
+
if target.is_file():
|
|
57
|
+
return target
|
|
58
|
+
data = download(pin["resolved"], config.limits(settings))
|
|
59
|
+
if _integrity(data) != pin["integrity"]:
|
|
60
|
+
raise BundleError(f"{pin['resolved']} doesn't match the lock's integrity")
|
|
61
|
+
with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as archive:
|
|
62
|
+
try:
|
|
63
|
+
handle = archive.extractfile(member)
|
|
64
|
+
except KeyError as missing:
|
|
65
|
+
raise BundleError(f"{pin['resolved']} has no {member}") from missing
|
|
66
|
+
if handle is None:
|
|
67
|
+
raise BundleError(f"{pin['resolved']}: {member} is not a file")
|
|
68
|
+
write_atomic(target, handle.read())
|
|
69
|
+
return target
|