foretop-ebb 0.1.0__py3-none-any.whl

ebb/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ebb/__main__.py

@@ -0,0 +1,4 @@
+from ebb.cli import app
+
+if __name__ == "__main__":
+    app()

ebb/brand.py

@@ -0,0 +1,5 @@
+BRAND = "foretop"
+"""The insulation rule (NEXT_STEPS.md): until the trademark search clears, the brand name lives
+in exactly this one constant — package prefix, CLI namespace, user-facing strings — and nowhere
+else. A rename is then a find-replace, a re-publish, and a GitHub org rename, not a week of
+hunting down hardcoded strings."""

ebb/build_findings.py

@@ -0,0 +1,118 @@
+import hashlib
+import uuid
+from datetime import UTC, date, datetime
+from pathlib import Path
+
+from ebb import __version__ as ENGINE_VERSION  # noqa: N812
+from ebb.canonicalize import canonicalize
+from ebb.detect.base import RawMatch
+from ebb.finding import Evidence, Finding, FindingState, ProductCode, Verdict
+from ebb.owner import find_owner
+from ebb.registry.loader import Registry
+from ebb.registry.models import RegistryEntry
+from ebb.registry.resolve import Resolution, Resolved, resolve
+from ebb.verdict import compute_confidence, compute_severity, compute_verdict
+from ebb.walk import scan_repo
+
+RULE_ID = "ebb.retirement"
+
+
+def compute_identity(canonical_id: str, relative_path: str, symbol: str) -> str:
+    """Canonical model id + file path + normalized surrounding symbol — deliberately excludes
+    the line number, per SUITE_ARCHITECTURE.md §3.1: identity must survive cosmetic reformatting
+    and break on real change. A hash rather than a readable string because identity is compared,
+    never displayed — title/detail_md carry the human-facing description."""
+    raw = f"ebb|{canonical_id}|{relative_path}|{symbol}"
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
+
+
+def _title_for(canonical_id: str, verdict: Verdict, entry: RegistryEntry | None) -> str:
+    if verdict is Verdict.BREAK:
+        assert entry is not None and entry.shutdown_at is not None
+        return f"{canonical_id} retired {entry.shutdown_at.isoformat()}"
+    if verdict is Verdict.DRIFT:
+        assert entry is not None and entry.shutdown_at is not None
+        return f"{canonical_id} retires {entry.shutdown_at.isoformat()}"
+    if verdict is Verdict.CLEAR:
+        return f"{canonical_id} is actively supported"
+    return f"{canonical_id} is not in the tracked registry"
+
+
+def _detail_md_for(canonical_id: str, entry: RegistryEntry | None) -> str:
+    if entry is None:
+        return (
+            f"`{canonical_id}` was detected but is not a verified entry in the retirement "
+            "registry. This means unknown, not confirmed safe."
+        )
+    parts = [f"Provider: **{entry.provider.value}**", f"Source: {entry.source_url}"]
+    if entry.announced_at:
+        parts.append(f"Announced: {entry.announced_at.isoformat()}")
+    if entry.shutdown_at:
+        parts.append(f"Shutdown: {entry.shutdown_at.isoformat()}")
+    if entry.replacement_id:
+        parts.append(f"Replacement: `{entry.replacement_id}`")
+    return "\n".join(f"- {p}" for p in parts)
+
+
+def build_finding(
+    match: RawMatch,
+    *,
+    repo_root: Path,
+    registry: Registry,
+    run_id: str,
+    today: date | None = None,
+) -> Finding:
+    today = today or datetime.now(UTC).date()
+    canonical_id = canonicalize(match.matched_text)
+    resolution: Resolution = resolve(canonical_id, registry)
+    entry = resolution.entry if isinstance(resolution, Resolved) else None
+
+    verdict = compute_verdict(resolution, today)
+    severity = compute_severity(verdict, resolution, today)
+    confidence = compute_confidence(resolution)
+
+    relative_path = str(match.path.relative_to(repo_root))
+    owner = find_owner(match.path, match.line, repo_root)
+    content_hash = hashlib.sha256(match.path.read_bytes()).hexdigest()
+
+    evidence = Evidence(
+        source_uri=relative_path,
+        locator=str(match.line),
+        excerpt=match.matched_text,
+        retrieved_at=datetime.now(UTC),
+        content_hash=content_hash,
+    )
+
+    return Finding(
+        identity=compute_identity(canonical_id, relative_path, match.symbol),
+        product=ProductCode.EBB,
+        rule_id=RULE_ID,
+        subject=canonical_id,
+        severity=severity,
+        confidence=confidence,
+        title=_title_for(canonical_id, verdict, entry),
+        detail_md=_detail_md_for(canonical_id, entry),
+        evidence=[evidence],
+        owner=owner,
+        deadline=entry.shutdown_at if entry else None,
+        verdict=verdict,
+        # No baseline mechanism exists for ebb's stateless local CLI yet — every finding from a
+        # single `ebb scan` invocation is NEW. See FindingState's own docstring.
+        state=FindingState.NEW,
+        first_seen_run=run_id,
+        rule_version=registry.version,
+        engine_version=ENGINE_VERSION,
+    )
+
+
+def build_findings(
+    repo_root: Path, registry: Registry, *, today: date | None = None
+) -> list[Finding]:
+    """The full pipeline, wired together for the first time: walk -> detect -> canonicalize ->
+    resolve -> owner attribution -> verdict/severity/confidence -> Finding. One run_id shared
+    across every finding from this invocation."""
+    run_id = f"run-{uuid.uuid4()}"
+    return [
+        build_finding(match, repo_root=repo_root, registry=registry, run_id=run_id, today=today)
+        for match in scan_repo(repo_root)
+    ]

ebb/canonicalize.py

@@ -0,0 +1,60 @@
+import re
+
+# Collapses infrastructure-wrapper syntax down to the bare model id a provider's own API would
+# use directly, so the same underlying model is recognized as the same canonical id regardless
+# of which cloud layer referenced it. Every pattern here is verified against live vendor docs
+# (CLAUDE_CODE_PLAN.md's "never write a contract from memory" applies to this too):
+#
+# - AWS Bedrock cross-Region inference profile IDs are exactly "{region}.{vendor}.{model-id}",
+#   e.g. `us.anthropic.claude-3-haiku-20240307-v1:0` — this literal example is drawn straight
+#   from AWS's own inference-profiles-support docs, not invented.
+# - Bedrock (profile or plain) model IDs carry a trailing "-v{N}:{M}" version suffix.
+# - GCP Vertex AI publisher-model resource names are "publishers/{publisher}/models/{model}",
+#   optionally prefixed "projects/{project}/locations/{location}/" — confirmed against Google's
+#   own REST reference for the publisherModels resource.
+# - Vertex AI model *versions* use a trailing "@{N}" suffix — this is GCP's general resource
+#   versioning convention (used across several GCP APIs), not confirmed against a Claude-
+#   specific example, so treat it as a well-hedged structural rule rather than a cited fact.
+#
+# Deliberately NOT handled here: stripping "-latest" / "-preview" style suffixes. Some of those
+# are curated as their own whole registry entries (e.g. `chatgpt-4o-latest`, which OpenAI
+# deprecated as an alias in its own right — see src/ebb/registries/retirements/openai.yaml).
+# Stripping the suffix here would silently break that entry's resolution. A floating alias
+# that ISN'T itself curated stays exactly as unresolvable after canonicalization as it was
+# before — see resolve()'s tests (Session 4) for why that's correct, not a gap.
+_BEDROCK_REGION_PREFIX = re.compile(r"^(us|eu|apac|us-gov)\.")
+_BEDROCK_VENDOR_PREFIX = re.compile(
+    r"^(anthropic|amazon|meta|mistral|cohere|ai21|openai|deepseek|writer)\."
+)
+_BEDROCK_VERSION_SUFFIX = re.compile(r"(-v\d+)?:\d+$")
+_VERTEX_VERSION_SUFFIX = re.compile(r"@\d+$")
+_VERTEX_RESOURCE_PATH = re.compile(
+    r"^(?:projects/[^/]+/locations/[^/]+/)?publishers/[^/]+/models/(?P<model_id>.+)$"
+)
+
+
+def canonicalize(raw_text: str) -> str:
+    """Pure and isolated, per CLAUDE_CODE_PLAN.md Session 5 — no registry lookup, no I/O, no
+    dependency on anything but its own input. Idempotent (canonicalize(canonicalize(x)) ==
+    canonicalize(x) for all x) and round-trips (any of this module's recognized wrapper forms
+    of a given model canonicalizes to the same result as the model's own bare id) — both
+    verified by the property tests in tests/unit/test_canonicalize.py.
+    """
+    text = raw_text.strip()
+
+    vertex_match = _VERTEX_RESOURCE_PATH.match(text)
+    if vertex_match:
+        text = vertex_match.group("model_id")
+
+    text = _VERTEX_VERSION_SUFFIX.sub("", text)
+    text = _BEDROCK_VERSION_SUFFIX.sub("", text)
+
+    region_match = _BEDROCK_REGION_PREFIX.match(text)
+    if region_match:
+        text = text[region_match.end() :]
+
+    vendor_match = _BEDROCK_VENDOR_PREFIX.match(text)
+    if vendor_match:
+        text = text[vendor_match.end() :]
+
+    return text

