docsweep 0.1.0__py3-none-any.whl

docsweep/auto_triage.py

@@ -0,0 +1,172 @@
+"""C5: auto-triage — md の状態遷移提案を LLM に委譲し、承認済みを一括適用する。
+
+設計:
+- ``suggest`` モード: md 本文 + 索引メタ + linkcheck 結果 を LLM に渡して
+  「[完了] / 維持 / [廃止] / 不明」と根拠を返してもらう
+- ``apply`` モード: 提案を ``engine.apply_action`` で一括実行する
+
+実 LLM は本 plan では呼ばない。``ruleset`` ベースの decider（フラグから推測）と
+Mock LLM 経路の両方を用意する。
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+from .config import Config
+from .engine import apply_action, run_scan
+from .linkcheck import linkcheck
+from .models import Action, FileRecord, Flag
+
+
+@dataclass
+class TriageSuggestion:
+    """1 ファイル分の遷移提案。"""
+
+    path: str
+    project: str
+    current_state: str | None
+    proposed_action: str  # "discard" / "keep" / "resume" / "relabel" / "promote" / "skip"
+    proposed_to: str | None  # relabel 時の宛先ラベル名（例 "[完了]"）
+    reason: str
+    confidence: float  # 0..1
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class TriageSuggestResult:
+    suggestions: list[TriageSuggestion] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {"suggestions": [s.to_dict() for s in self.suggestions]}
+
+
+def _ruleset_decide(rec: FileRecord, lc_progress: str | None) -> TriageSuggestion | None:
+    """ヒューリスティック decider。LLM 不要の最小実装。
+
+    判定ルール:
+      - linkcheck progress = "implemented" の plan → "promote" (完了候補)
+      - NEEDS_DECISION + age > 180 → "discard" 候補（陳腐化が長すぎる）
+      - state=watching + age > 14 → "promote" (release sweep 候補)
+      - それ以外 → 提案無し
+    """
+    flags = set(rec.flags or [])
+    age = rec.age_days or 0
+
+    if rec.type == "plan" and lc_progress == "implemented" and rec.state in {"planned", "in-progress"}:
+        return TriageSuggestion(
+            path=rec.path, project=rec.project, current_state=rec.state,
+            proposed_action="relabel",
+            proposed_to="[完了]",
+            reason="linkcheck で「変更予定ファイル」がほぼ実装済み + commit 言及あり",
+            confidence=0.75,
+        )
+
+    if Flag.NEEDS_DECISION.value in flags and age > 180:
+        return TriageSuggestion(
+            path=rec.path, project=rec.project, current_state=rec.state,
+            proposed_action="discard",
+            proposed_to=None,
+            reason=f"陳腐化フラグが立ってから 180 日超 (age={age}d) — 廃止判断を提案",
+            confidence=0.6,
+        )
+
+    if rec.state == "watching" and age > 14:
+        return TriageSuggestion(
+            path=rec.path, project=rec.project, current_state=rec.state,
+            proposed_action="promote",
+            proposed_to=None,
+            reason=f"様子見 → 完了 へ昇格候補 (age={age}d, release sweep に該当)",
+            confidence=0.5,
+        )
+
+    return None
+
+
+def suggest_transitions(
+    config: Config, *, target: str | None = None,
+) -> TriageSuggestResult:
+    """状態遷移提案を生成する。
+
+    Args:
+        config: ロード済み Config
+        target: 単一ファイルの相対パス / basename。None で全件
+
+    Returns:
+        ``TriageSuggestResult``。
+    """
+    # linkcheck 結果を map にまとめておく（plan 進捗を判断材料に）
+    lc_map: dict[str, str] = {}
+    for lc in linkcheck(config):
+        lc_map[lc.plan_path] = lc.progress_hint
+
+    result = run_scan(config)
+    suggestions: list[TriageSuggestion] = []
+    for doc in result.docs:
+        rec = doc.record
+        if target:
+            from pathlib import Path
+            t = Path(target)
+            if rec.path != str(t) and Path(rec.path).name != t.name:
+                continue
+        s = _ruleset_decide(rec, lc_map.get(rec.path))
+        if s is not None:
+            suggestions.append(s)
+    return TriageSuggestResult(suggestions=suggestions)
+
+
+@dataclass
+class ApplyResult:
+    applied: list[dict] = field(default_factory=list)
+    skipped: list[dict] = field(default_factory=list)
+    failed: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def apply_suggestions(
+    config: Config,
+    decisions: list[dict],
+    *,
+    dry_run: bool = False,
+) -> ApplyResult:
+    """承認済み提案を一括適用する。
+
+    Args:
+        config: ロード済み Config
+        decisions: ``[{path, action, to?}]`` のリスト。CLI / MCP で承認したものを渡す
+        dry_run: True で実際の移送/書換は行わず計画だけ返す
+
+    Returns:
+        ``ApplyResult``。
+    """
+    result = run_scan(config)
+    by_path = {d.record.path: d for d in result.docs}
+    applied: list[dict] = []
+    skipped: list[dict] = []
+    failed: list[dict] = []
+
+    for d in decisions:
+        path = d.get("path")
+        action = d.get("action")
+        to = d.get("to")
+        if not path or not action:
+            failed.append({"path": path, "reason": "path/action 欠落"})
+            continue
+        doc = by_path.get(path)
+        if doc is None:
+            failed.append({"path": path, "reason": "対象ファイルが見つからない"})
+            continue
+        if action == "skip":
+            skipped.append({"path": path})
+            continue
+        try:
+            entry = apply_action(doc, action, config, to=to, dry_run=dry_run)
+            applied.append(entry.to_dict())
+        except ValueError as e:
+            failed.append({"path": path, "reason": str(e)})
+
+    return ApplyResult(applied=applied, skipped=skipped, failed=failed)

docsweep/brief/__init__.py

@@ -0,0 +1,9 @@
+"""C3 (wings): brief — 「今日の 1 個」を断定する出口の双子（CLI / Web 共通基盤）。
+
+主役は :func:`service.build_brief` と :func:`score.score_record`。CLI/Web/MCP は全部この
+2 関数を経由する（再実装しない）。
+"""
+
+from .service import BriefResult, build_brief
+
+__all__ = ["BriefResult", "build_brief"]

docsweep/brief/score.py

@@ -0,0 +1,132 @@
+"""brief / cross 共通のスコア式（C3 + C4 共有モジュール）。
+
+「今日の 1 個」を決めるための単一スコア式を 1 か所に集める。式は ``score_record(rec)`` で
+1 つの FileRecord に対して float を返す。式自体は **断定する** ことを優先しており、
+同点時はタイブレーカ（``rec.path`` 昇順）でも必ず 1 件が決まる。
+
+設計指針:
+- 入力は ``FileRecord`` のみ（索引から復元された FileRecord でもそのまま動く）
+- 外部 LLM を呼ばない（決定性・速度のため）
+- フィールドの欠落は 0 として扱い、例外を投げない
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+from ..models import FileRecord, Flag
+
+# スコア重み — 「今日の 1 個」の意思決定要素ごとの寄与度。値の妥当性はテストで固定する。
+W_URGENCY = 40.0           # due 切れ・要判断（陳腐化）への重み
+W_STALE = 1.5              # 経過日数の寄与（1 日 = 1.5 点）
+W_REVIEW_STATUS = 5.0      # review_status 別の追加点（review > draft > published）
+W_TOUCHED_DECAY = 0.3      # 直近触ったものを下げる（同じファイルに張り付かない誘導）
+W_DEP_CHAIN = 8.0          # related の本数（プロジェクト中枢ファイルを浮かせる）
+
+# stale 寄与の上限日数（無制限だと古い凍結ファイルが top_pick を独占してしまう）。
+# 30 日 = 最大 45 点。urgency boost (= NEEDS_DECISION 40 点) と同等のオーダーになる。
+STALE_DAY_CAP = 30
+
+# state ごとの基礎点。done / discarded は brief の対象外として 0 にする
+# （これらは archive 候補なので brief には浮かべない）。
+_STATE_BASE: dict[str, float] = {
+    "in-progress": 12.0,
+    "planned": 10.0,
+    "watching": 6.0,
+    "pending": 5.0,
+    "done": 0.0,
+    "discarded": 0.0,
+}
+
+_REVIEW_STATUS_WEIGHT: dict[str, float] = {
+    "review": 2.0,   # 「レビュー待ち」は催促したい
+    "draft": 1.0,
+    "published": 0.0,
+}
+
+
+@dataclass(frozen=True)
+class ScoreBreakdown:
+    """スコア内訳。``brief --explain`` / Web で内訳を見せるときに使う。"""
+
+    total: float
+    state_base: float
+    urgency: float
+    stale: float
+    review_status: float
+    touched_decay: float
+    dep_chain: float
+
+    def to_dict(self) -> dict:
+        return {
+            "total": round(self.total, 2),
+            "state_base": round(self.state_base, 2),
+            "urgency": round(self.urgency, 2),
+            "stale": round(self.stale, 2),
+            "review_status": round(self.review_status, 2),
+            "touched_decay": round(self.touched_decay, 2),
+            "dep_chain": round(self.dep_chain, 2),
+        }
+
+
+def _urgency_score(rec: FileRecord, *, today: date | None = None) -> float:
+    """due 超過 / NEEDS_DECISION (陳腐化) を urgency 軸として加点する。
+
+    NEEDS_DECISION は「陳腐化した未終端 = 即判断が要る」を意味する強いシグナル。
+    stale (経過日数の連続値) より優先するため、40 点をつける（W_URGENCY 同等）。
+    """
+    score = 0.0
+    base = today or date.today()
+    if rec.due:
+        try:
+            d = date.fromisoformat(rec.due)
+            days_over = (base - d).days
+            if days_over > 0:
+                # 1 日 1 点、上限 +30 まで（青天井にしない）
+                score += min(30.0, float(days_over))
+        except ValueError:
+            pass
+    if Flag.NEEDS_DECISION.value in (rec.flags or []):
+        score += 40.0  # 強いシグナル: stale cap 寄与より大きく
+    if Flag.OVERDUE_TODO.value in (rec.flags or []):
+        score += 20.0
+    if Flag.OVERDUE_GRADUATE.value in (rec.flags or []):
+        score += 12.0
+    return score
+
+
+def score_record(rec: FileRecord, *, today: date | None = None) -> ScoreBreakdown:
+    """FileRecord を入力に ``ScoreBreakdown`` を返す。``total`` が大きいほど「今日の 1 個」候補。
+
+    done / discarded はスコア 0 で固定（brief / cross の対象外）。
+    """
+    state_base = _STATE_BASE.get(rec.state or "", 0.0)
+    if state_base == 0.0 and rec.state in {"done", "discarded"}:
+        return ScoreBreakdown(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
+
+    urgency = _urgency_score(rec, today=today) * (W_URGENCY / 40.0)
+    # stale は cap 付き（古い凍結ファイルが top_pick を独占しないよう抑える）。
+    capped_age = min(float(rec.age_days or 0), float(STALE_DAY_CAP))
+    stale = capped_age * W_STALE
+    review_status = _REVIEW_STATUS_WEIGHT.get(rec.review_status or "", 0.0) * W_REVIEW_STATUS
+    # 触ったばかりのファイルは下げる（同じものに張り付かない誘導）
+    touched_decay = max(0.0, 14.0 - float(rec.age_days or 0)) * W_TOUCHED_DECAY
+    dep_chain = float(len(rec.related or [])) * W_DEP_CHAIN
+
+    total = state_base + urgency + stale + review_status - touched_decay + dep_chain
+    return ScoreBreakdown(
+        total=total,
+        state_base=state_base,
+        urgency=urgency,
+        stale=stale,
+        review_status=review_status,
+        touched_decay=-touched_decay,
+        dep_chain=dep_chain,
+    )
+
+
+def tiebreak_key(rec: FileRecord) -> tuple:
+    """同点時のタイブレーカ。決定性を確保するため ``path`` 昇順で 1 件に絞る。"""
+    return (rec.project or "", Path(rec.path).name, rec.path)

docsweep/brief/service.py

@@ -0,0 +1,243 @@
+"""C3: brief 生成のコアロジック。CLI / Web / MCP がすべてここを呼ぶ。
+
+brief は「今日 1 個だけやろう」を断定するための朝の入口。表示要素は 4 つ:
+
+1. ``today_pick``: 「今日の 1 個」（最高スコア・必ず 1 件決まる）
+2. ``co_running``: 併走中（in-progress 上位 ~3 件、today_pick を除く）
+3. ``watchouts``: 要注意 stale（NEEDS_DECISION / OVERDUE_TODO 等を持つ古い未終端）
+4. ``yesterday_done``: 昨日終わったこと（mtime が 24h 以内の done/discarded）
+
+すべてプロジェクト粒度の概念で、``--project all`` 時は project_id ごとに同じ束を作る。
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+
+from ..config import Config
+from ..engine import scan_records
+from ..models import FileRecord, Flag
+from .score import ScoreBreakdown, score_record, tiebreak_key
+
+
+def _short_record(rec: FileRecord, score: ScoreBreakdown | None = None) -> dict:
+    """brief 表示で使う slim 表現。冗長な path は basename を併記して人間にも AI にも読める形に。"""
+    out = {
+        "path": rec.path,
+        "rel": Path(rec.path).name,
+        "project": rec.project,
+        "type": rec.type,
+        "state": rec.state,
+        "state_label": rec.state_label,
+        "title": rec.title,
+        "summary": rec.summary,
+        "age_days": rec.age_days,
+        "due": rec.due,
+        "owner": rec.owner,
+        "flags": list(rec.flags or []),
+        "tags": list(rec.tags or []),
+    }
+    if score is not None:
+        out["score"] = score.to_dict()
+    return out
+
+
+@dataclass
+class ProjectBrief:
+    """1 プロジェクト分の brief。``BriefResult.projects`` に複数並ぶ。"""
+
+    project: str
+    today_pick: dict | None
+    co_running: list[dict] = field(default_factory=list)
+    watchouts: list[dict] = field(default_factory=list)
+    yesterday_done: list[dict] = field(default_factory=list)
+    open_count: int = 0
+    stale_count: int = 0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class BriefResult:
+    """brief の最終出力。CLI/Web/MCP 共通。"""
+
+    mode: str  # "single" | "all"
+    generated_at: str
+    projects: list[ProjectBrief] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "mode": self.mode,
+            "generated_at": self.generated_at,
+            "projects": [p.to_dict() for p in self.projects],
+        }
+
+
+def _is_open_state(rec: FileRecord) -> bool:
+    """brief の主要対象（done/discarded 以外の未終端）。"""
+    return rec.state in {"in-progress", "planned", "watching", "pending"}
+
+
+def _yesterday_window(now: datetime) -> tuple[float, float]:
+    """直近 24h ウィンドウの mtime 範囲（epoch 秒）。"""
+    end = now.timestamp()
+    start = (now - timedelta(hours=24)).timestamp()
+    return start, end
+
+
+def _build_for_project(
+    records: list[FileRecord], project: str, *, today: date, now: datetime
+) -> ProjectBrief:
+    """1 プロジェクト分のレコードから ProjectBrief を組み立てる。"""
+    open_recs = [r for r in records if _is_open_state(r)]
+    scored: list[tuple[FileRecord, ScoreBreakdown]] = sorted(
+        ((r, score_record(r, today=today)) for r in open_recs),
+        key=lambda pair: (-pair[1].total, tiebreak_key(pair[0])),
+    )
+
+    today_pick: dict | None = None
+    co_running: list[dict] = []
+    if scored:
+        head_rec, head_score = scored[0]
+        today_pick = _short_record(head_rec, head_score)
+        for rec, sc in scored[1:4]:
+            if rec.state == "in-progress" or len(co_running) < 2:
+                co_running.append(_short_record(rec, sc))
+            if len(co_running) >= 3:
+                break
+
+    watchouts: list[dict] = []
+    for rec in open_recs:
+        flags = set(rec.flags or [])
+        if not (flags & {
+            Flag.NEEDS_DECISION.value,
+            Flag.OVERDUE_TODO.value,
+            Flag.OVERDUE_GRADUATE.value,
+        }):
+            continue
+        if today_pick and rec.path == today_pick["path"]:
+            continue
+        watchouts.append(_short_record(rec, score_record(rec, today=today)))
+    watchouts.sort(key=lambda d: -(d.get("score") or {}).get("total", 0.0))
+    watchouts = watchouts[:5]
+
+    start, end = _yesterday_window(now)
+    yesterday: list[dict] = []
+    for rec in records:
+        if rec.state not in {"done", "discarded"}:
+            continue
+        if rec.mtime and start <= rec.mtime <= end:
+            yesterday.append(_short_record(rec))
+    yesterday.sort(key=lambda d: -(d.get("age_days") or 0))
+    yesterday = yesterday[:5]
+
+    stale_count = sum(1 for r in open_recs if Flag.STALE.value in (r.flags or []))
+
+    return ProjectBrief(
+        project=project,
+        today_pick=today_pick,
+        co_running=co_running,
+        watchouts=watchouts,
+        yesterday_done=yesterday,
+        open_count=len(open_recs),
+        stale_count=stale_count,
+    )
+
+
+def _resolve_target_projects(
+    records: list[FileRecord],
+    *,
+    project: str | None,
+    all_projects: bool,
+    cwd_project: str | None,
+) -> list[str]:
+    if all_projects:
+        names = sorted({r.project for r in records if r.project})
+        return names
+    if project:
+        return [project]
+    if cwd_project:
+        return [cwd_project]
+    # cwd 解決ができない時は records から先頭プロジェクトを 1 つ
+    names = sorted({r.project for r in records if r.project})
+    return names[:1]
+
+
+def _detect_cwd_project(config: Config) -> str | None:
+    """現在ディレクトリが含まれるプロジェクトを推測する（``cwd プロジェクト`` 既定）。
+
+    まず ``config.roots`` 配下に cwd が含まれていれば、その root の name を返す。
+    git remote が使える場合はそちら優先。失敗時は None（呼び出し側で他のフォールバック）。
+    """
+    import os
+    import subprocess
+
+    cwd = Path(os.getcwd()).resolve()
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(cwd), "remote", "get-url", "origin"],
+            capture_output=True, text=True, timeout=2,
+        )
+        if result.returncode == 0:
+            url = result.stdout.strip()
+            if url:
+                tail = url.rstrip("/").split("/")[-1]
+                if tail.endswith(".git"):
+                    tail = tail[:-4]
+                if tail:
+                    return tail
+    except (OSError, subprocess.SubprocessError):
+        pass
+
+    for root in config.roots:
+        try:
+            cwd.relative_to(Path(root).resolve())
+            return Path(root).name
+        except ValueError:
+            continue
+    return None
+
+
+def build_brief(
+    config: Config,
+    *,
+    project: str | None = None,
+    all_projects: bool = False,
+    today: date | None = None,
+) -> BriefResult:
+    """brief を 1 回ぶん組み立てて返す。
+
+    Args:
+        config: ロード済み Config
+        project: 単一プロジェクト指定（``project_id`` 文字列）
+        all_projects: True で search_paths の全プロジェクトを横並び要約
+        today: テスト用の日付固定。未指定なら ``date.today()``
+    """
+    now = datetime.now(timezone.utc).astimezone()
+    today_date = today or now.date()
+
+    records = scan_records(config)
+
+    cwd_proj = _detect_cwd_project(config) if not (project or all_projects) else None
+    targets = _resolve_target_projects(
+        records, project=project, all_projects=all_projects, cwd_project=cwd_proj,
+    )
+
+    by_project: dict[str, list[FileRecord]] = {}
+    for r in records:
+        if r.project:
+            by_project.setdefault(r.project, []).append(r)
+
+    projects: list[ProjectBrief] = []
+    for name in targets:
+        proj_recs = by_project.get(name, [])
+        projects.append(_build_for_project(proj_recs, name, today=today_date, now=now))
+
+    return BriefResult(
+        mode="all" if all_projects else "single",
+        generated_at=now.isoformat(),
+        projects=projects,
+    )

docsweep/capture/__init__.py

@@ -0,0 +1,15 @@
+"""C2 (wings): capture — 会話履歴から plan / bugfix / pending の草案を抽出する上流の双子。
+
+設計の要点:
+- Heuristic 経路（LLM 無し）と LLM 経路（mock / 実 provider）の 2 系統
+- 草案は :class:`models.Draft` で表現し、ユーザーが番号選択で採用 → frontmatter 付き md を生成
+- 実 LLM API（OpenAI/Anthropic）は本 plan では呼ばない（abstract + Mock のみ）
+"""
+
+from .models import Draft, DraftKind
+from .service import (
+    extract_drafts,
+    save_drafts,
+)
+
+__all__ = ["Draft", "DraftKind", "extract_drafts", "save_drafts"]

docsweep/capture/heuristics.py

@@ -0,0 +1,69 @@
+"""LLM を使わずに会話履歴から草案を拾うヒューリスティック。
+
+LLM 経路の前段として、決定事項マーカー（「決定」「TODO」「バグ」等）を含む段落を
+切り出し、最低限の Draft を作る。LLM が無くても CLI / MCP の口は動く。
+"""
+
+from __future__ import annotations
+
+import re
+
+from .llm import _make_draft
+from .models import Draft, DraftKind
+
+# 決定事項マーカー（段落単位で拾う）。
+PLAN_MARKERS = ("決定", "やる", "実装する", "TODO", "todo", "次に", "やろう", "対応する")
+BUGFIX_MARKERS = ("バグ", "不具合", "壊れ", "再現", "エラー", "落ちる", "出ない")
+PENDING_MARKERS = ("保留", "あとで", "ペンディング", "棚上げ")
+
+
+def _split_paragraphs(text: str) -> list[str]:
+    """1 行空きで段落を切る。連続改行は 1 つの区切りに丸める。"""
+    chunks = re.split(r"\n\s*\n", text)
+    return [c.strip() for c in chunks if c.strip()]
+
+
+def _classify_paragraph(para: str) -> str | None:
+    if any(m in para for m in BUGFIX_MARKERS):
+        return DraftKind.BUGFIX.value
+    if any(m in para for m in PENDING_MARKERS):
+        return DraftKind.PENDING.value
+    if any(m in para for m in PLAN_MARKERS):
+        return DraftKind.PLAN.value
+    return None
+
+
+def _extract_title(para: str) -> str:
+    """段落の最初の意味行をタイトルにする。記号・改行は削る。"""
+    for line in para.splitlines():
+        s = line.strip()
+        if not s:
+            continue
+        # H1 / 箇条書き記号を剥がす
+        s = re.sub(r"^[#\-*>\s]+", "", s).strip()
+        if s:
+            return s[:60]
+    return para[:60]
+
+
+def extract_drafts_heuristic(
+    text: str, *, project: str | None = None, max_drafts: int = 5
+) -> list[Draft]:
+    """LLM 不要のヒューリスティック抽出。"""
+    drafts: list[Draft] = []
+    for para in _split_paragraphs(text):
+        kind = _classify_paragraph(para)
+        if kind is None:
+            continue
+        title = _extract_title(para)
+        drafts.append(_make_draft(
+            idx=len(drafts) + 1,
+            kind=kind,
+            title=title,
+            body_seed=para,
+            source_hint="heuristic",
+            project=project,
+        ))
+        if len(drafts) >= max_drafts:
+            break
+    return drafts