linnl 0.1.0__py3-none-any.whl

linnl/__init__.py

@@ -0,0 +1 @@
+"""Lint prose against style rules, with an LLM judging."""

linnl/agents.py

@@ -0,0 +1,60 @@
+"""Install linnl commands for supported coding agents."""
+
+import logging
+from enum import StrEnum
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class Agent(StrEnum):
+    """Select the model backend for model-judged rules."""
+
+    CLAUDE = "claude"
+    CODEX = "codex"
+
+
+DEFAULT_AGENT_MODELS: dict[Agent, str] = {
+    Agent.CLAUDE: "claude-opus-5",
+    Agent.CODEX: "gpt-5.6-luna",
+}
+
+
+LINNL_COMMAND = """---
+description: Check your most recent response with linnl.
+---
+
+Check your most recent assistant response with linnl.
+
+Extract only the user-facing text from your immediately preceding response.
+Do not include tool calls, this command, or your current reasoning. Pipe that
+text to `linnl lint` through standard input and report the result.
+
+If linnl reports violations, explain them and provide a corrected version. If it
+reports no violations, say that the response is clean.
+"""
+
+AGENT_COMMAND_DIRECTORIES: dict[Agent, tuple[str, str]] = {
+    Agent.CLAUDE: (".claude", "commands"),
+    Agent.CODEX: (".codex", "prompts"),
+}
+
+
+def install_hook(agent: Agent, *, local: bool) -> Path:
+    """Install the linnl command for an agent and return its path."""
+    agent_directory, command_directory = AGENT_COMMAND_DIRECTORIES[agent]
+    base_directory = Path.cwd() if local else Path.home()
+    command_path = base_directory / agent_directory / command_directory / "linnl.md"
+    command_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if command_path.exists():
+        existing_command = command_path.read_text(encoding="utf-8")
+        if existing_command != LINNL_COMMAND:
+            logger.info("linnl command out of date, will update at %s", command_path)
+        else:
+            logger.info("linnl command already installed at %s", command_path)
+            return command_path
+
+    command_path.write_text(LINNL_COMMAND, encoding="utf-8")
+    logger.info("Installed linnl command at %s", command_path)
+    return command_path

linnl/cli.py

