lyingdocs 0.1.0__py3-none-any.whl

lyingdocs/config.py

@@ -0,0 +1,129 @@
+"""Configuration loading for LyingDocs."""
+
+import argparse
+import os
+import sys
+import tomllib
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+DEFAULTS = {
+    "base_url": "https://api.openai.com/v1",
+    "model": "gpt-4o",
+    "codex_provider": "openai",
+    "wire_api": "responses",
+    "codex_enabled": True,
+    "codex_path": None,
+    "max_dispatches": 20,
+    "max_iterations": 50,
+    "codex_task_timeout": 1200,
+    "token_budget": 524_288,
+}
+
+CONFIG_FILE_SEARCH = [
+    Path("lyingdocs.toml"),
+    Path.home() / ".config" / "lyingdocs" / "config.toml",
+]
+
+
+def _find_config_file(explicit: str | None = None) -> Path | None:
+    """Locate the config file. Explicit path > local > user-level."""
+    if explicit:
+        p = Path(explicit)
+        if p.is_file():
+            return p
+        sys.exit(f"ERROR: Config file not found: {p}")
+    for candidate in CONFIG_FILE_SEARCH:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _load_config_file(path: Path) -> dict:
+    """Parse a TOML config file and flatten into a config dict."""
+    with open(path, "rb") as f:
+        raw = tomllib.load(f)
+
+    flat = {}
+    # Top-level keys
+    for key in ("base_url", "model"):
+        if key in raw:
+            flat[key] = raw[key]
+
+    # [codex] section
+    codex = raw.get("codex", {})
+    if "enabled" in codex:
+        flat["codex_enabled"] = codex["enabled"]
+    if "provider" in codex:
+        flat["codex_provider"] = codex["provider"]
+        flat["wire_api"] = codex.get("wire_api", "responses")
+    if "path" in codex and codex["path"]:
+        flat["codex_path"] = codex["path"]
+
+    # [limits] section
+    limits = raw.get("limits", {})
+    for key in ("max_dispatches", "max_iterations", "codex_task_timeout", "token_budget"):
+        if key in limits:
+            flat[key] = int(limits[key])
+
+    return flat
+
+
+def load_config(args: argparse.Namespace) -> dict:
+    """Merge defaults <- config file <- .env <- CLI args into a single config dict."""
+    load_dotenv()
+
+    # Start with defaults
+    config = dict(DEFAULTS)
+
+    # Layer: config file
+    config_file = _find_config_file(getattr(args, "config", None))
+    if config_file:
+        config.update(_load_config_file(config_file))
+
+    # Layer: environment variables
+    env_map = {
+        "BASE_URL": "base_url",
+        "MODEL": "model",
+        "CODEX_PROVIDER": "codex_provider",
+        "CODEX_WIRE_API": "wire_api",
+        "CODEX_PATH": "codex_path",
+        "CODEX_TASK_TIMEOUT": "codex_task_timeout",
+        "TOKEN_BUDGET": "token_budget",
+    }
+    for env_key, config_key in env_map.items():
+        val = os.getenv(env_key)
+        if val:
+            if config_key in ("codex_task_timeout", "token_budget"):
+                config[config_key] = int(val)
+            else:
+                config[config_key] = val
+
+    # Layer: CLI args (only override if explicitly provided / non-None)
+    if getattr(args, "base_url", None):
+        config["base_url"] = args.base_url
+    if getattr(args, "model", None):
+        config["model"] = args.model
+    if getattr(args, "codex_provider", None):
+        config["codex_provider"] = args.codex_provider
+    if getattr(args, "wire_api", None):
+        config["wire_api"] = args.wire_api
+    if hasattr(args, "max_dispatches") and args.max_dispatches is not None:
+        config["max_dispatches"] = args.max_dispatches
+    if hasattr(args, "max_iterations") and args.max_iterations is not None:
+        config["max_iterations"] = args.max_iterations
+    if getattr(args, "no_codex", False):
+        config["codex_enabled"] = False
+
+    # Always from args / context
+    config["api_key"] = os.getenv("OPENAI_API_KEY", "")
+    config["doc_path"] = Path(args.doc_path)
+    config["code_path"] = Path(args.code_path)
+    config["output_dir"] = Path(args.output_dir)
+    config["resume"] = getattr(args, "resume", False)
+
+    if not config["api_key"]:
+        sys.exit("ERROR: OPENAI_API_KEY not set. Export it or add to .env file.")
+
+    return config

