pi-fovea 0.1.0 → 0.1.2

package/README.md

@@ -132,6 +132,8 @@ Drop `.fovea/rules.json` in a repo to extend anchor detection beyond the built-i
 
 Changing the rules file invalidates **only** the anchor extraction cache — green-node reuse one level up.
 
+A rule may additionally declare `prefixPattern` (e.g. NestJS `@Controller('api/airports')`) so per-method paths like `@Get('search')` compose into the full router-visible anchor `GET /api/airports/search` — see `ts-http-decorator*` in `src/core/anchors.ts`.
+
 ## How the graph is joined
 
 - **imports / contains / inherits / tests** — outline-derived; call edges specificity-tiered, with language builtins and log/test entry points warded off

package/media/cover.svg

@@ -0,0 +1,46 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1100" height="330" viewBox="0 0 1100 330">
+  <defs>
+    <radialGradient id="fovea" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#ffb454" stop-opacity="0.95"/>
+      <stop offset="18%" stop-color="#ff7a3d" stop-opacity="0.75"/>
+      <stop offset="40%" stop-color="#b3452e" stop-opacity="0.35"/>
+      <stop offset="100%" stop-color="#0a0e14" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="edge" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#2a3441" stop-opacity="0.2"/>
+      <stop offset="0.5" stop-color="#ffb454" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#2a3441" stop-opacity="0.2"/>
+    </linearGradient>
+  </defs>
+  <rect width="1100" height="330" fill="#0a0e14"/>
+  <g opacity="0.55">
+    <line x1="60" y1="258" x2="550" y2="165" stroke="url(#edge)" stroke-width="1.4"/>
+    <line x1="140" y1="88" x2="550" y2="165" stroke="url(#edge)" stroke-width="1"/>
+    <line x1="260" y1="298" x2="550" y2="165" stroke="url(#edge)" stroke-width="1.2"/>
+    <line x1="330" y1="56" x2="550" y2="165" stroke="url(#edge)" stroke-width="1"/>
+    <line x1="770" y1="66" x2="550" y2="165" stroke="url(#edge)" stroke-width="1.1"/>
+    <line x1="830" y1="274" x2="550" y2="165" stroke="url(#edge)" stroke-width="1.4"/>
+    <line x1="980" y1="130" x2="550" y2="165" stroke="url(#edge)" stroke-width="1"/>
+    <line x1="1030" y1="248" x2="550" y2="165" stroke="url(#edge)" stroke-width="0.9"/>
+    <line x1="430" y1="300" x2="550" y2="165" stroke="url(#edge)" stroke-width="0.9"/>
+    <line x1="205" y1="180" x2="550" y2="165" stroke="url(#edge)" stroke-width="1.3"/>
+  </g>
+  <circle cx="550" cy="165" r="150" fill="url(#fovea)"/>
+  <g fill="#39424f">
+    <circle cx="60" cy="258" r="4.5"/><circle cx="140" cy="88" r="4"/><circle cx="260" cy="298" r="4.5"/>
+    <circle cx="330" cy="56" r="4"/><circle cx="770" cy="66" r="4"/><circle cx="830" cy="274" r="4.5"/>
+    <circle cx="980" cy="130" r="4"/><circle cx="1030" cy="248" r="4"/><circle cx="430" cy="300" r="4"/>
+    <circle cx="205" cy="180" r="4.5"/>
+  </g>
+  <g fill="#ffb454">
+    <circle cx="550" cy="165" r="7"/>
+    <circle cx="512" cy="137" r="4"/><circle cx="588" cy="142" r="4"/><circle cx="600" cy="192" r="4.5"/>
+    <circle cx="498" cy="193" r="4"/><circle cx="556" cy="108" r="3.6"/><circle cx="534" cy="216" r="3.4"/>
+  </g>
+  <g fill="none" stroke="#ffb454" stroke-opacity="0.85">
+    <circle cx="550" cy="165" r="26" stroke-width="2"/>
+    <circle cx="550" cy="165" r="52" stroke-opacity="0.5" stroke-width="1.4"/>
+    <circle cx="550" cy="165" r="84" stroke-opacity="0.28" stroke-width="1.1" stroke-dasharray="3 6"/>
+    <circle cx="550" cy="165" r="120" stroke-opacity="0.14" stroke-width="1" stroke-dasharray="2 8"/>
+  </g>
+</svg>

