smashuml 0.1.0__tar.gz

smashuml-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+build/
+dist/
+*.egg-info/
+# generated diagrams (golden files under tests/ are tracked)
+/*.drawio
+/*.pdf
+/*.png
+/out/
+
+# .NET build output of ExampleCodebase (IDE restores create it)
+bin/
+obj/

smashuml-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Ocheri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smashuml-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.5
+Name: smashuml
+Version: 0.1.0
+Summary: Deterministic UML class diagrams (draw.io) generated from source code
+Author: Adam Ocheri
+License-Expression: MIT
+License-File: LICENSE
+Keywords: class-diagram,csharp,diagram,documentation,drawio,react,typescript,uml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Requires-Dist: pathspec>=0.12
+Requires-Dist: tree-sitter-c-sharp>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter>=0.23
+Description-Content-Type: text/markdown
+
+# SmashUML
+
+**Generate complete UML class diagrams from your source code, as a draw.io document.**
+
+SmashUML scans a folder, parses every source file and writes one multi-page [draw.io](https://www.drawio.com/) document that documents the whole codebase: packages, classes, interfaces, enums, their members and the relationships between them. Open it in the draw.io desktop app or at [app.diagrams.net](https://app.diagrams.net), or export it to PDF.
+
+- **Complete** – every type and member is drawn, nothing is shortened; each run tells you so.
+- **Deterministic** – no AI involved: the same code always produces a byte-identical file, so documents can be committed and diffed.
+- **Laid out for you** – boxes are arranged and lines routed automatically; no manual dragging needed.
+- **Code-oriented** – C# and TypeScript (including React) are documented in their own terms: attributes, decorators, dependency injection, components, hooks, routes and HTTP endpoints.
+
+## Installation
+
+SmashUML needs Python 3.11 or newer. Install it as a command-line tool:
+
+```sh
+uv tool install smashuml
+```
+
+or with pipx:
+
+```sh
+pipx install smashuml
+```
+
+or into the current environment:
+
+```sh
+pip install smashuml
+```
+
+Check the installation:
+
+```sh
+smashuml --version
+```
+
+PDF export additionally needs the free [draw.io desktop app](https://github.com/jgraph/drawio-desktop/releases); `.drawio` and JSON output work without it.
+
+## Quick start
+
+From the root of your project:
+
+```sh
+smashuml generate
+```
+
+This scans the current folder and all its sub-folders and writes `<folder name>.drawio` into the current folder. The summary tells you what was found and whether everything was drawn:
+
+```text
+Scanned 126 files (csharp), 224 types, 1385 members, 458 relationships -> MyApi.drawio, 30 pages
+Complete: every type and member is drawn.
+```
+
+## Usage
+
+```text
+smashuml generate [path] [options]
+```
+
+`path` is the folder to scan (default: the current folder). Every option is optional.
+
+### Choosing what to scan and where to write
+
+| Command | Effect |
+|---|---|
+| `smashuml generate` | Documents the current folder into `./<folder name>.drawio`. |
+| `smashuml generate src/MyApp` | Documents another folder; the file is named after it (`./MyApp.drawio`). |
+| `smashuml generate -o docs/architecture.drawio` | Writes to a file of your choice (folders are created). |
+| `smashuml generate -o model.json` | Writes the parsed model as JSON instead of a diagram (the format follows the extension). |
+| `smashuml generate -o architecture.pdf` | Writes a PDF with one page per diagram page (needs the draw.io desktop app). |
+| `smashuml generate -f json -o model.txt` | Chooses the format explicitly: `drawio`, `json` or `pdf`. |
+| `smashuml generate --include "src/**" --include "lib/**"` | Scans only matching files (gitignore-style patterns, repeatable). |
+| `smashuml generate --exclude "**/Legacy/**"` | Skips matching files (repeatable). |
+| `smashuml generate --no-gitignore` | Also scans files that `.gitignore` excludes. |
+| `smashuml generate --no-default-excludes` | Also scans generated code and tests that are skipped by default (`*.Designer.cs`, `*.g.cs`, `Migrations/`, `*.test.ts`, `*.spec.ts`, `__tests__/`, `setupTests.ts`). |
+| `smashuml generate -q` | Prints errors only. |
+
+Build output and tool folders (`bin`, `obj`, `node_modules`, `dist`, hidden folders, ...) are never scanned.
+
+### Repositories with several projects
+
+A folder that *is* a project – it has a project file at its root (`*.csproj`, `package.json`, `tsconfig.json`, `pyproject.toml`, `go.mod`, ...) or source files directly in it – gives one document. A folder that only *holds* projects gives one document per top-level sub-folder:
+
+```text
+my-app/
+├── Backend/     (ASP.NET, has Backend.csproj)
+└── Frontend/    (React, has package.json)
+```
+
+| Command | Effect |
+|---|---|
+| `smashuml generate my-app` | Writes `Backend.drawio` and `Frontend.drawio`. |
+| `smashuml generate my-app -o docs/uml` | Writes `docs/uml/Backend.drawio` and `docs/uml/Frontend.drawio` (`-o` is a folder here). |
+| `smashuml generate my-app --single` | Writes one `my-app.drawio` covering both projects. |
+| `smashuml generate my-app/Backend` | Writes `Backend.drawio` only. |
+
+`.gitignore` files of the outer folder still apply to each project.
+
+### Choosing what to draw
+
+| Command | Effect |
+|---|---|
+| `smashuml generate --visibility public` | Draws only public members (`public`, `protected`, `package` or `all`; default `all`). |
+| `smashuml generate --no-members` | Draws class names only, without attributes and operations. |
+| `smashuml generate --max-members 20` | Caps each class box section at 20 rows, followed by `… N more` (default: no limit). |
+| `smashuml generate --no-external` | Hides base types that are not part of the scanned code (e.g. `ControllerBase`). |
+| `smashuml generate --pages overview,index,namespaces` | Emits only the listed pages (see below). |
+| `smashuml generate --title "Billing service"` | Sets the document title (default: the folder name). |
+
+Whenever an option leaves something out, the summary says so, e.g. `Not drawn because of options: 121 members below --visibility public`.
+
+### Configuration file
+
+The same settings can be kept in a `smashuml.toml` at the root of the scanned folder. Command-line options override it; `output` is relative to the file.
+
+```toml
+[smashuml]
+output = "docs/architecture.drawio"
+visibility = "public"
+exclude = ["**/Tests/**"]
+pages = ["overview", "index", "namespaces"]
+```
+
+## What the document contains
+
+Each document has several pages (tabs):
+
+| Page (`--pages` name) | Shows |
+|---|---|
+| **Overview** (`overview`) | The top-level packages with their sub-packages nested inside, and the dependencies between them. Thicker arrows mean more references; hover an arrow for the details. Click a package to open its page. |
+| **Namespace dependencies** (`namespace-dependencies`) | Every namespace and every dependency between two namespaces, ungrouped. |
+| **Index** (`index`) | Every scanned file, folder by folder, with the types it declares and a link to the page that documents them. |
+| **Type hierarchy** (`hierarchy`) | All inheritance and interface-implementation trees. |
+| **Dependencies** (`dependencies`) | Constructor-injected dependencies (controllers → services → data access), with dependency-injection lifetimes such as «scoped». |
+| **Component tree** (`components`) | React: which component renders which, from the routes down, labelled with the route paths. |
+| **Class diagrams** (`namespaces`) | One page per namespace (C#) or per top-level folder (TypeScript) with full UML class boxes. |
+
+Pages without content (e.g. *Component tree* in a C# project) are left out.
+
+Class boxes show:
+
+- attributes and operations with visibility (`+` public, `-` private, `#` protected, `~` package); static members underlined, abstract ones in italics
+- types, parameters (with `ref`, `out`, `params`, optional markers and default values), return types, initial values and enum values
+- attributes and decorators in grey, e.g. `[Route("api/courses")]`, `[HttpGet("{id}")]`, `@Injectable()`
+- modifiers as property strings (`{readOnly}`, `{override}`, `{async}`), accessors such as `{get; private set}` and generic constraints
+- associations with role names and multiplicities (`1`, `0..1`, `*`), inheritance, interface implementation, nesting and dependencies
+
+C# top-level statements (`Program.cs`) become a «program» box listing the dependency-injection registrations (`AddScoped<IFoo, Foo>()`, ...) and the request pipeline (`app.UseRouting()`, ...).
+
+React code is shown as «component», «hook» and «context» boxes with props, state, refs and the hooks used; `renders` arrows follow the JSX, routes come from `<Route>` elements and route tables, and each function lists the HTTP endpoints it calls, e.g. `getAllCourses(): Promise<Course[]> {GET /api/courses}`.
+
+Hover over a box to see the file and line it was declared in.
+
+## Supported languages
+
+| Language | Files | Packages are |
+|---|---|---|
+| C# | `.cs` | namespaces |
+| TypeScript, including React (TSX) | `.ts`, `.tsx`, `.mts`, `.cts` | folders |
+
+A folder may mix both languages. Parsing is done with [tree-sitter](https://tree-sitter.github.io/): no compiler or SDK of the scanned language is needed. TypeScript imports are followed through relative paths, `tsconfig.json` `baseUrl` / `paths` and `index.ts` re-exports.
+
+## PDF export
+
+`-o file.pdf` uses the draw.io desktop app's command line. SmashUML finds it in its default install location or on `PATH`; otherwise set the `SMASHUML_DRAWIO` environment variable to the executable.
+
+## License
+
+MIT

smashuml-0.1.0/README.md

@@ -0,0 +1,170 @@
+# SmashUML
+
+**Generate complete UML class diagrams from your source code, as a draw.io document.**
+
+SmashUML scans a folder, parses every source file and writes one multi-page [draw.io](https://www.drawio.com/) document that documents the whole codebase: packages, classes, interfaces, enums, their members and the relationships between them. Open it in the draw.io desktop app or at [app.diagrams.net](https://app.diagrams.net), or export it to PDF.
+
+- **Complete** – every type and member is drawn, nothing is shortened; each run tells you so.
+- **Deterministic** – no AI involved: the same code always produces a byte-identical file, so documents can be committed and diffed.
+- **Laid out for you** – boxes are arranged and lines routed automatically; no manual dragging needed.
+- **Code-oriented** – C# and TypeScript (including React) are documented in their own terms: attributes, decorators, dependency injection, components, hooks, routes and HTTP endpoints.
+
+## Installation
+
+SmashUML needs Python 3.11 or newer. Install it as a command-line tool:
+
+```sh
+uv tool install smashuml
+```
+
+or with pipx:
+
+```sh
+pipx install smashuml
+```
+
+or into the current environment:
+
+```sh
+pip install smashuml
+```
+
+Check the installation:
+
+```sh
+smashuml --version
+```
+
+PDF export additionally needs the free [draw.io desktop app](https://github.com/jgraph/drawio-desktop/releases); `.drawio` and JSON output work without it.
+
+## Quick start
+
+From the root of your project:
+
+```sh
+smashuml generate
+```
+
+This scans the current folder and all its sub-folders and writes `<folder name>.drawio` into the current folder. The summary tells you what was found and whether everything was drawn:
+
+```text
+Scanned 126 files (csharp), 224 types, 1385 members, 458 relationships -> MyApi.drawio, 30 pages
+Complete: every type and member is drawn.
+```
+
+## Usage
+
+```text
+smashuml generate [path] [options]
+```
+
+`path` is the folder to scan (default: the current folder). Every option is optional.
+
+### Choosing what to scan and where to write
+
+| Command | Effect |
+|---|---|
+| `smashuml generate` | Documents the current folder into `./<folder name>.drawio`. |
+| `smashuml generate src/MyApp` | Documents another folder; the file is named after it (`./MyApp.drawio`). |
+| `smashuml generate -o docs/architecture.drawio` | Writes to a file of your choice (folders are created). |
+| `smashuml generate -o model.json` | Writes the parsed model as JSON instead of a diagram (the format follows the extension). |
+| `smashuml generate -o architecture.pdf` | Writes a PDF with one page per diagram page (needs the draw.io desktop app). |
+| `smashuml generate -f json -o model.txt` | Chooses the format explicitly: `drawio`, `json` or `pdf`. |
+| `smashuml generate --include "src/**" --include "lib/**"` | Scans only matching files (gitignore-style patterns, repeatable). |
+| `smashuml generate --exclude "**/Legacy/**"` | Skips matching files (repeatable). |
+| `smashuml generate --no-gitignore` | Also scans files that `.gitignore` excludes. |
+| `smashuml generate --no-default-excludes` | Also scans generated code and tests that are skipped by default (`*.Designer.cs`, `*.g.cs`, `Migrations/`, `*.test.ts`, `*.spec.ts`, `__tests__/`, `setupTests.ts`). |
+| `smashuml generate -q` | Prints errors only. |
+
+Build output and tool folders (`bin`, `obj`, `node_modules`, `dist`, hidden folders, ...) are never scanned.
+
+### Repositories with several projects
+
+A folder that *is* a project – it has a project file at its root (`*.csproj`, `package.json`, `tsconfig.json`, `pyproject.toml`, `go.mod`, ...) or source files directly in it – gives one document. A folder that only *holds* projects gives one document per top-level sub-folder:
+
+```text
+my-app/
+├── Backend/     (ASP.NET, has Backend.csproj)
+└── Frontend/    (React, has package.json)
+```
+
+| Command | Effect |
+|---|---|
+| `smashuml generate my-app` | Writes `Backend.drawio` and `Frontend.drawio`. |
+| `smashuml generate my-app -o docs/uml` | Writes `docs/uml/Backend.drawio` and `docs/uml/Frontend.drawio` (`-o` is a folder here). |
+| `smashuml generate my-app --single` | Writes one `my-app.drawio` covering both projects. |
+| `smashuml generate my-app/Backend` | Writes `Backend.drawio` only. |
+
+`.gitignore` files of the outer folder still apply to each project.
+
+### Choosing what to draw
+
+| Command | Effect |
+|---|---|
+| `smashuml generate --visibility public` | Draws only public members (`public`, `protected`, `package` or `all`; default `all`). |
+| `smashuml generate --no-members` | Draws class names only, without attributes and operations. |
+| `smashuml generate --max-members 20` | Caps each class box section at 20 rows, followed by `… N more` (default: no limit). |
+| `smashuml generate --no-external` | Hides base types that are not part of the scanned code (e.g. `ControllerBase`). |
+| `smashuml generate --pages overview,index,namespaces` | Emits only the listed pages (see below). |
+| `smashuml generate --title "Billing service"` | Sets the document title (default: the folder name). |
+
+Whenever an option leaves something out, the summary says so, e.g. `Not drawn because of options: 121 members below --visibility public`.
+
+### Configuration file
+
+The same settings can be kept in a `smashuml.toml` at the root of the scanned folder. Command-line options override it; `output` is relative to the file.
+
+```toml
+[smashuml]
+output = "docs/architecture.drawio"
+visibility = "public"
+exclude = ["**/Tests/**"]
+pages = ["overview", "index", "namespaces"]
+```
+
+## What the document contains
+
+Each document has several pages (tabs):
+
+| Page (`--pages` name) | Shows |
+|---|---|
+| **Overview** (`overview`) | The top-level packages with their sub-packages nested inside, and the dependencies between them. Thicker arrows mean more references; hover an arrow for the details. Click a package to open its page. |
+| **Namespace dependencies** (`namespace-dependencies`) | Every namespace and every dependency between two namespaces, ungrouped. |
+| **Index** (`index`) | Every scanned file, folder by folder, with the types it declares and a link to the page that documents them. |
+| **Type hierarchy** (`hierarchy`) | All inheritance and interface-implementation trees. |
+| **Dependencies** (`dependencies`) | Constructor-injected dependencies (controllers → services → data access), with dependency-injection lifetimes such as «scoped». |
+| **Component tree** (`components`) | React: which component renders which, from the routes down, labelled with the route paths. |
+| **Class diagrams** (`namespaces`) | One page per namespace (C#) or per top-level folder (TypeScript) with full UML class boxes. |
+
+Pages without content (e.g. *Component tree* in a C# project) are left out.
+
+Class boxes show:
+
+- attributes and operations with visibility (`+` public, `-` private, `#` protected, `~` package); static members underlined, abstract ones in italics
+- types, parameters (with `ref`, `out`, `params`, optional markers and default values), return types, initial values and enum values
+- attributes and decorators in grey, e.g. `[Route("api/courses")]`, `[HttpGet("{id}")]`, `@Injectable()`
+- modifiers as property strings (`{readOnly}`, `{override}`, `{async}`), accessors such as `{get; private set}` and generic constraints
+- associations with role names and multiplicities (`1`, `0..1`, `*`), inheritance, interface implementation, nesting and dependencies
+
+C# top-level statements (`Program.cs`) become a «program» box listing the dependency-injection registrations (`AddScoped<IFoo, Foo>()`, ...) and the request pipeline (`app.UseRouting()`, ...).
+
+React code is shown as «component», «hook» and «context» boxes with props, state, refs and the hooks used; `renders` arrows follow the JSX, routes come from `<Route>` elements and route tables, and each function lists the HTTP endpoints it calls, e.g. `getAllCourses(): Promise<Course[]> {GET /api/courses}`.
+
+Hover over a box to see the file and line it was declared in.
+
+## Supported languages
+
+| Language | Files | Packages are |
+|---|---|---|
+| C# | `.cs` | namespaces |
+| TypeScript, including React (TSX) | `.ts`, `.tsx`, `.mts`, `.cts` | folders |
+
+A folder may mix both languages. Parsing is done with [tree-sitter](https://tree-sitter.github.io/): no compiler or SDK of the scanned language is needed. TypeScript imports are followed through relative paths, `tsconfig.json` `baseUrl` / `paths` and `index.ts` re-exports.
+
+## PDF export
+
+`-o file.pdf` uses the draw.io desktop app's command line. SmashUML finds it in its default install location or on `PATH`; otherwise set the `SMASHUML_DRAWIO` environment variable to the executable.
+
+## License
+
+MIT

smashuml-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "smashuml"
+version = "0.1.0"
+description = "Deterministic UML class diagrams (draw.io) generated from source code"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Adam Ocheri" }]
+requires-python = ">=3.11"
+keywords = ["uml", "drawio", "diagram", "class-diagram", "documentation", "csharp", "typescript", "react"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "tree-sitter>=0.23",
+    "tree-sitter-c-sharp>=0.23",
+    "pathspec>=0.12",
+    "tree-sitter-typescript>=0.23.2",
+]
+
+[project.scripts]
+smashuml = "smashuml.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/smashuml"]
+
+# The published source archive holds the package only (pyproject.toml, the
+# README and license files are always added): no ExampleCodebase, tests or tooling.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/smashuml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

smashuml-0.1.0/src/smashuml/__init__.py

@@ -0,0 +1,3 @@
+"""SmashUML - deterministic UML diagrams generated from source code."""
+
+__version__ = "0.1.0"

smashuml-0.1.0/src/smashuml/__main__.py

@@ -0,0 +1,3 @@
+from smashuml.cli import main
+
+raise SystemExit(main())