@nidvue/teamwork 1.1.1 → 1.4.2

package/skills/teamwork/src/teamwork/gitutil.py

@@ -114,9 +114,50 @@ def branch_worktree(project: Path, branch: str):
     return None
 
 
+class HooksDirUnresolved(RuntimeError):
+    """git could not answer ``rev-parse --git-path hooks`` for this work tree.
+
+    This exception is the *single* hooks-directory contract: it is raised here and
+    each caller chooses what a failure means for it. ``hooks.hooks_dir`` (the
+    installer) hands the message to ``die``, so the operator sees the same text as
+    before; ``harness.hooks_dir`` (a report, which must never abort a listing)
+    catches it and returns ``None``. Two divergent implementations of the same
+    ``rev-parse`` made the report disagree with the installer about both resolution
+    and failure - one function, two policies, is the fix.
+    """
+
+    def __init__(self, project: Path, stderr: str) -> None:
+        self.project = project
+        self.stderr = stderr
+        super().__init__(f"cannot resolve the git hooks directory for {project}: {stderr}")
+
+
+def hooks_dir(project: Path) -> Path:
+    """``<git-dir>/hooks``, resolved, so a linked worktree finds the shared one.
+
+    ``git rev-parse --git-path hooks`` prints a path relative to ``project``; it is
+    resolved here because inside a worktree the answer is the *common* git
+    directory, which is not under ``project`` at all. Raises
+    :class:`HooksDirUnresolved` when git cannot answer - the callers decide whether
+    that is fatal (installer) or a reported absence (harness).
+    """
+    result = run_git(project, "rev-parse", "--git-path", "hooks")
+    if result.returncode != 0 or not result.stdout.strip():
+        raise HooksDirUnresolved(project, result.stderr.strip())
+    located = Path(result.stdout.strip())
+    return (located if located.is_absolute() else project / located).resolve()
+
+
 def ensure_lfs(project: Path, quiet: bool = False) -> dict:
-    """Enable Git LFS locally and keep .gitattributes in sync."""
-    result = {"available": False, "installed": False, "patterns_added": 0}
+    """Enable Git LFS locally and keep .gitattributes in sync.
+
+    ``installed`` and ``install_error`` are the readable status the caller (and a
+    test) can act on: a failed ``git lfs install`` used to be swallowed while the
+    probe above warned, which left a repository whose ``.gitattributes`` names LFS
+    filters that git has never been told about - every large binary then committed
+    as a plain blob, silently.
+    """
+    result = {"available": False, "installed": False, "install_error": "", "patterns_added": 0}
     probe = subprocess.run(["git", "lfs", "version"], capture_output=True, text=True)
     if probe.returncode != 0:
         if not quiet:
@@ -130,6 +171,14 @@ def ensure_lfs(project: Path, quiet: bool = False) -> dict:
         ["git", "-C", str(project), "lfs", "install", "--local"], capture_output=True, text=True
     )
     result["installed"] = inst.returncode == 0
+    if not result["installed"]:
+        result["install_error"] = (inst.stderr.strip() or inst.stdout.strip())[:500]
+        if not quiet:
+            print(
+                "teamwork: WARNING `git lfs install --local` failed; large binaries will"
+                " be committed as plain blobs. Run it by hand to enable archival"
+                f" ({result['install_error'] or 'no output'})."
+            )
 
     path = project / ".gitattributes"
     existing = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
@@ -150,21 +199,110 @@ def ensure_lfs(project: Path, quiet: bool = False) -> dict:
     return result
 
 
