dsh-task-ledger 0.0.101 → 0.0.102

package/skill/scripts/ledgerkit/core/labels.py

@@ -1,89 +0,0 @@
-"""分类与标签：校验、拼行、拆行。只做文本换算。"""
-
-from __future__ import annotations
-
-import re
-from collections.abc import Iterable
-
-from ..errors import Fail
-
-STATUSES = ("open", "doing")
-FORMAT_VERSION = "20261022000000"
-
-LABEL_MAX_CHARS = 4  # 含 CJK 时按「字」算
-LABEL_MAX_WORDS_EN = 3  # 纯 ASCII 时按「词」算
-TAGS_MAX_COUNT = 5
-
-CJK_RE = re.compile(r"[\u4e00-\u9fff]")
-LABEL_CAT_RE = re.compile(r"分类\*\*\s*[：:]\s*([^｜|·]+)")
-LABEL_TAG_RE = re.compile(r"标签\*\*\s*[：:]\s*(.+)$")
-_SPLIT_RE = re.compile(r"[,，、]")
-
-
-def normalize_label(value: str, *, field: str) -> str:
-    """分类 / 单个标签的校验：去空白、限长。空串直接 Fail（给了就要有意义）。"""
-    text = (value or "").strip()
-    if not text:
-        raise Fail(f"{field} 不能为空。")
-    if CJK_RE.search(text):
-        if len(text) > LABEL_MAX_CHARS:
-            raise Fail(f"{field} {text!r} 太长：含中文时最多 {LABEL_MAX_CHARS} 个字。")
-    elif len(text.split()) > LABEL_MAX_WORDS_EN:
-        raise Fail(f"{field} {text!r} 太长：英文最多 {LABEL_MAX_WORDS_EN} 个词。")
-    return text
-
-
-def parse_tags(raw: str | Iterable[str] | None) -> tuple[str, ...]:
-    """标签串（「、」「,」「，」分隔）→ 去重保序的元组；超上限报错。"""
-    if raw is None:
-        return ()
-    items = list(raw) if not isinstance(raw, str) else _SPLIT_RE.split(raw)
-    out: list[str] = []
-    for item in items:
-        text = normalize_label(str(item).strip(), field="标签")
-        if text not in out:
-            out.append(text)
-    if len(out) > TAGS_MAX_COUNT:
-        raise Fail(f"标签最多 {TAGS_MAX_COUNT} 个，收到 {len(out)} 个。")
-    return tuple(out)
-
-
-def label_line(tags: Iterable[str] | None) -> str:
-    """过程文档头部的「标签」行；标签为空返回空串（此行不写）。
-
-    分类**不进过程文档**（2026-10-27 用户拍板）：它只活在分片字段与历史表里，
-    标签可涵盖分类（「建设」「修改」这类词直接当标签写）。
-    """
-    tag_list = [t for t in (tags or ()) if t]
-    return f"- **标签**：{'、'.join(tag_list)}" if tag_list else ""
-
-
-def parse_label_line(text: str) -> tuple[str | None, tuple[str, ...]]:
-    """从过程文档头部（第一个 `## ` 小节之前）解析分类与标签。
-
-    跳过 HTML 注释块：模板注释里的示例不是数据。老文档的分类段照样能解析出来。
-    """
-    in_comment = False
-    for line in text.splitlines():
-        if line.startswith("## "):
-            break
-        stripped = line.lstrip()
-        if in_comment:
-            if "-->" in stripped:
-                in_comment = False
-            continue
-        if stripped.startswith("<!--"):
-            in_comment = "-->" not in stripped
-            continue
-        mc = LABEL_CAT_RE.search(line)
-        mt = LABEL_TAG_RE.search(line)
-        if not (mc or mt):
-            continue
-        category = mc.group(1).strip() if mc else None
-        tags = (
-            tuple(t.strip() for t in _SPLIT_RE.split(mt.group(1).strip()) if t.strip())
-            if mt
-            else ()
-        )
-        return (category or None, tags)
-    return (None, ())

package/skill/scripts/ledgerkit/core/paths.py

