tiredize 0.1.0__py3-none-any.whl

tiredize/__main__.py

@@ -0,0 +1,19 @@
+"""Entry point for `python -m tiredize`.
+
+The console script generated from `[project.scripts]` wraps
+`tiredize.cli:main` in `sys.exit(...)`; module execution has no such
+wrapper, so the exit status has to be raised here. Without it every
+`-m` invocation exits `0` and the tool cannot gate CI or a pre-commit
+hook.
+"""
+# Standard library
+from __future__ import annotations
+
+# Local
+from tiredize.cli import main
+
+
+# `raise SystemExit(...)` matches the idiom at the bottom of
+# `tiredize/cli.py`. A usage error raised by argparse inside `main()`
+# is itself a SystemExit and unwinds through this statement untouched.
+raise SystemExit(main())

tiredize/cli.py

@@ -0,0 +1,238 @@
+# Standard library
+from __future__ import annotations
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as metadata_version
+from pathlib import Path
+from typing import Any
+import argparse
+import sys
+
+# Third-party
+import yaml
+
+# Local
+from tiredize.core_types import RuleNotFoundError
+from tiredize.core_types import RuleResult
+from tiredize.linter.engine import run_linter
+from tiredize.markdown.types.document import Document
+from tiredize.markdown.types.schema import load_schema
+from tiredize.validators.frontmatter_schema import load_frontmatter_schema
+from tiredize.validators.frontmatter_schema import validate \
+    as validate_frontmatter
+from tiredize.validators.markdown_schema import AmbiguityError
+from tiredize.validators.markdown_schema import validate
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tiredize",
+        description="Validate markdown documents against user-defined "
+        "linting rules and schemas."
+    )
+
+    parser.add_argument(
+        "--rules",
+        dest="rules_path",
+        help="YAML configuration file defining linter rules.",
+    )
+    parser.add_argument(
+        "--markdown-schema",
+        dest="markdown_schema_path",
+        help="YAML configuration file defining markdown schema.",
+    )
+    parser.add_argument(
+        "--frontmatter-schema",
+        dest="frontmatter_schema_path",
+        help="YAML configuration file defining frontmatter schema.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {_installed_version()}",
+        help="Print the installed tiredize version and exit.",
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        help="Markdown files to validate.",
+    )
+
+    return parser
+
+
+def _installed_version() -> str:
+    """
+    Return the version of the installed tiredize distribution.
+
+    The version lives only in the distribution metadata, which
+    hatch-vcs derives from git tags at build time; no source file
+    holds it. When tiredize is imported from a source tree that was
+    never installed there is no metadata, and "unknown" is returned
+    so that normal runs still work and `--version` makes no number
+    up.
+    """
+    try:
+        return metadata_version("tiredize")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    with path.open("r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"Expected YAML mapping in {path}, "
+            f"got {type(data).__name__}."
+        )
+    return data
+
+
+def _run_rules(
+    doc: Document,
+    rules_config_path: Path,
+) -> list[RuleResult]:
+    raw_config = _load_yaml(rules_config_path)
+
+    results: list[RuleResult] = run_linter(
+        document=doc,
+        rule_configs=raw_config
+    )
+    return results
+
+
+def _run_markdown_schema(doc: Document, schema_path: Path) -> list[RuleResult]:
+    schema = load_schema(schema_path.read_text(encoding="utf-8"))
+    return validate(doc, schema)
+
+
+def _run_frontmatter_schema(
+        doc: Document,
+        schema_path: Path) -> list[RuleResult]:
+    schema = load_frontmatter_schema(
+        schema_path.read_text(encoding="utf-8")
+    )
+    return validate_frontmatter(doc, schema)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """
+    Validate every requested path and return the process exit status.
+
+    Returns:
+        0 - every path was loaded and produced no findings.
+        1 - at least one path produced findings, or a runtime error
+            occurred.
+        2 - usage error: no paths, or no configuration flag.
+
+    Findings do not stop the run: every path is processed, every
+    finding is reported, and the status is 1 at the end. Runtime
+    errors do stop it: the first one prints to stderr and the status
+    is returned immediately, leaving later paths unprocessed.
+
+    Argparse's own errors raise SystemExit(2) from inside this
+    function rather than returning.
+    """
+    parser = _build_arg_parser()
+    args = parser.parse_args(argv)
+
+    if not args.paths or not (
+        args.rules_path or args.markdown_schema_path or
+            args.frontmatter_schema_path):
+        parser.print_usage(sys.stderr)
+        print(
+            "error: at least one of --rules, --markdown-schema, or "
+            "--frontmatter-schema must be provided, and at least one path.",
+            file=sys.stderr,
+        )
+        return 2
+
+    exit_code = 0
+
+    for path_str in args.paths:
+        doc = Document()
+        try:
+            doc.load(path=Path(path_str))
+        except FileNotFoundError as exc:
+            # A runtime error aborts the run. Findings continue to the
+            # next path; errors do not, so any remaining paths are
+            # left unprocessed.
+            print(
+                f"error: {exc}",
+                file=sys.stderr,
+            )
+            return 1
+
+        all_results: list[RuleResult] = []
+
+        if args.rules_path:
+            try:
+                all_results.extend(
+                    _run_rules(
+                        doc, Path(args.rules_path)
+                    )
+                )
+            except (
+                RuleNotFoundError,
+                FileNotFoundError,
+                ValueError,
+                yaml.YAMLError,
+            ) as exc:
+                print(
+                    f"error: {exc}",
+                    file=sys.stderr,
+                )
+                return 1
+
+        if args.markdown_schema_path:
+            try:
+                all_results.extend(
+                    _run_markdown_schema(
+                        doc, Path(args.markdown_schema_path)
+                    )
+                )
+            except (
+                ValueError,
+                AmbiguityError,
+                FileNotFoundError,
+                yaml.YAMLError,
+            ) as exc:
+                print(
+                    f"error: {exc}",
+                    file=sys.stderr,
+                )
+                return 1
+
+        if args.frontmatter_schema_path:
+            try:
+                all_results.extend(
+                    _run_frontmatter_schema(
+                        doc, Path(args.frontmatter_schema_path)
+                    )
+                )
+            except (
+                ValueError,
+                FileNotFoundError,
+                yaml.YAMLError,
+            ) as exc:
+                print(
+                    f"error: {exc}",
+                    file=sys.stderr,
+                )
+                return 1
+
+        for res in all_results:
+            pos = res.position
+            line, col = doc.line_col(pos.offset)
+            print(f"{doc.path}:{line}:{col}: [{res.rule_id}] {res.message}")
+        if all_results:
+            exit_code = 1
+        else:
+            print(f"{doc.path}: no issues found.")
+    return exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tiredize/core_types.py

