irminsul 0.1.0.dev0__py3-none-any.whl

irminsul/__init__.py

@@ -0,0 +1,7 @@
+"""Irminsul — a documentation system for complex codebases."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0.dev0"
+
+__all__ = ["__version__"]

irminsul/checks/__init__.py

@@ -0,0 +1,31 @@
+"""Check registry.
+
+Looking-up by name keeps the CLI/config side honest: `irminsul.toml`'s
+`checks.hard` field is just a list of strings, and we resolve them here.
+"""
+
+from __future__ import annotations
+
+from irminsul.checks.base import Check, Finding, Severity, sort_findings, summarize
+from irminsul.checks.frontmatter import FrontmatterCheck
+from irminsul.checks.globs import GlobsCheck
+from irminsul.checks.links import LinksCheck
+from irminsul.checks.schema_leak import SchemaLeakCheck
+from irminsul.checks.uniqueness import UniquenessCheck
+
+HARD_REGISTRY: dict[str, type[Check]] = {
+    FrontmatterCheck.name: FrontmatterCheck,
+    GlobsCheck.name: GlobsCheck,
+    UniquenessCheck.name: UniquenessCheck,
+    LinksCheck.name: LinksCheck,
+    SchemaLeakCheck.name: SchemaLeakCheck,
+}
+
+__all__ = [
+    "HARD_REGISTRY",
+    "Check",
+    "Finding",
+    "Severity",
+    "sort_findings",
+    "summarize",
+]

irminsul/checks/base.py

@@ -0,0 +1,61 @@
+"""Check protocol, finding model, and reporting helpers.
+
+Every check ingests a `DocGraph` and returns a list of `Finding`s. The CLI
+prints them and uses their severity to decide the exit code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import ClassVar, Protocol, runtime_checkable
+
+from irminsul.docgraph import DocGraph
+
+
+class Severity(StrEnum):
+    error = "error"
+    warning = "warning"
+    info = "info"
+
+
+_SEVERITY_ORDER = {Severity.error: 0, Severity.warning: 1, Severity.info: 2}
+
+
+@dataclass(frozen=True)
+class Finding:
+    check: str
+    severity: Severity
+    message: str
+    path: Path | None = None
+    doc_id: str | None = None
+    line: int | None = None
+
+
+@runtime_checkable
+class Check(Protocol):
+    name: ClassVar[str]
+    default_severity: ClassVar[Severity]
+
+    def run(self, graph: DocGraph) -> list[Finding]: ...
+
+
+def sort_findings(findings: list[Finding]) -> list[Finding]:
+    """Errors first, then warnings, then info; stable on (path, line, check)."""
+    return sorted(
+        findings,
+        key=lambda f: (
+            _SEVERITY_ORDER[f.severity],
+            str(f.path) if f.path else "",
+            f.line if f.line is not None else -1,
+            f.check,
+        ),
+    )
+
+
+def summarize(findings: list[Finding]) -> dict[Severity, int]:
+    counts = {s: 0 for s in Severity}
+    for f in findings:
+        counts[f.severity] += 1
+    return counts

irminsul/checks/frontmatter.py