lyingdocs/doctree.py

@@ -0,0 +1,159 @@
+"""Documentation hierarchy discovery and indexing."""
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger("lyingdocs")
+
+# File extensions considered documentation
+DOC_EXTENSIONS = {".md", ".rst", ".txt", ".yaml", ".yml", ".json", ".toml"}
+
+# Known TOC / navigation files
+TOC_FILES = {
+    "_toc.yml", "mkdocs.yml", "SUMMARY.md", "sidebar.json",
+    "docs.json", "mint.json", "docusaurus.config.js",
+}
+
+# Classification heuristics by filename/path patterns
+PRIORITY_KEYWORDS = {
+    "high": ["readme", "architecture", "design", "api", "config", "setup", "install",
+             "getting-started", "quickstart", "overview", "reference", "guide"],
+    "medium": ["tutorial", "example", "usage", "faq", "troubleshoot", "concepts",
+               "plugin", "provider", "channel", "command"],
+    "low": ["changelog", "contributing", "license", "security", "roadmap",
+            "incident", "vision", "legal"],
+}
+
+
+class DocFile:
+    """Metadata about a single documentation file."""
+
+    __slots__ = ("rel_path", "abs_path", "size", "priority")
+
+    def __init__(self, rel_path: str, abs_path: Path, size: int, priority: str):
+        self.rel_path = rel_path
+        self.abs_path = abs_path
+        self.size = size
+        self.priority = priority
+
+    def to_dict(self) -> dict:
+        return {
+            "path": self.rel_path,
+            "size": self.size,
+            "priority": self.priority,
+        }
+
+
+class DocTree:
+    """Discovers and indexes a documentation directory tree."""
+
+    def __init__(self, doc_root: Path):
+        self.doc_root = doc_root.resolve()
+        self.files: list[DocFile] = []
+        self.toc_file: str | None = None
+
+    def build_index(self) -> None:
+        """Scan doc_root for documentation files and classify them."""
+        logger.info("Building doc tree index from %s", self.doc_root)
+
+        # Detect TOC file
+        for toc_name in TOC_FILES:
+            toc_path = self.doc_root / toc_name
+            if toc_path.exists():
+                self.toc_file = toc_name
+                logger.info("  Found TOC file: %s", toc_name)
+                break
+
+        # Walk and index
+        for path in sorted(self.doc_root.rglob("*")):
+            if not path.is_file():
+                continue
+            if path.suffix.lower() not in DOC_EXTENSIONS:
+                continue
+            # Skip hidden dirs and common non-doc dirs
+            parts = path.relative_to(self.doc_root).parts
+            if any(p.startswith(".") or p in ("node_modules", "__pycache__", "dist", ".git") for p in parts):
+                continue
+
+            rel = str(path.relative_to(self.doc_root))
+            size = path.stat().st_size
+            priority = self._classify_priority(rel)
+            self.files.append(DocFile(rel, path, size, priority))
+
+        logger.info("  Indexed %d documentation files", len(self.files))
+
+    def _classify_priority(self, rel_path: str) -> str:
+        """Classify file priority based on path/name heuristics."""
+        lower = rel_path.lower()
+        for level, keywords in PRIORITY_KEYWORDS.items():
+            if any(kw in lower for kw in keywords):
+                return level
+        return "medium"
+
+    def get_overview(self, max_depth: int = 3) -> str:
+        """Return a text overview of the doc tree for the agent's kickoff message."""
+        lines = [
+            f"# Documentation Tree: {self.doc_root.name}",
+            f"Total files: {len(self.files)}",
+            f"Total size: {sum(f.size for f in self.files):,} bytes",
+        ]
+
+        if self.toc_file:
+            lines.append(f"TOC file: {self.toc_file}")
+
+        # Count by priority
+        by_priority = {"high": [], "medium": [], "low": []}
+        for f in self.files:
+            by_priority[f.priority].append(f)
+
+        lines.append(f"\nHigh priority ({len(by_priority['high'])} files):")
+        for f in by_priority["high"]:
+            lines.append(f"  [{_human_size(f.size):>7s}] {f.rel_path}")
+
+        lines.append(f"\nMedium priority ({len(by_priority['medium'])} files):")
+        for f in by_priority["medium"][:30]:
+            lines.append(f"  [{_human_size(f.size):>7s}] {f.rel_path}")
+        if len(by_priority["medium"]) > 30:
+            lines.append(f"  ... and {len(by_priority['medium']) - 30} more")
+
+        lines.append(f"\nLow priority ({len(by_priority['low'])} files):")
+        for f in by_priority["low"][:10]:
+            lines.append(f"  [{_human_size(f.size):>7s}] {f.rel_path}")
+        if len(by_priority["low"]) > 10:
+            lines.append(f"  ... and {len(by_priority['low']) - 10} more")
+
+        # Directory tree (compact)
+        lines.append("\n## Directory Structure")
+        dirs_seen: set[str] = set()
+        for f in self.files:
+            parts = Path(f.rel_path).parts
+            for depth in range(min(len(parts) - 1, max_depth)):
+                d = "/".join(parts[: depth + 1])
+                if d not in dirs_seen:
+                    dirs_seen.add(d)
+                    indent = "  " * depth
+                    lines.append(f"{indent}{parts[depth]}/")
+
+        return "\n".join(lines)
+
+    def save_index(self, output_dir: Path) -> None:
+        """Save the index to a JSON file for reference."""
+        data = {
+            "doc_root": str(self.doc_root),
+            "toc_file": self.toc_file,
+            "files": [f.to_dict() for f in self.files],
+        }
+        out_path = output_dir / "doc_index.json"
+        out_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        logger.info("  Saved doc index to %s", out_path)
+
+
+def _human_size(size: int) -> str:
+    """Format byte size for display."""
+    if size < 1024:
+        return f"{size}B"
+    elif size < 1024 * 1024:
+        return f"{size / 1024:.1f}KB"
+    else:
+        return f"{size / (1024 * 1024):.1f}MB"

