docsweep 0.1.0__py3-none-any.whl

docsweep/__init__.py

@@ -0,0 +1,3 @@
+"""docsweep — AI 作業ドキュメント（plan/bugfix/pending）の横断スキャン・判定・archive 移送ツール。"""
+
+__version__ = "0.1.0"

docsweep/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

docsweep/activity.py

@@ -0,0 +1,183 @@
+"""``docsweep activity`` — 過去に触ったもの／今後期限のものを日付でまとめる。
+
+新規永続化は一切行わない。``scan_records()`` が既に返す ``mtime``（過去日軸）と
+``due``（未来日軸）だけを使い、日付ごとにグルーピングする薄い読み取り専用ロジック。
+today 自身は両軸を出す。plan_activity-summary.md C1 の主要 deliverable。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+
+from .brief.service import _detect_cwd_project, _resolve_target_projects
+from .config import Config
+from .engine import scan_records
+from .models import FileRecord
+from .services.due import DueParseError, resolve_relative_offset
+
+
+class ActivityDateError(ValueError):
+    """``--date``/``--since``/``--until`` の指定が解釈できないときに発生。"""
+
+
+def _resolve_date_token(token: str, *, today: date) -> date:
+    """``--date`` の 1 トークンを解決する（today/yesterday/tomorrow/YYYY-MM-DD）。"""
+    t = token.strip().lower()
+    if t == "today":
+        return today
+    if t == "yesterday":
+        return today - timedelta(days=1)
+    if t == "tomorrow":
+        return today + timedelta(days=1)
+    try:
+        return date.fromisoformat(token.strip())
+    except ValueError as e:
+        raise ActivityDateError(f"--date を解釈できません: {token!r}") from e
+
+
+def resolve_target_dates(
+    dates: list[str] | None,
+    *,
+    since: str | None,
+    until: str | None,
+    today: date,
+) -> list[date]:
+    """CLI 引数から対象日付の一覧（昇順・重複無し）を組み立てる。
+
+    ``--since``/``--until`` と ``--date`` は和集合（両方指定されたら両方を含める）。
+    どちらも未指定なら既定（today + yesterday）。
+    """
+    out: set[date] = set()
+    if dates:
+        for tok in dates:
+            out.add(_resolve_date_token(tok, today=today))
+    if since or until:
+        try:
+            start = resolve_relative_offset(since, today=today) if since else today
+            end = resolve_relative_offset(until, today=today) if until else today
+        except DueParseError as e:
+            raise ActivityDateError(str(e)) from e
+        if start > end:
+            start, end = end, start
+        cur = start
+        while cur <= end:
+            out.add(cur)
+            cur += timedelta(days=1)
+    if not out:
+        out = {today, today - timedelta(days=1)}
+    return sorted(out)
+
+
+def _axes_for_date(d: date, *, today: date) -> tuple[bool, bool]:
+    """(mtime 軸を出すか, due 軸を出すか) を返す。today 自身は両方 True。"""
+    if d < today:
+        return (True, False)
+    if d > today:
+        return (False, True)
+    return (True, True)
+
+
+def _short_record(rec: FileRecord) -> dict:
+    return {
+        "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,
+        "due": rec.due,
+        "age_days": rec.age_days,
+    }
+
+
+@dataclass
+class DateBucket:
+    """1 日分のグルーピング結果。"""
+
+    touched: list[dict] = field(default_factory=list)  # mtime 軸（触ったもの）
+    due: list[dict] = field(default_factory=list)  # due 軸（期限のもの）
+
+    def to_dict(self) -> dict:
+        return {"touched": list(self.touched), "due": list(self.due)}
+
+
+@dataclass
+class ActivityResult:
+    """activity の最終出力。CLI/JSON 共通。"""
+
+    generated_at: str
+    today: str
+    dates: dict[str, DateBucket] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "generated_at": self.generated_at,
+            "today": self.today,
+            "dates": {k: v.to_dict() for k, v in self.dates.items()},
+        }
+
+
+def build_activity(
+    config: Config,
+    *,
+    dates: list[str] | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    project: str | None = None,
+    all_projects: bool = False,
+    today: date | None = None,
+) -> ActivityResult:
+    """activity を 1 回ぶん組み立てて返す。
+
+    Args:
+        config: ロード済み Config
+        dates: ``--date`` の複数指定（today/yesterday/tomorrow/YYYY-MM-DD）
+        since: ``--since``（絶対 or 符号付き相対オフセット）
+        until: ``--until``（同上）
+        project: 単一プロジェクト指定（``project_id`` 文字列）
+        all_projects: True で search_paths の全プロジェクトを束ねる
+        today: テスト用の日付固定。未指定なら ``date.today()``
+    """
+    now = datetime.now(timezone.utc).astimezone()
+    today_date = today or now.date()
+
+    target_dates = resolve_target_dates(dates, since=since, until=until, today=today_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,
+    )
+    scoped = [r for r in records if r.project in targets]
+
+    buckets: dict[str, DateBucket] = {}
+    for d in target_dates:
+        want_mtime, want_due = _axes_for_date(d, today=today_date)
+        bucket = DateBucket()
+        if want_mtime:
+            bucket.touched = [
+                _short_record(r) for r in scoped
+                if r.mtime and datetime.fromtimestamp(r.mtime).astimezone().date() == d
+            ]
+            bucket.touched.sort(key=lambda x: (x["project"] or "", x["rel"]))
+        if want_due:
+            for r in scoped:
+                if not r.due:
+                    continue
+                try:
+                    due_date = date.fromisoformat(r.due)
+                except ValueError:
+                    continue
+                if due_date == d:
+                    bucket.due.append(_short_record(r))
+            bucket.due.sort(key=lambda x: (x["project"] or "", x["rel"]))
+        buckets[d.isoformat()] = bucket
+
+    return ActivityResult(
+        generated_at=now.isoformat(),
+        today=today_date.isoformat(),
+        dates=buckets,
+    )

docsweep/aggregate_index.py

@@ -0,0 +1,148 @@
+"""横断集約 INDEX（develop 全体を 1 か所で把握）— C5。
+
+実ファイルは各プロジェクトに残したまま、スキャンルート直下に論理集約の INDEX を生成する。
+- INDEX.json: AI エージェント連携用（ステータス別・pending 常設・要判断/要修正）
+- INDEX.md: 人間がエディタで一覧
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .config import Config
+from .engine import ScanResult, run_scan, scan_records
+from .models import Flag
+
+INDEX_DIRNAME = ".docsweep"
+
+
+@dataclass
+class IndexData:
+    roots: list[str]
+    counts: dict
+    by_state: dict[str, list[dict]]
+    pending: list[dict]
+    needs_decision: list[dict]
+    needs_fix: list[dict]
+    overdue_todo: list[dict] = None  # type: ignore[assignment]
+    overdue_graduate: list[dict] = None  # type: ignore[assignment]
+
+    def __post_init__(self):
+        if self.overdue_todo is None:
+            self.overdue_todo = []
+        if self.overdue_graduate is None:
+            self.overdue_graduate = []
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def build_index(config: Config, result: ScanResult | None = None) -> IndexData:
+    # 引数で ScanResult が渡されていれば優先（書き込み系から呼ぶ古い経路）。
+    # 渡されなければ索引フォールバック付きの scan_records を使う（fast path）。
+    if result is not None:
+        recs = result.records
+    else:
+        recs = scan_records(config)
+
+    by_state: dict[str, list[dict]] = {}
+    for r in recs:
+        by_state.setdefault(r.state or "unknown", []).append(r.to_dict())
+    for v in by_state.values():
+        v.sort(key=lambda d: d["age_days"], reverse=True)
+
+    pending = [r.to_dict() for r in recs if r.state == "pending"]
+    needs_decision = sorted(
+        [r.to_dict() for r in recs if Flag.NEEDS_DECISION.value in r.flags],
+        key=lambda d: d["age_days"], reverse=True,
+    )
+    needs_fix = [r.to_dict() for r in recs if Flag.NEEDS_FIX.value in r.flags]
+    overdue_todo = sorted(
+        [r.to_dict() for r in recs if Flag.OVERDUE_TODO.value in r.flags],
+        key=lambda d: d.get("due") or "",
+    )
+    overdue_graduate = sorted(
+        [r.to_dict() for r in recs if Flag.OVERDUE_GRADUATE.value in r.flags],
+        key=lambda d: d.get("due") or "",
+    )
+
+    counts = {
+        "total": len(recs),
+        "projects": len({r.project for r in recs}),
+        "needs_decision": len(needs_decision),
+        "needs_fix": len(needs_fix),
+        "pending": len(pending),
+        "archivable": sum(1 for r in recs if r.auto_movable and r.archivable),
+        "overdue_todo": len(overdue_todo),
+        "overdue_graduate": len(overdue_graduate),
+    }
+    return IndexData(
+        roots=[str(r) for r in config.roots],
+        counts=counts,
+        by_state=by_state,
+        pending=pending,
+        needs_decision=needs_decision,
+        needs_fix=needs_fix,
+        overdue_todo=overdue_todo,
+        overdue_graduate=overdue_graduate,
+    )
+
+
+def _render_row(d: dict) -> str:
+    name = Path(d["path"]).name
+    label = d.get("state_label") or "[?]"
+    summary = f" — {d['summary']}" if d.get("summary") else ""
+    flags = f" `{','.join(d['flags'])}`" if d.get("flags") else ""
+    return f"- {label} **{d['project']}**/{name} · {d['age_days']}d{flags}{summary}"
+
+
+def render_markdown(idx: IndexData, state_model) -> str:
+    c = idx.counts
+    lines: list[str] = [
+        "# docsweep INDEX",
+        "",
+        f"> 横断集約: {c['projects']} プロジェクト / {c['total']} 件 ＝ "
+        f"要判断 {c['needs_decision']} · 要修正 {c['needs_fix']} · 保留 {c['pending']} · archive候補 {c['archivable']}",
+        "",
+    ]
+    if idx.needs_decision:
+        lines += ["## ⚠ 要判断（陳腐化）", ""]
+        lines += [_render_row(d) for d in idx.needs_decision]
+        lines += [""]
+    if idx.pending:
+        lines += ["## 💤 保留（pending）", ""]
+        lines += [_render_row(d) for d in idx.pending]
+        lines += [""]
+    if idx.needs_fix:
+        lines += ["## 🔧 要修正（ラベル欠落・パース不能）", ""]
+        lines += [_render_row(d) for d in idx.needs_fix]
+        lines += [""]
+
+    lines += ["## ステータス別", ""]
+    for key in sorted(idx.by_state):
+        recs = idx.by_state[key]
+        st = state_model.by_key(key) if state_model else None
+        label = f"[{st.label()}]" if st else f"[{key}]"
+        lines += [f"### {label} ({len(recs)})", ""]
+        lines += [_render_row(d) for d in recs]
+        lines += [""]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def index_dir(config: Config) -> Path:
+    base = config.roots[0] if config.roots else Path.cwd()
+    return Path(base) / INDEX_DIRNAME
+
+
+def write_index(config: Config, result: ScanResult | None = None) -> tuple[Path, Path]:
+    """INDEX.json / INDEX.md をスキャンルート直下の .docsweep/ に書き出す。"""
+    idx = build_index(config, result)
+    out_dir = index_dir(config)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    json_path = out_dir / "INDEX.json"
+    md_path = out_dir / "INDEX.md"
+    json_path.write_text(json.dumps(idx.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8")
+    md_path.write_text(render_markdown(idx, config.state_model), encoding="utf-8")
+    return json_path, md_path

docsweep/archive.py

@@ -0,0 +1,80 @@
+"""archive 移送と移動ログ JSONL。
+
+- 場所は config 可変（既定 archive/）。同名衝突は連番（_2）。
+- 移動ログ {ts, op, project, status, src, dst} を JSONL 追記（eject/復元の土台）。
+- 同一ボリューム前提に依存しない（shutil.move で吸収）。
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from datetime import datetime
+from pathlib import Path
+
+from .models import MoveLogEntry
+
+MOVE_LOG_NAME = "moves.jsonl"
+
+
+def _now_iso() -> str:
+    return datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def dedupe_path(dst: Path) -> Path:
+    """衝突時に stem に _2, _3... を付けて空きパスを返す。"""
+    if not dst.exists():
+        return dst
+    stem, suffix, parent = dst.stem, dst.suffix, dst.parent
+    n = 2
+    while True:
+        cand = parent / f"{stem}_{n}{suffix}"
+        if not cand.exists():
+            return cand
+        n += 1
+
+
+def move_log_path(root: Path) -> Path:
+    return root / ".docsweep" / MOVE_LOG_NAME
+
+
+def append_move_log(root: Path, entry: MoveLogEntry) -> None:
+    p = move_log_path(root)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with p.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry.to_dict(), ensure_ascii=False) + "\n")
+
+
+def archive_file(
+    *,
+    src: Path,
+    project_dir: Path,
+    archive_dir: str,
+    root: Path,
+    project: str,
+    status: str | None,
+    op: str = "archive",
+    dry_run: bool = False,
+    batch_id: str | None = None,
+) -> Path:
+    """src を project_dir/<archive_dir>/ へ移送し、移動ログに記録する。移送先を返す。
+
+    ``batch_id`` を与えると JSONL の同名フィールドに記録され、後で Undo で逆引きできる。
+    """
+    src = src.resolve()
+    dest_dir = (project_dir / archive_dir).resolve()
+    dst = dedupe_path(dest_dir / src.name)
+
+    if dry_run:
+        return dst
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(src), str(dst))
+    append_move_log(
+        root,
+        MoveLogEntry(
+            ts=_now_iso(), op=op, project=project, status=status,
+            src=src.as_posix(), dst=dst.as_posix(), batch_id=batch_id,
+        ),
+    )
+    return dst

docsweep/atomic.py

@@ -0,0 +1,181 @@
+"""アトミック書き込み + 楽観ロック（mtime check） + バックアップ。
+
+全ての書き込み API はこのヘルパ経由で MD を更新する。Web UI と MCP どちらから書いても安全。
+
+- アトミック書き込み: 同ディレクトリに一時ファイル作成 → ``os.replace`` で差し替え。
+  Windows でも ``os.replace`` は atomic（NTFS の ``MoveFileEx`` 経由）。
+- 楽観ロック: ``expected_mtime`` を任意引数で受け取り、不一致なら ``ConflictError``。
+  Web UI からは必ず送る（読み込み時の mtime を保持）。CLI / MCP は省略可。
+- バックアップ: 全書き込み前に ``.docsweep/backup/`` へコピー。既定 30 日保持・自動掃除。
+- 行単位編集 vs 全置換:
+  - ``update_line`` は frontmatter `due:` 1 行や H1 ラベル先頭だけを置換（本文を触らない）
+  - ``write_atomic`` は全置換（Web UI の本文編集ペインから呼ぶ）
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+import time
+from pathlib import Path
+
+BACKUP_DIR_NAME = "backup"
+BACKUP_RETENTION_SECONDS = 30 * 24 * 60 * 60  # 30 日
+
+
+class ConflictError(Exception):
+    """expected_mtime と実 mtime が一致しないときに発生（楽観ロックの不一致）。"""
+
+    def __init__(self, path: Path, expected: float, actual: float) -> None:
+        super().__init__(
+            f"mtime conflict at {path}: expected={expected!r} actual={actual!r}"
+        )
+        self.path = path
+        self.expected = expected
+        self.actual = actual
+
+
+def _mtime(path: Path) -> float:
+    return path.stat().st_mtime
+
+
+def _project_root_for(path: Path) -> Path | None:
+    """書き込み対象 path から ``.docsweep/`` を置くプロジェクト境界を辿る。
+
+    ``backup`` の置き場決めにだけ使うので、見つからなければ path の親で代用する
+    （バックアップを取らないより取った方が安全という選択）。
+    """
+    cur = path.parent.resolve()
+    while True:
+        for marker in (".docsweep.yaml", ".git", "pyproject.toml", "package.json"):
+            if (cur / marker).exists():
+                return cur
+        parent = cur.parent
+        if parent == cur:
+            return None
+        cur = parent
+
+
+def backup_dir_for(path: Path) -> Path:
+    root = _project_root_for(path) or path.parent
+    return root / ".docsweep" / BACKUP_DIR_NAME
+
+
+def backup(path: Path) -> Path | None:
+    """書き込み直前に呼ぶ。``.docsweep/backup/<filename>.<unix_ts>`` へコピー。
+
+    対象が存在しない（新規作成）場合は何もしないで None を返す。古いバックアップは
+    呼び出しのついでに掃除する（30 日超で自動削除）。
+    """
+    if not path.is_file():
+        return None
+    dst_dir = backup_dir_for(path)
+    dst_dir.mkdir(parents=True, exist_ok=True)
+    ts = int(time.time())
+    dst = dst_dir / f"{path.name}.{ts}"
+    shutil.copy2(str(path), str(dst))
+    _cleanup_backups(dst_dir)
+    return dst
+
+
+def _cleanup_backups(dst_dir: Path) -> None:
+    """30 日経過したバックアップを削除する（best-effort・失敗無視）。"""
+    cutoff = time.time() - BACKUP_RETENTION_SECONDS
+    try:
+        for entry in dst_dir.iterdir():
+            try:
+                if entry.is_file() and entry.stat().st_mtime < cutoff:
+                    entry.unlink()
+            except OSError:
+                pass
+    except OSError:
+        pass
+
+
+def write_atomic(
+    path: Path,
+    content: str,
+    *,
+    expected_mtime: float | None = None,
+    encoding: str = "utf-8",
+    take_backup: bool = True,
+) -> float:
+    """``path`` の内容を ``content`` で全置換する。書き込み後の新 mtime を返す。
+
+    ``expected_mtime`` が指定され、実 mtime と一致しなければ ``ConflictError``。
+    ``take_backup=True`` のとき、既存ファイルを `.docsweep/backup/` へ退避する。
+    """
+    path = Path(path)
+    if expected_mtime is not None and path.is_file():
+        actual = _mtime(path)
+        if not _mtime_close(actual, expected_mtime):
+            raise ConflictError(path, expected_mtime, actual)
+    if take_backup:
+        backup(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=str(path.parent)
+    )
+    try:
+        with os.fdopen(fd, "w", encoding=encoding, newline="") as fh:
+            fh.write(content)
+        os.replace(tmp_name, str(path))
+    except Exception:
+        # 一時ファイルが残らないよう片付ける。
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return _mtime(path)
+
+
+def update_line(
+    path: Path,
+    *,
+    transform,
+    expected_mtime: float | None = None,
+    take_backup: bool = True,
+) -> float:
+    """``transform(text) -> new_text`` を経由して 1 ファイルを書き換える。
+
+    呼び出し側の transform 関数が「frontmatter `due:` を 1 行だけ差し替える」「H1 行先頭の
+    ラベルだけ差し替える」のような行単位の正規表現置換を行うため、本ヘルパは
+    アトミック書き込み・楽観ロック・バックアップだけを担う。
+    """
+    path = Path(path)
+    if expected_mtime is not None and path.is_file():
+        actual = _mtime(path)
+        if not _mtime_close(actual, expected_mtime):
+            raise ConflictError(path, expected_mtime, actual)
+    text = path.read_text(encoding="utf-8", newline="")
+    new_text = transform(text)
+    if new_text == text:
+        # 変更なし。書き込みも backup も省略する。
+        return _mtime(path)
+    if take_backup:
+        backup(path)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=str(path.parent)
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as fh:
+            fh.write(new_text)
+        os.replace(tmp_name, str(path))
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return _mtime(path)
+
+
+def _mtime_close(a: float, b: float, *, tol: float = 0.001) -> bool:
+    """ファイルシステムの mtime 解像度（Windows FAT は 2 秒・NTFS は 100ns）を考慮した近似比較。
+
+    そのまま `==` で比較すると、JSON 経由で round-trip した mtime と実 mtime が
+    sub-millisecond オーダーで微妙にズレて誤検出する。1ms 以内なら同一とみなす。
+    """
+    return abs(a - b) < tol