@@ -0,0 +1,215 @@
+"""Parse the command line and run the linter."""
+
+import pathlib as pl
+import sys
+from typing import Annotated
+
+import typer
+
+from linnl.agents import Agent
+from linnl.agents import install_hook as install_agent_hook
+from linnl.config import SHIPPED_CONFIG_FILE, discover_config_file
+from linnl.linter import Linter
+from linnl.logconfig import (
+    DEFAULT_PRETTY,
+    DEFAULT_STRUCTURED,
+    DEFAULT_VERBOSE,
+    config_logging,
+)
+
+app = typer.Typer(
+    add_completion=True,
+    pretty_exceptions_show_locals=False,
+    pretty_exceptions_short=True,
+    pretty_exceptions_enable=False,
+)
+
+
+PathsArgument = Annotated[
+    list[pl.Path] | None,
+    typer.Argument(
+        help="Files or directories to lint. Reads stdin when none are given."
+    ),
+]
+ConfigOption = Annotated[
+    pl.Path | None,
+    typer.Option(
+        help="Config file. Discovered from the working directory when not given."
+    ),
+]
+SelectOption = Annotated[
+    list[str] | None,
+    typer.Option(
+        help="Enable exactly these rules or prefixes, replacing the config's selection."
+    ),
+]
+ExtendSelectOption = Annotated[
+    list[str] | None,
+    typer.Option(help="Enable these rules or prefixes on top of the selection."),
+]
+IgnoreOption = Annotated[
+    list[str] | None,
+    typer.Option(help="Disable these rules or prefixes."),
+]
+ModelOption = Annotated[
+    str | None, typer.Option(help="Model alias or id the judge calls.")
+]
+AgentOption = Annotated[
+    Agent | None, typer.Option(help="Model agent to use for model-judged rules.")
+]
+MaxConcurrencyOption = Annotated[
+    int | None,
+    typer.Option(min=1, help="How many documents are linted concurrently."),
+]
+IncludeExtensionOption = Annotated[
+    list[str] | None,
+    typer.Option(
+        "--include-extension",
+        help="Extensions linted when a directory is given, replacing the config's.",
+    ),
+]
+IgnoreCodeBlocksOption = Annotated[
+    bool | None,
+    typer.Option(
+        "--ignore-code-blocks/--lint-code-blocks",
+        help="Ignore Markdown and reStructuredText code blocks.",
+    ),
+]
+
+
+@app.callback()
+def main(
+    verbose: int = typer.Option(
+        DEFAULT_VERBOSE,
+        "--verbose",
+        "-v",
+        count=True,
+        help="Verbosity level. Pass more than once for more logging.",
+    ),
+    pretty: bool = typer.Option(
+        DEFAULT_PRETTY,
+        "--pretty",
+        help="Pretty-print logs with colors.",
+    ),
+    structured: bool = typer.Option(
+        DEFAULT_STRUCTURED,
+        "--structured/--unstructured",
+        "-s/-u",
+        help="Output structured (JSON) logs.",
+    ),
+) -> None:
+    """linnl, a prose linter."""
+    config_logging(verbose=verbose, pretty=pretty, structured=structured)
+
+
+@app.command()
+def lint(
+    paths: PathsArgument = None,
+    config_file: ConfigOption = None,
+    select: SelectOption = None,
+    extend_select: ExtendSelectOption = None,
+    ignore: IgnoreOption = None,
+    model: ModelOption = None,
+    agent: AgentOption = None,
+    max_concurrency: MaxConcurrencyOption = None,
+    include_extensions: IncludeExtensionOption = None,
+    ignore_code_blocks: IgnoreCodeBlocksOption = None,
+) -> None:
+    """Lint files and print the violations. Exits with 1 when any is reported."""
+    try:
+        if config_file is None:
+            config_file = discover_config_file(pl.Path.cwd())
+
+        linter = Linter.from_config(
+            config_file,
+            select=select,
+            extend_select=extend_select,
+            ignore=ignore,
+            model=model,
+            agent=agent,
+            max_concurrency=max_concurrency,
+            include_extensions=include_extensions,
+            ignore_code_blocks=ignore_code_blocks,
+        )
+
+        if paths is None:
+            if sys.stdin.isatty():
+                raise typer.BadParameter("no paths given and nothing piped to stdin")
+
+            violations = linter.lint_text(sys.stdin.read())
+        else:
+            violations = linter.lint_paths(paths)
+    except ExceptionGroup as error:
+        typer.echo(f"Error: {error.exceptions[0]}", err=True)
+        raise typer.Exit(code=2) from None
+    except (OSError, RuntimeError, TypeError, ValueError, typer.BadParameter) as error:
+        typer.echo(f"Error: {error}", err=True)
+        raise typer.Exit(code=2) from None
+
+    if len(violations) == 0:
+        print("No violations found.")
+        return
+
+    print(violations)
+
+    file_count = len(set(v.path for v in violations))
+    file_label = "file" if file_count == 1 else "files"
+    print(f"Found {len(violations)} violations across {file_count} {file_label}.")
+
+    raise typer.Exit(code=1)
+
+
+@app.command(name="rules")
+def list_rules(
+    config_file: ConfigOption = None,
+    select: SelectOption = None,
+    extend_select: ExtendSelectOption = None,
+    ignore: IgnoreOption = None,
+) -> None:
+    """Print the rule book with each rule's on/off state and who checks it."""
+    if config_file is None:
+        config_file = discover_config_file(pl.Path.cwd())
+
+    linter = Linter.from_config(
+        config_file,
+        select=select,
+        extend_select=extend_select,
+        ignore=ignore,
+    )
+
+    print(linter.rules)
+
+
+@app.command(name="config")
+def print_shipped_config() -> None:
+    """Print the shipped config, to copy and edit: linnl config > linnl.toml."""
+    print(SHIPPED_CONFIG_FILE.read_text(encoding="utf-8"), end="")
+
+
+@app.command(name="plugins")
+def list_plugins(config_file: ConfigOption = None) -> None:
+    """List the rule packages enabled by the active configuration."""
+    if config_file is None:
+        config_file = discover_config_file(pl.Path.cwd())
+
+    linter = Linter.from_config(config_file)
+
+    if len(linter.config.plugins) == 0:
+        print("No linnl plugins enabled.")
+        return
+
+    print(linter.config.plugins)
+
+
+@app.command()
+def install_hook(
+    agent: Agent,
+    local: bool = typer.Option(
+        False,
+        "--local/--global",
+        help="Install in the current project or in your home directory.",
+    ),
+) -> None:
+    """Install linnl as hook for your coding agent."""
+    command_path = install_agent_hook(agent, local=local)
+    typer.echo(f"Installed linnl command at {command_path}")