@@ -0,0 +1,21 @@
+# Standard library
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+class RuleNotFoundError(Exception):
+    """Raised when a rule ID does not match any discovered rule."""
+    pass
+
+
+@dataclass(frozen=True)
+class Position:
+    offset: int
+    length: int
+
+
+@dataclass(frozen=False)
+class RuleResult:
+    position: Position
+    rule_id: str | None
+    message: str

tiredize/linter/engine.py

@@ -0,0 +1,73 @@
+# Standard library
+from __future__ import annotations
+from dataclasses import replace
+from typing import Any
+
+# Local
+from tiredize.core_types import RuleNotFoundError
+from tiredize.core_types import RuleResult
+from tiredize.linter.rules import Rule
+from tiredize.linter.rules import discover_rules
+from tiredize.markdown.types.document import Document
+
+
+def _select_rules(
+    rules: dict[str, Rule],
+    rule_configs: dict[str, dict[str, Any]] | None,
+) -> dict[str, dict[str, Rule | dict[str, Any]]]:
+    """
+    Filter rules by id.
+
+    If rule_configs is None, no rules are returned.
+    """
+    if rule_configs is None:
+        return dict()
+
+    enabled_set: dict[str, dict[str, dict[str, Any] | Rule]] = dict()
+    for rule_id in rule_configs.keys():
+        if rule_id not in rules:
+            raise RuleNotFoundError(f"Unknown rule id: {rule_id}")
+        if rule_id not in enabled_set:
+            enabled_set[rule_id] = dict()
+        rule_config = rule_configs[rule_id]
+        enabled_set[rule_id]["rule"] = rules[rule_id]
+        enabled_set[rule_id]["config"] = rule_config
+
+    return enabled_set
+
+
+def run_linter(
+    document: Document,
+    rule_configs: dict[str, dict[str, Any]] | None = None
+) -> list[RuleResult]:
+    """
+    Run lint rules against a document and return normalized results.
+
+    - document: the parsed Document to lint.
+    - rule_configs: mapping of rule_id to configuration dictionary
+
+    Note: Rules without an entry are disabled.
+    """
+    all_rules = discover_rules()
+    active_rules = _select_rules(all_rules, rule_configs)
+
+    all_results: list[RuleResult] = []
+    for rule_id in active_rules.keys():
+        rule_config = active_rules[rule_id]["config"]
+        if not isinstance(rule_config, dict):
+            raise ValueError(
+                f"Invalid configuration for rule {rule_id}: {rule_config}"
+            )
+
+        rule = active_rules[rule_id]["rule"]
+        if not isinstance(rule, Rule):
+            raise ValueError(
+                f"Invalid rule object for {rule_id}: {rule}"
+            )
+
+        raw_results = rule.func(document, rule_config)
+        for res in raw_results:
+            normalized = replace(res, rule_id=rule_id)
+            all_results.append(normalized)
+
+    return all_results

