graphite-code 1.1.0__tar.gz → 1.2.0__tar.gz

{graphite_code-1.1.0 → graphite_code-1.2.0}/CHANGELOG.md

@@ -15,6 +15,438 @@ machine-checkable identity; the version is for humans.
 
 ## [Unreleased]
 
+## [1.2.0] — 2026-10-10
+
+A minor release. Query and search results, channel rounds and Python
+definition nodes gain fields, which are additions under
+`docs/compatibility.md`. No field is removed or renamed, and nothing under
+`docs/reference/` changes. Python node ids change, which that document allows
+when the CHANGELOG says so: **do not persist node ids across this upgrade.**
+
+The graph changes in this release. On this repository, measured against the
+deployed 1.1.1 engine:
+
+- 4,776 of 5,716 definition ids keep both their id and their definition. 937
+  are gone and 1,322 are new. No id names a different definition. 3 survive
+  as strings and now name the placeholder for a call made through a local
+  name (`poll = getattr(process, "poll", None)`, then `poll()`), which 1.1.1
+  bound to the method of that name;
+- all 408 file ids survive, and 2,046 of 2,049 placeholder ids;
+- nodes go from 8,173 to 8,555 and edges from 23,073 to 23,363. `calls` goes
+  from 14,758 to 14,994 and `contains` from 6,042 to 6,096; `imports` (2,310)
+  and `inherits` (118) are unchanged. 18,983 of 23,228 edge triples are
+  unchanged;
+- `analysis.cycles` goes from 20 to 19, and the community count from 170 to
+  171;
+- the Python `calls` ratio goes from 0.978 to 0.975.
+
+Two builds of this tree are byte-identical (`graph.json`, `GRAPH_REPORT.md`,
+`graph.html`). The parser version plays no part in these figures: each engine
+gives the same graph under tree-sitter 0.25.2 and 0.26.0.
+
+The entries below quote figures measured when each change was made, on earlier
+commits of this tree, so they differ slightly from the ones above.
+
+`graphite init` now writes `DOC_VERSION` 15. Re-run it in each repository to
+refresh the managed files.
+
+### Changed
+
+**Consumers use graphite only as a tool, and the agent channel carries only bug
+reports and recommended improvements.** A consumer has the tool, never the
+agent behind it, so anything that needs an agent to answer cannot exist in a
+real installation. The files `graphite init` writes (`DOC_VERSION` 14 -> 15:
+`GRAPHITE.md`, the `CLAUDE.md` / `AGENTS.md` pointer, the Cursor rule) now
+say so, and stop telling agents to ask other agents. Version 14 told them "If
+you need a fact from another repo, ask for it" and to "ask the owning agent to
+look". Facts about a tool come from the tool: its CLI, its MCP tools and its
+documentation. The `graphite_channel_post` description states the same rule
+when an agent posts. `graphite channel --help` states it for an agent that
+has the CLI but not the MCP tools. Re-run `graphite init` to pick it up; the
+sentence "The channel carries only bug reports and recommended improvements."
+marks a refreshed file.
+
+### Added
+
+**Channel rounds carry a `kind`: `bug_report` or `improvement`.**
+`graphite_channel_post` takes it, and the round records it. These surfaces
+show it:
+- `graphite_channel_list` and `graphite_channel_read`;
+- `graphite channel list` and `graphite channel report`, as text and as
+  `--json`;
+- `graphite channel show`.
+
+The text views tag a classified round as `[bug_report]` or `[improvement]`
+before its title. JSON carries `null` for a round posted without one, which is
+every round before this release. Any other value is refused with
+`invalid_kind` before a round number is spent.
+
+**Two Python call-binding blind spots are now declared on every Python
+`callers` / `calls` answer**, the day they were confirmed (#70, #71):
+
+- `python-nested-name-shared-id`: nested functions and methods share one node
+  per file and short name, so a call to or from one may be attributed to
+  another definition of the same name;
+- `python-bare-call-ignores-scope`: a bare call through a parameter or other
+  local binding, or inside a method body, may be bound to a same-named module
+  function or sibling method.
+
+Both produce wrong callers at `decision_grade`. Measured on graphite's own
+code with the real extractor against CPython `symtable`: 118 of 12,082
+bare-name calls bound to the wrong definition, and 1,345 call sites credited
+to the wrong caller; on Django 5.2.7, 76 and 6,614. They are scope disclosures,
+present on empty and non-empty answers alike, because the wrong binding is
+made during extraction and no single answer can tell whether it is affected.
+Both are retired in this same release by the fix under "Fixed".
+
+**A new Python `calls` caveat, `python-member-call-over-dispatch-cap`, declared
+the day it was measured (#73).** A member call (`obj.m()`, `self.m()`,
+`super().m()`) whose method name has more than three definitions in the
+caller's file and the files it imports gets no edge. So a `callers` or
+`impact` result on a method may be missing real callers. It is a scope
+disclosure, present on every Python `calls` answer; the measurement is under
+"Fixed".
+
+**Query by qualified name.** A dotted Python qualified name (`Worker.run`,
+`test_one.fake_build`) now selects that definition in `query`, `context` and
+`impact`, as match type `qualname`, tried after `exact-id` and before `name`.
+Among same-named definitions at equal path depth, a bare name picks the
+module-level one, then a method, then a nested definition. Two published
+schemas gain an optional field, an additive change:
+- `search-result` rows carry `qualname` when it differs from `name`;
+- `query-result` `resolution[]` items carry `alternates_total`, the number of
+  alternates. `alternates` still lists at most three (four for `path-suffix`).
+
+### Deprecated
+
+**Posting a channel round without `kind`.** It still lands, with a
+`kind_missing` warning in the result naming the replacement, and becomes an
+error in the next major release (`docs/compatibility.md`: the channel
+protocol is a stable surface).
+
+### Fixed
+
+**Python methods and nested definitions get their own node, and bare-name
+calls bind the way Python resolves them (#70, #71).**
+
+- Every `def` and `class` that is not at module scope now has a scope-qualified
+  id, built from its qualified name (`Worker.run`, `test_one.fake_build`), so
+  same-named methods and nested helpers stop sharing one node.
+- Module-scope ids are unchanged.
+- Every Python definition node carries `qualname`.
+- A bare call now resolves in the scope it is made in: parameters,
+  assignments, loop and `with` targets, `except` and `match` captures,
+  comprehension targets, function-local imports, `global` and `nonlocal`.
+  Enclosing class scopes are skipped from inside a method.
+- A call through a local name is kept as an unbound edge rather than bound to
+  a same-named definition.
+- A call on a module name bound by two different imports is kept as an unbound
+  edge rather than guessed by method name. Examples: `import pkg` beside
+  `import pkg.sub`, or an in-repo module with an external fallback. 1.1.1 bound
+  the first shape through its file-wide alias map; neither corpus has one.
+- A file's Python node ids are distinct by construction. A module-level def
+  spelled like a scoped id (`def worker_run_7c6b1a()`) no longer merges into
+  `Worker.run`; the scoped id is re-salted instead. Real names never collide.
+
+Measured with `scripts/pyscopeoracle.py` against CPython's `symtable`:
+- wrong-target bare-name calls went from 118 to 0 on graphite and from 77 to 0 on
+  Django 5.2.7;
+- 1,075 call sites on graphite (4,411 on Django) were credited to a different caller
+  before this change.
+
+The oracle grades bare-name calls only; member calls (`obj.m()`) are not
+graded. Its figures differ slightly from the census quoted under "Added":
+- Django's 77 is the census's 76, plus two generator-target sites the census
+  missed, minus one site the oracle reports as rebound and does not score;
+- 1,075 (4,411) counts only call sites that produce an edge, while 1,345
+  (6,614) also counts calls that produce none, such as `len()`.
+
+Python node ids changed:
+- 4,505 of 5,420 definition ids survive with the same meaning on graphite;
+- 8,959 of 34,609 survive on Django (the whole sdist, tests included);
+- id strings that now name a different definition: 0 on graphite and 6 on
+  Django. Each of the 6 is a module-level function whose id a same-named method
+  had taken.
+
+Do not persist node ids across this upgrade. graphite's own node-id holders
+were audited: the incident ledger, daemon manifest, `check` records, rollback
+store, usage ledger, overlays and extraction cache. None reads a node id back
+across an engine change.
+
+The Python `calls` ratio moved from 0.977 to 0.975 on graphite (0.704 to 0.700
+on Django). The change was not broken down by cause. The candidates are:
+- local-value calls kept as unbound edges;
+- split nodes no longer sharing deduplicated edges;
+- over-cap member edges leaving the denominator.
+
+The retired caveats `python-nested-name-shared-id` and
+`python-bare-call-ignores-scope` stay in the registry, marked retired.
+
+Member calls on a commonly reused method name now lose their edge more often,
+though method dispatch itself is unchanged. A member call with more than
+three candidate methods gets no edge, counting candidates in the caller's own
+file and the files it imports. Same-named methods in one file used to be one
+candidate; now each is its own. On Django 5.2.7:
+- over-limit member-call sites rose from 2,889 to 3,817;
+- dropped member-call sites rose from 7,149 to 8,518.
+
+Many of the lost edges were wrong, such as `super().__init__()` bound to the
+class's own `__init__`. Some were right but imprecise.
+
+`graphite impact <file>` is unchanged for every file on graphite and on
+Django, both impacted files and likely tests, measured over the whole
+population. `impact` and `callers` on a method can lose callers: 8 of 1,803
+definitions on graphite and 236 of 8,439 on Django lost at least one likely
+test. This is disclosed as the caveat `python-member-call-over-dispatch-cap`.
+Class-aware `self.`/`super()` dispatch is #73.
+
+**`graphite init` no longer moves its hooks to the end of
+`.claude/settings.json` when they are already current.** It used to strip and
+re-append them on every run, so in a repo where another tool's hook came after
+graphite's, each `init` re-run reordered the file. That showed up as a change
+to a committed file although nothing had changed: Claude Code runs matching
+hooks in parallel, so their order has no effect. A current entry now stays
+where it is. A stale, duplicated or legacy graphite entry is still replaced,
+and a missing one is still appended.
+
+**A name typed in its exact case now picks the definition spelled that way.**
+`graphite query "callers Verdict"` could answer about a function named
+`verdict`, and grade that answer like any other. The whole query string was
+lowercased before the matcher ranked same-named definitions, so the tie
+between `Verdict` and `verdict` fell to id order. Now only the verb is folded.
+Where two matches rank equally by path depth and scope, the one spelled as
+typed comes first. The same holds for a dotted qualname (`Worker.run`), and
+for `context` and `impact`. Matching still ignores case: `callers verdict`
+still finds a class `Verdict` when nothing is spelled `verdict`.
+
+A query plan (`query --plan-only`) and each `resolution[].input` now carry a
+target as it was typed. They used to carry it lowercased.
+
+Path depth still outranks case: a shallower `verdict` is still chosen over a
+deeper `Verdict`. The next entry is what such an answer now says about itself.
+
+**An answer about a different spelling than the one typed is no longer graded
+`decision_grade` (#77, channel round 317).** When a name matched definitions in more
+than one spelling and the node chosen is not spelled as typed, the answer may
+be about another symbol. `callers Verdict` could list the callers of a function
+`verdict` at `decision_grade`, with the class named only in `alternates`. Now:
+
+- the `resolution[]` entry carries `case_ambiguous: true`, and so does the
+  `matched` entry in `context`. It is an optional field of the `query-result`
+  schema, an additive change;
+- the answer grades `advisory` at most, in `query`, `context` and `impact`;
+- the answer carries a new caveat, `target-resolved-to-another-spelling`. It is
+  conditional: present only where that pick was made, and listed first;
+- `impact` and `context` print their `answer health:` and `known limits:`
+  lines for such an answer even when it is not empty;
+- an empty listing reads "none found — UNVERIFIED: the name matched more than
+  one spelling ...".
+
+A name with one spelling is not affected, however it is typed and however many
+definitions share it. Those are listed in `alternates` as before. Ask again by
+node id for an answer about exactly one node.
+
+`query --natural` now keeps the case of the question. It used to lowercase it,
+so "Who calls Verdict?" reached the matcher as `verdict`. The grammar itself
+still ignores case. A suggested `impact` or `context` command now names the
+path as typed. Search-fallback terms are still lowercased.
+
+Ranking exact case before path depth was measured and not taken. Over every
+name with more than one spelling:
+
+| | graphite | Django 5.2.7 |
+|---|---|---|
+| names with more than one spelling | 5 of 5,264 | 163 of 28,868 |
+| queries, each spelling typed exactly | 10 | 330 |
+| answered about another spelling | 2 | 128 |
+| the same, with exact case ranked first | 0 | 0 |
+| the same names typed in lowercase | 5 | 163 |
+| of those, resolving to a different node with exact case ranked first | 1 | 78 |
+
+Lowercase is how a name is usually typed, and those queries rely on a bare name
+meaning the shallowest definition. On Django, 20 of the 78 would move from one
+test definition to another. The grade change moves no query to another node. It
+applies to the 2 and the 128 exact-case queries above, and to 1 of the 5 and 88
+of the 163 lowercase ones.
+
+Not changed: a `reaches` or `path` result of "no path" is an error with no
+`answer` block, so it has no grade to lower. Its message names the node ids it
+used. That such a result is never graded, on a degraded graph included, is #76.
+Two published sentences said otherwise and are corrected: the integration guide
+called a `no_path` with `truncated: false` proof of absence, and the
+`query-result` schema described the `answer` block as present on `no_path`.
+
+**The strict graph-first hook no longer refuses searches for directory names,
+filenames and plain words (#72).** It refused a cross-file search whenever one
+fragment of the pattern matched a node in the graph. `graph-out`,
+`graph\.json` and the word `round` under `docs/` were all turned away, against
+the hook's own "literal text and filename searches are fine". Four things
+changed:
+
+- **A placeholder is not a symbol.** `json` is in the graph because a file
+  imports it, not because the repo defines it. About a quarter of the nodes in
+  graphite's own graph are placeholders.
+- **A directory with no code is searched as text.** When no source file the
+  graph models (Python, TypeScript, JavaScript, Go, Rust) lies under any
+  directory the search names, the search is allowed. Every named path must
+  exist: a glob or a shell variable reaches the hook unexpanded, so it gets no
+  exemption. A directory the repository lies under, such as `..`, holds all of
+  its code.
+- **The symbol check ignores case only when the search does.** `DONE` in a log
+  line is not the function `done`. The Grep tool without `-i` is compared
+  case-exactly. So are `grep`, `git grep` and `rg`, unless they carry `-i`,
+  `-y`, `--ignore-case`, `-S` or `--smart-case`. An inline `(?i)` in the
+  pattern folds on every route. Every other tool (`Select-String`, `ag`,
+  `ack`, `findstr`) is still treated as ignoring case. So is `grep` while
+  `GREP_OPTIONS` is set, and `rg` while `RIPGREP_CONFIG_PATH` is set: either
+  can turn folding on without showing in the command. The Grep tool is built
+  on ripgrep and is treated the same way while `RIPGREP_CONFIG_PATH` is set.
+  Whether it reads that file was not measured, so the hook does not assume it
+  matches case exactly.
+- **A piece of a longer literal is not judged alone.** A name joined to its
+  neighbour by a hyphen (`graph-out`, `--no-verify`) or a slash (`src/pkg`), or
+  followed by a file extension (`graph\.json`, `query.py`), is skipped.
+  `name-?`, `name->` and member access such as `self\.run` are still judged.
+
+Still refused: the name of a real definition, searched across a directory that
+holds code. `dependents` over `src/` is the control.
+
+**The strict hook resolves a search's paths where the shell will.**
+`cd <scratch> && grep check ci.log` reads one file outside the repository. The
+hook resolved `ci.log` against the repository root, found no such file, and
+refused the search for a symbol named `check`. A `cd` or `pushd` is now
+followed when the directory exists and it is joined to the search by `&&`,
+with nothing between them but another `cd` or another search. A search that
+then names no path searches that directory. After `;`, `||`, `&` or a pipe the
+search can run without the `cd` having worked, so paths resolve against the
+repository root as before. The same goes for a directory spelled with syntax
+only the shell can expand (`$VAR`, `~`, `-` or a glob), for any other command
+in between (`cd docs && ls && grep ...`: the hook cannot tell `ls` from a
+function that changes directory), and while `CDPATH` is set.
+
+Four kinds of search are now refused that used to pass:
+
+- `cd docs && grep -rn <symbol> ..`, where `..` is the repository root. The
+  path was resolved against the root itself and read as leading outside.
+- On Windows, a Git Bash drive path into the repository, such as
+  `grep -rn <symbol> /f/Projects/repo/src`. Read by Python it was a path on
+  the current drive. The Bash tool's `/c/...` paths are now read as the drive.
+- A search rooted at a directory the repository lies under, such as
+  `grep -rn <symbol> ..`. It was read as a search outside the repository,
+  although it covers all of it.
+- A search behind another search. Only the first search of a command line was
+  judged, so `grep x notes.md ; grep -rn <symbol> src/` passed. Every search in
+  the command is judged now, and one refusal refuses the command.
+
+## [1.1.1] — 2026-10-03
+
+A patch release. Security fixes ship in the next patch release of the current
+minor (`docs/compatibility.md`, `SECURITY.md`). The graph itself does not
+change: on this repository, measured against the deployed 1.1.0 engine,
+7797 of 7797 node ids survive, 22154 of 22154 edge triples are
+unchanged, every relation count is equal, and `analysis.cycles` is identical.
+Only the engine fingerprint moves, because graphite's own bytes did.
+
+### Security
+
+**graphite no longer launches a program by bare name, so a program sitting in
+a repository root cannot run in place of the real one.** On Windows a bare
+name is looked up in the launching process's current directory before PATH.
+That covers a list-form `subprocess.run(["git", ...])`, cmd.exe and
+`shutil.which`, unless `NoDefaultCurrentDirectoryInExePath` is set. Claude
+Code sets that variable, but the daemon at login and a commit from a terminal
+do not.
+
+graphite's builds, hooks and channel broker run with a repository root as
+their current directory. A `node.exe` committed to a TypeScript repo's root
+ran on every build, and the build still exited 0. This was measured against
+the released 1.1.0 wheel; channel round 304 reported it.
+
+Every launch now goes through `graphite.programs.resolve_program`, which:
+
+- reads only absolute PATH entries;
+- skips a PATH directory inside the target repository, or one that IS the
+  current directory, judged both as written and as resolved, so a committed
+  symlink cannot choose which outside binary runs (aramid llm-review
+  `1d8d8cf`);
+- refuses any candidate that resolves into one of those;
+- on Windows, tries `.exe` as CreateProcess does, unless the caller asks for
+  more.
+
+Windows' own tools come from the system directory the OS reports. The
+sites changed are:
+
+- the TypeScript bridge's `node` (every build);
+- the channel broker's `git`;
+- the channel's commit-msg hook, which fails closed when no git is found;
+- the `git` calls in `init` and `hookinstall`;
+- `daemon-health`'s `powershell.exe`;
+- the four `schtasks.exe` calls;
+- the Startup launcher's `powershell.exe`;
+- routing's `claude`/`codex` lookup, which keeps `.cmd` shims, excludes the
+  repository and the task worktree whatever the current directory (aramid
+  llm-review `30e2473`), and sets the CLI's environment (see below);
+- `doctor`'s `graphite-mcp` check;
+- the mutation-test launcher's `git`.
+
+Resolving the first program is not enough when that program is a `.cmd` shim.
+An npm-installed CLI with no `node.exe` beside it runs bare `node` through
+cmd.exe, which searches the task worktree first. A `node.exe` committed to the
+repo would then run before the CLI's own sandbox. Routing now sets
+`NoDefaultCurrentDirectoryInExePath=1` in every CLI's environment, which turns
+that search off for the whole chain. The commit-msg hook also has its own status
+when it cannot find git. It used to fall through to "this commit names no agent".
+
+Two older private copies of the same PATH walk, in `git` and `doctor`, now
+delegate to the shared resolver. A test walks every launch call in `src/`,
+`scripts/` and the hook's embedded program, and fails on a program named by a
+literal or on `shell=True`.
+
+The current directory is refused itself, not its subtree, because that is
+what Windows searches. Refusing everything beneath it would refuse every tool
+on drive C for a run started from `C:\`, and `~/.local/bin` or an
+nvm-installed `node` for a run started from `$HOME`. A pre-release build
+measured exactly that. The repository's own subtree is refused through the
+repository each caller passes.
+
+Artifacts already installed keep the old command until they are regenerated:
+- the Startup `.vbs` (`graphite daemon-install-startup-windows`);
+- the channel's commit-msg hook (rewritten by `graphite channel register`).
+
+### Fixed
+
+**`doctor --deep`'s LLM probe no longer spends the provider's timeout on
+starting its worker.** One number was both the provider timeout and the worker
+process's whole budget. The interpreter's start was therefore paid from the
+provider's time, and a loaded machine reported `timeout` for a provider that
+was only misconfigured: 2 s read `timeout` 7 times in 10 under 36 CPU burners.
+
+The worker already enforces the provider timeout itself. Its process budget is
+now that timeout plus `_LLM_WORKER_START_ALLOWANCE_SECONDS` (30 s), which only
+bounds a worker that never answers. A 0.1 s provider timeout, below any
+interpreter's start, now reaches `configuration`.
+
+**The channel reports an abandoned lock on every path that can break one.**
+These come from aramid llm-review findings:
+- **`1810f9e`:** `inbox()`, the path every agent takes at session start, was
+  the one writer that dropped the recovery. `graphite_channel_inbox` now
+  carries `lock_recovered` when a delivery had to break a lock, and stays
+  silent otherwise.
+- **`9751aab`:** a residue scan that failed read as `[]`, the same as a clean
+  one. It now reads `null`, meaning "we could not look". A wedged git, the
+  likeliest cause of an abandoned lock, is also what makes the scan fail.
+- **`9a23b84`:** the recovery report no longer returns the dead holder's host
+  name. Nothing decides on it: identity is pid + start time, and staleness is
+  the clock.
+
+**The channel's commit-msg hook is installed with exactly `0o755`, pinned on
+every platform.** aramid's mutation drain found `0o755 -> 0o756`, a
+world-writable audit hook on POSIX, surviving (`e37afd86`). On Windows,
+`os.chmod` honours only the write bit, so no on-disk check there could see it.
+A test now pins the argument, which kills the mutant on Windows too. A
+POSIX-only test checks the on-disk property: executable, and not group- or
+world-writable.
+
 ## [1.1.0] — 2026-09-27
 
 A minor release. The agent channel's read surfaces gain fields, which is an

{graphite_code-1.1.0 → graphite_code-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphite-code
-Version: 1.1.0
+Version: 1.2.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.1.0, production/stable.** Published on PyPI as
+**Status: 1.2.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.1.0 → graphite_code-1.2.0}/README.md

@@ -2,7 +2,7 @@
 
 Local-first, deterministic knowledge graph extraction for codebases — zero-LLM, daemon-maintained, agent-agnostic.
 
-**Status: 1.1.0, production/stable.** Published on PyPI as
+**Status: 1.2.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.1.0 → graphite_code-1.2.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.1.0"
+__version__ = "1.2.0"