Migrate project towards cutting edge 2025 tooling and methodology

.github/workflows/main.yml

@@ -21,19 +21,19 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        # https://endoflife.date/python
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
-    # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+      # https://github.com/actions/checkout
+      - uses: actions/checkout@v6
+      # https://docs.astral.sh/uv/guides/integration/github/#multiple-python-versions
+      # https://github.com/astral-sh/setup-uv
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install Poetry
-        run: pip install poetry
-      - name: Install dependencies
-        run: poetry install --with dev
+      - name: Install the project
+        run: uv sync --locked --dev
       - name: Run tests
-        run: poetry run pytest
+        run: uv run pytest tests

.gitignore

@@ -132,3 +132,5 @@ devbox.lock
 
 # zed
 .zed
+
+sbom.json

CONTRIBUTING.md

@@ -7,21 +7,22 @@ Please read those before starting an issue or a pull request.
 
 Specific PyTM design and development issues, bugs, and feature requests are maintained by GitHub Issues.
 
-*Please do not post installation, build, usage, or modeling questions, or other requests for help to Issues.*
+_Please do not post installation, build, usage, or modeling questions, or other requests for help to Issues._
 Use the [PyTM-users list](https://groups.google.com/forum/#!forum/pytm-users) instead.
 This helps developers maintain a clear, uncluttered, and efficient view of the state of PyTM.
 See the chapter [PyTM-users](#PyTM-users) below for guidance on posting to the users list.
 
 When reporting an issue, it's most helpful to provide the following information, where applicable:
-* How does the problem look like and what steps reproduce it?
-* Can you reproduce it using the latest [master](https://github.com/izar/pytm/tree/master)?
-* What is your running environment? In particular:
-	* OS,
-	* Python version,
-	* Dot or PlantUML version, if relevant,
-	* Your model file, if possible.
-* **What have you already tried** to solve the problem? How did it fail? Are there any other issues related to yours?
-* If the bug is a crash, provide the backtrace (usually printed by PyTM).
+
+- How does the problem look like and what steps reproduce it?
+- Can you reproduce it using the latest [master](https://github.com/izar/pytm/tree/master)?
+- What is your running environment? In particular:
+  - OS,
+  - Python version,
+  - Dot or PlantUML version, if relevant,
+  - Your model file, if possible.
+- **What have you already tried** to solve the problem? How did it fail? Are there any other issues related to yours?
+- If the bug is a crash, provide the backtrace (usually printed by PyTM).
 
 If only a small portion of the code/log is relevant to your issue, you may paste it directly into the post, preferably using Markdown syntax for code block: triple backtick ( \`\`\` ) to open/close a block.
 In other cases (multiple files, or long files), please **attach** them to the post - this greatly improves readability.
@@ -34,13 +35,85 @@ Try to give your issue a title that is succinct and specific. The devs will rena
 
 To execute the test suite, from the root of the repo run `make test`. To control what tests to run, use `python3 -m unittest -v tests/<test_name>`.
 
-To regenerate test fixtures for `json.dumps` and report tests add a `print(output)` statement in the test and run `make test 2>/dev/null > tests/output.json` or  `make test 2>/dev/null > tests/output.md`.
+To regenerate test fixtures for `json.dumps` and report tests add a `print(output)` statement in the test and run `make test 2>/dev/null > tests/output.json` or `make test 2>/dev/null > tests/output.md`.
+
+## Host setup
+
+### brew-capable OSes
+
+Operating system with builtin support (e.g. macOS or [Bluefin](https://projectbluefin.io/)) or extended with support for [brew](https://brew.sh/):
+
+    brew install uv
+    brew install graphviz
+    brew install pandoc
+    brew install plantuml
+
+## Python package management
+
+The project uses the [`uv`](https://github.com/astral-sh/uv) package manager.
+
+## Project setup
+
+`uv` installs the library `pytm` as [editable package](https://docs.astral.sh/uv/guides/package/#editable-packages)
+and considers [development dependencies](https://docs.astral.sh/uv/concepts/projects/sync/#syncing-development-dependencies).
+
+    uv sync
+
+[Activate the virtual environment](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment)
+(depending on your shell you might need to activate differently, for the `fish` shell e.g. `source .venv/bin/activate.fish`):
+
+    source .venv/bin/activate
+
+## Running tests
+
+    uv run pytest
+
+## Check report and diagram generation
+
+    mkdir -p tm
+    ./tm.py --report docs/basic_template.md | pandoc -f markdown -t html > tm/report.html
+    ./tm.py --dfd | dot -Tpng -o tm/dfd.png
+    ./tm.py --seq | plantuml -tpng -pipe > tm/seq.png
+
+## Bump the version
+
+[Update the version](https://docs.astral.sh/uv/guides/package/#updating-your-version) with e.g.
+
+    uv version --bump minor
+
+## Build the library
+
+[build](https://docs.astral.sh/uv/guides/package/#building-your-package) the library with
+
+    uv build
+
+The project is a Python [library](https://docs.astral.sh/uv/concepts/projects/init/#libraries) and is packaged with the
+[`build-backend` of `uv`](https://docs.astral.sh/uv/reference/settings/#build-backend).
+
+## Publish the library (project maintainers only)
+
+[publish](https://docs.astral.sh/uv/guides/package/#publishing-your-package) the library with
+
+    uv publish
+
+## Generating a requirements file
+
+Docker/OCI containers depend on a requirements file.
+
+    uv export --no-editable --no-dev --format requirements.txt --output-file requirements.txt
+    uv export --no-editable --only-dev --format requirements.txt --output-file requirements-dev.txt
+
+## Export SBOM metadata
+
+`uv` supports [CycloneDX](https://github.com/CycloneDX) format out of the box.
+
+    uv export --format cyclonedx1.5 --output-file sbom.json
 
 ## PyTM-users
 
 Before you post to the [PyTM-users list](https://groups.google.com/forum/#!forum/pytm-users), make sure you look for existing solutions.
 
-* [GitHub issues](https://github.com/izar/pytm/issues) tracker (some problems have been answered there),
+- [GitHub issues](https://github.com/izar/pytm/issues) tracker (some problems have been answered there),
 
 Found a post/issue with your exact problem, but with no answer?
 Don't just leave a "me too" message - provide the details of your case.
@@ -56,9 +129,9 @@ PyTM welcomes all contributions.
 
 Briefly: read commit by commit, a PR should tell a clean, compelling story of _one_ improvement to PyTM. In particular:
 
-* A PR should do one clear thing that obviously improves PyTM, and nothing more. Making many smaller PRs is better than making one large PR; review effort is superlinear in the amount of code involved.
-* Similarly, each commit should be a small, atomic change representing one step in development. PRs should be made of many commits where appropriate.
-* Please do rewrite PR history to be clean rather than chronological. Within-PR bugfixes, style cleanups, reversions, etc. should be squashed and should not appear in merged PR history.
-* Anything nonobvious from the code should be explained in comments, commit messages, or the PR description, as appropriate.
+- A PR should do one clear thing that obviously improves PyTM, and nothing more. Making many smaller PRs is better than making one large PR; review effort is superlinear in the amount of code involved.
+- Similarly, each commit should be a small, atomic change representing one step in development. PRs should be made of many commits where appropriate.
+- Please do rewrite PR history to be clean rather than chronological. Within-PR bugfixes, style cleanups, reversions, etc. should be squashed and should not appear in merged PR history.
+- Anything nonobvious from the code should be explained in comments, commit messages, or the PR description, as appropriate.
 
 (With many thanks to the Caffe project for their original CONTRIBUTING.md file)

Dockerfile

@@ -1,7 +1,5 @@
-
 FROM python:3.12-rc-alpine
 
-
 WORKDIR /usr/src/app
 ENTRYPOINT ["sh"]
 
@@ -20,10 +18,10 @@ RUN apk add --no-cache graphviz openjdk11-jre fontconfig make curl ttf-liberatio
 ENV _JAVA_OPTIONS -Duser.home=/tmp -Dawt.useSystemAAFontSettings=gasp
 RUN printf '@startuml\n@enduml' | java -Djava.awt.headless=true -jar $PLANTUML_PATH -tpng -pipe >/dev/null
 
-COPY requirements.txt requirements-dev.txt ./
-RUN pip install --no-cache-dir -r requirements-dev.txt \
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt \
     && apk del .build-deps
 
-COPY pytm ./pytm
+COPY src/pytm ./pytm
 COPY docs ./docs
 COPY *.py Makefile ./

Makefile

@@ -12,7 +12,7 @@ endif
 
 MODEL?=tm
 
-libs := $(wildcard pytm/*.py) $(wildcard pytm/threatlib/*.json) $(wildcard pytm/images/*)
+libs := $(wildcard src/pytm/*.py) $(wildcard src/pytm/threatlib/*.json) $(wildcard src/pytm/images/*)
 
 all: clean docs/pytm/index.html $(MODEL)
 
@@ -26,7 +26,7 @@ endif
 docs/pytm/index.html: $(wildcard pytm/*.py)
 	PYTHONPATH=. pdoc --html --force --output-dir docs pytm
 
-docs/threats.md: $(wildcard pytm/threatlib/*.json)
+docs/threats.md: $(wildcard src/pytm/threatlib/*.json)
 	printf "# Threat database\n" > $@
 	jq -r ".[] | \"$$(cat docs/threats.jq)\"" $< >> $@
 
@@ -69,4 +69,4 @@ docs: docs/pytm/index.html docs/threats.md
 
 .PHONY: fmt
 fmt:
-	black  $(wildcard pytm/*.py) $(wildcard tests/*.py) $(wildcard *.py)
+	black  $(wildcard src/pytm/*.py) $(wildcard tests/*.py) $(wildcard *.py)

README.md

@@ -239,7 +239,7 @@ tm.py --dfd | dot -Tpng -o sample.png
 
 Generates this diagram:
 
-![dfd.png](.gitbook/assets/dfd.png)
+![dfd.png](docs/diagrams/dfd.png)
 
 Adding ".levels = [1,2]" attributes to an element will cause it (and its associated Dataflows if both flow endings are in the same DFD level) to render (or not) depending on the command argument "--levels 1 2".
 
@@ -253,7 +253,7 @@ tm.py --seq | java -Djava.awt.headless=true -jar plantuml.jar -tpng -pipe > seq.
 
 Generates this diagram:
 
-![seq.png](.gitbook/assets/seq.png)
+![seq.png](docs/diagrams/seq.png)
 
 ### Creating a Report
 

SECURITY.md

@@ -1,4 +1,3 @@
-Reporting a Vulnerability
-Please report (suspected) security vulnerabilities as a project issue. You will receive a response from us within 48 hours. If the issue is confirmed, we will release a patch as soon as possible depending on complexity but historically within a few days.
-
+# Reporting a Vulnerability
 
+Please report (suspected) security vulnerabilities as a project issue. You will receive a response from us within 48 hours. If the issue is confirmed, we will release a patch as soon as possible depending on complexity but historically within a few days.

docs/advanced_template.md

@@ -6,7 +6,7 @@
 
 ## Dataflow Diagram - Level 0 DFD
 
-![](sample.png)
+![sample.png](diagrams/sample.png)
 
  
 

docs/basic_template.md

@@ -22,7 +22,7 @@
 
 ## Dataflow Diagram - Level 0 DFD
 
-![](sample.png)
+![sample.png](diagrams/sample.png)
 
  
 

docs/reveal.md

@@ -10,7 +10,7 @@
 
 ## Dataflow Diagram 
 
-![](sample.png)
+![sample.png](docs/diagrams/sample.png)
 
 ---
 
@@ -182,4 +182,3 @@ Finding Count|{{item:call:getFindingCount}}|
 }}
 }}
 }
-