sourcecode 1.53.0__tar.gz → 1.54.0__tar.gz

{sourcecode-1.53.0 → sourcecode-1.54.0}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [1.54.0] — 2026-06-19
+
+### Added
+- **`export --c4` now emits `components.module_roots` — architectural module
+  enumeration + DDD/legacy classification.** Field test (saint-server C4 doc pass)
+  surfaced that the C4 export keyed modules by *leaf source directory*
+  (`dirname(source_file)`), so a DDD module split across
+  `domain/` / `application/` / `infrastructure/` subdirs fragmented into several
+  unrelated "modules". A downstream consumer had to infer module boundaries from
+  directory names, which produced a module **undercount** and **DDD-vs-legacy
+  misclassification** in the generated docs.
+
+  Fix: `_detect_module_roots()` rolls leaf dirs up to their architectural module
+  root (the directory above the shallowest recognized layer dir) and classifies
+  each `layered` (≥2 of `domain`/`application`/`infrastructure`) vs `flat`
+  (legacy/flat package). `c4.components.module_roots` carries the per-module
+  `{root, pattern, layers, symbol_count, leaf_dir_count}` plus a summary with a
+  verifiable `module_count` / `layered_module_count` / `flat_module_count`, so a
+  consumer enumerates real modules instead of guessing.
+
+  Pure-structural (no extra file reads). Non-breaking: top-level `c4` keys and the
+  leaf-level `--module-graph` dependency view are unchanged. 3 regression tests
+  (layered rollup, flat classification, summary counts).
+
 ## [1.50.0] — 2026-06-17
 
 ### Fixed