package/package.json

@@ -1,20 +1,50 @@
 {
   "name": "pi-fovea",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",
-  "engines": { "node": ">=20" },
-  "pi": { "extensions": ["./src/index.ts"] },
-  "exports": { "./ops": "./src/core/ops.ts" },
-  "files": ["src", "cli.ts", "README.md", "LICENSE"],
-  "bin": { "fovea": "cli.ts" },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "bench": "tsx scripts/bench.ts",
-    "fovea": "tsx cli.ts",
-    "check": "pnpm run typecheck && pnpm run test"
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "monotykamary",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/pi-fovea.git"
+  },
+  "homepage": "https://github.com/monotykamary/pi-fovea#readme",
+  "bugs": "https://github.com/monotykamary/pi-fovea/issues",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "repo-map",
+    "code-graph",
+    "heat-diffusion",
+    "progressive-disclosure",
+    "context-engineering",
+    "agents"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/monotykamary/pi-fovea/main/media/cover.svg"
+  },
+  "exports": {
+    "./ops": "./src/core/ops.ts"
+  },
+  "files": [
+    "src",
+    "cli.ts",
+    "media",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "fovea": "cli.ts"
   },
   "dependencies": {
     "typebox": "^1.0.76"
@@ -30,5 +60,12 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.80.6",
     "@earendil-works/pi-tui": ">=0.80.6"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "bench": "tsx scripts/bench.ts",
+    "fovea": "tsx cli.ts",
+    "check": "pnpm run typecheck && pnpm run test"
   }
-}
+}

package/src/core/anchors.ts

@@ -7,7 +7,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join as joinPath } from "node:path";
-import { groupByLang, patternRun } from "./astgrep.js";
+import { groupByLang, patternRun, patternRunAll } from "./astgrep.js";
 import { PATH_TOKEN_RE } from "./extract.js";
 import { classifyLiteral, normalizeLiteral } from "./join.js";
 import type { Anchor } from "./types.js";
@@ -18,6 +18,12 @@ export interface AnchorRule {
   pattern: string;
   methods: string; // regex tested against the captured method metavar
   kind: string;
+  /**
+   * Optional class-level prefix patterns (e.g. NestJS '@Controller("api/x")').
+   * Their $P captures are collected per file; a matched route path is composed
+   * prefix + suffix so the anchor id is the full router-visible path.
+   */
+  prefixPattern?: string[];
 }
 
 const PLACEHOLDER_ONLY = /^(:[A-Za-z_]\w*|\{[A-Za-z_]\w*\})$/;