ebb/cli.py

@@ -0,0 +1,176 @@
+import sys
+from datetime import UTC, datetime
+from importlib import resources
+from pathlib import Path
+
+import typer
+from keel.gate import GateFetchError, gate_identities, maybe_fetch_gate, summarize
+from keel.render.triage_json import render_triage_json
+from keel.report import ReportError, maybe_report
+from keel.triage import TriageResult
+from rich.console import Console
+
+from ebb.brand import BRAND
+from ebb.build_findings import build_findings
+from ebb.finding import Finding, Severity
+from ebb.registry.loader import RegistryLoadError, load_registry
+from ebb.render.annotations import render_annotations
+from ebb.render.json_renderer import render_json
+from ebb.render.markdown import render_markdown
+from ebb.render.sarif import render_sarif
+from ebb.render.terminal import render_terminal
+from ebb.triage import build_triage
+
+_FORMATS = ("table", "markdown", "json", "sarif", "annotations", "triage-json")
+
+app = typer.Typer(
+    name="ebb", help=f"{BRAND} ebb — find model identifiers before a provider retires them."
+)
+console = Console()
+error_console = Console(stderr=True)
+
+_SEVERITY_ORDER = [
+    Severity.INFO,
+    Severity.LOW,
+    Severity.MEDIUM,
+    Severity.HIGH,
+    Severity.CRITICAL,
+]
+
+
+@app.callback()
+def _callback() -> None:
+    """Keeps `scan` addressable as `ebb scan PATH` — without a callback, Typer collapses an
+    app with a single command into a bare `ebb PATH` invocation instead."""
+
+
+def _default_registry_dir() -> Path:
+    # Packaged as data inside the `ebb` distribution (src/ebb/registries/retirements/) so
+    # `uvx foretop-ebb scan .` works on a cold machine with no monorepo checkout in sight
+    # (specs/ebb.md §9's definition of done) — importlib.resources resolves relative to
+    # wherever the installed package actually lives, whether that's an editable workspace
+    # checkout or a normal site-packages install. --registry-dir still overrides this for
+    # anyone pinning to their own fork of the data (specs/ebb.md §5: the registry becomes a
+    # versioned dependency of its own eventually — this is the seam that day reuses).
+    return Path(str(resources.files("ebb") / "registries" / "retirements"))
+
+
+def _render(findings: list[Finding], fmt: str, *, triage: TriageResult | None = None) -> str:
+    if fmt == "table":
+        return render_terminal(findings, no_color=not sys.stdout.isatty())
+    if fmt == "markdown":
+        return render_markdown(findings)
+    if fmt == "json":
+        return render_json(findings)
+    if fmt == "sarif":
+        import json
+
+        return json.dumps(render_sarif(findings), indent=2, sort_keys=True)
+    if fmt == "annotations":
+        return render_annotations(findings)
+    if fmt == "triage-json":
+        assert triage is not None  # guaranteed by the fmt == "triage-json" caller-side guard
+        return render_triage_json(triage)
+    raise ValueError(f"unknown format: {fmt!r}")
+
+
+@app.command()
+def scan(
+    path: Path = typer.Argument(Path("."), help="Repository path to scan."),  # noqa: B008
+    fmt: str = typer.Option(
+        "table",
+        "--format",
+        help="Output format: table, markdown, json, sarif, annotations, or triage-json.",
+    ),
+    registry_dir: Path | None = typer.Option(  # noqa: B008
+        None,
+        "--registry-dir",
+        help="Directory of registry YAML files. Defaults to this repo's registries/retirements/.",
+    ),
+    fail_on: str | None = typer.Option(
+        None,
+        "--fail-on",
+        help="Exit 1 if any finding's severity is at or above this level "
+        "(info, low, medium, high, critical). Unset: always exit 0.",
+    ),
+    report: bool = typer.Option(
+        False,
+        "--report",
+        help="Send this run's findings to the hub (FORETOP_TOKEN required). Off by default. "
+        "Always prints the exact payload before sending — findings are metadata only, "
+        "never your source.",
+    ),
+    gate: bool = typer.Option(
+        False,
+        "--gate",
+        help="Fetch the org's baseline/suppressions from the hub (FORETOP_TOKEN required) and "
+        "exclude matching findings from --fail-on's decision. Off by default; a no-op unless "
+        "--fail-on is also given.",
+    ),
+) -> None:
+    """Scan a repository for model references and report their retirement status.
+
+    Exit codes are an API (specs/ebb.md §6): 0 clean or below --fail-on's threshold, 1 a
+    finding met or exceeded --fail-on, 2 an internal error (bad --format, registry failed to
+    load). These must never be conflated.
+    """
+    if fmt not in _FORMATS:
+        error_console.print(f"Unknown --format {fmt!r}. Choose one of: {', '.join(_FORMATS)}.")
+        raise typer.Exit(code=2)
+
+    threshold: Severity | None = None
+    if fail_on is not None:
+        try:
+            threshold = Severity(fail_on)
+        except ValueError:
+            error_console.print(
+                f"Unknown --fail-on {fail_on!r}. Choose one of: "
+                f"{', '.join(s.value for s in _SEVERITY_ORDER)}."
+            )
+            raise typer.Exit(code=2) from None
+
+    registry_paths = sorted((registry_dir or _default_registry_dir()).glob("*.yaml"))
+    try:
+        registry = load_registry(registry_paths)
+    except RegistryLoadError as exc:
+        error_console.print(f"Registry failed to load: {exc}")
+        raise typer.Exit(code=2) from exc
+
+    findings = build_findings(path.resolve(), registry)
+    # Computed lazily, shared between --format triage-json and --report: build_triage is not
+    # free (classify_usage_role re-reads and re-parses every matched source file), so a plain
+    # scan with neither flag must never pay for it, and giving both flags at once must not pay
+    # for it twice.
+    triage = (
+        build_triage(findings, registry=registry, repo_root=path.resolve())
+        if fmt == "triage-json" or report
+        else None
+    )
+    print(_render(findings, fmt, triage=triage))
+
+    try:
+        maybe_report(enabled=report, product="ebb", path=path, findings=findings, triage=triage)
+    except ReportError as exc:
+        error_console.print(str(exc))
+        raise typer.Exit(code=2) from exc
+
+    if threshold is not None:
+        threshold_rank = _SEVERITY_ORDER.index(threshold)
+        candidates = {
+            f.identity for f in findings if _SEVERITY_ORDER.index(f.severity) >= threshold_rank
+        }
+        # --gate is a no-op both when unset and when there's nothing --fail-on would flag
+        # anyway — no network call in either case, matching --report's own offline-by-default
+        # posture (MARKETING_BRIEF.md: "runs offline, no account").
+        if gate and candidates:
+            try:
+                gate_response = maybe_fetch_gate(enabled=True)
+            except GateFetchError as exc:
+                error_console.print(str(exc))
+                raise typer.Exit(code=2) from exc
+            assert gate_response is not None  # enabled=True always returns a GateResponse
+            result = gate_identities(candidates, gate_response, today=datetime.now(UTC).date())
+            print(summarize(result))
+            candidates -= result.excluded
+        if candidates:
+            raise typer.Exit(code=1)