{sourcecode-1.53.0 → sourcecode-1.54.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.53.0
+Version: 1.54.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.53.0-blue)
+![Version](https://img.shields.io/badge/version-1.54.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 ---
@@ -404,7 +404,7 @@ Emits **structured, tool-agnostic** codebase views as plain JSON/YAML — the ki
 | `--by-directory` | One group per source directory, each symbol with a `source_file:line` reference. |
 | `--module-graph` | `{nodes, edges, summary}` — directories as modules, inter-module dependencies rolled up from class-level relation edges with hit counts + edge types. |
 | `--integrations` | Outbound integrations (`RestTemplate`, `WebClient`, `@FeignClient`, `LdapTemplate`, `JmsTemplate`, ActiveMQ) with `file:line` evidence and a literal `target` URL/name when present. |
-| `--c4` | Unified document: `c4.{context, containers, components, code}` + `api_surface` + a `manifest` with per-directory content hashes for **incremental** consumers (skip directories whose hash is unchanged). |
+| `--c4` | Unified document: `c4.{context, containers, components, code}` + `api_surface` + a `manifest` with per-directory content hashes for **incremental** consumers (skip directories whose hash is unchanged). `components.module_roots` rolls leaf source dirs up to architectural module roots and classifies each `layered` (DDD: ≥2 of `domain`/`application`/`infrastructure`) vs `flat` (legacy/flat package), with a verifiable `module_count` — so a consumer enumerates real modules instead of inferring boundaries from leaf directories. |
 
 The section flags compose (pass several for one multi-section document); `--c4` assembles the full export on its own. URLs assembled at runtime yield `target: null` (honest absence, never a guess); containers are derived from build files (Maven/Gradle) and reported as a limitation when none are found.
 

{sourcecode-1.53.0 → sourcecode-1.54.0}/README.md

@@ -2,7 +2,7 @@
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.53.0-blue)
+![Version](https://img.shields.io/badge/version-1.54.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 ---
@@ -366,7 +366,7 @@ Emits **structured, tool-agnostic** codebase views as plain JSON/YAML — the ki
 | `--by-directory` | One group per source directory, each symbol with a `source_file:line` reference. |
 | `--module-graph` | `{nodes, edges, summary}` — directories as modules, inter-module dependencies rolled up from class-level relation edges with hit counts + edge types. |
 | `--integrations` | Outbound integrations (`RestTemplate`, `WebClient`, `@FeignClient`, `LdapTemplate`, `JmsTemplate`, ActiveMQ) with `file:line` evidence and a literal `target` URL/name when present. |
-| `--c4` | Unified document: `c4.{context, containers, components, code}` + `api_surface` + a `manifest` with per-directory content hashes for **incremental** consumers (skip directories whose hash is unchanged). |
+| `--c4` | Unified document: `c4.{context, containers, components, code}` + `api_surface` + a `manifest` with per-directory content hashes for **incremental** consumers (skip directories whose hash is unchanged). `components.module_roots` rolls leaf source dirs up to architectural module roots and classifies each `layered` (DDD: ≥2 of `domain`/`application`/`infrastructure`) vs `flat` (legacy/flat package), with a verifiable `module_count` — so a consumer enumerates real modules instead of inferring boundaries from leaf directories. |
 
 The section flags compose (pass several for one multi-section document); `--c4` assembles the full export on its own. URLs assembled at runtime yield `target: null` (honest absence, never a guess); containers are derived from build files (Maven/Gradle) and reported as a limitation when none are found.
 

{sourcecode-1.53.0 → sourcecode-1.54.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.53.0"
+version = "1.54.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.53.0 → sourcecode-1.54.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.53.0"
+__version__ = "1.54.0"

{sourcecode-1.53.0 → sourcecode-1.54.0}/src/sourcecode/cli.py

@@ -4137,6 +4137,82 @@ def _directory_hashes(file_list: "list[str]", root: "Path") -> "dict[str, str]":
     return out
 
 
+# Architectural layer directory names used to recognize a layered module
+# (DDD / hexagonal). The module *root* is the directory directly above the
+# shallowest layer dir, so symbols living in domain/application/infrastructure
+# subdirs all roll up to one module — a consumer counts modules, not leaf dirs.
+_LAYER_MARKERS: "frozenset[str]" = frozenset({
+    "domain", "application", "infrastructure",
+    "interfaces", "presentation", "adapters", "ports", "api",
+})
+# Core DDD layers — presence of >=2 marks a module as DDD-layered vs flat/legacy.
+_DDD_CORE_LAYERS: "frozenset[str]" = frozenset({
+    "domain", "application", "infrastructure",
+})
+
+
+def _module_root_of(leaf_dir: "str") -> "tuple[str, str | None]":
+    """Map a leaf source directory to its architectural module root.
+
+    For a layered module ``<root>/<layer>/...`` the root is the path above the
+    shallowest recognized layer dir, and the layer name is returned alongside.
+    Flat directories (no layer marker) are their own root with a ``None`` layer.
+    Pure-structural — no file reads.
+    """
+    parts = leaf_dir.split("/")
+    for i, seg in enumerate(parts):
+        if seg.lower() in _LAYER_MARKERS:
+            return "/".join(parts[:i]) or ".", seg.lower()
+    return leaf_dir, None
+
+
+def _detect_module_roots(by_directory: "dict[str, list]") -> "dict":
+    """Roll leaf source dirs up to architectural module roots and classify them.
+
+    Resolves the leaf-directory-vs-module mismatch in the C4 component view: a
+    DDD module split across ``domain/`` / ``application/`` / ``infrastructure/``
+    subdirs is reported once, with its layers and a structural ``pattern``
+    (``layered`` when it carries >=2 core DDD layers, else ``flat``). Gives a
+    downstream consumer a verifiable module enumeration and a DDD-vs-legacy
+    signal instead of forcing it to infer module boundaries from directory names.
+    """
+    roots: "dict[str, dict]" = {}
+    for leaf, symbols in by_directory.items():
+        root, layer = _module_root_of(leaf)
+        slot = roots.setdefault(
+            root, {"layers": set(), "symbol_count": 0, "leaf_dirs": 0}
+        )
+        if layer:
+            slot["layers"].add(layer)
+        slot["symbol_count"] += len(symbols)
+        slot["leaf_dirs"] += 1
+
+    modules: "list[dict]" = []
+    layered = flat = 0
+    for root in sorted(roots):
+        s = roots[root]
+        pattern = "layered" if len(s["layers"] & _DDD_CORE_LAYERS) >= 2 else "flat"
+        if pattern == "layered":
+            layered += 1
+        else:
+            flat += 1
+        modules.append({
+            "root": root,
+            "pattern": pattern,
+            "layers": sorted(s["layers"]),
+            "symbol_count": s["symbol_count"],
+            "leaf_dir_count": s["leaf_dirs"],
+        })
+    return {
+        "modules": modules,
+        "summary": {
+            "module_count": len(modules),
+            "layered_module_count": layered,
+            "flat_module_count": flat,
+        },
+    }
+
+
 def _build_c4_export(
     root: "Path",
     file_list: "list[str]",
@@ -4155,6 +4231,9 @@ def _build_c4_export(
     """
     by_directory = _group_symbols_by_directory(nodes)
     module_graph = _build_module_graph(nodes, edges)
+    # Architectural module-root rollup + DDD/legacy classification, so a
+    # consumer counts/classifies modules instead of inferring them from leaf dirs.
+    module_graph["module_roots"] = _detect_module_roots(by_directory)
     api_surface = _group_endpoints_by_controller(endpoints)
     containers = _detect_containers(root)