linnl/config.py

@@ -0,0 +1,85 @@
+"""Configuration for the linter."""
+
+import logging
+import os
+import tomllib
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+LINNL_CONFIG_FILE_NAME = "linnl.toml"
+PYPROJECT_FILE_NAME = "pyproject.toml"
+SHIPPED_CONFIG_FILE = Path(
+    str(resources.files("linnl").joinpath("resources", "config.toml"))
+)
+
+
+def locate_user_config_file() -> Path:
+    """Return the user config path under $XDG_CONFIG_HOME, or ~/.config when unset."""
+    base = os.environ.get("XDG_CONFIG_HOME", "")
+    if base == "":
+        return Path.home() / ".config" / "linnl" / "config.toml"
+
+    return Path(base) / "linnl" / "config.toml"
+
+
+def has_linnl_section(pyproject: Path) -> bool:
+    with pyproject.open("rb") as handle:
+        return "linnl" in tomllib.load(handle).get("tool", {})
+
+
+def discover_config_file(start: Path) -> Path:
+    """Find the config file to be used, starting at a given directory.
+
+    Walking upward, a pyproject.toml with a [tool.linnl] table wins over an
+    linnl.toml in the same directory. Below both comes the user config, and
+    below that the shipped config.
+    """
+    for directory in (start, *start.parents):
+        pyproject = directory / PYPROJECT_FILE_NAME
+        linnl_config = directory / LINNL_CONFIG_FILE_NAME
+        pyproject_applies = pyproject.is_file() and has_linnl_section(pyproject)
+
+        if pyproject_applies and linnl_config.is_file():
+            logger.warning(
+                "%s: both %s and %s configure linnl, using %s",
+                directory,
+                pyproject.name,
+                linnl_config.name,
+                pyproject.name,
+            )
+
+        if pyproject_applies:
+            logger.info("Using pyproject.toml at %s", pyproject)
+            return pyproject
+
+        if linnl_config.is_file():
+            logger.info("Using linnl.toml at %s", linnl_config)
+            return linnl_config
+
+    user_file = locate_user_config_file()
+    if user_file.is_file():
+        logger.info("Using user config at %s", user_file)
+        return user_file
+
+    logger.info("Using default config at %s", SHIPPED_CONFIG_FILE)
+    return SHIPPED_CONFIG_FILE
+
+
+def read_config_file(path: Path) -> dict[str, Any]:
+    """Parse the config file, unwrapping [tool.linnl] for pyproject.toml."""
+    with path.open("rb") as handle:
+        data = tomllib.load(handle)
+
+    logger.info("Settings loaded from %s", path)
+
+    if path.name != PYPROJECT_FILE_NAME:
+        return data
+
+    section = data.get("tool", {}).get("linnl")
+    if not isinstance(section, dict):
+        raise ValueError(f"{path}: no [tool.linnl] table")
+
+    return section

linnl/constants.py

@@ -0,0 +1,5 @@
+"""linnl constants."""
+
+from typing import Final
+
+DEFAULT_IGNORE_CODE_BLOCKS: Final[bool] = True

linnl/document.py