ebb/detect/base.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class RawMatch:
+    """One model-identifier-shaped string found in a file.
+
+    Line numbers exist for human-readable output only — per SUITE_ARCHITECTURE.md §3.1, line
+    numbers must never enter finding identity. `symbol` is the "normalized surrounding symbol"
+    identity actually uses instead: the identifier immediately governing the matched text (an
+    assignment target, a JSON/YAML/TOML key, a Dockerfile ENV/ARG name), captured at detection
+    time since that's when the full line text is already in hand. See
+    ebb.detect.scan_text.nearest_symbol for exactly what "normalized" means here.
+    """
+
+    path: Path
+    line: int
+    matched_text: str
+    symbol: str
+
+
+class Detector(Protocol):
+    """A pure function `(path, content) -> list[RawMatch]`. No I/O, no side effects — the
+    walker reads file content once and hands it to every detector registered for that file's
+    kind. Adding a language means adding one detector and registering it in registry.py."""
+
+    def __call__(self, path: Path, content: str) -> list[RawMatch]: ...

ebb/detect/dockerfile.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from ebb.detect.base import RawMatch
+from ebb.detect.scan_text import scan_lines
+
+
+def detect(path: Path, content: str) -> list[RawMatch]:
+    return scan_lines(path, content)

ebb/detect/json_format.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from ebb.detect.base import RawMatch
+from ebb.detect.scan_text import scan_lines
+
+
+def detect(path: Path, content: str) -> list[RawMatch]:
+    return scan_lines(path, content)

