pystdoc 0.8.2__tar.gz → 0.8.4__tar.gz

{pystdoc-0.8.2/src/pystdoc.egg-info → pystdoc-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pystdoc
-Version: 0.8.2
+Version: 0.8.4
 Summary: Python Structural & Topological Documentation Engine (pystdoc): High-precision, LLM-powered hierarchical codebase and architecture documentation generator.
 Author: tab4moji
 License: MIT
@@ -78,7 +78,7 @@ your_project/
    - Evaluates call graphs in $O(V+E)$ linear time.
    - Automatically breaks cyclic mutual recursions and organizes code symbols into dependency-safe execution levels.
    - Level-by-level parallel LLM execution guarantees context-rich bottom-up summaries without race conditions.
-2. **High-Speed Incremental Sync & Semantic Change Propagation (v0.8.0 - v0.8.2)**:
+2. **High-Speed Incremental Sync & Semantic Change Propagation (v0.8.0 - v0.8.4)**:
    - **Selective Bottom-Up Propagation & Immediate Snippet Flush**: Detects AST and logic-level code differences. If regenerated specifications remain semantically unchanged, cascading LLM re-analysis terminates early while Markdown documents (source code snippets, line ranges, caller/callee references) are immediately updated with latest code. Signature, kind, and callee alterations are guaranteed to propagate upstream.
    - **Content-Defined Map-Reduce Caching**: Intermediate summaries in architecture synthesis (`designgen`) are chunked using stable hash boundaries and cached per group in SQLite, ensuring that only groups containing edited functions are re-summarized.
    - **Architectural Entry-Point Filtering**: For system execution modeling (`execution_model.md`), key architectural functions (entry points, CLI routers, and core dispatchers) are automatically filtered and passed directly into the LLM context, bypassing heavy multi-step Map-Reduce loops and speeding up generation by up to 90%+.

{pystdoc-0.8.2 → pystdoc-0.8.4}/README.md

@@ -49,7 +49,7 @@ your_project/
    - Evaluates call graphs in $O(V+E)$ linear time.
    - Automatically breaks cyclic mutual recursions and organizes code symbols into dependency-safe execution levels.
    - Level-by-level parallel LLM execution guarantees context-rich bottom-up summaries without race conditions.
-2. **High-Speed Incremental Sync & Semantic Change Propagation (v0.8.0 - v0.8.2)**:
+2. **High-Speed Incremental Sync & Semantic Change Propagation (v0.8.0 - v0.8.4)**:
    - **Selective Bottom-Up Propagation & Immediate Snippet Flush**: Detects AST and logic-level code differences. If regenerated specifications remain semantically unchanged, cascading LLM re-analysis terminates early while Markdown documents (source code snippets, line ranges, caller/callee references) are immediately updated with latest code. Signature, kind, and callee alterations are guaranteed to propagate upstream.
    - **Content-Defined Map-Reduce Caching**: Intermediate summaries in architecture synthesis (`designgen`) are chunked using stable hash boundaries and cached per group in SQLite, ensuring that only groups containing edited functions are re-summarized.
    - **Architectural Entry-Point Filtering**: For system execution modeling (`execution_model.md`), key architectural functions (entry points, CLI routers, and core dispatchers) are automatically filtered and passed directly into the LLM context, bypassing heavy multi-step Map-Reduce loops and speeding up generation by up to 90%+.

{pystdoc-0.8.2 → pystdoc-0.8.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pystdoc"
-version = "0.8.2"
+version = "0.8.4"
 description = "Python Structural & Topological Documentation Engine (pystdoc): High-precision, LLM-powered hierarchical codebase and architecture documentation generator."
 readme = "README.md"
 authors = [

{pystdoc-0.8.2 → pystdoc-0.8.4}/src/pystdoc/__init__.py

@@ -1,3 +1,3 @@
 """pystdoc: Python Structural & Topological Documentation Engine (pystdoc)."""
 
-__version__ = "0.8.2"
+__version__ = "0.8.4"

pystdoc-0.8.4/src/pystdoc/call_graph.py

@@ -0,0 +1,77 @@
+"""Call graph facade: Level DAG ordering and backward-compatible exports.
+
+Purpose:
+    Partition symbol nodes into dependency-safe levels (callees before
+    callers, SCC groups together) for level-by-level parallel LLM runs.
+    The implementation is split across small modules; the public names
+    below are re-exported so existing imports keep working:
+
+    - call_graph_nodes : SymbolNode, flatten_symbols
+    - var_linker       : link_variables_to_functions
+    - scc              : tarjan_scc
+    - level_graph      : ordering helpers
+    - callee_summary   : build_callee_context_summary
+
+Change history:
+    1. 2026-11-02 (v0.8.3): Split into the modules above. Fixed the
+       redundant SCC re-queueing in ranking (see level_graph.py).
+"""
+
+from typing import List
+
+from pystdoc.callee_summary import build_callee_context_summary
+from pystdoc.call_graph_nodes import SymbolNode, flatten_symbols
+from pystdoc.level_graph import (
+    assemble_levels,
+    assign_scc_groups,
+    build_callee_edges,
+    build_condensation,
+    index_nodes,
+    rank_sccs,
+)
+from pystdoc.scc import tarjan_scc
+from pystdoc.symbols import get_kind_prefix
+from pystdoc.var_linker import link_variables_to_functions
+
+__all__ = [
+    "SymbolNode",
+    "flatten_symbols",
+    "link_variables_to_functions",
+    "tarjan_scc",
+    "order_symbols_by_levels",
+    "order_symbols_bottom_up",
+    "build_callee_context_summary",
+]
+
+
+def order_symbols_by_levels(
+    nodes: List[SymbolNode],
+) -> List[List[SymbolNode]]:
+    """Partition symbol nodes into strictly dependency-safe levels."""
+    id_to_node, fqdn_to_ids, short_to_ids = index_nodes(nodes)
+    caller_to_callees = build_callee_edges(
+        nodes, id_to_node, fqdn_to_ids, short_to_ids
+    )
+
+    base_nodes = [n for n in nodes if get_kind_prefix(n.symbol.kind) != "fn"]
+    for node in base_nodes:
+        node.dag_level = 0
+    fn_ids = [
+        n.unique_id for n in nodes if get_kind_prefix(n.symbol.kind) == "fn"
+    ]
+
+    sccs = tarjan_scc(fn_ids, caller_to_callees)
+    node_to_scc_idx = assign_scc_groups(sccs, id_to_node)
+    scc_callees, scc_callers = build_condensation(
+        node_to_scc_idx, caller_to_callees
+    )
+    scc_rank = rank_sccs(len(sccs), scc_callees, scc_callers)
+    return assemble_levels(base_nodes, sccs, scc_rank, id_to_node)
+
+
+def order_symbols_bottom_up(nodes: List[SymbolNode]) -> List[SymbolNode]:
+    """Flattened bottom-up order."""
+    flat: List[SymbolNode] = []
+    for level in order_symbols_by_levels(nodes):
+        flat.extend(level)
+    return flat

pystdoc-0.8.4/src/pystdoc/call_graph_nodes.py

@@ -0,0 +1,77 @@
+"""SymbolNode data structure and symbol flattening.
+
+Purpose:
+    Define the flat graph node (SymbolNode) and convert a hierarchical
+    Symbol tree into a flat list of nodes with unique IDs and FQDNs.
+
+Change history:
+    1. 2026-11-02 (v0.8.3): Split out of call_graph.py (no logic change).
+"""
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+from pystdoc.symbols import Symbol, get_kind_prefix
+
+
+@dataclass
+class SymbolNode:
+    symbol: Symbol
+    rel_path: Path
+    full_path: Path
+    unique_id: str
+    fqdn: str = ""
+    direct_callee_ids: Set[str] = field(default_factory=set)
+    direct_caller_ids: Set[str] = field(default_factory=set)
+    scc_group_ids: List[str] = field(default_factory=list)
+    dag_level: int = 0
+
+
+def flatten_symbols(
+    symbols: List[Symbol],
+    rel_path: Path,
+    full_path: Path,
+    prefix: str = "",
+    seen_ids: Optional[Dict[str, int]] = None,
+) -> List[SymbolNode]:
+    """Recursively collect symbols into flat list with FQDN and prefixes."""
+    if seen_ids is None:
+        seen_ids = defaultdict(int)
+    nodes: List[SymbolNode] = []
+    for sym in symbols:
+        k_prefix = get_kind_prefix(sym.kind)
+        raw_name = f"{prefix}{sym.name}" if prefix else sym.name
+        identifier = f"{k_prefix}.{raw_name}"
+        base_uid = f"{rel_path.as_posix()}::{identifier}"
+        seen_ids[base_uid] += 1
+        if seen_ids[base_uid] == 1:
+            uid = base_uid
+        else:
+            uid = f"{base_uid}#{seen_ids[base_uid]}"
+
+        base_mod = rel_path.with_suffix("").as_posix().replace("/", ".")
+        fqdn = sym.fqdn or f"{base_mod}.{raw_name}"
+
+        node = SymbolNode(
+            symbol=sym,
+            rel_path=rel_path,
+            full_path=full_path,
+            unique_id=uid,
+            fqdn=fqdn,
+            direct_callee_ids=set(),
+            scc_group_ids=[],
+            dag_level=0,
+        )
+        nodes.append(node)
+        if sym.children:
+            child_nodes = flatten_symbols(
+                sym.children,
+                rel_path,
+                full_path,
+                prefix=f"{raw_name}.",
+                seen_ids=seen_ids,
+            )
+            nodes.extend(child_nodes)
+    return nodes

pystdoc-0.8.4/src/pystdoc/callee_summary.py

@@ -0,0 +1,66 @@
+"""Callee context summary builder for LLM prompts.
+
+Purpose:
+    Build a text summary of directly called functions and mutual
+    recursion peers of a symbol node, used as bottom-up LLM context.
+
+Change history:
+    1. 2026-11-02 (v0.8.3): Split out of call_graph.py (no logic change).
+"""
+
+from typing import Dict, List
+
+from pystdoc.call_graph_nodes import SymbolNode
+
+
+def build_callee_context_summary(
+    node: SymbolNode,
+    resolved_symbols: Dict[str, SymbolNode],
+) -> str:
+    """Build summary text of called functions and recursion peers for LLM."""
+    lines: List[str] = []
+
+    if node.scc_group_ids:
+        peer_names = []
+        for peer_id in node.scc_group_ids:
+            peer_node = resolved_symbols.get(peer_id)
+            if peer_node:
+                peer_names.append(
+                    f"`{peer_node.symbol.name}` ({peer_node.rel_path.name})"
+                )
+        if peer_names:
+            lines.append("[Mutual Recursion Group]:")
+            lines.append(
+                f"- Note: This function operates in mutual recursion "
+                f"with {', '.join(peer_names)}."
+            )
+            lines.append("")
+
+    if node.direct_callee_ids:
+        lines.append("[Direct Callees Summary]:")
+        for callee_id in sorted(node.direct_callee_ids):
+            callee_node = resolved_symbols.get(callee_id)
+            if callee_node:
+                sym = callee_node.symbol
+                purpose = sym.purpose or "Executes operation"
+                params_str = ", ".join(
+                    f"{p.name}: {p.type_hint}" for p in sym.parameters
+                )
+                inputs = sym.inputs_note or params_str or "None"
+                outputs = sym.outputs_note or sym.return_type or "None"
+                fqdn_str = sym.fqdn or sym.name
+                lines.append(
+                    f"- Function `{sym.name}` (FQDN: `{fqdn_str}`, "
+                    f"File: `{callee_node.rel_path.name}`):"
+                )
+                lines.append(f"  - Purpose: {purpose}")
+                lines.append(f"  - Inputs: {inputs}")
+                lines.append(f"  - Outputs: {outputs}")
+                if sym.overview:
+                    first_lines = sym.overview.strip().splitlines()[:2]
+                    summary_str = " / ".join(
+                        line_item.strip() for line_item in first_lines
+                    )
+                    lines.append(f"  - Summary: {summary_str}")
+
+    return "\n".join(lines)

pystdoc-0.8.4/src/pystdoc/doc_labels.py

@@ -0,0 +1,171 @@
+"""Documentation label localization and JSON template management."""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+DEFAULT_ENGLISH_LABELS: Dict[str, str] = {
+    "language": "English",
+    "doc_title_template": "{kind} Documentation: `{name}`",
+    "basic_info_title": "## 1. Basic Information",
+    "label_name": "Name",
+    "label_fqdn": "FQDN",
+    "label_symbol_kind": "Symbol Kind",
+    "label_location": "Location",
+    "location_template": "Line {start} to Line {end}",
+    "label_signature": "Signature / Type",
+    "parameters_title": "## 2. Parameters",
+    "label_none": "None",
+    "input_return_title": "## 3. Input / Return Specifications",
+    "label_input_constraints": "Input Constraints",
+    "label_return_type": "Return Type",
+    "label_return_value_side_effects": "Return Value & Side Effects",
+    "label_void_none": "void / None",
+    "called_functions_title": "## 4. Called Functions",
+    "referencing_functions_title": "## 4. Referencing Functions",
+    "source_code_snippet_title": "## Source Code Snippet",
+    "file_doc_title_template": "File Documentation: `{path}`",
+    "label_file_hash": "File SHA-256",
+    "label_detected_symbols": "Detected Symbols",
+    "symbol_list_title": "## Symbol List",
+    "symbol_list_item_template": "- `{name}` ({kind}) [Lines: {line_range}]",
+    "kind_function": "Function",
+    "kind_class": "Class",
+    "kind_method": "Method",
+    "kind_variable": "Variable",
+    "kind_struct": "Struct",
+    "kind_enum": "Enum",
+    "kind_interface": "Interface",
+    "kind_constant": "Constant",
+    "kind_type": "Type",
+    "kind_module": "Module",
+    "prose_referenced_by_template": (
+        "In the system architecture, it is referenced by {callers}."
+    ),
+    "prose_root_entry_point": (
+        "It serves as the root entry point (system bootstrap and dispatcher)."
+    ),
+    "prose_implementation_overview_template": (
+        "Implementation overview: {overview}"
+    ),
+}
+
+
+def get_default_labels(language: str = "English") -> Dict[str, str]:
+    """Return default dictionary of documentation labels (English base)."""
+    return dict(DEFAULT_ENGLISH_LABELS)
+
+
+def translate_labels_with_llm(
+    llm_client: Any,
+    target_language: str,
+) -> Dict[str, str]:
+    """Translate documentation labels to target_language using LLM."""
+    from pystdoc.llm_client import extract_json_from_text
+
+    base_labels = dict(DEFAULT_ENGLISH_LABELS)
+    base_labels["language"] = target_language
+
+    system_prompt = (
+        "You are an expert technical documentation localizer. "
+        f"Translate software documentation labels and headings into natural, "
+        f"standard software engineering terms in {target_language}.\n"
+        "Guidelines:\n"
+        "- In Japanese software engineering, documentation is conventionally "
+        "called '仕様書' (e.g. '関数仕様書' for Function Documentation, "
+        "'クラス仕様書' for Class Documentation, "
+        "'ファイル仕様書' for File Documentation).\n"
+        "- When translating into Japanese, translate `doc_title_template` "
+        "as '{kind}仕様書: `{name}`', `file_doc_title_template` as "
+        "'ファイル仕様書: `{path}`', `kind_function` as '関数', "
+        "`kind_class` as 'クラス', `kind_method` as 'メソッド', "
+        "`kind_variable` as '変数', `kind_struct` as '構造体', "
+        "`kind_enum` as '列挙型', `kind_constant` as '定数'.\n"
+        "- For other languages, translate software terms idiomatic to that "
+        "language (e.g. Funktion in German, 函数 in Chinese).\n"
+        "- Keep placeholders {kind}, {name}, {path}, {start}, {end}, "
+        "{line_range}, {callers}, {overview} exactly as is.\n"
+        "- Respond strictly with a valid JSON object matching the input keys."
+    )
+    user_prompt = (
+        f"Translate the following JSON documentation labels into "
+        f"{target_language}:\n\n"
+        f"```json\n"
+        f"{json.dumps(base_labels, indent=2, ensure_ascii=False)}\n"
+        f"```\n\n"
+        f"Output ONLY valid JSON."
+    )
+
+    try:
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+        response_text = llm_client.chat_completion(messages)
+        parsed = extract_json_from_text(response_text)
+        if isinstance(parsed, dict) and len(parsed) >= 5:
+            merged = dict(base_labels)
+            for k, v in parsed.items():
+                if k in merged and isinstance(v, str) and v.strip():
+                    merged[k] = v.strip()
+            merged["language"] = target_language
+            return merged
+    except Exception:
+        pass
+
+    return base_labels
+
+
+def get_or_init_document_labels(
+    target_dir: Optional[Path],
+    language: str = "English",
+    llm_client: Optional[Any] = None,
+) -> Dict[str, str]:
+    """Load or initialize document_labels.json under target_dir/.pystdoc/."""
+    from pystdoc.doc_writer import normalize_language
+
+    norm_lang = normalize_language(language)
+    defaults = get_default_labels(norm_lang)
+
+    if target_dir is None:
+        return defaults
+
+    pystdoc_dir = target_dir / ".pystdoc"
+    labels_file = pystdoc_dir / "document_labels.json"
+
+    if labels_file.exists():
+        try:
+            content = labels_file.read_text(encoding="utf-8")
+            loaded = json.loads(content)
+            if (
+                isinstance(loaded, dict)
+                and loaded.get("language") == norm_lang
+            ):
+                merged = dict(defaults)
+                merged.update(loaded)
+                return merged
+        except Exception:
+            pass
+
+    # If language is not English, generate localized labels via LLM
+    final_labels = defaults
+    if norm_lang != "English" and llm_client is not None:
+        try:
+            print(
+                f"[Labels] Generating localized document labels for "
+                f"{norm_lang} via LLM...",
+                flush=True,
+            )
+            final_labels = translate_labels_with_llm(llm_client, norm_lang)
+        except Exception:
+            final_labels = defaults
+
+    # Save initial labels JSON for the target language
+    try:
+        pystdoc_dir.mkdir(parents=True, exist_ok=True)
+        content = json.dumps(final_labels, indent=2, ensure_ascii=False) + "\n"
+        labels_file.write_text(content, encoding="utf-8")
+    except Exception:
+        pass
+
+    return final_labels