git-worklog 1.6.0__py3-none-any.whl

git_worklog/__init__.py

@@ -0,0 +1,58 @@
+"""Git Worklog — engineering worklogs from real Git history and code.
+
+This package is the deterministic engine and CLI. It does the work that must be
+exact — date maths, Git collection, marker parsing, transactional writes,
+preview integrity — and leaves the semantic work (reading patches, deciding
+what actually changed) to the agent's LLM. See ``references/`` in the skill for
+that contract.
+
+It lives inside the skill directory so the skill stays copy-to-install with no
+dependencies, while ``pip install git-worklog`` puts the same code's CLI on
+PATH.
+"""
+
+# The single source of truth for the product version. pyproject.toml reads this
+# attribute; anything else that reports a version derives from here. The one copy
+# that cannot import it -- agents/openai.yaml, static YAML -- is pinned to it by a
+# guard test (tests/test_version.py), so the two cannot drift.
+#
+# Held at 0.4.0 through the internal v0.5-v0.9 milestones, then moved here to
+# 1.0.0 for the first public release since v0.4.0. See issue #12.
+#
+# 1.1.0 is a minor bump on a deliberately loose reading: no command, flag or JSON
+# field changed, but the skill stopped answering natural language without
+# /git-worklog and its menu switched to English. That is not an API break, and it
+# is not invisible either -- hence the prominent Changed entry in the CHANGELOG.
+#
+# 1.2.0 on the same reading: no command, flag or JSON field changed, but the
+# subagent contract pinned the write mechanism to a Bash heredoc, banned the
+# Write tool, and gave a Day Subagent a second thing it may reply --
+# FAILED:<date>. For anyone reading the contract that is an interface change.
+#
+# 1.2.1 is a patch: 1.2.0 banned the Write tool but not Edit, so a subagent whose
+# result failed its own parse check reached for Edit to fix the one bad line and
+# stalled there. Nothing in the interface moved -- the ban simply covers the tool
+# it always should have.
+#
+# 1.3.1 is a patch on the reading that `view`'s page is output, not interface: no
+# command, flag or JSON field changed. The light/dark switch and the copy badges
+# are the parts of 1.3.0's page that should have shipped with it.
+#
+# 1.4.0 is a minor bump on the 1.1.0 reading: no command, flag or JSON field
+# changed, but every host's default subagent model did (GPT-6 Luna, Gemini 3.8
+# Flash; Sonnet 5.5 and GPT-6.1 Sol to escalate). Which model reads your code,
+# and what a run costs, is not invisible.
+#
+# 1.5.0 is a minor bump by the plain rule: `view` gained a flag (`--serve`) and
+# its JSON gained fields (`commit_count`, `serving`). The commit drawer alone
+# would have read as page output, like 1.3.1; a server mode does not.
+#
+# 1.6.0 is a minor bump by the plain rule again: a new command (`models`), and
+# the model table a run reads moved from the package to the user's own file.
+__version__ = "1.6.0"
+
+# On-disk layout version of `.git-worklog/`, re-exported for convenience. It
+# describes the *data*, not the tool, and bumps only when a migration is needed.
+from git_worklog.markers import LAYOUT_VERSION  # noqa: E402
+
+__all__ = ["__version__", "LAYOUT_VERSION"]

