Add literalinclude line number checker/fixer tool

py/README.md

@@ -29,6 +29,7 @@ These packages are specific to Envoy or work to Envoy's specific requirements:
 - [envoy.distribution.repo](envoy.distribution.repo) - Repository management
 - [envoy.distribution.verify](envoy.distribution.verify) - Distribution verification
 - [envoy.docker.utils](envoy.docker.utils) - Docker utilities
+- [envoy.docs.literalinclude](envoy.docs.literalinclude) - Tool to check and fix literalinclude line numbers in RST documentation
 - [envoy.docs.sphinx_runner](envoy.docs.sphinx_runner) - Sphinx documentation runner
 - [envoy.github.abstract](envoy.github.abstract) - GitHub abstractions
 - [envoy.github.release](envoy.github.release) - GitHub release management

py/envoy.docs.literalinclude/BUILD

@@ -0,0 +1 @@
+toolshed_package("envoy.docs.literalinclude")

py/envoy.docs.literalinclude/README.rst

@@ -0,0 +1,103 @@
+Literalinclude Line Number Checker
+===================================
+
+A tool to automatically detect and fix outdated line numbers in Sphinx ``literalinclude`` directives.
+
+Problem
+-------
+
+When using ``literalinclude`` directives in Sphinx documentation, you often specify line numbers to include specific portions of code:
+
+.. code-block:: rst
+
+   .. literalinclude:: /path/to/config.yaml
+      :lines: 10-25
+      :emphasize-lines: 15-18
+
+However, when the source files change (lines are added or removed), these line numbers become outdated, potentially showing the wrong code or breaking the documentation build.
+
+Solution
+--------
+
+This tool:
+
+1. Scans RST files for ``literalinclude`` directives with line specifications
+2. Uses git history to detect when source files changed after the RST files
+3. Identifies directives where line changes affect the specified range
+4. Optionally fixes the line numbers automatically
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install envoy.docs.literalinclude
+
+Usage
+-----
+
+Check for outdated directives (dry run):
+
+.. code-block:: bash
+
+   literalinclude-check /path/to/repo
+
+Check specific directories:
+
+.. code-block:: bash
+
+   literalinclude-check /path/to/repo --dirs docs api
+
+Fix outdated directives:
+
+.. code-block:: bash
+
+   literalinclude-check /path/to/repo --fix
+
+List all literalinclude directives:
+
+.. code-block:: bash
+
+   literalinclude-check /path/to/repo --list
+
+JSON output:
+
+.. code-block:: bash
+
+   literalinclude-check /path/to/repo --json
+
+How It Works
+------------
+
+1. **Discovery**: Finds all RST files in specified directories (default: ``docs`` and ``api``)
+2. **Parsing**: Extracts ``literalinclude`` directives with their options:
+
+   - ``:lines:`` - Line ranges to include
+   - ``:emphasize-lines:`` - Lines to emphasize
+   - Source file path
+
+3. **Git Analysis**: For each directive:
+
+   - Checks when the RST file was last modified
+   - Checks when the source file was last modified
+   - If source changed after RST, analyzes the diff
+
+4. **Detection**: Flags directives as outdated if:
+
+   - Lines were added/removed in the source file
+   - Changes occurred at or before the maximum line number referenced
+
+5. **Fixing**: Updates the line numbers in RST files to match current source
+
+Limitations
+-----------
+
+- Requires a git repository
+- Best-effort fixing - may not always determine correct new line numbers
+- Currently focused on ``:lines:`` and ``:emphasize-lines:`` options
+- Does not handle ``:start-after:`` and ``:end-before:`` markers yet
+
+License
+-------
+
+Apache License 2.0

py/envoy.docs.literalinclude/VERSION

@@ -0,0 +1 @@
+0.1.0

py/envoy.docs.literalinclude/envoy/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

py/envoy.docs.literalinclude/envoy/docs/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

py/envoy.docs.literalinclude/envoy/docs/literalinclude/BUILD

@@ -0,0 +1,14 @@
+toolshed_library(
+    "envoy.docs.literalinclude",
+    sources=[
+        "__init__.py",
+        "checker.py",
+        "cmd.py",
+        "fixer.py",
+    ],
+)
+
+file(
+    name="py_typed",
+    source="py.typed",
+)

py/envoy.docs.literalinclude/envoy/docs/literalinclude/__init__.py

@@ -0,0 +1,18 @@
+"""Literalinclude line number checker and fixer.
+
+This module provides tools to:
+1. Find literalinclude directives in RST files
+2. Check if source files have changed since RST files
+3. Detect outdated line number specifications
+4. Fix the line numbers automatically
+"""
+
+from .checker import LiteralIncludeChecker, LiteralIncludeDirective
+from .fixer import LiteralIncludeFixer
+
+
+__all__ = (
+    "LiteralIncludeChecker",
+    "LiteralIncludeDirective",
+    "LiteralIncludeFixer",
+)