git-worklog 1.6.0__py3-none-any.whl

git_worklog/cli/refs.py

@@ -0,0 +1,55 @@
+"""``git-worklog refs`` — turn a tag into the commit set it actually contains.
+
+For report mode's version questions ("整理 v1.0.1 CHANGELOG"). The worklog is
+indexed by calendar date and a version is bounded by a commit set; the two do not
+map onto each other, so this emits the commits as the authority and the dates
+only as an index for locating day files worth reading. See
+:mod:`git_worklog.analysis.refs` for why converting a tag to a date span is wrong
+in both directions.
+"""
+
+from __future__ import annotations
+
+from git_worklog.analysis import AnalysisError
+from git_worklog.analysis import refs as engine
+
+
+def run(args) -> "tuple[dict, int]":
+    try:
+        return engine.resolve(repo=args.repo, tag=args.tag, from_ref=args.from_ref,
+                              to_ref=args.to_ref, list_tags_only=args.list_tags,
+                              timezone=args.timezone,
+                              date_field=args.date_field), 0
+    except AnalysisError as exc:
+        return {"ok": False, "errors": [
+            {"code": exc.code, "message": exc.message, **exc.extra}]}, 2
+    except engine.GitError as exc:
+        return {"ok": False, "errors": [
+            {"code": "GIT_ERROR", "message": str(exc)}]}, 2
+
+
+def render_text(p: dict) -> str:
+    if not p.get("ok"):
+        lines = []
+        for e in p.get("errors", []):
+            lines.append(f"error: {e['message']}\n")
+            for tag in e.get("available_tags", []):
+                lines.append(f"  available: {tag}\n")
+        return "".join(lines)
+
+    if "tags" in p:
+        if not p["tags"]:
+            return "No tags in this repository.\n"
+        return "".join(f"{t}\n" for t in p["tags"])
+
+    lines = [f"git-worklog refs — {p['commit_range']}\n"]
+    if p["first_release"]:
+        lines.append("  first release: the range runs from the root commit\n")
+    span = p["date_span"]
+    lines.append(f"  {p['commit_count']} commit(s)"
+                 + (f", {span['from']} .. {span['to']}\n" if span else "\n"))
+    lines.append(f"  ({p['date_field']} date, {p['timezone']})\n\n")
+    for c in p["commits"]:
+        lines.append(f"  {c['short_hash']}  {c['date']}  {c['subject']}\n")
+    lines.append(f"\n{p['note']}\n")
+    return "".join(lines)

git_worklog/cli/reindex.py

@@ -0,0 +1,72 @@
+"""``git-worklog reindex`` — rebuild index.md from the day files.
+
+The index is navigation only, and a pure function of the day files: a
+date-descending table linking each one, each row carrying that day's 當日摘要.
+That is what makes this safe to re-run and what makes it the repair for
+``INDEX_WRITE_FAILED`` — when an apply writes the days and then fails to write
+the index, nothing is lost, because the index can be derived again from what
+landed.
+
+Normal runs do not need it: ``apply`` rebuilds the index itself. Dry-run is the
+default here too.
+
+The index's MANUAL region is preserved byte-for-byte. Files that are not
+``<date>.md`` (including ``index.md`` itself) are ignored.
+"""
+
+from __future__ import annotations
+
+import os
+
+from git_worklog import writer
+
+
+def run(args) -> "tuple[dict, int]":
+    try:
+        worklog_dir = args.dir or writer.DEFAULT_DIR
+        # plan_index is happy to plan an index for a directory that is not there
+        # — correct for `apply`, which is allowed to create the worklog. Here it
+        # is not: this command repairs a worklog that exists, so a --dir that
+        # does not is a typo, and planning an empty index over it would answer a
+        # question nobody asked. Same answer `validate` gives.
+        if not os.path.isdir(worklog_dir):
+            return {"ok": False, "errors": [{
+                "code": "NOT_FOUND",
+                "message": f"{os.path.abspath(worklog_dir)} does not exist.",
+                "target": os.path.abspath(worklog_dir),
+            }]}, 2
+        plan = writer.plan_index(worklog_dir, {}, args.language)
+        common = {k: v for k, v in plan.items() if k not in ("original", "content")}
+
+        if not args.apply:
+            return {"ok": True, "mode": "dry-run", **common,
+                    "preview": plan["content"],
+                    "note": "No files have been modified."}, 0
+
+        writer.apply_index(plan["index_path"], plan["content"])
+        with open(plan["index_path"], "r", encoding="utf-8") as fh:
+            written = fh.read()
+        return {"ok": True, "mode": "apply", **common,
+                "written_sha256": writer.sha256(written),
+                "note": ("index.md written atomically. No git add / commit / "
+                         "push was performed.")}, 0
+    except writer.WriterError as exc:
+        return {"ok": False, "errors": [
+            {"code": exc.code, "message": exc.message, **exc.extra}]}, 2
+    except OSError as exc:
+        return {"ok": False, "errors": [
+            {"code": "IO_ERROR", "message": str(exc)}]}, 2
+
+
+def render_text(p: dict) -> str:
+    if not p.get("ok"):
+        return "".join(f"error: {e['message']}\n" for e in p.get("errors", []))
+
+    lines = [f"git-worklog reindex — {p['mode']}\n"]
+    lines.append(f"  {p['index_path']}\n")
+    lines.append(f"  {len(p['dates'])} day file(s) listed\n")
+    lines.append(f"  action: {p['action']}\n")
+    if p.get("preserved_index_manual"):
+        lines.append("  the index's MANUAL region was kept\n")
+    lines.append(f"\n{p['note']}\n")
+    return "".join(lines)