ebb/detect/notebook.py

@@ -0,0 +1,25 @@
+import json
+from pathlib import Path
+
+from ebb.detect.base import RawMatch
+from ebb.detect.scan_text import scan_lines
+
+
+def detect(path: Path, content: str) -> list[RawMatch]:
+    """Scans every cell's source (code and markdown alike — a model id in a doc cell is still
+    worth surfacing; ranking it belongs to later sessions, not detection). A notebook that
+    fails to parse as JSON yields no matches rather than crashing the walk — one malformed
+    .ipynb must never take down a scan of the other 499 files in the repo."""
+    try:
+        notebook = json.loads(content)
+    except json.JSONDecodeError:
+        return []
+
+    matches: list[RawMatch] = []
+    for cell in notebook.get("cells", []):
+        source = cell.get("source", "")
+        cell_text = source if isinstance(source, str) else "".join(source)
+        # Line numbers are cell-relative, not file-relative — a notebook has no single
+        # meaningful line axis across cells. Informational only, as everywhere in Slice 1.
+        matches.extend(scan_lines(path, cell_text))
+    return matches

ebb/detect/patterns.py

@@ -0,0 +1,51 @@
+import re
+
+# Structural patterns, not an enumerated list: DEC-06 (specs/ebb.md §1) commits to three
+# providers "deeply correct" at launch — OpenAI, Anthropic, Google. Each pattern matches the
+# provider's naming *shape* (including older `claude-3-opus-20240229`-style and newer
+# `claude-opus-4-8`-style Anthropic ids — both conventions exist in the wild) so a model
+# released after this file was written still matches, without needing a code change. This is
+# deliberately looser than the versioned registry (Session 4), which pins exact known-valid ids
+# with source_url/verified_at; Slice 1 only needs "shaped like a model identifier".
+# OpenAI dates ship two conventions: a full ISO date (`-2024-05-13`) and a bare 4-digit code,
+# optionally trailed by `-preview` (`-0125`, `-1106-preview`) — both need to be optional and
+# tried in this order so the longer ISO form isn't shadowed by the shorter one matching a
+# prefix of it.
+_OPENAI_DATE_SUFFIX = r"(?:-\d{4}-\d{2}-\d{2}|-\d{4}(?:-preview)?)"
+# `4\.\d+` (gpt-4.1, gpt-4.1-mini) must come before bare `4` in the alternation: alternatives
+# are tried in order and the first one that lets the overall match succeed wins, so with `4`
+# first, "gpt-4.1" would match only "gpt-4" and silently drop the ".1" that makes it a
+# different, real model. Found via the Session 7 golden corpus, not guessed.
+_OPENAI = (
+    r"\bgpt-(?:4o|4\.\d+|4|3\.5|5(?:\.\d+)?)(?:-turbo|-mini|-nano)?" + _OPENAI_DATE_SUFFIX + r"?\b"
+)
+_OPENAI_O_SERIES = r"\bo[134](?:-preview|-mini|-pro)?" + _OPENAI_DATE_SUFFIX + r"?\b"
+_OPENAI_EMBEDDING = r"\btext-embedding-(?:ada-002|3-small|3-large)\b"
+_OPENAI_OTHER = r"\b(?:dall-e-[23]|whisper-1)\b"
+
+_ANTHROPIC_DATED = (
+    r"\bclaude-\d(?:[.-]\d)?(?:-(?:opus|sonnet|haiku|instant))?(?:-\d{8})?(?:-latest)?\b"
+)
+# Tier-before-version: covers both the old `claude-instant-1.2` (dotted) and the current
+# `claude-opus-4-8` / `claude-haiku-4-5-20251001` (hyphenated) conventions.
+_ANTHROPIC_NAMED = r"\bclaude-(?:opus|sonnet|haiku|fable|instant)-\d+(?:[.-]\d+)?(?:-\d{8})?\b"
+
+_GOOGLE_GEMINI = (
+    r"\bgemini-\d(?:\.\d)?(?:-pro|-flash|-ultra)?(?:-vision)?(?:-\d{3})?(?:-preview|-exp)?\b"
+)
+_GOOGLE_BISON = r"\b(?:text|chat)-bison(?:-00[12])?\b"
+
+MODEL_ID_PATTERN = re.compile(
+    "|".join(
+        [
+            _OPENAI,
+            _OPENAI_O_SERIES,
+            _OPENAI_EMBEDDING,
+            _OPENAI_OTHER,
+            _ANTHROPIC_DATED,
+            _ANTHROPIC_NAMED,
+            _GOOGLE_GEMINI,
+            _GOOGLE_BISON,
+        ]
+    )
+)