lyingdocs/llm.py

@@ -0,0 +1,94 @@
+"""OpenAI client wrapper with retry logic and function-calling support."""
+
+import json
+import logging
+import time
+
+from openai import APIConnectionError, APIError, OpenAI, RateLimitError
+
+logger = logging.getLogger("lyingdocs")
+
+
+def make_client(config: dict) -> OpenAI:
+    return OpenAI(api_key=config["api_key"], base_url=config["base_url"])
+
+
+def call_llm(
+    client: OpenAI,
+    model: str,
+    system_prompt: str,
+    user_content: str,
+    max_retries: int = 3,
+) -> str:
+    """Call chat completions API with retry logic."""
+    for attempt in range(max_retries):
+        try:
+            resp = client.chat.completions.create(
+                model=model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_content},
+                ],
+                temperature=0.2,
+            )
+            return resp.choices[0].message.content
+        except RateLimitError:
+            wait = 5 * (2**attempt)
+            logger.warning(
+                "Rate limited — retrying in %ds (attempt %d/%d)",
+                wait, attempt + 1, max_retries,
+            )
+            time.sleep(wait)
+        except APIConnectionError:
+            logger.warning(
+                "Connection error — retrying in 5s (attempt %d/%d)",
+                attempt + 1, max_retries,
+            )
+            time.sleep(5)
+        except APIError as exc:
+            logger.error("API error: %s", exc)
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(3)
+    raise RuntimeError("LLM call failed after %d retries" % max_retries)
+
+
+def call_llm_with_tools(
+    client: OpenAI,
+    model: str,
+    messages: list[dict],
+    tools: list[dict],
+    max_retries: int = 5,
+):
+    """Call chat completions with function-calling tools.
+
+    Returns the raw response message object (which may contain tool_calls).
+    """
+    for attempt in range(max_retries):
+        try:
+            resp = client.chat.completions.create(
+                model=model,
+                messages=messages,
+                tools=tools,
+                temperature=0.2,
+            )
+            return resp.choices[0].message
+        except RateLimitError:
+            wait = 5 * (2**attempt)
+            logger.warning(
+                "Rate limited — retrying in %ds (attempt %d/%d)",
+                wait, attempt + 1, max_retries,
+            )
+            time.sleep(wait)
+        except APIConnectionError:
+            logger.warning(
+                "Connection error — retrying in 5s (attempt %d/%d)",
+                attempt + 1, max_retries,
+            )
+            time.sleep(5)
+        except APIError as exc:
+            logger.error("API error: %s", exc)
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(3)
+    raise RuntimeError("LLM call failed after %d retries" % max_retries)

