graphite-code 1.3.0__tar.gz → 1.4.0__tar.gz

{graphite_code-1.3.0 → graphite_code-1.4.0}/CHANGELOG.md

@@ -15,6 +15,126 @@ machine-checkable identity; the version is for humans.
 
 ## [Unreleased]
 
+## [1.4.0] — 2026-10-25
+
+A minor release: eight fixes, to the Python graph, the build, the CLI and the
+agent hooks, and one addition to the hook contract (#101).
+
+The `hooks` check of `doctor --json` gains the field `chain_slots`, and
+`graphite init` reports the same slots beside the hooks it installs; both are
+additions under `docs/compatibility.md`. No field is removed or renamed,
+`Requires-Dist` and the entry points are those of 1.3.0, and `graphite init`
+writes what it wrote (`DOC_VERSION` 15): in a new repository, `init --all`
+leaves 17 files, the three trampolines among them, and a `.git/config`, each
+byte for byte as 1.3.0 leaves it.
+
+The graph changes in this release. On this repository, measured against the
+deployed 1.3.0 engine, with the same interpreter, from one tree:
+
+- every definition and file node id survives (6,616 and 425), each naming
+  the same definition or file, and none is new. This tree has no pair of
+  paths that #82 tells apart;
+- 24 placeholder nodes are gone and 4 are new, so 9,164 nodes become 9,144;
+- 32 of the 120 `inherits` edges ended at a placeholder and now end at the
+  class the base names (#86);
+- `calls` goes from 16,065 to 16,066. 21 call sites through a local alias
+  ended at a placeholder named for the local: 16 now end at a definition,
+  and 5 at a placeholder for a name the module only imports, which is where
+  a direct call of it already ended (#90; that gap is #107). One call site is
+  new (#85). `contains` (6,614) and `imports` (2,431) are unchanged, and
+  25,177 of the 25,230 edge triples are unchanged;
+- the Python `calls` ratio goes from 0.976 to 0.978: 12,001 of 12,276 call
+  sites are bound, where 11,984 of 12,275 were;
+- `analysis` lists 20 cycles before and after, and one entry is new, in
+  `git.py`: the new `inherits` edge closes a loop through a
+  `super().__init__` call that both engines bind to the wrong `__init__`
+  (#106). The entry it displaced is still a cycle in the graph. Entry
+  points, god nodes, orphans, surprising connections and top files are
+  identical, and so is the community count (177).
+
+Two builds of this tree with either engine are byte-identical (`graph.json`,
+`GRAPH_REPORT.md`, `graph.html`).
+
+The entries below quote figures measured when each change was made, on
+earlier commits of this tree, so they differ from the ones above.
+
+### Added
+
+**Where another tool's git hook goes is declared, not only written in
+shell.** Each of graphite's trampolines (`post-commit`, `post-merge`,
+`post-rewrite`) runs `<hook>.local` beside it first when that file exists. The
+name was stated only inside the trampoline's text. When graphite was installed
+first, nothing was in that slot, and a hook manager that would not chain to
+graphite's trampoline left its own hook out entirely (channel rounds 322 to
+324). The name is now part of the hook contract in `docs/compatibility.md`.
+It is reported in two places:
+
+- the `hooks` check of `doctor --json`, as `chain_slots`: for each trigger,
+  the `file` relative to the hooks directory and whether it is `present`;
+- the hook line of `graphite init`, in either install order.
+
+An empty slot is not a finding. The trampolines are byte for byte those of
+1.3.0. This adds a field to `doctor --json`, so the next release is a minor.
+
+### Fixed
+
+- Python: a name a package re-exports is followed to the file that defines it
+  (#87). `from pkg import Base` used to bind to `pkg/__init__.py`, so a call of
+  a re-exported function ended at a placeholder, and a `self.m()` in a class
+  whose base was re-exported had no edge and was not counted, which let
+  `callers` answer `decision_grade` without that caller. Only a plain
+  top-level `from X import name` in an `__init__.py` is followed, for as many
+  steps as the source states; a name the package binds some other way, a cycle,
+  and a module other than `__init__.py` stay as they were. The Python cache key
+  gains a digest of the re-exports, so an unchanged importer is re-resolved
+  when an `__init__.py` changes.
+- Python: an `inherits` edge ends at the class its base names (#86). Its far
+  end was always a node made from the base's bare name, of kind `unknown`, so
+  the graph held no link from a class to its base and every class of one name
+  shared one placeholder. A base that is a bare name the file binds by a
+  class statement or imports by name now ends at that class's node; a
+  builtin, a dotted name or a call keeps its placeholder.
+- Python: a call through a local alias binds to what the alias names (#90).
+  `t = mod.target` followed by `t(x)` used to end at a placeholder named for
+  the local, so `callers target` left that function out and still answered
+  `decision_grade`. A name bound by one assignment of a bare name or of
+  `module.attr` is read as that name or attribute, as the call written
+  directly is, also through a chain of such assignments. A name bound a
+  second time in its scope, a `with ... as` name, a cycle, and a longer chain
+  such as `a.b.c` stay as they were.
+- Build: two paths that differ only by `/`, `.` or `_` keep a file node each
+  (#82). `a/b.py` and `a_b.py` both made `a_b_py`, so one had no node and its
+  definitions hung off the other's. Only the paths of the tree that actually
+  collide are marked, each with a hash of its exact path; every other file
+  node id is what it was. A tree with such a pair re-extracts once, because
+  the marked ids are folded into the cache key.
+- Python: a bare call of a name the file binds gets its edge also when the
+  name is a builtin of another language (#85). The list that drops calls of
+  builtins holds JavaScript, Go and Rust names beside Python's, so a class
+  `Error` or a function `make` had no callers in the graph and its call sites
+  were absent from the `calls` ratio. A listed name that nothing in the file
+  binds still gets no edge.
+- CLI: `build` and `report` of a path that is not there say `path not found`
+  and exit 1, as `scan` does, and create nothing (#88). The build lock made
+  its cache directory first, which made the path, and a complete empty
+  `graph-out/` was written into it with exit 0. `build --detach` is refused
+  the same way. Below a repository root the message is still the one that
+  names the root.
+- CLI: `doctor` typed below a repository's root reports on the repository
+  (#89). It took the folder for the repository, so in a subfolder of a
+  repository with a fresh graph it said `Graph artifact is missing` and
+  offered a build that is refused there, and its incident line read a ledger
+  nothing writes. It now follows the root, as the read commands do (#81); a
+  `.git` above that graphite does not take is not followed.
+- Agent hooks: the strict hook reads files piped to `Select-String` as a
+  search of them (#84). `Get-ChildItem -Recurse src | Select-String name` was
+  let through as a filter, while `Select-String name -Path src` was refused.
+  A listing (`Get-ChildItem`, `gci`, `ls`, `dir`) now hands its paths to a
+  `Select-String` after it, also across `Where-Object`, `Select-Object` and
+  `Sort-Object`, and the search is judged as the path form is. `-Name`
+  listings, other commands' output and any other stage between them stay
+  filters.
+
 ## [1.3.0] — 2026-10-16
 
 A minor release, with a security fix: from a folder below a repository's

{graphite_code-1.3.0 → graphite_code-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphite-code
-Version: 1.3.0
+Version: 1.4.0
 Summary: Local-first, zero-LLM knowledge graph extraction for codebases.
 Project-URL: Homepage, https://github.com/jared0565/graphite
 Project-URL: Repository, https://github.com/jared0565/graphite
@@ -48,7 +48,7 @@ Description-Content-Type: text/markdown
 
 Local-first, deterministic knowledge graph extraction for codebases — zero-LLM, daemon-maintained, agent-agnostic.
 
-**Status: 1.3.0, production/stable.** Published on PyPI as
+**Status: 1.4.0, production/stable.** Published on PyPI as
 [`graphite-code`](https://pypi.org/project/graphite-code/) with PEP 740
 attestations; supported on Windows, Linux and macOS with Python 3.11–3.14
 (every cell gates CI). What 1.x promises — CLI, JSON outputs, `graph.json`,

{graphite_code-1.3.0 → graphite_code-1.4.0}/README.md

@@ -2,7 +2,7 @@
 
 Local-first, deterministic knowledge graph extraction for codebases — zero-LLM, daemon-maintained, agent-agnostic.
 
-**Status: 1.3.0, production/stable.** Published on PyPI as
+**Status: 1.4.0, production/stable.** Published on PyPI as
 [`graphite-code`](https://pypi.org/project/graphite-code/) with PEP 740
 attestations; supported on Windows, Linux and macOS with Python 3.11–3.14
 (every cell gates CI). What 1.x promises — CLI, JSON outputs, `graph.json`,

{graphite_code-1.3.0 → graphite_code-1.4.0}/src/graphite/__init__.py

@@ -38,4 +38,4 @@ __all__ = ["__version__"]
 #: Coarse and hand-maintained by construction. It is a release label, not
 #: evidence that a given fix is present -- to answer that, survey for the marker
 #: the fix introduced, or compare `graphite --version` fingerprints.
-__version__ = "1.3.0"
+__version__ = "1.4.0"

{graphite_code-1.3.0 → graphite_code-1.4.0}/src/graphite/agent_hooks.py

@@ -968,6 +968,54 @@ def _forget_what_may_be_set_again(assigned: dict[str, str], argv: list[str], pow
             assigned.pop(named.group().lower() if powershell else named.group(), None)
 
 
+# PowerShell commands whose output is the files (or folders) of a path, so that a
+# `Select-String` after a pipe searches what they hand it (#84).
+_FILE_LISTINGS = frozenset({"get-childitem", "gci", "ls", "dir"})
+# The searches that take files from the pipeline. `grep` does not: it reads the
+# lines of what is piped, so `ls | grep name` filters a list of names.
+_POWERSHELL_SEARCHES = frozenset({"select-string", "sls"})
+# What may stand between such a listing and the search and still hand the search
+# files: a stage that only keeps or orders them. Any other stage (`ForEach-Object`,
+# `Out-String`, `Select-Object -ExpandProperty`) may make text, and ends the chain.
+_FILE_KEEPING_STAGES = frozenset({
+    "where-object", "where", "?", "select-object", "select", "sort-object", "sort",
+})
+# Listing flags that take a word, so the word is not a path. `-Path` and
+# `-LiteralPath` are the exceptions: their word IS one.
+_LISTING_VALUE_FLAGS = frozenset({
+    "-filter", "-include", "-exclude", "-depth", "-attributes",
+})
+_LISTING_PATH_FLAGS = frozenset({"-path", "-literalpath"})
+
+
+def _listed_paths(name: str, rest: list[str]) -> list[str] | None:
+    """The paths a file listing names, else None where `name` lists no files.
+
+    An empty list is a listing of the current directory. `-Name` makes the
+    listing text, and what is piped on is then a filter of it.
+    """
+    if name not in _FILE_LISTINGS:
+        return None
+    paths: list[str] = []
+    expecting = False
+    skipping = False
+    for token in rest:
+        lowered = token.lower()
+        if expecting or skipping:
+            if expecting:
+                paths.append(token)
+            expecting = skipping = False
+        elif lowered == "-name" or lowered == "-n":
+            return None
+        elif lowered in _LISTING_PATH_FLAGS:
+            expecting = True
+        elif lowered in _LISTING_VALUE_FLAGS:
+            skipping = True
+        elif not token.startswith("-"):
+            paths.append(token)
+    return paths
+
+
 def _bash_searches(
     command: str, root: Path, msys: bool = False, cwd: Path | None = None, powershell: bool = False
 ) -> list[_Search]:
@@ -1024,9 +1072,11 @@ def _bash_searches(
         base, placed = start, start_placed  # `base` is where the shell is
         moved = False  # a `cd`, or a command the hook does not model, has run in this shell
         pipeline_base, pipeline_placed = base, placed  # where the pipeline being read started
+        listed: list[str] | None = None  # the paths of the file listing whose output the stage before gives
         for head in _bash_command_heads(lines, powershell):
             piped = head.before in ("|", "|&")  # `||` is or-else, not a pipe
             if not piped:
+                listed = None
                 if head.before != "&&":
                     base, placed = (None, False) if moved else (start, start_placed)
                 pipeline_base, pipeline_placed = base, placed
@@ -1040,6 +1090,16 @@ def _bash_searches(
             if len(head.argv) == 1 and _NESTED_RE.fullmatch(head.argv[0]):
                 continue  # a subshell standing alone
             if piped and _command_name(head.argv[0]) != "xargs":
+                stage = _command_name(head.argv[0])
+                if listed is not None and stage in _POWERSHELL_SEARCHES:
+                    # `Get-ChildItem -Recurse src | Select-String name` searches
+                    # the files it is handed (#84), as `xargs grep` does.
+                    found = _search_in(stage, [_expanded(t, assigned, powershell) for t in head.argv[1:]], here, msys)
+                    if found is not None:
+                        found = found._replace(paths=_located(listed, here, msys))
+                        searches.append(found if here_placed or cwd is None else _unplaced(found, cwd))
+                if stage not in _FILE_KEEPING_STAGES:
+                    listed = None
                 continue  # a filter: it reads what the command before it wrote
             assignments = _assignments(head.argv, powershell)
             if assignments is not None:
@@ -1063,6 +1123,7 @@ def _bash_searches(
                 continue
             name = _command_name(argv[0])
             rest = [_expanded(token, assigned, powershell) for token in argv[1:]]
+            listed = _listed_paths(name, rest) if len(argv) == len(written) else None
             # A `cd` behind a wrapper is not the shell's: `env cd docs` moves a
             # program that then exits, and `! cd docs && ...` goes on only when
             # the `cd` failed. It is read below, as a command that may move.

{graphite_code-1.3.0 → graphite_code-1.4.0}/src/graphite/cli.py

@@ -255,12 +255,17 @@ def _write_json(path: Path, data: dict[str, Any]) -> None:
     atomic_write_json(path, data, indent=2)
 
 
-def _scan(args: argparse.Namespace, cfg: Config) -> tuple[dict[str, Any], list[Any]]:
-    cfg = cfg.canonical_graph()
-    root = Path(args.path).resolve()
+def _require_existing(root: Path) -> None:
+    """Exit 1 with `path not found` for a path that is not there."""
     if not root.exists():
         print(f"[graphite] path not found: {root}", file=sys.stderr)
         raise SystemExit(1)
+
+
+def _scan(args: argparse.Namespace, cfg: Config) -> tuple[dict[str, Any], list[Any]]:
+    cfg = cfg.canonical_graph()
+    root = Path(args.path).resolve()
+    _require_existing(root)
     top = _root_above(root)
     if top is not None:
         raise ValueError(_below_a_root(root, top))
@@ -727,6 +732,9 @@ def cmd_build(args: argparse.Namespace) -> int:
     top = _root_above(asked)
     if top is not None:
         raise ValueError(_below_a_root(asked, top))
+    # A path that is not there is refused as `scan` refuses it (#88): the lock
+    # below would otherwise make it, and a detached child could not start in it.
+    _require_existing(asked)
     if getattr(args, "detach", False):
         root = Path(args.path).resolve()
         # Deliberately omits --detach: the child must build, not re-spawn.
@@ -839,6 +847,10 @@ def cmd_doctor(args: argparse.Namespace) -> int:
     root = Path(args.path).resolve()
     if not root.is_dir():
         raise ValueError("doctor path must be an existing directory")
+    # The report is about the repository the folder is in (#89), as the read
+    # commands are: from a subfolder the graph is the root's, and so are the
+    # incidents. A root graphite does not take (`repository_root`) is not followed.
+    root = repository_root(root)
     cfg = _project_scoped_config(args, root)
     report = run_doctor(
         root,
@@ -1204,6 +1216,11 @@ def cmd_init(args: argparse.Namespace) -> int:
             extra += f", reason={hooks['reason']}"
         if hooks.get("relocated"):
             extra += f", relocated={', '.join(hooks['relocated'])}"
+        if hooks.get("chain_slots"):
+            # Said in either install order: with graphite first nothing is in
+            # these slots yet, and this is where another tool's hook goes.
+            files = ", ".join(slot["file"] for slot in hooks["chain_slots"].values())
+            extra += f"; another tool's hook for the same event belongs in {files} there, run first"
         print(f"  - hooks: {hooks.get('action')} ({hooks.get('path')}{extra})")
         allowlist = result["allowlist"]
         if allowlist.get("changed"):

{graphite_code-1.3.0 → graphite_code-1.4.0}/src/graphite/doctor.py

@@ -20,7 +20,7 @@ from .daemon import read_daemon_status
 from .daemon_health import HealthOptions, evaluate_daemon_health
 from .freshness import FreshnessLimitError, check_graph_freshness
 from .git import GitError, GitRunner
-from .hookinstall import DEFAULT_HOOKS_DIRNAME, hook_shim_present, hooks_dir
+from .hookinstall import DEFAULT_HOOKS_DIRNAME, chain_slots, hook_shim_present, hooks_dir
 from .init import gitignored_managed_paths, managed_doc_paths
 from .hookshim import TRIGGERS
 from .llm import canonical_provider_name
@@ -179,7 +179,7 @@ def check_hooks(root: Path) -> DoctorCheck:
     installed = all(hook_shim_present(hdir / hook) for hook in TRIGGERS)
     configured = _hooks_path_configured(root)
     custom_hooks_dir = hdir != root / DEFAULT_HOOKS_DIRNAME
-    details = {"onboarded": True, "custom_hooks_dir": custom_hooks_dir, "hookspath_configured": configured, "trampolines_installed": installed}
+    details = {"onboarded": True, "custom_hooks_dir": custom_hooks_dir, "hookspath_configured": configured, "trampolines_installed": installed, "chain_slots": chain_slots(hdir)}
 
     if configured and installed:
         return DoctorCheck("hooks", "Hooks", "ready", "Git hooks are installed and enforced.", details)