@@ -53,6 +59,16 @@ export const DEFAULT_PACK: AnchorRule[] = [
     pattern: '@$M("$P")',
     methods: "^(?i:get|post|put|delete|patch|options|head)$",
     kind: "route",
+    prefixPattern: ['@Controller("$P")', "@Controller('$P')"],
+  },
+  {
+    // Single-quotes dominate real NestJS codebases (NOMAD, starters, docs).
+    id: "ts-http-decorator-singlequote",
+    langs: ["TypeScript", "Tsx"],
+    pattern: "@$M('$P')",
+    methods: "^(?i:get|post|put|delete|patch|options|head)$",
+    kind: "route",
+    prefixPattern: ['@Controller("$P")', "@Controller('$P')"],
   },
   {
     id: "python-decorator-route",
@@ -86,6 +102,14 @@ export const DEFAULT_PACK: AnchorRule[] = [
 
 export interface AnchorDraft extends Anchor {}
 
+// NestJS mounts every controller at the router root, so the joined path is
+// always slash-rooted regardless of how each framework writes the pieces.
+const joinRoute = (prefix: string, child: string): string => {
+  const p = prefix.replace(/^\/+|\/+$/g, "");
+  const c = child.replace(/^\/+|\/+$/g, "");
+  return c ? `/${[p, c].filter(Boolean).join("/")}` : `/${p}`;
+};
+
 export const extractAnchors = (
   files: string[],
   cwd: string,
@@ -99,15 +123,23 @@ export const extractAnchors = (
     for (const lang of rule.langs) {
       const langFiles = byLang.get(lang);
       if (!langFiles?.length) continue;
+      const prefixes = new Map<string, string>(); // file -> @Controller prefix
+      if (rule.prefixPattern?.length) {
+        for (const pm of patternRunAll(rule.prefixPattern, lang, langFiles, cwd)) {
+          const p = pm.single.P?.trim();
+          if (p !== undefined && !prefixes.has(pm.file)) prefixes.set(pm.file, p);
+        }
+      }
       for (const m of patternRun(rule.pattern, lang, langFiles, cwd)) {
         const method = m.single.M;
         const path = m.single.P;
         if (!method || !path || !methodRe.test(method)) continue;
-        const raw = path.trim();
+        const prefix = prefixes.get(m.file);
+        const raw = prefix !== undefined && prefix !== "" ? joinRoute(prefix, path.trim()) : path.trim();
         // $R.$M(...) also matches Map.get("key")-style data access; only real
         // paths (or router-relative placeholders like ":id") may anchor.
         if (!PATH_TOKEN_RE.test(raw) && !PLACEHOLDER_ONLY.test(raw)) continue;
-        const norm = normalizeLiteral(path, "path");
+        const norm = normalizeLiteral(raw, "path");
         const httpMethod = method.toUpperCase() === "ROUTE" || method.toLowerCase() === "route" || method.toLowerCase() === "use" || method.toLowerCase() === "any"
           ? method.toUpperCase()
           : method.toUpperCase();

package/src/core/build.ts

@@ -25,7 +25,7 @@ export interface FileFacts {
   anchors: AnchorDraft[];
 }
 
-const CACHE_VERSION = 3; // bump when extractor semantics change
+const CACHE_VERSION = 4; // bump when extractor semantics change
 const IGNORE_DIRS = new Set([".git", "node_modules", "dist", "vendor", ".venv", "venv", "target", "coverage", ".next", "build", "__pycache__", ".pi", ".pi-fovea", "deps", "_build", ".tox", "Pods"]);
 const MAX_FILES = 24000;
 // Generated dependency manifests are enormous and carry no first-class routes.

package/src/core/ops.ts

@@ -90,9 +90,25 @@ export const resolveSeeds = (state: RepoState, query: string): SeedResolution =>
   const terms = q.split(/\s+/).filter((t) => t.length > 1);
 
   // Literal route: treat the query itself as a join token (path/env/word).
-  if (classifyLiteral(q)) {
-    for (const occ of state.joinIndex.byKey.get(normalizeLiteral(q, classifyLiteral(q)!))?.occ ?? []) {
-      bump(occ.node, 1);
+  const cls = classifyLiteral(q);
+  if (cls) {
+    const norm = normalizeLiteral(q, cls);
+    for (const occ of state.joinIndex.byKey.get(norm)?.occ ?? []) bump(occ.node, 1);
+    if (cls === "path") {
+      // Route-prefix queries ("/api/airports") seed everything mounted below
+      // them — the query is rarely a literal in code, which is the point: the
+      // model shouldn't have to guess the full route string to look at it.
+      const under = `${norm}/`;
+      for (const [key, bucket] of state.joinIndex.byKey) {
+        if (bucket.cls !== "path" || !key.startsWith(under)) continue;
+        for (const occ of bucket.occ) bump(occ.node, 0.8);
+      }
+      // Anchors whose route sits under the query get seeded directly.
+      state.graph.nodes.forEach((n, i) => {
+        if (n.kind !== "anchor") return;
+        const route = n.name.slice(n.name.indexOf(" ") + 1);
+        if (route === norm || route.startsWith(under)) bump(i, 0.9);
+      });
     }
   }