git_worklog/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for ``python3 -m git_worklog``.
+
+The console script (``git-worklog``) only exists after a pip install. This form
+works straight from the skill directory with nothing installed, which is how the
+skill itself runs.
+"""
+
+from git_worklog.cli import main
+
+raise SystemExit(main())

git_worklog/analysis/__init__.py

@@ -0,0 +1,48 @@
+"""The analysis pipeline: Git facts in, validated per-day results out.
+
+This is the engine behind ``git-worklog analyze prepare`` and ``analyze
+collect`` (roadmap §7). It lives in the package rather than in ``scripts/``
+because only ``git_worklog*`` is packaged: an installed CLI has no ``scripts/``
+directory to shell out to, so anything the CLI needs has to be importable.
+
+The split mirrors the pipeline's three deterministic stages:
+
+* :mod:`~git_worklog.analysis.history` — what Git says happened.
+* :mod:`~git_worklog.analysis.manifest` — what a Day Subagent is asked to do.
+* :mod:`~git_worklog.analysis.results` — what came back, and whether it holds up.
+
+None of them summarise code or decide wording. That is the hosting agent's LLM's
+job (§6.1), and the CLI deliberately needs no model API key.
+"""
+
+from __future__ import annotations
+
+SCHEMA_VERSION = 1
+
+# A run's on-disk layout (§7.1). Two directories, not one: `collect` can then
+# tell a task that was never answered from a result nobody asked for. They live
+# here rather than in the CLI because `preview` reads the same run and must not
+# guess at the layout the CLI wrote.
+TASKS_SUBDIR = "tasks"
+RESULTS_SUBDIR = "results"
+# Scratch space for a large day's fan-out. Deliberately *not* inside results/:
+# `collect` treats every file there as a day's answer and fails the run over any
+# it did not ask for, so a Day Subagent's per-group parts need somewhere to land
+# that is not policed. See manifest.build's `parts_dir`.
+PARTS_SUBDIR = "parts"
+
+
+class AnalysisError(ValueError):
+    """A failure that carries the wire code the CLI and scripts report.
+
+    Mirrors :class:`git_worklog.language.LanguageError`: the pipeline's callers
+    are two thin shells (a script and a CLI subcommand) that both owe the user
+    one JSON object with a stable ``code``, so the code belongs on the
+    exception rather than being re-derived from the message at each call site.
+    """
+
+    def __init__(self, code: str, message: str, **extra):
+        self.code = code
+        self.message = message
+        self.extra = extra
+        super().__init__(message)

git_worklog/analysis/commits.py

@@ -0,0 +1,118 @@
+"""What Git knows about the commits a worklog cites (``git-worklog view``).
+
+Read-only, and narrow on purpose: it answers for the hashes it is handed and
+for nothing else, so a page built from it shows the commits the worklog talks
+about, never the repository's history.
+
+**The repository has to be the one the worklog lives in.** Git looks upward for
+a repository, so a worklog kept under an unrelated one -- a dotfiles ``~``, a
+monorepo -- would have its hashes resolved there, and ``view --serve`` would
+then hand out that repository's diffs. :func:`owns` therefore asks for the
+directory to be the top level itself.
+
+**Nothing here is an error.** A worklog outside any repository, a shallow clone
+and a hash rebased away are all ordinary; each one just means fewer commits to
+show, and the page falls back to what it did before it knew about Git.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+from git_worklog.analysis.history import UNIT_SEP, GitError, _git
+from git_worklog.analysis.reconcile import _batch_resolve
+
+RECORD_SEP = "\x1e"
+MAX_FILES = 200       # per commit; a vendoring commit lists thousands
+MAX_BODY = 20000      # characters of commit message body
+
+# How a commit is diffed -- for the file list here and for the patch the server
+# sends, so the two describe the same files. A merge is shown against its first
+# parent (what it brought in), the root commit against nothing; a signature is
+# never checked, which would start a program named by the repository's config.
+DIFF_FLAGS = ["--root", "--diff-merges=first-parent", "--no-show-signature",
+              "--submodule=short", "-M"]
+
+_FORMAT = "--format=%x1e" + "%x1f".join(["%H", "%h", "%an", "%aI", "%s", "%b"]) + "%x1f"
+
+
+def owns(repo: str) -> bool:
+    """Whether ``repo`` is itself the top level of a Git work tree."""
+    try:
+        top = _git(repo, ["rev-parse", "--show-toplevel"]).strip()
+    except (GitError, OSError):
+        return False
+    return os.path.realpath(top) == os.path.realpath(repo)
+
+
+def _parse(blob: str) -> "dict[str, dict]":
+    """``git log -z --numstat`` output, one record per ``RECORD_SEP``.
+
+    A record is its fields, each closed by ``UNIT_SEP``, then NUL; then, when
+    the commit changed files, a newline and NUL-terminated entries:
+    ``add\\tdel\\tpath``, or for a rename ``add\\tdel\\t`` followed by the old
+    and the new path as two entries of their own. Binary files count ``-``.
+    """
+    commits: "dict[str, dict]" = {}
+    for record in blob.split(RECORD_SEP)[1:]:
+        head, _, rest = record.partition(UNIT_SEP + "\0")
+        fields = head.split(UNIT_SEP)
+        if len(fields) < 6:
+            continue
+        full, short, author, date, subject = fields[:5]
+        body = UNIT_SEP.join(fields[5:]).strip()
+        entries = rest.lstrip("\n").split("\0")
+        files, adds, dels, i = [], 0, 0, 0
+        while i < len(entries):
+            parts = entries[i].split("\t", 2)
+            i += 1
+            if len(parts) < 3:
+                continue
+            add, dele, path = parts
+            old = None
+            if not path and i + 1 < len(entries):
+                old, path = entries[i], entries[i + 1]
+                i += 2
+            binary = add == "-"
+            files.append({"path": path, "old_path": old,
+                          "additions": None if binary else int(add),
+                          "deletions": None if binary else int(dele)})
+            if not binary:
+                adds += int(add)
+                dels += int(dele)
+        commits[full] = {
+            "sha": full, "short": short, "author": author, "date": date,
+            "subject": subject, "body": body[:MAX_BODY],
+            "body_truncated": len(body) > MAX_BODY,
+            "files": files[:MAX_FILES], "file_count": len(files),
+            "additions": adds, "deletions": dels,
+        }
+    return commits
+
+
+def collect(repo: str, tokens) -> "tuple[dict[str, dict], dict[str, str]]":
+    """(commits by full hash, full hash by token) for the tokens naming a commit.
+
+    A token that names nothing, names a tree or a blob, or is ambiguous is in
+    neither: the caller treats it as text.
+    """
+    tokens = sorted({t.lower() for t in tokens})
+    if not tokens or not owns(repo):
+        return {}, {}
+    try:
+        resolved = _batch_resolve(repo, tokens)
+        shas = sorted(set(resolved.values()))
+        if not shas:
+            return {}, {}
+        proc = subprocess.run(
+            ["git", "-C", repo, "log", "--no-walk", "--stdin", *DIFF_FLAGS,
+             "--numstat", "-z", _FORMAT],
+            input="\n".join(shas).encode("ascii"),
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        if proc.returncode != 0:
+            return {}, {}
+    except (GitError, OSError):
+        return {}, {}
+    commits = _parse(proc.stdout.decode("utf-8", "replace"))
+    return commits, {t: s for t, s in resolved.items() if s in commits}

git_worklog/analysis/coverage.py

@@ -0,0 +1,149 @@
+"""Report which dates have worklog coverage, for report mode.
+
+Report mode answers questions from the day files already on disk. Before it can
+do that honestly it has to know which of the requested dates actually have an
+analysis behind them -- otherwise it quietly degrades into summarising commit
+messages, which is the one thing this skill exists not to do.
+
+The distinction that matters
+----------------------------
+A date with no worklog file is **not** automatically a gap. Per
+``references/worklog-format.md`` §6, a day with no commits is deliberately given
+no file -- the directory is not padded with empty days. So each date is one of:
+
+* ``covered``    -- has commits and has a day file. Usable material.
+* ``gap``        -- has commits but no day file. **A real gap**: real work exists
+                    that nothing has analysed.
+* ``no-commits`` -- no commits, so no file is expected. Nothing is missing.
+
+Conflating ``no-commits`` with ``gap`` would send the user off to backfill days
+that can never produce a file.
+
+Commit counts come from :func:`git_worklog.analysis.history.collect_commits`, so
+the self-referential worklog-commit exclusion is inherited: a day whose only
+commits edited the worklog directory counts as ``no-commits``, not as a gap.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import date as date_cls
+
+from git_worklog import dates as gwdates
+from git_worklog import markers as wm
+from git_worklog.analysis import AnalysisError
+from git_worklog.analysis import history as cgh
+
+# Report mode's day cap. Generation is bounded at 30 because each day costs a
+# subagent; report mode only reads day files that already exist, so the thing
+# that cap protects is not at stake and a quarter is a reasonable question to
+# ask of a worklog.
+REPORT_MAX_DAYS = 90
+
+
+def _has_day_file(worklog_dir: str, date_str: str) -> bool:
+    # Resolve against the layout actually on disk, so a not-yet-migrated
+    # worklog reports its real coverage instead of a repo-wide false gap.
+    return os.path.isfile(wm.day_path(worklog_dir, date_str))
+
+
+def _parse_dates(raw: str) -> "list[str]":
+    """An explicit ``a,b,c`` list. Ref scope's dates are a set, not a range."""
+    parsed = [d.strip() for d in raw.split(",") if d.strip()]
+    if not parsed:
+        raise AnalysisError("NO_DATES", "Provide at least one date via --dates.")
+    for d in parsed:
+        # wm.is_valid_date only checks the YYYY-MM-DD shape, so it accepts
+        # impossible dates like 2026-13-99; parse to reject those here rather
+        # than let them raise out of the day window as a bare traceback.
+        if not wm.is_valid_date(d):
+            raise AnalysisError("INVALID_DATE", f"Not an ISO YYYY-MM-DD date: {d}.", date=d)
+        try:
+            date_cls.fromisoformat(d)
+        except ValueError:
+            raise AnalysisError("INVALID_DATE", f"Not a real calendar date: {d}.", date=d)
+    return parsed
+
+
+def check(repo: str = ".", dir: "str | None" = None, dates: str = "",
+          timezone: "str | None" = None, date_field: str = "committer",
+          worklog_dir: "str | None" = None, shortcut: "str | None" = None,
+          date: "str | None" = None, days: "int | None" = None,
+          from_: "str | None" = None, to: "str | None" = None,
+          today: "str | None" = None,
+          max_days: "int | None" = None) -> dict:
+    """Coverage for the requested dates. Raises AnalysisError or GitError.
+
+    Two ways to say which dates, because report mode has two scopes and they are
+    shaped differently. A *date* scope is a range, so it is given the same way
+    `analyze prepare` takes one and resolved by the same contract. A *ref* scope
+    is whatever days a tag's commits happen to fall on — an arbitrary set, with
+    gaps — so it arrives as an explicit ``dates`` list instead.
+    """
+    if dates and (shortcut or date or days is not None or from_ or to):
+        raise AnalysisError(
+            "ARG_CONFLICT",
+            "--dates lists exact days; the range flags resolve a span. Pass one.")
+
+    dir = dir or wm.WORKLOG_DIRNAME
+    worklog_dir = worklog_dir or cgh.DEFAULT_WORKLOG_DIR
+
+    if dates:
+        requested = _parse_dates(dates)
+        # An explicit list still needs a zone to know where its days start.
+        # UTC rather than the machine's: the caller of this form is ref scope,
+        # which already resolved these dates under a zone it chose, and guessing
+        # a different one here would silently re-cut the day boundaries.
+        tz, tz_name, tz_source = gwdates.detect_timezone(timezone or "UTC")
+    else:
+        # The same date contract generation mode uses, with report mode's own
+        # cap: it reads day files already on disk and spawns no subagents, so
+        # the 30-day bound on subagent cost does not apply to it.
+        d, n = gwdates.absorb_shortcut(shortcut, date, days)
+        resolved = gwdates.resolve(
+            date=d, days=n, from_=from_, to=to, timezone=timezone, today=today,
+            max_days=REPORT_MAX_DAYS if max_days is None else max_days)
+        requested = [e["date"] for e in resolved["dates"]]
+        tz, tz_name, tz_source = gwdates.detect_timezone(resolved["timezone"])
+
+    info = cgh.repo_info(repo)  # raises NOT_A_GIT_REPO when applicable
+    resolved_dir = dir if os.path.isabs(dir) else os.path.join(info["root"], dir)
+    dir_exists = os.path.isdir(resolved_dir)
+
+    results = []
+    for date_str in sorted(set(requested)):
+        if info["has_commits"]:
+            start, end = gwdates.day_window(date_str, tz)
+            commits = cgh.collect_commits(repo, start, end, date_field, worklog_dir)
+        else:
+            commits = []
+        has_worklog = dir_exists and _has_day_file(resolved_dir, date_str)
+        if not commits:
+            status = "no-commits"
+        elif has_worklog:
+            status = "covered"
+        else:
+            status = "gap"
+        results.append({
+            "date": date_str,
+            "commit_count": len(commits),
+            "has_worklog": has_worklog,
+            "status": status,
+        })
+
+    gaps = [r["date"] for r in results if r["status"] == "gap"]
+    return {
+        "ok": True,
+        "repository": {"root": info["root"], "has_commits": info["has_commits"]},
+        "worklog_dir": resolved_dir,
+        "dir_exists": dir_exists,
+        "timezone": {"resolved": tz_name, "source": tz_source},
+        "date_field": date_field,
+        "dates": results,
+        "covered": [r["date"] for r in results if r["status"] == "covered"],
+        "gaps": gaps,
+        "no_commit_dates": [r["date"] for r in results if r["status"] == "no-commits"],
+        "gap_commit_count": sum(r["commit_count"] for r in results
+                                if r["status"] == "gap"),
+        "fully_covered": not gaps,
+    }