Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

13.4 KB
Raw Blame
"""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_action_counts():
    md = """
# Services Overview

## Service Matrix

| Service | Endpoint | Protocol | Supported operations |
|---|---|---|---|
| [SSM](ssm.md) | ... | JSON 1.1 | 22 |
| [CloudFormation](cloudformation.md) | ... | Query | 19 |
| [API Gateway v2](api-gateway.md#v2) | ... | REST JSON | 53 + data-plane |

## Common Setup
"""

    assert c.extract_matrix_action_counts(md) == {
        "ssm": 22,
        "cloudformation": 19,
    }


def test_extract_matrix_action_counts_ignores_links_outside_matrix():
    md = """
# Services Overview

A link to [SSM](ssm.md) outside the matrix must not be counted.

## Service Matrix

| Service | Endpoint | Protocol | Supported operations |
|---|---|---|---|
| [CloudFormation](cloudformation.md) | ... | Query | 19 |

## Common Setup

Another link to [SQS](sqs.md).
"""

    assert c.extract_matrix_action_counts(md) == {
        "cloudformation": 19,
    }


@pytest.mark.parametrize("slug,handler", [
    ("ec2", "ec2/Ec2QueryHandler.java"),
    ("ecs", "ecs/EcsJsonHandler.java"),
    ("elb", "elbv2/ElbV2QueryHandler.java"),
    ("glue", "glue/GlueJsonHandler.java"),
])
def test_non_tabular_action_counts_follow_dispatcher(slug, handler):
    root = c._repo_root()
    source = root / c.PACKAGE_DIR / "services" / handler
    expected = len(set(c.regen_action_docs.extract_switch_actions(
        source.read_text(encoding="utf-8")
    )))

    assert c.extract_action_counts(root)[slug] == expected


def test_non_tabular_action_count_tracks_new_dispatch_cases(tmp_path):
    matrix = tmp_path / "docs/services/index.md"
    matrix.parent.mkdir(parents=True)
    matrix.write_text(
        "## Service Matrix\n\n| [Glue](glue.md) | Query | JSON | 2 |\n\n## Common Setup\n",
        encoding="utf-8",
    )
    registry = tmp_path / "tools/docs/service_matrix.yaml"
    registry.parent.mkdir(parents=True)
    registry.write_text("action_count_sources:\n  glue: services/GlueJsonHandler.java\n", encoding="utf-8")
    handler = tmp_path / c.PACKAGE_DIR / "services/GlueJsonHandler.java"
    handler.parent.mkdir(parents=True)
    handler.write_text(
        'case "CreateTable" -> create();\ncase "GetTable" -> get();\n',
        encoding="utf-8",
    )

    assert c.extract_action_counts(tmp_path)["glue"] == 2

    handler.write_text(
        handler.read_text(encoding="utf-8") + 'case "DeleteTable" -> delete();\n',
        encoding="utf-8",
    )
    assert c.extract_action_counts(tmp_path)["glue"] == 3


def test_generated_action_table_requires_numeric_matrix_count(tmp_path):
    matrix = tmp_path / "docs/services/index.md"
    matrix.parent.mkdir(parents=True)
    matrix.write_text(
        "## Service Matrix\n\n| [EFS](efs.md) | REST | REST | TBD |\n"
        "| [Glue](glue.md) | Query | JSON | 2 |\n\n## Common Setup\n",
        encoding="utf-8",
    )
    (matrix.parent / "efs.md").write_text(
        "<!-- floci:actions:start -->\n| Action | Description |\n"
        "| --- | --- |\n| CreateFileSystem | Creates a file system |\n"
        "<!-- floci:actions:end -->\n",
        encoding="utf-8",
    )
    registry = tmp_path / "tools/docs/service_matrix.yaml"
    registry.parent.mkdir(parents=True)
    registry.write_text("action_count_sources:\n  glue: services/GlueJsonHandler.java\n", encoding="utf-8")
    handler = tmp_path / c.PACKAGE_DIR / "services/GlueJsonHandler.java"
    handler.parent.mkdir(parents=True)
    handler.write_text('case "CreateTable" -> create();\ncase "GetTable" -> get();\n', encoding="utf-8")

    with pytest.raises(ValueError, match="efs.*numeric matrix row"):
        c.extract_action_counts(tmp_path)


@pytest.mark.parametrize("source_entry", ["[]", "{}", "null"])
def test_non_tabular_action_sources_cannot_be_disabled(tmp_path, source_entry):
    matrix = tmp_path / "docs/services/index.md"
    matrix.parent.mkdir(parents=True)
    matrix.write_text(
        "## Service Matrix\n\n| [Glue](glue.md) | Query | JSON | 2 |\n\n## Common Setup\n",
        encoding="utf-8",
    )
    registry = tmp_path / "tools/docs/service_matrix.yaml"
    registry.parent.mkdir(parents=True)
    registry.write_text(f"action_count_sources: {source_entry}\n", encoding="utf-8")

    with pytest.raises(ValueError, match="non-empty mapping"):
        c.extract_action_counts(tmp_path)


def test_non_tabular_action_source_cannot_be_removed_silently(tmp_path):
    matrix = tmp_path / "docs/services/index.md"
    matrix.parent.mkdir(parents=True)
    matrix.write_text(
        "## Service Matrix\n\n| [Glue](glue.md) | Query | JSON | 2 |\n"
        "| [EC2](ec2.md) | Query | Query | 1 |\n\n## Common Setup\n",
        encoding="utf-8",
    )
    registry = tmp_path / "tools/docs/service_matrix.yaml"
    registry.parent.mkdir(parents=True)
    registry.write_text(
        "action_count_sources:\n  glue: services/GlueJsonHandler.java\n"
        "  ec2: services/Ec2QueryHandler.java\n", encoding="utf-8",
    )
    source_dir = tmp_path / c.PACKAGE_DIR / "services"
    source_dir.mkdir(parents=True)
    (source_dir / "GlueJsonHandler.java").write_text(
        'case "CreateTable" -> create();\ncase "GetTable" -> get();\n', encoding="utf-8",
    )
    (source_dir / "Ec2QueryHandler.java").write_text(
        'case "DescribeInstances" -> describe();\n', encoding="utf-8",
    )

    required = frozenset({"glue", "ec2"})
    assert c.extract_action_counts(tmp_path, required) == {"glue": 2, "ec2": 1}
    registry.write_text("action_count_sources:\n  glue: services/GlueJsonHandler.java\n", encoding="utf-8")
    with pytest.raises(ValueError, match="required action count source\\(s\\) missing: ec2"):
        c.extract_action_counts(tmp_path, required)


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 == []


# --------------------------------------------------------------------------- #
# Unlinked pages
# --------------------------------------------------------------------------- #
def test_find_unlinked_pages_flags_a_page_with_no_row(tmp_path):
    for name in ("index.md", "ssm.md", "elb.md", "elb-classic.md"):
        (tmp_path / name).write_text("# page\n")
    # index.md is the matrix page itself; elb.md is linked; elb-classic.md is not.
    assert c.find_unlinked_pages(tmp_path, slugs={"ssm", "elb"}, facet_pages=set()) == ["elb-classic"]


def test_find_unlinked_pages_honours_facet_exemption(tmp_path):
    for name in ("index.md", "lambda.md", "lambda-microvms.md"):
        (tmp_path / name).write_text("# page\n")
    assert c.find_unlinked_pages(tmp_path, slugs={"lambda"}, facet_pages={"lambda-microvms"}) == []


def test_find_unlinked_pages_ignores_non_markdown(tmp_path):
    (tmp_path / "ssm.md").write_text("# page\n")
    (tmp_path / "diagram.svg").write_text("<svg/>")
    assert c.find_unlinked_pages(tmp_path, slugs={"ssm"}, facet_pages=set()) == []


def test_action_count_source_paths_are_relative_to_the_package_root(tmp_path):
    matrix = tmp_path / "docs/services/index.md"
    matrix.parent.mkdir(parents=True)
    matrix.write_text(
        "## Service Matrix\n\n| [Glue](glue.md) | Query | JSON | 2 |\n\n## Common Setup\n",
        encoding="utf-8",
    )
    registry = tmp_path / "tools/docs/service_matrix.yaml"
    registry.parent.mkdir(parents=True)
    registry.write_text(
        f"action_count_sources:\n  glue: {c.PACKAGE_DIR}/services/GlueJsonHandler.java\n", encoding="utf-8",
    )

    with pytest.raises(ValueError, match="relative to"):
        c.extract_action_counts(tmp_path)