pystdoc 0.2.0__py3-none-any.whl

pystdoc/__init__.py

@@ -0,0 +1,3 @@
+"""pystdoc: Python Structural & Topological Documentation Engine."""
+
+__version__ = "0.2.0"

pystdoc/cache.py

@@ -0,0 +1,38 @@
+"""Cache storage and atomic write operations with immediate disk sync."""
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+def write_flushed_text(file_path: Path, text: str) -> None:
+    """Write text to file with immediate directory creation, flush, and fsync."""
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(file_path, "w", encoding="utf-8") as f:
+        f.write(text)
+        f.flush()
+        os.fsync(f.fileno())
+
+
+def save_symbol_cache(target_dir: Path, unique_id: str, data: Dict[str, Any]) -> Path:
+    """Save symbol LLM analysis result to json cache file with immediate sync."""
+    safe_name = re.sub(r"[^\w\-.]", "_", unique_id)
+    cache_dir = target_dir / ".docgen" / "cache"
+    cache_file = cache_dir / f"{safe_name}.json"
+    content = json.dumps(data, ensure_ascii=False, indent=2)
+    write_flushed_text(cache_file, content)
+    return cache_file
+
+
+def load_symbol_cache(target_dir: Path, unique_id: str) -> Optional[Dict[str, Any]]:
+    """Load cached LLM analysis data for a symbol."""
+    safe_name = re.sub(r"[^\w\-.]", "_", unique_id)
+    cache_file = target_dir / ".docgen" / "cache" / f"{safe_name}.json"
+    if cache_file.exists():
+        try:
+            return json.loads(cache_file.read_text(encoding="utf-8"))
+        except Exception:
+            return None
+    return None

pystdoc/call_graph.py