tiredize/linter/rules/__init__.py

@@ -0,0 +1,107 @@
+# Standard library
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any
+from typing import Callable
+import importlib
+import inspect
+import pkgutil
+
+# Local
+from tiredize.core_types import RuleResult
+from tiredize.markdown.types.document import Document
+
+
+RuleFunc = Callable[[Document, dict[str, Any]], list[RuleResult]]
+
+
+@dataclass(frozen=True)
+class Rule:
+    """
+    Class containing a single lint rule.
+    """
+    id: str
+    func: RuleFunc
+    description: str | None = None
+
+
+def _iter_rule_modules(package_name: str) -> list[str]:
+    """
+    Return fully qualified module names for all rule modules.
+
+    A rule module is any non private Python module directly under this package.
+    """
+    package = importlib.import_module(package_name)
+    if not hasattr(package, "__path__"):
+        # Not a package, nothing to iterate
+        return []
+
+    module_names: list[str] = []
+
+    prefix = package.__name__ + "."
+    for _, name, ispkg in pkgutil.iter_modules(package.__path__, prefix):
+        # Skip subpackages for now, only plain modules
+        if ispkg:
+            continue
+
+        short_name = name.rsplit(".", 1)[-1]
+        if short_name.startswith("_"):
+            continue
+
+        module_names.append(name)
+
+    return module_names
+
+
+def _is_rule_function(name: str, obj: Any) -> bool:
+    """
+    A rule is any callable named 'validate'.
+    """
+    return callable(obj) and name == "validate"
+
+
+def _rule_id(module_name: str, func_name: str) -> str:
+    """
+    Compute the rule id from module and function names.
+
+    Example:
+        module_name = 'tiredize.linter.rules.whitespace'
+        func_name = 'validate_newline_at_eof'
+        result = 'whitespace.validate_newline_at_eof'
+    """
+    short_module = module_name.rsplit(".", 1)[-1]
+    return f"{short_module}"
+
+
+def discover_rules(package: str | None = None) -> dict[str, Rule]:
+    """
+    Import all rule modules and return a mapping of rule_id to definitions.
+
+    If package is None, rules are discovered under tiredize.linter.rules.
+    If package is provided, it must be the dotted name of a Python package
+    that contains rule modules.
+    """
+    package_name = package or __name__
+    rules: dict[str, Rule] = {}
+
+    module_names: list[str] = _iter_rule_modules(package_name)
+    for module_name in module_names:
+        module = importlib.import_module(module_name)
+
+        for name, obj in inspect.getmembers(module):
+            if not _is_rule_function(name, obj):
+                continue
+
+            func: RuleFunc = obj
+            rule_id = _rule_id(module_name, name)
+            description = inspect.getdoc(func)
+            if description:
+                description = description.strip()
+
+            rules[rule_id] = Rule(
+                id=rule_id,
+                func=func,
+                description=description,
+            )
+
+    return rules

