sourcecode 2.5.5__tar.gz → 2.5.7__tar.gz

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

@@ -1,5 +1,143 @@
 # Changelog
 
+## [2.5.7] — 2026-07-17
+
+**A framework claim must be attested by its own runtime.** The `examples` repo
+read *"C#/.NET rest api using JAX-RS."* — a JVM-only framework attributed to a
+.NET headline, self-contradictory inside a single clause. This release closes the
+last of the narrative cluster, and settles how reconciliation findings reach the
+surfaces that report them.
+
+### Fixed
+
+- **A polyglot repository was narrated as one program (P2-F)**
+  (`reconciliation.py`, `architecture_summary.py`): the sentence was assembled
+  from two unrelated sources —
+
+  | part | comes from | on `examples` |
+  |---|---|---|
+  | `C#/.NET` | the **primary** stack | dotnet, root `.`, declares **zero** frameworks |
+  | `using JAX-RS` | **every** stack | java, workspace `microservices-orders`, the sole owner of JAX-RS |
+
+  New Evidence Reconciliation rule **`framework_stack_attestation`**: a framework
+  named in a single-program headline whose owning stacks are all of another
+  runtime family contradicts the claim. Ownership is already structural — a
+  `FrameworkDetection` is discovered inside the `StackDetection` whose manifest
+  declares it — so the rule reasons from evidence and never from what a framework
+  is called. Grouped by runtime family, so a Kotlin framework beside Java is one
+  program; `fullstack`/`monorepo`/`microservices` are exempt, their headline is
+  meant to span runtimes.
+
+  The type label had to go with it. `project_type` is decided by frameworks
+  pooled across every stack, while a separate vote picks the primary, so
+  *"rest api"* was java's evidence too — dropping only the `using` clause would
+  have left *"C#/.NET rest api."*, the same claim one clause shorter. The
+  headline now degrades to what is actually known:
+
+  > C#/.NET project. Polyglot repository: the rest api evidence (JAX-RS) is
+  > declared by the Java stack, not by C#/.NET — no single stack owns this
+  > repository's architecture. See `stacks`.
+
+  Every fact survives, correctly attributed.
+
+- **The structured fields kept asserting what the sentence had retracted
+  (P2-F-RESIDUE(a))** (`confidence_analyzer.py`, `reconciliation.py`):
+  `project_type` and `primary_stack` are read on their own by agents that never
+  see the prose, and on `examples` they still said `"api"` + `"dotnet"` silently.
+  `ConfidenceAnalyzer` now consumes the same rule, emitting an
+  `analysis_gaps` entry (`area="framework_stack_attestation"`) plus an anomaly
+  beside its existing "ambiguous primary" siblings.
+
+  `project_type` deliberately keeps its value: the classifier's vote is a
+  separate decision, and minting a *"polyglot"* type here would silently rewrite
+  what every consumer branches on. Flagging the claim is honest; changing the
+  field is a different change.
+
+### Internal
+
+- `_FRAMEWORK_DRIVEN_TYPES` moved out of `architecture_summary` into
+  `reconciliation.type_claim_unattested()`. Two surfaces must judge *"did the
+  frameworks decide this type"* identically — a duplicated table is how the
+  headline kept lying in the first place.
+- `ReconciliationFinding.detail` is now **sink-neutral**. It used to narrate
+  itself (*"framework(s) named in the headline … the sentence attributes them
+  to"*), which the rule that strips the claim promptly made false. Details are
+  read by prose and by structured gaps alike; none may assume prose.
+
+Validation across 12 field-test repos through the real CLI: `examples` emits the
+degraded headline, the gap and the anomaly (*"JAX-RS declared by another runtime,
+not by the dotnet primary stack"*); petclinic, keycloak, eureka, jobrunr, ofbiz,
+jenkins, broadleaf, alfresco, openmrs, neo4j and spaghetti-api are **silent —
+every headline byte-identical**, no gap, no anomaly. Every control's primary
+stack declares its own frameworks, which is exactly why the rule stays quiet.
+
+Measured along the way, and worth knowing: on a polyglot repo the **primary stack
+is a coin flip** — `max(stacks, …)` breaks an exact tie between java and dotnet
+(both manifest-detected, both high-confidence) by list order, and the narrative
+then welded the loser's evidence onto the winner's label.
+
+14 new tests; suite 3462 passed, 5 skipped.
+
+## [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.7}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.5.5"
+version = "2.5.7"
 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.7}/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.7"

{sourcecode-2.5.5 → sourcecode-2.5.7}/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.7}/src/sourcecode/architecture_summary.py