ebb/detect/python.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from ebb.detect.base import RawMatch
+from ebb.detect.scan_text import scan_lines
+
+
+def detect(path: Path, content: str) -> list[RawMatch]:
+    return scan_lines(path, content)

ebb/detect/registry.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+from ebb.detect import dockerfile, json_format, notebook, python, terraform, toml, typescript, yaml
+from ebb.detect.base import Detector
+
+_BY_EXTENSION: dict[str, Detector] = {
+    ".py": python.detect,
+    ".ts": typescript.detect,
+    ".tsx": typescript.detect,
+    ".yml": yaml.detect,
+    ".yaml": yaml.detect,
+    ".toml": toml.detect,
+    ".json": json_format.detect,
+    ".tf": terraform.detect,
+    ".ipynb": notebook.detect,
+}
+
+
+def get_detector(path: Path) -> Detector | None:
+    """Adding a language: add one file under detect/, one entry here (or one more filename
+    rule below for extension-less formats), and one fixture under tests/fixtures/. Nothing
+    else in the walker or CLI needs to change."""
+    if path.name == "Dockerfile" or path.name.startswith("Dockerfile."):
+        return dockerfile.detect
+    return _BY_EXTENSION.get(path.suffix)

ebb/detect/scan_text.py

@@ -0,0 +1,46 @@
+import re
+from pathlib import Path
+
+from ebb.detect.base import RawMatch
+from ebb.detect.patterns import MODEL_ID_PATTERN
+
+# The identifier immediately before the nearest '=' or ':' preceding a match on its own line —
+# covers Python/TypeScript assignments (MODEL = "..."), JSON/YAML/TOML keys ("model": "...",
+# model: ...), and Dockerfile ENV/ARG forms (ENV MODEL=...). Language-agnostic on purpose: a
+# real per-language symbol table (AST-scoped to the enclosing function/class) would be far more
+# precise, but is a much bigger undertaking than this session's scope — this heuristic is
+# "good enough to keep identity stable across reformatting," which is the actual requirement
+# (SUITE_ARCHITECTURE.md §3.1), not "semantically perfect."
+_ASSIGNMENT_PATTERN = re.compile(r"([A-Za-z_][A-Za-z0-9_.\-]*)[\"']?\s*[:=]")
+_MAX_FALLBACK_SYMBOL_LENGTH = 40
+
+
+def nearest_symbol(line: str, match_start: int) -> str:
+    """Never empty: falls back to a bounded prefix of the line itself (e.g. a bare string in a
+    list has no assignment to name it), and finally to "unknown" for a blank line — every match
+    gets a stable, non-empty symbol so identity never depends on an absent one."""
+    prefix = line[:match_start]
+    candidates = list(_ASSIGNMENT_PATTERN.finditer(prefix))
+    if candidates:
+        return candidates[-1].group(1)
+    stripped = line.strip()
+    return stripped[:_MAX_FALLBACK_SYMBOL_LENGTH] if stripped else "unknown"
+
+
+def scan_lines(path: Path, content: str) -> list[RawMatch]:
+    """Line-oriented regex scan shared by every format where a model id appears as plain text
+    inside otherwise-structured content (source code, YAML/TOML/JSON values, Terraform,
+    Dockerfiles). One RawMatch per occurrence — no dedup here, that's identity's job later
+    (SUITE_ARCHITECTURE.md §3.1), not the raw-match layer's."""
+    matches: list[RawMatch] = []
+    for lineno, line in enumerate(content.splitlines(), start=1):
+        for m in MODEL_ID_PATTERN.finditer(line):
+            matches.append(
+                RawMatch(
+                    path=path,
+                    line=lineno,
+                    matched_text=m.group(0),
+                    symbol=nearest_symbol(line, m.start()),
+                )
+            )
+    return matches

