sourcecode 2.5.6__tar.gz → 2.5.7__tar.gz

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

@@ -1,5 +1,83 @@
 # 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

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

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

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

{sourcecode-2.5.6 → 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.6 → 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)")

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

@@ -42,6 +42,15 @@ Rule registry (architecture):
         subsystems (SIM-3: keycloak's "MVC … view layer" was a React SPA, zero
         Java files, sitting beside a 1088-file Java model).
 
+Rule registry (narrative):
+    framework_stack_attestation — the headline welds a stack label to a
+        framework that no stack of that runtime declares. The stack table and
+        the framework-ownership view are contradicting each other: the sentence
+        describes one program while the evidence names two (P2-F: the confluent
+        examples repo read "C#/.NET rest api using JAX-RS" — a JVM framework,
+        declared by a Java stack in one sub-workspace, attributed to a .NET
+        primary that declares no framework at all).
+
 Never raises. Empty evidence → no findings.
 """
 from __future__ import annotations
@@ -438,6 +447,188 @@ def incoherent_layers(
     return frozenset(out)
 
 
+# ---------------------------------------------------------------------------
+# Narrative reconciliation (headline claim × stack ownership)
+# ---------------------------------------------------------------------------
+
+# Stack identifier → RUNTIME FAMILY. Same reasoning as `_RUNTIME_FAMILY` above,
+# applied to the stack ontology instead of file extensions: a Kotlin framework
+# named in a Java headline is ONE program (same runtime, direct interop), while a
+# Java framework named in a .NET headline is a different one. Stacks absent here
+# are deliberately unjudgeable: an unknown stack can never prove a contradiction.
+_STACK_FAMILY: dict[str, str] = {
+    "java": "jvm", "kotlin": "jvm", "scala": "jvm", "groovy": "jvm",
+    "nodejs": "js", "deno": "js", "bun": "js",
+    "python": "python",
+    "go": "go",
+    "rust": "rust",
+    "ruby": "ruby",
+    "dotnet": "dotnet",
+    "php": "php",
+    "swift": "swift",
+    "dart": "dart",
+    "elixir": "beam", "erlang": "beam",
+}
+
+# Project types that are SUPPOSED to span runtimes — their headline names a tier
+# split, so a framework from another runtime is the point, not a contradiction.
+# Same carve-out (and same names) as `_CROSS_RUNTIME_PATTERNS` for layer claims.
+_CROSS_RUNTIME_TYPES = _CROSS_RUNTIME_PATTERNS
+
+# Project types DRIVEN by framework presence: `_classify_project_type` pools
+# frameworks across every stack to pick them, while a separate vote picks the
+# primary stack — so on a polyglot repo the type can be decided by one stack's
+# evidence and reported as another's. When the frameworks that drove the type are
+# all foreign to the primary, the type inherits their lie: the sentence
+# "C#/.NET rest api" is the same claim as "using JAX-RS", one clause shorter.
+# Lives here, not in a consumer: BOTH the headline and the confidence/gap surface
+# must judge this identically or the duplicated table lies again.
+_FRAMEWORK_DRIVEN_TYPES: frozenset[str] = frozenset({
+    "api", "webapp", "web_mvc", "angular-spa",
+})
+
+
+def framework_owner_stacks(stacks) -> dict[str, frozenset[str]]:
+    """{framework name -> stack ids that declare it} — the ownership view.
+
+    Ownership is already structural: a FrameworkDetection is discovered inside a
+    StackDetection's manifests, so which runtime a framework belongs to is
+    evidence the detector recorded, never a name lookup (VAI-safe — no rule here
+    branches on what the framework is called).
+    """
+    out: dict[str, set[str]] = {}
+    for stack in stacks or []:
+        sid = getattr(stack, "stack", "") or ""
+        if not sid:
+            continue
+        for fw in getattr(stack, "frameworks", None) or []:
+            name = getattr(fw, "name", "") or ""
+            if name:
+                out.setdefault(name, set()).add(sid)
+    return {name: frozenset(ids) for name, ids in out.items()}
+
+
+def framework_owner_families(stacks) -> dict[str, frozenset[str]]:
+    """{framework name -> runtime families that declare it} — the ownership view."""
+    return {
+        name: frozenset(
+            fam for sid in ids if (fam := _STACK_FAMILY.get(sid)) is not None
+        )
+        for name, ids in framework_owner_stacks(stacks).items()
+    }
+
+
+def _rule_framework_stack_attestation(
+    claimed_family: str | None,
+    owner_families: dict[str, frozenset[str]],
+) -> list[ReconciliationFinding]:
+    """A framework named in a headline is declared by no stack of the claimed runtime.
+
+    The headline describes ONE program: it welds a stack label ("C#/.NET") to the
+    frameworks found anywhere in the repo. On a polyglot repository those can be
+    different programs, and the sentence asserts a relationship the evidence
+    denies — the confluent examples repo read "C#/.NET rest api using JAX-RS",
+    attributing a JVM-only framework, declared by a Java stack in one
+    sub-workspace, to a .NET primary that declares no framework at all.
+
+    Fires only when ownership is PROVEN and disjoint: the framework has at least
+    one known owning family and the claimed family is not among them. An unknown
+    stack, or a framework no stack claims, yields nothing.
+    """
+    if not claimed_family:
+        return []
+    foreign = sorted(
+        name for name, fams in owner_families.items()
+        if fams and claimed_family not in fams
+    )
+    if not foreign:
+        return []
+    others = sorted({fam for name in foreign for fam in owner_families[name]})
+    return [
+        ReconciliationFinding(
+            rule="framework_stack_attestation",
+            symbols=tuple(foreign),
+            # Sink-neutral: this detail is read by a prose surface AND by a
+            # structured gap, so it states the contradiction, never "the
+            # headline says…" — the headline may already have dropped the claim.
+            detail=(
+                f"{len(foreign)} framework(s) are declared only by "
+                f"{', '.join(others)} stack(s), not by the {claimed_family} "
+                "primary stack — attributing them to it describes two separate "
+                "programs as one."
+            ),
+        )
+    ]
+
+
+def reconcile_headline_evidence(
+    *,
+    claimed_stack: str,
+    project_type: str | None,
+    stacks,
+) -> list[ReconciliationFinding]:
+    """Run headline reconciliation rules. Never raises.
+
+    Args:
+        claimed_stack: stack id the headline's label is built from (the primary).
+        project_type:  claimed type — cross-runtime types are exempt, their
+                       headline is MEANT to name another tier's framework.
+        stacks:        every StackDetection, each owning its own frameworks.
+    """
+    if project_type in _CROSS_RUNTIME_TYPES:
+        return []
+    findings: list[ReconciliationFinding] = []
+    try:
+        findings.extend(
+            _rule_framework_stack_attestation(
+                _STACK_FAMILY.get(claimed_stack or ""),
+                framework_owner_families(stacks),
+            )
+        )
+    except Exception:
+        pass
+    return findings
+
+
+def type_claim_unattested(
+    *, claimed_stack: str, project_type: str | None, stacks
+) -> bool:
+    """True when a framework-driven type label rests ONLY on foreign evidence.
+
+    The sibling of `_rule_framework_stack_attestation` for the type clause: the
+    frameworks that decided `project_type` are declared, every one of them, by
+    stacks of another runtime. The narrative consumer degrades the sentence; the
+    confidence consumer records the gap — same judgement, two sinks, one table.
+
+    Provable only: silent when the type is not framework-driven, when the claimed
+    stack's runtime is unknown, or when no framework is owned at all.
+    """
+    try:
+        if project_type not in _FRAMEWORK_DRIVEN_TYPES:
+            return False
+        family = _STACK_FAMILY.get(claimed_stack or "")
+        if not family:
+            return False
+        owners = framework_owner_families(stacks)
+        if not owners:
+            return False
+        return not any(family in fams for fams in owners.values())
+    except Exception:
+        return False
+
+
+def unattested_frameworks(
+    claimed_stack: str, project_type: str | None, stacks
+) -> frozenset[str]:
+    """Framework names the claimed stack does not attest (convenience view)."""
+    out: set[str] = set()
+    for f in reconcile_headline_evidence(
+        claimed_stack=claimed_stack, project_type=project_type, stacks=stacks
+    ):
+        out.update(f.symbols)
+    return frozenset(out)
+
+
 def reconcile_extraction_evidence(
     *,
     type_decl_files: frozenset[str],