@@ -1,92 +0,0 @@
-"""路径与文件名怎么拼：只做换算，一个文件都不碰。
-
-**基准只有两个**：
-- 磁盘与 JSON 里存的（`task["worklog"]` 等）一律**相对 `ledger/`**；
-- 输出给人或给界面的（`Result.where`、`payload` 里的 `*_path`）一律**相对 repo**。
-
-换算只在这两个函数里做，任何层都不许自己拼 `..`。
-"""
-
-from __future__ import annotations
-
-import hashlib
-import re
-from pathlib import Path
-
-LEDGER_DIR = Path("ledger")
-
-POOL_REL = Path("pool.json")
-OWNERS_REL = Path("owners.json")
-OWNERS_DIR = Path("owners")
-HISTORY_DIR = Path("history")
-WORKLOG_DIR = Path("worklog")
-
-SHA_LEN = 12
-
-# 模板与资产的唯一定位基准：按自身位置算绝对路径，不依赖调用方 cwd。
-# ledgerkit/core/paths.py → parents: [core, ledgerkit, scripts, skill]
-SKILL_DIR = Path(__file__).resolve().parents[3]
-WORKLOG_TEMPLATE = SKILL_DIR / "assets" / "worklog.md"
-
-
-def to_repo_rel(ledger_rel: str | Path) -> Path:
-    """相对 `ledger/` 的路径 → 相对 repo 的路径。"""
-    return LEDGER_DIR / Path(ledger_rel)
-
-
-def to_ledger_rel(repo_rel: str | Path) -> str:
-    """相对 repo 的路径 → 相对 `ledger/` 的路径（已经是 `ledger/` 内的原样返回）。"""
-    p = Path(repo_rel)
-    if p.parts and p.parts[0] == LEDGER_DIR.name:
-        return Path(*p.parts[1:]).as_posix()
-    return p.as_posix()
-
-
-def to_history_rel(ledger_rel: str | Path) -> str:
-    """`ledger/` 内的路径 → 从 `ledger/history/<ym>.md` 出发的链接串。
-
-    深度固定（`history/` 与 `worklog/` 都在 `ledger/` 下），拼 `..` 只许在这一处。
-    """
-    return ("../" / Path(ledger_rel)).as_posix()
-
-
-def shard_rel(identity: str) -> Path:
-    """某人分片相对 `ledger/` 的路径：sha256(归一化身份)[:12] + .json。"""
-    digest = hashlib.sha256(identity.strip().lower().encode("utf-8")).hexdigest()
-    return OWNERS_DIR / f"{digest[:SHA_LEN]}.json"
-
-
-def month_of(stamp: str, *, fallback_now: str | None = None) -> str:
-    """存盘时间 → `YYYYMM`；取不到时用 `fallback_now`，再没有就抛错由调用方定夺。"""
-    month = re.sub(r"[^0-9]", "", (stamp or "")[:7])[:6]
-    if len(month) == 6:
-        return month
-    if fallback_now:
-        return re.sub(r"[^0-9]", "", fallback_now[:7])[:6]
-    return ""
-
-
-def worklog_dir_for(created: str) -> Path:
-    """过程文档的按月目录（相对 `ledger/`）：`worklog/<YYYYMM>/`。"""
-    return WORKLOG_DIR / month_of(created)
-
-
-def worklog_name(tid: str) -> str:
-    """过程文档的文件名：任务号剥掉前缀年月日，随机码保留。
-
-    父目录 `worklog/<YYYYMM>/` 已带年月，文件名里再写一遍是冗余；
-    自定义 `--id` 不以「8 位数字-」开头时，文件名就是任务号本身。
-    """
-    if len(tid) > 9 and tid[:8].isdigit() and tid[8] == "-":
-        return f"{tid[6:]}.md"
-    return f"{tid}.md"
-
-
-def worklog_rel(tid: str, created: str) -> str:
-    """过程文档相对 `ledger/` 的路径：任务对象与历史末列共用同一口径。"""
-    return (worklog_dir_for(created) / worklog_name(tid)).as_posix()
-
-
-def history_path_for(finished: str) -> Path:
-    """结案时间 → 历史文件相对 `ledger/` 的路径：`history/<YYYYMM>.md`。"""
-    return HISTORY_DIR / f"{month_of(finished)}.md"

package/skill/scripts/ledgerkit/core/roots.py