@@ -0,0 +1,66 @@
+"""FrontmatterCheck — required fields, enums, ID/filename agreement."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from irminsul.checks.base import Finding, Severity
+from irminsul.docgraph import DocGraph
+from irminsul.frontmatter import expected_id_for
+
+
+class FrontmatterCheck:
+    name: ClassVar[str] = "frontmatter"
+    default_severity: ClassVar[Severity] = Severity.error
+
+    def run(self, graph: DocGraph) -> list[Finding]:
+        out: list[Finding] = []
+
+        for failure in graph.parse_failures:
+            out.append(
+                Finding(
+                    check=self.name,
+                    severity=Severity.error,
+                    message=f"frontmatter parse error: {failure.error}",
+                    path=failure.path,
+                )
+            )
+
+        for path in graph.missing_frontmatter:
+            out.append(
+                Finding(
+                    check=self.name,
+                    severity=Severity.error,
+                    message="missing frontmatter (required for every doc atom)",
+                    path=path,
+                )
+            )
+
+        for node in graph.nodes.values():
+            expected = expected_id_for(node.path)
+            if node.frontmatter.id != expected:
+                out.append(
+                    Finding(
+                        check=self.name,
+                        severity=Severity.error,
+                        message=(
+                            f"id '{node.frontmatter.id}' does not match filename "
+                            f"(expected '{expected}')"
+                        ),
+                        path=node.path,
+                        doc_id=node.frontmatter.id,
+                    )
+                )
+
+        for dup_id, first_path, conflicting_path in graph.duplicate_ids:
+            out.append(
+                Finding(
+                    check=self.name,
+                    severity=Severity.error,
+                    message=(f"duplicate id '{dup_id}' (also defined at {first_path})"),
+                    path=conflicting_path,
+                    doc_id=dup_id,
+                )
+            )
+
+        return out

irminsul/checks/globs.py

@@ -0,0 +1,76 @@
+"""GlobsCheck — every `describes` pattern must resolve to ≥1 source file."""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+from typing import ClassVar
+
+from pathspec import GitIgnoreSpec
+
+from irminsul.checks.base import Finding, Severity
+from irminsul.docgraph import DocGraph
+
+
+def walk_source_files(repo_root: Path, source_roots: list[str]) -> tuple[list[str], list[str]]:
+    """Return (relative_posix_paths, missing_roots).
+
+    Walks every file under each existing source root. Skips dot-directories
+    (`.git`, `.venv`, `.mypy_cache`, ...) so we don't drag environment cruft
+    into the source set. A missing root isn't fatal here — surfaced separately
+    so the caller can warn rather than error.
+    """
+    files: list[str] = []
+    missing: list[str] = []
+    for root in source_roots:
+        abs_root = (repo_root / root).resolve()
+        if not abs_root.exists():
+            missing.append(root)
+            continue
+        for path in abs_root.rglob("*"):
+            if not path.is_file():
+                continue
+            if any(part.startswith(".") for part in path.relative_to(repo_root).parts):
+                continue
+            rel = PurePosixPath(*path.relative_to(repo_root).parts)
+            files.append(str(rel))
+    return files, missing
+
+
+class GlobsCheck:
+    name: ClassVar[str] = "globs"
+    default_severity: ClassVar[Severity] = Severity.error
+
+    def run(self, graph: DocGraph) -> list[Finding]:
+        if graph.config is None or graph.repo_root is None:
+            return []
+
+        source_files, missing_roots = walk_source_files(
+            graph.repo_root, graph.config.paths.source_roots
+        )
+
+        out: list[Finding] = []
+
+        for root in missing_roots:
+            out.append(
+                Finding(
+                    check=self.name,
+                    severity=Severity.warning,
+                    message=f"source root '{root}' does not exist",
+                )
+            )
+
+        for node in graph.nodes.values():
+            for pattern in node.frontmatter.describes:
+                spec = GitIgnoreSpec.from_lines([pattern])
+                if not any(spec.match_file(f) for f in source_files):
+                    out.append(
+                        Finding(
+                            check=self.name,
+                            severity=Severity.error,
+                            message=(f"describes pattern '{pattern}' matched zero files"),
+                            path=node.path,
+                            doc_id=node.id,
+                        )
+                    )
+
+        return out

irminsul/checks/links.py

@@ -0,0 +1,100 @@
+"""LinksCheck — internal markdown link integrity.
+
+Walks each doc body via markdown-it and verifies every relative link target
+resolves to an existing file inside the repo. External URLs (`http`/`https`/
+`mailto`/`tel`) and same-doc anchor links (`#heading`) are skipped — same-doc
+anchor validation and external link checking land in Sprint 2.
+"""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+from typing import ClassVar
+from urllib.parse import urlparse
+
+from markdown_it import MarkdownIt
+
+from irminsul.checks.base import Finding, Severity
+from irminsul.docgraph import DocGraph, DocNode
+
+_SKIP_SCHEMES = {"http", "https", "mailto", "tel", "ftp", "ftps", "data"}
+
+
+def _is_external_or_anchor(href: str) -> bool:
+    if not href:
+        return True
+    if href.startswith("#"):
+        return True
+    parsed = urlparse(href)
+    return parsed.scheme.lower() in _SKIP_SCHEMES
+
+
+def _extract_link_hrefs(body: str, md: MarkdownIt) -> list[str]:
+    """Return every href attribute on a link_open token in the doc body."""
+    hrefs: list[str] = []
+    tokens = md.parse(body)
+    for token in tokens:
+        if token.type == "inline" and token.children:
+            for child in token.children:
+                if child.type == "link_open":
+                    href = child.attrGet("href")
+                    if isinstance(href, str):
+                        hrefs.append(href)
+    return hrefs
+
+
+def _resolve_target(doc: DocNode, href: str, repo_root: PurePosixPath) -> PurePosixPath:
+    """Resolve a relative link's target to a repo-relative POSIX path.
+
+    Strips the trailing `#anchor`, treats the href as relative to the doc's
+    parent directory, and joins onto `repo_root` to canonicalize.
+    """
+    target = href.split("#", 1)[0]
+    doc_parent = PurePosixPath(doc.path.as_posix()).parent
+    # Posix-normalize by going through parts; PurePosixPath handles "../".
+    raw = doc_parent / target
+    # PurePosixPath has no resolve(); collapse .. manually.
+    parts: list[str] = []
+    for part in raw.parts:
+        if part == "..":
+            if parts:
+                parts.pop()
+        elif part != ".":
+            parts.append(part)
+    return PurePosixPath(*parts)
+
+
+class LinksCheck:
+    name: ClassVar[str] = "links"
+    default_severity: ClassVar[Severity] = Severity.error
+
+    def __init__(self) -> None:
+        self._md = MarkdownIt("commonmark")
+
+    def run(self, graph: DocGraph) -> list[Finding]:
+        if graph.repo_root is None:
+            return []
+
+        repo_root_posix = PurePosixPath(*graph.repo_root.resolve().parts)
+        out: list[Finding] = []
+
+        for node in graph.nodes.values():
+            for href in _extract_link_hrefs(node.body, self._md):
+                if _is_external_or_anchor(href):
+                    continue
+
+                target_rel = _resolve_target(node, href, repo_root_posix)
+                target_abs = graph.repo_root / target_rel
+
+                if not target_abs.exists():
+                    out.append(
+                        Finding(
+                            check=self.name,
+                            severity=Severity.error,
+                            message=f"broken link: '{href}' (resolved to '{target_rel}')",
+                            path=node.path,
+                            doc_id=node.id,
+                        )
+                    )
+
+        return out

irminsul/checks/schema_leak.py

@@ -0,0 +1,98 @@
+"""SchemaLeakCheck — type/schema definitions don't belong in narrative docs.
+
+Scans every doc inside the protected glob (`docs/20-components/**/*.md` for
+v0.1.0; configurable later) line-by-line against the active language profiles'
+patterns. Tracks fenced-code-block state so a snippet labelled ```toml or
+```text doesn't trigger findings just because it contains the word "class".
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from typing import ClassVar
+
+from pathspec import GitIgnoreSpec
+
+from irminsul.checks.base import Finding, Severity
+from irminsul.docgraph import DocGraph
+from irminsul.languages import LANGUAGE_REGISTRY, LanguageProfile
+
+# Hardcoded for v0.1.0; expose via config in Sprint 2.
+_PROTECTED_GLOB = GitIgnoreSpec.from_lines(["docs/20-components/**/*.md"])
+
+# Languages whose code-blocks should be scanned for schema leaks. A markdown
+# fence labelled with one of these names is treated as scannable; anything else
+# (toml, json, text, yaml, …) is exempt.
+_SCANNABLE_FENCE_LANGS = {"", "python", "py", "sql", "ts", "typescript", "tsx", "javascript", "js"}
+
+_FENCE_RE = re.compile(r"^\s*```(\S*)\s*$")
+
+
+def _truncate_pattern(pattern: re.Pattern[str], limit: int = 60) -> str:
+    src = pattern.pattern
+    return src if len(src) <= limit else src[: limit - 1] + "…"
+
+
+def _active_profiles(enabled: Sequence[str]) -> list[LanguageProfile]:
+    return [LANGUAGE_REGISTRY[name] for name in enabled if name in LANGUAGE_REGISTRY]
+
+
+class SchemaLeakCheck:
+    name: ClassVar[str] = "schema-leak"
+    default_severity: ClassVar[Severity] = Severity.error
+
+    def run(self, graph: DocGraph) -> list[Finding]:
+        if graph.config is None:
+            return []
+
+        profiles = _active_profiles(graph.config.languages.enabled)
+        if not profiles:
+            return []
+
+        out: list[Finding] = []
+
+        for node in graph.nodes.values():
+            if not _PROTECTED_GLOB.match_file(node.path.as_posix()):
+                continue
+
+            in_fence = False
+            fence_scannable = True
+            for lineno, line in enumerate(node.body.splitlines(), start=1):
+                fence_match = _FENCE_RE.match(line)
+                if fence_match:
+                    if in_fence:
+                        in_fence = False
+                        fence_scannable = True
+                    else:
+                        in_fence = True
+                        lang = fence_match.group(1).lower()
+                        fence_scannable = lang in _SCANNABLE_FENCE_LANGS
+                    continue
+
+                if in_fence and not fence_scannable:
+                    continue
+
+                for profile in profiles:
+                    for pattern in profile.schema_leak_patterns:
+                        if pattern.search(line):
+                            out.append(
+                                Finding(
+                                    check=self.name,
+                                    severity=Severity.error,
+                                    message=(
+                                        f"schema-leak: line matches "
+                                        f"{profile.name}:/{_truncate_pattern(pattern)}/ -- "
+                                        "type/schema definitions belong in 40-reference/"
+                                    ),
+                                    path=node.path,
+                                    doc_id=node.id,
+                                    line=lineno,
+                                )
+                            )
+                            break  # one finding per (line, profile)
+                    else:
+                        continue
+                    break
+
+        return out