git_worklog/cli/report.py

@@ -0,0 +1,227 @@
+"""``git-worklog report`` — everything a report needs decided before it is written.
+
+Report mode's one entry point. It answers, in a single call, the four questions
+that must be settled before a word of a report is written:
+
+* **What is in scope?** A date range, or a tag's commit set (:mod:`.refs`).
+* **Is it backed by analysis?** Which days have a day file (:mod:`.coverage`).
+* **What must be left out?** For a tag, which citations in those day files belong
+  to another release (:mod:`.reconcile`).
+* **In which language?** Resolved here, independently of the day files being read.
+
+It writes nothing. The prose is the agent LLM's job (§6.1): this command decides
+*what may be said*, not what to say. There is deliberately no ``--out`` — the
+report does not exist yet at this point, so there would be nothing to write.
+
+Why one command rather than a module per report type
+----------------------------------------------------
+The roadmap (§11) sketched ``weekly.py`` / ``release.py`` / ``contributor.py``
+and four more. They are not here, because the seven report types differ only in
+their scope, an optional filter, and which question the user asked — and the
+v0.4.0 design that shipped report mode said so explicitly: the types are prompt
+examples in ``references/report-mode.md``, "非各自的程式分支". Seven modules each
+forwarding to the same two scope resolvers would be an abstraction over a single
+call site. §3.2 reserved the namespace for the day the types actually diverge;
+they have not, so the namespace stays unbuilt.
+"""
+
+from __future__ import annotations
+
+import os
+
+from git_worklog import dates as gwdates
+from git_worklog import language
+from git_worklog import markers as wm
+from git_worklog.analysis import AnalysisError
+from git_worklog.analysis import coverage as cov
+from git_worklog.analysis import history as ah
+from git_worklog.analysis import manifest as am
+from git_worklog.analysis import reconcile as rec
+from git_worklog.analysis import refs as refs_engine
+
+def _material(worklog_dir: str, dates: "list[str]") -> "list[dict]":
+    """The day files worth reading, in date order."""
+    out = []
+    for date in dates:
+        path = wm.day_path(worklog_dir, date)
+        if os.path.isfile(path):
+            out.append({"date": date, "path": path})
+    return out
+
+
+def run(args) -> "tuple[dict, int]":
+    try:
+        payload = _run(args)
+        # Exit 1 for a gap, matching `coverage`: it ran fine and the answer to
+        # "can I report on this?" is no. `out_of_range` deliberately does not
+        # earn a 1 — a day file citing another release's work is the normal
+        # case, not a failure. It is *why* the reconciliation exists, and the
+        # report simply leaves those commits out. Exiting 1 on the ordinary case
+        # would train the caller to ignore the code.
+        return payload, (0 if payload["fully_covered"] else 1)
+    except (AnalysisError, gwdates.DateError) as exc:
+        return {"ok": False, "errors": [
+            {"code": exc.code, "message": exc.message, **exc.extra}]}, 2
+    except language.LanguageError as exc:
+        return {"ok": False, "errors": [
+            {"code": exc.code, "message": exc.message, **exc.extra}]}, 2
+    except (ah.GitError, refs_engine.GitError) as exc:
+        return {"ok": False, "errors": [
+            {"code": "GIT_ERROR", "message": str(exc)}]}, 2
+
+
+def _run(args) -> dict:
+    is_ref = bool(args.tag or args.from_ref or args.to_ref)
+    is_date = bool(args.shortcut or args.date or args.days is not None
+                   or getattr(args, "from") or args.to)
+    if is_ref and is_date:
+        raise AnalysisError(
+            "ARG_CONFLICT",
+            "A report has one scope: a tag's commit set (--tag/--to-ref) or a "
+            "date range. The two do not mean the same thing — a version is "
+            "bounded by commits, the worklog is indexed by date. Pass one.")
+    if not is_ref and not is_date:
+        raise AnalysisError(
+            "NO_SCOPE",
+            "Provide a date scope (NNd, --date, --days, --from/--to) or a ref "
+            "scope (--tag, or --to-ref with an optional --from-ref).")
+
+    # Resolved before any Git work: an unusable language tag should say so
+    # whether or not the tag exists. Report language is decided here and owes
+    # nothing to the language the day files happen to be written in (§6.2.11) —
+    # this command never reads their language, only their hashes and prose.
+    lang = am.resolve_language(args.language, args.language_source, args.dir)
+
+    scope: dict
+    reconciliation = None
+    if is_ref:
+        r = refs_engine.resolve(
+            repo=args.repo, tag=args.tag, from_ref=args.from_ref,
+            to_ref=args.to_ref, list_tags_only=False,
+            timezone=args.timezone or "UTC", date_field=args.date_field)
+        scope = {
+            "kind": "ref",
+            "tag": r["tag"],
+            "prev_tag": r["prev_tag"],
+            "first_release": r["first_release"],
+            "commit_range": r["commit_range"],
+            "date_span": r["date_span"],
+        }
+        dates_arg = ",".join(r["dates"])
+        # An empty range has no dates to check; coverage would reject "".
+        coverage = (cov.check(repo=args.repo, dir=args.dir, dates=dates_arg,
+                              timezone=args.timezone or "UTC",
+                              date_field=args.date_field,
+                              worklog_dir=args.worklog_dir)
+                    if r["dates"] else None)
+    else:
+        scope = {"kind": "date"}
+        coverage = cov.check(
+            repo=args.repo, dir=args.dir, dates="", timezone=args.timezone,
+            date_field=args.date_field, worklog_dir=args.worklog_dir,
+            shortcut=args.shortcut, date=args.date, days=args.days,
+            from_=getattr(args, "from"), to=args.to, today=args.today,
+            max_days=args.max_days)
+        r = None
+
+    if coverage is None:
+        # A tag containing no commits: real (an empty release), and not a gap.
+        # There are no dates to ask `coverage` about — it rejects an empty
+        # --dates — so the same answer is assembled here. detect_timezone rather
+        # than a literal, so `timezone.source` carries the same vocabulary as
+        # every other path: a caller must not have to special-case the shape of
+        # an empty release.
+        info = ah.repo_info(args.repo)
+        _tz, tz_name, tz_source = gwdates.detect_timezone(args.timezone or "UTC")
+        resolved_dir = (args.dir if os.path.isabs(args.dir)
+                        else os.path.join(info["root"], args.dir))
+        coverage = {
+            "ok": True,
+            "repository": {"root": info["root"], "has_commits": info["has_commits"]},
+            "worklog_dir": resolved_dir, "dir_exists": os.path.isdir(resolved_dir),
+            "timezone": {"resolved": tz_name, "source": tz_source},
+            "date_field": args.date_field, "dates": [], "covered": [], "gaps": [],
+            "no_commit_dates": [], "gap_commit_count": 0, "fully_covered": True,
+        }
+
+    dates = [row["date"] for row in coverage["dates"]]
+    if is_ref:
+        # The check the prose could not hold. Runs for a ref scope only: a date
+        # scope has no authoritative commit set to reconcile against — its dates
+        # *are* the authority, so a day file citing anything on those days is
+        # in scope by definition.
+        reconciliation = rec.reconcile(args.repo, coverage["worklog_dir"],
+                                       r["commits"], r["dates"])
+
+    payload = {
+        "ok": True,
+        "scope": scope,
+        "language": lang.as_manifest(),
+        "repository": coverage["repository"],
+        "worklog_dir": coverage["worklog_dir"],
+        "dir_exists": coverage["dir_exists"],
+        "timezone": coverage["timezone"],
+        "date_field": coverage["date_field"],
+        "dates": coverage["dates"],
+        "covered": coverage["covered"],
+        "gaps": coverage["gaps"],
+        "no_commit_dates": coverage["no_commit_dates"],
+        "gap_commit_count": coverage["gap_commit_count"],
+        "fully_covered": coverage["fully_covered"],
+        "material": _material(coverage["worklog_dir"], dates),
+        "warnings": list(lang.warnings),
+    }
+    if is_ref:
+        payload["commit_count"] = r["commit_count"]
+        payload["commits"] = r["commits"]
+        payload["reconciliation"] = reconciliation
+    return payload
+
+
+def render_text(p: dict) -> str:
+    if not p.get("ok"):
+        return "".join(f"error: {e['message']}\n" for e in p.get("errors", []))
+
+    s, tz = p["scope"], p["timezone"]
+    head = (f"{s['commit_range']}" if s["kind"] == "ref"
+            else f"{p['dates'][0]['date']} .. {p['dates'][-1]['date']}"
+            if p["dates"] else "no dates")
+    lines = [f"git-worklog report — {head}\n"]
+    lines.append(f"  language: {p['language']['resolved']} "
+                 f"(via {p['language']['source']})\n")
+    lines.append(f"  ({tz['resolved']} via {tz['source']})\n")
+    if s["kind"] == "ref" and s["first_release"]:
+        lines.append("  first release: the range runs from the root commit\n")
+    lines.append("\n")
+
+    symbol = {"covered": "✓", "gap": "✗", "no-commits": "·"}
+    for row in p["dates"]:
+        note = (f"{row['commit_count']} commit(s)" if row["commit_count"]
+                else "no commits, no file expected")
+        lines.append(f"  {symbol[row['status']]} {row['date']}  "
+                     f"{row['status']:11} {note}\n")
+
+    if not p["fully_covered"]:
+        lines.append(f"\n{len(p['gaps'])} gap(s) covering {p['gap_commit_count']} "
+                     f"commit(s): {', '.join(p['gaps'])}\n")
+        lines.append("Real work exists on those days that nothing has analysed.\n")
+
+    rn = p.get("reconciliation")
+    if rn is not None:
+        lines.append(f"\n{p['commit_count']} commit(s) in range; "
+                     f"{rn['backed_count']} backed by a day file.\n")
+        for c in rn["unbacked"]:
+            lines.append(f"  unbacked     {c['short_hash']}  {c['subject']}\n")
+        if rn["unbacked"]:
+            lines.append("  ^ in this release, but no day file describes them. "
+                         "Do not claim to have analysed these.\n")
+        for c in rn["out_of_range"]:
+            lines.append(f"  out of range {c['short_hash']}  {c['subject']}\n"
+                         f"               cited on {', '.join(c['cited_on'])}\n")
+        if rn["out_of_range"]:
+            lines.append("  ^ the day files describe these, but they belong to a "
+                         "different release. Leave them out.\n")
+        for u in rn["unresolved"]:
+            lines.append(f"  unresolved   {u['hash']}  "
+                         f"cited on {', '.join(u['cited_on'])}, names no commit here\n")
+    return "".join(lines)