ebb/detect/terraform.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from ebb.detect.base import RawMatch
+from ebb.detect.scan_text import scan_lines
+
+
+def detect(path: Path, content: str) -> list[RawMatch]:
+    return scan_lines(path, content)

ebb/detect/toml.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from ebb.detect.base import RawMatch
+from ebb.detect.scan_text import scan_lines
+
+
+def detect(path: Path, content: str) -> list[RawMatch]:
+    return scan_lines(path, content)

ebb/detect/typescript.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from ebb.detect.base import RawMatch
+from ebb.detect.scan_text import scan_lines
+
+
+def detect(path: Path, content: str) -> list[RawMatch]:
+    return scan_lines(path, content)

ebb/detect/yaml.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from ebb.detect.base import RawMatch
+from ebb.detect.scan_text import scan_lines
+
+
+def detect(path: Path, content: str) -> list[RawMatch]:
+    return scan_lines(path, content)

ebb/finding.py

@@ -0,0 +1,34 @@
+"""Re-export shim: the Finding schema moved to keel.finding in Session 26.
+
+SUITE_ARCHITECTURE.md §3 always called this "the keystone: everything flows from this" and
+listed all five products in ProductCode — but the module lived here, in ebb, and four of five
+products never emitted a Finding at all. Session 26 moved it to packages/keel so the other
+four can adopt it one at a time (telltale first), because every paid tier on the pricing page
+is a query across products and that needs one shape in one table.
+
+This shim keeps `from ebb.finding import ...` working unchanged for ebb's own eight importing
+modules — same approach apps/telltale/src/telltale/walk.py (Session 10) and
+apps/undertow-crawler/src/undertow_crawler/fetch.py (Session 20) already use for their own
+extractions. ebb's behaviour did not change; its full test suite passing untouched is the
+proof.
+"""
+
+from keel.finding import (
+    Confidence,
+    Evidence,
+    Finding,
+    FindingState,
+    ProductCode,
+    Severity,
+    Verdict,
+)
+
+__all__ = [
+    "Confidence",
+    "Evidence",
+    "Finding",
+    "FindingState",
+    "ProductCode",
+    "Severity",
+    "Verdict",
+]