@@ -0,0 +1,138 @@
+from pathlib import Path
+
+from docutils import nodes
+from docutils.core import publish_doctree
+from markdown_it import MarkdownIt
+
+from linnl.constants import DEFAULT_IGNORE_CODE_BLOCKS
+
+MARKDOWN_PARSER = MarkdownIt("commonmark")
+
+
+class Document:
+    def __init__(
+        self,
+        path: Path | None = None,
+        prose: str | None = None,
+        ignore_code_blocks: bool = DEFAULT_IGNORE_CODE_BLOCKS,
+    ):
+        if prose is None:
+            if path is None:
+                raise ValueError("Either 'prose' or 'path' must be provided.")
+
+            prose = path.read_text(encoding="utf-8")
+
+        self.ignore_code_blocks = ignore_code_blocks
+        self._prose = prose
+        self.path = path
+
+    @property
+    def prose(self) -> str:
+        if self.ignore_code_blocks:
+            return self._omit_code_blocks()
+        return self._prose
+
+    @property
+    def lines(self) -> list[str]:
+        return self.prose.split("\n")
+
+    def _omit_code_blocks(self) -> str:
+        """Omit code content while preserving source line positions."""
+        if self.path is None:
+            return self._prose
+
+        if self.path.suffix.lower() == ".md":
+            omitted_ranges = self._find_markdown_code_block_ranges()
+        elif self.path.suffix.lower() == ".rst":
+            omitted_ranges = self._find_rst_code_block_ranges()
+        else:
+            return self._prose
+
+        lines = self._prose.splitlines(keepends=True)
+        omitted_lines = [False] * len(lines)
+
+        for start_line, end_line in omitted_ranges:
+            for line_index in range(start_line, end_line):
+                omitted_lines[line_index] = True
+
+        return "".join(
+            self._extract_line_ending(line) if omitted else line
+            for line, omitted in zip(lines, omitted_lines, strict=True)
+        )
+
+    def _find_markdown_code_block_ranges(self) -> list[tuple[int, int]]:
+        """Find source ranges for Markdown code blocks."""
+        ranges = []
+
+        for token in MARKDOWN_PARSER.parse(self._prose):
+            if token.type in {"code_block", "fence"} and token.map is not None:
+                ranges.append((token.map[0], token.map[1]))
+
+        return ranges
+
+    def _find_rst_code_block_ranges(self) -> list[tuple[int, int]]:
+        """Find source ranges for reStructuredText literal blocks."""
+        tree = publish_doctree(
+            self._prose,
+            settings_overrides={
+                "file_insertion_enabled": False,
+                "halt_level": 6,
+                "raw_enabled": False,
+                "report_level": 5,
+            },
+        )
+        ranges = []
+        source_offset = 0
+
+        for block in tree.findall(nodes.literal_block):
+            if isinstance(
+                block.parent, nodes.system_message
+            ) and not block.rawsource.lstrip().startswith(
+                (".. code::", ".. code-block::")
+            ):
+                continue
+
+            start_offset = self._find_source_offset_for_rst_block(
+                block.rawsource,
+                source_offset,
+                block.line,
+            )
+
+            start_line = self._prose.count("\n", 0, start_offset)
+            end_line = start_line + len(block.rawsource.splitlines())
+            ranges.append((start_line, end_line))
+            source_offset = start_offset + len(block.rawsource)
+
+        return ranges
+
+    def _find_source_offset_for_rst_block(
+        self,
+        rawsource: str,
+        source_offset: int,
+        reported_line: int | None,
+    ) -> int:
+        """Find the source offset for a reStructuredText literal block."""
+        offset = self._prose.find(rawsource, source_offset)
+
+        if offset == -1:
+            raise ValueError("Could not locate a reStructuredText code block.")
+
+        if reported_line is None:
+            return offset
+
+        expected_offset = offset
+
+        while offset != -1:
+            line_number = self._prose.count("\n", 0, offset) + 1
+
+            if line_number > reported_line:
+                break
+
+            expected_offset = offset
+            offset = self._prose.find(rawsource, offset + 1)
+
+        return expected_offset
+
+    @staticmethod
+    def _extract_line_ending(line: str) -> str:
+        return line[len(line.rstrip("\r\n")) :]