sourcecode 2.5.5__tar.gz → 2.5.6__tar.gz

{sourcecode-2.5.5 → sourcecode-2.5.6}/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## [2.5.6] — 2026-07-17
+
+**A layer must be attested by code.** The architecture fallback chain reported
+directories as architecture; measured on the field-test repos, every fabricated
+claim rested on files that are not code.
+
+### Fixed
+
+- **Build and asset directories were reported as modules (P1-D-REMAINING)**
+  (`reconciliation.py`, `architecture_analyzer.py`, `summarizer.py`):
+
+  | repo | claimed | what it rested on |
+  |---|---|---|
+  | ofbiz | *"modular: docker, framework, runtime, gradle"* | shell scripts, a wrapper jar, a `.gitignore` |
+  | neo4j | *"modular: packaging, annotations, community"* | `packaging/` is a build directory |
+  | eureka | *"modular: …, images, …"* | five PNGs |
+  | openmrs | *"modular: …, webapp, monitoring"* | GIFs and yaml |
+  | petclinic | *"Layered Architecture with orchestration, data layers"* | ONE directory entry and a `settings.gradle` — with 47 Java files visible and ignored |
+  | jobrunr | *"Fullstack with frontend, backend layers"* | a JVM library; the "frontend" is `dashboard/ui/model/`, **16 Java files** |
+
+  Two new Evidence Reconciliation rules, mirror images of each other and both
+  applied to the duplicated layer tables (architecture prose + headline):
+
+  - **`layer_code_attestation`** — a claimed MODULE or logical code layer that
+    holds no code of the repo's runtime is not one. Stricter sibling of
+    `layer_language_coherence`, which deliberately ignores runtime-less layers
+    so that a real Spring-MVC `templates/` view survives: a view may be
+    templates, a module may not.
+  - **`composition_runtime_split`** — a pattern that IS the split must show it.
+    `fullstack` names a frontend TIER and a backend TIER; if every layer runs on
+    one runtime, the layer names are a directory-name coincidence. Not applied
+    to `monorepo`/`microservices` — an all-TypeScript monorepo, or same-runtime
+    services, are perfectly real.
+
+  petclinic's stem-based layering is Python-shaped (`cli.py`, `*_analyzer.py`,
+  `config.py`) and matches almost nothing in Java, which is why two stray hits
+  could mint a whole "Layered Architecture".
+
+- **Module names that never name a module** (`architecture_analyzer.py`): the
+  reverse-DNS package roots every JVM repo starts its namespace with
+  (`org`/`com`/`io`/`net` — jobrunr reported a module called *"org"*) and
+  multi-release source sets (`src/main/java17` minted *"java17"*; now as
+  transparent as `java/`). Same class as the `core` already excluded.
+
+Validation across 10 field-test repos through the real CLI: ofbiz →
+*"framework, applications"* (its two real modules); neo4j → *"annotations,
+community"*; eureka → its eight real `eureka-*` modules; openmrs → *"web,
+test-suite, api, liquibase"*; jobrunr → *"modular: jobrunr, language-support,
+framework-support"* (its real top-level directories); **petclinic emits no
+architecture claim at all** — the fabricated line is gone while every true
+statement survives (*"Java server-side mvc web app using Spring Boot,
+Thymeleaf"*, frameworks, bootstrap annotation). Broadleaf, alfresco, keycloak
+and jenkins: byte-identical prose.
+
+Investigated and refuted along the way: these claims are NOT built on a
+truncated file list — the analyzer sees 100% of petclinic's Java and 99.4% of
+ofbiz's.
+
+11 new tests; suite 3448 passed.
+
 ## [2.5.5] — 2026-07-16
 
 **An architecture claim must belong to one program.** Third Evidence

{sourcecode-2.5.5 → sourcecode-2.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.5
+Version: 2.5.6
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-2.5.5 → sourcecode-2.5.6}/pyproject.toml

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

{sourcecode-2.5.5 → sourcecode-2.5.6}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.5.5"
+__version__ = "2.5.6"

{sourcecode-2.5.5 → sourcecode-2.5.6}/src/sourcecode/architecture_analyzer.py

@@ -4,7 +4,11 @@ import re
 from pathlib import Path
 from typing import Literal, Optional
 
-from sourcecode.reconciliation import incoherent_layers
+from sourcecode.reconciliation import (
+    incoherent_layers,
+    pattern_contradicted,
+    unattested_layers,
+)
 
 from sourcecode.schema import (
     ArchitectureAnalysis,
@@ -41,11 +45,27 @@ _SRC_TRANSPARENT = {
     "src", "lib", "app", "pkg",
     "main", "java", "kotlin", "scala", "groovy",
 }
+
+# `src/main/java17/` is a MULTI-RELEASE source set, as transparent as `java/`
+# — JobRunr's minted a module called "java17".
+_VERSIONED_SRC_RE = re.compile(r"^(?:java|kotlin|scala)\d+$")
+
+
+def _is_transparent_segment(name: str) -> bool:
+    """A path segment that carries no architectural meaning of its own."""
+    low = name.lower()
+    return low in _SRC_TRANSPARENT or bool(_VERSIONED_SRC_RE.match(low))
 _CODE_EXTENSIONS = {
     ".py", ".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs",
     ".go", ".java", ".kt", ".rs", ".rb",
 }
-_GENERIC_NAMES = {"utils", "helpers", "common", "shared", "misc", "core", "root", ""}
+# Names that never identify a module: generic buckets, and the reverse-DNS
+# package roots every JVM repo starts its namespace with (JobRunr reported a
+# module called "org").
+_GENERIC_NAMES = {
+    "utils", "helpers", "common", "shared", "misc", "core", "root", "",
+    "org", "com", "io", "net",
+}
 
 _TEST_DIRS: frozenset[str] = frozenset({
     "tests", "test", "spec", "specs", "__tests__", "e2e",
@@ -671,14 +691,18 @@ class ArchitectureAnalyzer:
             # reconciliation rule drops layers owned by a different runtime;
             # template/asset-only layers are untouched, so a real Spring-MVC
             # `templates/` view survives.
-            for _bad in incoherent_layers(
-                pattern_name,
-                {k: [source_paths[i] for i in v] for k, v in layer_files.items()},
-                source_paths,
-            ):
+            _layer_paths = {k: [source_paths[i] for i in v] for k, v in layer_files.items()}
+            for _bad in incoherent_layers(pattern_name, _layer_paths, source_paths):
                 matched.pop(_bad, None)
                 layer_files.pop(_bad, None)
 
+            # A claim that IS a runtime split must show one: JobRunr, a JVM
+            # library, read "Fullstack with frontend, backend layers" off a
+            # `dashboard/ui/model/` package of 16 Java files. Nothing to prune —
+            # the pattern itself is what the evidence contradicts.
+            if pattern_contradicted(pattern_name, _layer_paths, source_paths):
+                continue
+
             # A pattern with unmet required keys cannot qualify (e.g. mvc needs a view).
             required = _PATTERN_REQUIRED_KEYS.get(pattern_name)
             if required and not required.issubset(matched.keys()):
@@ -842,6 +866,14 @@ class ArchitectureAnalyzer:
             k: v for k, v in layer_files.items()
             if v and (not total or len(v) / total >= _LAYER_MIN_SHARE)
         }
+        # P1-D residue: these stem patterns are Python-shaped (cli.py,
+        # *_analyzer.py, config.py). On a Java repo almost nothing matches, so
+        # the few stray hits are not a layering — petclinic's "Layered
+        # Architecture with orchestration, data layers" rested on ONE directory
+        # entry plus a settings.gradle, with 47 Java files visible and ignored.
+        # A logical code layer that holds no code of this repo is not one.
+        for _bad in unattested_layers(non_empty, paths):
+            non_empty.pop(_bad, None)
         if len(non_empty) >= 2:
             return "layered", [
                 ArchitectureLayer(name=k, pattern="layered", files=v, confidence="low")
@@ -861,13 +893,19 @@ class ArchitectureAnalyzer:
         for p in paths:
             parts = p.replace("\\", "/").split("/")
             for part in parts[:-1]:
-                if (part not in _SRC_TRANSPARENT
+                if (not _is_transparent_segment(part)
                         and part.lower() not in _NON_SOURCE_DIRS
                         and part.lower() not in _GENERIC_NAMES):
                     module_files.setdefault(part, []).append(p)
                     break
 
         meaningful = {k: v for k, v in module_files.items() if len(v) >= 3}
+        # P1-D residue: a MODULE of this repo must hold this repo's code. File
+        # count alone let build and asset directories be reported as modules —
+        # ofbiz "docker, framework, runtime, gradle", neo4j "packaging",
+        # eureka "images" (five PNGs). The real modules survive untouched.
+        for _bad in unattested_layers(meaningful, paths):
+            meaningful.pop(_bad, None)
         if len(meaningful) >= 2:
             return "modular", [
                 ArchitectureLayer(name=k, pattern="modular", files=v, confidence="low")

{sourcecode-2.5.5 → sourcecode-2.5.6}/src/sourcecode/reconciliation.py

@@ -223,6 +223,15 @@ _CROSS_RUNTIME_PATTERNS: frozenset[str] = frozenset({
     "fullstack", "microservices", "monorepo",
 })
 
+# Patterns whose meaning IS the runtime split — a "fullstack" repo names a
+# frontend TIER and a backend TIER. If every layer runs on the same runtime
+# there is no split, and the claim is a directory-name coincidence: JobRunr, a
+# JVM library, read "Fullstack with frontend, backend layers" off a
+# `dashboard/ui/model/` package holding 16 JAVA files. (Not monorepo or
+# microservices: an all-TypeScript monorepo, or same-runtime services, are
+# perfectly real.)
+_SPLIT_REQUIRED_PATTERNS: frozenset[str] = frozenset({"fullstack"})
+
 
 def runtime_census(layer_files: dict[str, list[str]]) -> dict[str, dict[str, int]]:
     """{layer -> {runtime_family -> file count}} — the language evidence view.
@@ -288,6 +297,91 @@ def _rule_layer_language_coherence(
     ]
 
 
+def _rule_layer_code_attestation(
+    census: dict[str, dict[str, int]],
+    repo_runtimes: dict[str, int],
+) -> list[ReconciliationFinding]:
+    """A claimed code module holds no code of the repo's runtime.
+
+    Stricter sibling of `layer_language_coherence`, for claims whose layers are
+    modules or logical code layers — their whole role is to hold code, so a
+    directory with none is not one of them. (`layer_language_coherence` cannot
+    serve here: it deliberately ignores layers with no runtime files at all, so
+    that a real Spring-MVC `templates/` view survives. A view may be templates;
+    a MODULE may not.)
+
+    Measured on the field-test repos: ofbiz's "modular architecture" listed
+    `docker`, `gradle`, `runtime` and `themes` (shell scripts, wrapper jars, a
+    .gitignore, images — zero Java); neo4j listed `packaging`; eureka listed
+    `images` (five PNGs); petclinic's whole "Layered Architecture with
+    orchestration, data layers" rested on one directory entry and a
+    settings.gradle.
+    """
+    if not repo_runtimes:
+        return []
+    dominant = max(sorted(repo_runtimes), key=lambda f: repo_runtimes[f])
+    unattested = sorted(
+        layer for layer, counts in census.items() if not counts.get(dominant)
+    )
+    if not unattested:
+        return []
+    return [
+        ReconciliationFinding(
+            rule="layer_code_attestation",
+            symbols=tuple(unattested),
+            detail=(
+                f"{len(unattested)} claimed layer(s) hold no {dominant} code — "
+                "a directory without the repo's code is not a module of it."
+            ),
+        )
+    ]
+
+
+def _rule_composition_runtime_split(
+    pattern: str,
+    census: dict[str, dict[str, int]],
+) -> list[ReconciliationFinding]:
+    """A pattern that names a runtime split shows none.
+
+    The mirror image of `layer_language_coherence`: a claim about one program
+    must NOT span runtimes; a claim that IS the split must show it. Silent
+    unless the pattern's layers carry runtime evidence at all.
+    """
+    if pattern not in _SPLIT_REQUIRED_PATTERNS or len(census) < 2:
+        return []
+    families = {fam for counts in census.values() for fam in counts}
+    if len(families) != 1:
+        return []  # a real split, or no runtime evidence to judge
+    only = next(iter(families))
+    return [
+        ReconciliationFinding(
+            rule="composition_runtime_split",
+            symbols=tuple(sorted(census)),
+            detail=(
+                f"the '{pattern}' claim names a runtime split but every layer is "
+                f"{only} — the layer names are a coincidence, not two tiers."
+            ),
+        )
+    ]
+
+
+def unattested_layers(
+    layer_files: dict[str, list[str]], repo_files: "list[str]"
+) -> frozenset[str]:
+    """Layers holding no code of the repo's runtime (convenience view).
+
+    For consumers claiming code modules / logical code layers. Never raises.
+    """
+    try:
+        repo_runtimes = runtime_census({"_repo": list(repo_files)})["_repo"]
+        out: set[str] = set()
+        for f in _rule_layer_code_attestation(runtime_census(layer_files), repo_runtimes):
+            out.update(f.symbols)
+        return frozenset(out)
+    except Exception:
+        return frozenset()
+
+
 def reconcile_architecture_evidence(
     *,
     pattern: str,
@@ -304,17 +398,34 @@ def reconcile_architecture_evidence(
     """
     findings: list[ReconciliationFinding] = []
     try:
+        census = runtime_census(layer_files)
         repo_runtimes = runtime_census({"_repo": list(repo_files)})["_repo"]
         findings.extend(
-            _rule_layer_language_coherence(
-                pattern, runtime_census(layer_files), repo_runtimes
-            )
+            _rule_layer_language_coherence(pattern, census, repo_runtimes)
         )
+        findings.extend(_rule_composition_runtime_split(pattern, census))
     except Exception:
         pass
     return findings
 
 
+def pattern_contradicted(
+    pattern: str, layer_files: dict[str, list[str]], repo_files: "list[str]"
+) -> bool:
+    """True when a rule rejects the PATTERN itself, not just some of its layers.
+
+    `incoherent_layers` prunes layers and lets the pattern re-qualify on what
+    is left; a split-less "fullstack" has nothing to re-qualify with — the
+    claim as a whole is the thing contradicted.
+    """
+    return any(
+        f.rule == "composition_runtime_split"
+        for f in reconcile_architecture_evidence(
+            pattern=pattern, layer_files=layer_files, repo_files=repo_files
+        )
+    )
+
+
 def incoherent_layers(
     pattern: str, layer_files: dict[str, list[str]], repo_files: "list[str]"
 ) -> frozenset[str]:

{sourcecode-2.5.5 → sourcecode-2.5.6}/src/sourcecode/summarizer.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from typing import Any
 
 from sourcecode.architecture_analyzer import _LAYER_MIN_SHARE, _PATTERN_REQUIRED_KEYS
-from sourcecode.reconciliation import incoherent_layers
+from sourcecode.reconciliation import incoherent_layers, pattern_contradicted
 from sourcecode.detectors.parsers import load_json_file, load_toml_file
 from sourcecode.tree_utils import safe_read_text
 from sourcecode.entrypoint_classifier import is_production_entry_point
@@ -439,6 +439,8 @@ class ProjectSummarizer:
             # two duplicated tables leaves the other one lying.
             for _bad in incoherent_layers(pattern_name, layer_files, file_paths):
                 layer_files.pop(_bad, None)
+            if pattern_contradicted(pattern_name, layer_files, file_paths):
+                continue
             # A pattern must show its defining trait here too, or the headline
             # contradicts the architecture prose that already enforces this.
             required = _PATTERN_REQUIRED_KEYS.get(pattern_name)