git_worklog/cli/validate.py

@@ -0,0 +1,252 @@
+"""``git-worklog validate`` — is what is on disk actually well-formed?
+
+This is the read-only integrity check: day files, their GENERATED/MANUAL
+markers, the index, and config. It reuses ``git_worklog.markers`` — the same
+parser the writers use — rather than re-deriving the rules, so validate can
+never disagree with what update/rebuild would produce.
+
+Roadmap §12.1 also lists preview records, analysis results and evidence links.
+Those are reported as ``skipped`` rather than quietly dropped: they are transient
+user-level state, and their validators live in ``git_worklog.preview`` /
+``analysis.results``, which run inside a pipeline where the run id is known. A
+result's language is checked there too, against the manifest that asked for it --
+a worklog directory has no manifest in scope to check against.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from git_worklog import config, language
+from git_worklog import markers as wm
+
+
+def _issue(code: str, message: str, **extra) -> dict:
+    return {"code": code, "message": message, **extra}
+
+
+def _validate_day(path: str, date: str) -> "tuple[list[dict], list[dict]]":
+    try:
+        with open(path, "rb") as fh:
+            raw = fh.read()
+    except OSError as exc:
+        return [_issue("UNREADABLE", f"{path}: {exc}", date=date)], []
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return [_issue("NON_UTF8", f"{path} is not valid UTF-8: {exc}", date=date)], []
+
+    _, issues = wm.scan_day(text, date)
+    fatal = [dict(i, date=date, target=path)
+             for i in issues if i["code"] in wm.FATAL_CODES]
+    warn = [dict(i, date=date, target=path)
+            for i in issues if i["code"] not in wm.FATAL_CODES]
+    return fatal, warn
+
+
+def _validate_index(worklog_dir: str, layout: str,
+                    disk_dates: "list[str]") -> "tuple[list[dict], list[dict]]":
+    path = wm.index_path(worklog_dir)
+    if not os.path.exists(path):
+        if disk_dates:
+            return [_issue("INDEX_MISSING",
+                           f"{len(disk_dates)} day file(s) exist but there is no "
+                           f"{path}. Rebuild it with rebuild_worklog_index.py.",
+                           target=path)], []
+        return [], []
+    try:
+        with open(path, "rb") as fh:
+            text = fh.read().decode("utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return [_issue("INDEX_UNREADABLE", f"{path}: {exc}", target=path)], []
+
+    doc, issues = wm.scan_index(text)
+    fatal = [dict(i, target=path) for i in issues if i["code"] in wm.FATAL_CODES]
+    warn = [dict(i, target=path) for i in issues if i["code"] not in wm.FATAL_CODES]
+    if doc is None:
+        return fatal, warn
+
+    listed = {d for d, _ in doc.rows}
+    on_disk = set(disk_dates)
+    # A row pointing at a day file that is gone is a broken link in the one
+    # document whose whole job is navigation.
+    for d in sorted(listed - on_disk):
+        fatal.append(_issue("INDEX_ROW_WITHOUT_FILE",
+                            f"The index lists {d} but {wm.day_path(worklog_dir, d, layout)} "
+                            "does not exist.", date=d, target=path))
+    for d in sorted(on_disk - listed):
+        warn.append(_issue("DAY_FILE_NOT_INDEXED",
+                           f"{d} has a day file but no index row; rebuild the index.",
+                           date=d, target=path))
+    return fatal, warn
+
+
+def _validate_config(worklog_dir: str) -> "tuple[list[dict], list[dict]]":
+    path = wm.config_path(worklog_dir)
+    if not os.path.exists(path):
+        return [], []
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            cfg = json.load(fh)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        return [_issue("CONFIG_INVALID", f"{path}: {exc}", target=path)], []
+    if not isinstance(cfg, dict):
+        return [_issue("CONFIG_INVALID", f"{path} must contain an object.",
+                       target=path)], []
+    got = cfg.get("schema_version")
+    if got is None:
+        return [], [_issue("CONFIG_NO_SCHEMA_VERSION",
+                           f"{path} has no schema_version.", target=path)]
+    if not isinstance(got, int):
+        return [_issue("CONFIG_INVALID",
+                       f"{path}: schema_version must be an integer (got {got!r}).",
+                       target=path)], []
+    if got > wm.LAYOUT_VERSION:
+        return [_issue("CONFIG_TOO_NEW",
+                       f"{path} declares schema_version {got}, newer than this build "
+                       f"understands ({wm.LAYOUT_VERSION}).", target=path)], []
+    return [], []
+
+
+def _validate_language(worklog_dir: str, layout: str,
+                       dates: "list[str]") -> "tuple[list, list]":
+    """Language settings and stamps on disk (§6.2.7, §6.2.12).
+
+    What is checkable from a worklog alone is that its declared languages are
+    tags this build can honour, and that day files carry a summary marker so the
+    index can find their summary whatever language they are in. What is NOT
+    checkable is whether the prose is *in* that language: engineering writing is
+    full of English identifiers by contract (§6.2.9), so a detector would flag
+    correct zh-TW work items. This deliberately does not try.
+    """
+    errors: "list[dict]" = []
+    warnings: "list[dict]" = []
+    cfg = config.load(worklog_dir)
+
+    for key in ("language", "index_language"):
+        raw = cfg.get(key)
+        if not isinstance(raw, str) or raw.strip().lower() == language.AUTO:
+            continue
+        try:
+            language.normalize(raw)
+        except language.LanguageError as exc:
+            errors.append(_issue("CONFIG_LANGUAGE_INVALID",
+                                 f"config.json {key}: {exc.message}",
+                                 target=wm.config_path(worklog_dir)))
+
+    index_path = wm.index_path(worklog_dir)
+    if os.path.exists(index_path):
+        try:
+            with open(index_path, "r", encoding="utf-8") as fh:
+                stamped = wm.index_language_of(fh.read())
+        except (OSError, UnicodeDecodeError):
+            stamped = None      # the index's own validator reports this
+        else:
+            if stamped is not None:
+                try:
+                    language.normalize(stamped)
+                except language.LanguageError as exc:
+                    errors.append(_issue("INDEX_LANGUAGE_INVALID",
+                                         f"index.md is stamped lang={stamped!r}, "
+                                         f"which is not usable: {exc.message}",
+                                         target=index_path))
+
+    for d in dates:
+        path = wm.day_path(worklog_dir, d, layout)
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                day = wm.parse_day(fh.read(), d)
+        except (OSError, UnicodeDecodeError, wm.WorklogFormatError):
+            continue            # _validate_day already reported it
+        if wm.summarise_generated(day.generated) and not wm.has_summary_marker(day.generated):
+            # Not an error: the zh-TW heading fallback still finds it, which is
+            # exactly why this is worth saying. The day works today and silently
+            # loses its index summary the moment it is regenerated in another
+            # language.
+            warnings.append(_issue(
+                "DAY_SUMMARY_UNMARKED",
+                f"{d}.md has no summary marker; its index row relies on the "
+                f"zh-TW heading fallback and would go blank if the day were "
+                f"rewritten in another language.", target=path))
+
+    return errors, warnings
+
+
+def run(args) -> "tuple[dict, int]":
+    repo = args.repo or "."
+    worklog_dir = args.dir or os.path.join(repo, wm.WORKLOG_DIRNAME)
+
+    if not os.path.isdir(worklog_dir):
+        return {
+            "ok": False,
+            "worklog_dir": os.path.abspath(worklog_dir),
+            "errors": [_issue("NOT_FOUND",
+                              f"{os.path.abspath(worklog_dir)} does not exist.",
+                              target=os.path.abspath(worklog_dir))],
+            "warnings": [], "day_count": 0,
+        }, 2
+
+    layout = wm.detect_layout(worklog_dir)
+    dates = wm.list_day_dates(worklog_dir, layout)
+
+    errors: "list[dict]" = []
+    warnings: "list[dict]" = []
+    for d in dates:
+        f, w = _validate_day(wm.day_path(worklog_dir, d, layout), d)
+        errors.extend(f)
+        warnings.extend(w)
+
+    f, w = _validate_index(worklog_dir, layout, dates)
+    errors.extend(f)
+    warnings.extend(w)
+    f, w = _validate_config(worklog_dir)
+    errors.extend(f)
+    warnings.extend(w)
+    f, w = _validate_language(worklog_dir, layout, dates)
+    errors.extend(f)
+    warnings.extend(w)
+
+    if layout == wm.LAYOUT_LEGACY:
+        warnings.append(_issue("LEGACY_LAYOUT",
+                               f"{worklog_dir} uses the pre-v0.6 flat layout. It is "
+                               "valid and readable, but not writable; migrate it with "
+                               "migrate_legacy_worklog.py --from-dir."))
+
+    return {
+        "ok": not errors,
+        "worklog_dir": os.path.abspath(worklog_dir),
+        "layout": layout,
+        "day_count": len(dates),
+        "dates": dates,
+        "errors": errors,
+        "warnings": warnings,
+        "skipped": [
+            {"check": "preview_records",
+             "reason": "Transient user-level state; validated by `git-worklog apply` "
+                       "against the record itself, where the preview_id is known."},
+            {"check": "analysis_results",
+             "reason": "Transient user-level state; validated by `git-worklog analyze "
+                       "collect` within a run, where the run_dir is known."},
+            {"check": "result_language",
+             "reason": "Analysis results are transient user-level state; their "
+                       "language is checked by collect_day_results.py against the "
+                       "run's manifest, where the expected tag is known."},
+        ],
+    }, (1 if errors else 0)
+
+
+def render_text(p: dict) -> str:
+    lines = [f"git-worklog validate — {p['worklog_dir']}"]
+    if p.get("layout"):
+        lines.append(f"  layout: {p['layout']}, {p['day_count']} day file(s)")
+    lines.append("")
+    for e in p.get("errors", []):
+        lines.append(f"  ✗ {e['code']}: {e['message']}")
+    for w in p.get("warnings", []):
+        lines.append(f"  ! {w['code']}: {w['message']}")
+    if not p.get("errors") and not p.get("warnings"):
+        lines.append("  ✓ No problems found.")
+    lines.append("")
+    lines.append("OK." if p["ok"] else f"FAILED: {len(p.get('errors', []))} error(s).")
+    return "\n".join(lines) + "\n"

git_worklog/cli/version.py

@@ -0,0 +1,47 @@
+"""``git-worklog version`` — every version that matters, and what each governs.
+
+Roadmap §12.1 asks for the CLI, engine, schema and skill-compatibility versions.
+They are reported separately because they answer different questions and move on
+different clocks: the product version tracks releases, while the layout and
+schema versions track the shape of data already on someone's disk and bump only
+when a migration is needed. Collapsing them would imply every release migrates
+user data. See issue #12 and docs/naming-conventions.md.
+"""
+
+from __future__ import annotations
+
+import platform
+
+from git_worklog import __version__
+from git_worklog.markers import LAYOUT_VERSION
+
+# The skill body and this package ship together in one directory, so they cannot
+# drift apart in a normal install. The number exists for the case where they can:
+# a pip-installed CLI meeting a separately-copied skill. Bump it when the CLI
+# changes in a way an older skill body cannot drive.
+SKILL_COMPAT_VERSION = 1
+
+
+def run(args) -> "tuple[dict, int]":
+    return {
+        "ok": True,
+        "cli_version": __version__,
+        # The engine is this same package today; PR 7 may split it out, at which
+        # point this stops being a copy of cli_version.
+        "engine_version": __version__,
+        "layout_version": LAYOUT_VERSION,
+        "schema_version": LAYOUT_VERSION,
+        "skill_compat_version": SKILL_COMPAT_VERSION,
+        "python_version": platform.python_version(),
+    }, 0
+
+
+def render_text(p: dict) -> str:
+    return (
+        f"git-worklog {p['cli_version']}\n"
+        f"  engine        {p['engine_version']}\n"
+        f"  layout        {p['layout_version']}    (.git-worklog/VERSION)\n"
+        f"  config schema {p['schema_version']}    (config.json schema_version)\n"
+        f"  skill compat  {p['skill_compat_version']}\n"
+        f"  python        {p['python_version']}\n"
+    )