Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

11.3 KB
Raw Blame
"""Tests for ``repowise export --format structurizr``.

The model building is covered elsewhere; what matters here is the surface a
user actually touches — where the file lands, and whether the message tells
them what to do next when the default output is a fragment that looks
incomplete on its own.
"""

from __future__ import annotations

from pathlib import Path

import pytest

from repowise.cli.commands.export_structurizr import (
    FRAGMENT_FILENAME,
    STANDALONE_FILENAME,
    _counts,
    _resolve_output,
    export_structurizr,
)
from repowise.server.services.c4_builder.models import (
    C4Model,
    Component,
    Container,
    ExternalSystemView,
    Relation,
    System,
)


def _model(*, containers: bool = True) -> C4Model:
    core = Container(
        id="pkg:packages/core",
        name="core",
        path="packages/core",
        language="python",
        file_count=10,
        symbol_count=20,
    )
    return C4Model(
        system=System(id="sys:abc", name="demo"),
        people=[],
        containers=[core] if containers else [],
        components_by_container={
            core.id: [
                Component(
                    id="cmp:packages/core/ingestion",
                    name="ingestion",
                    path="packages/core/ingestion",
                    container_id=core.id,
                    file_count=4,
                    symbol_count=9,
                )
            ]
        }
        if containers
        else {},
        external_systems=[
            ExternalSystemView(
                id="ext:fastapi",
                name="fastapi",
                display_name="FastAPI",
                category="framework",
                ecosystem="pypi",
            )
        ]
        if containers
        else [],
        container_relations=[Relation(source_id=core.id, target_id="ext:fastapi", label="imports")]
        if containers
        else [],
        component_relations=[],
    )


@pytest.fixture
def patched(monkeypatch):
    """Swap the database build for a fixed model."""
    model = _model()

    async def fake_build(repo_path, *, include_components):
        return model

    monkeypatch.setattr("repowise.cli.commands.export_structurizr._build", fake_build)
    return model


# ---------------------------------------------------------------------------
# Output path
# ---------------------------------------------------------------------------


def test_output_defaults_to_the_repo_root(tmp_path: Path) -> None:
    assert _resolve_output(None, tmp_path, standalone=False) == tmp_path / FRAGMENT_FILENAME
    assert _resolve_output(None, tmp_path, standalone=True) == tmp_path / STANDALONE_FILENAME


def test_a_dsl_path_names_the_file_and_anything_else_is_a_directory(
    tmp_path: Path,
) -> None:
    named = _resolve_output(str(tmp_path / "arch.dsl"), tmp_path, standalone=False)
    assert named == tmp_path / "arch.dsl"

    directory = _resolve_output(str(tmp_path / "out"), tmp_path, standalone=False)
    assert directory == tmp_path / "out" / FRAGMENT_FILENAME


# ---------------------------------------------------------------------------
# Writing
# ---------------------------------------------------------------------------


def test_writes_a_fragment_by_default(tmp_path: Path, patched, capsys) -> None:
    code = export_structurizr(
        tmp_path,
        output=None,
        standalone=False,
        include_components=False,
        include_externals=True,
    )
    assert code == 0
    written = (tmp_path / FRAGMENT_FILENAME).read_text(encoding="utf-8")
    assert written.lstrip().startswith("#")
    assert "\nmodel {\n" in written
    assert "component " not in written


def test_standalone_writes_a_whole_workspace(tmp_path: Path, patched) -> None:
    code = export_structurizr(
        tmp_path,
        output=None,
        standalone=True,
        include_components=True,
        include_externals=True,
    )
    assert code == 0
    written = (tmp_path / STANDALONE_FILENAME).read_text(encoding="utf-8")
    assert "workspace " in written
    assert "views {" in written


def test_a_hand_written_workspace_is_never_overwritten(tmp_path: Path, patched, capsys) -> None:
    """--standalone targets workspace.dsl, which is what a Structurizr user's
    own hand-written workspace is already called. Clobbering it would destroy
    views, styles and docs that live nowhere else."""
    mine = tmp_path / STANDALONE_FILENAME
    mine.write_text('workspace "mine" {\n  # my views\n}\n', encoding="utf-8")

    code = export_structurizr(
        tmp_path,
        output=None,
        standalone=True,
        include_components=False,
        include_externals=True,
    )
    assert code == 1
    assert mine.read_text(encoding="utf-8").startswith('workspace "mine"')
    out = capsys.readouterr().out
    # Both ways out are named: include the fragment, or overwrite deliberately.
    assert "--force" in out
    assert FRAGMENT_FILENAME in out


def test_force_overwrites_a_file_that_is_not_ours(tmp_path: Path, patched) -> None:
    mine = tmp_path / STANDALONE_FILENAME
    mine.write_text('workspace "mine" {}\n', encoding="utf-8")

    code = export_structurizr(
        tmp_path,
        output=None,
        standalone=True,
        include_components=False,
        include_externals=True,
        force=True,
    )
    assert code == 0
    assert "generated by Repowise" in mine.read_text(encoding="utf-8")


def test_our_own_output_is_replaced_without_asking(tmp_path: Path, patched) -> None:
    """Re-exporting is the normal workflow; a prompt every time would be noise."""
    for _ in range(2):
        code = export_structurizr(
            tmp_path,
            output=None,
            standalone=False,
            include_components=False,
            include_externals=True,
        )
        assert code == 0
    assert (tmp_path / FRAGMENT_FILENAME).exists()


