ai-docs-gen 0.1.2__py3-none-any.whl

ai_docs/cache.py

@@ -0,0 +1,52 @@
+import json
+from pathlib import Path
+from typing import Dict, Tuple
+
+from .utils import ensure_dir
+
+
+class CacheManager:
+    def __init__(self, cache_dir: Path):
+        self.cache_dir = cache_dir
+        ensure_dir(self.cache_dir)
+        self.index_path = self.cache_dir / "index.json"
+        self.llm_cache_path = self.cache_dir / "llm_cache.json"
+
+    def load_index(self) -> Dict:
+        if not self.index_path.exists():
+            return {"files": {}, "sections": {}}
+        return json.loads(self.index_path.read_text(encoding="utf-8", errors="ignore"))
+
+    def save_index(self, data: Dict) -> None:
+        self.index_path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def load_llm_cache(self) -> Dict[str, str]:
+        if not self.llm_cache_path.exists():
+            return {}
+        return json.loads(self.llm_cache_path.read_text(encoding="utf-8", errors="ignore"))
+
+    def save_llm_cache(self, data: Dict[str, str]) -> None:
+        self.llm_cache_path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def diff_files(self, current_files: Dict[str, Dict]) -> Tuple[Dict, Dict, Dict, Dict]:
+        prev = self.load_index().get("files", {})
+        added = {}
+        modified = {}
+        deleted = {}
+        unchanged = {}
+
+        for path, meta in current_files.items():
+            if path not in prev:
+                added[path] = meta
+                continue
+            if prev[path].get("hash") != meta.get("hash"):
+                modified[path] = meta
+            else:
+                unchanged[path] = meta
+
+        for path, meta in prev.items():
+            if path not in current_files:
+                deleted[path] = meta
+
+        return added, modified, deleted, unchanged
+

ai_docs/changes.py

@@ -0,0 +1,25 @@
+from typing import Dict, List
+
+
+def format_changes_md(added: Dict, modified: Dict, deleted: Dict, regenerated_sections: List[str], summary: str) -> str:
+    def _fmt_list(title: str, items: Dict) -> str:
+        if not items:
+            return f"## {title}\n\n- нет\n"
+        lines = "\n".join([f"- {path}" for path in sorted(items.keys())])
+        return f"## {title}\n\n{lines}\n"
+
+    md = "# Изменения с последней генерации\n\n"
+    md += _fmt_list("Добавленные файлы", added)
+    md += _fmt_list("Изменённые файлы", modified)
+    md += _fmt_list("Удалённые файлы", deleted)
+
+    md += "## Перегенерированные разделы\n\n"
+    if regenerated_sections:
+        md += "\n".join([f"- {name}" for name in regenerated_sections]) + "\n"
+    else:
+        md += "- нет\n"
+
+    md += "\n## Краткое резюме\n\n"
+    md += summary.strip() + "\n"
+    return md
+

ai_docs/cli.py

