graphitect 0.2.0__py3-none-any.whl

graphitect/synthesize/questions.py

@@ -0,0 +1,139 @@
+"""Two renderers, one RationaleQuestion object - plan.md §03.
+
+The skill surface maps a RationaleQuestion straight onto the host's
+structured-question tool (e.g. Claude Code's AskUserQuestion) - that mapping
+lives in the SKILL.md itself, not here, since it's a host-tool-call, not
+Python. This module is the standalone-CLI renderer: a numbered terminal
+prompt when interactive, or a JSON file round-trip when not - matching
+Graphify's own `--update` re-run convention rather than inventing a new one.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from ..models import Claim, Confidence, Evidence, RationaleQuestion
+
+
+def ask_interactive(questions: list[RationaleQuestion]) -> dict[str, str]:
+    """Numbered terminal prompt with a free-text escape hatch. Returns
+    {claim_id: answer_text} - either the chosen option's becomes_text or the
+    typed free text, verbatim.
+    """
+    answers: dict[str, str] = {}
+    total = len(questions)
+    for i, q in enumerate(questions, start=1):
+        print(f"\n[{i}/{total}] {q.question}")
+        for j, opt in enumerate(q.options, start=1):
+            marker = "  [our best guess]" if j == 1 else ""
+            print(f"  {j}) {opt.label}{marker}")
+        if q.allow_free_text:
+            print(f"  {len(q.options) + 1}) Something else (type your own)")
+        try:
+            choice = input("> ").strip()
+        except EOFError:
+            # No real terminal behind stdin despite isatty() saying so (seen
+            # under some sandboxed/wrapped shells) - stop asking rather than
+            # crash; caller falls back to writing out whatever's left unanswered.
+            print("\n(no input available - leaving remaining questions unanswered)")
+            break
+
+        if choice.isdigit() and 1 <= int(choice) <= len(q.options):
+            answers[q.claim_id] = q.options[int(choice) - 1].becomes_text
+        elif q.allow_free_text:
+            free_text = choice if not choice.isdigit() else input("Your answer: ").strip()
+            answers[q.claim_id] = free_text
+        else:
+            print("No valid option chosen - leaving this claim inferred.")
+    return answers
+
+
+def write_pending(questions: list[RationaleQuestion], out_path: Path) -> Path:
+    """Non-interactive path: don't block CI/piped runs. Write pending
+    questions to disk for a human to answer later via `graphitect synthesize
+    --answers <file>`. Set each emitted `answer` field to a string, then pass
+    the same file back to `--answers`.
+    """
+    payload = [{**q.model_dump(), "answer": None} for q in questions]
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    return out_path
+
+
+def read_answers(answers_path: Path) -> dict[str, str]:
+    """Load answers written by a human editing the file written by
+    write_pending. The preferred format is its question list with an `answer`
+    string filled per item. The older {"claim_id": "answer text"} mapping is
+    accepted for compatibility.
+    """
+    payload = json.loads(answers_path.read_text(encoding="utf-8"))
+    if isinstance(payload, dict):
+        if not all(isinstance(claim_id, str) and isinstance(answer, str) for claim_id, answer in payload.items()):
+            raise TypeError("answer mappings must contain string claim IDs and answer text")
+        return payload
+    if not isinstance(payload, list):
+        raise TypeError("answers must be an object or the generated question list")
+
+    answers: dict[str, str] = {}
+    for index, item in enumerate(payload, start=1):
+        if not isinstance(item, dict) or not isinstance(item.get("claim_id"), str):
+            raise TypeError(f"question {index} must contain a string claim_id")
+        answer = item.get("answer")
+        if answer is None or answer == "":
+            continue
+        if not isinstance(answer, str):
+            raise TypeError(f"question {index} answer must be a string or null")
+        if item["claim_id"] in answers:
+            raise ValueError(f"duplicate answer for claim_id {item['claim_id']!r}")
+        answers[item["claim_id"]] = answer
+    return answers
+
+
+def apply_answer(claim: Claim, answer_text: str) -> Claim:
+    """An answer always confirms - and, if it's free text rather than a
+    listed option, *rewrites* claim.text to match what was actually said.
+    That's what let a wrong guess (e.g. Phase 0's Word-COM inference) get
+    genuinely corrected instead of rubber-stamped (plan.md §03).
+    """
+    return claim.model_copy(
+        update={
+            "text": answer_text,
+            "confidence": Confidence.CONFIRMED,
+            "cites": [*claim.cites, Evidence(source="user", note=answer_text)],
+        }
+    )
+
+
+def resolve_questions(
+    questions: list[RationaleQuestion],
+    claims_by_id: dict[str, Claim],
+    pending_path: Path,
+    *,
+    non_interactive: bool = False,
+) -> tuple[dict[str, Claim], list[RationaleQuestion]]:
+    """Interactive when attached to a real terminal, otherwise write pending
+    questions to disk and leave those claims inferred for this run.
+
+    `non_interactive` is an explicit override for `--non-interactive`/CI use -
+    isatty() alone isn't reliable everywhere (some wrapped/sandboxed shells
+    report a tty even with stdin redirected from /dev/null), and a dropped
+    stdin mid-prompt raises EOFError rather than silently hanging, so this
+    always degrades to write_pending for whatever wasn't answered rather than
+    crashing.
+    """
+    if not questions:
+        return claims_by_id, []
+
+    if non_interactive or not sys.stdin.isatty():
+        write_pending(questions, pending_path)
+        return claims_by_id, questions
+
+    answers = ask_interactive(questions)
+    for claim_id, answer_text in answers.items():
+        claims_by_id[claim_id] = apply_answer(claims_by_id[claim_id], answer_text)
+    unanswered = [q for q in questions if q.claim_id not in answers]
+    if unanswered:
+        write_pending(unanswered, pending_path)
+    return claims_by_id, unanswered

graphitect/synthesize/rubric.py

@@ -0,0 +1,104 @@
+"""The rationale-mining rubric - plan.md §03.
+
+For each claim: code -> README -> git log -> other docs -> stop. If nothing
+found, only *descriptive* claims in a load-bearing section become an askable
+RationaleQuestion; *prescriptive* claims (recommendations, "not a stated
+plan") stay `inferred` forever by construction - asking "did you really mean
+this suggestion" doesn't make sense the same way a factual gap does.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from ..models import Claim, Confidence, Evidence, QuestionOption, RationaleQuestion
+
+# Only these sections are worth a targeted question - incidental color in
+# Overview/Components/Workflows isn't "why" material (plan.md §03).
+ASKABLE_SECTIONS = {"Technology choices & why", "Tradeoffs & alternatives considered"}
+
+
+def search_text(text: str, keywords: list[str]) -> str | None:
+    """Return the first line containing any keyword, or None. A real
+    implementation would use embeddings/fuzzy match; keyword search is the
+    honest floor - it either finds explicit textual evidence or it doesn't,
+    with no risk of a false-confident semantic match standing in for a
+    citation.
+    """
+    lowered_keywords = [k.lower() for k in keywords]
+    for line in text.splitlines():
+        low = line.lower()
+        if any(k in low for k in lowered_keywords):
+            return line.strip()
+    return None
+
+
+def mine_readme(repo_path: Path, keywords: list[str]) -> Evidence | None:
+    readme = repo_path / "README.md"
+    if not readme.exists():
+        return None
+    hit = search_text(readme.read_text(encoding="utf-8", errors="ignore"), keywords)
+    return Evidence(source="readme", file="README.md", note=hit) if hit else None
+
+
+def mine_git_log(repo_path: Path, keywords: list[str]) -> Evidence | None:
+    changelog = repo_path / "CHANGELOG.md"
+    if changelog.exists():
+        hit = search_text(changelog.read_text(encoding="utf-8", errors="ignore"), keywords)
+        if hit:
+            return Evidence(source="git_log", file="CHANGELOG.md", note=hit)
+
+    try:
+        result = subprocess.run(
+            ["git", "log", "--all", "--grep", "|".join(keywords), "-i", "--oneline", "-n", "1"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except FileNotFoundError:
+        return None
+    hit = result.stdout.strip()
+    return Evidence(source="git_log", note=hit) if hit else None
+
+
+def mine_other_docs(repo_path: Path, keywords: list[str]) -> Evidence | None:
+    docs_dir = repo_path / "docs"
+    if not docs_dir.is_dir():
+        return None
+    for doc in sorted(docs_dir.rglob("*.md")):
+        hit = search_text(doc.read_text(encoding="utf-8", errors="ignore"), keywords)
+        if hit:
+            return Evidence(source="docs", file=str(doc.relative_to(repo_path)), note=hit)
+    return None
+
+
+def mine_rationale(repo_path: Path, claim_text: str, keywords: list[str]) -> Evidence | None:
+    """Walk the rubric in order, stop at the first hit. Code-level evidence
+    (step 1) isn't handled here - that comes pre-attached from Graphify's own
+    extraction (EXTRACTED edges) or a direct source read, not a text search.
+    """
+    for miner in (mine_readme, mine_git_log, mine_other_docs):
+        evidence = miner(repo_path, keywords)
+        if evidence:
+            return evidence
+    return None
+
+
+def build_question(claim: Claim, claim_id: str, section: str, guess: str) -> RationaleQuestion | None:
+    """Only queue a question for a descriptive, load-bearing, unresolved claim."""
+    if claim.kind != "descriptive" or section not in ASKABLE_SECTIONS:
+        return None
+    if claim.confidence == Confidence.CONFIRMED:
+        return None
+    return RationaleQuestion(
+        claim_id=claim_id,
+        question=f"Why: {claim.text}?",
+        options=[
+            QuestionOption(label=guess, becomes_text=claim.text),
+            QuestionOption(label="No deeper reason", becomes_text=f"{claim.text} (no deliberate reason given)"),
+        ],
+    )

graphitect-0.2.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: graphitect
+Version: 0.2.0
+Summary: One self-contained codebase explainer: bundled Graphify analysis, bundled Archify diagrams, and optional LLM rationale.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Naman6019/graphitect
+Project-URL: Repository, https://github.com/Naman6019/graphitect
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE-GRAPHIFY-APACHE-2.0
+License-File: LICENSE-GRAPHIFY-MIT
+License-File: NOTICE-GRAPHIFY
+License-File: LICENSE-ARCHIFY-MIT
+License-File: NOTICE-ARCHIFY-THIRD-PARTY.md
+Requires-Dist: pydantic>=2.0
+Requires-Dist: networkx>=3.4
+Requires-Dist: numpy>=1.21
+Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Requires-Dist: tree-sitter<0.26,>=0.23.0
+Requires-Dist: tree-sitter-python<0.26,>=0.23
+Requires-Dist: tree-sitter-javascript<0.26,>=0.23
+Requires-Dist: tree-sitter-typescript<0.25,>=0.23
+Requires-Dist: tree-sitter-go<0.26,>=0.23
+Requires-Dist: tree-sitter-rust<0.25,>=0.23
+Requires-Dist: tree-sitter-java<0.25,>=0.23
+Requires-Dist: tree-sitter-groovy<0.3,>=0.1
+Requires-Dist: tree-sitter-c<0.25,>=0.23
+Requires-Dist: tree-sitter-cpp<0.25,>=0.23
+Requires-Dist: tree-sitter-ruby<0.25,>=0.23
+Requires-Dist: tree-sitter-c-sharp<0.25,>=0.23
+Requires-Dist: tree-sitter-kotlin<2.0,>=1.0
+Requires-Dist: tree-sitter-scala<0.27,>=0.23
+Requires-Dist: tree-sitter-php<0.25,>=0.23
+Requires-Dist: tree-sitter-swift<0.9,>=0.7
+Requires-Dist: tree-sitter-lua<0.6,>=0.2
+Requires-Dist: tree-sitter-zig<2.0,>=1.0
+Requires-Dist: tree-sitter-powershell<0.28,>=0.26
+Requires-Dist: tree-sitter-elixir<0.5,>=0.3
+Requires-Dist: tree-sitter-objc<4.0,>=3.0
+Requires-Dist: tree-sitter-julia<0.25,>=0.23
+Requires-Dist: tree-sitter-verilog<2.0,>=1.0
+Requires-Dist: tree-sitter-fortran<0.8,>=0.6
+Requires-Dist: tree-sitter-bash<0.27,>=0.23
+Requires-Dist: tree-sitter-json<0.26,>=0.23
+Requires-Dist: tree-sitter-sql
+Requires-Dist: openai
+Requires-Dist: anthropic
+Requires-Dist: tiktoken
+Dynamic: license-file
+
+# Graphitect
+
+**Turn an existing codebase into one interactive architecture report.**
+
+Graphitect produces a self-contained HTML artifact for project walkthroughs,
+technical interviews, handoffs, and architectural review. It has two sections:
+
+1. **Interactive system diagram** — generated locally from the repository.
+2. **Project explanation** — technical choices, mechanisms, trade-offs, and
+   pros/cons, with every statement marked confirmed or inferred.
+
+![Graphitect report with a responsive embedded interactive viewer](docs/images/embedded-viewer-demo.png)
+
+*A live Graphitect report with a responsive embedded Archify viewer. Theme,
+view, presentation, and export controls remain interactive inside the report.*
+
+## Why Graphitect
+
+Reading a repository is slow when a graph tells you only **what** connects and
+a prose summary tells you only **why**. Graphitect combines both without
+letting a model invent the diagram:
+
+| Layer | What it does |
+| --- | --- |
+| **Graphify** | Extracts code structure, direct relationships, and communities locally. It is the deterministic source for diagram nodes and edges. |
+| **Archify** | Renders the bundled, interactive architecture, workflow, and sequence views. |
+| **Graphitect** | Turns that evidence into one portable HTML report and verifies any file-backed explanation citation before publishing it. |
+
+The diagram does not require an LLM or API key. The explanation can come from
+a configured standalone provider or the model already running inside Codex,
+Claude Code, or another Agent Skills-compatible host.
+
+## Requirements
+
+- Python 3.10+
+- Node.js 18+ for the bundled Archify renderer
+
+Graphify and Archify are bundled with Graphitect. You do **not** install
+Graphify separately or run `npm install` for Archify.
+
+## Install
+
+### From this repository
+
+```bash
+git clone https://github.com/Naman6019/graphitect.git
+cd graphitect
+python -m pip install .
+```
+
+### From PyPI
+
+```bash
+python -m pip install graphitect
+```
+
+Confirm that the renderer runtime is available:
+
+```bash
+node --version
+graphitect --help
+```
+
+## Quick start
+
+```bash
+graphitect build /path/to/project -o project-architecture.html
+```
+
+This produces one standalone HTML file. Open it in any modern browser; it does
+not need a server or an internet connection after generation.
+
+Without an LLM key, Graphitect still produces Section 1 and plainly marks
+Section 2 as unavailable. To explicitly omit the diagram:
+
+```bash
+graphitect build /path/to/project --no-diagram -o project-explanation.html
+```
+
+## Add the detailed explanation
+
+### Standalone CLI
+
+Configure one supported provider, then use the same command:
+
+```bash
+# PowerShell example — do not commit keys to your repository.
+$env:GEMINI_API_KEY = "..."
+graphitect build /path/to/project -o project-architecture.html
+```
+
+Supported environment variables are `GEMINI_API_KEY` (or `GOOGLE_API_KEY`),
+`ANTHROPIC_API_KEY`, and `OLLAMA_API_KEY`. A local Ollama server is also
+supported through `--ollama-local`.
+
+## Install as an agent skill — no separate API key
+
+Install the `graphitect` CLI once, then export a **project skill** inside each
+repository you want an agent to explain. The agent host's selected model writes
+Section 2; Graphitect makes no LLM network call in this path.
+
+### Codex
+
+```bash
+# One time, if Graphitect is not installed already.
+python -m pip install graphitect
+
+# In the project you want to document.
+cd /path/to/project
+graphitect skill export --host codex
+# Writes .agents/skills/graphitect/SKILL.md
+```
+
+Open that project in Codex, then say: `Use the Graphitect skill to explain this
+codebase and write project-architecture.html.`
+
+### Claude Code
+
+```bash
+# One time, if Graphitect is not installed already.
+python -m pip install graphitect
+
+# In the project you want to document.
+cd /path/to/project
+graphitect skill export --host claude-code
+# Writes .claude/skills/graphitect/SKILL.md
+```
+
+Start or reopen Claude Code in that project, then say: `Use the Graphitect
+skill to explain this codebase and write project-architecture.html.`
+
+### Other Agent Skills-compatible hosts
+
+Export the portable bundle to the host's project-skill directory. Point
+`--output` at the directory that host discovers:
+
+```bash
+cd /path/to/project
+graphitect skill export --output ./skills/graphitect
+# Writes SKILL.md and agents/openai.yaml.
+```
+
+### What the skill does
+
+The agent follows this evidence-first handoff:
+
+```bash
+graphitect agent prepare /path/to/project -o .graphitect-agent
+# The host model writes .graphitect-agent/narrative.json from grounded evidence.
+graphitect agent compile .graphitect-agent --title "Project name" -o project-architecture.html
+```
+
+Graphitect owns the diagram in this mode. The host model can write only the
+narrative; it cannot add, remove, or rename Graphify nodes and edges. A
+confirmed code claim must cite a repository-relative file and a full phrase
+from that file. Unverified, uncited, externally referenced, or fabricated
+user-backed claims are downgraded to **inferred**.
+
+## What the report contains
+
+### Section 1 — Interactive system diagram
+
+- Overview: a readable structural subset of the Graphify graph.
+- Full architecture rollup: every retained relationship in a scrollable view.
+- Guided workflow story: a paced, direct path through observed relationships.
+- Sequence trace: shown only for consecutive direct `calls` or `invokes`
+  relationships; it is static source evidence, never runtime telemetry.
+- Per-block hover details: source path, symbol, relationship context, and
+  legacy naming context where a function name might be mistaken for a provider.
+
+![Graphitect evidence-gated static call sequence](docs/images/static-call-sequence-demo.png)
+
+*A source-derived sequence view. Every arrow represents a direct Graphify
+`calls` or `invokes` relationship; no runtime request, timing, or trace data
+is implied.*
+
+### Section 2 — Project explanation
+
+- Architecture and component walkthrough.
+- Technology choices and the evidence behind them.
+- Trade-offs, alternatives, strengths, and costs.
+- Related diagram components for each section.
+- Confirmed versus inferred labels, plus optional author questions for
+  unresolved, load-bearing rationale.
+
+## Evidence rules
+
+Graphitect keeps the distinction between repository fact and analysis visible:
+
+- **Confirmed**: backed by code, README, docs, Git history, or a direct author
+  answer. File-backed citations must contain the cited phrase.
+- **Inferred**: a reasoned interpretation or recommendation. It is useful, but
+  never presented as a proven historical decision.
+- Diagram relationships: direct Graphify extraction, not an LLM reconstruction.
+
+If `synthesize --non-interactive` or the agent workflow writes
+`graphitect-questions.json`, fill its `answer` fields and rerun with
+`--answers`. Unanswered items remain inferred.
+
+## Advanced commands
+
+```bash
+# Write reusable Graphify-grounded data.
+graphitect ground /path/to/project -o grounding.json
+
+# Synthesize from that data with a configured standalone provider.
+graphitect synthesize grounding.json --repo /path/to/project -o understanding.json
+
+# Render a saved understanding file.
+graphitect deliver understanding.json --title "Project name" -o project-architecture
+```
+
+For normal use, prefer `graphitect build` or the installed-agent workflow.
+
+## Privacy and network behavior
+
+- Graphify extraction and diagram generation run locally.
+- The self-contained report embeds its interactive viewer; viewing it requires
+  no hosted Graphitect service.
+- Standalone explanation generation sends the bounded evidence context to the
+  provider you configure.
+- Installed-agent mode uses the host agent's own model and permissions instead
+  of a Graphitect API key.
+
+Review your repository and provider policy before sending source context to an
+external model.
+
+## Bundled projects and notices
+
+Graphitect bundles Graphify under its Apache-2.0 distribution terms and
+Archify under MIT plus its third-party notices. See `licenses/graphify/`,
+`licenses/archify/`, and the root notice files for details.