@@ -205,6 +205,22 @@ class ArchitectureSummarizer:
                 for f in s.frameworks[:2]
             ))[:3]
 
+        # F-1 reconciliation: the headline describes ONE program, but fw_names is
+        # gathered from every stack in the repo. On a polyglot repository that
+        # welds a foreign runtime's framework onto the primary's label. Drop what
+        # the claimed stack does not attest, and never let the TYPE label — which
+        # those same frameworks drove — survive its own evidence (P2-F).
+        from sourcecode.reconciliation import type_claim_unattested, unattested_frameworks
+
+        foreign = unattested_frameworks(primary.stack, sm.project_type, sm.stacks)
+        attested = [name for name in fw_names if name not in foreign]
+        dropped = [name for name in fw_names if name in foreign]
+        if dropped and not attested and type_claim_unattested(
+            claimed_stack=primary.stack, project_type=sm.project_type, stacks=sm.stacks
+        ):
+            return self._describe_foreign_evidence(sm, stack_label, runtime, dropped)
+        fw_names = attested
+
         fw_str = f" using {', '.join(fw_names)}" if fw_names else ""
         if runtime:
             # BUG #4: never assert "rest api" in the headline unless the endpoints
@@ -237,6 +253,29 @@ class ArchitectureSummarizer:
             return f"{stack_label} {runtime.lower()}{fw_str}."
         return f"{stack_label} project{fw_str}."
 
