docsmoke 1.0.0__py3-none-any.whl

NOTICE

@@ -0,0 +1,10 @@
+docsmoke
+Copyright 2026 Uğur Kontel
+
+This product includes software developed by Uğur Kontel.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0

docsmoke/__init__.py

@@ -0,0 +1,12 @@
+"""docsmoke public package metadata."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__"]
+
+try:
+    __version__ = version("docsmoke")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"

docsmoke/__main__.py

@@ -0,0 +1,3 @@
+from docsmoke.cli import app
+
+app()

docsmoke/cli.py

@@ -0,0 +1,184 @@
+"""Command-line interface for docsmoke."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path  # noqa: TC003 - Typer resolves path annotations at runtime
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from docsmoke import __version__
+from docsmoke.config import Config
+from docsmoke.config import load as load_config
+from docsmoke.exceptions import ConfigError, DirectiveError
+from docsmoke.reporting import render, write
+from docsmoke.runner import collect_snippets
+from docsmoke.runner import scan as run_scan
+
+app = typer.Typer(
+    name="docsmoke",
+    help="Validate executable Markdown documentation snippets.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"docsmoke {__version__}")
+        raise typer.Exit()
+
+
+def _resolve_config(
+    config_path: Path | None,
+    *,
+    all_supported: bool,
+    fail_fast: bool | None,
+) -> Config:
+    config = load_config(config_path)
+    if all_supported:
+        config.require_directive = False
+    if fail_fast is not None:
+        config.fail_fast = fail_fast
+    return config
+
+
+@app.callback()
+def _root(
+    _version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = None,
+) -> None:
+    """Executable documentation smoke tests for Markdown."""
+
+
+@app.command()
+def scan(
+    paths: Annotated[
+        list[Path] | None,
+        typer.Argument(
+            help="Markdown files or directories to scan. Defaults to configured include globs."
+        ),
+    ] = None,
+    config_path: Annotated[
+        Path | None,
+        typer.Option("--config", help="Path to docsmoke.toml or pyproject.toml."),
+    ] = None,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Write a machine-readable report."),
+    ] = None,
+    fmt: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Report format for --output: json or markdown."),
+    ] = "json",
+    quiet: Annotated[
+        bool,
+        typer.Option("--quiet", "-q", help="Suppress console report output."),
+    ] = False,
+    all_supported: Annotated[
+        bool,
+        typer.Option(
+            "--all-supported",
+            help="Execute every supported fenced block, even when not explicitly marked.",
+        ),
+    ] = False,
+    fail_fast: Annotated[
+        bool | None,
+        typer.Option("--fail-fast/--no-fail-fast", help="Stop after the first failing snippet."),
+    ] = None,
+) -> None:
+    """Scan Markdown files, execute snippets, and report the results."""
+    if output is not None and fmt not in {"json", "markdown"}:
+        typer.secho("--format must be 'json' or 'markdown'", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    try:
+        paths = paths or []
+        config = _resolve_config(config_path, all_supported=all_supported, fail_fast=fail_fast)
+        report = run_scan(paths, config=config)
+    except (ConfigError, DirectiveError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2) from None
+
+    if not quiet:
+        typer.echo(render(report, "console"))
+
+    if output is not None:
+        write(report, output, fmt)
+
+    if report.has_failures:
+        raise typer.Exit(code=2)
+
+
+@app.command("list-snippets")
+def list_snippets(
+    paths: Annotated[
+        list[Path] | None,
+        typer.Argument(
+            help="Markdown files or directories to inspect. Defaults to configured include globs."
+        ),
+    ] = None,
+    config_path: Annotated[
+        Path | None,
+        typer.Option("--config", help="Path to docsmoke.toml or pyproject.toml."),
+    ] = None,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Emit JSON instead of a table."),
+    ] = False,
+    all_supported: Annotated[
+        bool,
+        typer.Option(
+            "--all-supported",
+            help="List every supported fenced block, even when not explicitly marked.",
+        ),
+    ] = False,
+) -> None:
+    """List snippets that docsmoke would execute."""
+    try:
+        paths = paths or []
+        config = _resolve_config(config_path, all_supported=all_supported, fail_fast=None)
+        snippets = collect_snippets(paths, config=config)
+    except (ConfigError, DirectiveError) as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2) from None
+
+    if as_json:
+        payload = [
+            {
+                "id": snippet.identifier,
+                "path": str(snippet.path),
+                "language": snippet.language,
+                "executor": snippet.executor,
+                "name": snippet.display_name,
+                "line": snippet.start_line,
+            }
+            for snippet in snippets
+        ]
+        typer.echo(json.dumps(payload, indent=2, ensure_ascii=False))
+        return
+
+    table = Table(title="docsmoke snippets")
+    table.add_column("Snippet")
+    table.add_column("Language")
+    table.add_column("Executor")
+    table.add_column("Location")
+    for snippet in snippets:
+        table.add_row(
+            snippet.display_name,
+            snippet.language,
+            snippet.executor,
+            f"{snippet.path}:{snippet.start_line}",
+        )
+    console = Console()
+    console.print(table)