@@ -0,0 +1,277 @@
+"""Call graph construction, Tarjan SCC cycle condensation, FQDN matching, and Level-by-Level DAG parallel ordering."""
+
+import re
+from collections import defaultdict, deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+
+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)
+    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 = "",
+) -> List[SymbolNode]:
+    """Recursively collect all symbols into a flat list of SymbolNodes with FQDN and kind prefixes."""
+    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}"
+        uid = f"{rel_path.as_posix()}::{identifier}"
+
+        fqdn = sym.fqdn or f"{rel_path.with_suffix('').as_posix().replace('/', '.')}.{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}.",
+            )
+            nodes.extend(child_nodes)
+    return nodes
+
+
+def link_variables_to_functions(nodes: List[SymbolNode]) -> None:
+    """Detect which functions directly reference each variable using FQDN and scope matching."""
+    fn_nodes = [n for n in nodes if get_kind_prefix(n.symbol.kind) == "fn"]
+    var_nodes = [n for n in nodes if get_kind_prefix(n.symbol.kind) == "var"]
+
+    for v_node in var_nodes:
+        v_name = v_node.symbol.name
+        ref_funcs: Set[str] = set()
+
+        for f_node in fn_nodes:
+            if f_node.rel_path == v_node.rel_path:
+                if f_node.symbol.line_start <= v_node.symbol.line_start <= f_node.symbol.line_end:
+                    ref_funcs.add(f"`{f_node.symbol.name}` (`{f_node.rel_path.name}`)")
+                    continue
+
+            try:
+                code_lines = f_node.full_path.read_text(encoding="utf-8", errors="replace").splitlines()
+                start = max(0, f_node.symbol.line_start - 1)
+                end = min(len(code_lines), f_node.symbol.line_end)
+                func_code = "\n".join(code_lines[start:end])
+
+                if re.search(rf"\b{re.escape(v_name)}\b", func_code):
+                    ref_funcs.add(f"`{f_node.symbol.name}` (`{f_node.rel_path.name}`)")
+            except Exception:
+                pass
+
+        v_node.symbol.referencing_functions = sorted(list(ref_funcs))
+
+
+def tarjan_scc(node_ids: List[str], adj: Dict[str, Set[str]]) -> List[List[str]]:
+    """Tarjan's strongly connected components algorithm in O(V+E) time."""
+    index = 0
+    indices: Dict[str, int] = {}
+    lowlinks: Dict[str, int] = {}
+    on_stack: Set[str] = set()
+    stack: List[str] = []
+    sccs: List[List[str]] = []
+
+    def strongconnect(v: str) -> None:
+        nonlocal index
+        indices[v] = index
+        lowlinks[v] = index
+        index += 1
+        stack.append(v)
+        on_stack.add(v)
+
+        for w in adj.get(v, set()):
+            if w not in indices:
+                strongconnect(w)
+                lowlinks[v] = min(lowlinks[v], lowlinks[w])
+            elif w in on_stack:
+                lowlinks[v] = min(lowlinks[v], indices[w])
+
+        if lowlinks[v] == indices[v]:
+            scc: List[str] = []
+            while True:
+                w = stack.pop()
+                on_stack.remove(w)
+                scc.append(w)
+                if w == v:
+                    break
+            sccs.append(scc)
+
+    for node_id in node_ids:
+        if node_id not in indices:
+            strongconnect(node_id)
+
+    return sccs
+
+
+def order_symbols_by_levels(nodes: List[SymbolNode]) -> List[List[SymbolNode]]:
+    """Partition symbol nodes into strictly dependency-safe levels for parallel processing."""
+    id_to_node: Dict[str, SymbolNode] = {n.unique_id: n for n in nodes}
+    fqdn_to_node_ids: Dict[str, List[str]] = defaultdict(list)
+    short_name_to_ids: Dict[str, List[str]] = defaultdict(list)
+
+    for node in nodes:
+        short_name_to_ids[node.symbol.name].append(node.unique_id)
+        if node.fqdn:
+            fqdn_to_node_ids[node.fqdn].append(node.unique_id)
+        if "::" in node.unique_id:
+            sym_part = node.unique_id.split("::", 1)[1]
+            raw_without_prefix = sym_part.split(".", 1)[-1] if "." in sym_part else sym_part
+            short_name_to_ids[raw_without_prefix].append(node.unique_id)
+
+    caller_to_callees: Dict[str, Set[str]] = {n.unique_id: set() for n in nodes}
+
+    for node in nodes:
+        prefix_type = get_kind_prefix(node.symbol.kind)
+        if prefix_type == "fn":
+            for callee_name in node.symbol.callees:
+                matched_ids = fqdn_to_node_ids.get(callee_name, [])
+                if not matched_ids:
+                    matched_ids = short_name_to_ids.get(callee_name, [])
+
+                for target_id in matched_ids:
+                    if target_id != node.unique_id and get_kind_prefix(id_to_node[target_id].symbol.kind) == "fn":
+                        caller_to_callees[node.unique_id].add(target_id)
+                        node.direct_callee_ids.add(target_id)
+
+    base_types_and_vars = [n for n in nodes if get_kind_prefix(n.symbol.kind) in ("const", "type", "var")]
+    for n in base_types_and_vars:
+        n.dag_level = 0
+
+    fn_nodes = [n for n in nodes if get_kind_prefix(n.symbol.kind) == "fn"]
+    fn_ids = [n.unique_id for n in fn_nodes]
+
+    # Tarjan SCC
+    sccs = tarjan_scc(fn_ids, caller_to_callees)
+
+    node_to_scc_idx: Dict[str, int] = {}
+    for scc_idx, scc_members in enumerate(sccs):
+        for member_id in scc_members:
+            node_to_scc_idx[member_id] = scc_idx
+            if len(scc_members) > 1:
+                id_to_node[member_id].scc_group_ids = [m for m in scc_members if m != member_id]
+
+    # Condensation DAG construction
+    scc_callees: Dict[int, Set[int]] = defaultdict(set)
+    scc_callers: Dict[int, Set[int]] = defaultdict(set)
+
+    for caller_id, callee_ids in caller_to_callees.items():
+        if caller_id not in node_to_scc_idx:
+            continue
+        c_scc = node_to_scc_idx[caller_id]
+        for callee_id in callee_ids:
+            if callee_id not in node_to_scc_idx:
+                continue
+            target_scc = node_to_scc_idx[callee_id]
+            if target_scc != c_scc:
+                scc_callees[c_scc].add(target_scc)
+                scc_callers[target_scc].add(c_scc)
+
+    # Bottom-up topological ranking
+    scc_rank: Dict[int, int] = {}
+    queue = deque([i for i in range(len(sccs)) if len(scc_callees[i]) == 0])
+    for i in queue:
+        scc_rank[i] = 0
+
+    resolved_sccs = set(queue)
+    while queue:
+        curr_scc = queue.popleft()
+        for parent_scc in scc_callers[curr_scc]:
+            if scc_callees[parent_scc].issubset(resolved_sccs):
+                max_child_rank = max(scc_rank[c] for c in scc_callees[parent_scc])
+                scc_rank[parent_scc] = max_child_rank + 1
+                resolved_sccs.add(parent_scc)
+                queue.append(parent_scc)
+
+    for i in range(len(sccs)):
+        if i not in scc_rank:
+            scc_rank[i] = 0
+
+    # Assign DAG levels
+    level_groups: Dict[int, List[SymbolNode]] = defaultdict(list)
+    if base_types_and_vars:
+        level_groups[0].extend(base_types_and_vars)
+
+    for scc_idx, members in enumerate(sccs):
+        rank = scc_rank[scc_idx]
+        node_level = rank + (1 if base_types_and_vars else 0)
+        for member_id in members:
+            node = id_to_node[member_id]
+            node.dag_level = node_level
+            level_groups[node_level].append(node)
+
+    max_lvl = max(level_groups.keys()) if level_groups else 0
+    levels_list = [level_groups[i] for i in range(max_lvl + 1) if level_groups[i]]
+    return levels_list
+
+
+def order_symbols_bottom_up(nodes: List[SymbolNode]) -> List[SymbolNode]:
+    """Flattened bottom-up order."""
+    levels = order_symbols_by_levels(nodes)
+    flat: List[SymbolNode] = []
+    for lvl in levels:
+        flat.extend(lvl)
+    return flat
+
+
+def build_callee_context_summary(
+    node: SymbolNode,
+    resolved_symbols: Dict[str, SymbolNode],
+) -> str:
+    """Build summary text of called low-level functions and mutual recursion peers for LLM prompt."""
+    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 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"
+                inputs = sym.inputs_note or ", ".join(f"{p.name}: {p.type_hint}" for p in sym.parameters) or "None"
+                outputs = sym.outputs_note or sym.return_type or "None"
+                lines.append(f"- Function `{sym.name}` (FQDN: `{sym.fqdn or sym.name}`, 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]
+                    lines.append(f"  - Summary: {' / '.join(l.strip() for l in first_lines)}")
+
+    return "\n".join(lines)

pystdoc/cli.py

@@ -0,0 +1,184 @@
+"""Command-line interface entry points for docgen, designgen, and reportgen with multi-language support."""
+
+import argparse
+import sys
+from pathlib import Path
+
+import pystdoc
+from pystdoc.engine import run_docgen
+from pystdoc.design_engine import run_design_generation
+from pystdoc.report_engine import generate_readme_doc
+
+
+def docgen_main() -> None:
+    """CLI entry point for `docgen` command."""
+    parser = argparse.ArgumentParser(description="Source code symbol document generator (docgen)")
+    parser.add_argument("--version", "-v", action="version", version=f"%(prog)s {pystdoc.__version__}")
+    parser.add_argument("--dir", default="./", help="Target project directory path (default: ./)")
+    parser.add_argument("--no-llm", action="store_true", help="Disable LLM explanation generation")
+    parser.add_argument("--host", "-H", default=None, help="LLM server host URL (default: http://127.0.0.1:11434)")
+    parser.add_argument("--base-url", "-b", default=None, help="Alias for --host")
+    parser.add_argument("--model", "-m", default="gemma4-26b-a4b", help="LLM model identifier (default: gemma4-26b-a4b)")
+    parser.add_argument("--token", default=None, help="API token / key (or env OPENAI_API_KEY / LLM_TOKEN)")
+    parser.add_argument("--api-key", default=None, help="Alias for --token")
+    parser.add_argument("--context-size", "--ctx-size", type=int, default=16384, help="LLM context window size (default: 16384)")
+    parser.add_argument("--language", "-l", default="English", help="Output documentation language (e.g. English, Japanese) (default: English)")
+    parser.add_argument("--force", "-f", action="store_true", help="Force regenerate all documents ignoring cache")
+    parser.add_argument("--allow-fallback", action="store_true", help="Allow fallback to static template on LLM failure")
+    parser.add_argument("--compile-commands", default=None, help="Path to compile_commands.json (auto-detected if omitted)")
+    parser.add_argument("--concurrency", "-j", type=int, default=4, help="Number of parallel LLM workers (default: 4)")
+
+    args = parser.parse_args()
+    sys.exit(
+        run_docgen(
+            target_dir=Path(args.dir),
+            use_llm=not args.no_llm,
+            host=args.host,
+            base_url=args.base_url,
+            model=args.model,
+            token=args.token,
+            api_key=args.api_key,
+            context_size=args.context_size,
+            language=args.language,
+            force=args.force,
+            allow_fallback=args.allow_fallback,
+            compile_commands_path=args.compile_commands,
+            concurrency=args.concurrency,
+        )
+    )
+
+
+def designgen_main() -> None:
+    """CLI entry point for `designgen` command."""
+    parser = argparse.ArgumentParser(description="Architecture and system design generator (designgen)")
+    parser.add_argument("--version", "-v", action="version", version=f"%(prog)s {pystdoc.__version__}")
+    parser.add_argument("--dir", default="./", help="Target project directory path (default: ./)")
+    parser.add_argument("--no-llm", action="store_true", help="Disable LLM explanation generation")
+    parser.add_argument("--host", "-H", default=None, help="LLM server host URL (default: http://127.0.0.1:11434)")
+    parser.add_argument("--base-url", "-b", default=None, help="Alias for --host")
+    parser.add_argument("--model", "-m", default="gemma4-26b-a4b", help="LLM model identifier (default: gemma4-26b-a4b)")
+    parser.add_argument("--token", default=None, help="API token / key (or env OPENAI_API_KEY / LLM_TOKEN)")
+    parser.add_argument("--api-key", default=None, help="Alias for --token")
+    parser.add_argument("--context-size", "--ctx-size", type=int, default=16384, help="LLM context window size (default: 16384)")
+    parser.add_argument("--language", "-l", default="English", help="Output documentation language (e.g. English, Japanese) (default: English)")
+    parser.add_argument("--force", "-f", action="store_true", help="Force regenerate all design documents ignoring cache")
+    parser.add_argument("--allow-fallback", action="store_true", help="Allow fallback to static template on LLM failure")
+
+    args = parser.parse_args()
+    sys.exit(
+        run_design_generation(
+            target_dir=Path(args.dir),
+            use_llm=not args.no_llm,
+            host=args.host,
+            base_url=args.base_url,
+            model=args.model,
+            token=args.token,
+            api_key=args.api_key,
+            context_size=args.context_size,
+            language=args.language,
+            force=args.force,
+            allow_fallback=args.allow_fallback,
+        )
+    )
+
+
+def reportgen_main() -> None:
+    """CLI entry point for `reportgen` and `pystdoc` commands."""
+    parser = argparse.ArgumentParser(description="Unified documentation orchestrator (reportgen / pystdoc)")
+    parser.add_argument("--version", "-v", action="version", version=f"%(prog)s {pystdoc.__version__}")
+    parser.add_argument("--dir", default="./", help="Target project directory path (default: ./)")
+    parser.add_argument("--no-llm", action="store_true", help="Disable LLM explanation generation")
+    parser.add_argument("--host", "-H", default=None, help="LLM server host URL (default: http://127.0.0.1:11434)")
+    parser.add_argument("--base-url", "-b", default=None, help="Alias for --host")
+    parser.add_argument("--model", "-m", default="gemma4-26b-a4b", help="LLM model identifier (default: gemma4-26b-a4b)")
+    parser.add_argument("--token", default=None, help="API token / key (or env OPENAI_API_KEY / LLM_TOKEN)")
+    parser.add_argument("--api-key", default=None, help="Alias for --token")
+    parser.add_argument("--context-size", "--ctx-size", type=int, default=16384, help="LLM context window size (default: 16384)")
+    parser.add_argument("--language", "-l", default="English", help="Output documentation language (e.g. English, Japanese) (default: English)")
+    parser.add_argument("--force", "-f", action="store_true", help="Force regenerate all documents ignoring cache")
+    parser.add_argument("--allow-fallback", action="store_true", help="Allow fallback to static template on LLM failure")
+    parser.add_argument("--compile-commands", default=None, help="Path to compile_commands.json (auto-detected if omitted)")
+    parser.add_argument("--concurrency", "-j", type=int, default=4, help="Number of parallel LLM workers (default: 4)")
+    parser.add_argument("--skip-docgen", action="store_true", help="Skip docgen step")
+    parser.add_argument("--skip-designgen", action="store_true", help="Skip designgen step")
+
+    args = parser.parse_args()
+    target_dir = Path(args.dir).resolve()
+
+    if not target_dir.exists() or not target_dir.is_dir():
+        print(f"Error: Specified directory does not exist: {target_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    print("================================================================")
+    print(f"=== pystdoc Unified Pipeline v{pystdoc.__version__} (Lang: {args.language}): {target_dir} ===")
+    print("================================================================")
+
+    # 1. docgen
+    if not args.skip_docgen:
+        print("\n>>> [Step 1/3] docgen: Parsing source code and generating symbol docs...")
+        ret_docgen = run_docgen(
+            target_dir=target_dir,
+            use_llm=not args.no_llm,
+            host=args.host,
+            base_url=args.base_url,
+            model=args.model,
+            token=args.token,
+            api_key=args.api_key,
+            context_size=args.context_size,
+            language=args.language,
+            force=args.force,
+            allow_fallback=args.allow_fallback,
+            compile_commands_path=args.compile_commands,
+            concurrency=args.concurrency,
+        )
+        if ret_docgen != 0:
+            sys.exit(ret_docgen)
+
+    # 2. designgen
+    if not args.skip_designgen:
+        print("\n>>> [Step 2/3] designgen: Synthesizing architecture and data models...")
+        ret_design = run_design_generation(
+            target_dir=target_dir,
+            use_llm=not args.no_llm,
+            host=args.host,
+            base_url=args.base_url,
+            model=args.model,
+            token=args.token,
+            api_key=args.api_key,
+            context_size=args.context_size,
+            language=args.language,
+            force=args.force,
+            allow_fallback=args.allow_fallback,
+        )
+        if ret_design != 0:
+            sys.exit(ret_design)
+
+    # 3. reportgen
+    print("\n>>> [Step 3/3] reportgen: Generating project overview README (.docgen/README.md)...")
+    from pystdoc.llm_client import LLMClient
+    llm_client = None
+    if not args.no_llm:
+        client = LLMClient(
+            host=args.host or args.base_url,
+            model=args.model,
+            token=args.token or args.api_key,
+            context_size=args.context_size,
+        )
+        if client.check_availability():
+            llm_client = client
+        elif not args.allow_fallback:
+            print(f"Error: Failed to connect to LLM server ({client.base_url}).", file=sys.stderr)
+            sys.exit(1)
+
+    generate_readme_doc(
+        target_dir=target_dir,
+        llm_client=llm_client,
+        language=args.language,
+        allow_fallback=args.allow_fallback,
+    )
+
+    out_readme = target_dir / ".docgen" / "README.md"
+    print("================================================================")
+    print(f"=== reportgen Finished: Created {out_readme} ===")
+    print("================================================================")
+    sys.exit(0)

pystdoc/compilation_db.py

@@ -0,0 +1,112 @@
+"""Compilation database (compile_commands.json) parser and compiler flags resolver."""
+
+import json
+import os
+import shlex
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+class CompilationDatabase:
+    """Compilation database resolver for C/C++ compilation flags."""
+
+    def __init__(self, db_path: Optional[Path] = None, target_dir: Optional[Path] = None):
+        self.flags_map: Dict[str, List[str]] = {}
+        self.loaded_path: Optional[Path] = None
+        self.target_dir = target_dir
+
+        # Auto-discover compile_commands.json
+        candidates = []
+        if db_path:
+            candidates.append(Path(db_path))
+        if target_dir:
+            candidates.extend([
+                target_dir / "compile_commands.json",
+                target_dir / "build" / "compile_commands.json",
+                target_dir / "builddir" / "compile_commands.json",
+            ])
+        candidates.extend([
+            Path("compile_commands.json"),
+            Path("build/compile_commands.json"),
+            Path("builddir/compile_commands.json"),
+        ])
+
+        for c in candidates:
+            if c.exists() and c.is_file():
+                try:
+                    self._load_db(c)
+                    self.loaded_path = c
+                    break
+                except Exception:
+                    continue
+
+    def _load_db(self, db_file: Path) -> None:
+        """Parse compile_commands.json and extract flags for each source file."""
+        data = json.loads(db_file.read_text(encoding="utf-8"))
+        for entry in data:
+            file_path = entry.get("file")
+            if not file_path:
+                continue
+
+            directory = entry.get("directory", "")
+            full_file = Path(directory) / file_path if directory else Path(file_path)
+            norm_key = full_file.resolve().as_posix()
+
+            # Extract arguments from command string or arguments list
+            raw_args = []
+            if "arguments" in entry:
+                raw_args = entry["arguments"]
+            elif "command" in entry:
+                raw_args = shlex.split(entry["command"])
+
+            # Filter valid flags for libclang
+            clang_args = []
+            skip_next = False
+            for i, arg in enumerate(raw_args[1:], start=1):
+                if skip_next:
+                    skip_next = False
+                    continue
+
+                if arg in ("-c", "-o"):
+                    skip_next = True
+                    continue
+                if arg.startswith("-o"):
+                    continue
+
+                if arg.startswith(("-I", "-D", "-U", "-isystem", "-std=", "-m", "-f")):
+                    if arg in ("-I", "-isystem") and i + 1 < len(raw_args):
+                        inc_path = raw_args[i + 1]
+                        if directory:
+                            inc_path = (Path(directory) / inc_path).resolve().as_posix()
+                        clang_args.append(f"{arg}{inc_path}")
+                        skip_next = True
+                    else:
+                        if arg.startswith("-I") and len(arg) > 2:
+                            inc_dir = arg[2:]
+                            if directory and not inc_dir.startswith("/"):
+                                inc_dir = (Path(directory) / inc_dir).resolve().as_posix()
+                            clang_args.append(f"-I{inc_dir}")
+                        else:
+                            clang_args.append(arg)
+
+            self.flags_map[norm_key] = clang_args
+            self.flags_map[Path(file_path).name] = clang_args
+
+    def get_flags_for_file(self, file_path: Path) -> List[str]:
+        """Get compilation flags for a given source file, or return smart defaults."""
+        norm_key = file_path.resolve().as_posix()
+        if norm_key in self.flags_map:
+            return self.flags_map[norm_key]
+        if file_path.name in self.flags_map:
+            return self.flags_map[file_path.name]
+
+        # Smart defaults with inferred include directories
+        base_dir = self.target_dir or file_path.parent
+        defaults = [
+            "-std=c11" if file_path.suffix in (".c", ".h") else "-std=c++17",
+            "-D_GNU_SOURCE",
+            f"-I{base_dir.resolve().as_posix()}",
+            f"-I{(base_dir / 'include').resolve().as_posix()}",
+            f"-I{(base_dir / 'src').resolve().as_posix()}",
+        ]
+        return defaults