tool: Add spec summary command with markdown output

Author: colmjude

spec.py

@@ -27,6 +27,31 @@
 from bin.loader import load_content, load_needs
 
 
+def get_spec_summary_counts():
+    spec = load_content()
+    keys = [
+        ("applications", "application"),
+        ("modules", "module"),
+        ("fields", "field"),
+        ("components", "component"),
+        ("codelists", "codelist"),
+        ("datasets", "dataset"),
+        ("specifications", "specification"),
+    ]
+    return [(label, len(spec.get(table_name, {}) or {})) for label, table_name in keys]
+
+
+def format_spec_summary(markdown=False):
+    counts = get_spec_summary_counts()
+
+    if markdown:
+        lines = ["# Specification summary", ""]
+        lines.extend(f"- **{label.capitalize()}**: {count}" for label, count in counts)
+        return "\n".join(lines)
+
+    return "\n".join(f"{label}: {count}" for label, count in counts)
+
+
 def print_2025_form_urls(application_type):
     forms_path = PROJECT_ROOT / FORMS_2025_FILEPATH
     rows = read_csv(str(forms_path), as_dict=True)
@@ -253,6 +278,13 @@ def decision():
     pass
 
 
+@cli.command(name="summary")
+@click.option("--markdown", is_flag=True, help="Print the summary in markdown format")
+def spec_summary(markdown):
+    """Print a summary of loaded specification record counts."""
+    click.echo(format_spec_summary(markdown=markdown))
+
+
 @decision.command()
 @click.option("--list", "do_list", is_flag=True, help="List covered need ids")
 def summary(do_list):

tests/test_spec_cli.py

@@ -3,6 +3,69 @@
 import spec
 
 
+def test_summary_command_prints_loaded_record_counts(monkeypatch):
+    runner = CliRunner()
+
+    monkeypatch.setattr(
+        spec,
+        "load_content",
+        lambda: {
+            "application": {"a": {}, "b": {}},
+            "module": {"m1": {}, "m2": {}, "m3": {}},
+            "field": {"f1": {}},
+            "component": {"c1": {}, "c2": {}},
+            "codelist": {"cl1": {}},
+            "dataset": {"d1": {}, "d2": {}, "d3": {}, "d4": {}},
+            "specification": {"s1": {}},
+        },
+    )
+
+    result = runner.invoke(spec.cli, ["summary"])
+
+    assert result.exit_code == 0
+    assert result.output == (
+        "applications: 2\n"
+        "modules: 3\n"
+        "fields: 1\n"
+        "components: 2\n"
+        "codelists: 1\n"
+        "datasets: 4\n"
+        "specifications: 1\n"
+    )
+
+
+def test_summary_command_supports_markdown_output(monkeypatch):
+    runner = CliRunner()
+
+    monkeypatch.setattr(
+        spec,
+        "load_content",
+        lambda: {
+            "application": {"a": {}},
+            "module": {"m1": {}},
+            "field": {"f1": {}, "f2": {}},
+            "component": {},
+            "codelist": {"cl1": {}, "cl2": {}},
+            "dataset": {"d1": {}},
+            "specification": {"s1": {}, "s2": {}},
+        },
+    )
+
+    result = runner.invoke(spec.cli, ["summary", "--markdown"])
+
+    assert result.exit_code == 0
+    assert result.output == (
+        "# Specification summary\n\n"
+        "- **Applications**: 1\n"
+        "- **Modules**: 1\n"
+        "- **Fields**: 2\n"
+        "- **Components**: 0\n"
+        "- **Codelists**: 2\n"
+        "- **Datasets**: 1\n"
+        "- **Specifications**: 2\n"
+    )
+
+
 def test_forms_command_lists_matching_2025_forms(monkeypatch):
     runner = CliRunner()