@mrclrchtr/supi-code-intelligence 2.0.6 → 2.2.0

package/src/analysis/instruction-files.ts

@@ -0,0 +1,194 @@
+// Directory-local instruction file discovery and rendering for code_orientation.
+
+import { readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
+
+export const INSTRUCTION_FILE_LINE_LIMIT = 200;
+
+/** Directory-local instruction file selected for orientation output. */
+export interface InstructionFileMatch {
+  /** Absolute file path. */
+  absolutePath: string;
+  /** Workspace-relative file path. */
+  relativePath: string;
+  /** Absolute containing directory. */
+  directory: string;
+  /** Workspace-relative containing directory. */
+  relativeDirectory: string;
+}
+
+/** Agent-visible instruction file snippet plus metadata for details. */
+export interface RenderedInstructionFile {
+  path: string;
+  directory: string;
+  shownLines: number;
+  totalLines: number;
+  truncated: boolean;
+  content: string;
+}
+
+/** Structured metadata stored in code_orientation details. */
+export interface InstructionFilesMetadata {
+  files: Array<Omit<RenderedInstructionFile, "content">>;
+}
+
+/**
+ * Find configured instruction files for a directory focus.
+ *
+ * Walks from cwd to the focused directory (shallowest first, deepest last),
+ * selecting the first configured file name that exists in each directory.
+ */
+export function findInstructionFilesForDirectory(options: {
+  directory: string;
+  cwd: string;
+  fileNames: string[];
+  nativeContextPaths: Set<string>;
+  surfacedDirectories: Set<string>;
+}): InstructionFileMatch[] {
+  const cwd = path.resolve(options.cwd);
+  const directory = path.resolve(options.directory);
+  const fileNames = options.fileNames.filter((name) => name.trim().length > 0);
+  if (fileNames.length === 0) return [];
+  if (!isDirectoryWithinCwd(directory, cwd)) return [];
+
+  const dirs = collectDirsShallowestFirst(directory, cwd);
+  const matches: InstructionFileMatch[] = [];
+
+  for (const dir of dirs) {
+    if (options.surfacedDirectories.has(dir)) continue;
+    const match = findFirstInstructionFile(dir, cwd, fileNames);
+    if (!match) continue;
+    if (options.nativeContextPaths.has(match.absolutePath)) continue;
+    matches.push(match);
+  }
+
+  return matches;
+}
+
+function isDirectoryWithinCwd(directory: string, cwd: string): boolean {
+  try {
+    return statSync(directory).isDirectory() && isWithinOrEqual(cwd, directory);
+  } catch {
+    return false;
+  }
+}
+
+function collectDirsShallowestFirst(directory: string, cwd: string): string[] {
+  const dirs: string[] = [];
+  let current = directory;
+
+  while (isWithinOrEqual(cwd, current)) {
+    dirs.push(current);
+    if (current === cwd) break;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return dirs.reverse();
+}
+
+function findFirstInstructionFile(
+  dir: string,
+  cwd: string,
+  fileNames: string[],
+): InstructionFileMatch | null {
+  for (const fileName of fileNames) {
+    const candidate = path.join(dir, fileName);
+    if (!isFile(candidate)) continue;
+    return {
+      absolutePath: candidate,
+      relativePath: path.relative(cwd, candidate),
+      directory: dir,
+      relativeDirectory: path.relative(cwd, dir) || ".",
+    };
+  }
+  return null;
+}
+
+/** Render instruction files as a markdown section and structured metadata. */
+export function renderInstructionFiles(
+  files: InstructionFileMatch[],
+  lineLimit = INSTRUCTION_FILE_LINE_LIMIT,
+): { markdown: string; metadata: InstructionFilesMetadata } | null {
+  const rendered = files.map((file) => renderInstructionFile(file, lineLimit)).filter(isRendered);
+  if (rendered.length === 0) return null;
+
+  const lines: string[] = [];
+  lines.push("## Instructions");
+  lines.push("");
+  for (const file of rendered) {
+    lines.push(`### ${file.path}`);
+    lines.push("");
+    lines.push(file.content);
+    if (file.truncated) {
+      lines.push("");
+      lines.push(
+        `_Instruction file truncated to ${file.shownLines} of ${file.totalLines} lines. Use \`read\` on \`${file.path}\` for the full file._`,
+      );
+    }
+    lines.push("");
+  }
+
+  return {
+    markdown: lines.join("\n").trimEnd(),
+    metadata: {
+      files: rendered.map(({ content: _content, ...metadata }) => metadata),
+    },
+  };
+}
+
+function isFile(candidate: string): boolean {
+  try {
+    return statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function renderInstructionFile(
+  file: InstructionFileMatch,
+  lineLimit: number,
+): RenderedInstructionFile | null {
+  try {
+    const content = readFileSync(file.absolutePath, "utf-8").trim();
+    if (!content) return null;
+
+    const lines = content.split("\n");
+    const shown = lines.slice(0, lineLimit);
+    return {
+      path: file.relativePath,
+      directory: file.relativeDirectory,
+      shownLines: shown.length,
+      totalLines: lines.length,
+      truncated: lines.length > shown.length,
+      content: shown.join("\n"),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function isRendered(value: RenderedInstructionFile | null): value is RenderedInstructionFile {
+  return value !== null;
+}
+
+/** Insert instruction markdown after the opening title/summary block of a brief. */
+export function insertInstructionsNearTop(content: string, instructionsMarkdown: string): string {
+  const lines = content.split("\n");
+  const insertAt = findFirstSectionIndexAfterTitle(lines);
+  const before = lines.slice(0, insertAt).join("\n").trimEnd();
+  const after = lines.slice(insertAt).join("\n").trimStart();
+
+  if (!before) return `${instructionsMarkdown}\n\n${after}`.trimEnd();
+  if (!after) return `${before}\n\n${instructionsMarkdown}`.trimEnd();
+  return `${before}\n\n${instructionsMarkdown}\n\n${after}`.trimEnd();
+}
+
+function findFirstSectionIndexAfterTitle(lines: string[]): number {
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) return i;
+  }
+  return lines.length;
+}

package/src/analysis/search/pattern.ts

@@ -64,7 +64,7 @@ export function isStructuredPatternKind(kind: string | undefined): kind is Struc
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: enumeration-interrupted, cap, timeout, and error branches are each necessary
 export async function getStructuredPatternMatches(
   params: StructuredPatternParams,
-  scopePath: string,
+  scopePath: string | readonly string[],
   cwd: string,
   relScope: string,
   structural: StructuralSubstrate,
@@ -143,7 +143,10 @@ interface FileEnumeration {
  * Enumerate all tree-sitter-supported source files in scopePath using rg --files.
  * Returns null if ripgrep is not available.
  */
-function enumerateSourceFiles(scopePath: string, cwd: string): FileEnumeration | null {
+function enumerateSourceFiles(
+  scopePath: string | readonly string[],
+  cwd: string,
+): FileEnumeration | null {
   const extensions = getSupportedExtensions();
   // Strip leading dots — ripgrep -g expects ".ext" without the dot prefix
   const globPattern = `*.{${Array.from(extensions)
@@ -151,18 +154,14 @@ function enumerateSourceFiles(scopePath: string, cwd: string): FileEnumeration |
     .join(",")}}`;
 
   try {
-    const output = execFileSync("rg", ["--files", "-g", globPattern, scopePath], {
+    const output = execFileSync("rg", ["--files", "-g", globPattern, ...scopePathArgs(scopePath)], {
       encoding: "utf-8",
       cwd,
       timeout: 5000,
       stdio: ["pipe", "pipe", "pipe"],
     });
     return {
-      files: output
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0)
-        .sort((a, b) => a.localeCompare(b)),
+      files: normalizeEnumeratedFiles(output),
       interrupted: false,
     };
   } catch (err: unknown) {
@@ -174,11 +173,7 @@ function enumerateSourceFiles(scopePath: string, cwd: string): FileEnumeration |
       const stdout = typeof err.stdout === "string" ? err.stdout : "";
       const wasKilled = (err as { killed?: boolean }).killed === true;
       return {
-        files: stdout
-          .split("\n")
-          .map((line) => line.trim())
-          .filter((line) => line.length > 0)
-          .sort((a, b) => a.localeCompare(b)),
+        files: normalizeEnumeratedFiles(stdout),
         interrupted: wasKilled,
       };
     }
@@ -186,6 +181,22 @@ function enumerateSourceFiles(scopePath: string, cwd: string): FileEnumeration |
   }
 }
 
+function scopePathArgs(scopePath: string | readonly string[]): string[] {
+  const paths = Array.isArray(scopePath) ? scopePath : [scopePath];
+  return paths.length > 0 ? [...paths] : ["."];
+}
+
+function normalizeEnumeratedFiles(output: string): string[] {
+  return [
+    ...new Set(
+      output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0),
+    ),
+  ].sort((a, b) => a.localeCompare(b));
+}
+
 // biome-ignore lint/complexity/useMaxParams: helper takes explicit collection inputs to avoid intermediate objects in the hot path
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: kind-specific tree-sitter matching is clearest as one helper
 async function collectMatchesForFile(

package/src/analysis/search/ripgrep.ts

@@ -47,6 +47,11 @@ export function isInProjectPath(filePath: string, cwd: string): boolean {
 /** Result of resolving a user-provided `scope` value to an absolute path. */
 export type ScopeResolution = { kind: "ok"; path: string } | { kind: "error"; reason: string };
 
+/** Result of resolving a code_find `scope` value to one or more absolute paths. */
+export type ScopeSetResolution =
+  | { kind: "ok"; paths: string[]; display: string | null }
+  | { kind: "error"; reason: string };
+
 /**
  * Resolve a `scope` value to an absolute path using pi scope semantics:
  * - strip leading `@`
@@ -61,6 +66,55 @@ export function resolveScope(scope: string | undefined, cwd: string): ScopeResol
       reason: `Scope accepts a single directory or file path, not multiple: \`${scope}\``,
     };
   }
+  return resolveSingleScope(scope, cwd);
+}
+
+/**
+ * Resolve a code_find scope input to one or more absolute paths.
+ *
+ * `code_find` is intentionally more flexible than other code-intelligence tools:
+ * it accepts `scope: ["docs", "packages"]` and also splits delimiter-separated
+ * strings such as `"docs packages"` only when no exact path by that name exists.
+ */
+export function resolveScopeSet(
+  scope: string | readonly string[] | undefined,
+  cwd: string,
+): ScopeSetResolution {
+  if (scope === undefined) {
+    return { kind: "ok", paths: [cwd], display: null };
+  }
+
+  const labels = typeof scope === "string" ? splitScopeString(scope, cwd) : [...scope];
+  if (labels.length === 0) {
+    return { kind: "error", reason: "Scope must include at least one directory or file path." };
+  }
+
+  const resolved: Array<{ label: string; path: string }> = [];
+  for (const label of labels) {
+    const trimmed = label.trim();
+    if (!trimmed) {
+      return { kind: "error", reason: "Scope must not include empty path entries." };
+    }
+    const single = resolveSingleScope(trimmed, cwd);
+    if (single.kind === "error") return single;
+    resolved.push({ label: trimmed, path: single.path });
+  }
+
+  const byPath = new Map<string, string>();
+  for (const entry of resolved) {
+    if (!byPath.has(entry.path)) byPath.set(entry.path, entry.label);
+  }
+  const paths = [...byPath.keys()];
+  const uniqueLabels = paths.map((p) => byPath.get(p) ?? p);
+
+  return {
+    kind: "ok",
+    paths,
+    display: uniqueLabels.length > 0 ? uniqueLabels.join(", ") : null,
+  };
+}
+
+function resolveSingleScope(scope: string, cwd: string): ScopeResolution {
   const resolved = normalizePath(scope, cwd);
   if (!existsSync(resolved)) {
     return { kind: "error", reason: `Scope path not found: \`${scope}\`` };
@@ -68,6 +122,20 @@ export function resolveScope(scope: string | undefined, cwd: string): ScopeResol
   return { kind: "ok", path: resolved };
 }
 
+function splitScopeString(scope: string, cwd: string): string[] {
+  const trimmed = scope.trim();
+  if (!trimmed) return [];
+
+  const exact = resolveSingleScope(trimmed, cwd);
+  if (exact.kind === "ok") return [trimmed];
+
+  const parts = trimmed
+    .split(/[,;\s]+/)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  return parts.length > 1 ? parts : [trimmed];
+}
+
 /** Escape regex special characters. */
 export function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -152,7 +220,7 @@ export class RipgrepAbortedError extends Error {
  */
 export async function runRipgrep(
   pattern: string,
-  scopePath: string,
+  scopePath: string | readonly string[],
   cwd: string,
   opts?: RipgrepOptions,
 ): Promise<RgMatch[]> {
@@ -166,7 +234,7 @@ export async function runRipgrep(
  */
 export async function runRipgrepDetailed(
   pattern: string,
-  scopePath: string,
+  scopePath: string | readonly string[],
   cwd: string,
   opts?: RipgrepOptions,
 ): Promise<RipgrepRunResult> {
@@ -195,16 +263,16 @@ export async function runRipgrepDetailed(
       };
     case "ok":
     case "nomatch":
-      return { matches: parseRgJson(proc.stdout, filter) };
+      return { matches: dedupeMatches(parseRgJson(proc.stdout, filter)) };
     case "timeout":
       // Timeout: yield any partial stdout matches with no error surfaced — an
       // improvement over the prior execFileSync path, which discarded partial
       // output on timeout (the timeout error lacked a `status`, so the old
       // handleRipgrepError returned an empty match set).
-      return { matches: proc.stdout ? parseRgJson(proc.stdout, filter) : [] };
+      return { matches: proc.stdout ? dedupeMatches(parseRgJson(proc.stdout, filter)) : [] };
     case "error":
       return {
-        matches: proc.stdout ? parseRgJson(proc.stdout, filter) : [],
+        matches: proc.stdout ? dedupeMatches(parseRgJson(proc.stdout, filter)) : [],
         ...(proc.stderr.trim() ? { error: proc.stderr.trim() } : {}),
       };
   }
@@ -212,7 +280,7 @@ export async function runRipgrepDetailed(
 
 function buildRipgrepArgs(
   pattern: string,
-  scopePath: string,
+  scopePath: string | readonly string[],
   opts?: { maxMatches?: number; contextLines?: number; literal?: boolean },
 ): string[] {
   const args = ["--json", "-m", String(opts?.maxMatches ?? 30)];
@@ -222,10 +290,15 @@ function buildRipgrepArgs(
   if (opts?.literal) {
     args.push("-F");
   }
-  args.push("-e", pattern, scopePath);
+  args.push("-e", pattern, ...normalizeScopePathArgs(scopePath));
   return args;
 }
 
+function normalizeScopePathArgs(scopePath: string | readonly string[]): string[] {
+  const paths = Array.isArray(scopePath) ? scopePath : [scopePath];
+  return paths.length > 0 ? [...paths] : ["."];
+}
+
 /** Discriminated result of a single ripgrep process run (see {@link runRgProcess}). */
 type RgProcessResult =
   | { kind: "ok"; stdout: string; stderr: string; status: number }
@@ -432,6 +505,18 @@ function parseRgJson(output: string, filterLowSignal: boolean): RgMatch[] {
   return matches;
 }
 
+function dedupeMatches(matches: RgMatch[]): RgMatch[] {
+  const seen = new Set<string>();
+  const deduped: RgMatch[] = [];
+  for (const match of matches) {
+    const key = `${match.file}\u0000${match.line}\u0000${match.text}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(match);
+  }
+  return deduped;
+}
+
 /**
  * Minimal interface for a reference-like object with a URI and range start.
  * Used by {@link filterOutDeclaration} to avoid coupling to a specific LspRef type.

package/src/app/app.ts

@@ -77,8 +77,9 @@ export function createCodeIntelligenceApp(pi: ExtensionAPI): CodeIntelligenceApp
   pi.on("session_start", (_event, ctx) => {
     const session = manager.getOrCreateSession(ctx.cwd);
 
-    // Check if the branch already contains an overview
+    // Check if the branch already contains an overview and restore branch-local instruction state.
     const branch = ctx.sessionManager.getBranch();
+    session.reconstructInstructionState(branch);
     for (const entry of branch) {
       if (
         entry.type === "custom_message" &&
@@ -90,6 +91,10 @@ export function createCodeIntelligenceApp(pi: ExtensionAPI): CodeIntelligenceApp
     }
   });
 
+  pi.on("session_compact", (_event, ctx) => {
+    manager.getSession(ctx.cwd)?.resetSurfacedInstructionDirs();
+  });
+
   pi.on("session_shutdown", () => {
     // Clear per-session stores before releasing sessions
     for (const session of manager.allSessions()) {

package/src/config.ts

@@ -0,0 +1,42 @@
+// Code Intelligence configuration and settings registration.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
+import { registerDeclarativeSettings } from "@mrclrchtr/supi-core/settings";
+
+const CODE_INTELLIGENCE_SECTION = "code-intelligence";
+
+/** User-facing configuration for the code-intelligence extension. */
+export interface CodeIntelligenceConfig extends Record<string, unknown> {
+  /** Ordered directory-local instruction file names to surface during directory orientation. */
+  instructionFileNames: string[];
+}
+
+/** Default code-intelligence configuration. */
+export const CODE_INTELLIGENCE_DEFAULTS: CodeIntelligenceConfig = {
+  instructionFileNames: ["CLAUDE.md", "AGENTS.md"],
+};
+
+/** Load merged code-intelligence configuration for a workspace. */
+export function loadCodeIntelligenceConfig(cwd: string, homeDir?: string): CodeIntelligenceConfig {
+  return loadSupiConfig(CODE_INTELLIGENCE_SECTION, cwd, CODE_INTELLIGENCE_DEFAULTS, { homeDir });
+}
+
+/** Register code-intelligence settings with the shared SuPi settings registry. */
+export function registerCodeIntelligenceSettings(pi: ExtensionAPI, homeDir?: string): void {
+  registerDeclarativeSettings(pi, {
+    id: CODE_INTELLIGENCE_SECTION,
+    label: "Code Intelligence",
+    section: CODE_INTELLIGENCE_SECTION,
+    defaults: CODE_INTELLIGENCE_DEFAULTS,
+    fields: [
+      {
+        kind: "stringList" as const,
+        key: "instructionFileNames",
+        label: "Instruction File Names",
+        description: "Directory-local instruction file names shown by directory orientation",
+      },
+    ],
+    ...(homeDir ? { homeDir } : {}),
+  });
+}

package/src/extension.ts

@@ -8,6 +8,7 @@ import {
   gatherCoverageEvalInput,
 } from "./analysis/coverage/coverage-warnings.ts";
 import { createCodeIntelligenceApp } from "./app/app.ts";
+import { registerCodeIntelligenceSettings } from "./config.ts";
 import type { WorkspaceCodeIntelligenceSession } from "./session/session.ts";
 import { registerDiagnosticInjectionHandlers } from "./substrate/lsp/diagnostic-injection.ts";
 import { registerLspSessionLifecycle } from "./substrate/lsp/lifecycle.ts";
@@ -38,7 +39,8 @@ export default function codeIntelligenceExtension(
   const tsState = createTsAdapterState();
 
   // ── Substrate wiring ──────────────────────────────────────────────
-  registerLspSettings();
+  registerCodeIntelligenceSettings(pi);
+  registerLspSettings(pi);
   registerLspSessionLifecycle(pi, lspState);
   registerLspAwareToolOverrides(pi, lspState);
   registerDiagnosticInjectionHandlers(pi, lspState);
@@ -64,6 +66,12 @@ export default function codeIntelligenceExtension(
   registerCiStatusCommand(pi);
   registerLspFooterContribution(lspState);
 
+  // ── Native context path capture for instruction-file dedup ─────────
+  pi.on("before_agent_start", (event, ctx) => {
+    const session = app.getSession(ctx.cwd) ?? app.createSession(ctx.cwd);
+    session.captureNativeInstructionPaths(event.systemPromptOptions.contextFiles ?? []);
+  });
+
   // ── Coverage warning emission ─────────────────────────────────────
   pi.on(
     "before_agent_start",