@@ -1,74 +0,0 @@
-"""工作区根的判定：哪个目录才是「直接含有 `ledger/` 的那个根」。
-
-全仓唯一实现 —— `shell/` 与 `actions/` 都调这里，不各写一份（否则口径会漂）。
-判据是**结构**（含不含 `ledger/`、自己在不在 `ledger/` 里），不看目录里有哪些文件：
-项目根自带 `pool.json`、`history/` + `worklog/`、`owners.json` + `owners/` 这类同名文件
-或目录都很常见，按「里面有什么」判会把正常项目根误当成台账目录（2026-10-25 改）。
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..errors import Fail
-from .paths import LEDGER_DIR
-
-
-def _under_ledger(p: Path) -> bool:
-    """`p` 自己叫 `ledger`，或它落在某个 `ledger/` 目录里面。"""
-    if p.name == LEDGER_DIR.name:
-        return True
-    return any(anc.name == LEDGER_DIR.name for anc in p.parents)
-
-
-def as_root(repo: str | Path, *, source: str = "--repo") -> Path:
-    """校验「工作区根」，只看结构：
-
-    - 直接含 `ledger/` ⇒ 就是根。哪怕项目根自己叫 `ledger`、哪怕它自己也有 `pool.json`；
-    - 不含 `ledger/`、但自己叫 `ledger` 或落在某个 `ledger/` 下 ⇒ 是台账目录 / 台账里面，拒；
-    - 其余（含全新空目录）⇒ 收，第一条写命令会在它下面建 `ledger/`。
-    """
-    p = Path(repo).expanduser()
-    if not p.is_dir():
-        raise Fail(
-            f"{source} 指向的不是一个目录：{p}\n"
-            f"  处理：指向工作区根（直接含有 ledger/ 的那个目录，不是 ledger/ 本身）。"
-        )
-    if (p / LEDGER_DIR).is_dir():
-        return p.resolve()
-    if _under_ledger(p):
-        anc = next(a for a in (p, *p.parents) if a.name == LEDGER_DIR.name)
-        root = anc.parent
-        if anc is p:
-            what = f"指到了台账目录本身：{p}"
-            why = f"它的上一级 {root} 才是工作区根 —— 在它下面跑会再建出 {p / LEDGER_DIR}。"
-        else:
-            what = f"指到了台账目录里面：{p}"
-            why = f"它已经在 {anc} 这个台账目录底下 —— 工作区根是 {anc.parent}。"
-        raise Fail(
-            f"{source} {what}\n"
-            f"  {why}\n"
-            f"  处理：把 {source} 指到 {root}\n"
-            f"      例：progress.py list --repo {root}"
-        )
-    return p.resolve()
-
-
-def root_of(start: str | Path) -> Path | None:
-    """从 `start` 往上定位工作区根；找不到返回 None。
-
-    ① 自己在台账目录里（名字叫 `ledger`、且里面没有再套一层 `ledger/`）⇒ 根是它的上一级。
-       按位置判，不看里面有什么：项目根自带 `history/` + `worklog/` 不会被误当成台账目录。
-    ② 兜底：从**自己**开始往上，取最近的、直接含 `ledger/` 的目录。`start` 必须优先于
-       祖先，否则工作区根恰好叫 `ledger` 时会被父目录抢走（2026-10-25 改）。
-    """
-    here = Path(start).resolve()
-    for anc in (here, *here.parents):
-        if anc.name == LEDGER_DIR.name and not (anc / LEDGER_DIR).is_dir():
-            root = anc.parent
-            if (root / LEDGER_DIR).is_dir():
-                return root
-    for cand in (here, *here.parents):
-        if (cand / LEDGER_DIR).is_dir():
-            return cand
-    return None

package/skill/scripts/ledgerkit/core/time.py

@@ -1,103 +0,0 @@
-"""时间：本地墙钟 ↔ UTC 的换算、格式化、排序键。
-
-进门规则：不读文件、不写文件、不打印；只依赖 errors。
-所有**存盘**时间都是 UTC（`YYYY-MM-DD HH:MM:SS`，不带偏移量）；
-所有**对外输出**（人话表格与 `--json`）的时间字段都过 `fmt_local` 转本机时区，
-内部筛选 / 排序一律用存盘的 UTC —— 调用方拿到的时间不用再转。
-"""
-
-from __future__ import annotations
-
-import re
-from datetime import UTC, datetime
-
-from ..errors import Fail
-
-_UTC = UTC
-
-TIME_RE = re.compile(r"\d{4}-\d{2}-\d{2} \d{2}:\d{2}(?::\d{2})?\Z")
-_TIME_IN_RE = re.compile(
-    r"(\d{4})-(\d{1,2})-(\d{1,2})(?: +(\d{1,2}):(\d{1,2})(?::(\d{1,2}))?)?\Z"
-)
-
-
-def now() -> str:
-    """当前时刻（UTC，到秒）。"""
-    return datetime.now(_UTC).strftime("%Y-%m-%d %H:%M:%S")
-
-
-def normalize_time(
-    value: str | datetime,
-    *,
-    field: str = "时间",
-    tid: str | None = None,
-    date_only_ref: str | None = None,
-) -> str:
-    """把「正确但不完整」的写法归一化到 `YYYY-MM-DD HH:MM:SS`。
-
-    接受 `YYYY-MM-DD`、`YYYY-MM-DD HH:MM`、`YYYY-MM-DD HH:MM:SS`，容忍 `/` 与 `T`。
-    `date_only_ref`：只给了日期时用这个时刻顶替（`--until` 想含整天传 `23:59:59`）。
-    """
-    where = f"{tid}: " if tid else ""
-    if isinstance(value, datetime):
-        return value.strftime("%Y-%m-%d %H:%M:%S")
-    if not isinstance(value, str) or not value.strip():
-        raise Fail(f"{where}{field} 要是一个时间字符串，收到 {value!r}")
-    s = " ".join(
-        value.strip().replace("/", "-").replace("T", " ").replace("t", " ").split()
-    )
-    m = _TIME_IN_RE.fullmatch(s)
-    if not m:
-        raise Fail(
-            f"{where}{field} 时间格式不对：{value!r}"
-            "（可用 YYYY-MM-DD、YYYY-MM-DD HH:MM、YYYY-MM-DD HH:MM:SS）"
-        )
-    y, mo, d, hh, mm, ss = m.groups()
-    if date_only_ref is not None and hh is None:
-        out = f"{int(y):04d}-{int(mo):02d}-{int(d):02d} {date_only_ref}"
-    else:
-        out = (
-            f"{int(y):04d}-{int(mo):02d}-{int(d):02d} "
-            f"{int(hh or 0):02d}:{int(mm or 0):02d}:{int(ss or 0):02d}"
-        )
-    try:
-        datetime.strptime(out, "%Y-%m-%d %H:%M:%S")
-    except ValueError as exc:
-        raise Fail(f"{where}{field} 不是真实时间：{value!r}（{exc}）") from exc
-    return out
-
-
-def to_utc(
-    value: str,
-    *,
-    field: str,
-    tid: str | None = None,
-    date_only_ref: str | None = None,
-) -> str:
-    """用户按本地墙钟给的时间 → 存盘用的 UTC 串。只由外壳调用。"""
-    wall = normalize_time(value, field=field, tid=tid, date_only_ref=date_only_ref)
-    naive = datetime.strptime(wall, "%Y-%m-%d %H:%M:%S")
-    return naive.astimezone(_UTC).strftime("%Y-%m-%d %H:%M:%S")
-
-
-def fmt_local(stamp: object) -> str:
-    """存盘的 UTC → 查看者本地时间，只用于人看的输出。
-
-    存量老数据（2026-10-22 前写的是写入者本地时间、无标记）无法区分，
-    按 UTC 转会显示偏后若干小时 —— 这是已知例外，不在脚本里猜。
-    """
-    key = time_key(stamp)
-    if key is None:
-        return "" if stamp is None else str(stamp)
-    try:
-        dt = datetime.strptime(key, "%Y-%m-%d %H:%M:%S").replace(tzinfo=_UTC)
-    except ValueError:
-        return str(stamp)
-    return dt.astimezone().strftime("%Y-%m-%d %H:%M:%S")
-
-
-def time_key(value: object) -> str | None:
-    """已存时间（可能只到分）→ 秒精度串，用于比较/排序；不合法返回 None。"""
-    if not isinstance(value, str) or not TIME_RE.fullmatch(value):
-        return None
-    return value if len(value) == 19 else value + ":00"