+    def _describe_foreign_evidence(
+        self, sm: SourceMap, stack_label: str, runtime: str, dropped: list[str]
+    ) -> str:
+        """Headline for a claim whose defining evidence belongs to another stack.
+
+        Says what IS known instead of asserting a program that does not exist:
+        the primary stack, the foreign frameworks, and the stacks that actually
+        declare them. The reader gets the same facts, correctly attributed.
+        """
+        from sourcecode.context_summarizer import _STACK_LABELS
+        from sourcecode.reconciliation import framework_owner_stacks
+
+        owners = framework_owner_stacks(sm.stacks)
+        owner_ids = sorted({sid for name in dropped for sid in owners.get(name, ())})
+        owner_labels = [_STACK_LABELS.get(sid, sid) for sid in owner_ids] or ["another"]
+        plural = "s" if len(owner_labels) > 1 else ""
+        return (
+            f"{stack_label} project. Polyglot repository: the {runtime.lower()} "
+            f"evidence ({', '.join(dropped)}) is declared by the "
+            f"{', '.join(owner_labels)} stack{plural}, not by {stack_label} — no "
+            "single stack owns this repository's architecture. See `stacks`."
+        )
+
     def _endpoint_support(self) -> tuple[int, int]:
         """Return (total, high_confidence) endpoint counts from the canonical
         Java endpoint extractor — the same source the `endpoints` command uses,
@@ -412,41 +451,51 @@ class ArchitectureSummarizer:
         return None
 
     def _summarize_dotnet_entry(self, stacks: list[StackDetection]) -> list[str]:
+        # P2-F-RESIDUE(c): every line here counts .csproj files — facts about the
+        # .NET stack ALONE. Unscoped, they read as claims about the repository:
+        # the confluent examples monorepo (20+ subprojects, mostly Java/Python/Go)
+        # reported a bare "1 project detected." beside a headline that had just
+        # called it polyglot. Naming the stack costs one word and makes each line
+        # true on any repo, so no polyglot test is needed to decide the wording.
+        from sourcecode.context_summarizer import _STACK_LABELS
+
         dotnet_stacks = [s for s in stacks if s.stack == "dotnet"]
         if not dotnet_stacks:
             return []
+        label = _STACK_LABELS.get("dotnet", "dotnet")  # same table as the headline
         lines: list[str] = []
         signals = [sig for s in dotnet_stacks for sig in s.signals]
 
         for sig in signals:
             if "project" in sig and "detected" in sig:
-                lines.append(sig[0].upper() + sig[1:] + ".")
+                count = sig.split(" ", 1)[0]
+                lines.append(f"{label} projects: {count}.")
                 break
 
         for sig in signals:
             if sig.startswith("project types:"):
                 types = sig.removeprefix("project types:").strip()
-                lines.append(f"Stack: {types}.")
+                lines.append(f"{label} project types: {types}.")
                 break
 
         for sig in signals:
             if sig.startswith("target frameworks:"):
                 fws = sig.removeprefix("target frameworks:").strip()
-                lines.append(f"Target: {fws}.")
+                lines.append(f"{label} target frameworks: {fws}.")
                 break
 
         for sig in signals:
             if sig.startswith("architecture:"):
                 pattern = sig.removeprefix("architecture:").strip()
-                lines.append(f"Patrón detectado: {pattern}.")
+                lines.append(f"{label} solution pattern: {pattern}.")
                 break
 
         framework_names = [f.name for s in dotnet_stacks for f in s.frameworks]
         if framework_names:
-            lines.append(f"Frameworks: {', '.join(framework_names)}.")
+            lines.append(f"{label} frameworks: {', '.join(framework_names)}.")
 
         if not lines:
-            lines.append("Solución .NET detectada.")
+            lines.append(f"{label} solution detected.")
         return lines
 
     def _summarize_go_entry(self, path: str, content: str) -> list[str]:

{sourcecode-2.5.5 → sourcecode-2.5.7}/src/sourcecode/confidence_analyzer.py

@@ -102,6 +102,45 @@ class ConfidenceAnalyzer:
         if heuristic_only and not any(s.detection_method != "heuristic" for s in sm.stacks):
             anomalies.append("All stacks detected via heuristic only — no manifest found")
 
+        # ── Anomaly: a claim attributed to a stack that does not attest it ────
+        # F-1 reconciliation, second sink. The headline degrades itself
+        # (architecture_summary), but `project_type` and `primary_stack` are
+        # separate structured fields an agent can read on their own — and they
+        # keep asserting the claim this rule refutes. Same rule, same judgement,
+        # different surface: here it becomes an anomaly + gap instead of prose.
+        if primary_stacks:
+            from sourcecode.reconciliation import (
+                reconcile_headline_evidence,
+                type_claim_unattested,
+            )
+
+            _primary = primary_stacks[0]
+            for _rf in reconcile_headline_evidence(
+                claimed_stack=_primary.stack,
+                project_type=sm.project_type,
+                stacks=sm.stacks,
+            ):
+                anomalies.append(
+                    f"{', '.join(_rf.symbols)} declared by another runtime, not by the "
+                    f"{_primary.stack} primary stack"
+                )
+                _reason = _rf.detail
+                if type_claim_unattested(
+                    claimed_stack=_primary.stack,
+                    project_type=sm.project_type,
+                    stacks=sm.stacks,
+                ):
+                    _reason += (
+                        f' project_type="{sm.project_type}" rests on that same evidence — '
+                        f"it is not attested for the {_primary.stack} primary stack, and "
+                        "the repository is polyglot rather than one program."
+                    )
+                gaps.append(AnalysisGap(
+                    area=_rf.rule,
+                    reason=_reason,
+                    impact="medium",
+                ))
+
         # ── Anomaly: entry points all low-confidence ──────────────────────────
         if normalized_entry_points and all(ep.confidence == "low" for ep in normalized_entry_points):
             anomalies.append("All entry points are low-confidence (heuristic/code_signal only)")