sumd 0.3.4__tar.gz → 0.3.6__tar.gz

{sumd-0.3.4 → sumd-0.3.6}/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.6] - 2026-04-19
+
+### Docs
+- Update README.md
+
+### Other
+- Update sumd/cli.py
+
+## [0.3.5] - 2026-04-19
+
+### Docs
+- Update README.md
+- Update SUMD.md
+- Update SUMR.md
+- Update docs/README.md
+- Update docs/USAGE.md
+- Update examples/README.md
+- Update examples/basic/README.md
+- Update examples/basic/sample-project/README.md
+- Update examples/basic/sample-project/SUMD.md
+- Update examples/integrations/README.md
+- ... and 5 more files
+
+### Test
+- Update tests/test_cli.py
+- Update tests/test_mcp_server.py
+
+### Other
+- Update Taskfile.yml
+- Update examples/basic/demo.sh
+- Update examples/basic/sample-project/Taskfile.yml
+- Update examples/basic/sample-project/goal.yaml
+- Update examples/basic/sample-project/openapi.yaml
+- Update examples/basic/sample-project/project/map.toon.yaml
+- Update examples/basic/sample-project/pyproject.toml
+- Update examples/basic/sample-project/sumd.json
+- Update examples/integrations/Dockerfile
+- Update examples/integrations/docker-compose.yml
+- ... and 23 more files
+
 ## [0.3.4] - 2026-04-19
 
 ### Docs