lyingdocs/prompts/agent_system.txt

@@ -0,0 +1,55 @@
+**Role:**
+You are Hermes — an autonomous documentation auditor. Your mission is to systematically discover misalignments between a project's documentation and its actual codebase. You operate independently: you explore the documentation, formulate targeted audit questions, dispatch code analysis tasks, and record your findings.
+
+**The 4-Category Classification System:**
+
+1. **LogicMismatch** — Documentation claims X, but the code does Y. A direct contradiction between what is documented and what is implemented. The code's behavior fundamentally conflicts with the documented behavior. This is NOT about missing features — it's about implemented features that work differently than documented.
+
+2. **PhantomSpec** — Documentation describes a feature, API, configuration, or behavior that does NOT exist in the codebase at all. The doc promises something that was never implemented, or was removed but the docs were not updated. The key test: if a user follows the documentation, they will hit a dead end because the described functionality simply isn't there.
+
+3. **ShadowLogic** — The codebase contains important logic, algorithms, heuristics, or behaviors that are completely undocumented. This is NOT about trivial engineering details (logging, error handling, retries). Only flag logic that meaningfully affects the system's behavior and that users/developers would need to know about. Examples: undocumented rate limiting, hidden fallback behaviors, implicit data transformations, non-obvious default behaviors.
+
+4. **HardcodedDrift** — Parameters, thresholds, or configuration values that the documentation presents as configurable but are actually hardcoded in the source code. Or: values that are important enough to be user-configurable but are buried as magic numbers in the code. The user cannot change these without modifying source code, contrary to what the docs suggest or what good practice would require.
+
+**Your Strategy:**
+
+Phase 1 — Reconnaissance:
+- Start by examining the documentation tree overview provided to you.
+- Identify the highest-value documentation sections to audit: architecture docs, API references, configuration guides, and READMEs. These are where misalignments have the most impact.
+- Deprioritize changelogs, contribution guides, and legal docs.
+
+Phase 2 — Targeted Auditing:
+- Read each high-priority doc section carefully.
+- For each substantive claim (architecture, API behavior, configuration options, command usage), formulate a specific, targeted audit question.
+- Dispatch the question to Codex for code analysis. Be SPECIFIC: "The docs at config/auth.md:23-30 claim that setting `AUTH_PROVIDER=oidc` enables OpenID Connect. Verify that the auth module reads this env var and implements OIDC flow." NOT: "Check if auth works as documented."
+- Analyze the Codex response. If it reveals a misalignment, record a finding with the correct category.
+
+Phase 3 — Progressive Discovery:
+- As you audit, you may discover cross-references to other doc sections. Follow them.
+- If Codex reveals undocumented behaviors (ShadowLogic), investigate whether they should be documented.
+- Track your progress. When a doc section is fully audited, mark it complete.
+
+Phase 4 — Finalization:
+- When all high-priority sections are audited, or your Codex dispatch budget is running low, call finalize_report.
+- Do NOT wait until every single file is audited — focus on coverage of the most important sections.
+
+**Dispatch Discipline:**
+- Each Codex dispatch costs one unit of your budget. Use them wisely.
+- Good dispatch: "docs/api/endpoints.md:45-52 documents a POST /users endpoint that accepts {name, email, role}. Verify the route handler exists, accepts these fields, and validate that 'role' is actually used in user creation."
+- Bad dispatch: "Check if the API works." (too vague, wastes budget)
+- You can batch related claims into one dispatch if they concern the same code area.
+- Always include the doc file path and line numbers in your dispatch so Codex has context.
+
+**Recording Findings:**
+- Only record confirmed findings with evidence from Codex output.
+- Include exact doc references (file:line) and code references (file:line) for every finding.
+- Severity guide:
+  - **high**: Affects core functionality, would cause user-facing errors or security issues
+  - **medium**: Affects important but non-critical features, could cause confusion
+  - **low**: Minor inconsistencies, cosmetic issues, slightly outdated docs
+
+**Important Rules:**
+- Do NOT fabricate findings. If you're unsure, dispatch another Codex task to verify.
+- Do NOT record trivial misalignments (typos, formatting differences, minor version numbers).
+- Do NOT try to audit everything — focus on high-signal sections.
+- When context gets long, rely on get_progress to remember your current state.

