Metadata-Version: 2.4
Name: sumd
Version: 0.3.1
Summary: SUMD - Structured Unified Markdown Descriptor for AI-aware project documentation
Project-URL: Homepage, https://github.com/tom/statement
Project-URL: Repository, https://github.com/tom/statement
Author-email: Tom Sapletta <tom@sapletta.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: documentation,llm,markdown,project-descriptor,sumd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: costs>=0.1.20
Requires-Dist: goal>=2.1.0
Requires-Dist: pfix>=0.1.60
Requires-Dist: pyyaml>=6.0
Requires-Dist: toml>=0.10.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: costs>=0.1.20; extra == 'dev'
Requires-Dist: goal>=2.1.0; extra == 'dev'
Requires-Dist: pfix>=0.1.60; extra == 'dev'
Requires-Dist: pyqual>=0.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# SUMD

## AI Cost Tracking

![AI Cost](https://img.shields.io/badge/AI%20Cost-$4.65-green) ![AI Model](https://img.shields.io/badge/AI%20Model-openrouter%2Fqwen%2Fqwen3-coder-next-lightgrey)

This project uses AI-generated code. Total cost: **$4.6500** with **31** AI commits.

Generated on 2026-04-19 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/models/openrouter/qwen/qwen3-coder-next)

---



SUMD is a semantic project descriptor format in Markdown that defines intent, structure, execution entry points, and mental model of a system for both humans and LLMs.

## What is SUMD?

SUMD (Structured Unified Markdown Descriptor) is a lightweight structured markdown format for AI-aware project descriptions. It serves as a single source of truth for project documentation, optimized for both human readability and LLM context injection.

### Purpose

- **Project descriptor**: Defines API, CLI, workflows, endpoints, and system architecture
- **AI-optimized**: Structured for LLM consumption and automation tools
- **Lightweight manifest**: Bridges the gap between README, spec, and configuration files
- **Context injection**: Provides structured context for AI agents and tools

### Use Cases

- Project documentation and specification
- Input for LLM context injection
- CI/CD workflow descriptions
- API and CLI mapping
- Structural project manifest

## Installation

```bash
pip install sumd                  # stable
pip install sumd==0.2.0rc1        # latest release candidate
```

## Developer Workflow

```bash
# health check — verify environment
task doctor

# run tests with coverage
task test

# quality gate (CC + vallm + coverage)
task pyqual

# build + publish (runs automatically when gates pass via pyqual pipeline)
task publish
```



## Usage

### CLI Commands

```bash
# Shortcut: scan current directory (detects if workspace or single project)
sumd .                          # equivalent to: sumd scan . --fix
sumd /path/to/project           # scan a specific directory

# Scan a workspace — auto-generate SUMD.md for every project found
sumd scan .                     # skip projects that already have SUMD.md
sumd scan . --fix               # overwrite existing SUMD.md
sumd scan . --fix --no-raw      # convert sources to structured Markdown instead of raw code blocks
sumd scan . --fix --analyze     # also run analysis tools (code2llm, redup, vallm)
sumd scan . --fix --analyze --tools code2llm,redup  # only selected tools
sumd scan . --fix --depth 2     # limit recursive search depth (default: unlimited)

# Section profiles — control how much is rendered in SUMD.md
sumd scan . --fix --profile minimal  # core sections only (metadata, architecture, workflows, dependencies, deployment)
sumd scan . --fix --profile light    # + interfaces, quality, configuration, environment, extras
sumd scan . --fix --profile rich     # + code analysis, source snippets, call graph, API stubs, test contracts (default)

# Generate SUMR.md (pre-refactoring analysis report for AI-aware refactorization)
sumd scan . --profile refactor       # creates SUMR.md — use sumr alias below
sumr .                               # shorthand: sumr <path> ≡ sumd scan <path> --profile refactor

# Lint / validate SUMD files
sumd lint SUMD.md               # validate a single file
sumd lint --workspace .         # validate all SUMD.md files in the workspace
sumd lint --workspace . --json  # output JSON results

# Generate project/map.toon.yaml (static code map — without code2llm)
sumd map ./my-project             # write to project/map.toon.yaml
sumd map ./my-project --force     # overwrite existing
sumd map ./my-project --stdout    # print to stdout

# Generate testql scenario scaffolds from OpenAPI spec
sumd scaffold ./my-project                  # all scenarios (api + smoke)
sumd scaffold ./my-project --type smoke     # only smoke tests
sumd scaffold ./my-project --type crud      # per-resource CRUD scenarios
sumd scaffold ./my-project --force          # overwrite existing files

# Run analysis tools on a single project
sumd analyze ./my-project                    # run all tools
sumd analyze ./my-project --tools code2llm   # only code2llm
sumd analyze ./my-project --force            # reinstall tools
```

