sourcecode 2.5.4__tar.gz → 2.5.6__tar.gz

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

@@ -1,5 +1,121 @@
 # 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
+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.6}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.5.4"
+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.4 → 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.4"
+__version__ = "2.5.6"

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

@@ -4,6 +4,12 @@ import re
 from pathlib import Path
 from typing import Literal, Optional
 
+from sourcecode.reconciliation import (
+    incoherent_layers,
+    pattern_contradicted,
+    unattested_layers,
+)
+
 from sourcecode.schema import (
     ArchitectureAnalysis,
     ArchitectureDomain,
@@ -39,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",
@@ -139,8 +161,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 +201,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 +224,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 +681,28 @@ 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.
+            _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()):
@@ -809,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")
@@ -828,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")