tiredize/linter/rules/_elements.py

@@ -0,0 +1,32 @@
+# Standard library
+from __future__ import annotations
+
+_ELEMENT_LABELS = {
+    "autolink": "Autolink",
+    "autolink_extended": "Extended autolink",
+    "code_block": "Fenced code block",
+    "code_inline": "Inline code",
+    "header": "Header",
+    "image_inline": "Inline image",
+    "image_reference": "Reference-style image",
+    "link_inline": "Inline link",
+    "link_reference": "Reference-style link",
+    "quoteblock": "Blockquote",
+    "reference_definition": "Reference definition",
+    "table": "Table",
+}
+
+_ELEMENT_MAP = {
+    "autolink": lambda s: s.autolinks,
+    "autolink_extended": lambda s: s.autolinks_extended,
+    "code_block": lambda s: s.code_block,
+    "code_inline": lambda s: s.code_inline,
+    "header": lambda s: [s.header] if s.header.position.length > 0 else [],
+    "image_inline": lambda s: s.images_inline,
+    "image_reference": lambda s: s.images_reference,
+    "link_inline": lambda s: s.links_inline,
+    "link_reference": lambda s: s.links_reference,
+    "quoteblock": lambda s: s.quoteblocks,
+    "reference_definition": lambda s: s.reference_definitions,
+    "table": lambda s: s.tables,
+}

tiredize/linter/rules/elements.py

@@ -0,0 +1,71 @@
+# Standard library
+from __future__ import annotations
+from typing import Any
+
+# Local
+from tiredize.core_types import RuleResult
+from tiredize.linter.rules._elements import _ELEMENT_LABELS
+from tiredize.linter.rules._elements import _ELEMENT_MAP
+from tiredize.linter.utils import get_config_list
+from tiredize.linter.utils import validate_config
+from tiredize.markdown.types.document import Document
+
+
+# Configuration keys this rule accepts, and the subset it requires.
+# `disallow` is required because the rule inspects nothing without
+# it: enabling `elements` with no `disallow` would be a no-op.
+_RULE_ID = "elements"
+_ALLOWED_KEYS = {
+    "disallow": "list",
+}
+_REQUIRED_KEYS = ("disallow",)
+
+
+def validate(
+    document: Document,
+    config: dict[str, Any],
+) -> list[RuleResult]:
+    """
+    Validate that the document does not contain disallowed element types.
+
+    Configuration:
+        disallow: list[str] - Element types that must not appear in the
+            document. Required; an empty list allows everything.
+
+    Raises:
+        ValueError: the configuration names a key this rule does not
+            accept, gives an accepted key a wrong-typed value, omits
+            a required key, or names an unknown element in disallow.
+    """
+    validate_config(config, _ALLOWED_KEYS, _REQUIRED_KEYS, _RULE_ID)
+
+    # validate_config has confirmed disallow is present and a list.
+    disallow = get_config_list(config, "disallow")
+    if not disallow:
+        return []
+
+    for name in disallow:
+        if not isinstance(name, str):
+            raise ValueError(
+                "disallow entries must be strings, got "
+                f"{type(name).__name__!r}: {name!r}"
+            )
+        if name not in _ELEMENT_MAP:
+            raise ValueError(f"Unknown element name in disallow: '{name}'")
+
+    results: list[RuleResult] = []
+    for section in document.sections:
+        for name in disallow:
+            label = _ELEMENT_LABELS[name]
+            for elem in _ELEMENT_MAP[name](section):
+                if elem.position.length == 0:
+                    continue
+                results.append(
+                    RuleResult(
+                        message=f"{label} is not allowed.",
+                        position=elem.position,
+                        rule_id=None,
+                    )
+                )
+
+    return results

tiredize/linter/rules/line_length.py

