sourcecode 2.5.4__tar.gz → 2.5.5__tar.gz

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

@@ -1,5 +1,61 @@
 # Changelog
 
+## [2.5.5] — 2026-07-16
+
+**An architecture claim must belong to one program.** Third Evidence
+Reconciliation rule, extending the layer from the impact/extraction surfaces to
+the narrative one.
+
+### Fixed
+
+- **A React SPA supplied the "view layer" of a Java MVC claim (SIM-3)**
+  (`reconciliation.py`, `architecture_analyzer.py`, `summarizer.py`): keycloak
+  read *"MVC pattern with controller, model, view layers"* — the `view` was
+  `js/apps/*/src/components` (87 `.tsx`, zero Java), half the `controller` layer
+  was the Kubernetes operator's reconcile controllers, and both sat beside a
+  1088-file Java `model`. Directory names are language-blind, so one pattern was
+  assembled across two separate programs; P1-D's mass gate cannot catch it,
+  because the SPA has genuine mass.
+
+  New rule **`layer_language_coherence`** — the layer table cross-checked
+  against the file-language census. A layer is incoherent iff it holds ZERO
+  files of the repo's runtime and at least one file of another: it is a
+  different program, not a facet of this architecture. Runtimes are grouped by
+  FAMILY (`.java`/`.kt`/`.scala`/`.groovy` = one JVM program), so a Kotlin view
+  beside a Java model is never a contradiction. A layer holding no runtime files
+  at all (templates, assets) is never flagged — that carve-out is what keeps a
+  genuine Spring-MVC `templates/` view intact. Patterns describing repo
+  COMPOSITION rather than one program's internals (`fullstack`,
+  `microservices`, `monorepo`) are exempt: spanning runtimes is their point.
+  The dominant runtime is taken from the whole repo, never from the matched
+  layers — which directories match a keyword table is the thing under
+  suspicion, so it cannot also be the arbiter. Applied to BOTH duplicated layer
+  tables (architecture prose + headline), since fixing one leaves the other
+  lying.
+
+- **"core" minted an onion/hexagonal domain layer (P1-D residue)**
+  (`architecture_analyzer.py`, `summarizer.py`): P1-D removed the keywords that
+  do not attest their role (`api`, `store`, `db`) from the layered/fullstack/mvc
+  tables but left `core` in onion/hexagonal. `core` names a module's importance,
+  never a domain layer, and nearly every large JVM repo has one: keycloak's
+  `core/` (623 Java files) plus a `representations/adapters/config` package read
+  *"Onion Architecture with domain, adapters layers"*.
+
+- **Hexagonal was claimed without ports (P1-D residue)**
+  (`architecture_analyzer.py`, `summarizer.py`): a pattern must show its
+  defining trait, not just any two of its layers — the mechanism that already
+  requires a `view` for MVC. Hexagonal is literally "Ports and Adapters", yet
+  `models/` + `adapters/` alone was minting it; onion now requires its domain
+  centre. The headline's table enforces required keys too, so it can no longer
+  contradict the architecture prose.
+
+Validation across 10 field-test repos through the real CLI: keycloak's false
+MVC claim became *"Monorepo workspace with apps, packages layers"* — verified
+true in source (`js/apps/{admin-ui,account-ui}`, `js/libs/*`,
+`pnpm-workspace.yaml`). Broadleaf (layered, all four layers), petclinic,
+jobrunr, neo4j, openmrs, eureka, alfresco, ofbiz and jenkins: byte-identical
+prose, zero collateral. 18 new tests; suite 3440 passed.
+
 ## [2.5.4] — 2026-07-16
 
 **Evidence reconciliation + the endpoint axis.** The keycloak real-use simulacro

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.4
+Version: 2.5.5
 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.4 → sourcecode-2.5.5}/pyproject.toml

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

{sourcecode-2.5.4 → sourcecode-2.5.5}/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.4"
+__version__ = "2.5.5"

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

@@ -4,6 +4,8 @@ import re
 from pathlib import Path
 from typing import Literal, Optional
 
+from sourcecode.reconciliation import incoherent_layers
+
 from sourcecode.schema import (
     ArchitectureAnalysis,
     ArchitectureDomain,
@@ -139,8 +141,14 @@ LAYER_PATTERNS: dict[str, dict[str, list[str]]] = {
         "application":    ["application", "usecases", "usecase"],
         "infrastructure": ["infrastructure", "infra", "adapters", "persistence"],
     },
+    # P1-D residue (found by measurement, 2026-07-16): "core" belongs with
+    # "api"/"store"/"db" — it names a module's importance ("the main module"),
+    # never an onion/hexagonal DOMAIN layer, and nearly every large JVM repo has
+    # one. With it, keycloak's `core/` (623 Java files) + a
+    # `representations/adapters/config` package read "Onion Architecture with
+    # domain, adapters layers". Kept are the names that state their role.
     "onion": {
-        "domain":      ["domain", "core"],
+        "domain":      ["domain"],
         "application": ["application", "usecases"],
         "ports":       ["ports", "interfaces"],
         "adapters":    ["adapters", "secondary"],
@@ -173,7 +181,7 @@ LAYER_PATTERNS: dict[str, dict[str, list[str]]] = {
     "hexagonal": {
         "port":    ["port", "ports", "interface", "interfaces"],
         "adapter": ["adapter", "adapters"],
-        "domain":  ["domain", "core", "model", "models"],
+        "domain":  ["domain", "model", "models"],  # "core" dropped — see onion
     },
     "monorepo": {
         "apps":     ["apps", "applications"],
@@ -196,6 +204,13 @@ LAYER_PATTERNS: dict[str, dict[str, list[str]]] = {
 # it; without it the pattern falls through to layered / a weaker match.
 _PATTERN_REQUIRED_KEYS: dict[str, frozenset[str]] = {
     "mvc": frozenset({"view"}),
+    # Same principle as MVC/view — a pattern must show its DEFINING trait, not
+    # just any two of its layers. Hexagonal is literally "Ports and Adapters":
+    # a `models/` package next to an `adapters/` package is not one, and that
+    # pair alone was enough to label keycloak "Hexagonal Architecture". Onion's
+    # defining trait is the domain at the centre.
+    "hexagonal": frozenset({"port", "adapter"}),
+    "onion": frozenset({"domain"}),
 }
 
 # Minimum share of source files a matched layer must hold to count as a LAYER
@@ -646,6 +661,24 @@ class ArchitectureAnalyzer:
                     continue
                 matched[layer_key] = matched_dirs
                 layer_files[layer_key] = files
+
+            # SIM-3: a layer must belong to the same PROGRAM as the rest of the
+            # claim. Directory names are language-blind, so on a polyglot
+            # monorepo one pattern was assembled across two subsystems: keycloak
+            # read "MVC with controller, model, view layers" where `view` was a
+            # React SPA (87 .tsx, zero Java) sitting beside a 1088-file Java
+            # `model`. Mass cannot catch this — the SPA has genuine mass. The
+            # 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,
+            ):
+                matched.pop(_bad, None)
+                layer_files.pop(_bad, None)
+
             # 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()):

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

@@ -34,12 +34,21 @@ Rule registry (extraction):
         declarations the regex extractor cannot bind, e.g. `public class\n
         Name` split across lines, Unicode type identifiers).
 
+Rule registry (architecture):
+    layer_language_coherence — a directory-name-matched layer holds NO file in
+        the runtime that carries the rest of the claimed pattern, while being
+        owned by a DIFFERENT runtime. The layer table and the file-language
+        census are contradicting each other: the "architecture" spans two
+        subsystems (SIM-3: keycloak's "MVC … view layer" was a React SPA, zero
+        Java files, sitting beside a 1088-file Java model).
+
 Never raises. Empty evidence → no findings.
 """
 from __future__ import annotations
 
 import re
 from dataclasses import dataclass
+from pathlib import Path
 
 
 @dataclass(frozen=True)
@@ -182,6 +191,142 @@ def _rule_parse_coverage(
     ]
 
 
+# ---------------------------------------------------------------------------
+# Architecture reconciliation (layer table × file-language census)
+# ---------------------------------------------------------------------------
+
+# Source extension → RUNTIME FAMILY. Grouping by runtime, not by extension, is
+# what makes the rule correct: a Kotlin `view/` beside Java `model/` is ONE
+# system (same runtime, direct interop) and must not be called a contradiction,
+# while a TypeScript `view/` beside them is a separate program. Extensions
+# absent here (.html/.ftl/.jsp/.css/.xml …) are deliberately unmapped: a
+# template or asset carries no runtime of its own, so it can never contradict a
+# claim — that carve-out is what keeps a genuine Spring-MVC `templates/` view
+# layer intact.
+_RUNTIME_FAMILY: dict[str, str] = {
+    ".java": "jvm", ".kt": "jvm", ".kts": "jvm", ".scala": "jvm", ".groovy": "jvm",
+    ".js": "js", ".jsx": "js", ".ts": "js", ".tsx": "js", ".mjs": "js", ".cjs": "js",
+    ".py": "python",
+    ".go": "go",
+    ".rs": "rust",
+    ".rb": "ruby",
+    ".cs": "dotnet",
+    ".php": "php",
+    ".swift": "swift",
+}
+
+# Patterns that describe REPO COMPOSITION rather than one program's internal
+# architecture — their layers are SUPPOSED to span runtimes, so the coherence
+# rule must never fire on them. (mvc/layered/onion/hexagonal/clean are claims
+# about a single program and must hold together in one runtime.)
+_CROSS_RUNTIME_PATTERNS: frozenset[str] = frozenset({
+    "fullstack", "microservices", "monorepo",
+})
+
+
+def runtime_census(layer_files: dict[str, list[str]]) -> dict[str, dict[str, int]]:
+    """{layer -> {runtime_family -> file count}} — the language evidence view.
+
+    Files whose extension carries no runtime (templates, assets, config) are
+    simply absent from the census; a layer made only of them yields {}.
+    """
+    out: dict[str, dict[str, int]] = {}
+    for layer, files in layer_files.items():
+        counts: dict[str, int] = {}
+        for f in files:
+            fam = _RUNTIME_FAMILY.get(Path(str(f)).suffix.lower())
+            if fam:
+                counts[fam] = counts.get(fam, 0) + 1
+        out[layer] = counts
+    return out
+
+
+def _rule_layer_language_coherence(
+    pattern: str,
+    census: dict[str, dict[str, int]],
+    repo_runtimes: dict[str, int],
+) -> list[ReconciliationFinding]:
+    """A claimed layer is owned by a different runtime than the repo it describes.
+
+    The dominant runtime is taken from the WHOLE repo, not from the matched
+    layers: which directories happen to match a keyword table is exactly the
+    thing under suspicion, so it cannot also be the arbiter. (Measured: on a
+    Java backend beside a React SPA, layer-local dominance can invert — the SPA
+    out-matches the backend's one matched layer and the JAVA layer gets flagged.)
+
+    A layer is INCOHERENT iff it holds ZERO files of the repo's runtime AND at
+    least one file of another — it is a different program, not a facet of this
+    one. A layer with no runtime files at all (templates, assets) is never
+    flagged: it does not contradict, it just does not attest.
+
+    Silent for cross-runtime patterns, whose layers are meant to span runtimes.
+    """
+    if pattern in _CROSS_RUNTIME_PATTERNS or len(census) < 2:
+        return []
+    if len(repo_runtimes) < 2:
+        return []  # single-runtime repo — nothing to contradict
+
+    dominant = max(sorted(repo_runtimes), key=lambda f: repo_runtimes[f])
+
+    incoherent = sorted(
+        layer for layer, counts in census.items()
+        if not counts.get(dominant) and any(counts.values())
+    )
+    if not incoherent:
+        return []
+    return [
+        ReconciliationFinding(
+            rule="layer_language_coherence",
+            symbols=tuple(incoherent),
+            detail=(
+                f"{len(incoherent)} layer(s) of the '{pattern}' claim hold no "
+                f"{dominant} file while the rest of the pattern is {dominant} — "
+                "the claim spans two separate programs, so it does not describe "
+                "one architecture."
+            ),
+        )
+    ]
+
+
+def reconcile_architecture_evidence(
+    *,
+    pattern: str,
+    layer_files: dict[str, list[str]],
+    repo_files: "list[str]",
+) -> list[ReconciliationFinding]:
+    """Run architecture reconciliation rules. Never raises.
+
+    Args:
+        pattern:     candidate pattern name (e.g. "mvc").
+        layer_files: {layer -> files matched for that layer}.
+        repo_files:  every source file considered — supplies the repo's own
+                     runtime, the arbiter of which layers belong to the claim.
+    """
+    findings: list[ReconciliationFinding] = []
+    try:
+        repo_runtimes = runtime_census({"_repo": list(repo_files)})["_repo"]
+        findings.extend(
+            _rule_layer_language_coherence(
+                pattern, runtime_census(layer_files), repo_runtimes
+            )
+        )
+    except Exception:
+        pass
+    return findings
+
+
+def incoherent_layers(
+    pattern: str, layer_files: dict[str, list[str]], repo_files: "list[str]"
+) -> frozenset[str]:
+    """Layer names the coherence rule rejects for `pattern` (convenience view)."""
+    out: set[str] = set()
+    for f in reconcile_architecture_evidence(
+        pattern=pattern, layer_files=layer_files, repo_files=repo_files
+    ):
+        out.update(f.symbols)
+    return frozenset(out)
+
+
 def reconcile_extraction_evidence(
     *,
     type_decl_files: frozenset[str],

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

@@ -8,7 +8,8 @@ No API calls — templates applied directly over SourceMap.
 from pathlib import Path
 from typing import Any
 
-from sourcecode.architecture_analyzer import _LAYER_MIN_SHARE
+from sourcecode.architecture_analyzer import _LAYER_MIN_SHARE, _PATTERN_REQUIRED_KEYS
+from sourcecode.reconciliation import incoherent_layers
 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
@@ -62,7 +63,9 @@ _ARCH_LAYER_PATTERNS: dict[str, dict[str, list[str]]] = {
     "hexagonal": {
         "port": ["ports", "interfaces"],
         "adapter": ["adapters"],
-        "domain": ["domain", "core", "models"],
+        # P1-D residue: "core" names a module's importance, not a domain layer
+        # (keycloak `core/` = 623 Java files). Keep in step with the analyzer.
+        "domain": ["domain", "models"],
     },
     "fullstack": {
         "frontend": ["frontend", "client", "web", "ui", "pages", "components"],
@@ -415,16 +418,33 @@ class ProjectSummarizer:
                 dir_files.setdefault(seg.lower(), set()).add(i)
         total = len(file_paths)
 
-        def _has_mass(keywords: list[str]) -> bool:
+        def _layer_paths(keywords: list[str]) -> list[str]:
             files: set[int] = set()
             for d in keywords:
                 files |= dir_files.get(d, set())
-            return bool(files) and (not total or len(files) / total >= _LAYER_MIN_SHARE)
+            if not files or (total and len(files) / total < _LAYER_MIN_SHARE):
+                return []
+            return [file_paths[i] for i in sorted(files)]
 
         best_pattern: str | None = None
         best_score = 0
         for pattern_name, layer_keys in _ARCH_LAYER_PATTERNS.items():
-            score = sum(1 for keywords in layer_keys.values() if _has_mass(keywords))
+            layer_files: dict[str, list[str]] = {}
+            for layer, keywords in layer_keys.items():
+                paths = _layer_paths(keywords)
+                if paths:
+                    layer_files[layer] = paths
+            # SIM-3: same coherence rule the architecture prose applies — this
+            # table is the headline's copy, and a fix applied to only one of the
+            # two duplicated tables leaves the other one lying.
+            for _bad in incoherent_layers(pattern_name, layer_files, file_paths):
+                layer_files.pop(_bad, None)
+            # 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)
+            if required and not required.issubset(layer_files.keys()):
+                continue
+            score = len(layer_files)
             if score > best_score:
                 best_score = score
                 best_pattern = pattern_name