moru-narrow 26.45.0__tar.gz

moru_narrow-26.45.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 taehwandev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

moru_narrow-26.45.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: moru-narrow
+Version: 26.45.0
+Summary: Narrow `rg -w <Name>` to the files and lines you must edit after a signature change (Kotlin+Gradle, TypeScript).
+Author: taehwandev
+License: MIT
+Project-URL: Homepage, https://github.com/taehwandev/moru-narrow
+Project-URL: Issues, https://github.com/taehwandev/moru-narrow/issues
+Keywords: ripgrep,rg,refactoring,coding-agent,kotlin,typescript,claude-code,codex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# moru-narrow
+
+**English** | [한국어](README.ko.md)
+
+> **rg tells you every line that mentions a name. moru-narrow tells you which of those lines you must edit.** It keeps every hit; it only changes the order and what is shown first.
+
+`moru-narrow` post-processes `rg -w <Name>` for coding agents and humans. It keeps every hit, ranks them, and prints the
+files and **line ranges** to check first. No index, no database, no model calls, no daemon. Python standard library and
+[ripgrep](https://github.com/BurntSushi/ripgrep) only.
+
+> Scope: **signature changes** (add or change a parameter, then find what breaks). It is not a general `rg` replacement: for renaming a variable, tracing a logic bug or searching a config string, use plain `rg`.
+>
+> Status: alpha / experimental. MIT license. The examples use the `moru-narrow` command (alias `mnarrow`); from a clone, run `python3 -m moru_narrow` instead.
+
+## In short
+
+- **What it does:** after `rg -w name`, it lists the few files and line ranges you must edit, ranked, and hides the rest behind `--all`. Nothing is dropped.
+- **Does it miss files?** Checked against the compiler: in all 217 Kotlin tasks every truth file was listed (rules were partly tuned on them), and 191 of 194 tasks (99.3% of files) on a fresh TypeScript set. The rare misses are files that never mention the name.
+- **Does it help a coding agent?** In 6 test setups the compile success rate never dropped below the baseline. Context tokens fell by 9.8% to 34.5% in five setups; in the sixth (Codex on TypeScript) the change cannot be told apart from noise.
+- **The catch:** the savings appeared only when the agent was also told not to re-run `rg`. Without that sentence, cost went up 10.3% [+0.0003, +0.0009 USD per task] in one test (Kotlin, Haiku, 57 tasks).
+
+```text
+$ moru-narrow getGlobalTheme --repo ./my-next-app
+getGlobalTheme  declared: src/lib/theme-settings.ts:28
+TIER 1: check these (3 files). rg found 4 files, 6 lines.
+src/app/[locale]/(walled)/manage/(protected)/admin/settings/page.tsx
+  5: import { getGlobalTheme, saveGlobalTheme, type ThemeMode } from '@/lib/theme-settings';
+  19-22: getGlobalTheme({ fresh: true }).then(t => {
+...
+hidden: tier 2 has 0 files (use --all to list them)
+```
+
+## Quick start
+
+Needs Python 3.9+ and [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) on your `PATH`. No other dependency. It does not need Moru Core or any other tool.
+
+```bash
+pipx install git+https://github.com/taehwandev/moru-narrow     # or: uv tool install git+https://... / pip install git+https://...
+moru-narrow <Name> --repo /path/to/your/project                # Kotlin+Gradle or TypeScript, auto-detected
+```
+
+Without installing, from a clone: `git clone https://github.com/taehwandev/moru-narrow && cd moru-narrow && python3 -m moru_narrow <Name> --repo ...`.
+
+Not published on PyPI or npm yet. The `pip install git+...` route was tested in a clean virtualenv on macOS with Python 3.9.6; other platforms and Python versions are untested.
+
+## Use with your coding agent
+
+The tool only helps an agent when the agent is told how to use it (see the savings section: without the "do not re-run rg" sentence cost went up). One command registers that instruction:
+
+```bash
+moru-narrow --install                # agent skill in ~/.claude/skills/ (Claude Code) and ~/.agents/skills/ (Codex and other agent-skills tools)
+moru-narrow --install --project      # same, but into ./.claude and ./.agents so your team shares it via git
+moru-narrow --install --agents-md    # no skill support (e.g. Cursor): add a marked block to ./AGENTS.md
+```
+
+Re-running is safe: an existing `SKILL.md` is kept (`--force` overwrites it), and the `AGENTS.md` block is replaced in place without touching your other text. `--target claude|agents` limits the skill install to one location. The installed text is based on the instruction used in the agent tests (worded differently, and extended as noted below):
+
+> When a task changes a function or constructor signature (adds or changes a parameter), run `moru-narrow <Name> --repo <project root>` once and edit the call sites it lists under TIER 1. Do not run `rg` again for the same name. Use `--all` only if the list looks incomplete. For anything else (renames, logic bugs, config strings), or if moru-narrow reports an error or an unsupported language, use plain `rg`.
+
+The exact wording was not the one measured, and the last sentence (use plain `rg` for other tasks and unsupported languages) is new: the tests only contained signature-change tasks and a prompt written for them. Any agent that can run a shell command can also call `moru-narrow` directly.
+
+## Why
+
+Changing a function signature means finding every place that breaks. `rg -w name` finds all of them, plus comments,
+strings, same-named functions in other modules and unrelated files. On a Kotlin monorepo it returned **60 files for a
+change that broke 3 to 4**. An agent then reads all of them.
+
+A code-graph index was the obvious fix. We measured a syntax-level code-graph index on the same Kotlin repo and it did not
+pay off at the agent level: no measurable cost difference with location-only output, and about +45.5% cost when it returned source code (that run also carried MCP connection overhead, so part of the increase is not the graph itself).
+It also needs an index build and a sync after every edit (stale until synced). `moru-narrow` has no build step and no
+staleness, because it runs `rg` live.
+
+## How it works
+
+1. `rg -nw <Name>` collects hits (test files are excluded).
+2. Each line gets a role: `use`, `import`, `override`, `declaration`, `comment`, `string`, `named-arg`, ...
+3. A file is **tier 1** when it has a strong role (`use`/`import`/`override`) **and** can see the declaration:
+   - Kotlin: the module is reachable through Gradle `project()` edges, and the file is in the same package or imports it.
+   - TypeScript: the file imports the declaring file (relative paths and `tsconfig` aliases, through re-exporting
+     barrel files), or imports a wrapper that does and calls `X.name`, or is the declaring file itself.
+4. Everything else is demoted to tier 2/3. **Filters only demote. `--all` always lists everything `rg` found.**
+5. Multi-line calls are returned as ranges (`19-22`), because compilers report errors at argument lines.
+
+```text
+moru-narrow <Name> [--repo DIR] [--decl FILE] [--all] [--json] [--lang kotlin|ts]
+```
+
+Language is auto-detected (`tsconfig.json`, or a Gradle build).
+
+## How to read the numbers
+
+| Term | What it means here |
+| --- | --- |
+| **Truth files** | Production files that stop compiling after we add a required first parameter (`traceId`) to a function. The compiler decides, not us. |
+| **Recall** | Whether the truth files appear in tier 1. The table counts tasks where all of them do (`23/23`); TypeScript rows also give files (`428/431` = 3 truth files were not listed). |
+| **Tier 1** | The files moru-narrow tells you to read first. |
+| **`rg -w` files / lines** | What plain ripgrep returns for the same name. This is the baseline to beat. |
+| **Fresh set** | Candidates drawn after the rules were frozen. Nothing was tuned on them, so they are the fair test. |
+| **Baseline vs. with moru-narrow** (agent tests) | Same coding agent, same task, same prompt. Baseline may use `rg`, `ls` and file reads. The other condition also gets the tool and the sentence "edit from the list, do not re-run rg for the same name". |
+| **Compile pass** | The project compiles after the agent's edit (Kotlin: Gradle, TypeScript: `tsc --noEmit`). TypeScript runs also require that the declaration really gained the parameter, because an agent that changes nothing would otherwise pass. |
+| **Context tokens** | Input tokens the model processed during the whole run, cached ones included. A proxy for how much it read. |
+| **Cost** | API-equivalent price estimate reported by the Claude CLI, not an actual bill. Codex does not report it, shown as n/a. |
+| **`[a, b]` interval** | 95% range from a task-paired bootstrap (10,000 resamples): tasks are resampled and the two conditions are compared on the same task. If the range includes 0, treat the difference as noise. |
+| **tasks x reps** | Number of tasks times repetitions per task. Repetitions of one task are averaged before the comparison. |
+
+## Does it miss files?
+
+Ground truth is the **compiler**: add a required first parameter `traceId: String` / `traceId: string` to a function (or
+Kotlin constructor), compile, and take the production files that fail as the truth.
+
+| Set | Tasks | `rg -w` files / lines | moru-narrow tier 1 files / lines | Tasks with every truth file in tier 1 |
+| --- | ---: | --- | --- | ---: |
+| Kotlin, 23 selected noisy functions | 23 | 60.4 / 139 | 8.8 / 18 | 23/23 |
+| Kotlin, held-out functions | 120 | 68.3 / 281 | 3.3 / 5 | 120/120 |
+| Kotlin, held-out noisy subset (rg >= 20 files and >= 2x the truth) | 57 | 132.9 / 571 | 3.8 / 7 | 57/57 |
+| Kotlin, constructor changes | 74 | 14.9 / 36 | 8.8 / 17 | 74/74 |
+| TypeScript, **fresh** functions (v3 rules frozen first) | 194 | 3.5 / 7 | 2.5 / 6 | 191/194 (files: 428/431, 99.3%) |
+| TypeScript, fresh, noisy functions (rg >= 5 files) | 28 | 9.5 / 20 | 8.2 / 18 | 28/28 (files: 193/193) |
+
+Read these carefully:
+
+- Kotlin rules were adjusted after the first held-out misses (two regex bugs), so the Kotlin sets are **not fully
+  independent**. The TypeScript fresh set is: rules were frozen (sha256 recorded) before it was scored.
+- TypeScript misses that remain are cases where the failing file **never mentions the name** (the type flows through
+  another function). No `rg`-based tool can find those.
+- Line level: error lines inside the recommended ranges were 90% (Kotlin functions), 96% within +-8 lines (Kotlin
+  constructors) and 90% (TypeScript functions). Use ranges as hints, files as the guarantee.
+- The TypeScript compiler truth is built with the TypeScript API in memory against one private Next.js repo; Kotlin on
+  one private Compose Multiplatform repo. Neither repo is published here.
+
+## Does it save an agent anything?
+
+Same task, same prompt template, two conditions, task-paired bootstrap (10,000 resamples, 95% interval). Local logins
+only. Cost is the API-equivalent estimate reported by the CLI.
+
+| Setup | Compile pass (baseline -> with moru-narrow) | Context tokens | Cost |
+| --- | --- | --- | --- |
+| Kotlin, Haiku, 23 tasks x 2 | 46/46 -> 46/46 | **-34.5%** [-107k, -37k] | **-24.2%** |
+| Kotlin, Haiku, 57 tasks x 2 | 112/114 -> 114/114 | **-19.2%** [-36k, -18k] | **-16.4%** |
+| Kotlin, Codex terra, 23 x 2 | 44/46 -> 45/46 | **-14.2%** [-22.8%, -6.2%] | n/a |
+| Kotlin, Codex terra, 57 x 2 | 112/114 -> 114/114 | **-9.8%** [-14.6%, -5.3%] | n/a |
+| TypeScript, Haiku, 28 x 2 | 56/56 -> 56/56 | **-22.2%** [-29.4%, -15.3%] | **-11.1%** [-17.3%, -4.3%] |
+| TypeScript, Codex terra, 28 x 2 | 56/56 -> 56/56 | -6.5% [-13.5%, 0.0%] (touches 0) | n/a |
+
+**The agent instruction matters as much as the tool.** In the first Kotlin experiment the agent got the same list but
+kept re-running `rg` afterwards, and cost went **up** 10.3% (context +12.8%) on the larger Haiku set. Adding one
+sentence, "edit the call sites from this list without re-running rg for the same name; use --all only if the list looks
+incomplete", changed that: with it, `rg` calls per run fell from 2.4 to 0.02 (Kotlin, Codex, 23 tasks) and from 2.8 to 0.5
+(TypeScript, Haiku), and it produced the table above. That revised prompt was written after seeing the first
+results, so treat the savings as exploratory, and ship the instruction together with the tool.
+
+**What we learned the hard way.** The first TypeScript agent run failed 10 more tasks than the baseline (33/44 vs 43/44).
+Every file the compiler flagged was in the list; the miss was calls *inside the declaring file*, which the first
+version hid because a file does not import itself. The offline truth had also excluded the declaring file, so the offline
+check could not see it. Fix: v3 keeps those lines in tier 1. Lesson: validate with the real agent loop, not only offline.
+
+## Limits
+
+- Languages: Kotlin + Gradle and TypeScript. Each language needs a small profile (role patterns, how to see a
+  declaration). Dynamic languages need a different ground truth.
+- Verified on **one change shape** (adding a required first parameter) and **one repository per language**.
+- React components are out of scope (a positional first parameter does not exist in JSX).
+- Savings depend on the model. Codex on the TypeScript repo showed no clear reduction (-6.5%, interval touches 0). There
+  `rg` was already precise (3.5 files on average for functions) and the agent ran only ~3 commands per task; we did not test why.
+- Sample sizes are small (28 to 57 tasks, 2 repetitions per task). In the baseline every run passed in TypeScript, so pass rate cannot show an improvement there, only that nothing broke.
+- The agent tests sent private source to the model providers (Anthropic, OpenAI) through the author's own local CLI logins.
+
+## Reproduce
+
+The evaluation harnesses (agent runners, compiler-truth generators, scorers) are not in this repository yet: they carry local paths and private repository details and need a scrub first. `results/` holds the aggregate tables. The method is described above: compiler errors after adding a required first parameter are the ground truth; rules were frozen (hash recorded) before the fresh TypeScript set was scored.
+
+## Versioning
+
+Weekly CalVer `YY.WW.N` (scheme `calver-weekly`), for example `26.45.0`: two-digit year, week number, and a release count that starts at `0` each week and counts published packages. Weeks follow the Korean calendar (Asia/Seoul, Monday-start weeks). Git tags use a `v` prefix (`v26.45.0`); the package metadata omits it. Python normalises a zero-padded week, so week 5 appears as `26.5.0` on PyPI. This is a date-based version, not a compatibility signal: while the tool is alpha, read the commit log before upgrading.
+
+## Status
+
+Alpha. Not on PyPI or npm. No unit tests yet. The ranking was validated against compiler ground truth (see above); `--install` was only checked by hand in a temporary home directory (fresh install, re-run, `--project`, `--agents-md` idempotence). Issues and results from other repositories are welcome.
+
+License: [MIT](LICENSE).

moru_narrow-26.45.0/README.md

@@ -0,0 +1,180 @@
+# moru-narrow
+
+**English** | [한국어](README.ko.md)
+
+> **rg tells you every line that mentions a name. moru-narrow tells you which of those lines you must edit.** It keeps every hit; it only changes the order and what is shown first.
+
+`moru-narrow` post-processes `rg -w <Name>` for coding agents and humans. It keeps every hit, ranks them, and prints the
+files and **line ranges** to check first. No index, no database, no model calls, no daemon. Python standard library and
+[ripgrep](https://github.com/BurntSushi/ripgrep) only.
+
+> Scope: **signature changes** (add or change a parameter, then find what breaks). It is not a general `rg` replacement: for renaming a variable, tracing a logic bug or searching a config string, use plain `rg`.
+>
+> Status: alpha / experimental. MIT license. The examples use the `moru-narrow` command (alias `mnarrow`); from a clone, run `python3 -m moru_narrow` instead.
+
+## In short
+
+- **What it does:** after `rg -w name`, it lists the few files and line ranges you must edit, ranked, and hides the rest behind `--all`. Nothing is dropped.
+- **Does it miss files?** Checked against the compiler: in all 217 Kotlin tasks every truth file was listed (rules were partly tuned on them), and 191 of 194 tasks (99.3% of files) on a fresh TypeScript set. The rare misses are files that never mention the name.
+- **Does it help a coding agent?** In 6 test setups the compile success rate never dropped below the baseline. Context tokens fell by 9.8% to 34.5% in five setups; in the sixth (Codex on TypeScript) the change cannot be told apart from noise.
+- **The catch:** the savings appeared only when the agent was also told not to re-run `rg`. Without that sentence, cost went up 10.3% [+0.0003, +0.0009 USD per task] in one test (Kotlin, Haiku, 57 tasks).
+
+```text
+$ moru-narrow getGlobalTheme --repo ./my-next-app
+getGlobalTheme  declared: src/lib/theme-settings.ts:28
+TIER 1: check these (3 files). rg found 4 files, 6 lines.
+src/app/[locale]/(walled)/manage/(protected)/admin/settings/page.tsx
+  5: import { getGlobalTheme, saveGlobalTheme, type ThemeMode } from '@/lib/theme-settings';
+  19-22: getGlobalTheme({ fresh: true }).then(t => {
+...
+hidden: tier 2 has 0 files (use --all to list them)
+```
+
+## Quick start
+
+Needs Python 3.9+ and [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) on your `PATH`. No other dependency. It does not need Moru Core or any other tool.
+
+```bash
+pipx install git+https://github.com/taehwandev/moru-narrow     # or: uv tool install git+https://... / pip install git+https://...
+moru-narrow <Name> --repo /path/to/your/project                # Kotlin+Gradle or TypeScript, auto-detected
+```
+
+Without installing, from a clone: `git clone https://github.com/taehwandev/moru-narrow && cd moru-narrow && python3 -m moru_narrow <Name> --repo ...`.
+
+Not published on PyPI or npm yet. The `pip install git+...` route was tested in a clean virtualenv on macOS with Python 3.9.6; other platforms and Python versions are untested.
+
+## Use with your coding agent
+
+The tool only helps an agent when the agent is told how to use it (see the savings section: without the "do not re-run rg" sentence cost went up). One command registers that instruction:
+
+```bash
+moru-narrow --install                # agent skill in ~/.claude/skills/ (Claude Code) and ~/.agents/skills/ (Codex and other agent-skills tools)
+moru-narrow --install --project      # same, but into ./.claude and ./.agents so your team shares it via git
+moru-narrow --install --agents-md    # no skill support (e.g. Cursor): add a marked block to ./AGENTS.md
+```
+
+Re-running is safe: an existing `SKILL.md` is kept (`--force` overwrites it), and the `AGENTS.md` block is replaced in place without touching your other text. `--target claude|agents` limits the skill install to one location. The installed text is based on the instruction used in the agent tests (worded differently, and extended as noted below):
+
+> When a task changes a function or constructor signature (adds or changes a parameter), run `moru-narrow <Name> --repo <project root>` once and edit the call sites it lists under TIER 1. Do not run `rg` again for the same name. Use `--all` only if the list looks incomplete. For anything else (renames, logic bugs, config strings), or if moru-narrow reports an error or an unsupported language, use plain `rg`.
+
+The exact wording was not the one measured, and the last sentence (use plain `rg` for other tasks and unsupported languages) is new: the tests only contained signature-change tasks and a prompt written for them. Any agent that can run a shell command can also call `moru-narrow` directly.
+
+## Why
+
+Changing a function signature means finding every place that breaks. `rg -w name` finds all of them, plus comments,
+strings, same-named functions in other modules and unrelated files. On a Kotlin monorepo it returned **60 files for a
+change that broke 3 to 4**. An agent then reads all of them.
+
+A code-graph index was the obvious fix. We measured a syntax-level code-graph index on the same Kotlin repo and it did not
+pay off at the agent level: no measurable cost difference with location-only output, and about +45.5% cost when it returned source code (that run also carried MCP connection overhead, so part of the increase is not the graph itself).
+It also needs an index build and a sync after every edit (stale until synced). `moru-narrow` has no build step and no
+staleness, because it runs `rg` live.
+
+## How it works
+
+1. `rg -nw <Name>` collects hits (test files are excluded).
+2. Each line gets a role: `use`, `import`, `override`, `declaration`, `comment`, `string`, `named-arg`, ...
+3. A file is **tier 1** when it has a strong role (`use`/`import`/`override`) **and** can see the declaration:
+   - Kotlin: the module is reachable through Gradle `project()` edges, and the file is in the same package or imports it.
+   - TypeScript: the file imports the declaring file (relative paths and `tsconfig` aliases, through re-exporting
+     barrel files), or imports a wrapper that does and calls `X.name`, or is the declaring file itself.
+4. Everything else is demoted to tier 2/3. **Filters only demote. `--all` always lists everything `rg` found.**
+5. Multi-line calls are returned as ranges (`19-22`), because compilers report errors at argument lines.
+
+```text
+moru-narrow <Name> [--repo DIR] [--decl FILE] [--all] [--json] [--lang kotlin|ts]
+```
+
+Language is auto-detected (`tsconfig.json`, or a Gradle build).
+
+## How to read the numbers
+
+| Term | What it means here |
+| --- | --- |
+| **Truth files** | Production files that stop compiling after we add a required first parameter (`traceId`) to a function. The compiler decides, not us. |
+| **Recall** | Whether the truth files appear in tier 1. The table counts tasks where all of them do (`23/23`); TypeScript rows also give files (`428/431` = 3 truth files were not listed). |
+| **Tier 1** | The files moru-narrow tells you to read first. |
+| **`rg -w` files / lines** | What plain ripgrep returns for the same name. This is the baseline to beat. |
+| **Fresh set** | Candidates drawn after the rules were frozen. Nothing was tuned on them, so they are the fair test. |
+| **Baseline vs. with moru-narrow** (agent tests) | Same coding agent, same task, same prompt. Baseline may use `rg`, `ls` and file reads. The other condition also gets the tool and the sentence "edit from the list, do not re-run rg for the same name". |
+| **Compile pass** | The project compiles after the agent's edit (Kotlin: Gradle, TypeScript: `tsc --noEmit`). TypeScript runs also require that the declaration really gained the parameter, because an agent that changes nothing would otherwise pass. |
+| **Context tokens** | Input tokens the model processed during the whole run, cached ones included. A proxy for how much it read. |
+| **Cost** | API-equivalent price estimate reported by the Claude CLI, not an actual bill. Codex does not report it, shown as n/a. |
+| **`[a, b]` interval** | 95% range from a task-paired bootstrap (10,000 resamples): tasks are resampled and the two conditions are compared on the same task. If the range includes 0, treat the difference as noise. |
+| **tasks x reps** | Number of tasks times repetitions per task. Repetitions of one task are averaged before the comparison. |
+
+## Does it miss files?
+
+Ground truth is the **compiler**: add a required first parameter `traceId: String` / `traceId: string` to a function (or
+Kotlin constructor), compile, and take the production files that fail as the truth.
+
+| Set | Tasks | `rg -w` files / lines | moru-narrow tier 1 files / lines | Tasks with every truth file in tier 1 |
+| --- | ---: | --- | --- | ---: |
+| Kotlin, 23 selected noisy functions | 23 | 60.4 / 139 | 8.8 / 18 | 23/23 |
+| Kotlin, held-out functions | 120 | 68.3 / 281 | 3.3 / 5 | 120/120 |
+| Kotlin, held-out noisy subset (rg >= 20 files and >= 2x the truth) | 57 | 132.9 / 571 | 3.8 / 7 | 57/57 |
+| Kotlin, constructor changes | 74 | 14.9 / 36 | 8.8 / 17 | 74/74 |
+| TypeScript, **fresh** functions (v3 rules frozen first) | 194 | 3.5 / 7 | 2.5 / 6 | 191/194 (files: 428/431, 99.3%) |
+| TypeScript, fresh, noisy functions (rg >= 5 files) | 28 | 9.5 / 20 | 8.2 / 18 | 28/28 (files: 193/193) |
+
+Read these carefully:
+
+- Kotlin rules were adjusted after the first held-out misses (two regex bugs), so the Kotlin sets are **not fully
+  independent**. The TypeScript fresh set is: rules were frozen (sha256 recorded) before it was scored.
+- TypeScript misses that remain are cases where the failing file **never mentions the name** (the type flows through
+  another function). No `rg`-based tool can find those.
+- Line level: error lines inside the recommended ranges were 90% (Kotlin functions), 96% within +-8 lines (Kotlin
+  constructors) and 90% (TypeScript functions). Use ranges as hints, files as the guarantee.
+- The TypeScript compiler truth is built with the TypeScript API in memory against one private Next.js repo; Kotlin on
+  one private Compose Multiplatform repo. Neither repo is published here.
+
+## Does it save an agent anything?
+
+Same task, same prompt template, two conditions, task-paired bootstrap (10,000 resamples, 95% interval). Local logins
+only. Cost is the API-equivalent estimate reported by the CLI.
+
+| Setup | Compile pass (baseline -> with moru-narrow) | Context tokens | Cost |
+| --- | --- | --- | --- |
+| Kotlin, Haiku, 23 tasks x 2 | 46/46 -> 46/46 | **-34.5%** [-107k, -37k] | **-24.2%** |
+| Kotlin, Haiku, 57 tasks x 2 | 112/114 -> 114/114 | **-19.2%** [-36k, -18k] | **-16.4%** |
+| Kotlin, Codex terra, 23 x 2 | 44/46 -> 45/46 | **-14.2%** [-22.8%, -6.2%] | n/a |
+| Kotlin, Codex terra, 57 x 2 | 112/114 -> 114/114 | **-9.8%** [-14.6%, -5.3%] | n/a |
+| TypeScript, Haiku, 28 x 2 | 56/56 -> 56/56 | **-22.2%** [-29.4%, -15.3%] | **-11.1%** [-17.3%, -4.3%] |
+| TypeScript, Codex terra, 28 x 2 | 56/56 -> 56/56 | -6.5% [-13.5%, 0.0%] (touches 0) | n/a |
+
+**The agent instruction matters as much as the tool.** In the first Kotlin experiment the agent got the same list but
+kept re-running `rg` afterwards, and cost went **up** 10.3% (context +12.8%) on the larger Haiku set. Adding one
+sentence, "edit the call sites from this list without re-running rg for the same name; use --all only if the list looks
+incomplete", changed that: with it, `rg` calls per run fell from 2.4 to 0.02 (Kotlin, Codex, 23 tasks) and from 2.8 to 0.5
+(TypeScript, Haiku), and it produced the table above. That revised prompt was written after seeing the first
+results, so treat the savings as exploratory, and ship the instruction together with the tool.
+
+**What we learned the hard way.** The first TypeScript agent run failed 10 more tasks than the baseline (33/44 vs 43/44).
+Every file the compiler flagged was in the list; the miss was calls *inside the declaring file*, which the first
+version hid because a file does not import itself. The offline truth had also excluded the declaring file, so the offline
+check could not see it. Fix: v3 keeps those lines in tier 1. Lesson: validate with the real agent loop, not only offline.
+
+## Limits
+
+- Languages: Kotlin + Gradle and TypeScript. Each language needs a small profile (role patterns, how to see a
+  declaration). Dynamic languages need a different ground truth.
+- Verified on **one change shape** (adding a required first parameter) and **one repository per language**.
+- React components are out of scope (a positional first parameter does not exist in JSX).
+- Savings depend on the model. Codex on the TypeScript repo showed no clear reduction (-6.5%, interval touches 0). There
+  `rg` was already precise (3.5 files on average for functions) and the agent ran only ~3 commands per task; we did not test why.
+- Sample sizes are small (28 to 57 tasks, 2 repetitions per task). In the baseline every run passed in TypeScript, so pass rate cannot show an improvement there, only that nothing broke.
+- The agent tests sent private source to the model providers (Anthropic, OpenAI) through the author's own local CLI logins.
+
+## Reproduce
+
+The evaluation harnesses (agent runners, compiler-truth generators, scorers) are not in this repository yet: they carry local paths and private repository details and need a scrub first. `results/` holds the aggregate tables. The method is described above: compiler errors after adding a required first parameter are the ground truth; rules were frozen (hash recorded) before the fresh TypeScript set was scored.
+
+## Versioning
+
+Weekly CalVer `YY.WW.N` (scheme `calver-weekly`), for example `26.45.0`: two-digit year, week number, and a release count that starts at `0` each week and counts published packages. Weeks follow the Korean calendar (Asia/Seoul, Monday-start weeks). Git tags use a `v` prefix (`v26.45.0`); the package metadata omits it. Python normalises a zero-padded week, so week 5 appears as `26.5.0` on PyPI. This is a date-based version, not a compatibility signal: while the tool is alpha, read the commit log before upgrading.
+
+## Status
+
+Alpha. Not on PyPI or npm. No unit tests yet. The ranking was validated against compiler ground truth (see above); `--install` was only checked by hand in a temporary home directory (fresh install, re-run, `--project`, `--agents-md` idempotence). Issues and results from other repositories are welcome.
+
+License: [MIT](LICENSE).

moru_narrow-26.45.0/moru_narrow/__main__.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""moru-narrow: recommend the files and lines to check after `rg -w <Name>` (Kotlin + Gradle, TypeScript).
+
+Static, no model calls, no index, standard library + ripgrep only. Filters only demote; --all lists everything rg found.
+  moru-narrow <Name> [--repo DIR] [--decl FILE] [--all] [--json] [--lang kotlin|ts]
+  moru-narrow --install [--target claude|agents|both] [--project] [--agents-md] [--force]
+"""
+import importlib, sys
+from pathlib import Path
+
+
+def detect(repo):
+    root = Path(repo)
+    if (root / "tsconfig.json").exists(): return "ts"
+    if any(any(root.glob(g)) for g in ("settings.gradle*", "build.gradle*", "*/build.gradle*")): return "kotlin"
+    if (root / "package.json").exists(): return "ts"
+    sys.exit("moru-narrow: cannot detect the language (looked for tsconfig.json or a Gradle build at the repo root); pass --lang kotlin|ts")
+
+
+def main():
+    argv = sys.argv[1:]; lang = None; repo = "."
+    if argv[:1] == ["--install"]:
+        from moru_narrow import install
+        return install.main(argv[1:])
+    if "--lang" in argv:
+        i = argv.index("--lang"); lang = argv[i + 1]; del argv[i:i + 2]
+    if "--repo" in argv: repo = argv[argv.index("--repo") + 1]
+    lang = lang or detect(repo)
+    mod = importlib.import_module({"kotlin": "moru_narrow.kotlin", "ts": "moru_narrow.typescript"}[lang])
+    sys.argv = [f"moru-narrow({lang})"] + argv
+    mod.main()
+
+
+if __name__ == "__main__": main()

moru_narrow-26.45.0/moru_narrow/install.py

@@ -0,0 +1,63 @@
+"""`moru-narrow --install`: register moru-narrow with AI coding agents (agent-skills `SKILL.md`, or an `AGENTS.md` block).
+
+  moru-narrow --install [--target claude|agents|both] [--project] [--agents-md] [--force]
+"""
+import argparse, re
+from pathlib import Path
+
+RULE = ("When a task changes a function or constructor signature (adds or changes a parameter), run "
+        "`moru-narrow <Name> --repo <project root>` once and edit the call sites it lists under TIER 1. "
+        "Do not run `rg` again for the same name. Use `--all` only if the list looks incomplete. "
+        "For anything else (renames, logic bugs, config strings), or if moru-narrow reports an error or an unsupported language, use plain `rg`.")
+
+SKILL = f"""---
+name: moru-narrow
+description: After a Kotlin (Gradle) or TypeScript function/constructor signature change, list the few files and line ranges that break, instead of reading every `rg` hit.
+---
+
+# moru-narrow
+
+{RULE}
+
+```bash
+moru-narrow getGlobalTheme --repo .     # TIER 1 = files to edit; tier 2/3 are hidden, --all shows them
+```
+
+It post-processes `rg -nw`, so every hit is still reachable with `--all`. No index, no network, no model calls.
+If `moru-narrow` is not on PATH, use `python3 -m moru_narrow`.
+"""
+
+BEGIN, END = "<!-- moru-narrow:begin -->", "<!-- moru-narrow:end -->"
+BLOCK = f"{BEGIN}\n## moru-narrow\n\n{RULE}\n{END}\n"
+
+
+def skill_dirs(target, project):
+    base = Path(".") if project else Path.home()
+    return [base / d / "skills" / "moru-narrow" for d in ((".claude",) if target == "claude" else (".agents",) if target == "agents" else (".claude", ".agents"))]
+
+
+def write_skill(d, force):
+    f = d / "SKILL.md"
+    if f.exists() and not force: return f"kept     {f} (exists, use --force to overwrite)"
+    d.mkdir(parents=True, exist_ok=True); f.write_text(SKILL)
+    return f"wrote    {f}"
+
+
+def write_agents_md(path):
+    text = path.read_text() if path.exists() else ""
+    pat = re.compile(re.escape(BEGIN) + r".*?" + re.escape(END) + r"\n?", re.S)
+    new = pat.sub(lambda _: BLOCK, text) if pat.search(text) else (text + ("\n" if text and not text.endswith("\n\n") else "") + BLOCK)
+    path.write_text(new)
+    return f"updated  {path}"
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(prog="moru-narrow --install", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--target", choices=("claude", "agents", "both"), default="both")
+    ap.add_argument("--project", action="store_true", help="write into ./.claude and ./.agents instead of your home directory")
+    ap.add_argument("--agents-md", action="store_true", help="insert a marked block into ./AGENTS.md instead of installing a skill")
+    ap.add_argument("--force", action="store_true")
+    a = ap.parse_args(argv)
+    if a.agents_md: print(write_agents_md(Path("AGENTS.md")))
+    else:
+        for d in skill_dirs(a.target, a.project): print(write_skill(d, a.force))

moru_narrow-26.45.0/moru_narrow/kotlin.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""moru-narrow: recommend the files and lines to check after `rg -w <name>`, without missing any.
+
+Static, no model calls, standard library only. Kotlin + Gradle first.
+Filters only DEMOTE files into tiers; `--all` always lists everything rg found.
+
+  moru-narrow <Name> [--repo DIR] [--decl FILE] [--all] [--json]
+"""
+import argparse, json, os, re, subprocess, sys
+from pathlib import Path
+
+STRONG = ("use", "override", "import")
+TEST = re.compile(r"/(src/)?\w*[Tt]est\w*/")
+PKG = re.compile(r"^package\s+([\w.]+)", re.M)
+
+
+def is_test(rel): return bool(TEST.search("/" + rel)) or rel.endswith("Test.kt")
+
+
+class Repo:
+    def __init__(self, root):
+        self.root = Path(root).resolve(); self.src = {}
+        self.build = {}                      # module dir -> set(dependency dirs)
+        for g in list(self.root.rglob("build.gradle.kts")) + list(self.root.rglob("build.gradle")):
+            if "/build/" in str(g): continue
+            d = g.parent; base = self._settings_root(d)
+            deps = {(base / p.strip(":").replace(":", "/")).relative_to(self.root).as_posix()
+                    for p in re.findall(r'project\(["\'](:[\w:.-]+)["\']\)', g.read_text(errors="ignore"))}
+            self.build[d.relative_to(self.root).as_posix()] = deps
+        self.reach = {m: self._closure(m) for m in self.build}
+
+    def _settings_root(self, d):
+        cur = d
+        while True:
+            if (cur / "settings.gradle.kts").exists() or (cur / "settings.gradle").exists(): return cur
+            if cur == self.root or cur == cur.parent: return self.root
+            cur = cur.parent
+
+    def _closure(self, m):
+        seen, st = set(), [m]
+        while st:
+            for y in self.build.get(st.pop(), ()):
+                if y not in seen: seen.add(y); st.append(y)
+        return seen
+
+    def text(self, rel):
+        if rel not in self.src: self.src[rel] = (self.root / rel).read_text(errors="ignore")
+        return self.src[rel]
+
+    def module(self, rel):
+        cur = Path(rel).parent
+        while str(cur) != ".":
+            if cur.as_posix() in self.build: return cur.as_posix()
+            cur = cur.parent
+
+    def package(self, rel):
+        m = PKG.search(self.text(rel)); return m.group(1) if m else ""
+
+
+def role(line, name):
+    s = line.strip()
+    if s.startswith(("//", "*", "/*")): return "comment"
+    if re.match(r"import\s", s): return "import" if s.endswith("." + name) or " as " in s else "import-other"
+    if re.search(rf"\b(val|var)\s+{name}\b", s) and not re.search(rf"\b{name}\s*\(", s): return "property"
+    if re.search(rf"\bfun\s+(?:<[^>]*>\s*)?(?:[\w.<>?]+\.)?{name}\s*[(<]", s) or re.search(rf"\b(?:class|interface|object|typealias)\s+{name}\b", s):
+        return "override" if "override" in s else "declaration"
+    if re.search(rf"(?<![\w\"'])(?:\.|::|\b){name}\s*(?:\(|\{{|$|\)|,)", s): return "use"
+    if re.search(rf"\b{name}\s*=", s): return "named-arg"
+    return "other"
+
+
+def call_range(lines, i):
+    """1-based line i; extend to the closing paren of the call that starts there (max 40 lines)."""
+    depth, seen = 0, False
+    for j in range(i - 1, min(len(lines), i + 39)):
+        for ch in lines[j]:
+            if ch == "(": depth += 1; seen = True
+            elif ch == ")": depth -= 1
+        if seen and depth <= 0: return i, j + 1
+        if not seen and j > i - 1: break
+    return i, i
+
+
+def rg_hits(repo, name):
+    out = subprocess.run(["rg", "-nw", "--glob", "*.kt", name, "."], cwd=repo.root, capture_output=True, text=True).stdout.splitlines()
+    byfile = {}
+    for l in out:
+        m = re.match(r"\./(.+?\.kt):(\d+):(.*)", l)
+        if m and not is_test(m.group(1)): byfile.setdefault(m.group(1), []).append((int(m.group(2)), m.group(3)))
+    return byfile
+
+
+def recommend(repo, name, decl_files=None):
+    byfile = rg_hits(repo, name)
+    decls = []
+    for rel, hits in byfile.items():
+        for ln, tx in hits:
+            if role(tx, name) == "declaration" and (decl_files is None or rel in decl_files): decls.append((rel, ln))
+    if decl_files: decls = [(f, next((ln for ln, tx in byfile.get(f, []) if role(tx, name) == "declaration"), 0)) for f in decl_files]
+    dfiles = {d[0] for d in decls}
+    dmods = {repo.module(f) for f in dfiles}; dpkgs = {repo.package(f) for f in dfiles}
+    tiers = {1: {}, 2: {}, 3: {}}
+    for rel, hits in byfile.items():
+        lines = repo.text(rel).split("\n")
+        rows = [(ln, tx, role(tx, name)) for ln, tx in hits]
+        strong = [r for r in rows if r[2] in STRONG]
+        if rel in dfiles and (decl_files is not None or not strong): continue   # a file that only declares it needs no check; with --decl the user already knows
+        m = repo.module(rel)
+        in_mod = m in dmods or any(dm in repo.reach.get(m, ()) for dm in dmods)
+        pk = repo.package(rel); src = repo.text(rel)
+        near = pk in dpkgs or any(re.search(r"^import\s+" + re.escape(p) + r"[.\w]*", src, re.M) for p in dpkgs if p)
+        tier = 1 if (strong and in_mod and near) else 2 if (strong and in_mod) else 3
+        tiers[tier][rel] = [{"line": ln, "to": call_range(lines, ln)[1], "role": r, "text": tx.strip()[:160]} for ln, tx, r in (strong or rows)]
+    return {"name": name, "declarations": decls, "tiers": tiers, "rg_files": len(byfile),
+            "rg_lines": sum(len(v) for v in byfile.values())}
+
+
+def render(res, show_all):
+    o = [f"{res['name']}  declared: " + ("; ".join(f"{f}:{ln}" for f, ln in res["declarations"]) or "not found in non-test .kt")]
+    t1, t2, t3 = (res["tiers"][k] for k in (1, 2, 3))
+    o.append(f"TIER 1: check these ({len(t1)} files). rg found {res['rg_files']} files, {res['rg_lines']} lines.")
+    for rel, ls in sorted(t1.items()):
+        o.append(rel)
+        for r in ls: o.append(f"  {r['line']}" + (f"-{r['to']}" if r["to"] > r["line"] else "") + f": {r['text']}")
+    for k, t, label in ((2, t2, "TIER 2: strong match, outside the declaring package or its imports"), (3, t3, "TIER 3: weak match or unreachable module")):
+        if show_all:
+            o.append(f"{label} ({len(t)} files)")
+            for rel, ls in sorted(t.items()):
+                o.append(rel)
+                for r in ls[:5]: o.append(f"  {r['line']}: {r['text']}")
+        else:
+            o.append(f"hidden: tier {k} has {len(t)} files (use --all to list them)")
+    return "\n".join(o)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("name"); ap.add_argument("--repo", default="."); ap.add_argument("--decl", action="append")
+    ap.add_argument("--all", action="store_true"); ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(); repo = Repo(a.repo)
+    res = recommend(repo, a.name, set(a.decl) if a.decl else None)
+    print(json.dumps(res, ensure_ascii=False) if a.json else render(res, a.all))
+
+
+if __name__ == "__main__": main()

moru_narrow-26.45.0/moru_narrow/typescript.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""moru-narrow for TypeScript (v3: two-hop wrapper rule + uses inside the declaring file): recommend the files and lines to check after `rg -w <name>`, without missing any.
+
+Static, no model calls, standard library only. Filters only DEMOTE files into tiers; `--all` lists everything rg found.
+Tier 1 = a strong use/import AND the file imports the declaring file (directly or through re-exporting barrel files).
+
+  moru-narrow <Name> [--repo DIR] [--decl FILE] [--all] [--json]
+"""
+import argparse, json, os, re, subprocess
+from pathlib import Path
+
+STRONG = ("use", "import")
+TEST = re.compile(r"(\.test\.|\.spec\.|/__tests__/|/__mocks__/)")
+EXTS = (".ts", ".tsx", ".mts")
+FROM = re.compile(r"""(?:import|export)\s[^;'"]*?\bfrom\s*['"]([^'"]+)['"]""", re.S)
+BARE = re.compile(r"""\bimport\s*['"]([^'"]+)['"]""")
+DYN = re.compile(r"""(?:\bimport|\brequire)\s*\(\s*['"]([^'"]+)['"]\s*\)""")
+REEXPORT = re.compile(r"""\bexport\s+(?:type\s+)?(?:\*(?:\s+as\s+\w+)?|\{[^}]*\})\s*from\s*['"]([^'"]+)['"]""", re.S)
+
+
+def is_test(rel): return bool(TEST.search("/" + rel))
+
+
+class Repo:
+    def __init__(self, root):
+        self.root = Path(root).resolve(); self.src = {}; self._imp = {}; self._rex = {}
+        self.aliases = self._load_aliases()
+
+    def _load_aliases(self):
+        out = []
+        cfg = self.root / "tsconfig.json"
+        if cfg.exists():
+            raw = re.sub(r'("(?:\\.|[^"\\])*")|//[^\n]*|/\*.*?\*/', lambda m: m.group(1) or "", cfg.read_text(errors="ignore"), flags=re.S)
+            raw = re.sub(r",(\s*[}\]])", r"\1", raw)
+            try:
+                co = json.loads(raw).get("compilerOptions", {}); base = co.get("baseUrl", ".")
+                for k, v in (co.get("paths") or {}).items():
+                    if v: out.append((k.rstrip("*"), (Path(base) / v[0].rstrip("*")).as_posix().lstrip("./")))
+            except ValueError:
+                pass
+        return out
+
+    def text(self, rel):
+        if rel not in self.src: self.src[rel] = (self.root / rel).read_text(errors="ignore")
+        return self.src[rel]
+
+    def resolve(self, frm, spec):
+        cands = []
+        if spec.startswith("."): cands.append(os.path.normpath(Path(frm).parent / spec))
+        else:
+            for pre, tgt in self.aliases:
+                if spec.startswith(pre): cands.append(os.path.normpath(Path(tgt) / spec[len(pre):]))
+        for c in cands:
+            c = str(Path(c))
+            for suffix in ("", *EXTS, ".d.ts", "/index.ts", "/index.tsx"):
+                p = c + suffix
+                if p.endswith(EXTS) and (self.root / p).is_file(): return p
+        return None
+
+    def imports(self, rel):
+        if rel not in self._imp:
+            t = self.text(rel); specs = set(FROM.findall(t)) | set(BARE.findall(t)) | set(DYN.findall(t))
+            self._imp[rel] = {r for r in (self.resolve(rel, s) for s in specs) if r}
+        return self._imp[rel]
+
+    def reexports(self, rel):
+        if rel not in self._rex:
+            self._rex[rel] = {r for r in (self.resolve(rel, s) for s in REEXPORT.findall(self.text(rel))) if r}
+        return self._rex[rel]
+
+    def providers(self, decl, files):
+        """The declaring file plus every file that re-exports it, transitively."""
+        prov, grew = {decl}, True
+        while grew:
+            grew = False
+            for f in files:
+                if f not in prov and self.reexports(f) & prov: prov.add(f); grew = True
+        return prov
+
+
+def role(line, name):
+    s = line.strip()
+    if s.startswith(("//", "*", "/*")): return "comment"
+    if re.search(rf"\b(?:function\s*\*?|class|interface|type|enum)\s+{name}\b", s) or re.search(rf"\b(?:const|let|var)\s+{name}\b", s):
+        return "declaration"
+    if re.match(r"(?:import|export)\b", s) and (re.search(r"\bfrom\b", s) or s.endswith(("{", ","))):
+        return "import" if re.search(rf"\b{name}\b", s.split("from")[0]) else "import-other"
+    if re.search(rf"""(?<=['"`]){name}(?=['"`])""", s) and not re.search(rf"""(?<![\w'"`.]){name}(?![\w'"`])""", s): return "string"
+    if re.match(rf"{name}\s*\??:(?!:)", s) or re.search(rf"[{{,(]\s*{name}\s*\??:(?!:)", s): return "named-arg"
+    return "use"
+
+
+def call_range(lines, i):
+    """1-based line i; extend to the closing paren (or the end of a JSX opening tag) that starts there (max 40 lines)."""
+    depth, seen = 0, False
+    for j in range(i - 1, min(len(lines), i + 39)):
+        for ch in lines[j]:
+            if ch == "(": depth += 1; seen = True
+            elif ch == ")": depth -= 1
+        if seen and depth <= 0: return i, j + 1
+        if not seen and j > i - 1: break
+    if re.search(r"<\w", lines[i - 1]) and ">" not in lines[i - 1].replace("=>", ""):
+        for j in range(i, min(len(lines), i + 39)):
+            if ">" in lines[j].replace("=>", ""): return i, j + 1
+    return i, i
+
+
+def rg_hits(repo, name):
+    out = subprocess.run(["rg", "-nw", "-g", "*.ts", "-g", "*.tsx", "-g", "*.mts", "-g", "!node_modules", "-g", "!.next", "--", name, "."],
+                         cwd=repo.root, capture_output=True, text=True).stdout.splitlines()
+    byfile = {}
+    for l in out:
+        m = re.match(r"\./(.+?\.(?:ts|tsx|mts)):(\d+):(.*)", l)
+        if m and not is_test(m.group(1)): byfile.setdefault(m.group(1), []).append((int(m.group(2)), m.group(3)))
+    return byfile
+
+
+def recommend(repo, name, decl_files=None):
+    byfile = rg_hits(repo, name)
+    decls = []
+    for rel, hits in byfile.items():
+        for ln, tx in hits:
+            if role(tx, name) == "declaration" and (decl_files is None or rel in decl_files): decls.append((rel, ln))
+    if decl_files: decls = [(f, next((ln for ln, tx in byfile.get(f, []) if role(tx, name) == "declaration"), 0)) for f in decl_files]
+    dfiles = {d[0] for d in decls}
+    prov = set()
+    for d in dfiles: prov |= repo.providers(d, _all_files(repo))
+    tiers = {1: {}, 2: {}, 3: {}}
+    for rel, hits in byfile.items():
+        lines = repo.text(rel).split("\n")
+        rows = [(ln, tx, role(tx, name)) for ln, tx in hits]
+        strong = [r for r in rows if r[2] in STRONG]
+        if rel in dfiles and not strong: continue          # v3: a declaring file with other uses is kept, even when --decl names it
+        near = rel in dfiles or bool(repo.imports(rel) & prov)   # v3: calls inside the declaring file are near
+        # v2: a file that imports a wrapper (a file importing the declaring file) and calls `X.name` is also near
+        if not near and strong and any(re.search(rf"\.{re.escape(name)}\b", r[1]) for r in strong):
+            near = any(repo.imports(g) & prov for g in repo.imports(rel))
+        tier = 1 if (strong and near) else 2 if strong else 3
+        tiers[tier][rel] = [{"line": ln, "to": call_range(lines, ln)[1], "role": r, "text": tx.strip()[:160]} for ln, tx, r in (strong or rows)]
+    return {"name": name, "declarations": decls, "tiers": tiers, "rg_files": len(byfile),
+            "rg_lines": sum(len(v) for v in byfile.values())}
+
+
+_ALL = {}
+
+
+def _all_files(repo):
+    if repo.root not in _ALL:
+        out = subprocess.run(["rg", "--files", "-g", "*.ts", "-g", "*.tsx", "-g", "*.mts", "-g", "!node_modules", "-g", "!.next"], cwd=repo.root, capture_output=True, text=True).stdout.split()
+        _ALL[repo.root] = [f for f in out if not is_test(f) and "export" in repo.text(f)]
+    return _ALL[repo.root]
+
+
+def render(res, show_all):
+    o = [f"{res['name']}  declared: " + ("; ".join(f"{f}:{ln}" for f, ln in res["declarations"]) or "not found in non-test .ts/.tsx")]
+    t1, t2, t3 = (res["tiers"][k] for k in (1, 2, 3))
+    o.append(f"TIER 1: check these ({len(t1)} files). rg found {res['rg_files']} files, {res['rg_lines']} lines.")
+    for rel, ls in sorted(t1.items()):
+        o.append(rel)
+        for r in ls: o.append(f"  {r['line']}" + (f"-{r['to']}" if r["to"] > r["line"] else "") + f": {r['text']}")
+    for k, t, label in ((2, t2, "TIER 2: strong match in a file that does not import the declaring file"), (3, t3, "TIER 3: weak match (comment, string, key)")):
+        if show_all:
+            o.append(f"{label} ({len(t)} files)")
+            for rel, ls in sorted(t.items()):
+                o.append(rel)
+                for r in ls[:5]: o.append(f"  {r['line']}: {r['text']}")
+        else:
+            o.append(f"hidden: tier {k} has {len(t)} files (use --all to list them)")
+    return "\n".join(o)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("name"); ap.add_argument("--repo", default="."); ap.add_argument("--decl", action="append")
+    ap.add_argument("--all", action="store_true"); ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(); repo = Repo(a.repo)
+    res = recommend(repo, a.name, set(a.decl) if a.decl else None)
+    print(json.dumps(res, ensure_ascii=False) if a.json else render(res, a.all))
+
+
+if __name__ == "__main__": main()

moru_narrow-26.45.0/moru_narrow.egg-info/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: moru-narrow
+Version: 26.45.0
+Summary: Narrow `rg -w <Name>` to the files and lines you must edit after a signature change (Kotlin+Gradle, TypeScript).
+Author: taehwandev
+License: MIT
+Project-URL: Homepage, https://github.com/taehwandev/moru-narrow
+Project-URL: Issues, https://github.com/taehwandev/moru-narrow/issues
+Keywords: ripgrep,rg,refactoring,coding-agent,kotlin,typescript,claude-code,codex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# moru-narrow
+
+**English** | [한국어](README.ko.md)
+
+> **rg tells you every line that mentions a name. moru-narrow tells you which of those lines you must edit.** It keeps every hit; it only changes the order and what is shown first.
+
+`moru-narrow` post-processes `rg -w <Name>` for coding agents and humans. It keeps every hit, ranks them, and prints the
+files and **line ranges** to check first. No index, no database, no model calls, no daemon. Python standard library and
+[ripgrep](https://github.com/BurntSushi/ripgrep) only.
+
+> Scope: **signature changes** (add or change a parameter, then find what breaks). It is not a general `rg` replacement: for renaming a variable, tracing a logic bug or searching a config string, use plain `rg`.
+>
+> Status: alpha / experimental. MIT license. The examples use the `moru-narrow` command (alias `mnarrow`); from a clone, run `python3 -m moru_narrow` instead.
+
+## In short
+
+- **What it does:** after `rg -w name`, it lists the few files and line ranges you must edit, ranked, and hides the rest behind `--all`. Nothing is dropped.
+- **Does it miss files?** Checked against the compiler: in all 217 Kotlin tasks every truth file was listed (rules were partly tuned on them), and 191 of 194 tasks (99.3% of files) on a fresh TypeScript set. The rare misses are files that never mention the name.
+- **Does it help a coding agent?** In 6 test setups the compile success rate never dropped below the baseline. Context tokens fell by 9.8% to 34.5% in five setups; in the sixth (Codex on TypeScript) the change cannot be told apart from noise.
+- **The catch:** the savings appeared only when the agent was also told not to re-run `rg`. Without that sentence, cost went up 10.3% [+0.0003, +0.0009 USD per task] in one test (Kotlin, Haiku, 57 tasks).
+
+```text
+$ moru-narrow getGlobalTheme --repo ./my-next-app
+getGlobalTheme  declared: src/lib/theme-settings.ts:28
+TIER 1: check these (3 files). rg found 4 files, 6 lines.
+src/app/[locale]/(walled)/manage/(protected)/admin/settings/page.tsx
+  5: import { getGlobalTheme, saveGlobalTheme, type ThemeMode } from '@/lib/theme-settings';
+  19-22: getGlobalTheme({ fresh: true }).then(t => {
+...
+hidden: tier 2 has 0 files (use --all to list them)
+```
+
+## Quick start
+
+Needs Python 3.9+ and [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) on your `PATH`. No other dependency. It does not need Moru Core or any other tool.
+
+```bash
+pipx install git+https://github.com/taehwandev/moru-narrow     # or: uv tool install git+https://... / pip install git+https://...
+moru-narrow <Name> --repo /path/to/your/project                # Kotlin+Gradle or TypeScript, auto-detected
+```
+
+Without installing, from a clone: `git clone https://github.com/taehwandev/moru-narrow && cd moru-narrow && python3 -m moru_narrow <Name> --repo ...`.
+
+Not published on PyPI or npm yet. The `pip install git+...` route was tested in a clean virtualenv on macOS with Python 3.9.6; other platforms and Python versions are untested.
+
+## Use with your coding agent
+
+The tool only helps an agent when the agent is told how to use it (see the savings section: without the "do not re-run rg" sentence cost went up). One command registers that instruction:
+
+```bash
+moru-narrow --install                # agent skill in ~/.claude/skills/ (Claude Code) and ~/.agents/skills/ (Codex and other agent-skills tools)
+moru-narrow --install --project      # same, but into ./.claude and ./.agents so your team shares it via git
+moru-narrow --install --agents-md    # no skill support (e.g. Cursor): add a marked block to ./AGENTS.md
+```
+
+Re-running is safe: an existing `SKILL.md` is kept (`--force` overwrites it), and the `AGENTS.md` block is replaced in place without touching your other text. `--target claude|agents` limits the skill install to one location. The installed text is based on the instruction used in the agent tests (worded differently, and extended as noted below):
+
+> When a task changes a function or constructor signature (adds or changes a parameter), run `moru-narrow <Name> --repo <project root>` once and edit the call sites it lists under TIER 1. Do not run `rg` again for the same name. Use `--all` only if the list looks incomplete. For anything else (renames, logic bugs, config strings), or if moru-narrow reports an error or an unsupported language, use plain `rg`.
+
+The exact wording was not the one measured, and the last sentence (use plain `rg` for other tasks and unsupported languages) is new: the tests only contained signature-change tasks and a prompt written for them. Any agent that can run a shell command can also call `moru-narrow` directly.
+
+## Why
+
+Changing a function signature means finding every place that breaks. `rg -w name` finds all of them, plus comments,
+strings, same-named functions in other modules and unrelated files. On a Kotlin monorepo it returned **60 files for a
+change that broke 3 to 4**. An agent then reads all of them.
+
+A code-graph index was the obvious fix. We measured a syntax-level code-graph index on the same Kotlin repo and it did not
+pay off at the agent level: no measurable cost difference with location-only output, and about +45.5% cost when it returned source code (that run also carried MCP connection overhead, so part of the increase is not the graph itself).
+It also needs an index build and a sync after every edit (stale until synced). `moru-narrow` has no build step and no
+staleness, because it runs `rg` live.
+
+## How it works
+
+1. `rg -nw <Name>` collects hits (test files are excluded).
+2. Each line gets a role: `use`, `import`, `override`, `declaration`, `comment`, `string`, `named-arg`, ...
+3. A file is **tier 1** when it has a strong role (`use`/`import`/`override`) **and** can see the declaration:
+   - Kotlin: the module is reachable through Gradle `project()` edges, and the file is in the same package or imports it.
+   - TypeScript: the file imports the declaring file (relative paths and `tsconfig` aliases, through re-exporting
+     barrel files), or imports a wrapper that does and calls `X.name`, or is the declaring file itself.
+4. Everything else is demoted to tier 2/3. **Filters only demote. `--all` always lists everything `rg` found.**
+5. Multi-line calls are returned as ranges (`19-22`), because compilers report errors at argument lines.
+
+```text
+moru-narrow <Name> [--repo DIR] [--decl FILE] [--all] [--json] [--lang kotlin|ts]
+```
+
+Language is auto-detected (`tsconfig.json`, or a Gradle build).
+
+## How to read the numbers
+
+| Term | What it means here |
+| --- | --- |
+| **Truth files** | Production files that stop compiling after we add a required first parameter (`traceId`) to a function. The compiler decides, not us. |
+| **Recall** | Whether the truth files appear in tier 1. The table counts tasks where all of them do (`23/23`); TypeScript rows also give files (`428/431` = 3 truth files were not listed). |
+| **Tier 1** | The files moru-narrow tells you to read first. |
+| **`rg -w` files / lines** | What plain ripgrep returns for the same name. This is the baseline to beat. |
+| **Fresh set** | Candidates drawn after the rules were frozen. Nothing was tuned on them, so they are the fair test. |
+| **Baseline vs. with moru-narrow** (agent tests) | Same coding agent, same task, same prompt. Baseline may use `rg`, `ls` and file reads. The other condition also gets the tool and the sentence "edit from the list, do not re-run rg for the same name". |
+| **Compile pass** | The project compiles after the agent's edit (Kotlin: Gradle, TypeScript: `tsc --noEmit`). TypeScript runs also require that the declaration really gained the parameter, because an agent that changes nothing would otherwise pass. |
+| **Context tokens** | Input tokens the model processed during the whole run, cached ones included. A proxy for how much it read. |
+| **Cost** | API-equivalent price estimate reported by the Claude CLI, not an actual bill. Codex does not report it, shown as n/a. |
+| **`[a, b]` interval** | 95% range from a task-paired bootstrap (10,000 resamples): tasks are resampled and the two conditions are compared on the same task. If the range includes 0, treat the difference as noise. |
+| **tasks x reps** | Number of tasks times repetitions per task. Repetitions of one task are averaged before the comparison. |
+
+## Does it miss files?
+
+Ground truth is the **compiler**: add a required first parameter `traceId: String` / `traceId: string` to a function (or
+Kotlin constructor), compile, and take the production files that fail as the truth.
+
+| Set | Tasks | `rg -w` files / lines | moru-narrow tier 1 files / lines | Tasks with every truth file in tier 1 |
+| --- | ---: | --- | --- | ---: |
+| Kotlin, 23 selected noisy functions | 23 | 60.4 / 139 | 8.8 / 18 | 23/23 |
+| Kotlin, held-out functions | 120 | 68.3 / 281 | 3.3 / 5 | 120/120 |
+| Kotlin, held-out noisy subset (rg >= 20 files and >= 2x the truth) | 57 | 132.9 / 571 | 3.8 / 7 | 57/57 |
+| Kotlin, constructor changes | 74 | 14.9 / 36 | 8.8 / 17 | 74/74 |
+| TypeScript, **fresh** functions (v3 rules frozen first) | 194 | 3.5 / 7 | 2.5 / 6 | 191/194 (files: 428/431, 99.3%) |
+| TypeScript, fresh, noisy functions (rg >= 5 files) | 28 | 9.5 / 20 | 8.2 / 18 | 28/28 (files: 193/193) |
+
+Read these carefully:
+
+- Kotlin rules were adjusted after the first held-out misses (two regex bugs), so the Kotlin sets are **not fully
+  independent**. The TypeScript fresh set is: rules were frozen (sha256 recorded) before it was scored.
+- TypeScript misses that remain are cases where the failing file **never mentions the name** (the type flows through
+  another function). No `rg`-based tool can find those.
+- Line level: error lines inside the recommended ranges were 90% (Kotlin functions), 96% within +-8 lines (Kotlin
+  constructors) and 90% (TypeScript functions). Use ranges as hints, files as the guarantee.
+- The TypeScript compiler truth is built with the TypeScript API in memory against one private Next.js repo; Kotlin on
+  one private Compose Multiplatform repo. Neither repo is published here.
+
+## Does it save an agent anything?
+
+Same task, same prompt template, two conditions, task-paired bootstrap (10,000 resamples, 95% interval). Local logins
+only. Cost is the API-equivalent estimate reported by the CLI.
+
+| Setup | Compile pass (baseline -> with moru-narrow) | Context tokens | Cost |
+| --- | --- | --- | --- |
+| Kotlin, Haiku, 23 tasks x 2 | 46/46 -> 46/46 | **-34.5%** [-107k, -37k] | **-24.2%** |
+| Kotlin, Haiku, 57 tasks x 2 | 112/114 -> 114/114 | **-19.2%** [-36k, -18k] | **-16.4%** |
+| Kotlin, Codex terra, 23 x 2 | 44/46 -> 45/46 | **-14.2%** [-22.8%, -6.2%] | n/a |
+| Kotlin, Codex terra, 57 x 2 | 112/114 -> 114/114 | **-9.8%** [-14.6%, -5.3%] | n/a |
+| TypeScript, Haiku, 28 x 2 | 56/56 -> 56/56 | **-22.2%** [-29.4%, -15.3%] | **-11.1%** [-17.3%, -4.3%] |
+| TypeScript, Codex terra, 28 x 2 | 56/56 -> 56/56 | -6.5% [-13.5%, 0.0%] (touches 0) | n/a |
+
+**The agent instruction matters as much as the tool.** In the first Kotlin experiment the agent got the same list but
+kept re-running `rg` afterwards, and cost went **up** 10.3% (context +12.8%) on the larger Haiku set. Adding one
+sentence, "edit the call sites from this list without re-running rg for the same name; use --all only if the list looks
+incomplete", changed that: with it, `rg` calls per run fell from 2.4 to 0.02 (Kotlin, Codex, 23 tasks) and from 2.8 to 0.5
+(TypeScript, Haiku), and it produced the table above. That revised prompt was written after seeing the first
+results, so treat the savings as exploratory, and ship the instruction together with the tool.
+
+**What we learned the hard way.** The first TypeScript agent run failed 10 more tasks than the baseline (33/44 vs 43/44).
+Every file the compiler flagged was in the list; the miss was calls *inside the declaring file*, which the first
+version hid because a file does not import itself. The offline truth had also excluded the declaring file, so the offline
+check could not see it. Fix: v3 keeps those lines in tier 1. Lesson: validate with the real agent loop, not only offline.
+
+## Limits
+
+- Languages: Kotlin + Gradle and TypeScript. Each language needs a small profile (role patterns, how to see a
+  declaration). Dynamic languages need a different ground truth.
+- Verified on **one change shape** (adding a required first parameter) and **one repository per language**.
+- React components are out of scope (a positional first parameter does not exist in JSX).
+- Savings depend on the model. Codex on the TypeScript repo showed no clear reduction (-6.5%, interval touches 0). There
+  `rg` was already precise (3.5 files on average for functions) and the agent ran only ~3 commands per task; we did not test why.
+- Sample sizes are small (28 to 57 tasks, 2 repetitions per task). In the baseline every run passed in TypeScript, so pass rate cannot show an improvement there, only that nothing broke.
+- The agent tests sent private source to the model providers (Anthropic, OpenAI) through the author's own local CLI logins.
+
+## Reproduce
+
+The evaluation harnesses (agent runners, compiler-truth generators, scorers) are not in this repository yet: they carry local paths and private repository details and need a scrub first. `results/` holds the aggregate tables. The method is described above: compiler errors after adding a required first parameter are the ground truth; rules were frozen (hash recorded) before the fresh TypeScript set was scored.
+
+## Versioning
+
+Weekly CalVer `YY.WW.N` (scheme `calver-weekly`), for example `26.45.0`: two-digit year, week number, and a release count that starts at `0` each week and counts published packages. Weeks follow the Korean calendar (Asia/Seoul, Monday-start weeks). Git tags use a `v` prefix (`v26.45.0`); the package metadata omits it. Python normalises a zero-padded week, so week 5 appears as `26.5.0` on PyPI. This is a date-based version, not a compatibility signal: while the tool is alpha, read the commit log before upgrading.
+
+## Status
+
+Alpha. Not on PyPI or npm. No unit tests yet. The ranking was validated against compiler ground truth (see above); `--install` was only checked by hand in a temporary home directory (fresh install, re-run, `--project`, `--agents-md` idempotence). Issues and results from other repositories are welcome.
+
+License: [MIT](LICENSE).

moru_narrow-26.45.0/moru_narrow.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+moru_narrow/__init__.py
+moru_narrow/__main__.py
+moru_narrow/install.py
+moru_narrow/kotlin.py
+moru_narrow/typescript.py
+moru_narrow.egg-info/PKG-INFO
+moru_narrow.egg-info/SOURCES.txt
+moru_narrow.egg-info/dependency_links.txt
+moru_narrow.egg-info/entry_points.txt
+moru_narrow.egg-info/top_level.txt

moru_narrow-26.45.0/moru_narrow.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

moru_narrow-26.45.0/moru_narrow.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mnarrow = moru_narrow.__main__:main
+moru-narrow = moru_narrow.__main__:main

moru_narrow-26.45.0/moru_narrow.egg-info/top_level.txt

@@ -0,0 +1 @@
+moru_narrow

moru_narrow-26.45.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "moru-narrow"
+version = "26.45.0"
+description = "Narrow `rg -w <Name>` to the files and lines you must edit after a signature change (Kotlin+Gradle, TypeScript)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "taehwandev" }]
+keywords = ["ripgrep", "rg", "refactoring", "coding-agent", "kotlin", "typescript", "claude-code", "codex"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development",
+]
+
+[project.urls]
+Homepage = "https://github.com/taehwandev/moru-narrow"
+Issues = "https://github.com/taehwandev/moru-narrow/issues"
+
+[project.scripts]
+moru-narrow = "moru_narrow.__main__:main"
+mnarrow = "moru_narrow.__main__:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["moru_narrow"]

moru_narrow-26.45.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+