archledger 0.1.0__py3-none-any.whl

archledger/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+try:
+    from archledger._version import version as __version__
+except ImportError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

archledger/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

archledger/assembly.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from archledger import __version__
+from archledger.dialects import get_dialect
+from archledger.errors import RenderError
+from archledger.model import (
+    ArchitectureRecord,
+    default_document_filename_for_output_format,
+    document_template_name_for_source_format,
+    is_visible_status,
+    native_output_format_for_source_format,
+)
+from archledger.repository import ArchitectureRepository
+from archledger.section_rendering import (
+    adr_sections,
+    building_block_hierarchy,
+    concepts,
+    constraints_list,
+    context_interfaces,
+    deployment_view,
+    glossary_table,
+    quality_goals_table,
+    quality_requirements_overview,
+    quality_scenarios,
+    requirements_overview,
+    risk_table,
+    runtime_scenarios,
+    section_body,
+    section_diagrams,
+    solution_strategy_items,
+    stakeholders_table,
+)
+from archledger.storage.common import utc_now_iso, write_text
+
+
+@dataclass(frozen=True, slots=True)
+class AssemblyResult:
+    output_path: Path
+    rendered_text: str
+    source_format: str
+
+
+def assemble_document(
+    repo: ArchitectureRepository,
+    *,
+    output: Path | None = None,
+    source_format: str | None = None,
+    include_draft: bool = False,
+    include_superseded: bool = False,
+    strict: bool = False,
+    write: bool = True,
+) -> AssemblyResult:
+    check_result = repo.check(strict=strict)
+    if check_result.has_failures(strict=strict):
+        raise RenderError(
+            f"Build blocked by {len(check_result.errors)} error(s) and "
+            f"{len(check_result.warnings)} warning(s)."
+        )
+
+    resolved_source_format = (
+        repo.config.source_format if source_format is None else source_format
+    )
+    dialect = get_dialect(resolved_source_format)
+    all_records = repo.load_all_records(include_sections=True)
+    sections = {
+        record.section: record for record in all_records if record.type == "section"
+    }
+    records = _visible_records(
+        all_records,
+        include_draft=include_draft,
+        include_superseded=include_superseded,
+    )
+    env = Environment(
+        loader=PackageLoader("archledger", "templates"),
+        autoescape=select_autoescape(
+            enabled_extensions=(),
+            default_for_string=False,
+        ),
+        keep_trailing_newline=True,
+    )
+    template = env.get_template(
+        document_template_name_for_source_format(resolved_source_format)
+    )
+    rendered = template.render(
+        title=repo.config.arc42_title,
+        date=_document_date(records),
+        generator=f"archledger {__version__}",
+        arc42_template_version=repo.config.arc42_template_version,
+        section_body=lambda section_key: section_body(sections, section_key, dialect),
+        requirements_overview=lambda: requirements_overview(records, dialect),
+        quality_goals_table=lambda: quality_goals_table(records, dialect),
+        stakeholders_table=lambda: stakeholders_table(records, dialect),
+        constraints_list=lambda: constraints_list(records, dialect),
+        context_interfaces=lambda context_kind: context_interfaces(
+            records,
+            context_kind,
+            dialect,
+        ),
+        solution_strategy_items=lambda: solution_strategy_items(records, dialect),
+        section_diagrams=lambda section_key: section_diagrams(
+            records,
+            section_key,
+            dialect,
+        ),
+        building_block_hierarchy=lambda: building_block_hierarchy(records, dialect),
+        runtime_scenarios=lambda: runtime_scenarios(records, dialect),
+        deployment_view=lambda: deployment_view(records, dialect),
+        concepts=lambda: concepts(records, dialect),
+        adr_sections=lambda: adr_sections(records, dialect),
+        quality_requirements_overview=lambda: quality_requirements_overview(
+            records,
+            dialect,
+        ),
+        quality_scenarios=lambda: quality_scenarios(records, dialect),
+        risk_table=lambda: risk_table(records, dialect),
+        glossary_table=lambda: glossary_table(records, dialect),
+    )
+    output_path = _resolve_output_path(repo, resolved_source_format, output)
+    if write:
+        write_text(output_path, rendered)
+    return AssemblyResult(
+        output_path=output_path,
+        rendered_text=rendered,
+        source_format=resolved_source_format,
+    )
+
+
+def _document_date(records: list[ArchitectureRecord]) -> str:
+    source_date_epoch = os.getenv("SOURCE_DATE_EPOCH")
+    if source_date_epoch:
+        try:
+            timestamp = int(source_date_epoch)
+        except ValueError as exc:
+            raise RenderError(
+                "SOURCE_DATE_EPOCH must be an integer Unix timestamp."
+            ) from exc
+        return datetime.fromtimestamp(timestamp, tz=timezone.utc).date().isoformat()
+
+    latest_date: date | None = None
+    for record in records:
+        for key in ("updated_at", "date"):
+            metadata_value = record.metadata.get(key)
+            parsed = _parse_record_datetime(metadata_value)
+            if parsed is None:
+                continue
+            candidate = parsed.date()
+            if latest_date is None or candidate > latest_date:
+                latest_date = candidate
+
+    if latest_date is not None:
+        return latest_date.isoformat()
+    return utc_now_iso()[:10]
+
+
+def _parse_record_datetime(value: object) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    candidate = value.strip()
+    if not candidate:
+        return None
+    if len(candidate) == 10:
+        try:
+            return datetime.strptime(candidate, "%Y-%m-%d")
+        except ValueError:
+            return None
+
+    normalized = candidate
+    if normalized.endswith("Z"):
+        normalized = f"{normalized[:-1]}+00:00"
+    try:
+        return datetime.fromisoformat(normalized)
+    except ValueError:
+        return None
+
+
+def assemble_asciidoc_document(
+    repo: ArchitectureRepository,
+    *,
+    output: Path | None = None,
+    include_draft: bool = False,
+    include_superseded: bool = False,
+    strict: bool = False,
+    write: bool = True,
+) -> AssemblyResult:
+    return assemble_document(
+        repo,
+        output=output,
+        source_format="asciidoc",
+        include_draft=include_draft,
+        include_superseded=include_superseded,
+        strict=strict,
+        write=write,
+    )
+
+
+def _visible_records(
+    all_records: list[ArchitectureRecord],
+    *,
+    include_draft: bool,
+    include_superseded: bool,
+) -> list[ArchitectureRecord]:
+    return [
+        record
+        for record in all_records
+        if record.type != "section"
+        and is_visible_status(
+            record.status,
+            include_draft=include_draft,
+            include_superseded=include_superseded,
+        )
+    ]
+
+
+def _resolve_output_path(
+    repo: ArchitectureRepository,
+    source_format: str,
+    output: Path | None,
+) -> Path:
+    if output is None:
+        native_output_format = native_output_format_for_source_format(source_format)
+        default_output = (
+            repo.config.build_default_output
+            if repo.config.build_default_format == native_output_format
+            else default_document_filename_for_output_format(native_output_format)
+        )
+        return repo.paths.build_dir / default_output
+    if output.is_absolute():
+        return output
+    return repo.paths.workspace_root / output