irminsul/checks/uniqueness.py

@@ -0,0 +1,146 @@
+"""UniquenessCheck — every source file is claimed by exactly one most-specific doc.
+
+Implements Part VI ("Hierarchical Describes") of `Irminsul-reference.md`. Two
+docs claiming the same files at the same specificity is an error (silent
+duplication). A source file in a covered directory that no doc claims is a
+warning (silent omission). A child doc claiming a narrower glob wins over a
+parent's broader claim — that's the most-specific-match rule, and it's what
+lets `planner/INDEX.md` say `describes: [app/planner/**]` while
+`planner/routing.md` adds `describes: [app/planner/routing/*.py]` without
+either docking the other.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+from pathlib import Path
+from typing import ClassVar
+
+from pathspec import GitIgnoreSpec
+
+from irminsul.checks.base import Finding, Severity
+from irminsul.checks.globs import walk_source_files
+from irminsul.docgraph import DocGraph, DocNode
+
+# Files that are usually noise from a doc-coverage standpoint. Keeping the
+# omission warning quiet here trades a tiny risk of missing a legit doc gap
+# against the much larger annoyance of warning on every `__init__.py`.
+_OMISSION_SKIP = GitIgnoreSpec.from_lines(
+    [
+        "__init__.py",
+        "__main__.py",
+        "conftest.py",
+        "*.pyi",
+        "test_*.py",
+        "*_test.py",
+        "*.test.ts",
+        "*.spec.ts",
+        "*.test.tsx",
+        "*.spec.tsx",
+        "*.d.ts",
+    ]
+)
+
+
+def specificity(pattern: str) -> tuple[int, int, int]:
+    """Higher tuple = more specific. Compared lexicographically.
+
+    Components:
+    - count of literal (no-wildcard) path segments — exact paths beat globs
+    - total path depth — deeper claims beat shallower
+    - negated wildcard-character count — fewer wildcards beats more
+    """
+    parts = pattern.split("/")
+    literal_segments = sum(1 for p in parts if "*" not in p and "?" not in p)
+    depth = len(parts)
+    wildcard_chars = sum(p.count("*") + p.count("?") for p in parts)
+    return (literal_segments, depth, -wildcard_chars)
+
+
+class UniquenessCheck:
+    name: ClassVar[str] = "uniqueness"
+    default_severity: ClassVar[Severity] = Severity.error
+
+    def run(self, graph: DocGraph) -> list[Finding]:
+        if graph.config is None or graph.repo_root is None:
+            return []
+
+        source_files, _missing = walk_source_files(graph.repo_root, graph.config.paths.source_roots)
+
+        # claims_by_file: source file -> list of (DocNode, pattern, score).
+        claims_by_file: dict[str, list[tuple[DocNode, str, tuple[int, int, int]]]] = defaultdict(
+            list
+        )
+
+        for node in graph.nodes.values():
+            for pattern in node.frontmatter.describes:
+                spec = GitIgnoreSpec.from_lines([pattern])
+                score = specificity(pattern)
+                for source_file in source_files:
+                    if spec.match_file(source_file):
+                        claims_by_file[source_file].append((node, pattern, score))
+
+        out: list[Finding] = []
+
+        # Tie at most-specific level → silent duplication, error.
+        for source_file, claims in claims_by_file.items():
+            top_score = max(c[2] for c in claims)
+            top_claims = [c for c in claims if c[2] == top_score]
+            if len(top_claims) > 1:
+                claim_descs = ", ".join(
+                    f"{node.path.as_posix()} (`{pattern}`)" for node, pattern, _ in top_claims
+                )
+                out.append(
+                    Finding(
+                        check=self.name,
+                        severity=Severity.error,
+                        message=(
+                            f"source file '{source_file}' is claimed at the same "
+                            f"specificity by: {claim_descs}"
+                        ),
+                    )
+                )
+
+        # Covered directories: parents of every claimed file.
+        covered_dirs = _covered_dirs(claims_by_file.keys())
+
+        # Omission: a file under a covered directory that no doc claims.
+        for source_file in source_files:
+            if source_file in claims_by_file:
+                continue
+            if not _is_in_covered_dir(source_file, covered_dirs):
+                continue
+            if _OMISSION_SKIP.match_file(source_file):
+                continue
+            out.append(
+                Finding(
+                    check=self.name,
+                    severity=Severity.warning,
+                    message=(
+                        f"source file '{source_file}' lives in a doc-covered "
+                        "directory but no doc claims it"
+                    ),
+                )
+            )
+
+        return out
+
+
+def _covered_dirs(claimed_files: Iterable[str]) -> set[str]:
+    """Every directory that has at least one claimed file under it (at any
+    depth)."""
+    dirs: set[str] = set()
+    for f in claimed_files:
+        parent = str(Path(f).parent.as_posix())
+        while parent and parent != ".":
+            dirs.add(parent)
+            parent = str(Path(parent).parent.as_posix())
+            if parent == ".":
+                break
+    return dirs
+
+
+def _is_in_covered_dir(source_file: str, covered: set[str]) -> bool:
+    parent = str(Path(source_file).parent.as_posix())
+    return parent in covered