{sumd-0.3.4 → sumd-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sumd
-Version: 0.3.4
+Version: 0.3.6
 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
@@ -25,6 +25,7 @@ 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: mcp>=1.0.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'
@@ -37,41 +38,45 @@ Description-Content-Type: text/markdown
 
 # SUMD
 
+
 ## AI Cost Tracking
 
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$5.10-yellow) ![AI Model](https://img.shields.io/badge/AI%20Model-openrouter%2Fqwen%2Fqwen3-coder-next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.3.6-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-$5.40-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-13.1h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-This project uses AI-generated code. Total cost: **$5.1000** with **34** AI commits.
+- 🤖 **LLM usage:** $5.4000 (36 commits)
+- 👤 **Human dev:** ~$1306 (13.1h @ $100/h, 30min dedup)
 
-Generated on 2026-04-19 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/models/openrouter/qwen/qwen3-coder-next)
+Generated on 2026-04-19 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
+![Version](https://img.shields.io/badge/version-0.3.6-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.4-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-
-
-
-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.
+**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.
 
 ## 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.
+SUMD is a lightweight structured markdown format that serves as a **single source of truth** for project documentation — optimised for both human readability and LLM context injection.
+
+Think of it as a machine-readable README: a file an AI agent can parse, reason over, and act upon.
 
 ### 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
+- **Project descriptor** — defines API, CLI, workflows, endpoints, and system architecture
+- **AI context feed** — structured for LLM consumption: inject `SUMD.md` into any prompt to give the model full project understanding
+- **Lightweight manifest** — bridges the gap between README, openapi spec, and configuration files
+- **Automation anchor** — drives `sumd scan`, `sumd lint`, `sumd scaffold`, CI pipelines
 
 ### Use Cases
 
-- Project documentation and specification
-- Input for LLM context injection
+- Generating structured documentation from source code
+- Single-file project context for ChatGPT, Claude, Gemini, or local LLMs
+- LLM agent memory and tool context (via MCP server)
+- Input for testql scenario scaffolding
+- API and CLI contract documentation
 - CI/CD workflow descriptions
-- API and CLI mapping
 - Structural project manifest
 
 ## Installation

{sumd-0.3.4 → sumd-0.3.6}/README.md

@@ -1,40 +1,44 @@
 # SUMD
 
+
 ## AI Cost Tracking
 
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$5.10-yellow) ![AI Model](https://img.shields.io/badge/AI%20Model-openrouter%2Fqwen%2Fqwen3-coder-next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.3.6-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-$5.40-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-13.1h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-This project uses AI-generated code. Total cost: **$5.1000** with **34** AI commits.
+- 🤖 **LLM usage:** $5.4000 (36 commits)
+- 👤 **Human dev:** ~$1306 (13.1h @ $100/h, 30min dedup)
 
-Generated on 2026-04-19 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/models/openrouter/qwen/qwen3-coder-next)
+Generated on 2026-04-19 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
+![Version](https://img.shields.io/badge/version-0.3.6-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.4-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-
-
-
-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.
+**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.
 
 ## 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.
+SUMD is a lightweight structured markdown format that serves as a **single source of truth** for project documentation — optimised for both human readability and LLM context injection.
+
+Think of it as a machine-readable README: a file an AI agent can parse, reason over, and act upon.
 
 ### 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
+- **Project descriptor** — defines API, CLI, workflows, endpoints, and system architecture
+- **AI context feed** — structured for LLM consumption: inject `SUMD.md` into any prompt to give the model full project understanding
+- **Lightweight manifest** — bridges the gap between README, openapi spec, and configuration files
+- **Automation anchor** — drives `sumd scan`, `sumd lint`, `sumd scaffold`, CI pipelines
 
 ### Use Cases
 
-- Project documentation and specification
-- Input for LLM context injection
+- Generating structured documentation from source code
+- Single-file project context for ChatGPT, Claude, Gemini, or local LLMs
+- LLM agent memory and tool context (via MCP server)
+- Input for testql scenario scaffolding
+- API and CLI contract documentation
 - CI/CD workflow descriptions
-- API and CLI mapping
 - Structural project manifest
 
 ## Installation

{sumd-0.3.4 → sumd-0.3.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sumd"
-version = "0.3.4"
+version = "0.3.6"
 description = "SUMD - Structured Unified Markdown Descriptor for AI-aware project documentation"
 readme = "README.md"
 license = "Apache-2.0"
@@ -44,6 +44,7 @@ dev = [
     "goal>=2.1.0",
     "costs>=0.1.20",
     "pfix>=0.1.60",
+    "mcp>=1.0.0",
 ]
 
 [tool.pytest.ini_options]

{sumd-0.3.4 → sumd-0.3.6}/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.4"
+__version__ = "0.3.6"
 
 from sumd.parser import (
     SUMDDocument,

{sumd-0.3.4 → sumd-0.3.6}/sumd/cli.py

@@ -223,29 +223,74 @@ _SKIP_DIRS = {
 }
 
 
-def _detect_projects(workspace: Path, max_depth: int | None = None) -> list[Path]:
-    """Return sorted list of subdirectories containing pyproject.toml (recursive)."""
-    projects: list[Path] = []
-
-    def _walk(path: Path, depth: int) -> None:
-        if max_depth is not None and depth > max_depth:
-            return
+def _walk_projects(
+    path: Path, projects: list[Path], max_depth: int | None, depth: int
+) -> None:
+    """Recursively collect project directories (containing pyproject.toml)."""
+    if max_depth is not None and depth > max_depth:
+        return
+    try:
+        entries = sorted(path.iterdir(), key=lambda p: p.name)
+    except PermissionError:
+        return
+    for d in entries:
+        if not d.is_dir() or d.name.startswith(".") or d.name in _SKIP_DIRS:
+            continue
         try:
-            entries = sorted(path.iterdir(), key=lambda p: p.name)
-        except PermissionError:
-            return
-        for d in entries:
-            if not d.is_dir() or d.name.startswith(".") or d.name in _SKIP_DIRS:
-                continue
             if (d / "pyproject.toml").exists():
                 projects.append(d)
             else:
-                _walk(d, depth + 1)
+                _walk_projects(d, projects, max_depth, depth + 1)
+        except PermissionError:
+            continue
 
-    _walk(workspace, 0)
+
+def _detect_projects(workspace: Path, max_depth: int | None = None) -> list[Path]:
+    """Return sorted list of subdirectories containing pyproject.toml (recursive)."""
+    projects: list[Path] = []
+    _walk_projects(workspace, projects, max_depth, 0)
     return projects
 
 
+def _ensure_venv(tools_dir: Path, venv_dir: Path, tool_list: list[str]) -> None:
+    """Create virtual env and install tools if not already present."""
+    if venv_dir.exists():
+        return
+    tools_dir.mkdir(exist_ok=True)
+    subprocess.run([sys.executable, "-m", "venv", str(venv_dir)], capture_output=True)
+    pip_path = venv_dir / "bin" / "pip"
+    if not pip_path.exists():
+        pip_path = venv_dir / "Scripts" / "pip.exe"
+    for pkg in tool_list:
+        subprocess.run([str(pip_path), "install", "-q", pkg], capture_output=True)
+
+
+def _tool_bin(bin_dir: Path, name: str) -> Path:
+    """Return path to *name* executable, preferring non-.exe variant."""
+    plain = bin_dir / name
+    return plain if plain.exists() else bin_dir / f"{name}.exe"
+
+
+# Tool-specific CLI argument templates
+_TOOL_ARGS: dict[str, list[str]] = {
+    "code2llm": ["{proj_dir}", "-f", "all", "-o", "{out}", "--no-chunk"],
+    "redup":    ["scan", "{proj_dir}", "--format", "toon", "--output", "{out}"],
+    "vallm":    ["batch", "{proj_dir}", "--recursive", "--format", "toon", "--output", "{out}"],
+}
+
+
+def _run_one_tool(tool: str, bin_dir: Path, proj_dir: Path, project_output: Path) -> None:
+    """Run a single analysis tool if its arg template is known."""
+    template = _TOOL_ARGS.get(tool)
+    if template is None:
+        return
+    args = [
+        a.replace("{proj_dir}", str(proj_dir)).replace("{out}", str(project_output))
+        for a in template
+    ]
+    subprocess.run([str(_tool_bin(bin_dir, tool))] + args, capture_output=True, cwd=str(proj_dir))
+
+
 def _run_analysis_tools(
     proj_dir: Path,
     tool_list: list[str],
@@ -261,16 +306,7 @@ def _run_analysis_tools(
     venv_dir = tools_dir / "venv"
     project_output = proj_dir / "project"
 
-    if not venv_dir.exists():
-        tools_dir.mkdir(exist_ok=True)
-        subprocess.run(
-            [sys.executable, "-m", "venv", str(venv_dir)], capture_output=True
-        )
-        pip_path = venv_dir / "bin" / "pip"
-        if not pip_path.exists():
-            pip_path = venv_dir / "Scripts" / "pip.exe"
-        for pkg in tool_list:
-            subprocess.run([str(pip_path), "install", "-q", pkg], capture_output=True)
+    _ensure_venv(tools_dir, venv_dir, tool_list)
 
     bin_dir = venv_dir / "bin"
     if not bin_dir.exists():
@@ -278,56 +314,9 @@ def _run_analysis_tools(
 
     project_output.mkdir(exist_ok=True)
 
-    if "code2llm" in tool_list and "code2llm" not in skip_tools:
-        code2llm = bin_dir / (
-            "code2llm.exe" if not (bin_dir / "code2llm").exists() else "code2llm"
-        )
-        subprocess.run(
-            [
-                str(code2llm),
-                str(proj_dir),
-                "-f",
-                "all",
-                "-o",
-                str(project_output),
-                "--no-chunk",
-            ],
-            capture_output=True,
-            cwd=str(proj_dir),
-        )
-
-    if "redup" in tool_list and "redup" not in skip_tools:
-        redup = bin_dir / ("redup.exe" if not (bin_dir / "redup").exists() else "redup")
-        subprocess.run(
-            [
-                str(redup),
-                "scan",
-                str(proj_dir),
-                "--format",
-                "toon",
-                "--output",
-                str(project_output),
-            ],
-            capture_output=True,
-            cwd=str(proj_dir),
-        )
-
-    if "vallm" in tool_list and "vallm" not in skip_tools:
-        vallm = bin_dir / ("vallm.exe" if not (bin_dir / "vallm").exists() else "vallm")
-        subprocess.run(
-            [
-                str(vallm),
-                "batch",
-                str(proj_dir),
-                "--recursive",
-                "--format",
-                "toon",
-                "--output",
-                str(project_output),
-            ],
-            capture_output=True,
-            cwd=str(proj_dir),
-        )
+    for tool in tool_list:
+        if tool not in skip_tools:
+            _run_one_tool(tool, bin_dir, proj_dir, project_output)
 
 
 def _export_sumd_json(proj_dir: Path, doc) -> None:
@@ -370,6 +359,14 @@ def _render_write_validate(
     return doc, md_issues, cb_errors, cb_warnings, sources
 
 
+def _echo_scan_result(proj_dir: Path, doc, sources: list, cb_warnings: list) -> None:
+    """Print success line for a scanned project."""
+    warn_str = f" \u26a0 {len(cb_warnings)} warnings" if cb_warnings else ""
+    click.echo(
+        f"  \u2705 {proj_dir.name:<18} {'ok':<10} {len(doc.sections):<10} {', '.join(sources)}{warn_str}"
+    )
+
+
 def _scan_one_project(
     proj_dir: Path,
     fix: bool,
@@ -405,10 +402,7 @@ def _scan_one_project(
                 click.echo(f"       \u2193 {e}")
             return {"status": "INVALID", "errors": all_errors, "path": str(sumd_path)}
 
-        warn_str = f" \u26a0 {len(cb_warnings)} warnings" if cb_warnings else ""
-        click.echo(
-            f"  \u2705 {proj_dir.name:<18} {'ok':<10} {len(doc.sections):<10} {', '.join(sources)}{warn_str}"
-        )
+        _echo_scan_result(proj_dir, doc, sources, cb_warnings)
 
         if export_json:
             _export_sumd_json(proj_dir, doc)

{sumd-0.3.4 → sumd-0.3.6}/sumd/extractor.py

@@ -57,6 +57,17 @@ def extract_pyproject(proj_dir: Path) -> dict[str, Any]:
         return {}
 
 
+def _first_task_cmd(cmds: list) -> str:
+    """Extract the first command string from a task's cmds list."""
+    if not cmds:
+        return ""
+    if isinstance(cmds[0], str):
+        return cmds[0]
+    if isinstance(cmds[0], dict):
+        return cmds[0].get("task", cmds[0].get("cmd", ""))
+    return ""
+
+
 def extract_taskfile(proj_dir: Path) -> list[dict[str, str]]:
     taskfile_path = proj_dir / "Taskfile.yml"
     if not taskfile_path.exists():
@@ -69,18 +80,40 @@ def extract_taskfile(proj_dir: Path) -> list[dict[str, str]]:
             if not isinstance(body, dict):
                 continue
             desc = body.get("desc", "")
-            cmds = body.get("cmds", [])
-            cmd = ""
-            if cmds and isinstance(cmds[0], str):
-                cmd = cmds[0]
-            elif cmds and isinstance(cmds[0], dict):
-                cmd = cmds[0].get("task", cmds[0].get("cmd", ""))
+            cmd = _first_task_cmd(body.get("cmds", []))
             result.append({"name": task_name, "desc": desc, "cmd": cmd})
         return result
     except Exception:
         return []
 
 
+def _parse_openapi_endpoints(paths: dict) -> list[dict]:
+    """Extract endpoint dicts from the paths section of an OpenAPI spec."""
+    _HTTP_METHODS = {"get", "post", "put", "delete", "patch"}
+    endpoints: list[dict] = []
+    seen: set[tuple] = set()
+    for path, methods in paths.items():
+        if not isinstance(methods, dict) or "://" in path:
+            continue
+        for method, spec in methods.items():
+            if method not in _HTTP_METHODS or not isinstance(spec, dict):
+                continue
+            key = (method.upper(), path)
+            if key in seen:
+                continue
+            seen.add(key)
+            endpoints.append(
+                {
+                    "method": method.upper(),
+                    "path": path,
+                    "operationId": spec.get("operationId", ""),
+                    "summary": spec.get("summary", ""),
+                    "tags": spec.get("tags", []),
+                }
+            )
+    return endpoints
+
+
 def extract_openapi(proj_dir: Path) -> dict[str, Any]:
     openapi_path = proj_dir / "openapi.yaml"
     if not openapi_path.exists():
@@ -89,35 +122,12 @@ def extract_openapi(proj_dir: Path) -> dict[str, Any]:
         data = yaml.safe_load(openapi_path.read_text(encoding="utf-8"))
         info = data.get("info", {})
         paths = data.get("paths", {}) or {}
-        endpoints = []
-        seen: set[tuple] = set()
-        for path, methods in paths.items():
-            if not isinstance(methods, dict) or "://" in path:
-                continue
-            for method, spec in methods.items():
-                if method not in ("get", "post", "put", "delete", "patch"):
-                    continue
-                if not isinstance(spec, dict):
-                    continue
-                key = (method.upper(), path)
-                if key in seen:
-                    continue
-                seen.add(key)
-                endpoints.append(
-                    {
-                        "method": method.upper(),
-                        "path": path,
-                        "operationId": spec.get("operationId", ""),
-                        "summary": spec.get("summary", ""),
-                        "tags": spec.get("tags", []),
-                    }
-                )
         schemas = list((data.get("components", {}) or {}).get("schemas", {}).keys())
         return {
             "title": info.get("title", ""),
             "version": info.get("version", ""),
             "description": info.get("description", ""),
-            "endpoints": endpoints,
+            "endpoints": _parse_openapi_endpoints(paths),
             "schemas": schemas,
         }
     except Exception:
@@ -369,6 +379,22 @@ def extract_env(proj_dir: Path) -> list[dict[str, str]]:
     return vars_
 
 
+def _parse_dockerfile_line(line: str, parsed: dict) -> None:
+    """Update *parsed* dict in-place with one Dockerfile instruction."""
+    upper = line.upper()
+    if upper.startswith("FROM ") and not parsed["from"]:
+        parsed["from"] = line[5:].strip()
+    elif upper.startswith("EXPOSE "):
+        parsed["ports"].extend(line[7:].strip().split())
+    elif upper.startswith("ENTRYPOINT "):
+        parsed["entrypoint"] = line[11:].strip()
+    elif upper.startswith("CMD "):
+        parsed["cmd"] = line[4:].strip()
+    elif upper.startswith("LABEL "):
+        for kv in re.findall(r'(\w[\w.-]*)=("(?:[^"\\]|\\.)*"|\S+)', line[6:]):
+            parsed["labels"][kv[0]] = kv[1].strip('"')
+
+
 def extract_dockerfile(proj_dir: Path) -> dict[str, Any]:
     """Parse Dockerfile — base image, exposed ports, entrypoint, labels."""
     for candidate in (proj_dir / "Dockerfile", proj_dir / "docker" / "Dockerfile"):
@@ -378,29 +404,14 @@ def extract_dockerfile(proj_dir: Path) -> dict[str, Any]:
     else:
         return {}
     content = dockerfile_path.read_text(encoding="utf-8")
-    from_image = ""
-    ports: list[str] = []
-    entrypoint = ""
-    cmd = ""
-    labels: dict[str, str] = {}
+    parsed: dict = {"from": "", "ports": [], "entrypoint": "", "cmd": "", "labels": {}}
     for line in content.splitlines():
-        line = line.strip()
-        if line.upper().startswith("FROM ") and not from_image:
-            from_image = line[5:].strip()
-        elif line.upper().startswith("EXPOSE "):
-            ports.extend(line[7:].strip().split())
-        elif line.upper().startswith("ENTRYPOINT "):
-            entrypoint = line[11:].strip()
-        elif line.upper().startswith("CMD "):
-            cmd = line[4:].strip()
-        elif line.upper().startswith("LABEL "):
-            for kv in re.findall(r'(\w[\w.-]*)=("(?:[^"\\]|\\.)*"|\S+)', line[6:]):
-                labels[kv[0]] = kv[1].strip('"')
+        _parse_dockerfile_line(line.strip(), parsed)
     return {
-        "from": from_image,
-        "ports": ports,
-        "entrypoint": entrypoint or cmd,
-        "labels": labels,
+        "from": parsed["from"],
+        "ports": parsed["ports"],
+        "entrypoint": parsed["entrypoint"] or parsed["cmd"],
+        "labels": parsed["labels"],
     }
 
 
@@ -586,6 +597,18 @@ def _analyse_py_top_funcs(
     return exports, funcs
 
 
+def _analyse_class_methods(node: ast.ClassDef, radon_cc: dict) -> list[dict]:
+    """Extract method signatures and metrics from a class node."""
+    methods: list[dict] = []
+    for item in ast.iter_child_nodes(node):
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            margs = [a.arg for a in item.args.args if a.arg != "self"]
+            cc = radon_cc.get(item.name) or _cc_estimate(item)
+            fo = _fan_out(item)
+            methods.append({"name": item.name, "args": margs, "cc": cc, "fan": fo})
+    return methods
+
+
 def _analyse_py_top_classes(
     tree: ast.AST, radon_cc: dict[str, int]
 ) -> tuple[list[str], list[dict]]:
@@ -595,19 +618,11 @@ def _analyse_py_top_classes(
     for node in ast.iter_child_nodes(tree):
         if not isinstance(node, ast.ClassDef):
             continue
-        cname = node.name
-        exports.append(cname)
-        methods: list[dict] = []
-        for item in ast.iter_child_nodes(node):
-            if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
-                margs = [a.arg for a in item.args.args if a.arg != "self"]
-                cc = radon_cc.get(item.name) or _cc_estimate(item)
-                fo = _fan_out(item)
-                methods.append({"name": item.name, "args": margs, "cc": cc, "fan": fo})
-        docline = ""
-        if (ast.get_docstring(node) or "").strip():
-            docline = "  # " + (ast.get_docstring(node) or "").splitlines()[0][:60]
-        classes.append({"name": cname, "methods": methods, "doc": docline})
+        exports.append(node.name)
+        methods = _analyse_class_methods(node, radon_cc)
+        doc = (ast.get_docstring(node) or "").strip()
+        docline = ("  # " + doc.splitlines()[0][:60]) if doc else ""
+        classes.append({"name": node.name, "methods": methods, "doc": docline})
     return exports, classes
 
 
@@ -629,6 +644,14 @@ def _analyse_py_module(path: Path) -> dict[str, Any]:
     }
 
 
+def _is_map_ignored_path(p: Path) -> bool:
+    """Return True if *p* (relative) contains an ignored directory segment."""
+    for part in p.parts:
+        if part in _IGNORE_DIRS or part.endswith(".egg-info"):
+            return True
+    return False
+
+
 def _collect_map_files(
     proj_dir: Path,
 ) -> tuple[dict[str, int], list[tuple[Path, int, str]]]:
@@ -636,14 +659,8 @@ def _collect_map_files(
     lang_counts: dict[str, int] = {}
     modules: list[tuple[Path, int, str]] = []  # (path, lines, lang)
 
-    def _should_skip(p: Path) -> bool:
-        for part in p.parts:
-            if part in _IGNORE_DIRS or part.endswith(".egg-info"):
-                return True
-        return False
-
     for f in sorted(proj_dir.rglob("*")):
-        if not f.is_file() or _should_skip(f.relative_to(proj_dir)):
+        if not f.is_file() or _is_map_ignored_path(f.relative_to(proj_dir)):
             continue
         lang = _lang_of(f)
         if lang == "other" or lang not in _SOURCE_LANGS:
@@ -709,6 +726,25 @@ def _map_cc_stats(
     return avg_cc, critical, alerts, hotspots
 
 
+def _render_py_module_detail(rel: Path, info: dict, a) -> None:
+    """Append detail lines for one Python module in map.toon format."""
+    a(f"  {rel}:")
+    if info["exports"]:
+        a(f"    e: {','.join(info['exports'])}")
+    for cls in info["classes"]:
+        method_summary = ",".join(
+            f"{m['name']}({len(m['args'])})" for m in cls["methods"]
+        )
+        doc = cls["doc"]
+        if method_summary:
+            a(f"    {cls['name']}: {method_summary}{doc}")
+        else:
+            a(f"    {cls['name']}:{doc}")
+    for f in info["funcs"]:
+        sig = ";".join(f["args"]) if f["args"] else ""
+        a(f"    {f['name']}({sig})")
+
+
 def generate_map_toon(proj_dir: Path) -> str:
     """Generate project/map.toon.yaml content for proj_dir."""
     proj_dir = proj_dir.resolve()
@@ -755,21 +791,7 @@ def generate_map_toon(proj_dir: Path) -> str:
 
     a("D:")
     for rel, info in py_modules:
-        a(f"  {rel}:")
-        if info["exports"]:
-            a(f"    e: {','.join(info['exports'])}")
-        for cls in info["classes"]:
-            method_summary = ",".join(
-                f"{m['name']}({len(m['args'])})" for m in cls["methods"]
-            )
-            doc = cls["doc"]
-            if method_summary:
-                a(f"    {cls['name']}: {method_summary}{doc}")
-            else:
-                a(f"    {cls['name']}:{doc}")
-        for f in info["funcs"]:
-            sig = ";".join(f["args"]) if f["args"] else ""
-            a(f"    {f['name']}({sig})")
+        _render_py_module_detail(rel, info, a)
 
     return "\n".join(L) + "\n"
 

{sumd-0.3.4 → sumd-0.3.6}/sumd/parser.py

@@ -353,6 +353,35 @@ _MARKPACT_REQUIRED_ATTRS = {
 }
 
 
+def _validate_markpact_meta(
+    mp: re.Match, line_no: int, lang: str, meta: str, issues: list
+) -> None:
+    """Check markpact annotation kind and required attributes."""
+    kind = mp.group("kind")
+    attrs = mp.group("attrs") or ""
+    if kind not in _VALID_MARKPACT_KINDS:
+        issues.append(
+            CodeBlockIssue(
+                line_no,
+                lang,
+                "error",
+                f"unknown markpact kind {kind!r} (valid: {', '.join(sorted(_VALID_MARKPACT_KINDS))})",
+                meta,
+            )
+        )
+    req_attr = _MARKPACT_REQUIRED_ATTRS.get(kind)
+    if req_attr and f"{req_attr}=" not in attrs:
+        issues.append(
+            CodeBlockIssue(
+                line_no,
+                lang,
+                "error",
+                f"markpact:{kind} requires {req_attr}=... but got: {attrs!r}",
+                meta,
+            )
+        )
+
+
 def validate_codeblocks(content: str, source: str = "SUMD.md") -> list[CodeBlockIssue]:
     """Validate all fenced code blocks in *content*.
 
@@ -373,29 +402,7 @@ def validate_codeblocks(content: str, source: str = "SUMD.md") -> list[CodeBlock
         # ── markpact annotation checks ──────────────────────────────────
         mp = _MARKPACT_META_RE.search(meta)
         if mp:
-            kind = mp.group("kind")
-            attrs = mp.group("attrs") or ""
-            if kind not in _VALID_MARKPACT_KINDS:
-                issues.append(
-                    CodeBlockIssue(
-                        line_no,
-                        lang,
-                        "error",
-                        f"unknown markpact kind {kind!r} (valid: {', '.join(sorted(_VALID_MARKPACT_KINDS))})",
-                        meta,
-                    )
-                )
-            req_attr = _MARKPACT_REQUIRED_ATTRS.get(kind)
-            if req_attr and f"{req_attr}=" not in attrs:
-                issues.append(
-                    CodeBlockIssue(
-                        line_no,
-                        lang,
-                        "error",
-                        f"markpact:{kind} requires {req_attr}=... but got: {attrs!r}",
-                        meta,
-                    )
-                )
+            _validate_markpact_meta(mp, line_no, lang, meta, issues)
 
         # ── body emptiness ──────────────────────────────────────────────
         if not body:

{sumd-0.3.4 → sumd-0.3.6}/sumd/pipeline.py

@@ -75,6 +75,25 @@ def _refresh_map_toon(proj_dir: Path) -> None:
         pass  # non-fatal — embed will use the previous file if it exists
 
 
+def _find_tools_bin_dir(proj_dir: Path) -> Path | None:
+    """Return the venv bin directory for .sumd-tools, or None if not installed."""
+    base = proj_dir / ".sumd-tools" / "venv"
+    for subdir in ("bin", "Scripts"):
+        candidate = base / subdir
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _run_tool_if_present(bin_dir: Path, name: str, args: list, proj_dir: Path) -> None:
+    """Run *name* executable with *args* if it exists in *bin_dir*."""
+    exe = bin_dir / name
+    if not exe.exists():
+        exe = bin_dir / f"{name}.exe"
+    if exe.exists():
+        subprocess.run([str(exe)] + args, capture_output=True, cwd=str(proj_dir))
+
+
 def _refresh_analysis_files(proj_dir: Path, profile: str) -> None:
     """Run only the external tools required for the given profile.
 
@@ -88,51 +107,33 @@ def _refresh_analysis_files(proj_dir: Path, profile: str) -> None:
     if not tools_needed:
         return
 
-    bin_dir = proj_dir / ".sumd-tools" / "venv" / "bin"
-    if not bin_dir.exists():
-        bin_dir = proj_dir / ".sumd-tools" / "venv" / "Scripts"
-    if not bin_dir.exists():
+    bin_dir = _find_tools_bin_dir(proj_dir)
+    if not bin_dir:
         return  # tools not installed — skip silently
 
     project_output = proj_dir / "project"
     project_output.mkdir(parents=True, exist_ok=True)
 
-    def _exe(name: str):
-        p = bin_dir / name
-        if not p.exists():
-            p = bin_dir / f"{name}.exe"
-        return p if p.exists() else None
-
     try:
-        # code2llm generates calls.toon, analysis.toon, evolution.toon in one run
         if "code2llm" in tools_needed:
-            exe = _exe("code2llm")
-            if exe:
-                subprocess.run(
-                    [str(exe), "./", "-f", "toon", "-o", str(project_output), "--no-chunk"],
-                    capture_output=True,
-                    cwd=str(proj_dir),
-                )
-
+            _run_tool_if_present(
+                bin_dir, "code2llm",
+                ["./", "-f", "toon", "-o", str(project_output), "--no-chunk"],
+                proj_dir,
+            )
         if "redup" in tools_needed:
-            exe = _exe("redup")
-            if exe:
-                subprocess.run(
-                    [str(exe), "scan", str(proj_dir),
-                     "--format", "toon", "--output", str(project_output)],
-                    capture_output=True,
-                    cwd=str(proj_dir),
-                )
-
+            _run_tool_if_present(
+                bin_dir, "redup",
+                ["scan", str(proj_dir), "--format", "toon", "--output", str(project_output)],
+                proj_dir,
+            )
         if "vallm" in tools_needed:
-            exe = _exe("vallm")
-            if exe:
-                subprocess.run(
-                    [str(exe), "batch", str(proj_dir), "--recursive",
-                     "--format", "toon", "--output", str(project_output)],
-                    capture_output=True,
-                    cwd=str(proj_dir),
-                )
+            _run_tool_if_present(
+                bin_dir, "vallm",
+                ["batch", str(proj_dir), "--recursive",
+                 "--format", "toon", "--output", str(project_output)],
+                proj_dir,
+            )
     except Exception:  # noqa: BLE001
         pass  # non-fatal
 

{sumd-0.3.4 → sumd-0.3.6}/sumd/renderer.py

@@ -453,20 +453,25 @@ def _render_deployment_reqs(reqs: list, L: list[str]) -> None:
         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:
-        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("")
+        _render_dockerfile_info(dockerfile, a)
     if compose.get("services"):
         a(f"### Docker Compose (`{compose['file']}`)")
         a("")
@@ -495,35 +500,45 @@ def _render_deployment(
     return L
 
 
+def _render_makefile_targets(makefile: list, a) -> None:
+    """Append Makefile targets section via *a*."""
+    a("## Makefile Targets")
+    a("")
+    for t in makefile:
+        desc = f" — {t['desc']}" if t["desc"] else ""
+        a(f"- `{t['target']}`{desc}")
+    a("")
+
+
+def _render_pkg_json_scripts(pkg_json: dict, a) -> None:
+    """Append Node.js scripts section via *a*."""
+    a("## Node.js Scripts (`package.json`)")
+    a("")
+    if pkg_json.get("description"):
+        a(pkg_json["description"])
+        a("")
+    for script, cmd in pkg_json["scripts"].items():
+        a(f"- `npm run {script}` — `{cmd}`")
+    a("")
+    if pkg_json.get("dependencies"):
+        a(
+            "**Runtime deps**: "
+            + ", ".join(f"`{d}`" for d in pkg_json["dependencies"][:15])
+        )
+        a("")
+    if pkg_json.get("engines"):
+        for eng, ver in pkg_json["engines"].items():
+            a(f"- **{eng}**: `{ver}`")
+        a("")
+
+
 def _render_extras(makefile: list, pkg_json: dict) -> list[str]:
     L: list[str] = []
     a = L.append
     if makefile:
-        a("## Makefile Targets")
-        a("")
-        for t in makefile:
-            desc = f" — {t['desc']}" if t["desc"] else ""
-            a(f"- `{t['target']}`{desc}")
-        a("")
+        _render_makefile_targets(makefile, a)
     if pkg_json.get("scripts"):
-        a("## Node.js Scripts (`package.json`)")
-        a("")
-        if pkg_json.get("description"):
-            a(pkg_json["description"])
-            a("")
-        for script, cmd in pkg_json["scripts"].items():
-            a(f"- `npm run {script}` — `{cmd}`")
-        a("")
-        if pkg_json.get("dependencies"):
-            a(
-                "**Runtime deps**: "
-                + ", ".join(f"`{d}`" for d in pkg_json["dependencies"][:15])
-            )
-            a("")
-        if pkg_json.get("engines"):
-            for eng, ver in pkg_json["engines"].items():
-                a(f"- **{eng}**: `{ver}`")
-            a("")
+        _render_pkg_json_scripts(pkg_json, a)
     return L
 
 
@@ -637,6 +652,25 @@ def _render_api_stubs(openapi: dict) -> list[str]:
     return L
 
 
+def _render_scenario_contract(sc: dict, a) -> None:
+    """Append contract lines for a single scenario to the output via *a*."""
+    a(f"**`{sc['name']}`**")
+    if sc.get("endpoints"):
+        for ep in sc["endpoints"][:3]:
+            status = ep.get("status", "")
+            op = f" — `{ep['operationId']}`" if ep.get("operationId") else ""
+            a(f"- `{ep['method']} {ep['path']}` → `{status}`{op}")
+    if sc.get("asserts"):
+        for ass in sc["asserts"][:3]:
+            a(f"- assert `{ass['field']} {ass['op']} {ass['expected']}`")
+    if sc.get("performance"):
+        for p in sc["performance"][:2]:
+            a(f"- perf `{p['metric']} < {p['threshold']}`")
+    if sc.get("detectors"):
+        a(f"- detectors: {sc['detectors']}")
+    a("")
+
+
 def _render_test_contracts(scenarios: list) -> list[str]:
     """Render test scenarios as contract signatures — endpoint + key assertions."""
     if not scenarios:
@@ -658,21 +692,7 @@ def _render_test_contracts(scenarios: list) -> list[str]:
         a(f"### {sc_type.title()} ({len(scs)})")
         a("")
         for sc in scs:
-            a(f"**`{sc['name']}`**")
-            if sc.get("endpoints"):
-                for ep in sc["endpoints"][:3]:
-                    status = ep.get("status", "")
-                    op = f" — `{ep['operationId']}`" if ep.get("operationId") else ""
-                    a(f"- `{ep['method']} {ep['path']}` → `{status}`{op}")
-            if sc.get("asserts"):
-                for ass in sc["asserts"][:3]:
-                    a(f"- assert `{ass['field']} {ass['op']} {ass['expected']}`")
-            if sc.get("performance"):
-                for p in sc["performance"][:2]:
-                    a(f"- perf `{p['metric']} < {p['threshold']}`")
-            if sc.get("detectors"):
-                a(f"- detectors: {sc['detectors']}")
-            a("")
+            _render_scenario_contract(sc, a)
     return L
 
 
@@ -695,6 +715,32 @@ def _parse_calls_header(lines: list[str]) -> dict:
     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] = []
@@ -706,21 +752,8 @@ def _parse_calls_hubs(lines: list[str]) -> list[dict]:
             continue
         if in_hubs and line and not line.startswith(" "):
             in_hubs = False
-        if in_hubs and line.startswith("  ") and not line.startswith("    "):
-            if current_hub:
-                hubs.append(current_hub)
-            current_hub = {"name": line.strip()}
-        elif in_hubs and line.startswith("    "):
-            m = re.search(r"CC=(\d+)\s+in:(\d+)\s+out:(\d+)\s+total:(\d+)", line)
-            if m and current_hub:
-                current_hub.update(
-                    {
-                        "cc": int(m.group(1)),
-                        "in": int(m.group(2)),
-                        "out": int(m.group(3)),
-                        "total": int(m.group(4)),
-                    }
-                )
+        if in_hubs:
+            current_hub = _process_in_hubs_line(line, hubs, current_hub)
     if current_hub:
         hubs.append(current_hub)
     return hubs
@@ -786,6 +819,31 @@ def _render_call_graph(project_analysis: list) -> list[str]:
 # ---------------------------------------------------------------------------
 
 
+def _collect_tool_sources(
+    pyproj: dict, reqs: list, tasks: list, makefile: list, scenarios: list
+) -> list[str]:
+    """Collect source labels for file-based tool inputs."""
+    sources: list[str] = []
+    if pyproj:
+        sources.append("pyproject.toml")
+    if reqs:
+        sources.extend(r["file"] for r in reqs)
+    if tasks:
+        sources.append("Taskfile.yml")
+    if makefile:
+        sources.append("Makefile")
+    if scenarios:
+        sources.append(f"testql({len(scenarios)})")
+    return sources
+
+
+def _doql_sources(doql: dict) -> list[str]:
+    """Return doql source labels if any doql content is present."""
+    if doql.get("app") or doql.get("workflows") or doql.get("entities"):
+        return doql.get("sources", ["app.doql.less"])
+    return []
+
+
 def _collect_pkg_sources(
     pyproj: dict,
     reqs: list,
@@ -799,21 +857,10 @@ def _collect_pkg_sources(
     env_vars: list,
 ) -> list[str]:
     """Collect source labels for code/pipeline sources."""
-    sources: list[str] = []
-    if pyproj:
-        sources.append("pyproject.toml")
-    if reqs:
-        sources.extend(r["file"] for r in reqs)
-    if tasks:
-        sources.append("Taskfile.yml")
-    if makefile:
-        sources.append("Makefile")
-    if scenarios:
-        sources.append(f"testql({len(scenarios)})")
+    sources = _collect_tool_sources(pyproj, reqs, tasks, makefile, scenarios)
     if openapi.get("endpoints"):
         sources.append(f"openapi({len(openapi['endpoints'])} ep)")
-    if doql.get("app") or doql.get("workflows") or doql.get("entities"):
-        sources.extend(doql.get("sources", ["app.doql.less"]))
+    sources.extend(_doql_sources(doql))
     if pyqual.get("stages"):
         sources.append("pyqual.yaml")
     if goal.get("name"):