archledger/checks.py

@@ -0,0 +1,404 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+
+from archledger.model import PLACEHOLDER_SNIPPETS, ArchitectureRecord
+
+ALLOWED_CONSTRAINT_CATEGORIES = frozenset(
+    {"technical", "organizational", "regulatory", "convention"}
+)
+ALLOWED_RISK_LEVELS = frozenset({"low", "medium", "high"})
+_ALLOWED_DIAGRAM_TYPES = frozenset({"text", "ascii", "unicode", "svgbob", "mermaid"})
+_TEXT_DIAGRAM_TYPES = frozenset({"text", "ascii", "unicode"})
+_MAX_TEXT_DIAGRAM_LINE_LENGTH = 120
+
+_MARKDOWN_BLOCK_PATTERNS: dict[str, re.Pattern[str]] = {
+    "mermaid": re.compile(r"```mermaid\s*\n(.*?)\n```", re.IGNORECASE | re.DOTALL),
+    "svgbob": re.compile(r"```svgbob\s*\n(.*?)\n```", re.IGNORECASE | re.DOTALL),
+    "text": re.compile(
+        r"```(?:textdiagram|diagram|text)\s*\n(.*?)\n```", re.IGNORECASE | re.DOTALL
+    ),
+    "ascii": re.compile(
+        r"```(?:textdiagram|diagram|ascii|text)\s*\n(.*?)\n```",
+        re.IGNORECASE | re.DOTALL,
+    ),
+    "unicode": re.compile(
+        r"```(?:textdiagram|diagram|text)\s*\n(.*?)\n```", re.IGNORECASE | re.DOTALL
+    ),
+}
+_ASCIIDOC_BLOCK_PATTERNS: dict[str, re.Pattern[str]] = {
+    "mermaid": re.compile(
+        r"\[mermaid\]\s*\n\.\.\.\.\s*\n(.*?)\n\.\.\.\.",
+        re.IGNORECASE | re.DOTALL,
+    ),
+    "svgbob": re.compile(
+        r"\[svgbob\]\s*\n\.\.\.\.\s*\n(.*?)\n\.\.\.\.",
+        re.IGNORECASE | re.DOTALL,
+    ),
+    "text": re.compile(
+        r"(?:\[source,\s*text\]|\[listing\])\s*\n----\s*\n(.*?)\n----"
+        r"|^\.\.\.\.\s*\n(.*?)\n\.\.\.\.",
+        re.IGNORECASE | re.DOTALL | re.MULTILINE,
+    ),
+    "ascii": re.compile(
+        r"(?:\[source,\s*(?:text|ascii)\]|\[listing\])\s*\n----\s*\n(.*?)\n----"
+        r"|^\.\.\.\.\s*\n(.*?)\n\.\.\.\.",
+        re.IGNORECASE | re.DOTALL | re.MULTILINE,
+    ),
+    "unicode": re.compile(
+        r"(?:\[source,\s*text\]|\[listing\])\s*\n----\s*\n(.*?)\n----"
+        r"|^\.\.\.\.\s*\n(.*?)\n\.\.\.\.",
+        re.IGNORECASE | re.DOTALL | re.MULTILINE,
+    ),
+}
+
+
+def content_warnings(record: ArchitectureRecord) -> list[str]:
+    warnings: list[str] = []
+    if record.type != "section":
+        stripped_body = record.body.strip()
+        if stripped_body and any(
+            snippet in stripped_body for snippet in PLACEHOLDER_SNIPPETS
+        ):
+            warnings.append(f"Record body is placeholder text for {record.id}.")
+
+    checker = _CONTENT_WARNING_CHECKERS.get(record.type)
+    if checker is not None:
+        warnings.extend(checker(record))
+    warnings.extend(_body_syntax_warnings(record))
+    return warnings
+
+
+def _has_non_empty_sequence(value: object) -> bool:
+    return isinstance(value, list) and any(str(item).strip() for item in value)
+
+
+def _has_non_empty_text(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _contains_adr_sections(body: str) -> bool:
+    body_lower = body.lower()
+    return all(
+        any(heading in body_lower for heading in headings)
+        for headings in (
+            ("## context", "=== context"),
+            ("## decision", "=== decision"),
+            ("## consequences", "=== consequences"),
+        )
+    )
+
+
+def _looks_measurable(value: str) -> bool:
+    lowered = value.lower()
+    if any(char.isdigit() for char in lowered):
+        return True
+    indicators = (
+        "%",
+        "percent",
+        "ms",
+        "millisecond",
+        "second",
+        "minute",
+        "hour",
+        "count",
+        "byte",
+        "identical",
+        "latency",
+        "throughput",
+        "less than",
+        "greater than",
+        "at least",
+        "at most",
+        "zero",
+        "one",
+        "two",
+    )
+    return any(indicator in lowered for indicator in indicators)
+
+
+def _quality_goal_warnings(record: ArchitectureRecord) -> list[str]:
+    if _has_non_empty_text(record.metadata.get("scenario")):
+        return []
+    return [f"Quality goal {record.id} has no scenario."]
+
+
+def _stakeholder_warnings(record: ArchitectureRecord) -> list[str]:
+    if _has_non_empty_sequence(record.metadata.get("expectations")):
+        return []
+    return [f"Stakeholder {record.id} has no expectations."]
+
+
+def _constraint_warnings(record: ArchitectureRecord) -> list[str]:
+    warnings: list[str] = []
+    if not _has_non_empty_text(record.metadata.get("impact")):
+        warnings.append(f"Constraint {record.id} has no impact.")
+    category = record.metadata.get("category")
+    if category not in ALLOWED_CONSTRAINT_CATEGORIES:
+        warnings.append(f"Constraint {record.id} has unsupported category: {category}")
+    return warnings
+
+
+def _context_interface_warnings(record: ArchitectureRecord) -> list[str]:
+    warnings: list[str] = []
+    if not _has_non_empty_text(record.metadata.get("partner")):
+        warnings.append(f"Context interface {record.id} has no partner.")
+    if not any(
+        _has_non_empty_sequence(record.metadata.get(field))
+        for field in ("inputs", "outputs", "channels")
+    ):
+        warnings.append(
+            f"Context interface {record.id} has no inputs, outputs, or channels."
+        )
+    return warnings
+
+
+def _white_box_warnings(record: ArchitectureRecord) -> list[str]:
+    warnings: list[str] = []
+    level = record.metadata.get("level")
+    if isinstance(level, bool) or not isinstance(level, int) or level < 1:
+        warnings.append(f"White box {record.id} must have a positive integer level.")
+    parent = record.metadata.get("parent")
+    if isinstance(level, int) and level > 1 and parent in (None, "", "null"):
+        warnings.append(f"White box {record.id} at level > 1 requires a parent.")
+    return warnings
+
+
+def _black_box_warnings(record: ArchitectureRecord) -> list[str]:
+    if record.metadata.get("parent") not in (None, "", "null"):
+        return []
+    return [
+        (
+            f"Black box {record.id} should declare a parent unless it is "
+            "intentionally top-level external."
+        )
+    ]
+
+
+def _runtime_scenario_warnings(record: ArchitectureRecord) -> list[str]:
+    warnings: list[str] = []
+    if not _has_non_empty_sequence(record.metadata.get("participants")):
+        warnings.append(f"Runtime scenario {record.id} has no participants.")
+    if not _has_non_empty_text(record.metadata.get("trigger")):
+        warnings.append(f"Runtime scenario {record.id} has no trigger.")
+    return warnings
+
+
+def _infrastructure_warnings(record: ArchitectureRecord) -> list[str]:
+    warnings: list[str] = []
+    environment = record.metadata.get("environment")
+    if not _has_non_empty_text(environment):
+        warnings.append(f"Infrastructure {record.id} has no environment.")
+    if (
+        isinstance(environment, str)
+        and environment.strip().lower() == "production"
+        and not _has_non_empty_sequence(record.metadata.get("maps_building_blocks"))
+    ):
+        warnings.append(
+            f"Infrastructure {record.id} in production must map building "
+            "blocks explicitly."
+        )
+    return warnings
+
+
+def _adr_warnings(record: ArchitectureRecord) -> list[str]:
+    warnings: list[str] = []
+    if not _contains_adr_sections(record.body):
+        warnings.append(
+            "ADR "
+            f"{record.id} should contain Context, Decision, and Consequences "
+            "sections."
+        )
+    if not _has_non_empty_sequence(record.metadata.get("deciders")):
+        warnings.append(f"ADR {record.id} has no deciders.")
+    return warnings
+
+
+def _quality_scenario_warnings(record: ArchitectureRecord) -> list[str]:
+    response_measure = record.metadata.get("response_measure")
+    if not _has_non_empty_text(response_measure):
+        return [f"Quality scenario {record.id} has no response_measure."]
+    if isinstance(response_measure, str) and not _looks_measurable(response_measure):
+        return [f"Quality scenario {record.id} response_measure should be measurable."]
+    return []
+
+
+def _risk_warnings(record: ArchitectureRecord) -> list[str]:
+    warnings: list[str] = []
+    severity = record.metadata.get("severity")
+    probability = record.metadata.get("probability")
+    if severity not in ALLOWED_RISK_LEVELS:
+        warnings.append(f"Risk {record.id} has unsupported severity: {severity}")
+    if probability not in ALLOWED_RISK_LEVELS:
+        warnings.append(f"Risk {record.id} has unsupported probability: {probability}")
+    if not _has_non_empty_text(record.metadata.get("mitigation")):
+        warnings.append(f"Risk {record.id} has no mitigation.")
+    return warnings
+
+
+def _glossary_term_warnings(record: ArchitectureRecord) -> list[str]:
+    if _has_non_empty_text(record.metadata.get("definition")):
+        return []
+    return [f"Glossary term {record.id} has no definition."]
+
+
+def _diagram_warnings(record: ArchitectureRecord) -> list[str]:
+    warnings: list[str] = []
+    diagram_type_raw = record.metadata.get("diagram_type")
+    diagram_type = (
+        diagram_type_raw.strip().lower() if isinstance(diagram_type_raw, str) else ""
+    )
+    if diagram_type not in _ALLOWED_DIAGRAM_TYPES:
+        warnings.append(
+            f"Diagram {record.id} has unsupported diagram_type: {diagram_type_raw!r}. "
+            f"Allowed types: {', '.join(sorted(_ALLOWED_DIAGRAM_TYPES))}."
+        )
+    caption = record.metadata.get("caption")
+    if not isinstance(caption, str) or not caption.strip():
+        warnings.append(f"Diagram {record.id} has no caption.")
+
+    body_format_value = record.metadata.get("body_format")
+    body_format = (
+        body_format_value.strip().lower() if isinstance(body_format_value, str) else ""
+    )
+    if body_format == "markdown":
+        warnings.extend(_markdown_diagram_warnings(record, diagram_type))
+    elif body_format == "asciidoc":
+        warnings.extend(_asciidoc_diagram_warnings(record, diagram_type))
+    return warnings
+
+
+def _markdown_diagram_warnings(
+    record: ArchitectureRecord, diagram_type: str
+) -> list[str]:
+    warnings: list[str] = []
+    pattern = _MARKDOWN_BLOCK_PATTERNS.get(diagram_type)
+    if pattern is None:
+        return warnings
+    match = pattern.search(record.body)
+    if not match:
+        warnings.append(
+            f"Diagram {record.id} markdown body is missing a fenced "
+            f"{diagram_type} block."
+        )
+    else:
+        block_content = match.group(1) or ""
+        if not block_content.strip():
+            warnings.append(f"Diagram {record.id} {diagram_type} block is empty.")
+        elif diagram_type in _TEXT_DIAGRAM_TYPES:
+            for line in block_content.splitlines():
+                if len(line) > _MAX_TEXT_DIAGRAM_LINE_LENGTH:
+                    warnings.append(
+                        f"Diagram {record.id} has a text diagram line exceeding "
+                        f"{_MAX_TEXT_DIAGRAM_LINE_LENGTH} characters."
+                    )
+                    break
+    return warnings
+
+
+def _asciidoc_diagram_warnings(
+    record: ArchitectureRecord, diagram_type: str
+) -> list[str]:
+    warnings: list[str] = []
+    pattern = _ASCIIDOC_BLOCK_PATTERNS.get(diagram_type)
+    if pattern is None:
+        return warnings
+    if diagram_type == "mermaid":
+        if not _has_asciidoc_mermaid_block(record.body):
+            warnings.append(
+                f"Diagram {record.id} asciidoc body is missing a [mermaid] block."
+            )
+        elif _asciidoc_mermaid_block_is_empty(record.body):
+            warnings.append(f"Diagram {record.id} asciidoc mermaid block is empty.")
+    elif diagram_type == "svgbob":
+        match = pattern.search(record.body)
+        if not match:
+            warnings.append(
+                f"Diagram {record.id} asciidoc body is missing a [svgbob] block."
+            )
+        else:
+            block_content = match.group(1) or ""
+            if not block_content.strip():
+                warnings.append(f"Diagram {record.id} svgbob block is empty.")
+    else:
+        match = pattern.search(record.body)
+        if not match:
+            warnings.append(
+                f"Diagram {record.id} asciidoc body is missing a "
+                f"{diagram_type} text block."
+            )
+        else:
+            groups = [g for g in match.groups() if g is not None]
+            block_content = groups[0] if groups else ""
+            if not block_content.strip():
+                warnings.append(f"Diagram {record.id} {diagram_type} block is empty.")
+            elif diagram_type in _TEXT_DIAGRAM_TYPES:
+                for line in block_content.splitlines():
+                    if len(line) > _MAX_TEXT_DIAGRAM_LINE_LENGTH:
+                        warnings.append(
+                            f"Diagram {record.id} has a text diagram line "
+                            f"exceeding {_MAX_TEXT_DIAGRAM_LINE_LENGTH} characters."
+                        )
+                        break
+    return warnings
+
+
+def _has_asciidoc_mermaid_block(body: str) -> bool:
+    return bool(
+        re.search(
+            r"\[mermaid\]\s*\n\.\.\.\.\s*\n.*?\n\.\.\.\.",
+            body,
+            flags=re.IGNORECASE | re.DOTALL,
+        )
+    )
+
+
+def _asciidoc_mermaid_block_is_empty(body: str) -> bool:
+    match = re.search(
+        r"\[mermaid\]\s*\n\.\.\.\.\s*\n(.*?)\n\.\.\.\.",
+        body,
+        flags=re.IGNORECASE | re.DOTALL,
+    )
+    if match is None:
+        return False
+    return not match.group(1).strip()
+
+
+def _body_syntax_warnings(record: ArchitectureRecord) -> list[str]:
+    body_format_value = record.metadata.get("body_format")
+    if not isinstance(body_format_value, str):
+        return []
+    body_format = body_format_value.strip().lower()
+    if body_format == "markdown":
+        if "[discrete]" in record.body and "\n===" in record.body:
+            return [
+                "Markdown "
+                f"record {record.id} contains AsciiDoc-style discrete headings."
+            ]
+        return []
+    if body_format == "asciidoc":
+        if any(
+            line.startswith("## ")
+            for line in record.body.splitlines()
+            if not line.startswith("```")
+        ):
+            return [f"AsciiDoc record {record.id} contains Markdown headings."]
+    return []
+
+
+_CONTENT_WARNING_CHECKERS: dict[str, Callable[[ArchitectureRecord], list[str]]] = {
+    "quality_goal": _quality_goal_warnings,
+    "stakeholder": _stakeholder_warnings,
+    "constraint": _constraint_warnings,
+    "context_interface": _context_interface_warnings,
+    "white_box": _white_box_warnings,
+    "black_box": _black_box_warnings,
+    "runtime_scenario": _runtime_scenario_warnings,
+    "infrastructure": _infrastructure_warnings,
+    "adr": _adr_warnings,
+    "quality_scenario": _quality_scenario_warnings,
+    "risk": _risk_warnings,
+    "diagram": _diagram_warnings,
+    "glossary_term": _glossary_term_warnings,
+}