docsmoke/config.py

@@ -0,0 +1,98 @@
+"""Configuration loading and validation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from docsmoke.exceptions import ConfigError
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover
+    import tomli as tomllib
+
+
+@dataclass(slots=True)
+class Config:
+    """User-configurable scan defaults."""
+
+    project_root: Path = field(default_factory=Path.cwd)
+    include: tuple[str, ...] = ("README.md", "docs/**/*.md")
+    exclude: tuple[str, ...] = (".venv/**", "build/**", "dist/**")
+    default_timeout: float = 10.0
+    fail_fast: bool = False
+    require_directive: bool = True
+
+    def __post_init__(self) -> None:
+        if self.default_timeout <= 0:
+            raise ConfigError("default_timeout must be greater than 0")
+        if not self.include:
+            raise ConfigError("include must contain at least one glob")
+        if not all(isinstance(item, str) and item for item in self.include):
+            raise ConfigError("include must contain non-empty strings")
+        if not all(isinstance(item, str) and item for item in self.exclude):
+            raise ConfigError("exclude must contain non-empty strings")
+
+
+def load(config_path: Path | None = None) -> Config:
+    """Load configuration from docsmoke.toml or pyproject.toml when present."""
+    candidate = config_path
+    if candidate is None:
+        docsmoke_file = Path.cwd() / "docsmoke.toml"
+        pyproject_file = Path.cwd() / "pyproject.toml"
+        if docsmoke_file.exists():
+            candidate = docsmoke_file
+        elif pyproject_file.exists():
+            candidate = pyproject_file
+
+    if candidate is None:
+        return Config(project_root=Path.cwd())
+
+    if not candidate.exists():
+        raise ConfigError(f"config file does not exist: {candidate}")
+
+    data = tomllib.loads(candidate.read_text(encoding="utf-8"))
+    source = data if candidate.name == "docsmoke.toml" else data.get("tool", {}).get("docsmoke", {})
+    if not isinstance(source, dict):
+        raise ConfigError("docsmoke config section must be a TOML table")
+
+    return _from_mapping(source, project_root=candidate.parent)
+
+
+def _from_mapping(mapping: dict[str, Any], *, project_root: Path) -> Config:
+    include = _tuple_of_strings(mapping.get("include", ("README.md", "docs/**/*.md")), "include")
+    exclude = _tuple_of_strings(
+        mapping.get("exclude", (".venv/**", "build/**", "dist/**")), "exclude"
+    )
+    default_timeout = mapping.get("default_timeout", 10.0)
+    fail_fast = mapping.get("fail_fast", False)
+    require_directive = mapping.get("require_directive", True)
+
+    if not isinstance(default_timeout, (int, float)) or isinstance(default_timeout, bool):
+        raise ConfigError("default_timeout must be a positive number")
+    if not isinstance(fail_fast, bool):
+        raise ConfigError("fail_fast must be a boolean")
+    if not isinstance(require_directive, bool):
+        raise ConfigError("require_directive must be a boolean")
+
+    return Config(
+        project_root=project_root.resolve(),
+        include=include,
+        exclude=exclude,
+        default_timeout=float(default_timeout),
+        fail_fast=fail_fast,
+        require_directive=require_directive,
+    )
+
+
+def _tuple_of_strings(value: Any, field_name: str) -> tuple[str, ...]:
+    if isinstance(value, str):
+        return (value,)
+    if not isinstance(value, (list, tuple)):
+        raise ConfigError(f"{field_name} must be a string or list of strings")
+    items = tuple(value)
+    if not all(isinstance(item, str) and item for item in items):
+        raise ConfigError(f"{field_name} must contain non-empty strings")
+    return items

docsmoke/exceptions.py

@@ -0,0 +1,13 @@
+"""docsmoke exception hierarchy."""
+
+
+class DocsmokeError(Exception):
+    """Base error for user-facing docsmoke failures."""
+
+
+class ConfigError(DocsmokeError):
+    """Invalid configuration or user input."""
+
+
+class DirectiveError(DocsmokeError):
+    """Invalid docsmoke directive embedded in a snippet."""

docsmoke/executor.py

@@ -0,0 +1,162 @@
+"""Snippet execution primitives."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from docsmoke.models import Snippet, SnippetResult, SnippetStatus
+
+
+def run_snippet(snippet: Snippet, *, project_root: Path, default_timeout: float) -> SnippetResult:
+    """Execute a single snippet and evaluate its expectations."""
+    if snippet.directives.skip:
+        return SnippetResult(
+            snippet=snippet,
+            status=SnippetStatus.skipped,
+            duration_seconds=0.0,
+            exit_code=None,
+            stdout="",
+            stderr="",
+            message="snippet marked as skipped",
+        )
+
+    if not snippet.code.strip():
+        return SnippetResult(
+            snippet=snippet,
+            status=SnippetStatus.error,
+            duration_seconds=0.0,
+            exit_code=None,
+            stdout="",
+            stderr="",
+            message="snippet body is empty",
+        )
+
+    timeout = snippet.directives.timeout or default_timeout
+    cwd = _resolve_cwd(project_root, snippet)
+    if not cwd.exists():
+        return SnippetResult(
+            snippet=snippet,
+            status=SnippetStatus.error,
+            duration_seconds=0.0,
+            exit_code=None,
+            stdout="",
+            stderr="",
+            message=f"working directory does not exist: {cwd}",
+        )
+    if not cwd.is_dir():
+        return SnippetResult(
+            snippet=snippet,
+            status=SnippetStatus.error,
+            duration_seconds=0.0,
+            exit_code=None,
+            stdout="",
+            stderr="",
+            message=f"working directory is not a directory: {cwd}",
+        )
+    env = os.environ.copy()
+    env["PATH"] = _prepend_executable_dir(env.get("PATH", ""))
+    env.update(snippet.directives.env)
+    command = _build_command(snippet)
+
+    started = time.perf_counter()
+    try:
+        completed = subprocess.run(
+            command,
+            cwd=cwd,
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        duration = time.perf_counter() - started
+        return SnippetResult(
+            snippet=snippet,
+            status=SnippetStatus.error,
+            duration_seconds=duration,
+            exit_code=None,
+            stdout="",
+            stderr="",
+            message=f"executor not available: {exc.filename}",
+        )
+    except subprocess.TimeoutExpired as exc:
+        duration = time.perf_counter() - started
+        return SnippetResult(
+            snippet=snippet,
+            status=SnippetStatus.error,
+            duration_seconds=duration,
+            exit_code=None,
+            stdout=_coerce_output(exc.stdout),
+            stderr=_coerce_output(exc.stderr),
+            message=f"timed out after {timeout:.1f}s",
+        )
+
+    duration = time.perf_counter() - started
+    status, message = _evaluate(snippet, completed.returncode, completed.stdout, completed.stderr)
+    return SnippetResult(
+        snippet=snippet,
+        status=status,
+        duration_seconds=duration,
+        exit_code=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+        message=message,
+    )
+
+
+def _build_command(snippet: Snippet) -> list[str]:
+    if snippet.executor == "python":
+        return [sys.executable, "-c", snippet.code]
+    return [snippet.directives.shell or snippet.executor, "-eu", "-c", snippet.code]
+
+
+def _resolve_cwd(project_root: Path, snippet: Snippet) -> Path:
+    if snippet.directives.cwd is None:
+        return project_root
+    return (project_root / snippet.directives.cwd).resolve()
+
+
+def _evaluate(
+    snippet: Snippet,
+    exit_code: int,
+    stdout: str,
+    stderr: str,
+) -> tuple[SnippetStatus, str]:
+    if exit_code != 0:
+        return SnippetStatus.failed, f"snippet exited with code {exit_code}"
+
+    combined = stdout + stderr
+    for expected in snippet.directives.expect_contains:
+        if expected not in combined:
+            return SnippetStatus.failed, f"missing expected text: {expected!r}"
+
+    for pattern in snippet.directives.expect_regex:
+        try:
+            matched = re.search(pattern, combined, flags=re.MULTILINE)
+        except re.error as exc:
+            return SnippetStatus.error, f"invalid regex {pattern!r}: {exc}"
+        if matched is None:
+            return SnippetStatus.failed, f"missing regex match: {pattern!r}"
+
+    return SnippetStatus.passed, "ok"
+
+
+def _coerce_output(value: bytes | str | None) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode(errors="replace")
+    return value
+
+
+def _prepend_executable_dir(path_value: str) -> str:
+    executable_dir = Path(sys.executable).parent
+    if path_value:
+        return f"{executable_dir}{os.pathsep}{path_value}"
+    return str(executable_dir)

docsmoke/markdown.py

@@ -0,0 +1,211 @@
+"""Markdown fenced-block discovery and docsmoke directive parsing."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from docsmoke.exceptions import DirectiveError
+from docsmoke.models import Snippet, SnippetDirectives
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+DIRECTIVE_PATTERNS = (
+    re.compile(r"^\s*#\s*docsmoke:\s*(?P<body>.+?)\s*$"),
+    re.compile(r"^\s*//\s*docsmoke:\s*(?P<body>.+?)\s*$"),
+    re.compile(r"^\s*<!--\s*docsmoke:\s*(?P<body>.+?)\s*-->\s*$"),
+)
+OPENING_FENCE_PATTERN = re.compile(r"^(?P<indent> {0,3})(?P<fence>`{3,}|~{3,})(?P<info>.*)$")
+
+SUPPORTED_EXECUTORS = {
+    "bash": "bash",
+    "sh": "sh",
+    "shell": "sh",
+    "zsh": "zsh",
+    "python": "python",
+    "py": "python",
+}
+
+
+def discover_snippets(path: Path, *, require_directive: bool = True) -> list[Snippet]:
+    """Parse a Markdown file and return runnable docsmoke snippets."""
+    lines = path.read_text(encoding="utf-8").splitlines()
+    snippets: list[Snippet] = []
+    index = 0
+
+    while index < len(lines):
+        line = lines[index]
+        opening_fence = _parse_opening_fence(line)
+        if opening_fence is None:
+            index += 1
+            continue
+
+        fence_char, fence_length, info = opening_fence
+        opening_line = index + 1
+        index += 1
+        body: list[str] = []
+        while index < len(lines) and not _is_closing_fence(
+            lines[index], fence_char=fence_char, fence_length=fence_length
+        ):
+            body.append(lines[index])
+            index += 1
+
+        closing_line = index + 1 if index < len(lines) else len(lines)
+        language, opted_in = _parse_info_string(info)
+        executor = SUPPORTED_EXECUTORS.get(language)
+
+        if executor is None:
+            index += 1
+            continue
+
+        directives, code, has_directives = _parse_directives(body, path=path, line=opening_line)
+        if require_directive and not opted_in and not has_directives:
+            index += 1
+            continue
+
+        snippets.append(
+            Snippet(
+                path=path,
+                language=language,
+                executor=executor,
+                code="\n".join(code).rstrip(),
+                start_line=opening_line,
+                end_line=closing_line,
+                directives=directives,
+            )
+        )
+        index += 1
+
+    return snippets
+
+
+def _parse_opening_fence(line: str) -> tuple[str, int, str] | None:
+    match = OPENING_FENCE_PATTERN.match(line)
+    if match is None:
+        return None
+    fence = match.group("fence")
+    return fence[0], len(fence), match.group("info").strip()
+
+
+def _is_closing_fence(line: str, *, fence_char: str, fence_length: int) -> bool:
+    candidate = line.lstrip(" ")
+    if len(line) - len(candidate) > 3:
+        return False
+
+    marker_count = 0
+    for character in candidate:
+        if character != fence_char:
+            break
+        marker_count += 1
+
+    if marker_count < fence_length:
+        return False
+    return candidate[marker_count:].strip() == ""
+
+
+def _parse_info_string(info: str) -> tuple[str, bool]:
+    tokens = info.split()
+    if not tokens:
+        return "", False
+    language = tokens[0].lower()
+    opted_in = any(token.lower() == "docsmoke" for token in tokens[1:])
+    return language, opted_in
+
+
+def _parse_directives(
+    body: list[str],
+    *,
+    path: Path,
+    line: int,
+) -> tuple[SnippetDirectives, list[str], bool]:
+    directives = SnippetDirectives()
+    directive_count = 0
+    code = list(body)
+
+    while code:
+        payload = _directive_payload(code[0])
+        if payload is None:
+            break
+        directive_count += 1
+        _apply_directive_payload(directives, payload, path=path, line=line + directive_count)
+        code.pop(0)
+
+    return directives, code, directive_count > 0
+
+
+def _directive_payload(line: str) -> str | None:
+    for pattern in DIRECTIVE_PATTERNS:
+        match = pattern.match(line)
+        if match:
+            return match.group("body")
+    return None
+
+
+def _apply_directive_payload(
+    directives: SnippetDirectives,
+    payload: str,
+    *,
+    path: Path,
+    line: int,
+) -> None:
+    for part in payload.split(";"):
+        item = part.strip()
+        if not item:
+            continue
+        key, has_sep, value = item.partition("=")
+        raw_key = key.strip()
+        normalized_key = raw_key.lower()
+        normalized_value = value.strip()
+
+        if normalized_key == "name":
+            _require_value(has_sep, normalized_value, key=normalized_key, path=path, line=line)
+            directives.name = normalized_value
+        elif normalized_key == "cwd":
+            _require_value(has_sep, normalized_value, key=normalized_key, path=path, line=line)
+            directives.cwd = normalized_value
+        elif normalized_key == "timeout":
+            _require_value(has_sep, normalized_value, key=normalized_key, path=path, line=line)
+            try:
+                directives.timeout = float(normalized_value)
+            except ValueError as exc:
+                raise DirectiveError(
+                    f"{path}:{line}: timeout must be numeric, got {normalized_value!r}"
+                ) from exc
+            if directives.timeout <= 0:
+                raise DirectiveError(f"{path}:{line}: timeout must be greater than 0")
+        elif normalized_key == "expect-contains":
+            _require_value(has_sep, normalized_value, key=normalized_key, path=path, line=line)
+            directives.expect_contains += (normalized_value,)
+        elif normalized_key == "expect-regex":
+            _require_value(has_sep, normalized_value, key=normalized_key, path=path, line=line)
+            directives.expect_regex += (normalized_value,)
+        elif normalized_key == "shell":
+            _require_value(has_sep, normalized_value, key=normalized_key, path=path, line=line)
+            directives.shell = normalized_value
+        elif normalized_key == "skip":
+            directives.skip = _parse_bool(
+                normalized_value if has_sep else "true", path=path, line=line
+            )
+        elif normalized_key.startswith("env."):
+            _require_value(has_sep, normalized_value, key=normalized_key, path=path, line=line)
+            env_name = raw_key[4:]
+            if not env_name:
+                raise DirectiveError(f"{path}:{line}: env directives require a variable name")
+            directives.env[env_name] = normalized_value
+        else:
+            raise DirectiveError(f"{path}:{line}: unknown docsmoke directive {normalized_key!r}")
+
+
+def _require_value(has_sep: str, value: str, *, key: str, path: Path, line: int) -> None:
+    if has_sep != "=" or value == "":
+        raise DirectiveError(f"{path}:{line}: directive {key!r} requires a value")
+
+
+def _parse_bool(value: str, *, path: Path, line: int) -> bool:
+    normalized = value.lower()
+    if normalized in {"1", "true", "yes", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "off"}:
+        return False
+    raise DirectiveError(f"{path}:{line}: invalid boolean value {value!r}")