### Section Profiles

SUMD renders output in configurable **profiles** to trade off detail vs. token cost:

| Profile | Sections | Use case |
|---------|----------|----------|
| `minimal` | Metadata, Architecture, Workflows, Dependencies, Deployment | Quick overview, CI badges |
| `light` | + Interfaces, Quality, Configuration, Environment, Extras | Standard documentation |
| `rich` | + Code Analysis, Source Snippets, Call Graph, API Stubs, Test Contracts | LLM context injection (default) |
| `refactor` | Refactoring-focused analysis → generates `SUMR.md` | AI-aware pre-refactoring report |

### Python API

```python
from sumd import parse, parse_file
from sumd.parser import validate_sumd_file

# Parse SUMD from string
document = parse(content)

# Parse SUMD from file
document = parse_file("SUMD.md")

# Validate SUMD file (markdown structure + codeblock format)
result = validate_sumd_file(Path("SUMD.md"))
# result = {"source": "SUMD.md", "markdown": [...], "codeblocks": [...], "ok": True}
if not result["ok"]:
    for issue in result["markdown"] + result["codeblocks"]:
        print(issue)
```

## What is Embedded in SUMD.md?

SUMD auto-embeds the following sources from a project (when present):

| Source | Contents | markpact kind |
|--------|----------|---------------|
| `pyproject.toml` | metadata, deps, entry points | _parsed_ |
| `Taskfile.yml` | all tasks as raw YAML | `markpact:taskfile` |
| `openapi.yaml` | full OpenAPI spec (endpoints as sections) | `markpact:openapi` |
| `testql-scenarios/**` | all `.testql.toon.yaml` scenario files | `markpact:testql` |
| `app.doql.less` (preferred) or `.css` | DOQL styling | `markpact:doql` |
| `pyqual.yaml` | quality pipeline config | `markpact:pyqual` |
| `goal.yaml` | project intent | _rendered_ |
| `.env.example` | env variables list | _listed_ |
| `Dockerfile` | containerisation | _listed_ |
| `docker-compose.*.yml` | services | _listed_ |
| `src/**/*.py` modules | module list | _listed_ |
| `package.json` | Node.js deps (dependencies + devDependencies) | _listed_ |
| `project/analysis.toon.yaml` | static code analysis (CC, pipelines) | `markpact:analysis` |
| `project/project.toon.yaml` | project topology | `markpact:analysis` |
| `project/evolution.toon.yaml` | commit evolution | `markpact:analysis` |
| `project/map.toon.yaml` | module inventory, function signatures, CC metrics | `markpact:analysis` |
| `project/duplication.toon.yaml` | code duplication report | `markpact:analysis` |
| `project/validation.toon.yaml` | vallm validation results | `markpact:analysis` |
| `project/calls.toon.yaml` | call graph with hub metrics | `markpact:analysis` |
| `project/compact_flow.mmd` | compact call flow diagram | `markpact:analysis` |
| `project/calls.mmd` | full call graph | `markpact:analysis` |
| `project/flow.mmd` | execution flow | `markpact:analysis` |
| `project/context.md` | architecture analysis (code2llm) | _inline markdown_ |
| `project/README.md` | analysis readme | _inline markdown_ |
| `project/prompt.txt` | code2llm prompt used | `markpact:analysis` |

**Not embedded:** `*.png` (binary images), `index.html` (generated visualisation), `refactor-progress.txt`, `testql-scenarios/` inside project/.

`project/map.toon.yaml` is generated by `sumd map` (built-in, no extra deps). Other `project/` files are generated by `sumd analyze` (invokes `code2llm`, `redup`, `vallm`).


## Ecosystem Architecture

SUMD is part of a three-layer system:

```
┌─────────────────────────────────────────────────────────────┐
│                     SUMD (opis)                              │
│              Structured Unified Markdown Descriptor          │
│         Project description, intent, architecture            │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    DOQL (wykonanie)                          │
│              Declarative Object Query Language               │
│              Data manipulation and execution                 │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                  Taskfile (runtime)                          │
│              Task runner and workflow execution              │
│              Automation and orchestration                   │
└─────────────────────────────────────────────────────────────┘
```

- **SUMD → opis (description)**: Defines what the system is and how it should work
- **DOQL → wykonanie (execution)**: Provides the language to manipulate and execute operations
- **Taskfile → runtime**: Manages the actual execution of workflows and tasks

## License

Licensed under Apache-2.0.