@@ -0,0 +1,84 @@
+import argparse
+import os
+from pathlib import Path
+from typing import Optional, Set
+
+import shutil
+
+from .generator import generate_docs
+from .llm import from_env
+from .scanner import scan_source
+from .utils import is_url
+from dotenv import load_dotenv
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Generate README + MkDocs documentation for a code/config repository.")
+    parser.add_argument("--source", required=True, help="Path to local folder or git URL")
+    parser.add_argument("--output", help="Output root directory. Defaults to source for local paths, or ./output/<repo> for URLs")
+    parser.add_argument("--readme", action="store_true", help="Generate README.md")
+    parser.add_argument("--mkdocs", action="store_true", help="Generate MkDocs docs site")
+    parser.add_argument("--language", default="ru", help="Language for generated docs (ru|en)")
+    parser.add_argument("--include", nargs="*", help="Include patterns (glob)")
+    parser.add_argument("--exclude", nargs="*", help="Exclude patterns (glob)")
+    parser.add_argument("--max-size", type=int, default=200_000, help="Max file size in bytes")
+    parser.add_argument("--cache-dir", default=".ai_docs_cache", help="Cache directory")
+    parser.add_argument("--no-cache", action="store_true", help="Disable LLM cache")
+    parser.add_argument("--threads", type=int, default=None, help="Number of parallel LLM workers")
+    parser.add_argument("--local-site", action="store_true", help="Generate MkDocs config for local run")
+    parser.add_argument("--force", action="store_true", help="Overwrite README.md if it already exists")
+    return parser.parse_args()
+
+
+def resolve_output(source: str, output: Optional[str], repo_name: str) -> Path:
+    if output:
+        return Path(output).expanduser().resolve()
+    source_path = Path(source).expanduser().resolve()
+    if source_path.exists():
+        return source_path
+    return Path("output") / repo_name
+
+
+def main() -> None:
+    load_dotenv()
+    args = parse_args()
+    include: Optional[Set[str]] = set(args.include) if args.include else None
+    exclude: Optional[Set[str]] = set(args.exclude) if args.exclude else None
+
+    scan_result = scan_source(args.source, include=include, exclude=exclude, max_size=args.max_size)
+    root = scan_result.root
+    repo_name = scan_result.repo_name
+    print(f"[ai-docs] scan complete: {len(scan_result.files)} files")
+
+    output_root = resolve_output(args.source, args.output, repo_name)
+    output_root.mkdir(parents=True, exist_ok=True)
+
+    llm = from_env()
+    print(f"[ai-docs] llm: model={llm.model} context={llm.context_limit} max_tokens={llm.max_tokens}")
+
+    env_threads = int(os.getenv("AI_DOCS_THREADS", "1"))
+    env_local_site = os.getenv("AI_DOCS_LOCAL_SITE", "false").strip().lower() in {"1", "true", "yes", "y"}
+    threads = args.threads if args.threads is not None else env_threads
+    local_site = args.local_site or env_local_site
+
+    print(f"[ai-docs] generate: readme={args.readme or not args.mkdocs} mkdocs={args.mkdocs or not args.readme}")
+    generate_docs(
+        files=scan_result.files,
+        output_root=output_root,
+        cache_dir=output_root / args.cache_dir,
+        llm=llm,
+        language=args.language,
+        write_readme=(args.readme or not args.mkdocs),
+        write_mkdocs=(args.mkdocs or not args.readme),
+        use_cache=not args.no_cache,
+        threads=max(1, threads),
+        local_site=local_site,
+        force=args.force,
+    )
+
+    if is_url(args.source):
+        shutil.rmtree(scan_result.root, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

ai_docs/domain.py

@@ -0,0 +1,206 @@
+from pathlib import Path
+from typing import Set
+
+
+CODE_EXTENSION_DESCRIPTIONS = {
+    ".py": "Python",
+    ".pyi": "Python (типизация)",
+    ".pyx": "Cython",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript (JSX)",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript (TSX)",
+    ".go": "Go",
+    ".java": "Java",
+    ".c": "C",
+    ".cc": "C++",
+    ".cpp": "C++",
+    ".h": "C/C++ Header",
+    ".hpp": "C++ Header",
+    ".rs": "Rust",
+    ".rb": "Ruby",
+    ".php": "PHP",
+    ".cs": "C#",
+    ".kt": "Kotlin",
+    ".kts": "Kotlin (Script)",
+    ".swift": "Swift",
+    ".m": "Objective-C",
+    ".mm": "Objective-C++",
+    ".vb": "Visual Basic",
+    ".bas": "BASIC",
+    ".sql": "SQL",
+    ".pas": "Pascal",
+    ".dpr": "Delphi/Pascal",
+    ".pp": "Pascal",
+    ".r": "R",
+    ".pl": "Perl",
+    ".pm": "Perl Module",
+    ".f": "Fortran",
+    ".for": "Fortran",
+    ".f90": "Fortran",
+    ".f95": "Fortran",
+    ".f03": "Fortran",
+    ".f08": "Fortran",
+    ".sb3": "Scratch",
+    ".adb": "Ada",
+    ".ads": "Ada (Spec)",
+    ".asm": "Assembly",
+    ".s": "Assembly",
+    ".ino": "Arduino",
+    ".htm": "HTML",
+    ".html": "HTML",
+    ".css": "CSS",
+}
+
+DOC_EXTENSION_DESCRIPTIONS = {
+    ".md": "Markdown",
+    ".rst": "reStructuredText",
+    ".adoc": "AsciiDoc",
+    ".txt": "Text",
+}
+
+CONFIG_EXTENSION_DESCRIPTIONS = {
+    ".yml": "YAML",
+    ".yaml": "YAML",
+    ".json": "JSON",
+    ".toml": "TOML",
+    ".ini": "INI",
+    ".cfg": "Config",
+    ".conf": "Config",
+    ".env": "Environment",
+    ".properties": "Properties",
+}
+
+CODE_EXTENSIONS = set(CODE_EXTENSION_DESCRIPTIONS)
+DOC_EXTENSIONS = set(DOC_EXTENSION_DESCRIPTIONS)
+CONFIG_EXTENSIONS = set(CONFIG_EXTENSION_DESCRIPTIONS)
+
+DATA_EXTENSIONS = {".csv", ".tsv", ".parquet", ".avro", ".jsonl"}
+
+
+K8S_FILENAMES = {
+    "deployment.yaml", "deployment.yml", "service.yaml", "service.yml",
+    "ingress.yaml", "ingress.yml", "kustomization.yaml", "kustomization.yml",
+}
+
+CI_FILENAMES = {".gitlab-ci.yml", "Jenkinsfile", "azure-pipelines.yml"}
+CI_PATH_MARKERS = {".github/workflows", ".circleci", ".buildkite"}
+CI_FILENAMES_EXTRA = {"bitbucket-pipelines.yml", "buildkite.yml", "pipeline.yml"}
+
+
+HELM_FILENAMES = {"Chart.yaml", "Chart.yml", "values.yaml", "values.yml"}
+
+
+DOCKER_FILENAMES = {"Dockerfile", "docker-compose.yml", "docker-compose.yaml", "compose.yaml", "compose.yml"}
+
+OBSERVABILITY_FILENAMES = {
+    "prometheus.yml", "prometheus.yaml", "alertmanager.yml", "alertmanager.yaml",
+    "loki.yml", "loki.yaml", "promtail.yml", "promtail.yaml", "tempo.yml", "tempo.yaml",
+    "otel-collector.yml", "otel-collector.yaml", "opentelemetry-collector.yml", "opentelemetry-collector.yaml",
+    "jaeger.yml", "jaeger.yaml", "zipkin.yml", "zipkin.yaml",
+}
+OBSERVABILITY_PATH_MARKERS = {
+    "prometheus", "grafana", "loki", "tempo", "otel", "opentelemetry",
+    "jaeger", "zipkin", "logstash", "fluentd", "fluent-bit",
+}
+SERVICE_MESH_MARKERS = {
+    "istio", "linkerd", "consul", "cilium", "envoy", "traefik", "nginx-ingress",
+    "service-mesh", "servicemesh", "ingress", "gateway",
+}
+DATA_STORAGE_MARKERS = {
+    "postgres", "mysql", "mariadb", "redis", "mongo", "mongodb", "cassandra",
+    "clickhouse", "elasticsearch", "opensearch", "kafka", "minio", "s3",
+}
+
+TERRAFORM_EXTENSIONS = {".tf", ".tfvars"}
+
+
+def classify_type(path: Path) -> str:
+    name = path.name
+    suffix = path.suffix.lower()
+    if name in DOCKER_FILENAMES or name.startswith("Dockerfile"):
+        return "infra"
+    if name in CI_FILENAMES or name in CI_FILENAMES_EXTRA or any(marker in path.as_posix() for marker in CI_PATH_MARKERS):
+        return "ci"
+    if suffix in TERRAFORM_EXTENSIONS:
+        return "infra"
+    if suffix in CODE_EXTENSIONS:
+        return "code"
+    if suffix in DOC_EXTENSIONS:
+        return "docs"
+    if suffix in CONFIG_EXTENSIONS:
+        return "config"
+    if suffix in DATA_EXTENSIONS:
+        return "data"
+    return "other"
+
+
+def detect_domains(path: Path, content_snippet: str) -> Set[str]:
+    domains: Set[str] = set()
+    posix_path = path.as_posix()
+    name = path.name
+    suffix = path.suffix.lower()
+    content = content_snippet or ""
+
+    if name in DOCKER_FILENAMES or name.startswith("Dockerfile"):
+        domains.add("docker")
+
+    if "docker" in posix_path and (suffix in {".yml", ".yaml"} or name.startswith("Dockerfile")):
+        domains.add("docker")
+
+    if name in CI_FILENAMES or name in CI_FILENAMES_EXTRA or any(marker in posix_path for marker in CI_PATH_MARKERS):
+        domains.add("ci")
+
+    if name in HELM_FILENAMES or "charts/" in posix_path or "/templates/" in posix_path:
+        domains.add("helm")
+
+    if suffix in TERRAFORM_EXTENSIONS or "terraform" in posix_path:
+        domains.add("terraform")
+
+    if "ansible" in posix_path or "/roles/" in posix_path or "/tasks/" in posix_path:
+        domains.add("ansible")
+
+    if name in K8S_FILENAMES or "k8s" in posix_path or "kubernetes" in posix_path:
+        domains.add("kubernetes")
+
+    if suffix in {".yml", ".yaml"}:
+        if "apiVersion" in content and "kind" in content:
+            domains.add("kubernetes")
+
+    if name in OBSERVABILITY_FILENAMES or any(marker in posix_path for marker in OBSERVABILITY_PATH_MARKERS):
+        domains.add("observability")
+
+    if any(marker in posix_path for marker in SERVICE_MESH_MARKERS):
+        domains.add("service_mesh")
+        if "ingress" in posix_path:
+            domains.add("kubernetes")
+
+    if suffix in {".yml", ".yaml"}:
+        if "kind: Ingress" in content or "kind: Gateway" in content:
+            domains.add("service_mesh")
+            domains.add("kubernetes")
+        if "VirtualService" in content or "DestinationRule" in content or "ServiceEntry" in content:
+            domains.add("service_mesh")
+
+    if any(marker in posix_path for marker in DATA_STORAGE_MARKERS):
+        domains.add("data_storage")
+
+    return domains
+
+
+def is_infra(domains: Set[str]) -> bool:
+    return bool(
+        domains.intersection(
+            {
+                "kubernetes",
+                "helm",
+                "terraform",
+                "ansible",
+                "docker",
+                "ci",
+                "observability",
+                "service_mesh",
+                "data_storage",
+            }
+        )
+    )