@ngocsangairvds/vsaf 4.1.7 → 4.1.9

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/docs/consumption/__init__.py

@@ -1,7 +0,0 @@
-"""Doc consumption analytics package."""
-
-from __future__ import annotations
-
-from vds_cli.docs.consumption.scanner import DocRead, scan_consumption
-
-__all__ = ["DocRead", "scan_consumption"]

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/docs/consumption/funnel.py

@@ -1,105 +0,0 @@
-"""Aggregate and summarize doc-consumption funnel data."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import UTC, datetime, timedelta
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from vds_cli.docs.consumption.scanner import DocRead
-
-
-@dataclass(frozen=True)
-class FunnelRow:
-    path: Path
-    reads: int
-    unique_sessions: int
-    last_read: datetime | None
-    diataxis: str | None
-
-
-@dataclass(frozen=True)
-class FunnelStageSummary:
-    stage: str
-    read_count: int
-    unique_docs: int
-
-
-def aggregate_reads(doc_reads: list[DocRead]) -> list[FunnelRow]:
-    """Group DocRead events by path, counting reads and unique sessions."""
-    groups: dict[Path, dict] = {}
-    for dr in doc_reads:
-        if dr.path not in groups:
-            groups[dr.path] = {
-                "reads": 0,
-                "sessions": set(),
-                "last_read": None,
-                "diataxis": dr.diataxis,
-            }
-        info = groups[dr.path]
-        info["reads"] += 1
-        info["sessions"].add(dr.session_id)
-        if info["last_read"] is None or dr.read_at > info["last_read"]:
-            info["last_read"] = dr.read_at
-    return [
-        FunnelRow(
-            path=path,
-            reads=info["reads"],
-            unique_sessions=len(info["sessions"]),
-            last_read=info["last_read"],
-            diataxis=info["diataxis"],
-        )
-        for path, info in sorted(groups.items())
-    ]
-
-
-def dead_weight(docs: list[DocRead], window_days: int) -> list[FunnelRow]:
-    """Return docs with zero reads inside the look-back window."""
-    now = datetime.now(UTC)
-    cutoff = now - timedelta(days=window_days)
-    in_window = [d for d in docs if d.read_at >= cutoff]
-    aggregated = {r.path: r for r in aggregate_reads(in_window)}
-    all_paths = {d.path for d in docs}
-    result: list[FunnelRow] = []
-    for path in sorted(all_paths):
-        if path in aggregated:
-            continue
-        diataxis = next((d.diataxis for d in docs if d.path == path), None)
-        result.append(
-            FunnelRow(
-                path=path,
-                reads=0,
-                unique_sessions=0,
-                last_read=None,
-                diataxis=diataxis,
-            )
-        )
-    return result
-
-
-def funnel_summary(rows: list[FunnelRow]) -> list[FunnelStageSummary]:
-    """Aggregate FunnelRows into per-Diátaxis stage summaries."""
-    counts: dict[str, dict[str, int]] = {}
-    for row in rows:
-        stage = row.diataxis if row.diataxis is not None else "uncategorized"
-        if stage not in counts:
-            counts[stage] = {"read_count": 0, "unique_docs": 0}
-        counts[stage]["read_count"] += row.reads
-        counts[stage]["unique_docs"] += 1
-
-    standard = ["tutorial", "how-to", "reference", "explanation"]
-    for stage in standard:
-        if stage not in counts:
-            counts[stage] = {"read_count": 0, "unique_docs": 0}
-
-    ordered = standard + [s for s in sorted(counts) if s not in standard]
-    return [
-        FunnelStageSummary(
-            stage=stage,
-            read_count=counts[stage]["read_count"],
-            unique_docs=counts[stage]["unique_docs"],
-        )
-        for stage in ordered
-    ]

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/docs/consumption/scanner.py

@@ -1,211 +0,0 @@
-"""Scan Claude session JSONL files to discover doc consumption events."""
-
-from __future__ import annotations
-
-import json
-import logging
-import re
-from dataclasses import dataclass
-from datetime import UTC, datetime
-from pathlib import Path
-
-logger = logging.getLogger(__name__)
-
-_ALLOWED_TOOLS = frozenset({"Read", "Grep", "Glob"})
-_DIATAXIS_RE = re.compile(r"<!--\s*di[\u00e1\u00e0]taxis:\s*([\w-]+)\s*-->", re.IGNORECASE)
-
-
-@dataclass(frozen=True)
-class DocRead:
-    path: Path
-    session_id: str
-    read_at: datetime
-    diataxis: str | None
-
-
-def _slugify(text: str) -> str:
-    """Simple slug: lowercase, non-alnum -> hyphen, strip edges."""
-    text = text.lower()
-    text = re.sub(r"[^a-z0-9]+", "-", text)
-    text = text.strip("-")
-    return text or "unknown"
-
-
-def _redact_home(path: Path) -> Path:
-    """Replace leading $HOME with ~ in a Path."""
-    try:
-        home = Path.home().resolve()
-        resolved = path.resolve()
-        if resolved == home or home in resolved.parents:
-            rel = resolved.relative_to(home)
-            return Path("~") / rel
-    except (RuntimeError, ValueError, OSError):
-        pass
-    return path
-
-
-def _extract_diataxis(file_path: Path) -> str | None:
-    """Read first 2 KiB of a markdown file and extract diátaxis quadrant."""
-    if file_path.suffix.lower() != ".md":
-        return None
-    try:
-        text = file_path.read_text(encoding="utf-8", errors="ignore")
-        m = _DIATAXIS_RE.search(text)
-        if m:
-            return m.group(1).lower()
-    except (OSError, UnicodeDecodeError):
-        pass
-    return None
-
-
-def _session_jsonl_paths(cwd: Path) -> list[Path]:
-    """Discover session JSONL files under ~/.claude/projects/<slugified-cwd>."""
-    try:
-        home = Path.home()
-    except RuntimeError:
-        return []
-
-    slug = _slugify(cwd.name)
-    projects_dir = home / ".claude" / "projects" / slug
-    if not projects_dir.exists():
-        return []
-
-    paths: list[Path] = []
-    for entry in projects_dir.iterdir():
-        if entry.is_file() and entry.suffix == ".jsonl" and not entry.name.startswith("."):
-            paths.append(entry)
-        elif entry.is_dir() and entry.name == "subagents":
-            for sub in entry.iterdir():
-                if sub.is_file() and sub.suffix == ".jsonl" and sub.name.startswith("agent-"):
-                    paths.append(sub)
-    return sorted(paths)
-
-
-def _parse_iso_timestamp(value: str | None) -> datetime:
-    """Parse an ISO-8601-ish string; fallback to now(UTC)."""
-    if not value:
-        return datetime.now(UTC)
-    try:
-        # Python 3.11+ fromisoformat handles 'Z' suffix; for safety strip it.
-        value = value.replace("Z", "+00:00")
-        return datetime.fromisoformat(value)
-    except (ValueError, TypeError):
-        return datetime.now(UTC)
-
-
-def _extract_file_paths(event: dict) -> list[str]:
-    """Yield file_path strings from a single JSONL event."""
-    if not isinstance(event, dict):
-        return []
-
-    if event.get("type") != "assistant":
-        return []
-
-    message = event.get("message") or {}
-    content_blocks = message.get("content") or []
-    if not isinstance(content_blocks, list):
-        return []
-
-    paths: list[str] = []
-    for block in content_blocks:
-        if not isinstance(block, dict):
-            continue
-        if block.get("type") != "tool_use":
-            continue
-        if block.get("name") not in _ALLOWED_TOOLS:
-            continue
-        tool_input = block.get("input") or {}
-        # Tolerate scalar file_path or list file_path(s)
-        raw = tool_input.get("file_path")
-        if isinstance(raw, str):
-            paths.append(raw)
-        elif isinstance(raw, list):
-            for item in raw:
-                if isinstance(item, str):
-                    paths.append(item)
-    return paths
-
-
-def scan_consumption(
-    repo_root: Path,
-    *,
-    cwd: Path | None = None,
-    session_dir: Path | None = None,
-) -> list[DocRead]:
-    """Scan Claude JSONL sessions and return deduplicated DocRead events.
-
-    Parameters
-    ----------
-    repo_root:
-        Root of the repository; used to resolve relative paths.
-    cwd:
-        Current working directory name used to build the default session path.
-        Defaults to ``Path.cwd()``.
-    session_dir:
-        Optional explicit directory containing ``*.jsonl`` files. When provided,
-        *cwd* is ignored for discovery.
-    """
-    repo_root = repo_root.resolve()
-    if session_dir is not None:
-        if session_dir.exists() and session_dir.is_dir():
-            jsonl_files = sorted(p for p in session_dir.iterdir() if p.is_file() and p.suffix == ".jsonl")
-        else:
-            jsonl_files = []
-    else:
-        if cwd is None:
-            cwd = Path.cwd()
-        jsonl_files = _session_jsonl_paths(cwd)
-
-    seen: set[tuple[str, str]] = set()
-    reads: list[DocRead] = []
-
-    for jsonl_path in jsonl_files:
-        session_id = jsonl_path.stem
-        try:
-            with jsonl_path.open("r", encoding="utf-8", errors="ignore") as fh:
-                for line in fh:
-                    line = line.strip()
-                    if not line:
-                        continue
-                    try:
-                        event = json.loads(line)
-                    except json.JSONDecodeError:
-                        logger.debug("Skipping malformed JSON line in %s", jsonl_path)
-                        continue
-
-                    file_paths = _extract_file_paths(event)
-                    if not file_paths:
-                        continue
-
-                    ts = _parse_iso_timestamp(event.get("timestamp"))
-
-                    for raw_path in file_paths:
-                        # Resolve relative to repo_root if not absolute
-                        p = Path(raw_path)
-                        if not p.is_absolute():
-                            p = repo_root / p
-                        p = p.resolve()
-
-                        # Redact HOME
-                        p = _redact_home(p)
-
-                        key = (str(p), session_id)
-                        if key in seen:
-                            continue
-                        seen.add(key)
-
-                        diataxis = _extract_diataxis(p) if p.is_absolute() else None
-
-                        reads.append(
-                            DocRead(
-                                path=p,
-                                session_id=session_id,
-                                read_at=ts,
-                                diataxis=diataxis,
-                            )
-                        )
-        except (OSError, PermissionError):
-            logger.debug("Cannot read session file %s", jsonl_path)
-            continue
-
-    return reads

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/docs/freshness/report.py

@@ -1,90 +0,0 @@
-"""Freshness report builder."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import TYPE_CHECKING, Literal
-
-if TYPE_CHECKING:
-    from vds_cli.docs.types import FreshnessIssue
-
-FreshnessStatus = Literal["stale", "draft", "orphan_vi", "fresh"]
-
-_DRAFT_MARKER = "<!-- draft-translation: needs-human-review -->"
-
-
-@dataclass(frozen=True)
-class FreshnessRow:
-    vi_path: Path
-    en_path: Path
-    en_mtime: datetime | None
-    vi_mtime: datetime | None
-    lag_days: int | None
-    draft_marker_present: bool
-    status: FreshnessStatus
-    max_lag_days: int
-
-
-def _file_mtime(path: Path) -> datetime | None:
-    if not path.exists():
-        return None
-    ts = path.stat().st_mtime
-    return datetime.fromtimestamp(ts, tz=UTC)
-
-
-def _has_draft_marker(path: Path) -> bool:
-    if not path.exists():
-        return False
-    try:
-        with path.open("r", encoding="utf-8") as fh:
-            for i, line in enumerate(fh):
-                if i >= 20:
-                    break
-                if _DRAFT_MARKER.lower() in line.lower():
-                    return True
-    except (OSError, UnicodeDecodeError):
-        return False
-    return False
-
-
-def classify(row: FreshnessRow, threshold: int | None, include_drafts: bool) -> FreshnessStatus:
-    if row.en_mtime is None:
-        return "orphan_vi"
-    if row.draft_marker_present and not include_drafts:
-        return "draft"
-    effective = threshold if threshold is not None else row.max_lag_days
-    if row.lag_days is not None and row.lag_days > effective:
-        return "stale"
-    return "fresh"
-
-
-def enrich(issues: list[FreshnessIssue]) -> list[FreshnessRow]:
-    rows: list[FreshnessRow] = []
-    for issue in issues:
-        vi_path = Path(issue.doc)
-        en_path = Path(issue.source)
-        en_mtime = _file_mtime(en_path)
-        vi_mtime = _file_mtime(vi_path)
-
-        if en_mtime is not None and vi_mtime is not None:
-            lag = max((en_mtime - vi_mtime).total_seconds() / 86400.0, 0.0)
-            lag_days = int(lag)
-        else:
-            lag_days = None
-
-        draft_marker_present = _has_draft_marker(vi_path)
-
-        row = FreshnessRow(
-            vi_path=vi_path,
-            en_path=en_path,
-            en_mtime=en_mtime,
-            vi_mtime=vi_mtime,
-            lag_days=lag_days,
-            draft_marker_present=draft_marker_present,
-            status="fresh",
-            max_lag_days=issue.max_lag_days,
-        )
-        rows.append(row)
-    return rows

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/docs/types.py

@@ -1,27 +0,0 @@
-"""Shared types for docs observability to resolve circular imports."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-
-
-@dataclass(frozen=True)
-class ValidationIssue:
-    repo: str
-    check: str
-    message: str
-    path: Path | None = None
-    fixed: bool = False
-
-
-@dataclass(frozen=True)
-class FreshnessIssue:
-    doc: str
-    source: str
-    max_lag_days: int
-    lag_days: float
-    message: str
-
-
-FreshnessStatus = str  # "fresh" | "stale" | "draft" | "orphan_vi"