sumd 0.3.30__tar.gz → 0.3.32__tar.gz

{sumd-0.3.30 → sumd-0.3.32}/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.32] - 2026-04-23
+
+### Docs
+- Update README.md
+
+### Other
+- Update project.sh
+- Update sumd/sections/api_stubs.py
+- Update sumd/sections/call_graph.py
+- Update sumd/sections/code_analysis.py
+- Update sumd/sections/configuration.py
+- Update sumd/sections/dependencies.py
+- Update sumd/sections/deployment.py
+- Update sumd/sections/extras.py
+- Update sumd/sections/source_snippets.py
+- Update sumd/sections/test_contracts.py
+
+## [0.3.31] - 2026-04-23
+
+### Docs
+- Update README.md
+
+### Other
+- Update sumd/sections/interfaces.py
+- Update sumd/sections/quality.py
+- Update sumd/sections/workflows.py
+
 ## [0.3.30] - 2026-04-23
 
 ### Docs

{sumd-0.3.30 → sumd-0.3.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sumd
-Version: 0.3.30
+Version: 0.3.32
 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
@@ -41,17 +41,17 @@ Description-Content-Type: text/markdown
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.3.30-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-20.7h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.3.32-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-21.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (60 commits)
-- 👤 **Human dev:** ~$2071 (20.7h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (62 commits)
+- 👤 **Human dev:** ~$2098 (21.0h @ $100/h, 30min dedup)
 
 Generated on 2026-04-23 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![Version](https://img.shields.io/badge/version-0.3.30-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![Version](https://img.shields.io/badge/version-0.3.32-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 **SUMD** (Structured Unified Markdown Descriptor) is a semantic project descriptor format in Markdown.  
 It defines intent, structure, execution entry points, and the mental model of a system for both humans and LLMs.

{sumd-0.3.30 → sumd-0.3.32}/README.md

@@ -3,17 +3,17 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.3.30-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-20.7h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.3.32-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-21.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (60 commits)
-- 👤 **Human dev:** ~$2071 (20.7h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (62 commits)
+- 👤 **Human dev:** ~$2098 (21.0h @ $100/h, 30min dedup)
 
 Generated on 2026-04-23 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![Version](https://img.shields.io/badge/version-0.3.30-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![Version](https://img.shields.io/badge/version-0.3.32-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 **SUMD** (Structured Unified Markdown Descriptor) is a semantic project descriptor format in Markdown.  
 It defines intent, structure, execution entry points, and the mental model of a system for both humans and LLMs.

{sumd-0.3.30 → sumd-0.3.32}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sumd"
-version = "0.3.30"
+version = "0.3.32"
 description = "SUMD - Structured Unified Markdown Descriptor for AI-aware project documentation"
 readme = "README.md"
 license = "Apache-2.0"

{sumd-0.3.30 → sumd-0.3.32}/sumd/__init__.py

@@ -4,7 +4,7 @@ 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.
 """
 
-__version__ = "0.3.30"
+__version__ = "0.3.32"
 
 from sumd.models import SUMDDocument
 from sumd.parser import (

sumd-0.3.32/sumd/sections/api_stubs.py

@@ -0,0 +1,76 @@
+"""sumd.sections.api_stubs — ApiStubsSection.
+
+Renders OpenAPI endpoints as Python-like typed stubs for LLM orientation.
+LLM sees function signatures and HTTP method/path without reading full openapi.yaml.
+"""
+
+from __future__ import annotations
+
+from sumd.sections.base import RenderContext, Section
+
+
+# ---------------------------------------------------------------------------
+# Private renderers (moved from renderer.py)
+# ---------------------------------------------------------------------------
+
+
+def _render_api_stubs(openapi: dict) -> list[str]:
+    """Render OpenAPI endpoints as Python-like typed stubs for LLM orientation."""
+    endpoints = openapi.get("endpoints", [])
+    schemas = openapi.get("schemas", [])
+    if not endpoints:
+        return []
+    L: list[str] = []
+    a = L.append
+    a("## API Stubs")
+    a("")
+    title = openapi.get("title", "")
+    version = openapi.get("version", "")
+    if title:
+        a(f"*{title} v{version} — auto-generated stubs from `openapi.yaml`.*")
+        a("")
+
+    # Group by tag for structure
+    by_tag: dict[str, list[dict]] = {}
+    for ep in endpoints:
+        tag = ep["tags"][0] if ep.get("tags") else "default"
+        by_tag.setdefault(tag, []).append(ep)
+
+    a("```python markpact:openapi path=openapi.yaml")
+    for tag, eps in by_tag.items():
+        a(f"# {tag}")
+        for ep in eps:
+            op_id = (
+                ep.get("operationId")
+                or f"{ep['method'].lower()}_{ep['path'].replace('/', '_').strip('_')}"
+            )
+            summary = f"  # {ep['summary']}" if ep.get("summary") else ""
+            a(f"def {op_id}() -> Response:{summary}")
+            a(f'    "{ep["method"]} {ep["path"]}"')
+        a("")
+    a("```")
+    a("")
+    if schemas:
+        a("**Schemas**: " + ", ".join(f"`{s}`" for s in schemas))
+        a("")
+    return L
+
+
+# ---------------------------------------------------------------------------
+# Section class
+# ---------------------------------------------------------------------------
+
+
+class ApiStubsSection:
+    name = "api_stubs"
+    level = 2
+    profiles = frozenset({"rich"})
+
+    def should_render(self, ctx: RenderContext) -> bool:
+        return bool(ctx.openapi.get("endpoints"))
+
+    def render(self, ctx: RenderContext) -> list[str]:
+        return _render_api_stubs(ctx.openapi)
+
+
+assert isinstance(ApiStubsSection(), Section)

sumd-0.3.32/sumd/sections/call_graph.py

@@ -0,0 +1,156 @@
+"""sumd.sections.call_graph — CallGraphSection.
+
+Renders a summary of the call graph (HUBS table + degree stats) from
+calls.toon.yaml in project/, followed by the full embed for LLM reference.
+
+Replaces the raw dump that would otherwise appear in CodeAnalysis.
+"""
+
+from __future__ import annotations
+
+import re
+
+from sumd.sections.base import RenderContext, Section
+
+
+# ---------------------------------------------------------------------------
+# Private renderers (moved from renderer.py)
+# ---------------------------------------------------------------------------
+
+
+def _parse_calls_header(lines: list[str]) -> dict:
+    """Parse node/edge/module counts and CC average from header comments."""
+    result = {"nodes": 0, "edges": 0, "modules_count": 0, "cc_avg": 0.0}
+    for line in lines[:5]:
+        if line.startswith("# nodes:"):
+            m = re.search(
+                r"nodes:\s*(\d+).*edges:\s*(\d+).*modules:\s*(\d+)", line
+            )
+            if m:
+                result["nodes"] = int(m.group(1))
+                result["edges"] = int(m.group(2))
+                result["modules_count"] = int(m.group(3))
+        if line.startswith("# CC"):
+            m = re.search(r"CC\u0304=?\s*([\d.]+)", line)
+            if m:
+                result["cc_avg"] = float(m.group(1))
+    return result
+
+
+def _parse_hub_stat_line(line: str) -> dict | None:
+    """Extract CC/in/out/total metrics from a hub stats line, or return None."""
+    m = re.search(r"CC=(\d+)\s+in:(\d+)\s+out:(\d+)\s+total:(\d+)", line)
+    if not m:
+        return None
+    return {
+        "cc": int(m.group(1)),
+        "in": int(m.group(2)),
+        "out": int(m.group(3)),
+        "total": int(m.group(4)),
+    }
+
+
+def _process_in_hubs_line(line: str, hubs: list, current_hub: dict) -> dict:
+    """Process a single indented line while inside the HUBS block."""
+    if line.startswith("    "):
+        stats = _parse_hub_stat_line(line)
+        if stats and current_hub:
+            current_hub.update(stats)
+    elif line.startswith("  "):
+        if current_hub:
+            hubs.append(current_hub)
+        current_hub = {"name": line.strip()}
+    return current_hub
+
+
+def _parse_calls_hubs(lines: list[str]) -> list[dict]:
+    """Parse HUBS section into list of hub dicts."""
+    hubs: list[dict] = []
+    in_hubs = False
+    current_hub: dict = {}
+    for line in lines:
+        if line.startswith("HUBS["):
+            in_hubs = True
+            continue
+        if in_hubs and line and not line.startswith(" "):
+            in_hubs = False
+        if in_hubs:
+            current_hub = _process_in_hubs_line(line, hubs, current_hub)
+    if current_hub:
+        hubs.append(current_hub)
+    return hubs
+
+
+def _parse_calls_toon(content: str) -> dict:
+    """Parse calls.toon.yaml text into structured dict for rendering."""
+    lines = content.splitlines()
+    return {
+        **_parse_calls_header(lines),
+        "hubs": _parse_calls_hubs(lines),
+        "modules": [],
+    }
+
+
+def _render_call_graph(project_analysis: list) -> list[str]:
+    """Render call graph summary from calls.toon.yaml in project_analysis."""
+    calls_entry = next(
+        (e for e in project_analysis if "calls.toon" in e.get("file", "")), None
+    )
+    if not calls_entry:
+        return []
+
+    data = _parse_calls_toon(calls_entry["content"])
+    if not data["hubs"]:
+        return []
+
+    L: list[str] = []
+    a = L.append
+    a("## Call Graph")
+    a("")
+    a(
+        f"*{data['nodes']} nodes · {data['edges']} edges · {data['modules_count']} modules · CC\u0304={data['cc_avg']}*"
+    )
+    a("")
+
+    # Top hubs table (top 8 by total degree)
+    top_hubs = sorted(data["hubs"], key=lambda h: h.get("total", 0), reverse=True)[:8]
+    a("### Hubs (by degree)")
+    a("")
+    a("| Function | CC | in | out | total |")
+    a("|----------|----|----|-----|-------|")
+    for hub in top_hubs:
+        name = hub["name"].split(".")[-1]  # short name
+        module = ".".join(hub["name"].split(".")[:-1])
+        cc_flag = " ⚠" if hub.get("cc", 0) >= 10 else ""
+        a(
+            f"| `{name}` *(in {module})* | {hub.get('cc', 0)}{cc_flag} | {hub.get('in', 0)} | {hub.get('out', 0)} | **{hub.get('total', 0)}** |"
+        )
+    a("")
+
+    # Full embed for LLM reference under markpact tag
+    rel = calls_entry["file"]
+    a(f"```toon markpact:analysis path={rel}")
+    a(calls_entry["content"].rstrip())
+    a("```")
+    a("")
+    return L
+
+
+# ---------------------------------------------------------------------------
+# Section class
+# ---------------------------------------------------------------------------
+
+
+class CallGraphSection:
+    name = "call_graph"
+    level = 2
+    profiles = frozenset({"rich", "refactor"})
+
+    def should_render(self, ctx: RenderContext) -> bool:
+        return any("calls.toon" in e.get("file", "") for e in ctx.project_analysis)
+
+    def render(self, ctx: RenderContext) -> list[str]:
+        return _render_call_graph(ctx.project_analysis)
+
+
+assert isinstance(CallGraphSection(), Section)

sumd-0.3.32/sumd/sections/code_analysis.py

@@ -0,0 +1,68 @@
+"""sumd.sections.code_analysis — CodeAnalysisSection."""
+
+from __future__ import annotations
+
+from sumd.sections.base import RenderContext, Section
+
+
+# ---------------------------------------------------------------------------
+# Private renderers (moved from renderer.py)
+# ---------------------------------------------------------------------------
+
+
+def _render_code_analysis(
+    project_analysis: list, skip_files: set[str] | None = None
+) -> list[str]:
+    """Render Code Analysis section, optionally skipping files handled by other sections."""
+    skip_files = skip_files or set()
+    entries = [
+        e
+        for e in project_analysis
+        if not any(s in e.get("file", "") for s in skip_files)
+    ]
+    if not entries:
+        return []
+    L: list[str] = []
+    a = L.append
+    a("## Code Analysis")
+    a("")
+    for entry in entries:
+        a(f"### `{entry['file']}`")
+        a("")
+        lang = entry["lang"]
+        if lang == "markdown":
+            a(entry["content"])
+        elif lang == "text":
+            a(f"```text markpact:analysis path={entry['file']}")
+            a(entry["content"])
+            a("```")
+        else:
+            a(f"```{lang} markpact:analysis path={entry['file']}")
+            a(entry["content"])
+            a("```")
+        a("")
+    return L
+
+
+# ---------------------------------------------------------------------------
+# Section class
+# ---------------------------------------------------------------------------
+
+
+class CodeAnalysisSection:
+    name = "code_analysis"
+    level = 2
+    profiles = frozenset({"rich"})
+
+    def should_render(self, ctx: RenderContext) -> bool:
+        # Skip if ALL entries are calls.toon (handled by CallGraphSection)
+        non_calls = [
+            e for e in ctx.project_analysis if "calls.toon" not in e.get("file", "")
+        ]
+        return bool(non_calls)
+
+    def render(self, ctx: RenderContext) -> list[str]:
+        return _render_code_analysis(ctx.project_analysis, skip_files={"calls.toon"})
+
+
+assert isinstance(CodeAnalysisSection(), Section)

sumd-0.3.32/sumd/sections/configuration.py

@@ -0,0 +1,44 @@
+"""sumd.sections.configuration — ConfigurationSection."""
+
+from __future__ import annotations
+
+from sumd.sections.base import RenderContext, Section
+
+
+# ---------------------------------------------------------------------------
+# Private renderers (moved from renderer.py)
+# ---------------------------------------------------------------------------
+
+
+def _render_configuration_section(name: str, version: str) -> list[str]:
+    return [
+        "## Configuration",
+        "",
+        "```yaml",
+        "project:",
+        f"  name: {name}",
+        f"  version: {version}",
+        "  env: local",
+        "```",
+        "",
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Section class
+# ---------------------------------------------------------------------------
+
+
+class ConfigurationSection:
+    name = "configuration"
+    level = 2
+    profiles = frozenset({"light", "rich"})
+
+    def should_render(self, ctx: RenderContext) -> bool:
+        return True
+
+    def render(self, ctx: RenderContext) -> list[str]:
+        return _render_configuration_section(ctx.name, ctx.version)
+
+
+assert isinstance(ConfigurationSection(), Section)

sumd-0.3.32/sumd/sections/dependencies.py

@@ -0,0 +1,97 @@
+"""sumd.sections.dependencies — DependenciesSection."""
+
+from __future__ import annotations
+
+from sumd.sections.base import RenderContext, Section
+
+
+# ---------------------------------------------------------------------------
+# Private renderers (moved from renderer.py)
+# ---------------------------------------------------------------------------
+
+
+def _render_deps_runtime(deps: list, node_deps: list, L: list[str]) -> None:
+    a = L.append
+    if deps:
+        a("### Runtime")
+        a("")
+        a("```text markpact:deps python")
+        for dep in deps:
+            a(dep)
+        a("```")
+        a("")
+    elif node_deps:
+        a("### Runtime (Node.js)")
+        a("")
+        a("```text markpact:deps node")
+        for dep in node_deps[:30]:
+            a(dep)
+        if len(node_deps) > 30:
+            a(f"# (+{len(node_deps) - 30} more)")
+        a("```")
+        a("")
+    else:
+        a("### Runtime")
+        a("")
+        a("*(see pyproject.toml)*")
+        a("")
+
+
+def _render_deps_dev(dev_deps: list, node_dev: list, L: list[str]) -> None:
+    a = L.append
+    if dev_deps:
+        a("### Development")
+        a("")
+        a("```text markpact:deps python scope=dev")
+        for dep in dev_deps:
+            a(dep)
+        a("```")
+        a("")
+    elif node_dev:
+        a("### Development (Node.js)")
+        a("")
+        a("```text markpact:deps node scope=dev")
+        for dep in node_dev[:20]:
+            a(dep)
+        if len(node_dev) > 20:
+            a(f"# (+{len(node_dev) - 20} more)")
+        a("```")
+        a("")
+
+
+def _render_dependencies(
+    deps: list, dev_deps: list, pkg_json: dict | None = None
+) -> list[str]:
+    pkg_json = pkg_json or {}
+    L: list[str] = []
+    a = L.append
+    a("## Dependencies")
+    a("")
+    _render_deps_runtime(deps, pkg_json.get("dependencies", []), L)
+    _render_deps_dev(dev_deps, pkg_json.get("devDependencies", []), L)
+    return L
+
+
+# ---------------------------------------------------------------------------
+# Section class
+# ---------------------------------------------------------------------------
+
+
+class DependenciesSection:
+    name = "dependencies"
+    level = 2
+    profiles = frozenset({"light", "rich"})
+
+    def should_render(self, ctx: RenderContext) -> bool:
+        return bool(
+            ctx.deps
+            or ctx.dev_deps
+            or ctx.pkg_json.get("dependencies")
+            or ctx.pkg_json.get("devDependencies")
+        )
+
+    def render(self, ctx: RenderContext) -> list[str]:
+        return _render_dependencies(ctx.deps, ctx.dev_deps, ctx.pkg_json)
+
+
+assert isinstance(DependenciesSection(), Section)

sumd-0.3.32/sumd/sections/deployment.py

@@ -0,0 +1,111 @@
+"""sumd.sections.deployment — DeploymentSection."""
+
+from __future__ import annotations
+
+from sumd.sections.base import RenderContext, Section
+
+
+# ---------------------------------------------------------------------------
+# Private renderers (moved from renderer.py)
+# ---------------------------------------------------------------------------
+
+
+def _render_deployment_install(pkg_json: dict, name: str, L: list[str]) -> None:
+    a = L.append
+    if pkg_json.get("name"):
+        a("```bash markpact:run")
+        a(f"npm install {pkg_json['name']}")
+        a("```")
+    else:
+        a("```bash markpact:run")
+        a(f"pip install {name}")
+        a("")
+        a("# development install")
+        a("pip install -e .[dev]")
+        a("```")
+    a("")
+
+
+def _render_deployment_reqs(reqs: list, L: list[str]) -> None:
+    if not reqs:
+        return
+    a = L.append
+    a("### Requirements Files")
+    a("")
+    for r in reqs:
+        a(f"#### `{r['file']}`")
+        a("")
+        for dep in r["deps"][:20]:
+            a(f"- `{dep}`")
+        if len(r["deps"]) > 20:
+            a(f"- *(+{len(r['deps']) - 20} more)*")
+        a("")
+
+
+def _render_dockerfile_info(dockerfile: dict, a) -> None:
+    """Append Dockerfile section lines to output via *a*."""
+    a("### Docker")
+    a("")
+    a(f"- **base image**: `{dockerfile['from']}`")
+    if dockerfile["ports"]:
+        a(f"- **expose**: {', '.join(f'`{p}`' for p in dockerfile['ports'])}")
+    if dockerfile["entrypoint"]:
+        a(f"- **entrypoint**: `{dockerfile['entrypoint']}`")
+    if dockerfile["labels"]:
+        for k, v in dockerfile["labels"].items():
+            a(f"- **label** `{k}`: {v}")
+    a("")
+
+
+def _render_deployment_docker(dockerfile: dict, compose: dict, L: list[str]) -> None:
+    a = L.append
+    if dockerfile:
+        _render_dockerfile_info(dockerfile, a)
+    if compose.get("services"):
+        a(f"### Docker Compose (`{compose['file']}`)")
+        a("")
+        for svc in compose["services"]:
+            ports_str = (
+                ", ".join(f"`{p}`" for p in svc["ports"]) if svc["ports"] else ""
+            )
+            image_str = f" image=`{svc['image']}`" if svc["image"] else ""
+            a(
+                f"- **{svc['name']}**{image_str}"
+                + (f" ports: {ports_str}" if ports_str else "")
+            )
+        a("")
+
+
+def _render_deployment(
+    pkg_json: dict, name: str, reqs: list, dockerfile: dict, compose: dict
+) -> list[str]:
+    L: list[str] = []
+    a = L.append
+    a("## Deployment")
+    a("")
+    _render_deployment_install(pkg_json, name, L)
+    _render_deployment_reqs(reqs, L)
+    _render_deployment_docker(dockerfile, compose, L)
+    return L
+
+
+# ---------------------------------------------------------------------------
+# Section class
+# ---------------------------------------------------------------------------
+
+
+class DeploymentSection:
+    name = "deployment"
+    level = 2
+    profiles = frozenset({"light", "rich"})
+
+    def should_render(self, ctx: RenderContext) -> bool:
+        return True
+
+    def render(self, ctx: RenderContext) -> list[str]:
+        return _render_deployment(
+            ctx.pkg_json, ctx.name, ctx.reqs, ctx.dockerfile, ctx.compose
+        )
+
+
+assert isinstance(DeploymentSection(), Section)