sourcecode 4.0.0__tar.gz → 4.0.1__tar.gz

{sourcecode-4.0.0 → sourcecode-4.0.1}/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 ## [Unreleased]
 
+## [4.0.1] — 2026-08-02
+
+Patch, and the criterion is the one this project has used since 3.2.0: nothing here
+moves a published field, an exit code or a default. Three surfaces stopped
+misdescribing an engine that did not change — the release advertised half its own
+security ruleset, the front page led to neither capability the field asked for by
+name, and the document both of them call the full command reference covered fewer
+than half the commands. All three were found in-house.
+
+### Fixed
+
+- **`spring-audit --help` advertised three security rules and the build ships six**
+  (C4-9). The one-liner the root panel prints, and the command's own screen, said
+  `security surface (SEC-001..003)` two releases after CL-9 shipped SEC-004, SEC-005
+  and SEC-006; `docs/PRODUCT_TIERS.md` said `TX-001..005 + SEC-001..003` and
+  `docs/USER_GUIDE.md` said `TX-001..TX-005`. The engine was right in every case —
+  the product advertised half its ruleset, in the release that answered the field's
+  complaint about security recall. `sourcecode/rule_catalog.py` now holds one summary
+  line per rule and the help renders from it, while the id *set* is derived from the
+  shipped pattern registries by `tests/test_rule_catalog.py`: a seventh rule fails the
+  build until it is documented, and no surface may name a rule the build cannot emit.
+  The non-coverage block in the same help is rendered from `non_coverage` too, which
+  had a renderer with no consumer beside four rows restated by hand.
+- **The front page did not lead to either remedy that C4-8 closed** (C4-10). The
+  pointer lived in the payload that states the limitation, which reaches an agent and
+  not a reader who has not run the command yet — the same reader who wrote
+  `ask posture --provenance` and `ask contracts init` by hand after a full session.
+  `ask --help` now renders a *Questions the repository alone does not answer* block
+  from `remedies.REMEDIES`, and lists `risk .` in Start here; the README carries
+  `--resolve-environments`, `verify --init` and `ask risk` in the Quickstart,
+  `--resolve-environments` in §5b beside the `--diff` it qualifies, and a §5c for
+  composed risk. `tests/test_remedies.py` fails when a remedy is absent from either
+  surface.
+- **The "full command reference" documented 14 of 32 commands** (C4-11). `verify`,
+  `verify-edit` and `pr-impact` — the three gate commands — appeared only as names in
+  the tier table, and eight more had no occurrence in the file at all. Sections added
+  for the gate family (with the exit-code contract they share), for `plan`, `compare`,
+  `delta` and `contract-diff`, and a table for the rest.
+  `tests/test_user_guide_coverage.py` takes the command population from the CLI and
+  parses every invocation the guide prints against it.
+
 ## [4.0.0] — 2026-08-02
 
 Major because two published `gate_coverage` fields are removed, not because the

{sourcecode-4.0.0 → sourcecode-4.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.0.0
+Version: 4.0.1
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -129,6 +129,26 @@ ask spring-audit /path/to/repo
 ask migrate-check /path/to/repo --compact
 ```
 
+**Then the three that finish the sentence the four above start.** A profile-set answer stays
+conditional until you know which set the deployment starts with, a gate nobody can populate is
+a gate nobody runs, and a defect ranked without its reach is a linter note:
+
+```bash
+# Which profile set ACTUALLY runs? Reads every artefact that can set it — build,
+# descriptors, Dockerfile, Compose, Kubernetes, launch scripts — with file:line, and
+# says NOT DECIDED IN THIS REPOSITORY when nothing in the tree decides it. Then ranks
+# every admissible set by what it leaves reachable without authentication.
+ask posture /path/to/repo --resolve-environments
+
+# Derive the contracts this repository already satisfies, execute each one before
+# writing it, and populate .ask/contracts.yml from the measurement instead of by hand.
+ask verify /path/to/repo --init
+
+# What each defect actually costs once reach, access and write effect are in it:
+# severity × reachability × auth_verdict × write_effect, ordered, every factor traceable.
+ask risk /path/to/repo
+```
+
 Then the everyday loop:
 
 ```bash
@@ -145,13 +165,17 @@ ask onboard /path/to/repo
 ask review-pr /path/to/repo --since main
 
 # CI gate on NEW violations only, instead of on pre-existing debt
+ask verify /path/to/repo --init               # derive the contracts, don't hand-write them
 ask verify /path/to/repo --capture-baseline   # accept today's debt, once
 ask verify /path/to/repo                      # then: only new violations block
 ```
 
-> **Adopting a gate on a real codebase.** A repository that starts declaring contracts already
-> violates them somewhere; `ask verify` is **baseline-relative by default** (`--fail-on new`)
-> so the gate survives contact with reality instead of being switched off on day one.
+> **Adopting a gate on a real codebase.** Nobody hand-writes contracts for a 3 000-file
+> monolith, so `ask verify --init` derives the ones the repository satisfies **today** and
+> executes each before writing it — init followed by verify passes by construction.
+> A repository that starts declaring contracts already violates them somewhere; `ask verify`
+> is **baseline-relative by default** (`--fail-on new`) so the gate survives contact with
+> reality instead of being switched off on day one.
 > `ask baseline capture|diff|trend` is a different thing: versioned architectural metrics over
 > time, for trend reporting rather than blocking.
 
@@ -194,10 +218,32 @@ What a profile set **actually wires**: which conditional beans register, which d
 `ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
 → [posture.md](docs/posture.md)
 
+**`--resolve-environments` carries it past the edge of the repository.** Every answer above
+is conditional on a profile set, and which set runs is decided by the deployment. This flag
+reads every artefact in the tree that can set `spring.profiles.active` — Maven/Gradle,
+`web.xml`, `Dockerfile`, Compose, Kubernetes, launch scripts — with `file:line`, and returns
+`decided_in_repository`, `artefacts_disagree` (two deployments, never resolved by picking
+one) or **`NOT DECIDED IN THIS REPOSITORY`**. Then it resolves every admissible set over one
+parse and publishes the worst. A field audit closed those five hops by hand with grep before
+the flag existed.
+`ask posture . --resolve-environments`
+
 Unresolved is a first-class outcome: a condition the resolver cannot decide is reported as a
 hole with the condition named, never folded into active or inactive. **A posture answer that
 guesses is a confident security falsehood — the worst failure mode this tool has.**
 
+### 5c · Composed Risk *(experimental)*
+Every command above answers one axis, and a reader composes them by hand. `ask risk` does the
+join over the endpoint and symbol ids these commands already share with each other:
+`severity_effective = defect_severity × reachability × auth_verdict × write_effect`. The
+product of the published factors **is** the published score — decomposable to the four
+figures and the authority behind each — and an axis this build cannot measure is `unknown`,
+weighted 1.0 and named in `blind_axes` rather than silently treated as safe. Measured on a
+field case: a defect both `spring-audit` and `impact-chain` called *medium* composes to
+**high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
+`ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
+→ [reference](docs/USER_GUIDE.md)
+
 ### 6 · Developer Workflows
 The everyday loop: diff-based PR review, symptom-driven bug triage, and delta context for continuous agent runs.
 `ask review-pr` · `ask fix-bug` · `ask prepare-context`

{sourcecode-4.0.0 → sourcecode-4.0.1}/README.md

@@ -91,6 +91,26 @@ ask spring-audit /path/to/repo
 ask migrate-check /path/to/repo --compact
 ```
 
+**Then the three that finish the sentence the four above start.** A profile-set answer stays
+conditional until you know which set the deployment starts with, a gate nobody can populate is
+a gate nobody runs, and a defect ranked without its reach is a linter note:
+
+```bash
+# Which profile set ACTUALLY runs? Reads every artefact that can set it — build,
+# descriptors, Dockerfile, Compose, Kubernetes, launch scripts — with file:line, and
+# says NOT DECIDED IN THIS REPOSITORY when nothing in the tree decides it. Then ranks
+# every admissible set by what it leaves reachable without authentication.
+ask posture /path/to/repo --resolve-environments
+
+# Derive the contracts this repository already satisfies, execute each one before
+# writing it, and populate .ask/contracts.yml from the measurement instead of by hand.
+ask verify /path/to/repo --init
+
+# What each defect actually costs once reach, access and write effect are in it:
+# severity × reachability × auth_verdict × write_effect, ordered, every factor traceable.
+ask risk /path/to/repo
+```
+
 Then the everyday loop:
 
 ```bash
@@ -107,13 +127,17 @@ ask onboard /path/to/repo
 ask review-pr /path/to/repo --since main
 
 # CI gate on NEW violations only, instead of on pre-existing debt
+ask verify /path/to/repo --init               # derive the contracts, don't hand-write them
 ask verify /path/to/repo --capture-baseline   # accept today's debt, once
 ask verify /path/to/repo                      # then: only new violations block
 ```
 
-> **Adopting a gate on a real codebase.** A repository that starts declaring contracts already
-> violates them somewhere; `ask verify` is **baseline-relative by default** (`--fail-on new`)
-> so the gate survives contact with reality instead of being switched off on day one.
+> **Adopting a gate on a real codebase.** Nobody hand-writes contracts for a 3 000-file
+> monolith, so `ask verify --init` derives the ones the repository satisfies **today** and
+> executes each before writing it — init followed by verify passes by construction.
+> A repository that starts declaring contracts already violates them somewhere; `ask verify`
+> is **baseline-relative by default** (`--fail-on new`) so the gate survives contact with
+> reality instead of being switched off on day one.
 > `ask baseline capture|diff|trend` is a different thing: versioned architectural metrics over
 > time, for trend reporting rather than blocking.
 
@@ -156,10 +180,32 @@ What a profile set **actually wires**: which conditional beans register, which d
 `ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
 → [posture.md](docs/posture.md)
 
+**`--resolve-environments` carries it past the edge of the repository.** Every answer above
+is conditional on a profile set, and which set runs is decided by the deployment. This flag
+reads every artefact in the tree that can set `spring.profiles.active` — Maven/Gradle,
+`web.xml`, `Dockerfile`, Compose, Kubernetes, launch scripts — with `file:line`, and returns
+`decided_in_repository`, `artefacts_disagree` (two deployments, never resolved by picking
+one) or **`NOT DECIDED IN THIS REPOSITORY`**. Then it resolves every admissible set over one
+parse and publishes the worst. A field audit closed those five hops by hand with grep before
+the flag existed.
+`ask posture . --resolve-environments`
+
 Unresolved is a first-class outcome: a condition the resolver cannot decide is reported as a
 hole with the condition named, never folded into active or inactive. **A posture answer that
 guesses is a confident security falsehood — the worst failure mode this tool has.**
 
+### 5c · Composed Risk *(experimental)*
+Every command above answers one axis, and a reader composes them by hand. `ask risk` does the
+join over the endpoint and symbol ids these commands already share with each other:
+`severity_effective = defect_severity × reachability × auth_verdict × write_effect`. The
+product of the published factors **is** the published score — decomposable to the four
+figures and the authority behind each — and an axis this build cannot measure is `unknown`,
+weighted 1.0 and named in `blind_axes` rather than silently treated as safe. Measured on a
+field case: a defect both `spring-audit` and `impact-chain` called *medium* composes to
+**high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
+`ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
+→ [reference](docs/USER_GUIDE.md)
+
 ### 6 · Developer Workflows
 The everyday loop: diff-based PR review, symptom-driven bug triage, and delta context for continuous agent runs.
 `ask review-pr` · `ask fix-bug` · `ask prepare-context`

{sourcecode-4.0.0 → sourcecode-4.0.1}/pyproject.toml

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

{sourcecode-4.0.0 → sourcecode-4.0.1}/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__ = "4.0.0"
+__version__ = "4.0.1"

{sourcecode-4.0.0 → sourcecode-4.0.1}/src/sourcecode/cli.py

@@ -297,6 +297,27 @@ def _group_help_block() -> str:
     return "\n".join(lines)
 
 
+def _remedy_help_block() -> str:
+    """The front page names the answers the field asked for as missing features.
+
+    C4-8 was closed in the payload: a limitation now carries the invocation that
+    resolves it. But the evaluator who wrote `ask posture --provenance` and `ask
+    contracts init` by hand was reading `--help` first, and neither shipped flag
+    was on it. The block is rendered from `remedies.REMEDIES`, so the pointer and
+    the capability cannot drift — `tests/test_remedies.py` already refuses a
+    remedy whose option the CLI does not accept.
+    """
+    from sourcecode.remedies import headlines
+
+    lines = ["[bold]Questions the repository alone does not answer:[/bold]"]
+    for invocation, headline in headlines():
+        # Bare invocation, like every other block on this page: the header panels
+        # print without the `ask ` prefix (C3-16).
+        bare = invocation.removeprefix("ask ")
+        lines.append(f"  {bare:<33}[dim]# {headline}[/dim]")
+    return "\n".join(lines)
+
+
 def _build_help_text() -> str:
     """Build --help text dynamically based on current license state."""
     try:
@@ -323,6 +344,9 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
   endpoints .                  [dim]# endpoints + effective path + policy[/dim]
   spring-audit .               [dim]# TX anomalies + security surface[/dim]
   migrate-check . --compact    [dim]# Boot 2→3: located blockers + effort[/dim]
+  risk .                       [dim]# defects ranked by reach × access (exp.)[/dim]
+
+{_remedy_help_block()}
 
 [bold]Agent context:[/bold]
   ask --compact                [dim]# high-signal summary (~2,500–4,000 tokens)[/dim]
@@ -6438,19 +6462,11 @@ def spring_audit_cmd(
         help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
 ) -> None:
-    """Spring semantic audit: TX anomalies (TX-001..006) + security surface (SEC-001..003).
+    """Spring semantic audit: {{RULE_SUMMARY}}.
 
     \b
     Detects:
-      TX-001  @Transactional on private/final method (CGLIB proxy bypass)
-      TX-002  REQUIRES_NEW nested in REQUIRED call chain
-      TX-003  readOnly=true boundary propagating to write operation
-      TX-004  NOT_SUPPORTED/NEVER within active TX chain
-      TX-005  Exception swallowing inside @Transactional
-      TX-006  Self-invocation of @Transactional sibling (proxy bypass)
-      SEC-001 Unsecured endpoint in annotation_based security model
-      SEC-002 CVE-2025-41248: @PreAuthorize on inherited method from generic supertype
-      SEC-003 @Transactional on @Controller/@RestController (TX in wrong layer)
+{{RULE_LIST}}
 
     \b
     Findings and defects are two counts, both published. A rule fires per
@@ -6482,10 +6498,7 @@ def spring_audit_cmd(
     \b
     What it does not look at (the whole list is in the payload's `non_coverage`,
     and in the README):
-      NC-001  whether request input reaches a sink — no dataflow or taint
-      NC-002  secrets outside Java and Spring configuration
-      NC-003  filter-chain ORDER — a custom filter's presence is structural only
-      NC-004  known vulnerabilities in dependencies — no CVE matching
+{{NON_COVERAGE}}
     Silence about those is not evidence that there is nothing to find.
 """
     import json as _json
@@ -6587,6 +6600,30 @@ def spring_audit_cmd(
         raise typer.Exit(code=1)
 
 
+def _render_audit_help(doc: str) -> str:
+    """Fill the rule and non-coverage blocks from the tables that own them.
+
+    The rules this command detects were written out by hand in its own help, and
+    stayed at `SEC-001..003` for two releases after CL-9 shipped three more — the
+    C4-1 shape, where a curated list beside a generated one drifts and the
+    curated one is what the reader gets. Both blocks are rendered now, so adding
+    a rule updates the help by construction.
+    """
+    from sourcecode import non_coverage, rule_catalog
+
+    nc_lines = [
+        f"      {line}" for line in non_coverage.render_help_lines("security_surface", width=68)
+    ]
+    return (
+        doc.replace("{{RULE_SUMMARY}}", rule_catalog.summary_line())
+        .replace("{{RULE_LIST}}", rule_catalog.render_help_block())
+        .replace("{{NON_COVERAGE}}", "\n".join(nc_lines))
+    )
+
+
+spring_audit_cmd.__doc__ = _render_audit_help(spring_audit_cmd.__doc__ or "")
+
+
 # ── verify-edit: in-loop semantic diff gate ───────────────────────────────────
 
 

{sourcecode-4.0.0 → sourcecode-4.0.1}/src/sourcecode/remedies.py

@@ -38,6 +38,10 @@ class Remedy:
     #: feature name — the evaluator's request was written in their own words, so
     #: the pointer has to be recognisable from the question they were asking.
     answers: str
+    #: The same thing in a help-screen column. A payload can afford the sentence;
+    #: a front page cannot, and rewriting it there by hand is how the pointer and
+    #: the capability drift apart.
+    headline: str = ""
 
     @property
     def invocation(self) -> str:
@@ -63,6 +67,7 @@ REMEDIES: "dict[str, Remedy]" = {
                 "this repository; to read every artefact that can set it with file:line "
                 "and rank the admissible sets by what they leave reachable"
             ),
+            headline="which profile set actually runs",
         ),
         Remedy(
             key="no_contracts_declared",
@@ -73,11 +78,23 @@ REMEDIES: "dict[str, Remedy]" = {
                 "and write `.ask/contracts.yml` from the current measurement instead of "
                 "by hand"
             ),
+            headline="derive contracts from measurement",
         ),
     )
 }
 
 
+def headlines() -> "tuple[tuple[str, str], ...]":
+    """`(invocation, headline)` for every remedy, for a help screen or a README.
+
+    Rendered rather than restated: the front page is where the evaluator looked
+    first and found neither of these commands.
+    """
+    return tuple(
+        (r.invocation, r.headline or r.answers) for r in REMEDIES.values()
+    )
+
+
 def remedy(key: str) -> Remedy:
     """The remedy for `key`. Raises rather than returning a silent blank, because a
     missing pointer is exactly the defect this module exists to prevent."""

sourcecode-4.0.1/src/sourcecode/rule_catalog.py

@@ -0,0 +1,107 @@
+"""The rules `spring-audit` ships, in the one place every reader is rendered from.
+
+The help screen used to name its own rules. It said `SEC-001..003` for two
+releases after CL-9 shipped SEC-004, SEC-005 and SEC-006, so the product
+advertised three security rules while holding six — the same shape as C4-1
+(`endpoints` missing from every help list) and C4-8 (a shipped capability the
+field asked for as a feature): a curated list beside a generated one drifts, and
+the curated one is what a buyer reads.
+
+Two seams keep this honest, and neither is a promise:
+
+* The **summaries** live here, keyed by rule id, and `--help` renders from them
+  rather than restating them.
+* The **id set** is not authored here at all. It belongs to the pattern
+  registries in `spring_tx_analyzer` and `spring_security_audit`, and
+  `tests/test_rule_catalog.py` derives it from them: a seventh SEC rule fails
+  the build until it has a line in this table. That import is deliberately not
+  done at module level — the analyzers are heavy and this module is imported to
+  render a help screen.
+
+A pattern class that emits several ids declares them in `pattern_ids`; one that
+emits its own declares nothing and is read through `pattern_id`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+SCHEMA_VERSION = "rule-catalog-v1"
+
+
+@dataclass(frozen=True)
+class Rule:
+    """One audit rule, as a reader meets it."""
+
+    id: str
+    family: str        # "TX" or "SEC" — the scope flag that selects it
+    summary: str       # one line, no wrapping games
+
+    def to_dict(self) -> dict:
+        return {"id": self.id, "family": self.family, "summary": self.summary}
+
+
+RULES: tuple[Rule, ...] = (
+    Rule("TX-001", "TX", "@Transactional on private/final method (CGLIB proxy bypass)"),
+    Rule("TX-002", "TX", "REQUIRES_NEW nested in REQUIRED call chain"),
+    Rule("TX-003", "TX", "readOnly=true boundary propagating to write operation"),
+    Rule("TX-004", "TX", "NOT_SUPPORTED/NEVER within active TX chain"),
+    Rule("TX-005", "TX", "Exception swallowing inside @Transactional"),
+    Rule("TX-006", "TX", "Self-invocation of @Transactional sibling (proxy bypass)"),
+    Rule("SEC-001", "SEC", "Unsecured endpoint in annotation_based security model"),
+    Rule("SEC-002", "SEC", "CVE-2025-41248: @PreAuthorize inherited from a generic supertype"),
+    Rule("SEC-003", "SEC", "@Transactional on @Controller/@RestController (TX in wrong layer)"),
+    Rule("SEC-004", "SEC", "Password stored under a fast unsalted digest (SHA-1, MD5)"),
+    Rule("SEC-005", "SEC", "CSRF disabled under session-bearing authentication"),
+    Rule("SEC-006", "SEC", "Cookie created without the Secure attribute"),
+)
+
+FAMILY_ORDER: tuple[str, ...] = ("TX", "SEC")
+
+
+def ids() -> tuple[str, ...]:
+    """Every rule id this build can emit, in help order."""
+    return tuple(rule.id for rule in RULES)
+
+
+def for_family(family: str) -> tuple[Rule, ...]:
+    return tuple(rule for rule in RULES if rule.family == family)
+
+
+def range_label(family: str) -> str:
+    """`TX-001..006` — the span a one-line summary can carry without lying."""
+    rules = for_family(family)
+    if not rules:
+        return ""
+    if len(rules) == 1:
+        return rules[0].id
+    first, last = rules[0].id, rules[-1].id
+    _, _, tail = last.partition("-")
+    return f"{first}..{tail}"
+
+
+def summary_line() -> str:
+    """The command's one-liner: the families and how far each one reaches."""
+    return " + ".join(
+        f"{'TX anomalies' if fam == 'TX' else 'security surface'} "
+        f"({range_label(fam)})"
+        for fam in FAMILY_ORDER
+        if for_family(fam)
+    )
+
+
+def help_lines(*, indent: str = "      ") -> list[str]:
+    """One line per rule, id column aligned, for a `--help` screen."""
+    width = max(len(rule.id) for rule in RULES)
+    return [f"{indent}{rule.id.ljust(width)}  {rule.summary}" for rule in RULES]
+
+
+def render_help_block(*, indent: str = "      ") -> str:
+    return "\n".join(help_lines(indent=indent))
+
+
+def render_markdown() -> str:
+    """The docs table, generated from the same tuple."""
+    lines = ["| Rule | Detects |", "|---|---|"]
+    lines.extend(f"| `{rule.id}` | {rule.summary} |" for rule in RULES)
+    return "\n".join(lines)

{sourcecode-4.0.0 → sourcecode-4.0.1}/src/sourcecode/spring_security_audit.py

@@ -406,6 +406,9 @@ class _SEC00XConfigurationWeaknesses:
         "SEC-005": "CSRF protection disabled under session-bearing authentication",
         "SEC-006": "Cookie created without the Secure attribute",
     }
+    #: A pattern that emits more than one rule id declares them all, so a catalogue
+    #: reader is never left with the group's identity standing for the group.
+    pattern_ids = tuple(_TITLE)
     _FIX = {
         "SEC-004": (
             "Store passwords with an adaptive, salted function — BCryptPasswordEncoder, "