Light, fluffy, and always free - The AWS Local Emulator alternative
#!/usr/bin/env python3
"""Fail CI when a registered service has no row in the docs/services/index.md matrix.
`ResolvedServiceCatalog.java` is the source of truth for which AWS services Floci
emulates: every `descriptor("externalKey", "configKey", ...)` call registers one.
`docs/services/index.md` is the human-facing matrix users browse to find out what's
supported. Nothing previously connected the two, so a service could be registered,
enabled and routable while remaining absent from the matrix with every other check
green (see floci-io/floci#2454 - four services, and Bedrock AgentCore for five days,
shipped without a row).
This script closes that gap the same way regen_action_docs.py's unregistered-handler
sentinel closes the equivalent gap for action tables: extract descriptor keys from
Java source, extract documented filenames from the matrix, and fail on anything that
resolves to neither - unless tools/docs/service_matrix.yaml says otherwise (an alias
for a key whose AWS signing name differs from its doc filename, or a time-boxed
deferred entry for a service that is genuinely not documented yet).
The reverse direction is checked too: every docs/services/*.md page must have a
matrix row, unless listed under `facet_pages:` in the registry, so a page can no
longer exist in the nav with no row (elb-classic.md did, hidden by the `elb` key
exact-matching the v2 page).
Run from anywhere in the repo:
python3 tools/docs/check_service_matrix.py # print warnings only
python3 tools/docs/check_service_matrix.py --strict # exit non-zero on warnings
"""
from __future__ import annotations
import argparse
import re
import sys
from dataclasses import dataclass
from datetime import date
from pathlib import Path
try:
from tools.docs import regen_action_docs
except ModuleNotFoundError:
import regen_action_docs
import yaml
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from java_sources import PACKAGE_DIR, package_source # noqa: E402
CATALOG_SOURCE = f"{PACKAGE_DIR}/core/common/ResolvedServiceCatalog.java"
MATRIX_DOC = "docs/services/index.md"
REGISTRY = "tools/docs/service_matrix.yaml"
# These grouped rows already have one dispatcher each; removing a registry entry
# must not silently turn off their count check.
REQUIRED_ACTION_COUNT_SOURCES = frozenset({
"autoscaling", "cloudmap", "codebuild", "codedeploy", "cognito", "config",
"ec2", "ecs", "elastic-beanstalk", "elb", "elb-classic", "glue", "iam",
"resource-groups-tagging",
})
MATRIX_HEADING = "## Service Matrix"
MATRIX_END_HEADING = "## Common Setup"
# The externalKey is the first string literal argument to descriptor(...). It's always
# a plain double-quoted literal (no concatenation, no constants) in current usage.
DESCRIPTOR_KEY_RE = re.compile(r'\bdescriptor\(\s*"([^"]+)"')
# Every descriptor(...) call site, literal-keyed or not - used only to catch a call this
# parser's literal-only DESCRIPTOR_KEY_RE would otherwise miss in total silence (a future
# externalKey built from a variable or constant instead of a plain string literal). The
# negative lookbehind excludes the `private static ServiceDescriptor descriptor(...)`
# definition itself, the one place "descriptor(" appears that isn't a call.
ALL_DESCRIPTOR_CALLS_RE = re.compile(r"(?<!ServiceDescriptor )\bdescriptor\(")
# A matrix row's first cell is a markdown link to its doc page: `[Label](slug.md...)`.
# The slug is everything up to `.md`; a trailing `#anchor` (e.g. `cloudwatch.md#metrics`)
# is not part of the filename and is dropped by stopping the match at `.md` itself.
MATRIX_LINK_RE = re.compile(r"\]\(([a-z0-9][a-z0-9\-]*)\.md")
SERVICES_DIR = "docs/services"
@dataclass(frozen=True)
class DeferredEntry:
key: str
reason: str
by: date
def extract_descriptor_keys(java_source: str) -> list[str]:
"""externalKey of every descriptor(...) call, in source order.
May contain dupes only if the source itself registers the same externalKey twice
(a copy-paste bug); the caller dedups via set() before comparing against the matrix.
"""
return DESCRIPTOR_KEY_RE.findall(java_source)
def count_descriptor_calls(java_source: str) -> int:
"""Total descriptor(...) call sites, regardless of how the first argument is built."""
return len(ALL_DESCRIPTOR_CALLS_RE.findall(java_source))
def extract_matrix_slugs(md_source: str) -> set[str]:
"""Doc filenames (no extension, no anchor) linked from the Service Matrix table.
Scoped to the table between MATRIX_HEADING and MATRIX_END_HEADING so an unrelated
markdown link elsewhere on the page (prose, footer) can never be mistaken for a
documented row. Raises ValueError if either heading is missing, rather than letting
a renamed heading silently empty the table (and every service look undocumented).
"""
try:
start = md_source.index(MATRIX_HEADING)
end = md_source.index(MATRIX_END_HEADING, start)
except ValueError:
raise ValueError(
f"{MATRIX_DOC}: could not find '{MATRIX_HEADING}' ... '{MATRIX_END_HEADING}' "
"(has a heading been renamed or reordered?)"
) from None
table = md_source[start:end]
return set(MATRIX_LINK_RE.findall(table))
def extract_matrix_action_counts(md_source: str) -> dict[str, int]:
"""Extract documented operation counts for base service-doc rows.
Supports both plain numeric counts and composite counts such as
``61 (+ 3 tagging ...)``.
Rows linking to a document anchor are ignored because the linked
document may contain multiple distinct action sections.
"""
try:
start = md_source.index(MATRIX_HEADING)
end = md_source.index(MATRIX_END_HEADING, start)
except ValueError:
raise ValueError(
f"{MATRIX_DOC}: could not find '{MATRIX_HEADING}' ... "
f"'{MATRIX_END_HEADING}' (has a heading been renamed or reordered?)"
) from None
counts: dict[str, int] = {}
for line in md_source[start:end].splitlines():
match = re.match(
r"^\|\s*\[[^\]]+\]\(([a-z0-9][a-z0-9\-]*)\.md"
r"(#[^)]*)?\)\s*\|.*\|\s*(\d+)"
r"(?:\s*\(\+\s*(\d+)[^)]*\))?\s*\|$",
line,
)
if not match:
continue
slug, anchor, base_count, extra_count = match.groups()
if anchor:
continue
counts.setdefault(slug, int(base_count))
return counts
def count_generated_actions(md_source: str) -> int | None:
"""Count action rows inside a generated action-table marker pair.
Returns None when the document does not contain a generated action table.
"""
start_marker = "<!-- floci:actions:start -->"
end_marker = "<!-- floci:actions:end -->"
try:
start = md_source.index(start_marker) + len(start_marker)
end = md_source.index(end_marker, start)
except ValueError:
return None
section = md_source[start:end]
count = 0
for line in section.splitlines():
line = line.strip()
if not line.startswith("|") or line.count("|") < 3:
continue
# Skip the markdown header/separator rows.
if re.match(r"^\|\s*Action\s*\|", line, re.IGNORECASE):
continue
if re.match(r"^\|\s*:?-{3,}", line):
continue
count += 1
return count
def extract_action_counts(repo_root: Path, required_sources: frozenset[str] = frozenset()) -> dict[str, int]:
"""Extract mechanically verifiable action counts.
Generated service documents are counted from their generated action-table
markers. Explicitly mapped non-tabular Query/JSON dispatchers are counted
from source with the same action parser as regen_action_docs.py. Mixed and
anchored rows remain outside this check until their operations can be
attributed to a single matrix row.
"""
md_source = (repo_root / MATRIX_DOC).read_text(encoding="utf-8")
matrix_counts = extract_matrix_action_counts(md_source)
counts: dict[str, int] = {}
# Generated service documents.
for slug in sorted(extract_matrix_slugs(md_source)):
doc_path = repo_root / SERVICES_DIR / f"{slug}.md"
if not doc_path.exists():
continue
doc_source = doc_path.read_text(encoding="utf-8")
generated_count = count_generated_actions(doc_source)
if generated_count is not None:
if slug not in matrix_counts:
raise ValueError(
f"{MATRIX_DOC}: '{slug}' needs a numeric matrix row for its generated action table"
)
counts[slug] = generated_count
registry = yaml.safe_load((repo_root / REGISTRY).read_text(encoding="utf-8")) or {}
sources = registry.get("action_count_sources")
if not isinstance(sources, dict) or not sources:
raise ValueError(f"{REGISTRY}: action_count_sources must be a non-empty mapping")
missing = required_sources - sources.keys()
if missing:
raise ValueError(f"{REGISTRY}: required action count source(s) missing: {', '.join(sorted(missing))}")
for slug, relative_path in sources.items():
if slug not in matrix_counts:
raise ValueError(f"{REGISTRY}: action count source '{slug}' has no numeric matrix row")
if slug in counts:
raise ValueError(f"{REGISTRY}: '{slug}' already has a generated action table")
if not isinstance(relative_path, str):
raise ValueError(f"{REGISTRY}: action count source '{slug}' needs a source path")
actions = regen_action_docs.extract_switch_actions(
(repo_root / package_source(relative_path)).read_text(encoding="utf-8")
)
if not actions:
raise ValueError(f"{REGISTRY}: action count source '{slug}' has no actions")
counts[slug] = len(set(actions))
return counts
def find_unlinked_pages(services_dir: Path, slugs: set[str], facet_pages: set[str]) -> list[str]:
"""docs/services pages (by slug) that no matrix row links and no facet entry excuses.
index.md is the matrix page itself and is never expected to link to itself.
"""
pages = sorted(p.stem for p in services_dir.glob("*.md") if p.name != "index.md")
return [page for page in pages if page not in slugs and page not in facet_pages]
def _load_registry(repo_root: Path) -> tuple[dict[str, str], list[DeferredEntry], set[str]]:
"""Load service_matrix.yaml. Returns (aliases, deferred entries, facet pages).
Schema: `aliases:` maps an externalKey to the doc slug that documents it;
`deferred:` lists externalKeys with no row yet, each requiring `reason` and a
`by` expiry date (see service_matrix.yaml's header comment for why expiry is
mandatory rather than a permanent bypass); `facet_pages:` lists docs/services
slugs that deliberately have no matrix row of their own.
"""
raw = yaml.safe_load((repo_root / REGISTRY).read_text(encoding="utf-8")) or {}
aliases = dict(raw.get("aliases") or {})
facet_pages = set(raw.get("facet_pages") or [])
deferred: list[DeferredEntry] = []
for item in raw.get("deferred") or []:
missing = [f for f in ("key", "reason", "by") if f not in item]
if missing:
raise ValueError(
f"{REGISTRY}: deferred entry {item!r} is missing required field(s): {missing}"
)
deferred.append(
DeferredEntry(
key=item["key"],
reason=item["reason"],
by=date.fromisoformat(str(item["by"])),
)
)
return aliases, deferred, facet_pages
def find_undocumented(
keys: list[str],
slugs: set[str],
aliases: dict[str, str],
deferred: list[DeferredEntry],
today: date,
) -> tuple[list[str], list[DeferredEntry]]:
"""Classify descriptor keys against the matrix.
Returns (undocumented, expired_deferred):
- undocumented: keys that resolve to no matrix row by exact match, alias, or an
unexpired deferred entry. Includes keys whose only deferred entry has expired.
- expired_deferred: the deferred entries (still present in the registry) whose
`by` date has passed - reported separately so the warning names the date and
reason instead of reading like a brand-new, unexplained gap.
"""
active_deferred = {d.key: d for d in deferred if d.by >= today}
expired = [d for d in deferred if d.by < today]
undocumented: list[str] = []
for key in sorted(set(keys)):
target = aliases.get(key, key)
if target in slugs:
continue
if key in active_deferred:
continue
undocumented.append(key)
expired_deferred = [d for d in expired if d.key in set(keys) and aliases.get(d.key, d.key) not in slugs]
return undocumented, expired_deferred
def _repo_root() -> Path:
return Path(__file__).resolve().parent.parent.parent
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--strict",
action="store_true",
help="treat warnings (undocumented services, expired deferrals) as errors",
)
args = parser.parse_args(argv)
repo_root = _repo_root()
try:
aliases, deferred, facet_pages = _load_registry(repo_root)
except (ValueError, yaml.YAMLError) as exc:
print(f"error: {exc}", file=sys.stderr)
return 1
java_source = (repo_root / CATALOG_SOURCE).read_text(encoding="utf-8")
keys = extract_descriptor_keys(java_source)
if not keys:
print(f"error: no descriptor(...) calls found in {CATALOG_SOURCE}", file=sys.stderr)
return 1
total_calls = count_descriptor_calls(java_source)
if total_calls != len(keys):
# DESCRIPTOR_KEY_RE only matches a plain double-quoted externalKey. A call built
# from a variable or constant would be silently invisible to every check below -
# this is the one place that gap gets caught instead of just under-counting.
print(
f"error: {CATALOG_SOURCE} has {total_calls} descriptor(...) call(s) but only "
f"{len(keys)} have a plain string-literal externalKey as the first argument; "
"the rest are invisible to this script and need a parser update",
file=sys.stderr,
)
return 1
md_source = (repo_root / MATRIX_DOC).read_text(encoding="utf-8")
try:
slugs = extract_matrix_slugs(md_source)
except ValueError as exc:
print(f"error: {exc}", file=sys.stderr)
return 1
try:
matrix_action_counts = extract_matrix_action_counts(md_source)
source_action_counts = extract_action_counts(repo_root, REQUIRED_ACTION_COUNT_SOURCES)
except (ValueError, OSError, yaml.YAMLError) as exc:
print(f"error: {exc}", file=sys.stderr)
return 1
undocumented, expired_deferred = find_undocumented(
keys, slugs, aliases, deferred, date.today()
)
warnings: list[str] = []
for slug, documented_count in matrix_action_counts.items():
source_count = source_action_counts.get(slug)
if source_count is None:
continue
if documented_count != source_count:
warnings.append(
f"service '{slug}' documents {documented_count} supported operations "
f"in {MATRIX_DOC}, but the action source contains {source_count}; "
"update the matrix count"
)
for d in expired_deferred:
warnings.append(
f"deferred entry '{d.key}' expired on {d.by.isoformat()} ({d.reason}); "
f"add its docs/services/index.md row or renew the expiry in {REGISTRY}"
)
still_undocumented = set(undocumented) - {d.key for d in expired_deferred}
for key in sorted(still_undocumented):
warnings.append(
f"service '{key}' is registered in {CATALOG_SOURCE} but has no row in "
f"{MATRIX_DOC} (add a row, an alias, or a time-boxed entry in {REGISTRY})"
)
for page in find_unlinked_pages(repo_root / SERVICES_DIR, slugs, facet_pages):
warnings.append(
f"{SERVICES_DIR}/{page}.md has no row in {MATRIX_DOC} (add a row, or list it "
f"under facet_pages in {REGISTRY} if it is a facet of another service's page)"
)
for w in warnings:
print(f"warning: {w}", file=sys.stderr)
if args.strict and warnings:
return 1
return 0
if __name__ == "__main__":
sys.exit(main())