lyingdocs 0.1.0__py3-none-any.whl

lyingdocs/__init__.py

@@ -0,0 +1,3 @@
+"""LyingDocs: Documentation-Code Misalignment Detection."""
+
+__version__ = "0.1.0"

lyingdocs/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m lyingdocs"""
+
+from .cli import main
+
+main()

lyingdocs/agent.py

@@ -0,0 +1,352 @@
+"""DocentAgent: autonomous documentation-code misalignment detection agent."""
+
+import json
+import logging
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import asdict
+from pathlib import Path
+
+from .codex import find_codex_binary
+from .doctree import DocTree
+from .llm import call_llm, call_llm_with_tools, make_client
+from .tools import TOOL_SCHEMAS, ToolExecutor
+from .workspace import Workspace
+
+logger = logging.getLogger("lyingdocs")
+
+PROMPTS_DIR = Path(__file__).resolve().parent / "prompts"
+
+
+class DocentAgent:
+    """Autonomous agent that traverses documentation and dispatches code audits."""
+
+    def __init__(
+        self,
+        config: dict,
+        doc_path: Path,
+        code_path: Path,
+        output_dir: Path,
+    ):
+        self.config = config
+        self.doc_path = doc_path
+        self.code_path = code_path
+        self.output_dir = output_dir
+
+        self.client = make_client(config)
+        self.model = config["model"]
+        self.max_iterations = config.get("max_iterations", 50)
+        self.token_budget = config.get("token_budget", 524_288)
+
+        self.doctree = DocTree(doc_path)
+        self.workspace = Workspace(
+            output_dir, max_dispatches=config.get("max_dispatches", 20)
+        )
+
+        # Resolve codex binary once at startup
+        self.codex_bin = None
+        if config.get("codex_enabled", True):
+            self.codex_bin = find_codex_binary(config)
+            if self.codex_bin:
+                logger.info("Codex CLI found: %s", self.codex_bin)
+            else:
+                logger.warning(
+                    "Codex CLI not found. Code analysis dispatches will be unavailable. "
+                    "Install via: npm install -g @openai/codex"
+                )
+        else:
+            logger.info("Codex CLI disabled by configuration.")
+
+        self.tool_executor = ToolExecutor(
+            doc_root=doc_path,
+            code_path=code_path,
+            output_dir=output_dir,
+            workspace=self.workspace,
+            config=config,
+            codex_bin=self.codex_bin,
+        )
+
+        self.messages: list[dict] = []
+
+    def run(self) -> str:
+        """Execute the full agent loop. Returns the final report path."""
+        # Resume from checkpoint if requested
+        if self.config.get("resume"):
+            self.workspace.load_state()
+
+        # Build doc index
+        self.doctree.build_index()
+        self.doctree.save_index(self.output_dir)
+
+        # Seed conversation
+        system_prompt = self._load_prompt("agent_system.txt")
+        kickoff = self._build_kickoff_message()
+
+        self.messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": kickoff},
+        ]
+
+        logger.info("DocentAgent started — %d doc files indexed", len(self.doctree.files))
+
+        # Agent loop
+        iteration = 0
+        while iteration < self.max_iterations:
+            iteration += 1
+            logger.info("--- Agent iteration %d/%d ---", iteration, self.max_iterations)
+
+            # Call LLM with tools
+            response = call_llm_with_tools(
+                self.client, self.model, self.messages, TOOL_SCHEMAS
+            )
+
+            # Append assistant message
+            assistant_msg = self._response_to_message(response)
+            self.messages.append(assistant_msg)
+
+            # Handle tool calls (parallel when multiple)
+            if response.tool_calls:
+                parsed_calls = []
+                for tool_call in response.tool_calls:
+                    name = tool_call.function.name
+                    try:
+                        args = json.loads(tool_call.function.arguments)
+                    except json.JSONDecodeError:
+                        args = {}
+                    parsed_calls.append((tool_call, name, args))
+
+                if len(parsed_calls) == 1:
+                    # Single tool call — execute directly
+                    tc, name, args = parsed_calls[0]
+                    logger.info("  Tool call: %s(%s)", name, _truncate(str(args), 100))
+                    result = self.tool_executor.execute(name, args)
+                    logger.info("  Result: %s", _truncate(result, 200))
+                    self.messages.append({
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": result,
+                    })
+                else:
+                    # Multiple tool calls — execute in parallel
+                    def _exec(item):
+                        tc, name, args = item
+                        logger.info("  Tool call: %s(%s)", name, _truncate(str(args), 100))
+                        result = self.tool_executor.execute(name, args)
+                        logger.info("  Result: %s", _truncate(result, 200))
+                        return tc, result
+
+                    with ThreadPoolExecutor(max_workers=len(parsed_calls)) as pool:
+                        futures = {
+                            pool.submit(_exec, item): item[0].id
+                            for item in parsed_calls
+                        }
+                        results_map = {}
+                        for future in as_completed(futures):
+                            tc, result = future.result()
+                            results_map[tc.id] = result
+
+                    # Append results in original order to keep conversation deterministic
+                    for tc, _, _ in parsed_calls:
+                        self.messages.append({
+                            "role": "tool",
+                            "tool_call_id": tc.id,
+                            "content": results_map[tc.id],
+                        })
+
+                # Save state after each batch of tool calls
+                self.workspace.save_state()
+            else:
+                # Text-only response — agent is thinking or done
+                if response.content:
+                    logger.info("  Agent: %s", _truncate(response.content, 200))
+
+            # Check completion
+            if self.workspace.is_complete():
+                logger.info("Agent signaled completion.")
+                break
+
+            # Budget check
+            if self.workspace.is_budget_exhausted():
+                logger.warning("Codex dispatch budget exhausted — nudging agent to finalize.")
+                self.messages.append({
+                    "role": "user",
+                    "content": (
+                        "Your Codex dispatch budget is exhausted. Please call "
+                        "finalize_report now to generate the final report with "
+                        "the findings collected so far."
+                    ),
+                })
+
+            # Context management
+            if self._estimate_tokens() > self.token_budget:
+                self._compress_context()
+
+            # If no tool calls and not complete, nudge to continue
+            if not response.tool_calls and not self.workspace.is_complete():
+                self.messages.append({
+                    "role": "user",
+                    "content": "Continue with the audit. Use your tools to proceed.",
+                })
+        else:
+            logger.warning(
+                "Max iterations (%d) reached — auto-finalizing.", self.max_iterations
+            )
+
+        # Generate final report
+        report_path = self._generate_report()
+        self.workspace.save_state()
+
+        return str(report_path)
+
+    def _build_kickoff_message(self) -> str:
+        """Build the initial message with doc tree overview."""
+        overview = self.doctree.get_overview()
+        progress = ""
+        if self.workspace.findings or self.workspace.completed_sections:
+            progress = (
+                "\n\n## Resumed Session\n"
+                + self.workspace.get_progress_summary()
+            )
+
+        codex_status = (
+            f"Codex dispatches available: {self.workspace.dispatches_remaining()}"
+            if self.codex_bin
+            else "Codex CLI: NOT AVAILABLE — you must rely on documentation analysis only"
+        )
+
+        return (
+            f"## Documentation to Audit\n\n{overview}\n\n"
+            f"## Code Repository\nPath: {self.code_path}\n\n"
+            f"## Your Budget\n"
+            f"{codex_status}\n"
+            f"Max iterations: {self.max_iterations}\n"
+            f"{progress}\n\n"
+            "Begin your audit. Start by examining the high-priority documentation "
+            "files, then formulate targeted questions for Codex."
+        )
+
+    def _response_to_message(self, response) -> dict:
+        """Convert an OpenAI response message to a serializable dict."""
+        msg = {"role": "assistant"}
+        if response.content:
+            msg["content"] = response.content
+        if response.tool_calls:
+            msg["tool_calls"] = [
+                {
+                    "id": tc.id,
+                    "type": "function",
+                    "function": {
+                        "name": tc.function.name,
+                        "arguments": tc.function.arguments,
+                    },
+                }
+                for tc in response.tool_calls
+            ]
+        return msg
+
+    def _estimate_tokens(self) -> int:
+        """Rough token estimate: ~4 chars per token."""
+        total_chars = sum(
+            len(json.dumps(m)) for m in self.messages
+        )
+        return total_chars // 4
+
+    def _compress_context(self) -> None:
+        """Compress older messages to stay within token budget."""
+        logger.info("  Compressing context (estimated %d tokens)", self._estimate_tokens())
+
+        keep_recent = 8  # Keep last 4 exchanges
+        if len(self.messages) <= keep_recent + 1:
+            return  # Not enough to compress
+
+        # Extract messages to summarize (skip system prompt)
+        old_messages = self.messages[1:-keep_recent]
+        if not old_messages:
+            return
+
+        # Build a summary request
+        summary_input = []
+        for m in old_messages:
+            role = m.get("role", "unknown")
+            content = m.get("content", "")
+            if m.get("tool_calls"):
+                calls = [
+                    f'{tc["function"]["name"]}({_truncate(tc["function"]["arguments"], 80)})'
+                    for tc in m["tool_calls"]
+                ]
+                content = "Tool calls: " + ", ".join(calls)
+            if content:
+                summary_input.append(f"[{role}] {content}")
+
+        summary_text = "\n".join(summary_input)
+
+        summary = call_llm(
+            self.client,
+            self.model,
+            (
+                "Summarize the following agent conversation. Preserve ALL key findings, "
+                "decisions, audit results, and which doc sections have been examined. "
+                "Be concise but complete — this summary replaces the original messages."
+            ),
+            summary_text,
+        )
+
+        # Replace old messages with summary
+        self.messages = [
+            self.messages[0],  # system prompt
+            self.messages[1],  # kickoff message
+            {"role": "user", "content": f"[Context Summary from prior work]\n\n{summary}"},
+            *self.messages[-keep_recent:],
+        ]
+
+        logger.info(
+            "  Context compressed: now %d messages (~%d tokens)",
+            len(self.messages), self._estimate_tokens(),
+        )
+
+    def _generate_report(self) -> Path:
+        """Generate the final Misalignment_Report.md from collected findings."""
+        report_path = self.output_dir / "Misalignment_Report.md"
+
+        if not self.workspace.findings:
+            report = (
+                f"# Documentation-Code Misalignment Report: "
+                f"{self.doc_path.name}\n\n"
+                "## Executive Summary\n\n"
+                "No misalignment findings were detected during the audit. "
+                "The documentation appears to be well-aligned with the codebase.\n"
+            )
+            report_path.write_text(report, encoding="utf-8")
+            logger.info("No findings — wrote empty report to %s", report_path)
+            return report_path
+
+        # Use LLM to synthesize the report
+        synthesis_prompt = self._load_prompt("report_synthesis.txt")
+        findings_json = json.dumps(
+            [asdict(f) for f in self.workspace.findings], indent=2
+        )
+
+        user_content = (
+            f"Project: {self.doc_path.name}\n\n"
+            f"## Raw Findings ({len(self.workspace.findings)} total)\n\n"
+            f"```json\n{findings_json}\n```\n\n"
+            f"## Audit Coverage\n"
+            f"Sections audited: {len(self.workspace.completed_sections)}\n"
+            f"Codex dispatches used: {self.workspace.codex_dispatch_count}\n"
+        )
+
+        report = call_llm(
+            self.client, self.model, synthesis_prompt, user_content
+        )
+
+        report_path.write_text(report, encoding="utf-8")
+        logger.info("Final report written to %s (%d chars)", report_path, len(report))
+        return report_path
+
+    def _load_prompt(self, filename: str) -> str:
+        return (PROMPTS_DIR / filename).read_text(encoding="utf-8")
+
+
+def _truncate(text: str, max_len: int) -> str:
+    if len(text) <= max_len:
+        return text
+    return text[:max_len] + "... (truncated)"

lyingdocs/cli.py

@@ -0,0 +1,149 @@
+"""CLI entry point for LyingDocs."""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import DEFAULTS
+
+
+def setup_logging(output_dir: Path) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    logger = logging.getLogger("lyingdocs")
+    logger.setLevel(logging.INFO)
+
+    fmt = logging.Formatter(
+        "%(asctime)s [%(levelname)s] %(message)s", datefmt="%H:%M:%S"
+    )
+
+    console = logging.StreamHandler(sys.stderr)
+    console.setFormatter(fmt)
+    logger.addHandler(console)
+
+    fh = logging.FileHandler(output_dir / "pipeline.log", mode="a")
+    fh.setFormatter(fmt)
+    logger.addHandler(fh)
+
+
+def cmd_analyze(args: argparse.Namespace) -> None:
+    """Run the documentation-code misalignment analysis."""
+    from .agent import DocentAgent
+    from .config import load_config
+
+    # Validate paths
+    doc_path = Path(args.doc_path)
+    code_path = Path(args.code_path)
+    if not doc_path.is_dir():
+        sys.exit(f"ERROR: Documentation directory not found: {doc_path}")
+    if not code_path.is_dir():
+        sys.exit(f"ERROR: Code repository not found: {code_path}")
+
+    config = load_config(args)
+    output_dir = config["output_dir"]
+
+    setup_logging(output_dir)
+    logger = logging.getLogger("lyingdocs")
+    logger.info(
+        "LyingDocs starting — doc=%s  code=%s  output=%s",
+        doc_path, code_path, output_dir,
+    )
+
+    agent = DocentAgent(
+        config=config,
+        doc_path=doc_path,
+        code_path=code_path,
+        output_dir=output_dir,
+    )
+
+    report_path = agent.run()
+    logger.info("Done. Report at: %s", report_path)
+    print(f"\nReport generated: {report_path}")
+
+
+def cmd_version(_args: argparse.Namespace) -> None:
+    """Print version and exit."""
+    print(f"lyingdocs {__version__}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="lyingdocs",
+        description="LyingDocs: Documentation-Code Misalignment Detection",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # -- analyze subcommand --
+    analyze_parser = subparsers.add_parser(
+        "analyze",
+        help="Analyze documentation against code for misalignments",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+examples:
+  lyingdocs analyze --doc-path docs/ --code-path . -o output/audit
+  lyingdocs analyze --doc-path docs/ --code-path . --no-codex
+  lyingdocs analyze --doc-path docs/ --code-path . --config lyingdocs.toml
+""",
+    )
+    analyze_parser.add_argument(
+        "--doc-path", required=True,
+        help="Path to documentation root directory",
+    )
+    analyze_parser.add_argument(
+        "--code-path", required=True,
+        help="Path to code repository root",
+    )
+    analyze_parser.add_argument(
+        "--output-dir", "-o", default="output",
+        help="Output directory (default: output/)",
+    )
+    analyze_parser.add_argument(
+        "--model", "-m", default=None,
+        help="LLM model name (overrides config/env)",
+    )
+    analyze_parser.add_argument(
+        "--base-url", default=None,
+        help="API base URL (overrides config/env)",
+    )
+    analyze_parser.add_argument(
+        "--codex-provider", default=None,
+        help="Codex CLI model provider name",
+    )
+    analyze_parser.add_argument(
+        "--wire-api", default=None,
+        help="Codex CLI provider wire_api setting (e.g. 'responses' or 'chat')",
+    )
+    analyze_parser.add_argument(
+        "--max-dispatches", type=int, default=DEFAULTS["max_dispatches"],
+        help="Max Codex CLI dispatches (default: %(default)s)",
+    )
+    analyze_parser.add_argument(
+        "--max-iterations", type=int, default=DEFAULTS["max_iterations"],
+        help="Max agent loop iterations (default: %(default)s)",
+    )
+    analyze_parser.add_argument(
+        "--no-codex", action="store_true",
+        help="Disable Codex CLI integration (doc-only analysis)",
+    )
+    analyze_parser.add_argument(
+        "--config", default=None,
+        help="Path to config file (default: auto-detect lyingdocs.toml)",
+    )
+    analyze_parser.add_argument(
+        "--resume", action="store_true",
+        help="Resume from workspace checkpoint if available",
+    )
+    analyze_parser.set_defaults(func=cmd_analyze)
+
+    # -- version subcommand --
+    version_parser = subparsers.add_parser("version", help="Show version")
+    version_parser.set_defaults(func=cmd_version)
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    args.func(args)