@@ -0,0 +1,131 @@
+# Standard library
+from __future__ import annotations
+import bisect
+from typing import Any
+
+# Local
+from tiredize.core_types import Position
+from tiredize.core_types import RuleResult
+from tiredize.linter.rules._elements import _ELEMENT_MAP
+from tiredize.linter.utils import get_config_int
+from tiredize.linter.utils import get_config_list
+from tiredize.linter.utils import validate_config
+from tiredize.markdown.types.document import Document
+
+
+# Configuration keys this rule accepts, and the subset it requires.
+# `maximum_length` is required because the rule measures nothing
+# without it; `exclude` has a working default of "exclude nothing".
+_RULE_ID = "line_length"
+_ALLOWED_KEYS = {
+    "exclude": "list",
+    "maximum_length": "int",
+}
+_REQUIRED_KEYS = ("maximum_length",)
+
+
+def _build_excluded_ranges(
+    document: Document,
+    exclude: list[str],
+) -> list[tuple[int, int]]:
+    for name in exclude:
+        if not isinstance(name, str):
+            raise ValueError(
+                "exclude entries must be strings, got "
+                f"{type(name).__name__!r}: {name!r}"
+            )
+        if name not in _ELEMENT_MAP:
+            raise ValueError(f"Unknown element name in exclude: '{name}'")
+
+    raw: list[tuple[int, int]] = []
+    for section in document.sections:
+        for name in exclude:
+            for elem in _ELEMENT_MAP[name](section):
+                start = elem.position.offset
+                end = start + elem.position.length
+                if end > start:
+                    raw.append((start, end))
+
+    if not raw:
+        return []
+
+    raw.sort()
+    merged: list[tuple[int, int]] = [raw[0]]
+    for start, end in raw[1:]:
+        if start <= merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+        else:
+            merged.append((start, end))
+    return merged
+
+
+def validate(
+    document: Document,
+    config: dict[str, Any],
+) -> list[RuleResult]:
+    """
+    Validate document meets line length requirements.
+
+    Configuration:
+        maximum_length: int - The maximum allowed line length.
+            Required.
+        exclude: list[str] - Element types whose lines are exempt from
+            the limit. Optional; defaults to no exemptions.
+
+    Raises:
+        ValueError: the configuration names a key this rule does not
+            accept, gives an accepted key a wrong-typed value, omits
+            a required key, or names an unknown element in exclude.
+    """
+    validate_config(config, _ALLOWED_KEYS, _REQUIRED_KEYS, _RULE_ID)
+
+    # validate_config has confirmed maximum_length is present and an
+    # int, so the accessor cannot return None here.
+    maximum_length = get_config_int(config, "maximum_length")
+
+    exclude = get_config_list(config, "exclude") or []
+    excluded_ranges = _build_excluded_ranges(document, exclude)
+    exc_starts = [s for s, _ in excluded_ranges]
+
+    results: list[RuleResult] = []
+    text = document.string
+    cursor = 0
+
+    for line in text.splitlines(keepends=True):
+        line_end = cursor + len(line)
+
+        idx = bisect.bisect_right(exc_starts, cursor) - 1
+        line_excluded = (
+            idx >= 0 and excluded_ranges[idx][1] > cursor
+        ) or (
+            idx + 1 < len(excluded_ranges)
+            and excluded_ranges[idx + 1][0] < line_end
+        )
+
+        if not line_excluded:
+            line_text = line
+            if line.endswith("\n"):
+                line_text = line[:-1]
+                if line_text.endswith("\r"):
+                    line_text = line_text[:-1]
+
+            line_length = len(line_text)
+            if line_length > maximum_length:
+                overflow = line_length - maximum_length
+                position = Position(
+                    offset=cursor + maximum_length,
+                    length=overflow,
+                )
+                results.append(
+                    RuleResult(
+                        message=(
+                            f"Line exceeds maximum length of {maximum_length} "
+                            f"({line_length} found)."
+                        ),
+                        position=position,
+                        rule_id=None,
+                    )
+                )
+
+        cursor += len(line)
+    return results