@raymondchins/agentmap 0.2.0 → 0.2.2

package/NOTICE

@@ -1,19 +1,24 @@
-agentmap — NOTICE
-=================
+agentmap — Credits & attribution
+================================
 
 agentmap is copyright 2026 Raymond Surya Chin and contributors,
 licensed under the MIT License (see LICENSE).
 
 -------------------------------------------------------------------------------
-Third-party attribution
+Algorithm credit
 -------------------------------------------------------------------------------
 
-The repo-map ranking algorithm in agentmap.mjs — specifically the PageRank-based
-importance scoring and identifier-graph symbol ranking — is ported from Aider
+agentmap's repo-map ranking — personalized PageRank importance scoring and the
+identifier-graph symbol ranking — is an independent reimplementation, in
+JavaScript, of the approach introduced by Aider's repo map
 (https://github.com/Aider-AI/aider) by Paul Gauthier and contributors.
 
-Aider is licensed under the Apache License, Version 2.0. The full text of
-that license is in LICENSE-APACHE in this package.
+No Aider source code is copied or included here: PageRank is a public, textbook
+algorithm, agentmap implements it from scratch (a dependency-free power
+iteration in agentmap.mjs), and Aider itself relies on the networkx library
+rather than hand-written ranking code. This NOTICE is a courtesy credit to the
+project that pioneered applying that ranking approach to a coding-agent repo
+map — not a statement of derivative authorship.
 
-You may obtain a copy of the Apache License at:
-    http://www.apache.org/licenses/LICENSE-2.0
+Aider is licensed under the Apache License, Version 2.0
+(http://www.apache.org/licenses/LICENSE-2.0).

package/README.md

@@ -339,7 +339,7 @@ $ node agentmap.mjs --print | jq '.hubs[0]'
 | `--help` / `-h` | Print a usage block listing every flag and exit 0. |
 | `--version` / `-v` | Print the version from `package.json` and exit 0. |
 | `--json` | **Global modifier.** When present, every command prints exactly one JSON object to stdout (no prose). Shapes vary per command: `--json --hubs` → `{command,fileCount,sha,hubs:[string]}`, `--json --find X` → `{command,query,matches:[{file,name,kind}]}`, `--json --relates X` → `{command,file,pagerank,exports,imports,dependents,related}`, `--json --any X` → `{command,query,kind,…payload}`, etc. Bare `--json` (no query flag) → `{command:"build",fileCount,features,topHub}`. |
-| `--install-hooks` | Copy `hooks/post-commit` into `.git/hooks/` (chmod 0755), ensure `.claude/agentmap.json` is in `.gitignore`, and print the Claude Code `settings.json` `PreToolUse` snippet. Exit 0 on success, stderr + exit 1 on failure. |
+| `--install-hooks` | Copy `hooks/post-commit` into `.git/hooks/` (chmod 0755), ensure `.claude/agentmap.json` is in `.gitignore`, and auto-wire the Claude Code `PreToolUse(Grep)` nudge into `.claude/settings.json` (merge-safe + idempotent). Exit 0 on success, stderr + exit 1 on failure. |
 | `--mcp` | Start agentmap as a **stdio MCP server** so non-Claude-Code agents (Cursor, Cline, any MCP client) can call every flag as a first-class tool. |
 
 **Exit-code contract:** `0` = success / match / help / version; `1` = query returned zero results (`--any`, `--find`, `--relates`, `--feature` with no match); `2` = usage error (missing required arg, unknown flag). Any token starting with `-` that matches no known flag prints an error to stderr and exits 2.
@@ -365,8 +365,9 @@ npx @raymondchins/agentmap --install-hooks
 ```
 
 This copies `hooks/post-commit` into `.git/hooks/`, sets it executable, ensures
-`.claude/agentmap.json` is in `.gitignore`, and prints the `.claude/settings.json`
-snippet for the `PreToolUse` nudge hook (below). Manual alternative:
+`.claude/agentmap.json` is in `.gitignore`, and **auto-wires the `PreToolUse` nudge
+hook into `.claude/settings.json`** (merge-safe + idempotent) so map enforcement is
+on by default — no manual paste. Manual alternative for just the post-commit hook:
 
 ```bash
 # from your repo root
@@ -385,7 +386,9 @@ reuse search, it injects a reminder steering the agent to `agentmap --any` first
 denies the grep, and stays silent for raw-string / Tailwind-class / lowercase-HTML-tag
 sweeps — so it's high-signal, not nagging.
 
-Wire it up in `.claude/settings.json`:
+`--install-hooks` writes this into `.claude/settings.json` for you (merge-safe — it
+preserves existing settings and won't duplicate on re-run). For reference, or to wire
+it by hand:
 
 ```json
 {

package/agentmap.mjs

@@ -5,7 +5,7 @@
 //
 //  A ts-morph code-relationship map for TypeScript/JavaScript repos. Unlike
 //  one-shot "pack the repo into a prompt" tools, this is a QUERYABLE, RANKED
-//  map: PageRank importance (ported from Aider's repo map), Aider-style
+//  map: PageRank importance (approach from Aider's repo map), Aider-style
 //  symbol ranking, a token-budgeted `--map` digest, and a single `--any`
 //  router (file → symbol → feature → live git-grep) — wired into the agent
 //  loop via a post-commit auto-refresh + a PreToolUse hook.
@@ -13,11 +13,18 @@
 //  Near-zero deps (ts-morph only). Runs in the target repo's cwd.
 //  Algorithm credit: Aider's repo map (Apache-2.0) — github.com/Aider-AI/aider
 // ============================================================================
-import { Project, SyntaxKind } from "ts-morph";
-const CallExpression = SyntaxKind.CallExpression;
 import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync, readdirSync, statSync, chmodSync } from "node:fs";
 import { execSync, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+
+// Lazy ts-morph: its ~105ms module init only fires on a COLD rebuild. Warm cache
+// queries (the common case) never construct a Project, so they skip the load
+// entirely (~2x faster warm). createRequire keeps it synchronous — no async to
+// thread through build()/makeProject().
+const _require = createRequire(import.meta.url);
+let _tsm = null;
+const tsMorph = () => (_tsm ??= _require("ts-morph"));
 
 const MAP = ".claude/agentmap.json";
 const SCHEMA_VERSION = 2;
@@ -177,6 +184,7 @@ function identMul(ident, defineCount, mentioned) {
 // else (missing / malformed / solution-style references that index 0 files) fall
 // back to broad source globs so the tool degrades gracefully instead of crashing.
 function makeProject() {
+  const { Project } = tsMorph();
   // skipFileDependencyResolution: ~40% faster build, verified identical edge
   // set (we resolve module specifiers explicitly below, never via the implicit
   // dependency graph). allowJs so .js/.jsx are parsed.
@@ -248,6 +256,8 @@ function makeProject() {
 function build() {
   const t0 = Date.now();
   const project = makeProject();
+  const { SyntaxKind } = tsMorph();
+  const CallExpression = SyntaxKind.CallExpression;
   const cwd = process.cwd().replace(/\\/g, "/");
   const rel = (p) => p.replace(cwd + "/", "");
   const files = {}, dependents = {}, features = {};
@@ -534,14 +544,13 @@ function fileBlock(key, f) {
 
 // ---------------------------------------------------------------------------
 // --install-hooks: copy the package post-commit hook into .git/hooks, ensure
-// .claude/agentmap.json is gitignored, and print the Claude Code PreToolUse
-// snippet (mirrors hooks/INSTALL.md). Throws on any failure so the caller can
-// stderr+exit 1. Resolves the package hooks/ dir relative to THIS script so it
-// works whether agentmap is run locally, via npx, or globally installed.
+// .claude/agentmap.json is gitignored, and auto-wire the Claude Code
+// PreToolUse(Grep) nudge into the project's .claude/settings.json so map
+// enforcement is ON by default (no manual copy-paste). Merge-safe + idempotent.
+// Throws on any failure so the caller can stderr+exit 1.
 // ---------------------------------------------------------------------------
 function installHooks() {
   const src = new URL("./hooks/post-commit", import.meta.url);
-  const nudge = new URL("./hooks/agentmap-nudge.mjs", import.meta.url);
   // The package hooks/ dir must ship alongside agentmap.mjs.
   if (!existsSync(src)) throw new Error(`packaged hook not found at ${src.pathname} (is the hooks/ dir present?)`);
 
@@ -565,14 +574,36 @@ function installHooks() {
     writeFileSync(".gitignore", IGNORE_LINE + "\n");
   }
 
-  // Success report + the ready-to-paste PreToolUse snippet (points node at the
-  // installed nudge — use its absolute path so it resolves from any cwd).
+  // Auto-wire the PreToolUse(Grep) enforcement nudge into the PROJECT settings
+  // (.claude/settings.json) so "the agent is forced to use the map" is ON by
+  // default — not a manual paste. Merge-safe + idempotent: preserves any
+  // existing settings/hooks, never duplicates our entry. Uses a project-relative
+  // command so a committed settings.json stays portable across machines.
+  const NUDGE_CMD = "node node_modules/@raymondchins/agentmap/hooks/agentmap-nudge.mjs";
+  const settingsPath = ".claude/settings.json";
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, "utf8")) || {}; }
+    catch { throw new Error(`${settingsPath} is not valid JSON — fix or remove it, then re-run --install-hooks`); }
+  }
+  settings.hooks ??= {};
+  settings.hooks.PreToolUse ??= [];
+  const alreadyWired = settings.hooks.PreToolUse.some(
+    (e) => Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
+  );
+  if (!alreadyWired) {
+    settings.hooks.PreToolUse.push({ matcher: "Grep", hooks: [{ type: "command", command: NUDGE_CMD }] });
+    mkdirSync(".claude", { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  }
+
+  // Success report.
   console.log(`installed post-commit hook → ${dest}`);
   console.log(ignoredAlready ? `.gitignore already has ${IGNORE_LINE}` : `added ${IGNORE_LINE} to .gitignore`);
-  console.log("\nAdd this to your .claude/settings.json to enable the PreToolUse(Grep) nudge:\n");
-  console.log(JSON.stringify({
-    hooks: { PreToolUse: [{ matcher: "Grep", hooks: [{ type: "command", command: `node ${nudge.pathname}` }] }] },
-  }, null, 2));
+  console.log(alreadyWired
+    ? `${settingsPath} already wires the PreToolUse(Grep) → agentmap nudge — left as-is`
+    : `wired PreToolUse(Grep) → agentmap nudge into ${settingsPath} (map enforcement on by default)`);
+  console.log("\nDone — the map auto-refreshes on commit, and greps are nudged to agentmap first.");
 }
 
 // ---------------------------------------------------------------------------

package/hooks/INSTALL.md

@@ -121,8 +121,10 @@ agentmap --install-hooks
 ```
 
 This copies `hooks/post-commit` to `.git/hooks/post-commit`, chmods it, ensures
-`.claude/agentmap.json` is in `.gitignore`, and prints the Claude Code
-`settings.json` PreToolUse snippet — all in one step.
+`.claude/agentmap.json` is in `.gitignore`, and auto-wires the Claude Code
+`PreToolUse(Grep)` nudge into `.claude/settings.json` (merge-safe — preserves
+existing settings, idempotent on re-run) — enforcement on by default, all in one
+step. No manual paste needed.
 
 **Manual alternative:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raymondchins/agentmap",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "publishConfig": {
     "access": "public"
   },
@@ -14,12 +14,11 @@
     "agentmap.mjs",
     "mcp.mjs",
     "hooks",
-    "LICENSE-APACHE",
     "NOTICE"
   ],
   "scripts": {
     "map": "node agentmap.mjs",
-    "test": "node --test test/"
+    "test": "node --test test/*.test.mjs"
   },
   "engines": {
     "node": ">=18"

package/LICENSE-APACHE

@@ -1,194 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship made available under
-      the License, as indicated by a copyright notice that is included in
-      or attached to the work (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean, as submitted to the Licensor for inclusion
-      in the Work by the copyright owner or by an individual or Legal Entity
-      authorized to submit on behalf of the copyright owner. For the purposes
-      of this definition, "submitted" means any form of electronic, verbal,
-      or written communication sent to the Licensor or its representatives,
-      including but not limited to communication on electronic mailing lists,
-      source code control systems, and issue tracking systems that are managed
-      by, or on behalf of, the Licensor for the purpose of discussing and
-      improving the Work, but excluding communication that is conspicuously
-      marked or designated in writing by the copyright owner as "Not a
-      Contribution."
-
-      "Contributor" shall mean Licensor and any Legal Entity on behalf of
-      whom a Contribution has been received by the Licensor and included
-      within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by the combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a cross-claim
-      or counterclaim in a lawsuit) alleging that the Work or any
-      Contribution embodied within the Work constitutes direct or contributory
-      patent infringement, then any patent licenses granted to You under
-      this License for that Work shall terminate as of the date such
-      litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or Derivative Works
-          a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, You must include a readable copy of the attribution
-          notices contained within such NOTICE file, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own license statement for Your modifications and
-      may provide additional grant of rights to use, reproduce, modify,
-      prepare Derivative Works of, convert to other media types, publicly
-      display, publicly perform, sublicense, and distribute such modifications
-      and Derivative Works as a whole, provided Your use, reproduction,
-      and distribution of the Work otherwise complies with the conditions
-      stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or reproducing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or exemplary damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or all other
-      commercial damages or losses), even if such Contributor has been
-      advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may offer only
-      conditions consistent with this License, provided that You also
-      comply with the terms of this License, and, if applicable, offer
-      insurance and/or a fee for each obligation of benefit to the
-      Derivative Works.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format in question. It may also be
-      printed or read aloud for identification purposes.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.