lyingdocs/codex.py

@@ -0,0 +1,150 @@
+"""Codex CLI wrapper for atomic code analysis task dispatch."""
+
+import logging
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger("lyingdocs")
+
+PROMPTS_DIR = Path(__file__).resolve().parent / "prompts"
+
+
+def find_codex_binary(config: dict) -> str | None:
+    """Locate the codex CLI binary. Returns path string or None."""
+    # 1. Explicit path from config
+    explicit = config.get("codex_path")
+    if explicit:
+        p = Path(explicit)
+        if p.is_file() and os.access(str(p), os.X_OK):
+            return str(p)
+        logger.warning("Configured codex_path not found or not executable: %s", p)
+
+    # 2. System PATH (globally installed via npm install -g @openai/codex)
+    system_codex = shutil.which("codex")
+    if system_codex:
+        return system_codex
+
+    # 3. Local node_modules (dev setup / legacy)
+    for root in (Path.cwd(), Path(__file__).resolve().parent.parent):
+        local = root / "node_modules" / ".bin" / "codex"
+        if local.is_file():
+            return str(local)
+
+    return None
+
+
+def codex_provider_flags(config: dict) -> list[str]:
+    """Return the CLI flags that configure the model provider for codex."""
+    p = config.get("codex_provider", "openai")
+
+    # For the default OpenAI provider, codex knows it natively — just set model
+    if p == "openai":
+        return ["-m", config["model"]]
+
+    # Custom provider: inject full provider config
+    return [
+        "-m", config["model"],
+        "-c", f'model_provider="{p}"',
+        "-c", f'model_providers.{p}.name="{p}"',
+        "-c", f'model_providers.{p}.base_url="{config["base_url"]}"',
+        "-c", f'model_providers.{p}.env_key="OPENAI_API_KEY"',
+        "-c", f'model_providers.{p}.wire_api="{config.get("wire_api", "responses")}"',
+        "-c", 'model_reasoning_effort="high"',
+    ]
+
+
+def _load_codex_task_template() -> str:
+    return (PROMPTS_DIR / "codex_task.txt").read_text(encoding="utf-8")
+
+
+def run_codex_task(
+    config: dict,
+    task_description: str,
+    code_path: Path,
+    output_dir: Path,
+    task_id: str,
+    focus_paths: list[str] | None = None,
+    codex_bin: str | None = None,
+) -> str:
+    """Run a single atomic Codex analysis task.
+
+    Returns the Codex output text, or an error message if codex is unavailable.
+    """
+    if not codex_bin:
+        return (
+            "[UNAVAILABLE] Codex CLI binary not found. "
+            "Install it via 'npm install -g @openai/codex' to enable code analysis. "
+            "You can also set codex.path in your config file."
+        )
+
+    template = _load_codex_task_template()
+
+    focus_section = ""
+    if focus_paths:
+        paths_str = "\n".join(f"  - {p}" for p in focus_paths)
+        focus_section = f"\nPriority files/directories to examine:\n{paths_str}\n"
+
+    full_prompt = template.format(
+        task_description=task_description,
+        focus_paths_section=focus_section,
+    )
+
+    output_file = output_dir / f"codex_task_{task_id}.txt"
+    stderr_file = output_dir / f"codex_stderr_{task_id}.txt"
+
+    cmd = [
+        codex_bin, "exec",
+        "--dangerously-bypass-approvals-and-sandbox",
+        "-C", str(code_path.resolve()),
+        "--skip-git-repo-check",
+        "-o", str(output_file.resolve()),
+        *codex_provider_flags(config),
+        "-",  # read prompt from stdin
+    ]
+
+    logger.info("  Codex task %s: dispatching ...", task_id)
+    logger.debug("  Command: %s", " ".join(cmd[:7]) + " ...")
+
+    try:
+        result = subprocess.run(
+            cmd,
+            input=full_prompt,
+            capture_output=True,
+            text=True,
+            timeout=config.get("codex_task_timeout", 1200),
+            env=os.environ.copy(),
+        )
+
+        # Save stderr for debugging
+        stderr_file.write_text(result.stderr, encoding="utf-8")
+
+        if result.returncode != 0:
+            logger.warning(
+                "  Codex task %s exited with code %d", task_id, result.returncode
+            )
+
+        # Read output: -o file first, fallback to stdout
+        output = ""
+        if output_file.exists() and output_file.stat().st_size > 0:
+            output = output_file.read_text(encoding="utf-8")
+        elif result.stdout.strip():
+            output = result.stdout.strip()
+            output_file.write_text(output, encoding="utf-8")
+
+        if output:
+            logger.info(
+                "  Codex task %s: completed (%d chars)", task_id, len(output)
+            )
+        else:
+            logger.warning("  Codex task %s: no output produced", task_id)
+
+        return output
+
+    except subprocess.TimeoutExpired:
+        logger.error(
+            "  Codex task %s timed out after %ds",
+            task_id, config.get("codex_task_timeout", 1200),
+        )
+        return "[ERROR] Codex task timed out."