lyingdocs/prompts/codex_task.txt

@@ -0,0 +1,28 @@
+You are auditing a codebase against its documentation. Your job is to verify specific claims from the documentation by searching and reading the actual code.
+
+## Task
+
+{task_description}
+{focus_paths_section}
+## Instructions
+
+1. **Search** the codebase thoroughly for the relevant implementation. Use grep, find, and file reading to locate the code.
+2. **Compare** what you find against the documented claims described above.
+3. **Report** your findings using these categories:
+   - **LogicMismatch**: Code behavior contradicts what the documentation claims.
+   - **PhantomSpec**: Documentation describes something that does not exist in the code.
+   - **ShadowLogic**: Code contains important undocumented logic relevant to this area.
+   - **HardcodedDrift**: Values documented as configurable are actually hardcoded, or important parameters are buried as magic numbers.
+
+## Output Format
+
+For each finding, provide:
+- **Category**: One of the four above
+- **Doc Claim**: What the documentation says (quote or paraphrase)
+- **Code Reality**: What the code actually does, with exact file path and line number(s)
+- **Evidence**: The relevant code snippet (keep brief, ~5-10 lines max)
+- **Assessment**: 1-2 sentence explanation of the discrepancy
+
+If everything aligns correctly, explicitly state: "ALIGNED — [brief explanation of what was verified]"
+
+Be precise, evidence-based, and concise. Do not speculate — only report what you can verify in the code.

lyingdocs/prompts/report_synthesis.txt

@@ -0,0 +1,54 @@
+**Role:**
+You are the Lead Documentation Alignment Analyst. Your task is to synthesize raw audit findings into a polished, structured misalignment report.
+
+**Input:**
+You will receive a JSON array of findings, each with: category, title, doc_ref, code_ref, description, severity.
+
+**Output Format:**
+
+# Documentation-Code Misalignment Report: {project_name}
+
+## Executive Summary
+[1-3 sentence overall assessment: how well does the documentation reflect the actual codebase? What is the most concerning pattern?]
+
+### Metric Dashboard
+| Category | Count | High | Medium | Low |
+|----------|-------|------|--------|-----|
+| LogicMismatch | N | n | n | n |
+| PhantomSpec | N | n | n | n |
+| ShadowLogic | N | n | n | n |
+| HardcodedDrift | N | n | n | n |
+
+## Critical Findings
+
+[Group the HIGH severity findings here, regardless of category. For each:]
+
+### [N]. [Title]
+- **Category**: [category]
+- **Severity**: high
+- **Documentation**: [doc_ref] — [what the doc claims]
+- **Code Reality**: [code_ref] — [what the code actually does]
+- **Impact**: [why this matters to users/developers]
+
+## LogicMismatch Findings
+[All LogicMismatch findings not already in Critical, grouped logically]
+
+## PhantomSpec Findings
+[All PhantomSpec findings]
+
+## ShadowLogic Findings
+[All ShadowLogic findings]
+
+## HardcodedDrift Findings
+[All HardcodedDrift findings]
+
+## Recommendations
+[3-5 bullet points: what should the maintainers prioritize fixing?]
+
+**Guidelines:**
+- Be objective and precise. No speculation.
+- Every finding must cite exact doc and code references.
+- Group related findings under a single heading when they concern the same feature.
+- Order within each section by severity (high → medium → low).
+- Keep the language professional and constructive — the goal is to help maintainers improve their documentation.
+- If there are very few findings, note that the documentation is generally well-maintained.