Light, fluffy, and always free - The AWS Local Emulator alternative
feat(docs): guard the service matrix against undocumented services (#2465)
Matheus Oliveira700acc65c780
diff --git a/Makefile b/Makefileindex 3894362783..5081a73142 100644--- a/Makefile+++ b/Makefile@@ -2,6 +2,9 @@## Action-table docs: docs/services/*.md "Supported Actions" tables are generated# from handler source. See tools/docs/.+#+# Service-matrix docs: docs/services/index.md's Service Matrix table is checked+# against ResolvedServiceCatalog.java so a registered service can't ship undocumented.PYTHON ?= python3@@ -10,7 +13,7 @@ PYTHON ?= python3docs-sync: ## Regenerate the action tables in docs/services from handler source (in place)$(PYTHON) tools/docs/regen_action_docs.py-docs-check: ## CI gate: regenerate and fail if anything is stale or a handler is unregistered+docs-check: ## CI gate: regenerate and fail if anything is stale, unregistered, or undocumented@$(PYTHON) tools/docs/regen_action_docs.py --strict || { \echo ""; \echo "error: action-table regeneration reported problems (see warnings above)."; \@@ -22,6 +25,11 @@ docs-check: ## CI gate: regenerate and fail if anything is stale or a handler isecho " Run 'make docs-sync' and commit the result."; \exit 1; \}+ @$(PYTHON) tools/docs/check_service_matrix.py --strict || { \+ echo ""; \+ echo "error: a registered service has no row in docs/services/index.md (see warnings above)."; \+ exit 1; \+ }-docs-test: ## Run the action-table tooling tests+docs-test: ## Run the docs tooling's unit tests$(PYTHON) -m pytest tools/docs -qdiff --git a/README.md b/README.mdindex e65ca9cfc5..3d0267b84c 100644--- a/README.md+++ b/README.md@@ -178,7 +178,7 @@ LocalStack's community edition [sunset in March 2026](https://blog.localstack.cl| CodeBuild | Real Docker execution | No || Native binary | ~40 MB | No |-**73 AWS services. Broad coverage. Free forever.**+**76 AWS services. Broad coverage. Free forever.**## Architecture Overviewdiff --git a/docs/services/cloudcontrol.md b/docs/services/cloudcontrol.mdnew file mode 100644index 0000000000..708a6438ce--- /dev/null+++ b/docs/services/cloudcontrol.md@@ -0,0 +1,43 @@+# Cloud Control API++**Protocol:** JSON 1.1 (`X-Amz-Target: CloudApiService.*`)+**Endpoint:** `POST http://localhost:4566/`++Cloud Control provides a uniform CRUD(L) surface over CloudFormation resource types+(`AWS::S3::Bucket`, `AWS::EC2::Instance`, ...) instead of a bespoke API per service.+Floci's emulator reuses the same resource provisioner CloudFormation stacks call, so a+resource behaves consistently whether it's provisioned by a stack or directly through+Cloud Control.++## Supported Operations++| Operation | Description |+| --- | --- |+| `CreateResource` | Provision a resource of the given `TypeName` from a `DesiredState` JSON document |+| `DeleteResource` | Delete a resource by `TypeName` and `Identifier` |+| `GetResource` | Read a resource's current properties by `TypeName` and `Identifier` |+| `ListResources` | List resources of a `TypeName` |+| `GetResourceRequestStatus` | Poll a `CreateResource`/`DeleteResource` request by its token |++## Behavior++- **Asynchronous create/delete**: `CreateResource` returns an `IN_PROGRESS` `ProgressEvent`+ and a request token immediately; provisioning runs in the background. Poll+ `GetResourceRequestStatus` with the token until the status is `SUCCESS` or `FAILED`.+ `DeleteResource` is synchronous (deletes are fast enough not to need polling) but+ still returns a `ProgressEvent` for API-shape consistency.+- **`ListResources` / `GetResource` type coverage**: the read side lists+ `AWS::S3::Bucket`, `AWS::EC2::VPC`, `AWS::EC2::Subnet`, `AWS::EC2::SecurityGroup`,+ `AWS::EC2::Instance`, `AWS::EC2::LaunchTemplate`, `AWS::IAM::Role`, `AWS::IAM::User`,+ and `AWS::IAM::InstanceProfile`. `CreateResource` accepts any type the underlying+ CloudFormation resource provisioner supports (the same set stacks can provision),+ which is broader than the read side. A resource created through Cloud Control but+ outside the read-side type list is still readable via `GetResource`, from+ create-time state, but will not appear in `ListResources`.+- **Delete needs create-time state**: types whose delete depends on attributes+ captured at create time (currently `AWS::EKS::Nodegroup` and `AWS::IAM::Policy`, plus+ any `Custom::*` / `AWS::CloudFormation::CustomResource`) fail `DeleteResource` with a+ clear error if that state isn't held, rather than reporting `SUCCESS` over a resource+ that's still there.+- **No account context**: Cloud Control requests don't carry an account id; Floci uses+ its default test account (`000000000000`) for all resources.diff --git a/docs/services/index.md b/docs/services/index.mdindex 87a4babc2d..6e19f86f7e 100644--- a/docs/services/index.md+++ b/docs/services/index.md@@ -1,6 +1,6 @@# Services Overview-Floci emulates 73 AWS services on a single port (`4566`). All services use the real AWS wire protocol, your existing AWS CLI commands and SDK clients work without modification.+Floci emulates 76 AWS services on a single port (`4566`). All services use the real AWS wire protocol, your existing AWS CLI commands and SDK clients work without modification.This page is the canonical reference for supported service and operation counts. Some services expose separate control-plane and data-plane rows below. Other docs (and the README) should link here rather than duplicating the table.@@ -33,7 +33,9 @@ Operation counts are exact. For dispatch-table services (Query and JSON 1.1) eac| [Managed Service for Apache Flink](kinesisanalytics.md) | `POST /` + `X-Amz-Target: KinesisAnalytics_20180523.*` | JSON 1.1 | 7 || [Secrets Manager](secrets-manager.md) | `POST /` + `X-Amz-Target: secretsmanager.*` | JSON 1.1 | 16 || [Step Functions](step-functions.md) | `POST /` + `X-Amz-Target: AmazonStatesService.*` | JSON 1.1 | 19 |+| [SWF](swf.md) | `POST /` + `X-Amz-Target: SimpleWorkflowService.*` | JSON 1.0 | 39 || [CloudFormation](cloudformation.md) | `POST /` with `Action=` param | Query | 19 |+| [Cloud Control API](cloudcontrol.md) | `POST /` + `X-Amz-Target: CloudApiService.*` | JSON 1.1 | 5 || [EventBridge](eventbridge.md) | `POST /` + `X-Amz-Target: AmazonEventBridge.*` | JSON 1.1 | 16 || [EventBridge Scheduler](scheduler.md) | `/schedules/*`, `/schedule-groups/*`, `/tags/*` | REST JSON | 12 || [EventBridge Pipes](pipes.md) | `/v1/pipes/*` | REST JSON | 7 |@@ -53,6 +55,7 @@ Operation counts are exact. For dispatch-table services (Query and JSON 1.1) eac| [Neptune](neptune.md) | `POST /` with `Action=` param + Gremlin TCP proxy | Query + WebSocket | 8 || [DocumentDB](docdb.md) | `POST /` with `Action=` param + MongoDB container | Query + MongoDB wire | 8 || [EMR](emr.md) | `POST /` + `X-Amz-Target: ElasticMapReduce.*` | JSON 1.1 | 24 |+| [EMR Serverless](emr-serverless.md) | `/applications/*` | REST JSON | 7 || [Data Firehose](firehose.md) | `POST /` + `X-Amz-Target: Firehose_20150804.*` | JSON 1.1 | 6 || [ECS](ecs.md) | `POST /` + `X-Amz-Target: AmazonEC2ContainerServiceV20141113.*` | JSON 1.1 | 58 || [EC2](ec2.md) | `POST /` with `Action=` param | EC2 Query | 78 |diff --git a/mkdocs.yml b/mkdocs.ymlindex a5c9fdc9b6..441fba53ee 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -93,6 +93,7 @@ nav:- Managed Service for Apache Flink: services/kinesisanalytics.md- Secrets Manager: services/secrets-manager.md- CloudFormation: services/cloudformation.md+ - Cloud Control API: services/cloudcontrol.md- Step Functions: services/step-functions.md- SWF: services/swf.md- IAM: services/iam.md@@ -147,6 +148,7 @@ nav:- AWS Config: services/config.md- CloudTrail: services/cloudtrail.md- EMR: services/emr.md+ - EMR Serverless: services/emr-serverless.md- WAF v2: services/wafv2.md- Textract: services/textract.md- Transcribe: services/transcribe.mddiff --git a/tools/docs/check_service_matrix.py b/tools/docs/check_service_matrix.pynew file mode 100644index 0000000000..a19b329519--- /dev/null+++ b/tools/docs/check_service_matrix.py@@ -0,0 +1,231 @@+#!/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).++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++import yaml++CATALOG_SOURCE = "src/main/java/io/github/hectorvent/floci/core/common/ResolvedServiceCatalog.java"+MATRIX_DOC = "docs/services/index.md"+REGISTRY = "tools/docs/service_matrix.yaml"++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")+++@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 _load_registry(repo_root: Path) -> tuple[dict[str, str], list[DeferredEntry]]:+ """Load service_matrix.yaml. Returns (aliases, deferred entries).++ 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).+ """+ raw = yaml.safe_load((repo_root / REGISTRY).read_text(encoding="utf-8")) or {}+ aliases = dict(raw.get("aliases") 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+++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 = _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++ undocumented, expired_deferred = find_undocumented(+ keys, slugs, aliases, deferred, date.today()+ )++ warnings: list[str] = []+ 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 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())diff --git a/tools/docs/service_matrix.yaml b/tools/docs/service_matrix.yamlnew file mode 100644index 0000000000..ea6c51190b--- /dev/null+++ b/tools/docs/service_matrix.yaml@@ -0,0 +1,57 @@+# Registry for the service-matrix presence check (tools/docs/check_service_matrix.py).+#+# Every descriptor("externalKey", "configKey", ...) registered in+# core/common/ResolvedServiceCatalog.java must resolve to a row in the Service Matrix+# table in docs/services/index.md, keyed by the .md filename its row links to (no+# extension, no #anchor). A key resolves one of three ways:+#+# 1. exact match - externalKey literally equals a documented filename. No entry+# needed in this file; most services work this way.+# 2. aliases - externalKey differs from the filename that documents it, because+# it's an AWS SigV4 signing-name quirk (`kafka` -> msk.md) or a+# facet folded into another service's page (`ec2messages` -> ssm.md).+# 3. deferred - genuinely undocumented today, tracked with a reason. A NEW+# descriptor key that is neither an exact match, an alias target,+# nor listed here fails `check_service_matrix.py --strict`.++aliases:+ apigateway: api-gateway # "API Gateway v1" row title+ apigatewayv2: api-gateway # v2 facet, documented at api-gateway.md#v2+ kafka: msk # MSK's SigV4 signing name is "kafka"+ mq: amazonmq # Amazon MQ's SigV4 signing name is "mq"+ signin: iam # AWS Sign-In facet, at iam.md#aws-sign-in-login-credentials+ events: eventbridge+ servicediscovery: cloudmap # Cloud Map's SigV4 signing name+ elasticmapreduce: emr # EMR's SigV4 signing name+ logs: cloudwatch # CloudWatch Logs facet, at cloudwatch.md+ monitoring: cloudwatch # CloudWatch Metrics facet, at cloudwatch.md#metrics+ secretsmanager: secrets-manager+ cognito-idp: cognito # Cognito's SigV4 signing name+ states: step-functions # Step Functions' SigV4 signing name+ email: ses # SES's SigV4 signing name+ es: opensearch # OpenSearch's SigV4 signing name (legacy Elasticsearch)+ appconfigdata: appconfig # data-plane facet, at appconfig.md#data-plane+ tagging: resource-groups-tagging # Resource Groups Tagging API's SigV4 signing name+ elasticloadbalancing: elb # ELB v2's SigV4 signing name+ application-autoscaling: applicationautoscaling+ elasticbeanstalk: elastic-beanstalk+ ec2messages: ssm # SSM Messages facet, documented alongside ssm.md+ iotdata: iot # IoT Data row shares iot.md with IoT Core++# A NEW switch/REST descriptor not listed here and not resolvable via an alias fails+# `--strict`. Every entry MUST carry a `by:` expiry date (ISO, YYYY-MM-DD): once that+# date passes, `--strict` fails for it exactly as if it were never listed, even though+# the entry is still physically present in this file. This is deliberate - an+# unbounded deferred list is a silent, permanent bypass of the whole check, which is+# how Bedrock AgentCore (#2316) shipped a working service that stayed off the matrix+# for five days with nothing red anywhere. An expiring entry forces a human to either+# add the row or come back and renew the date with a fresh justification; it can never+# just be forgotten. Remove an entry outright once the referenced PR merges and the+# row lands - don't wait for it to expire.+deferred:+ - key: bedrock-agentcore+ reason: "documented by floci-io/floci#2436 (open at time of writing)"+ by: "2026-09-15"+ - key: bedrock-agentcore-control+ reason: "documented by floci-io/floci#2436 (open at time of writing)"+ by: "2026-09-15"diff --git a/tools/docs/test_check_service_matrix.py b/tools/docs/test_check_service_matrix.pynew file mode 100644index 0000000000..9d3c287108--- /dev/null+++ b/tools/docs/test_check_service_matrix.py@@ -0,0 +1,179 @@+"""Tests for check_service_matrix.++Run with: pytest tools/docs -q (or: make docs-test)+"""+from __future__ import annotations++from datetime import date++import pytest++import check_service_matrix as c+++# --------------------------------------------------------------------------- #+# Extraction+# --------------------------------------------------------------------------- #+def test_extract_descriptor_keys_basic():+ src = '''+ descriptor("ssm", "ssm", config.services().ssm().enabled(), true,+ "ssm", storageMode(...), 5000L, null, ServiceProtocol.JSON,+ protocols(ServiceProtocol.JSON),+ Set.of("AmazonSSM."), Set.of("ssm"), Set.of(), Set.of()),+ descriptor("sqs", "sqs", config.services().sqs().enabled(), true, ...),+ '''+ assert c.extract_descriptor_keys(src) == ["ssm", "sqs"]+++def test_extract_descriptor_keys_ignores_other_string_literals():+ # Only the first argument of descriptor(...) counts; targetPrefixes, credential+ # scopes and the like must not be picked up even though they're also quoted.+ src = 'descriptor("kafka", "msk", true, true, "msk", null, 5000L, null, X, Y, Set.of("kafka-signing-prefix."), Set.of("kafka"), Set.of(), Set.of())'+ assert c.extract_descriptor_keys(src) == ["kafka"]+++def test_count_descriptor_calls_matches_literal_keys_when_all_literal():+ src = '''+ descriptor("ssm", "ssm", true, true, ...),+ descriptor("sqs", "sqs", true, true, ...),+ '''+ assert c.count_descriptor_calls(src) == len(c.extract_descriptor_keys(src)) == 2+++def test_count_descriptor_calls_excludes_the_definition():+ src = '''+ private static ServiceDescriptor descriptor(+ String externalKey,+ String configKey) {+ return new ServiceDescriptor(externalKey, configKey);+ }+ '''+ assert c.count_descriptor_calls(src) == 0+ assert c.extract_descriptor_keys(src) == []+++def test_count_descriptor_calls_catches_a_non_literal_key():+ # A future externalKey built from a variable/constant instead of a plain string+ # literal must not be silently invisible: the call-site count and the literal-key+ # count have to disagree so main() can fail loudly instead of under-counting.+ src = '''+ descriptor("ssm", "ssm", true, true, ...),+ descriptor(SOME_CONSTANT, "other", true, true, ...),+ '''+ assert c.count_descriptor_calls(src) == 2+ assert len(c.extract_descriptor_keys(src)) == 1+++def test_extract_matrix_slugs_scoped_to_table():+ md = """+# Services Overview++Some prose with an unrelated [link](not-a-service.md) that must not be picked up.++## Service Matrix++| Service | Endpoint | Protocol | Supported operations |+|---|---|---|---|+| [SSM](ssm.md) | ... | JSON 1.1 | 22 |+| [CloudWatch Metrics](cloudwatch.md#metrics) | ... | Query | 11 |++## Common Setup++Another [link](also-not-a-service.md) below the table.+"""+ assert c.extract_matrix_slugs(md) == {"ssm", "cloudwatch"}+++def test_extract_matrix_slugs_strips_anchor():+ md = "## Service Matrix\n\n| [API Gateway v2](api-gateway.md#v2) | | | 48 |\n\n## Common Setup\n"+ assert c.extract_matrix_slugs(md) == {"api-gateway"}+++def test_extract_matrix_slugs_raises_on_missing_heading():+ # A renamed/reordered heading must fail loudly rather than silently returning an+ # empty slug set, which would make every registered service look undocumented.+ md = "# Services Overview\n\nNo matrix heading here.\n"+ with pytest.raises(ValueError, match="Service Matrix"):+ c.extract_matrix_slugs(md)+++# --------------------------------------------------------------------------- #+# Classification+# --------------------------------------------------------------------------- #+def test_find_undocumented_exact_match_needs_no_alias():+ undocumented, expired = c.find_undocumented(+ keys=["ssm", "sqs"],+ slugs={"ssm", "sqs"},+ aliases={},+ deferred=[],+ today=date(2026, 1, 1),+ )+ assert undocumented == []+ assert expired == []+++def test_find_undocumented_alias_resolves():+ undocumented, expired = c.find_undocumented(+ keys=["kafka"],+ slugs={"msk"},+ aliases={"kafka": "msk"},+ deferred=[],+ today=date(2026, 1, 1),+ )+ assert undocumented == []+++def test_find_undocumented_flags_genuine_gap():+ undocumented, expired = c.find_undocumented(+ keys=["swf"],+ slugs={"ssm"},+ aliases={},+ deferred=[],+ today=date(2026, 1, 1),+ )+ assert undocumented == ["swf"]+ assert expired == []+++def test_find_undocumented_unexpired_deferred_is_silenced():+ d = c.DeferredEntry(key="bedrock-agentcore", reason="tracked in #2436", by=date(2026, 9, 15))+ undocumented, expired = c.find_undocumented(+ keys=["bedrock-agentcore"],+ slugs=set(),+ aliases={},+ deferred=[d],+ today=date(2026, 8, 22),+ )+ assert undocumented == []+ assert expired == []+++def test_find_undocumented_expired_deferred_reports_and_still_flags():+ # This is the case the mandatory `by:` date exists to catch: a deferred entry that+ # has run past its expiry is reported distinctly (so the message names the date+ # and reason) AND still counts as undocumented - it cannot silently keep passing.+ d = c.DeferredEntry(key="bedrock-agentcore", reason="tracked in #2436", by=date(2026, 9, 15))+ undocumented, expired = c.find_undocumented(+ keys=["bedrock-agentcore"],+ slugs=set(),+ aliases={},+ deferred=[d],+ today=date(2026, 10, 1),+ )+ assert undocumented == ["bedrock-agentcore"]+ assert expired == [d]+++def test_find_undocumented_deferred_entry_already_resolved_is_not_flagged():+ # If the row was added but the registry entry wasn't cleaned up, the key resolves+ # via the matrix itself regardless of expiry - no warning either way.+ d = c.DeferredEntry(key="bedrock-agentcore", reason="tracked in #2436", by=date(2020, 1, 1))+ undocumented, expired = c.find_undocumented(+ keys=["bedrock-agentcore"],+ slugs={"bedrock-agentcore"},+ aliases={},+ deferred=[d],+ today=date(2026, 8, 22),+ )+ assert undocumented == []+ assert expired == []