source-kb 0.2.5__tar.gz → 0.2.26__tar.gz

{source_kb-0.2.5 → source_kb-0.2.26}/MANIFEST.in

@@ -1,15 +1,15 @@
-include LICENSE
-include README.en.md
-include pyproject.toml
-include setup.cfg
-
-recursive-include cli *.py
-recursive-include core *.py
-recursive-include presets *.yaml *.md *.py
-
-prune engine
-prune mcp_server
-prune skills
-prune tests
-prune docs
-prune .source-cache
+include LICENSE
+include README.en.md
+include pyproject.toml
+include setup.cfg
+
+recursive-include cli *.py
+recursive-include core *.py
+recursive-include presets *.yaml *.md *.py
+
+prune engine
+prune mcp_server
+prune skills
+prune tests
+prune docs
+prune .source-cache

{source_kb-0.2.5/source_kb.egg-info → source_kb-0.2.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: source-kb
-Version: 0.2.5
+Version: 0.2.26
 Summary: Auto-generate structured knowledge base documents from source code. Supports AI agent mode (skill-based) and standalone CLI.
 License-Expression: MIT
 Keywords: knowledge-base,documentation,code-analysis,llm,rag
@@ -61,15 +61,24 @@ Install the CLI toolchain:
 
 ```bash
 pip install source-kb[full]
+
+# If you have multiple Python versions, specify the target version:
+py -3.12 -m pip install source-kb[full]
+```
+
+Install skills to your Agent's directory:
+
+```bash
+source-kb install-skills --agent kiro     # Kiro
+source-kb install-skills --agent cursor   # Cursor
+source-kb install-skills --agent claude   # Claude Code
 ```
 
-Clone the presets repo into your project:
+This automatically installs `presets/` and `examples/` to `~/.source-kb/` (shared globally across all projects).
+To install global assets only:
 
 ```bash
-git clone https://github.com/anthropics/source-kb-presets.git
-cp -r source-kb-presets/skills ./skills
-cp -r source-kb-presets/presets ./presets
-cp -r source-kb-presets/examples ./examples
+source-kb install-skills --assets-only   # Install presets/ + examples/ to ~/.source-kb/
 ```
 
 Then talk to your AI Agent (Kiro / Claude Code / Cursor / Windsurf):

{source_kb-0.2.5 → source_kb-0.2.26}/README.en.md

@@ -28,15 +28,24 @@ Install the CLI toolchain:
 
 ```bash
 pip install source-kb[full]
+
+# If you have multiple Python versions, specify the target version:
+py -3.12 -m pip install source-kb[full]
+```
+
+Install skills to your Agent's directory:
+
+```bash
+source-kb install-skills --agent kiro     # Kiro
+source-kb install-skills --agent cursor   # Cursor
+source-kb install-skills --agent claude   # Claude Code
 ```
 
-Clone the presets repo into your project:
+This automatically installs `presets/` and `examples/` to `~/.source-kb/` (shared globally across all projects).
+To install global assets only:
 
 ```bash
-git clone https://github.com/anthropics/source-kb-presets.git
-cp -r source-kb-presets/skills ./skills
-cp -r source-kb-presets/presets ./presets
-cp -r source-kb-presets/examples ./examples
+source-kb install-skills --assets-only   # Install presets/ + examples/ to ~/.source-kb/
 ```
 
 Then talk to your AI Agent (Kiro / Claude Code / Cursor / Windsurf):

{source_kb-0.2.5 → source_kb-0.2.26}/README.md

@@ -28,15 +28,24 @@
 
 ```bash
 pip install source-kb[full]
+
+# 如果系统有多个 Python 版本，指定目标版本安装：
+py -3.12 -m pip install source-kb[full]
+```
+
+一键安装 Skill 到 Agent 目录：
+
+```bash
+source-kb install-skills --agent kiro     # Kiro
+source-kb install-skills --agent cursor   # Cursor
+source-kb install-skills --agent claude   # Claude Code
 ```
 
-克隆 presets 仓库到你的项目中：
+安装过程会自动将 `presets/` 和 `examples/` 安装到 `~/.source-kb/`（全局共享，所有项目通用）。
+如需单独安装全局资产：
 
 ```bash
-git clone https://github.com/anthropics/source-kb-presets.git
-cp -r source-kb-presets/skills ./skills
-cp -r source-kb-presets/presets ./presets
-cp -r source-kb-presets/examples ./examples
+source-kb install-skills --assets-only   # 仅安装 presets/ + examples/ 到 ~/.source-kb/
 ```
 
 在 AI Agent（Kiro / Claude Code / Cursor / Windsurf）中直接对话：

{source_kb-0.2.5 → source_kb-0.2.26}/cli/__init__.py

@@ -23,10 +23,31 @@ def _discover_commands(subparsers: argparse._SubParsersAction) -> None:
             module.register(subparsers)
 
 
+def _warn_python_version() -> None:
+    """Warn if tree-sitter-languages is unavailable (Python 3.13+)."""
+    v = sys.version_info
+    if v >= (3, 13):
+        try:
+            import tree_sitter_languages  # noqa: F401
+        except ImportError:
+            print(
+                f"[WARNING] Python {v.major}.{v.minor} detected. "
+                f"tree-sitter-languages has no wheel for 3.13+, "
+                f"skeleton extraction will fall back to regex (lower accuracy).\n"
+                f"  Recommended: py -3.12 -m pip install source-kb[full]",
+                file=sys.stderr,
+            )
+
+
 def main(argv: list[str] | None = None) -> None:
     sys.stdout.reconfigure(encoding="utf-8")
     sys.stderr.reconfigure(encoding="utf-8")
 
+    _warn_python_version()
+
+    from cli.global_assets import ensure_global_assets
+    ensure_global_assets()
+
     from core import __version__
 
     parser = argparse.ArgumentParser(

{source_kb-0.2.5 → source_kb-0.2.26}/cli/__main__.py

@@ -1,4 +1,5 @@
 """Allow running as: python -m cli"""
+from __future__ import annotations
 
 from cli import main
 

source_kb-0.2.26/cli/commands/anchor_fix.py

@@ -0,0 +1,126 @@
+"""source-kb anchor-fix — Fix broken cross-document anchor links."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("anchor-fix", help="Fix broken cross-document anchor links")
+    p.add_argument("--module-dir", required=True, help="Module documentation directory")
+    p.add_argument("--dry-run", action="store_true", help="Report without fixing")
+    p.add_argument("--threshold", type=float, default=0.8, help="Fuzzy match threshold (0.0-1.0)")
+    p.add_argument("--detect-cascade", metavar="FILE",
+                   help="Detect cascade: check which links break due to title changes in FILE")
+    p.add_argument("--old-content", help="Path to old version of file (for --detect-cascade)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    module_dir = Path(args.module_dir)
+    if not module_dir.is_dir():
+        print(f"Error: directory not found: {module_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    if getattr(args, "detect_cascade", None):
+        _run_detect_cascade(args, module_dir)
+    else:
+        _run_fix(args, module_dir)
+
+
+def _run_fix(args: argparse.Namespace, module_dir: Path) -> None:
+    from core.skeleton.anchor_fix import fix_anchors
+
+    result = fix_anchors(
+        module_dir,
+        dry_run=args.dry_run,
+        similarity_threshold=args.threshold,
+    )
+
+    mode = " (dry-run)" if args.dry_run else ""
+    print(f"Anchor fix{mode}: scanned {result.files_scanned} files, checked {result.links_checked} links")
+    if result.links_fixed or result.links_degraded:
+        print(f"  Fixed: {result.links_fixed}, Degraded: {result.links_degraded}")
+        for d in result.details:
+            action = "fixed" if d["action"] == "fixed" else "degraded"
+            print(f"  [{action}] {d['file']}: {d['old_link']} -> {d['new_link']}")
+    else:
+        print("  All links valid.")
+
+    print(json.dumps({
+        "status": "ok", "files_scanned": result.files_scanned,
+        "links_checked": result.links_checked, "links_fixed": result.links_fixed,
+        "links_degraded": result.links_degraded,
+    }, ensure_ascii=False), file=sys.stderr)
+
+
+def _run_detect_cascade(args: argparse.Namespace, module_dir: Path) -> None:
+    from core.skeleton.anchor_fix import detect_cascade
+
+    changed_file = args.detect_cascade
+    target_path = module_dir / changed_file
+
+    if not target_path.exists():
+        print(f"Error: {changed_file} not found in {module_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    new_content = target_path.read_text(encoding="utf-8", errors="replace")
+
+    if args.old_content:
+        old_path = Path(args.old_content)
+        if not old_path.exists():
+            print(f"Error: old content file not found: {old_path}", file=sys.stderr)
+            sys.exit(1)
+        old_content = old_path.read_text(encoding="utf-8", errors="replace")
+    else:
+        # Try git to get previous version
+        try:
+            import subprocess
+            result = subprocess.run(
+                ["git", "show", f"HEAD:{changed_file}"],
+                cwd=str(module_dir), capture_output=True, text=True, timeout=10,
+            )
+            if result.returncode == 0:
+                old_content = result.stdout
+            else:
+                print("Error: --old-content required (git HEAD version not available)",
+                      file=sys.stderr)
+                sys.exit(1)
+        except Exception:
+            print("Error: --old-content required (git not available)", file=sys.stderr)
+            sys.exit(1)
+
+    cascade = detect_cascade(
+        module_dir, changed_file, old_content, new_content,
+        similarity_threshold=args.threshold,
+    )
+
+    if not cascade.removed_anchors and not cascade.renamed_anchors:
+        print(f"No title changes detected in {changed_file}")
+        print(json.dumps({"status": "ok", "cascade": False}, ensure_ascii=False),
+              file=sys.stderr)
+        return
+
+    print(f"Cascade detection for {changed_file}:")
+    if cascade.renamed_anchors:
+        print(f"  Renamed ({len(cascade.renamed_anchors)}):")
+        for r in cascade.renamed_anchors:
+            print(f"    #{r['old']} -> #{r['new']} (score={r['score']})")
+    if cascade.removed_anchors:
+        print(f"  Removed ({len(cascade.removed_anchors)}):")
+        for a in cascade.removed_anchors:
+            print(f"    #{a}")
+    if cascade.affected_links:
+        print(f"  Affected links ({len(cascade.affected_links)}):")
+        for link in cascade.affected_links:
+            print(f"    {link['file']}: {link['link']}")
+
+    print(json.dumps({
+        "status": "cascade_detected",
+        "renamed": len(cascade.renamed_anchors),
+        "removed": len(cascade.removed_anchors),
+        "affected_links": len(cascade.affected_links),
+    }, ensure_ascii=False), file=sys.stderr)

source_kb-0.2.26/cli/commands/audit.py

@@ -0,0 +1,53 @@
+"""source-kb audit — Low-confidence classification audit."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("audit", help="Low-confidence classification audit")
+    p.add_argument("--skeleton", required=True, help="Skeleton JSON path")
+    p.add_argument("--preset", required=True, help="Preset name")
+    p.add_argument("--threshold", type=float, default=0.7, help="Confidence threshold (default: 0.7)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.classify import find_suspicious_files
+    from core.preset import load_preset
+    from core.skeleton.query import load_skeleton
+
+    preset = load_preset(args.preset)
+    skeleton_path = Path(args.skeleton)
+    entries = load_skeleton(skeleton_path)
+    threshold = args.threshold
+
+    suspicious = find_suspicious_files(entries, preset, threshold=threshold)
+
+    if suspicious:
+        print(f"Found {len(suspicious)} low-confidence files (threshold < {threshold}):\n")
+        print("| File | Category | Confidence | Match Reason | Suspicious Signal |")
+        print("|------|------|--------|---------|---------|")
+        for entry in suspicious:
+            cats = ", ".join(entry.categories) if entry.categories else "-"
+            reasons = "; ".join(entry.match_reasons[:2]) if entry.match_reasons else "-"
+            signals = "; ".join(entry.suspicious_signals[:2]) if entry.suspicious_signals else "-"
+            print(f"| {entry.file} | {cats} | {entry.confidence:.2f} | {reasons} | {signals} |")
+    else:
+        print(f"No low-confidence files (threshold < {threshold})")
+
+    from core.history import record_global_event
+    skeleton_dir = skeleton_path.parent
+    knowledge_dir = skeleton_dir.parent if skeleton_dir.name == ".meta" else skeleton_dir
+    record_global_event(
+        knowledge_dir, "audit",
+        docs_updated=[skeleton_path.name],
+        trigger="cli",
+    )
+
+    print(json.dumps({"status": "ok", "suspicious": len(suspicious),
+                      "threshold": threshold}, ensure_ascii=False), file=sys.stderr)

source_kb-0.2.26/cli/commands/check_triggers.py

@@ -0,0 +1,69 @@
+"""source-kb check-triggers — Detect optional document triggers from changed files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(
+        "check-triggers",
+        help="Detect optional documents triggered by source changes",
+    )
+    p.add_argument("--module-dir", required=True, help="Module documentation directory")
+    p.add_argument("--preset", default="java-spring", help="Preset name")
+    p.add_argument("--files", nargs="+", help="Changed source files to scan")
+    p.add_argument("--source-cache", help="Source cache directory (reads files from here)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.preset import load_preset
+    from core.docs.trigger_detect import detect_triggers_from_dir
+
+    module_dir = Path(args.module_dir)
+    preset = load_preset(args.preset)
+
+    changed_files: dict[str, str] = {}
+
+    if args.files:
+        source_base = Path(args.source_cache) if args.source_cache else Path(".")
+        for filepath in args.files:
+            full_path = source_base / filepath
+            if full_path.exists():
+                try:
+                    changed_files[filepath] = full_path.read_text(encoding="utf-8", errors="replace")
+                except OSError:
+                    pass
+
+    if not changed_files:
+        print("No changed files to scan.")
+        print(json.dumps({"status": "ok", "triggers": []}, ensure_ascii=False),
+              file=sys.stderr)
+        return
+
+    triggers = detect_triggers_from_dir(changed_files, preset, module_dir)
+
+    if not triggers:
+        print("No optional document triggers detected.")
+        print(json.dumps({"status": "ok", "triggers": []}, ensure_ascii=False),
+              file=sys.stderr)
+        return
+
+    print(f"Detected {len(triggers)} document trigger(s):")
+    for t in triggers:
+        action_label = "CREATE" if t["action"] == "create" else "UPDATE"
+        print(f"  [{action_label}] {t['filename']} ({t['doc_type']})")
+        for m in t["matches"][:3]:
+            print(f"    matched '{m['keyword']}' in {m['file']}")
+
+    print(json.dumps({
+        "status": "ok",
+        "triggers": [
+            {"doc_type": t["doc_type"], "filename": t["filename"], "action": t["action"]}
+            for t in triggers
+        ],
+    }, ensure_ascii=False), file=sys.stderr)

source_kb-0.2.26/cli/commands/detect.py

@@ -0,0 +1,44 @@
+"""source-kb detect — Detect project language, framework, and structure."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(
+        "detect",
+        help="Detect project language, framework, structure, and modules",
+    )
+    p.add_argument("--path", default=".", help="Path to source repo (default: current dir)")
+    p.add_argument("--json", action="store_true", dest="as_json", help="Output as JSON")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.bootstrap import detect_project, format_detection_summary
+
+    repo_path = Path(args.path).resolve()
+    if not repo_path.is_dir():
+        print(f"Error: path does not exist: {repo_path}")
+        sys.exit(1)
+
+    info = detect_project(repo_path)
+
+    if args.as_json:
+        data = {
+            "language": info.language,
+            "framework": info.framework,
+            "preset": info.preset,
+            "structure": info.structure,
+            "repo_name": info.repo_name,
+            "modules": [
+                {"name": m.name, "path": m.path, "type": m.module_type, "description": m.description}
+                for m in info.modules
+            ],
+        }
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+    else:
+        print(format_detection_summary(info))

{source_kb-0.2.5 → source_kb-0.2.26}/cli/commands/dispatch.py

@@ -34,14 +34,27 @@ def run(args: argparse.Namespace) -> None:
 
     module_name = args.module
     module_dir = knowledge_dir / module_name
-    source_cache = cache_dir / module_name
 
     module_type = "service"
-    repos = source.get("repos", [])
-    for repo in repos:
-        if repo.get("name") == module_name:
-            module_type = repo.get("type", "service")
+    source_cache = cache_dir / module_name
+
+    modules = kb_config.get("modules", [])
+    for mod in modules:
+        if mod.get("name") == module_name:
+            module_type = mod.get("module_type", mod.get("type", "service"))
+            repo_name = mod.get("repo", module_name)
+            mod_path = mod.get("path", ".")
+            if mod_path and mod_path != ".":
+                source_cache = cache_dir / repo_name / mod_path
+            else:
+                source_cache = cache_dir / repo_name
             break
+    else:
+        repos = source.get("repos", [])
+        for repo in repos:
+            if repo.get("name") == module_name:
+                module_type = repo.get("type", "service")
+                break
 
     mode = args.mode
 

source_kb-0.2.26/cli/commands/history_cmd.py

@@ -0,0 +1,94 @@
+"""source-kb history — Show operation history for a module or knowledge base."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("history", help="Show operation history")
+    p.add_argument("--config", help="kb-project.yaml path")
+    p.add_argument("--kb", required=True, help="Knowledge base name")
+    p.add_argument("--module", help="Module name (omit for global changelog)")
+    p.add_argument("--limit", type=int, default=20, help="Max entries (default: 20)")
+    p.add_argument("--json", dest="as_json", action="store_true", help="Output as JSON")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.config import load_config, find_config
+    from core.history import get_module_history, get_global_changelog
+
+    config_path = Path(args.config) if args.config else find_config()
+    config = load_config(config_path)
+    kb_cfg = config.get_kb(args.kb)
+
+    knowledge_dir = Path(kb_cfg.get("knowledge_dir", f"./knowledge/{args.kb}"))
+    if not knowledge_dir.is_absolute():
+        config_dir = Path(config.raw.get("_config_dir", ".")).resolve()
+        knowledge_dir = (config_dir / knowledge_dir).resolve()
+
+    if not knowledge_dir.is_dir():
+        print(f"Error: knowledge directory not found: {knowledge_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.module:
+        module_dir = knowledge_dir / args.module
+        if not module_dir.is_dir():
+            print(f"Error: module not found: {module_dir}", file=sys.stderr)
+            sys.exit(1)
+        entries = get_module_history(module_dir, limit=args.limit)
+        scope = f"{args.kb}/{args.module}"
+    else:
+        entries = get_global_changelog(knowledge_dir, limit=args.limit)
+        scope = f"{args.kb} (global)"
+
+    if args.as_json:
+        print(json.dumps(entries, ensure_ascii=False, indent=2))
+        return
+
+    if not entries:
+        print(f"No history for {scope}")
+        print(json.dumps({"status": "ok", "entries": 0}, ensure_ascii=False), file=sys.stderr)
+        return
+
+    print(f"History: {scope} (showing {len(entries)}/{args.limit} max)\n")
+
+    for entry in entries:
+        ts = _format_ts(entry.get("ts", ""))
+        op = entry.get("op", "?")
+        doc_type = entry.get("doc_type", "")
+        version = entry.get("version")
+        modules = entry.get("modules_affected", [])
+
+        line = f"  {ts}  {op:<12}"
+        if doc_type:
+            line += f" {doc_type}"
+        if version is not None:
+            line += f" v{version}"
+        if modules:
+            line += f" [{', '.join(modules[:3])}]"
+
+        stats = entry.get("stats", {})
+        if stats:
+            delta = stats.get("delta", "")
+            if delta:
+                line += f" ({delta})"
+
+        print(line)
+
+    print(json.dumps({"status": "ok", "entries": len(entries)}, ensure_ascii=False), file=sys.stderr)
+
+
+def _format_ts(ts: str) -> str:
+    if not ts:
+        return "            "
+    try:
+        dt = datetime.fromisoformat(ts)
+        return dt.strftime("%Y-%m-%d %H:%M")
+    except (ValueError, TypeError):
+        return ts[:16]

{source_kb-0.2.5 → source_kb-0.2.26}/cli/commands/index.py

@@ -35,14 +35,12 @@ def run_index(args: argparse.Namespace) -> None:
     knowledge_dir = Path(kb_cfg["knowledge_dir"])
     collection_name = kb_cfg["collection"]
 
-    incremental = bool(args.module or args.files)
-    if args.module:
-        knowledge_dir = knowledge_dir / args.module
+    module = args.module
 
     if args.files:
-        docs = load_documents(knowledge_dir, file_filter=args.files)
+        docs = load_documents(knowledge_dir, module=module, files=args.files)
     else:
-        docs = load_documents(knowledge_dir)
+        docs = load_documents(knowledge_dir, module=module)
 
     if not docs:
         print(f"No documents found in {knowledge_dir}")
@@ -51,8 +49,22 @@ def run_index(args: argparse.Namespace) -> None:
 
     chunks = chunk_documents(docs)
     print(f"Indexing {len(docs)} docs, {len(chunks)} chunks...")
-    build_index(chunks, collection_name, config, kb_name=args.kb, incremental=incremental)
+    build_index(chunks, collection_name, config, kb_name=args.kb, module=module, files=args.files)
     print(f"Index built: {len(chunks)} chunks -> collection '{collection_name}'")
+
+    from core.history import mark_indexed, record_global_event, refresh_kb_state
+    if module:
+        module_dir = knowledge_dir / module
+        if module_dir.is_dir():
+            mark_indexed(module_dir, config.embed_model, len(chunks), collection=collection_name)
+    else:
+        for d in sorted(knowledge_dir.iterdir()):
+            if d.is_dir() and not d.name.startswith(".") and (d / ".meta").is_dir():
+                mark_indexed(d, config.embed_model, len(chunks), collection=collection_name)
+
+    record_global_event(knowledge_dir, "index", trigger="cli")
+    refresh_kb_state(knowledge_dir)
+
     print(json.dumps({"status": "ok", "docs": len(docs), "chunks": len(chunks),
                       "collection": collection_name}, ensure_ascii=False), file=sys.stderr)