+BINARY_SNIFF_BYTES = 8192
+
+
+def is_binary_content(path: Path) -> bool:
+    """True when the file's CONTENT is binary, the way git decides it.
+
+    The LFS threshold is a binary threshold (Architecture 11.10): a text record
+    that grows past it is still a document, so the gates must not refuse it. The
+    test reads the bytes, never the name, because a name can be defeated - a
+    real binary renamed ``.md`` is still a binary, and a genuine binary dropped
+    into ``docs/Team/`` is still a binary. Git makes the same call from the
+    bytes (``git diff --numstat`` prints ``-  -`` for a binary), so this is the
+    model the repository already trusts.
+
+    A NUL byte in the first 8 KiB is the discriminator, with one exception: a
+    UTF-16 document also contains NUL bytes, so a head that decodes as UTF-16
+    into printable text is text and stays exempt.
+
+    The exception is bounded by NUL DENSITY, and it has to be: a UTF-16 file that
+    contains NUL bytes at all is a mostly-ASCII document, because a NUL byte IS
+    the high half of an ASCII unit - so such a head is at least a quarter NULs.
+    (A CJK-only UTF-16 document carries almost no NULs, and it is already text
+    above, before this branch is reached.) Without the density bound a single
+    leading NUL followed by a run of ``x`` bytes decodes as printable CJK and a
+    real 1 MiB blob passes every LFS gate - the gate would be vacuous exactly
+    where it matters. `tests/unit/test_audit_evidence_sources.py::
+    test_a_large_binary_is_still_an_lfs_candidate` pins that case.
+    """
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(BINARY_SNIFF_BYTES)
+    except OSError:
+        return False
+    if not head:
+        return False
+    nul_ratio = head.count(b"\x00") / len(head)
+    if not nul_ratio:
+        return False
+    if nul_ratio < 0.25:
+        return True
+    for encoding in ("utf-16-le", "utf-16-be"):
+        try:
+            candidate = head.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+        if candidate and all(ch.isprintable() or ch in "\n\r\t" for ch in candidate):
+            return False
+    return True
+
+
+def _attr_matches(pattern: str, rel: str, name: str) -> bool:
+    """Whether a .gitattributes pattern covers this path."""
+    if pattern.startswith("*."):
+        return name.endswith(pattern[1:])
+    return bool(Path(rel).match(pattern))
+
+
 def lfs_tracked(project: Path, rel: str) -> bool:
+    """Whether a .gitattributes pattern would route this file into Git LFS.
+
+    The LAST matching line wins, as git reads it: a later ``-filter`` opt-out
+    cancels an earlier ``filter=lfs`` pattern. The opt-out matters because
+    `.gitattributes` opts the small social-preview PNG and the brand assets OUT
+    of LFS, and a check that ignored the opt-out would report them as LFS
+    files - and, for a text file, would report a misconfiguration that does not
+    exist.
+    """
     path = project / ".gitattributes"
     if not path.exists():
         return False
     name = Path(rel).name
+    tracked = False
     for line in path.read_text(encoding="utf-8").splitlines():
         parts = line.split()
-        if len(parts) >= 2 and "filter=lfs" in line:
-            pattern = parts[0]
-            if pattern.startswith("*."):
-                if name.endswith(pattern[1:]):
-                    return True
-            elif Path(rel).match(pattern):
-                return True
-    return False
+        if len(parts) < 2:
+            continue
+        if not _attr_matches(parts[0], rel, name):
+            continue
+        if "filter=lfs" in line:
+            tracked = True
+        elif "-filter" in line:
+            tracked = False
+    return tracked
+
+
+def lfs_text_mismatch(project: Path, rel: str) -> bool:
+    """True when a TEXT file is captured by an LFS pattern - a misconfiguration.
+
+    ``.gitattributes`` routes a file into Git LFS BY NAME. A name is not
+    evidence, so a text file can be routed into LFS by accident: a record
+    written to ``assets/movie.bin`` is a 126-byte POINTER in the tree, and the
+    document is gone for every reader without an LFS client. LFS is for
+    binaries; a document in LFS is broken.
+
+    The size threshold is not the discriminator here and must not be: a text
+    file in LFS is broken at ANY size, so this check is size-independent. It
+    asks two questions of the same file - is the content text (the shared
+    ``is_binary_content``) and does a pattern capture the name (the shared
+    ``lfs_tracked``) - and both answers are reused by the three gates, so the
+    gates cannot disagree about which files are misconfigured.
+    """
+    if not lfs_tracked(project, rel):
+        return False
+    return not is_binary_content(project / rel)
 
 
 def branch_name(instance: str, task_id: str, title: str) -> str: