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