def test_a_binary_file_at_the_destination_is_treated_as_not_ours(tmp_path: Path, patched) -> None:
    """An undecodable file must fail closed — it is certainly not our text."""
    target = tmp_path / "arch.dsl"
    target.write_bytes(b"\xff\xfe\x00binary")

    code = export_structurizr(
        tmp_path,
        output=str(target),
        standalone=False,
        include_components=False,
        include_externals=True,
    )
    assert code == 1
    assert target.read_bytes() == b"\xff\xfe\x00binary"


def test_a_missing_parent_directory_is_created(tmp_path: Path, patched) -> None:
    target = tmp_path / "nested" / "deeper" / "arch.dsl"
    code = export_structurizr(
        tmp_path,
        output=str(target),
        standalone=False,
        include_components=False,
        include_externals=True,
    )
    assert code == 0
    assert target.is_file()


# ---------------------------------------------------------------------------
# What the user is told
# ---------------------------------------------------------------------------


def test_the_message_says_what_to_do_next(tmp_path: Path, patched, capsys) -> None:
    """A filename alone leaves the user staring at a file with no views."""
    export_structurizr(
        tmp_path,
        output=None,
        standalone=False,
        include_components=False,
        include_externals=True,
    )
    out = capsys.readouterr().out
    assert f"!include {FRAGMENT_FILENAME}" in out
    assert "workspace" in out
    # The system identifier is filled in, not left as a placeholder to edit.
    assert "systemContext sys_demo" in out
    assert "<system id>" not in out
    assert "structurizr/structurizr" in out


def test_the_standalone_hint_only_appears_when_there_is_no_workspace(
    tmp_path: Path, patched, capsys
) -> None:
    export_structurizr(
        tmp_path,
        output=None,
        standalone=False,
        include_components=False,
        include_externals=True,
    )
    assert "--standalone" in capsys.readouterr().out

    (tmp_path / STANDALONE_FILENAME).write_text("workspace {}", encoding="utf-8")
    export_structurizr(
        tmp_path,
        output=None,
        standalone=False,
        include_components=False,
        include_externals=True,
    )
    assert "--standalone" not in capsys.readouterr().out


def test_the_standalone_message_leads_with_the_zero_install_route(
    tmp_path: Path, patched, capsys
) -> None:
    """A docker command is not an answer for someone without docker."""
    export_structurizr(
        tmp_path,
        output=None,
        standalone=True,
        include_components=False,
        include_externals=True,
    )
    out = capsys.readouterr().out
    assert "structurizr.com" in out
    assert out.index("structurizr.com") < out.index("docker run")


def test_counts_are_reported_so_an_empty_index_is_obvious() -> None:
    summary = _counts(_model(), include_components=True, include_externals=True)
    assert "1 containers" in summary
    assert "1 components" in summary
    assert "1 external systems" in summary


# ---------------------------------------------------------------------------
# Failure modes
# ---------------------------------------------------------------------------


def test_an_unindexed_repo_names_the_command_that_fixes_it(
    tmp_path: Path, monkeypatch, capsys
) -> None:
    async def no_model(repo_path, *, include_components):
        return None

    monkeypatch.setattr("repowise.cli.commands.export_structurizr._build", no_model)
    code = export_structurizr(
        tmp_path,
        output=None,
        standalone=False,
        include_components=False,
        include_externals=True,
    )
    assert code == 1
    assert "repowise init" in capsys.readouterr().out
    assert not (tmp_path / FRAGMENT_FILENAME).exists()


def test_an_empty_model_fails_instead_of_writing_a_useless_file(
    tmp_path: Path, monkeypatch, capsys
) -> None:
    """A valid file with nothing in it reads as "this repo has no structure"."""
    empty = _model(containers=False)

    async def build_empty(repo_path, *, include_components):
        return empty

    monkeypatch.setattr("repowise.cli.commands.export_structurizr._build", build_empty)
    code = export_structurizr(
        tmp_path,
        output=None,
        standalone=False,
        include_components=False,
        include_externals=True,
    )
    assert code == 1
    assert "No containers" in capsys.readouterr().out
    assert not (tmp_path / FRAGMENT_FILENAME).exists()


def test_an_uppercase_dsl_suffix_is_still_a_file(tmp_path) -> None:
    """``--out MODEL.DSL`` used to create a directory of that name."""
    from repowise.cli.commands.export_structurizr import _resolve_output

    resolved = _resolve_output(str(tmp_path / "MODEL.DSL"), tmp_path, standalone=False)
    assert resolved.name == "MODEL.DSL"
    assert resolved.parent == tmp_path.resolve()


async def test_a_database_with_no_tables_reads_as_not_indexed(tmp_path) -> None:
    """The path a fresh clone with a stray .repowise/ dir takes.

    Every other CLI test stubs ``_build`` wholesale, so this branch — the one
    that turns a raw "no such table: repositories" traceback into the message
    naming the command that fixes it — had never run.
    """
    from repowise.cli.commands.export_structurizr import _build

    repo = tmp_path / "repo"
    (repo / ".repowise").mkdir(parents=True)
    # An empty file where the index belongs: opens as SQLite, has no tables.
    (repo / ".repowise" / "wiki.db").touch()

    assert await _build(repo, include_components=False) is None