leyline-code 0.9.1__tar.gz → 0.10.0__tar.gz

{leyline_code-0.9.1 → leyline_code-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: leyline-code
-Version: 0.9.1
+Version: 0.10.0
 Summary: Map a codebase so a person can plan a change, have an agent write the code, and check that it was done as agreed.
 Project-URL: Homepage, https://github.com/Orbitope/leyline
 Project-URL: Issues, https://github.com/Orbitope/leyline/issues
@@ -212,7 +212,9 @@ claude mcp add -s user leyline -- leyline serve         # or: every project you
 
 and `leyline skills install` to give Claude Code the skills (see [Working through an agent](#working-through-an-agent)).
 
-Claude Code starts the server in the directory it was opened in, and the server reads the store there,
+Claude Code starts the server in the directory it was opened in, and the server reads the store there (an agent that
+works in another checkout of the same repository, a git worktree, passes that checkout's absolute path to `map`: it is mapped
+as itself, its store is the one inside it, and the server reads that store until it restarts),
 `.leyline/leyline.db`, or, from a folder inside the repository, the nearest such store above it. Nothing needs to be mapped first: the agent's first call is `map`. If `leyline` is
 installed in a virtual environment, give its full path (`-- /path/to/venv/bin/leyline serve`); for a
 store elsewhere, such as a workspace mapped from another directory, add `-e LEYLINE_DB=/full/path/leyline.db`
@@ -237,10 +239,16 @@ Every record belongs to one of three layers:
 - **inferred**: written by an LLM, with evidence and a confidence
 - **intent**: written by you, such as boundaries and rules
 
+Every function and type also carries one line saying what it is for: its author's comment or docstring, or the
+`responsibility` an agent wrote after reading it (see [understanding.md](docs/understanding.md#what-a-function-or-type-is-for)).
+
 This version builds the fact layer for C# and Python, proposes systems by clustering, labels design
 patterns by their shape, generates an orientation tour, assesses a described change before it is made,
 reviews it after, and checks architecture rules.
 
+Godot scenes and Unity prefabs are on the map too, linked to the scripts they run and the methods their signals and
+events name, so renaming a method shows the scene that wires it ([indexing.md](docs/indexing.md#game-engine-assets)).
+
 ## Use
 
 ```bash

{leyline_code-0.9.1 → leyline_code-0.10.0}/README.md

@@ -179,7 +179,9 @@ claude mcp add -s user leyline -- leyline serve         # or: every project you
 
 and `leyline skills install` to give Claude Code the skills (see [Working through an agent](#working-through-an-agent)).
 
-Claude Code starts the server in the directory it was opened in, and the server reads the store there,
+Claude Code starts the server in the directory it was opened in, and the server reads the store there (an agent that
+works in another checkout of the same repository, a git worktree, passes that checkout's absolute path to `map`: it is mapped
+as itself, its store is the one inside it, and the server reads that store until it restarts),
 `.leyline/leyline.db`, or, from a folder inside the repository, the nearest such store above it. Nothing needs to be mapped first: the agent's first call is `map`. If `leyline` is
 installed in a virtual environment, give its full path (`-- /path/to/venv/bin/leyline serve`); for a
 store elsewhere, such as a workspace mapped from another directory, add `-e LEYLINE_DB=/full/path/leyline.db`
@@ -204,10 +206,16 @@ Every record belongs to one of three layers:
 - **inferred**: written by an LLM, with evidence and a confidence
 - **intent**: written by you, such as boundaries and rules
 
+Every function and type also carries one line saying what it is for: its author's comment or docstring, or the
+`responsibility` an agent wrote after reading it (see [understanding.md](docs/understanding.md#what-a-function-or-type-is-for)).
+
 This version builds the fact layer for C# and Python, proposes systems by clustering, labels design
 patterns by their shape, generates an orientation tour, assesses a described change before it is made,
 reviews it after, and checks architecture rules.
 
+Godot scenes and Unity prefabs are on the map too, linked to the scripts they run and the methods their signals and
+events name, so renaming a method shows the scene that wires it ([indexing.md](docs/indexing.md#game-engine-assets)).
+
 ## Use
 
 ```bash

{leyline_code-0.9.1 → leyline_code-0.10.0}/docs/changes.md

@@ -61,7 +61,9 @@ After implementation and a re-index, `verify` (inside `check`) marks each task f
 from its test's recorded result, lists edits outside the spec, new links between modules and rules
 newly broken, and appends the result to `leyline.md`. It exits 0 only when the change was done as
 agreed. A new function that only code named in the spec calls is listed as a helper, not as an edit
-outside the spec.
+outside the spec. A new link between modules whose target the change names in backticks (in its proposal, design, tasks
+or specs, such as the standard library module a task says it will use) was planned: it is listed, and does not hold
+the verdict up. One it does not name does.
 
 Each task and scenario gets one verdict, shown in the tables, counted under them ("7 proven, 1 needs
 you, 1 inconclusive"), and given as `verdict` and `verdict_why` in the MCP `check` answer:
@@ -333,6 +335,39 @@ checks a diagram of the code as it is). A baseline taken by an older Leyline kep
 what order: it still compares, and the code as it was is listed, not drawn. Keeping the order made a baseline of
 Parlance about 22% larger (8.2 MB to 10.0 MB).
 
+### Covered, but not asserted: a mutation plan
+
+A test can run every changed line and assert nothing about them; coverage cannot see it. A mutation can: break a changed
+line on purpose and see whether the scenario's own tests fail.
+
+```
+leyline mutants <change>                         # after the change is written: the plan, under .leyline/mutants/<change>/
+python .leyline/mutants/<change>/run.py          # runs the project's tests with each mutant applied; may be stopped and resumed
+<run the tests> | leyline check <change> --tests - --mutants .leyline/mutants/<change>/results.jsonl
+```
+
+The plan is for a spec change only. It holds at most 30 small breaks (a comparison flipped, `and` turned into `or`, a
+`not` dropped, a returned value replaced with None, an integer one more, `+` turned into `-`), at most 3 to a line, one to
+each edited function first so no function is left out while another has three. They are made only on the lines whose text
+is new in the functions the change edited, in Python product code: a function that only moved has none, tests have none,
+and other languages are named in the plan as having no operators yet. Each is a patch (in the file's own line endings,
+for `git apply` from the repository's top), with the tests that reach its function in two stages: the tests of the
+scenarios first, then up to 40 others.
+
+Leyline writes the plan and reads the results; it never runs the code. `run.py` (standard library only) is what runs
+it: the tests unmutated first (what fails there is never counted), then for each mutant its patch, the scenarios' own
+tests in full and, if none failed, the others until one does, under a timeout of twice the unmutated run (at least 30
+seconds; `LEYLINE_MUTANT_TIMEOUT` sets it). It always puts the file back, also after an error, a timeout or Ctrl-C, and a
+run that was killed puts it back the next time. One line per mutant goes to `results.jsonl`: `killed`, `survived`,
+`timeout` or `error`, and which tests failed.
+
+`check --mutants` refuses results made for another plan or for code that has changed since (which also catches a patch left
+applied). Then, for each passing scenario, it looks at the changed functions its tests reach: if every mutant of them ran
+and none failed the scenario's own tests (another test failing it does not count), the scenario is `unasserted`, which
+does not block unless the project lists it under `[check] blocking`. A mutant that was not run leaves the scenario unjudged. A
+person may append `{"plan": "<id>", "id": "m-3", "status": "equivalent", "why": "..."}` for a mutant that cannot change
+behavior, and it counts for nothing. The page lists the survivors under "Covered, but not asserted".
+
 ### Reviewing a change after it is made
 
 The first `propose_change` of a change keeps a baseline in `.leyline/snapshots/<change id>.db` (what the

{leyline_code-0.9.1 → leyline_code-0.10.0}/docs/indexing.md

@@ -13,7 +13,8 @@ instead, leaving out what git would: the patterns of your global excludes file (
 git reads them, so a file kept out of git such as `.env` stays off the map and its page. Some files are left out, and `map` names them with
 the reason: other people's code (`node_modules`, a Go or Composer `vendor`), submodules and nested
 repositories, symlinks to directories or out of the repository, files git lists that are gone, and source
-files that are binary, minified, unreadable or larger than 5 MB (`LEYLINE_MAX_FILE_MB` changes that). A
+files that are binary, minified, unreadable or larger than 5 MB (`LEYLINE_MAX_FILE_MB` changes that; engine assets
+have their own limit, below). A
 file that does not parse is kept on the map as a file, without its contents, and named too.
 
 Large repositories are parsed in worker processes (`LEYLINE_JOBS` sets how many). A worker that crashes
@@ -40,6 +41,29 @@ overloads, field reads and writes, events, routes. They are used for those langu
 `LEYLINE_GENERIC=1`. For other languages, a **SCIP index** (from the language's own indexer,
 `--scip FILE`) replaces the generic adapter's guesses with the compiler's links.
 
+#### Game engine assets
+
+Godot scenes and resources (`.tscn`, `.tres`) and Unity scenes, prefabs and assets (`.unity`, `.prefab`, `.asset`, in
+text serialization) are files on the map too, read whatever `LEYLINE_GENERIC` says. They hold no functions; what they
+name is what the map keeps. A scene or prefab links to the script a node or component runs, to the scene or prefab
+it includes (`imports`, exact), and to the methods its signal connections (Godot) or persistent events (Unity) call
+by name (`communicates` on the channel `asset`, heuristic: found by name, one edge to a method however many
+connections name it). A method counts as the script's when its class or a base class on the map has it.
+
+- A Godot script is found by its `res://` path, read from the folder of the `project.godot` above the scene, not from
+  the repository. Reading a `.gd` script's methods needs the GDScript grammar (`pip install 'leyline-code[languages]'`).
+- A Unity script, scene or prefab is found by its GUID, from the `.meta` file beside it, read only when the repository
+  holds a Unity asset. A `.meta` that is added, changed or gone counts as a change to `plan`, `check` and `map`.
+- `impact` of a script's class, method or field reaches the assets that run it, and `impact` of a scene or prefab
+  the assets that include it. An asset sits in the module of the nearest folder above it that holds code; a folder of
+  scenes alone is not a module.
+- What cannot be tied to code is not guessed. The extractor's coverage (`overview`) counts it by reason and names
+  the first few: a script or prefab outside the repository, a GUID two `.meta` files claim, a method the script does
+  not have, a script in a language that is not read, and calls on built-in components (counted apart, not missing).
+- An asset is read in a stream, never held as lines, up to 64 MB (`LEYLINE_MAX_ASSET_MB`; code keeps 5), binary ones
+  are left out and named, an unchanged one is not read again, and the map's page holds their names and links but not
+  their text.
+
 `leyline grade <repo> <index.scip | roslyn>` measures either adapter against a compiler. Precision
 counts only call sites the compiler resolved; recall counts the compiler's links between functions
 on the map.

{leyline_code-0.9.1 → leyline_code-0.10.0}/docs/mcp-tools.md

@@ -6,26 +6,27 @@ Part of Leyline's documentation: the [README](../README.md) is the start, and [q
 
 | Tool | Returns |
 | --- | --- |
-| `map(paths?)` | Step 1: index the code (or map again what the store holds); counts, the map page, `next` |
+| `map(paths?)` | Step 1: index the code (or map again what the store holds); counts, the map page, `next`. One checkout that is not the server's own (a git worktree) gets the store inside it, which the server reads from then on until it restarts (`store_note`) |
 | `plan(change, test_output?, test_results?, new_baseline?)` | Step 2: the one page for a change, `status.blocking`, `next`; records the tests from before; `new_baseline` compares from the code as it is now |
-| `check(change, test_output?, test_results?, coverage_path?)` | Step 3: re-index, record the tests from after, the verdict and `next`; with the run's coverage, whether each scenario's test ran the changed code |
+| `check(change, test_output?, test_results?, coverage_path?, mutants_path?)` | Step 3: re-index, record the tests from after, the verdict and `next`; with the run's coverage, whether each scenario's test ran the changed code; with the results of the change's mutation plan, whether its own tests failed a mutant of it |
+| `mutants(change, max_mutants?)` | A plan of small breaks of the code a spec change edited, written under `.leyline/mutants/<change>/` (a patch for each, `plan.json`, and `run.py`, which someone runs; Leyline never does): the mutants, the tests that reach each, and how to run it. Spec changes only |
 | `affected_tests(change)` | The tests to run for a change or a `pr-<id>` review, and the command that runs them |
-| `overview(scope?, limit?)` | Repos, modules with sizes, module-to-module dependencies by edge kind, systems, external packages, extractors that ran |
+| `overview(scope?, limit?, budget_tokens?)` | Repos, modules with sizes, module-to-module dependencies by edge kind, systems, external packages, extractors that ran |
 | `cross_repo(limit?)` | In a workspace of several repositories: links between them, functions most called across, flows that cross and come back |
 | `search(text, kind?, limit?)` | Node ids matching a name, qualified name or path |
-| `expand(node_id, limit?)` | One node in detail: contents, dependencies, dependents, callers and callees |
-| `neighbors(node_id, direction?, kinds?, limit?)` | Raw edges around a node, by kind |
+| `expand(node_id, limit?, budget_tokens?)` | One node in detail: contents, dependencies, dependents, callers and callees |
+| `neighbors(node_id, direction?, kinds?, limit?, budget_tokens?)` | Raw edges around a node, by kind |
 | `source(node_id, max_lines?)` | The node's source text |
-| `context(focus, budget_tokens?)` | A short outline of the code around a focus (ids, names, paths, a change, or words), most related first, cut to a token budget |
-| `module_outline(module?, depth?)` | A large module split into at most 12 parts (folders, or groups of files where a folder is flat): each part's size, entry points, links in and out, channels, busiest functions, risks and name; drill in with a part's id |
+| `context(focus, budget_tokens?, bodies?)` | A short outline of the code around a focus (ids, names, paths, a change, or words), most related first, cut to a token budget; with `bodies`, the code too: the focus's body, the types it takes, and the lines around each call to it |
+| `module_outline(module?, depth?, budget_tokens?)` | A large module split into at most 12 parts (folders, or groups of files where a folder is flat): each part's size, entry points, links in and out, channels, busiest functions, risks and name; drill in with a part's id |
 | `name_part(part_id, name, summary?, evidence?, layer?)` | Name a part from the outline with a one-line summary; kept across maps, shown as "may be stale" when the part changes a lot |
 | `flows(kind?, through?, limit?, offset?)` | Flows walked from each entry point and test; `through` keeps flows that pass a node |
 | `flow(flow_id, max_steps?, offset?)` | One flow step by step, in source order, with call depth |
 | `trace(from_id, to_id)` | The shortest chain of calls and channels between two functions |
-| `find_flows(description, limit?)` | Where a behavior described in words could start: entry points, route, UI and message handlers, tests named for it, functions; each with why it matched, its kind, file:line and the flows that start there, or else the entry points' flows (`reached_from`) and the tests' (`tests_reaching`) that reach it |
-| `explain_path(start, to?, through?, max_steps?)` | An ordered walk across calls and channels from `start` (its main flow, the shortest path `to` a node, or the path `through` one), each step with how it was reached, the calling line and the declaration; data written for later marked; a Mermaid diagram of the walk |
+| `find_flows(description, limit?, budget_tokens?)` | Where a behavior described in words could start: entry points, route, UI and message handlers, tests named for it, functions; each with why it matched, its kind, file:line and the flows that start there, or else the entry points' flows (`reached_from`) and the tests' (`tests_reaching`) that reach it |
+| `explain_path(start, to?, through?, max_steps?, budget_tokens?)` | An ordered walk across calls and channels from `start` (its main flow, the shortest path `to` a node, or the path `through` one), each step with how it was reached, the calling line and the declaration; data written for later marked; a Mermaid diagram of the walk |
 | `diagram(ids)` | A Mermaid sequence diagram of how execution reaches some functions or types and what they call |
-| `impact(node_id, max_depth?, limit?)` | What can reach a node: callers by module and the flows through it |
+| `impact(node_id, max_depth?, limit?, budget_tokens?)` | What can reach a node: callers by module and the flows through it |
 | `annotate(node_id, key, value, evidence?, confidence?, layer?)` | Write an inferred or intent statement about a node |
 | `propose_change(intent, targets, title?, depth?)` | Assess a change without an OpenSpec folder and save its blast-radius view |
 | `save_view(title, narrative, marks, legend?)` | Save any set of marked nodes as a view |
@@ -49,8 +50,19 @@ Part of Leyline's documentation: the [README](../README.md) is the start, and [q
 | `views()`, `view(view_id, limit?)` | List saved views, or read one |
 | `skills(skill?)` | The skills that ship with Leyline, each with when to use it, or one skill's text. Each is also an MCP prompt of the same name |
 
+`search` and `expand` rows, the steps of `explain_path`, the busiest functions, key types and key functions of
+`module_outline`, and the `--` lines of `context` carry `summary`: what the function or type is for, from a
+`responsibility` annotation (the intent layer first, stale ones passed over) or else the comment or docstring its
+author wrote (`doc`, kept when the file is mapped). See [What a function or type is for](understanding.md#what-a-function-or-type-is-for).
+
+`overview`, `expand`, `impact`, `module_outline`, `explain_path`, `find_flows` and `neighbors` also take
+`budget_tokens` (600 to 6,000; a token is four characters): the answer is cut to the smaller of that and the tool's
+usual size, `cut` says what was cut, and `more` names the budget. The budget is applied after the answer is worked
+out, so it saves the agent's context, not time; `explain_path` and `module_outline` also walk fewer steps or levels
+to fit it. `context` sizes its own outline with its `budget_tokens` and is not cut again; with `bodies` the outline takes a third of the budget, which is at least 600 tokens, and the code follows in the same text, with `bodies` describing each piece without repeating it.
+
 `change` is a change folder or its id. A tool that cannot answer returns an error saying what to do
 instead (no store yet: call `map`; an unknown id: find it with `search`). Each answer is at most about
-24,000 characters (30,000 for `module_outline` and `explain_path`, 36,000 for `context`): lists show their
+24,000 characters (30,000 for `module_outline` and `explain_path`, 44,000 for `context`): lists show their
 first items and their total, `cut` names any list that was shortened, and `more` says how to see the rest
 (`limit`, `offset`, `scope`, or a narrower id).

{leyline_code-0.9.1 → leyline_code-0.10.0}/docs/quick-reference.md

@@ -97,6 +97,7 @@ Only you resolve a finding. A rejection with a reason becomes a learning.
 | contradicted | the named code didn't change, but other code did | its test fails | yes |
 | inconclusive | the map can't place the code, or nothing changed | no result recorded | yes |
 | needs a person | it names no code | it passes, but doesn't reach the changed code | no |
+| unasserted | | it passes, but none of its own tests failed a mutant of the changed code it reaches (only with `--mutants`) | no |
 
 A tick in `tasks.md` never counts. Change which verdicts block in `openspec/leyline.toml`:
 
@@ -105,6 +106,9 @@ A tick in `tasks.md` never counts. Change which verdicts block in `openspec/leyl
 blocking = ["contradicted", "inconclusive", "partial", "needs a person"]
 ```
 
+`unasserted` is the one a project may add (`"unasserted"`) once it trusts its mutation results: a mutant that changes
+nothing (an equivalent one) looks the same as a test that asserts nothing, so it does not block by default.
+
 ## Writing a spec Leyline can read
 
 - Name code in backticks in `tasks.md`: `` `Engine.start` ``. A name that isn't on the map is new code.

{leyline_code-0.9.1 → leyline_code-0.10.0}/docs/understanding.md

@@ -4,6 +4,27 @@ What the map finds and how to ask it: exact references from a compiler, measured
 
 Part of Leyline's documentation: the [README](../README.md) is the start, and [quick-reference.md](quick-reference.md) is one page of what to ask.
 
+### What a function or type is for
+
+Every function and type carries one line saying what it is for, so an answer does not stop at who calls it. Two
+sources, the one written by a reader first:
+
+- **A `responsibility` annotation** (`annotate`, or `name_part` for a part's type), the intent layer before the
+  inferred one. One marked stale, because the code behind its evidence changed, is passed over.
+- **The author's own words**: the comment above a declaration, or a Python docstring inside it, read when the file is
+  mapped and kept in the node's attributes as `doc`. A comment edit re-reads its own file and nothing else.
+
+The summary is the first sentence of whichever applies, cut to 200 characters (120 under a step of a walk, a busiest
+function or a neighbour in a context outline). `search` and `expand` rows carry it as `summary` (and the `search` and
+`show` commands print it), `context` prints it as a `--` line under the focus and the code linked directly to it,
+`module_outline` carries it on busiest functions, key types and key functions, and each step of `explain_path` says
+what it does. `find_flows` ranks by it: the comment is one of the fields a word is looked for in, an annotation is read
+on each call (so one written after the map is found at once, under "its note"), and a function whose own words answer
+two or more words of the question counts for more than one that matches a single word of its name.
+
+An agent that has read some code should leave a sentence for the next one: `annotate(node, "responsibility", "...",
+evidence)` on the function, or `name_part` on a part.
+
 ### Exact references
 
 The syntax resolvers below work without a compiler and are sometimes wrong. Where a compiler's view
@@ -119,7 +140,11 @@ flow, a pattern, a saved view) with a few sentences on what to notice. `leyline
 orientation tour from the graph alone: what the repository is, where it starts, the modules from the
 most depended-on outward, the main abstractions and boundaries, one test path worth tracing, how it
 is tested, and what the map cannot see. Every sentence in it is a count or a name the store can
-back. An agent can write further tours with `save_tour`; `skills/leyline-tour/SKILL.md` says how.
+back. A module of 30 files or more (the size the map page splits) is described by its parts, as `leyline outline`
+splits it: the ones an agent named with `name_part`, with what each does, in the outline's order and marked when a name
+may be stale, and how many are still to name. A smaller module, and a module whose parts could not be worked out, is
+described by the groups the map proposed. `leyline map` says the same at the end of its `Next:` line when the largest
+product module has parts with no name, and the `map` tool lists the orientation steps in its `next`. An agent can write further tours with `save_tour`; `skills/leyline-tour/SKILL.md` says how.
 
 ### Change coupling
 
@@ -191,7 +216,16 @@ marked) or words to search for. Every function, type, field and test is ranked b
 over calls, channel links, type use and containment, each way, with a small boost for code a test reaches and code an
 entry point runs first. The outline shows declaration lines, not bodies, file by file, most related file first: the focus
 marked `>`, each channel end in words ("answers GET /api/x", "writes table t"), and what calls the focus or what it calls
-said so. The last lines say how much was left out and name the nearest of it. The ranking visits only code near the focus,
+said so. The last lines say how much was left out and name the nearest of it. With `bodies` (`leyline context <focus> --bodies`, or the tool's `bodies` argument) the code itself follows the outline,
+which then takes a third of the budget (the budget is raised to 600 tokens if it is smaller, and the answer says so).
+It holds, in this order: the whole body of each focus function, at most three and cut after 80 lines; each type the focus
+takes as a parameter or returns, as its declaration and at most 12 field lines, never its methods; and, for each direct
+caller (those that are not test code first, nearest in the rank first), the 40 lines around the call, or 16 for a call made
+from the top level of a file. A caller found by a guess says so, and so does one of a method the focus overrides. A text is
+shown once, a function defined twice shows each definition, and no sibling method comes with any of them. What fits is
+decided from the lengths the map holds before a file is read, and packing stops after ten bodies are too long for what is
+left; those and the rest are named under "Bodies left out". A file that has become a link out of the repository is not
+read, and a function edited since the map is not shown (it is named as changed since the map). The ranking visits only code near the focus,
 and the graph is read once per map run: on Parlance (160,000 lines) the first call takes 0.3 s and later ones 0.05 s.
 
 ### Asking how something works