graphite-code 1.1.1__tar.gz → 1.2.1__tar.gz

{graphite_code-1.1.1 → graphite_code-1.2.1}/CHANGELOG.md

@@ -15,6 +15,398 @@ machine-checkable identity; the version is for humans.
 
 ## [Unreleased]
 
+## [1.2.1] — 2026-10-11
+
+A patch release. It carries one fix, to the agent hooks (#80). No stable
+surface in `docs/compatibility.md` changes: nothing under `docs/reference/` or
+`docs/schemas/` moves, `graphite agent-hook` still always exits 0, and the
+wording of a hook's message is not a stable surface. The graph itself does not
+change: on this repository, measured against the deployed 1.2.0 engine,
+8581 of 8581 node ids survive, 23612 of 23612 edge triples are unchanged,
+every relation count is equal, and `analysis` is identical. Only the engine
+fingerprint moves, because graphite's own bytes did.
+
+### Fixed
+
+**The agent hooks find the repository from a subfolder (#80).** A hook payload
+carries the session's directory, and in Claude Code that follows a `cd` in the
+shell. All three hooks took it for the repository root. One directory below the
+root, with the graph fresh at the root:
+
+- `session-start` said `Graph status: missing`, the status that licenses a full
+  fallback from graph-first. The remedy it printed, `python -m graphite build .`,
+  is refused there ("nested Git roots are unsupported").
+- `pre-tool-use` wrote nothing: no refusal in strict mode and no reminder. A
+  `cd` into any subfolder switched the gate off.
+- `stop` created a `.graphite/local/` in the subfolder for its cursor and looked
+  for the turn's usage there.
+- The subfolder was registered as an open project. The daemon cannot build
+  one, so it logged `project_snapshot_failed` for it at every discovery cycle,
+  and the repository's own marker was no longer renewed.
+
+The repository is now the nearest directory upward that holds `.git`, the test
+the build already uses to refuse a nested path (`ingest.enclosing_git_root`).
+It is taken only where graphite is set up: a `graph-out/graph.json`, or the
+`GRAPHITE.md` that `init` commits. In a subfolder of any other checkout, and in
+a directory outside every checkout, the hooks read the session's directory as
+they did. A repository inside the repository, with its own `.git`, stays its
+own root.
+
+One reading changes inside a checkout that is set up. A folder there that has
+its own `GRAPHITE.md` or `graph-out/` but no `.git` was read as a project of
+its own: `Graph status: missing`, or `unknown` over a leftover graph, with a
+`build .` that is refused there. It is now read as part of the checkout.
+
+Below the root:
+
+- The graph, the freshness check, the usage ledger and the activation marker
+  are the repository's.
+- A search's relative paths, and a search that names no path, belong to the
+  directory the shell is in. `grep <symbol> core.py` beside the file is one
+  file. A search with no path in a `docs/` that holds no code is text. `..` and
+  `../src` are judged as the directories they are.
+- Once the command line has run a `cd` the hook does not follow, or any command
+  it does not model, the shell may be anywhere in the repository. A search then
+  keeps an absolute path, and a relative one that names a file in the session's
+  directory. With a directory, or no path, it is judged as a search of the
+  whole repository: from a `docs/` with no code, `cd ../src ; grep -rn <symbol> .`
+  is refused. At the root this case resolves paths against the root, as before.
+- Every status, refusal and reminder ends by naming the root: "This session is
+  below the repository root: run graphite from `<root>`." The CLI still looks
+  for the graph in its own working directory (#81), so the commands those
+  messages print work from the root only.
+
+The hooks no longer register a directory below a checkout's root with the
+daemon, whether or not graphite is set up in that checkout.
+
+Nothing changes for a session at the repository root. Measured on the 1.2.0
+wheel and on this change: 32 strict-hook arms from the #72 work (25 refused, 7
+allowed) and 12 hook arms on a checkout with `.git` and `GRAPHITE.md` read the
+same on both.
+
+## [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

{graphite_code-1.1.1 → graphite_code-1.2.1}/PKG-INFO

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

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