sourcecode 4.3.0__tar.gz → 4.5.0__tar.gz

{sourcecode-4.3.0 → sourcecode-4.5.0}/CHANGELOG.md

@@ -2,8 +2,82 @@
 
 ## [Unreleased]
 
+## [4.5.0] — 2026-08-03
+
+Minor: the servlet-mounted HTTP surface is admitted as a population of its own
+(CL-12's remaining half), the output envelope is published as an open
+specification (M11's first deliverable), and a specification under `docs/` stops
+being counted as a test source. Nothing published is removed and no exit code
+moves; `--servlets` is opt-in and `endpoints.total` is byte-identical with and
+without it.
+
+### Fixed
+
+- **A specification under `docs/` was classified as a test source.** `spec/` means a
+  test suite in the RSpec/Jasmine sense and the opposite under a documentation root,
+  where a *specification* lives — and the file that exposed it is this release's own
+  `docs/spec/envelope-v1.md`, which landed in the test population of the tool's own
+  metrics the moment it was published. Fixed in the authority (`test_sources`) and in
+  the shared helper (`path_filters`); the segment keeps its meaning everywhere else, and
+  `docs/tests/` is still tests. Found by the suite, not by the field.
+
+### Added
+
+- **`envelope-v1` published as an open specification** (`docs/spec/envelope-v1.md`,
+  roadmap M11). Audit #8 named the output envelope the product's most underrated
+  strategic asset, and the argument is asymmetric: a format that makes `basis`,
+  `limitations`, `unit` and `denominator` mandatory is one an incumbent cannot adopt
+  without confessing what its own output leaves out. The document specifies the four
+  properties an answer must have — provenance, a named unit, a stated basis with
+  `unknown` never spelled `0`, and declared non-coverage — plus the compatibility
+  promise (within `envelope_version: 1`, fields are only ever added). **The field table
+  is generated from the same JSON Schema `ask schema envelope-v1` prints**, and the
+  battery fails when the two disagree: a specification that has drifted from the
+  implementation is worth less than none, because the people asked to adopt it check.
+
+### Added
+
+- **`ask endpoints --servlets` — the admission half of CL-12 / NC-007.** 4.2.0 declared
+  that the endpoint population is Spring handler mappings and that a servlet mapped in
+  `web.xml` or registered as a `ServletRegistrationBean` is reachable HTTP surface in
+  none of those counts; this lists it, as a population of its own with the URL pattern,
+  the servlet class and the declaring file. **It is never merged into
+  `endpoints.total`** — the two count different things, and widening a published figure
+  moves every ratio keyed on it. Measured: openmrs-core **7 patterns against 1 Spring
+  endpoint**, alfresco-community-repo **11**, including `/api/*` served by a WebScript
+  servlet. The flag is what NC-007 now names, through the remedy registry, so a rename
+  breaks the build rather than the reader. Nothing here resolves what guards those
+  patterns and the block says so.
+
+## [4.4.0] — 2026-08-03
+
+Minor: M10.5 closes except for the one item blocked on a population nobody in the
+battery has. Two additions, both additive — a new experimental command
+(`ask migrate-recipe`) and a new opt-in block on `endpoints` (`--client-usage`).
+No published field is removed, no default moves, and neither runs unless asked
+for.
+
 ### Added
 
+- **`ask endpoints --client-usage` — which of these routes anything in this repository
+  actually calls** (roadmap M10.5 item 4). On a large surface the cheapest reduction of
+  exposure is deleting API nobody calls, and in a monorepo the caller is checked in
+  beside the callee. The join reads the TypeScript/JavaScript client, extracts the calls
+  whose verb and path are written at the call site, neutralises variable segments on both
+  sides (`${bankId}` and `{bank-id}` are one position with two naming conventions) and
+  reports three counts: routes called here, routes nothing here calls, and **client calls
+  matching no route** — the decisive direction, a request this repository's own front end
+  makes and its server does not serve. Measured on open-banking-gateway: 268 client files,
+  31 calls, **30 of 39 routes called, 9 not, 11 calls matching nothing**.
+  - It is a **floor** and says so (`direction: under_reports`, new row `NC-009`): a route
+    with no call site here is a candidate for deletion, never dead API, because nothing in
+    a repository can observe the consumers it does not contain.
+  - A URL built at run time is published under `unresolved_call_sites` with its file and
+    line, never passed over — it is precisely the call that would make a live route look
+    dead, and a call the extractor could not even *see* would shrink the census silently.
+  - `--client-dir` points at the client when it is not the whole repository. The join runs
+    over the population the filters chose, for the same reason the exposure census does.
+
 - **`ask migrate-recipe` — the migration report in the form the executor takes**
   (roadmap M10.5 item 5 / M8.5, experimental). `migrate-check` already names the
   OpenRewrite recipe each finding carries (296 of 309 on openmrs-core) and a reader

{sourcecode-4.3.0 → sourcecode-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.3.0
+Version: 4.5.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -387,6 +387,12 @@ And one about who calls a route:
 |---|---|---|
 | **Whether a route is called from outside this repository — another service, a mobile app, a partner, a cron job, or a client whose URL is assembled at run time.** | The join reads the TypeScript/JavaScript checked in beside the server and only the call shapes whose verb and path are written at the call site. That is a floor on who calls a route and can never be a ceiling: the repository cannot observe consumers it does not contain. So a route with no call site here is published as a candidate for deletion, never as dead API. | Access logs or an API gateway answer who really calls a route. The opposite direction is decisive without them: a client call matching no route is a request this repository's own front end makes and its server does not serve. |
 
+The one row above with a remedy in this build: `ask endpoints /path/to/repo --servlets`
+lists the servlet-mounted HTTP surface as a population of its own — `web.xml` mappings and
+`ServletRegistrationBean` registrations, with the file that declares each — and never merges
+it into `endpoints.total`. Measured: openmrs-core 7 patterns, alfresco-community-repo 11,
+including `/api/*` served by a WebScript servlet.
+
 **Positioning.** Until an executor ships, this is the **diagnosis layer**: it measures what
 must change, what each change reaches, and what a gate should block — and it removes none of
 it. Field evaluation scored it 7/10 as a report generator and 5.5/10 as a development tool,
@@ -479,3 +485,4 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | [PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md) | `ask` (command) vs `sourcecode` (package/alias) |
 | [privacy.md](docs/privacy.md) | Telemetry and data-handling policy |
 | [DEFECT-LEDGER.md](docs/DEFECT-LEDGER.md) | Every defect found in the field, its class, and which release closed it — published on purpose |
+| [spec/envelope-v1.md](docs/spec/envelope-v1.md) | The output format as an **open specification** — provenance, a named unit, a stated basis, declared non-coverage. Implementable by tools that are not this one; the field table is generated from the schema `ask schema envelope-v1` prints |

{sourcecode-4.3.0 → sourcecode-4.5.0}/README.md

@@ -349,6 +349,12 @@ And one about who calls a route:
 |---|---|---|
 | **Whether a route is called from outside this repository — another service, a mobile app, a partner, a cron job, or a client whose URL is assembled at run time.** | The join reads the TypeScript/JavaScript checked in beside the server and only the call shapes whose verb and path are written at the call site. That is a floor on who calls a route and can never be a ceiling: the repository cannot observe consumers it does not contain. So a route with no call site here is published as a candidate for deletion, never as dead API. | Access logs or an API gateway answer who really calls a route. The opposite direction is decisive without them: a client call matching no route is a request this repository's own front end makes and its server does not serve. |
 
+The one row above with a remedy in this build: `ask endpoints /path/to/repo --servlets`
+lists the servlet-mounted HTTP surface as a population of its own — `web.xml` mappings and
+`ServletRegistrationBean` registrations, with the file that declares each — and never merges
+it into `endpoints.total`. Measured: openmrs-core 7 patterns, alfresco-community-repo 11,
+including `/api/*` served by a WebScript servlet.
+
 **Positioning.** Until an executor ships, this is the **diagnosis layer**: it measures what
 must change, what each change reaches, and what a gate should block — and it removes none of
 it. Field evaluation scored it 7/10 as a report generator and 5.5/10 as a development tool,
@@ -441,3 +447,4 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | [PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md) | `ask` (command) vs `sourcecode` (package/alias) |
 | [privacy.md](docs/privacy.md) | Telemetry and data-handling policy |
 | [DEFECT-LEDGER.md](docs/DEFECT-LEDGER.md) | Every defect found in the field, its class, and which release closed it — published on purpose |
+| [spec/envelope-v1.md](docs/spec/envelope-v1.md) | The output format as an **open specification** — provenance, a named unit, a stated basis, declared non-coverage. Implementable by tools that are not this one; the field table is generated from the schema `ask schema envelope-v1` prints |

{sourcecode-4.3.0 → sourcecode-4.5.0}/pyproject.toml

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

{sourcecode-4.3.0 → sourcecode-4.5.0}/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.3.0"
+__version__ = "4.5.0"

{sourcecode-4.3.0 → sourcecode-4.5.0}/src/sourcecode/cli.py

@@ -4885,6 +4885,12 @@ def endpoints_cmd(
         False, "--by-controller",
         help="Group endpoints by controller class (structured API surface for C4/Container synthesis).",
     ),
+    servlets: bool = typer.Option(
+        False, "--servlets",
+        help="Also list the HTTP surface mounted as a servlet — `web.xml` mappings "
+             "and ServletRegistrationBean registrations (NC-007). Published as a "
+             "population of its own; never merged into the endpoint count.",
+    ),
     client_usage: bool = typer.Option(
         False, "--client-usage",
         help="Join the routes against the HTTP calls written in the TypeScript/"
@@ -5001,6 +5007,14 @@ def endpoints_cmd(
     # exists to remove, one line into its own implementation (R5-R8).
     data["exposure"] = _endpoint_exposure_summary(_selected)
 
+    # CL-12 admission half. NC-007 declared this population in 4.2.0; this lists it,
+    # under its own name and its own total, because the two things counted are not the
+    # same kind of thing and `endpoints.total` is a published figure.
+    if servlets:
+        from sourcecode.servlet_surface import build_servlet_surface
+
+        data["servlet_surface"] = build_servlet_surface(target)
+
     # M10.5 item 4. On a large surface the cheapest reduction of exposure is
     # deleting API nobody calls, and in a monorepo the caller is checked in next
     # to the callee. Joined over the population the filters chose, for the same

{sourcecode-4.3.0 → sourcecode-4.5.0}/src/sourcecode/envelope.py

@@ -201,3 +201,38 @@ def attach_meta(payload: "dict[str, Any]", meta: "dict[str, Any]") -> "dict[str,
     else:
         payload[_META_KEY] = dict(meta)
     return payload
+
+
+#: The specification document is *rendered* from the schema, never written beside it.
+#: Audit #8 called the envelope "el activo estratégico más subestimado del producto" and
+#: the asymmetry is the point: a format that makes `basis`, `limitations` and `unit`
+#: mandatory is one an incumbent cannot adopt without confessing. A spec that drifts from
+#: the implementation is worth nothing to the people asked to adopt it, so the document
+#: below is generated from the same JSON Schema `ask schema envelope-v1` prints, and the
+#: battery fails when the published copy no longer matches.
+SPEC_BEGIN = "<!-- BEGIN GENERATED: ask schema envelope-v1 -->"
+SPEC_END = "<!-- END GENERATED -->"
+
+
+def render_spec_markdown(name: str = "envelope-v1") -> str:
+    """The field table of a published schema, as Markdown."""
+    schema = load_schema(name)
+    required = set(schema.get("required", ()))
+    lines = [
+        f"**Schema id:** `{schema.get('$id', name)}`",
+        "",
+        schema.get("description", "").strip(),
+        "",
+        "| Field | Required | Type | Meaning |",
+        "|---|---|---|---|",
+    ]
+    for field, spec in schema.get("properties", {}).items():
+        kind = spec.get("type", "")
+        if isinstance(kind, list):
+            kind = " \\| ".join(kind)
+        meaning = " ".join(str(spec.get("description", "")).split())
+        lines.append(
+            f"| `{field}` | {'yes' if field in required else 'no'} | "
+            f"{kind or '—'} | {meaning} |"
+        )
+    return "\n".join(lines) + "\n"

{sourcecode-4.3.0 → sourcecode-4.5.0}/src/sourcecode/non_coverage.py

@@ -172,11 +172,12 @@ NON_COVERAGE: tuple[NonCoverage, ...] = (
             "declared before it is widened."
         ),
         instead=(
-            "Read the deployment descriptors for `<servlet-mapping>` entries and "
-            "the Spring configuration for `ServletRegistrationBean` beans. Field "
-            "evaluation #9 found a monitoring console mounted this way, behind a "
-            "credential `ask spring-audit` did report (SEC-007) at a path nothing "
-            "here listed."
+            "`ask endpoints --servlets` lists that surface as a population of its "
+            "own — `<servlet-mapping>` entries and `ServletRegistrationBean` "
+            "registrations, with the declaring file — and never merges it into the "
+            "endpoint count. Field evaluation #9 found a monitoring console mounted "
+            "this way, behind a credential `ask spring-audit` did report (SEC-007) "
+            "at a path nothing here listed."
         ),
     ),
     NonCoverage(

{sourcecode-4.3.0 → sourcecode-4.5.0}/src/sourcecode/path_filters.py

@@ -23,6 +23,14 @@ _TEST_MODULE_SEGMENTS = frozenset({
     "test-support", "testsupport",
 })
 
+#: `spec/` means a test suite in the RSpec/Jasmine sense — and it means the opposite
+#: under a documentation root, where a *specification* lives. Found in this repository:
+#: `docs/spec/envelope-v1.md`, the published output-format specification, was classified
+#: as a test file and counted in the test population of the tool's own metrics. The
+#: segment keeps its meaning everywhere else; only these parents disarm it.
+_DOC_ROOT_SEGMENTS = frozenset({"docs", "doc", "documentation"})
+_AMBIGUOUS_TEST_SEGMENTS = frozenset({"spec", "specs"})
+
 _VENDOR_SEGMENTS = frozenset({
     "vendor", "vendors",
     "third_party", "thirdparty",
@@ -73,10 +81,15 @@ def is_test_path(path: str) -> bool:
 
     # Segment-based check – any directory component is a test segment
     parts = norm.split("/")
+    seen: set[str] = set()
     for part in parts[:-1]:  # skip filename itself
         bare = part.rstrip("/")
+        if bare in _AMBIGUOUS_TEST_SEGMENTS and seen & _DOC_ROOT_SEGMENTS:
+            seen.add(bare)
+            continue  # a specification under `docs/`, not a spec suite
         if bare in _TEST_SEGMENTS:
             return True
+        seen.add(bare)
 
     # File-name conventions
     name = parts[-1]

{sourcecode-4.3.0 → sourcecode-4.5.0}/src/sourcecode/remedies.py

@@ -97,6 +97,18 @@ REMEDIES: "dict[str, Remedy]" = {
             ),
             headline="derive contracts, write nothing",
         ),
+        Remedy(
+            key="http_surface_that_is_not_a_handler_mapping",
+            command="endpoints",
+            option="--servlets",
+            answers=(
+                "the endpoint population is Spring handler mappings; to list the HTTP "
+                "surface mounted as a servlet instead — `web.xml` mappings and "
+                "`ServletRegistrationBean` registrations — as its own population, never "
+                "merged into the endpoint count"
+            ),
+            headline="servlet-mounted HTTP surface",
+        ),
     )
 }
 

sourcecode-4.5.0/src/sourcecode/servlet_surface.py

@@ -0,0 +1,194 @@
+"""servlet_surface.py — HTTP surface that is not a Spring handler mapping.
+
+Field evaluation #9's second finding was a monitoring console mounted at
+`/panel-de-control` through a `<servlet-mapping>` in `web.xml`, behind a credential
+`spring-audit` did report (SEC-007) at a path **nothing in this product listed**. The
+endpoint population is projected from the Spring route model — one entry per handler
+mapping — and a servlet is reachable over HTTP without being in that model.
+
+`NC-007` (4.2.0) declared that gap. This module is its admission half, and the rule
+that shaped it is the reason the declaration came first: **this population is never
+merged into `endpoints.total`**. That count, and every ratio keyed on it, is published
+and read; widening it silently would move numbers a reader has already acted on, and
+the two things counted are not the same kind of thing — a Spring handler has a
+controller, a handler symbol and a security verdict derived from the filter chain; a
+servlet mapping has a URL pattern and a class name, and nothing here resolves what
+guards it.
+
+So the answer is a second, named population beside the first, with its own total.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+from xml.etree import ElementTree as ET
+
+SCHEMA_VERSION = "servlet-surface-v1"
+
+_SKIP_DIRS = frozenset({".git", "target", "build", "out", "node_modules", "dist"})
+
+#: `new ServletRegistrationBean<>(new Foo(), "/path/*")` and the `addUrlMappings` form.
+_REGISTRATION_BEAN = re.compile(
+    r"""ServletRegistrationBean\s*(?:<[^>]*>)?\s*\(\s*(?P<args>[^;]{0,400}?)\)\s*;""",
+    re.DOTALL,
+)
+_URL_MAPPINGS = re.compile(
+    r"""(?:addUrlMappings|setUrlMappings)\s*\(\s*(?P<args>[^;]{0,300}?)\)""", re.DOTALL
+)
+_STRING_LITERAL = re.compile(r"""["']([^"']{1,200})["']""")
+
+
+@dataclass(frozen=True)
+class ServletMapping:
+    """One servlet reachable over HTTP, and where it was declared."""
+
+    url_pattern: str
+    servlet_name: str
+    servlet_class: str
+    source_file: str
+    source: str          # "web.xml" | "servlet_registration_bean"
+
+    def to_dict(self) -> dict:
+        return {
+            "url_pattern": self.url_pattern,
+            "servlet_name": self.servlet_name,
+            "servlet_class": self.servlet_class,
+            "source_file": self.source_file,
+            "source": self.source,
+        }
+
+
+def _local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def _child_text(elem: "ET.Element", name: str) -> str:
+    for child in elem.iter():
+        if _local(child.tag) == name and (child.text or "").strip():
+            return child.text.strip()
+    return ""
+
+
+def _from_web_xml(xml_path: Path, relative: str) -> "list[ServletMapping]":
+    try:
+        root = ET.parse(str(xml_path)).getroot()
+    except Exception:
+        return []
+    classes: "dict[str, str]" = {}
+    for elem in root.iter():
+        if _local(elem.tag) != "servlet":
+            continue
+        name = _child_text(elem, "servlet-name")
+        klass = _child_text(elem, "servlet-class")
+        if name:
+            classes[name] = klass
+    out: "list[ServletMapping]" = []
+    for elem in root.iter():
+        if _local(elem.tag) != "servlet-mapping":
+            continue
+        name = _child_text(elem, "servlet-name")
+        for child in elem.iter():
+            if _local(child.tag) != "url-pattern" or not (child.text or "").strip():
+                continue
+            out.append(ServletMapping(
+                url_pattern=child.text.strip(),
+                servlet_name=name,
+                servlet_class=classes.get(name, ""),
+                source_file=relative,
+                source="web.xml",
+            ))
+    return out
+
+
+def _from_registration_beans(java_path: Path, relative: str) -> "list[ServletMapping]":
+    try:
+        text = java_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+    if "ServletRegistrationBean" not in text:
+        return []
+    out: "list[ServletMapping]" = []
+    for match in _REGISTRATION_BEAN.finditer(text):
+        args = match.group("args")
+        literals = _STRING_LITERAL.findall(args)
+        patterns = [lit for lit in literals if lit.startswith("/")]
+        klass = ""
+        new_call = re.search(r"new\s+([A-Z][\w.]*)\s*\(", args)
+        if new_call:
+            klass = new_call.group(1)
+        for pattern in patterns:
+            out.append(ServletMapping(
+                url_pattern=pattern, servlet_name="", servlet_class=klass,
+                source_file=relative, source="servlet_registration_bean",
+            ))
+    for match in _URL_MAPPINGS.finditer(text):
+        for literal in _STRING_LITERAL.findall(match.group("args")):
+            if literal.startswith("/"):
+                out.append(ServletMapping(
+                    url_pattern=literal, servlet_name="", servlet_class="",
+                    source_file=relative, source="servlet_registration_bean",
+                ))
+    return out
+
+
+def build_servlet_surface(root: Path, *, limit: Optional[int] = None) -> dict:
+    """Every servlet-mapped URL pattern under `root`, as a population of its own."""
+    from sourcecode import non_coverage
+
+    root = Path(root)
+    mappings: "list[ServletMapping]" = []
+    for path in sorted(root.rglob("*")):
+        if any(part in _SKIP_DIRS for part in path.parts) or not path.is_file():
+            continue
+        try:
+            relative = str(path.relative_to(root))
+        except ValueError:
+            relative = str(path)
+        if path.name == "web.xml":
+            mappings.extend(_from_web_xml(path, relative))
+        elif path.suffix == ".java":
+            mappings.extend(_from_registration_beans(path, relative))
+
+    # One URL pattern declared twice is two declarations of one reachable path; the
+    # census counts patterns, the rows keep every declaration.
+    patterns = sorted({m.url_pattern for m in mappings})
+    by_source: "dict[str, int]" = {}
+    for mapping in mappings:
+        by_source[mapping.source] = by_source.get(mapping.source, 0) + 1
+
+    rows = [m.to_dict() for m in sorted(
+        mappings, key=lambda m: (m.url_pattern, m.source_file)
+    )]
+    shown = rows if limit is None else rows[:limit]
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "total_url_patterns": len(patterns),
+        "declarations": len(mappings),
+        "by_source": dict(sorted(by_source.items())),
+        "url_patterns": patterns,
+        "mappings": shown,
+        "mappings_omitted": len(rows) - len(shown),
+        "population": (
+            "servlet mappings declared in `web.xml` or registered as a "
+            "`ServletRegistrationBean` — HTTP surface that is NOT a Spring handler "
+            "mapping and is therefore in none of the endpoint counts"
+        ),
+        "never_merged": (
+            "This total is deliberately separate from `endpoints.total`. The two count "
+            "different things — a handler mapping has a controller, a handler symbol "
+            "and a security verdict derived from the chain; a servlet mapping has a URL "
+            "pattern and a class — and merging them would move a published count and "
+            "every ratio keyed on it."
+        ),
+        "access": (
+            "Nothing here resolves what guards these patterns. A servlet is matched by "
+            "the same filter chain as everything else, so a filter pattern that covers "
+            "it may or may not authenticate it; `ask spring-audit` reports credentials "
+            "found in the same descriptors (SEC-007)."
+        ),
+        "non_coverage": non_coverage.block("endpoints"),
+    }

{sourcecode-4.3.0 → sourcecode-4.5.0}/src/sourcecode/test_sources.py

@@ -52,6 +52,14 @@ _TEST_DIR_NAMES: frozenset[str] = frozenset(
     {"test", "tests", "spec", "specs", "__tests__"}
 )
 
+#: `spec/` is a test suite in the RSpec/Jasmine sense — and the opposite under a
+#: documentation root, where a *specification* lives. Found by this project's own suite
+#: when `docs/spec/envelope-v1.md` (the published output-format specification) landed in
+#: the test population of the tool's own metrics. Only these parents disarm the segment;
+#: `spec/` keeps its meaning everywhere else, and `docs/tests/` is still tests.
+_DOC_ROOT_NAMES: frozenset[str] = frozenset({"docs", "doc", "documentation"})
+_AMBIGUOUS_TEST_DIR_NAMES: frozenset[str] = frozenset({"spec", "specs"})
+
 # A directory named `test` under one of these is production code, not a test.
 _MAIN_ROOT_SEGMENTS: tuple[tuple[str, ...], ...] = (
     ("src", "main"),
@@ -99,8 +107,13 @@ def declared_test_root(path: str) -> "str | None":
         # A `test` package inside a main source root is production code.
         return None
     for i, part in enumerate(parts[:-1]):
-        if part in _TEST_DIR_NAMES:
-            return "/".join(parts[:i + 1])
+        if part not in _TEST_DIR_NAMES:
+            continue
+        if part in _AMBIGUOUS_TEST_DIR_NAMES and (
+            set(parts[:i]) & _DOC_ROOT_NAMES
+        ):
+            continue  # a specification under `docs/`, not a spec suite
+        return "/".join(parts[:i + 1])
     return None