claude-code-memory-explorer 0.11.1 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-memory-explorer",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Memory explorer dashboard for Claude Code",
   "main": "server.js",
   "bin": {

package/public/app.js

@@ -1055,11 +1055,7 @@ async function refreshAnalysis() {
     computeTreeHealth(st);
     renderTree();
     if (isNew && !healthViewOpen && selectedFileId) renderPreview();
-    const el = document.getElementById('analysisSection');
-    if (el) {
-      el.innerHTML = renderAnalysis(st);
-      applyScopeIndeterminate(el);
-    }
+    rerenderAnalysis(st);
   }
   lastPollKey = pollKey;
   clearTimeout(analysisPollTimer);
@@ -1072,11 +1068,16 @@ async function refreshAnalysis() {
 
 // Re-render from the cached state — used by scope/filter/dismiss handlers so a
 // checkbox click never triggers a server round-trip.
-function rerenderAnalysis() {
+function rerenderAnalysis(st = lastAnalysisSt) {
   const el = document.getElementById('analysisSection');
-  if (!el || !lastAnalysisSt) return;
-  el.innerHTML = renderAnalysis(lastAnalysisSt);
+  if (!el || !st) return;
+  // The scope tree is the scroll container; innerHTML replaces it, which would
+  // snap a group toggle deep in the list back to the top of the panel.
+  const scroll = el.querySelector('.scope-tree')?.scrollTop || 0;
+  el.innerHTML = renderAnalysis(st);
   applyScopeIndeterminate(el);
+  const tree = el.querySelector('.scope-tree');
+  if (tree) tree.scrollTop = scroll;
 }
 
 // `indeterminate` is a DOM property, not an attribute — set it after every innerHTML render.
@@ -1216,9 +1217,25 @@ function memoryDirPath() {
   return idx ? idx.path.replace(/[\\/][^\\/]+$/, '') : null;
 }
 
+// Resolve a finding's bare file names to the live stack sources they name, so a
+// prompt can cite real paths instead of guessing a location from `scope`.
+function findingSources(f) {
+  const ids = new Set();
+  for (const name of f.files || []) {
+    for (const id of findingFileIds(name, f.scope)) ids.add(id);
+  }
+  return [...ids].map((id) => stackData.find((s) => s.id === id)).filter((s) => s?.path);
+}
+
 function findingPrompt(f) {
+  const sources = findingSources(f);
+  const paths = sources.map((s) => s.path);
   let header;
-  if (f.scope === 'user') {
+  if (paths.length === 1) {
+    header = `In the Claude Code instruction file at ${paths[0]}, apply this fix:`;
+  } else if (paths.length > 1) {
+    header = 'In the Claude Code instruction files listed below, apply this fix:';
+  } else if (f.scope === 'user') {
     const path = stackData.find((s) => s.id === 'user-claude-md')?.path || '~/.claude/CLAUDE.md';
     header = `In the user-level Claude Code instructions at ${path}, apply this fix:`;
   } else {
@@ -1228,8 +1245,12 @@ function findingPrompt(f) {
       : "In this project's Claude Code auto-memory, apply this fix:";
   }
   const lines = [header, '', `Finding (${f.kind}, ${f.severity}): ${f.title}`, f.detail, '', `Action: ${f.suggestion}`];
-  if ((f.files || []).length) lines.push(`Files: ${f.files.join(', ')}`);
-  if (f.scope !== 'user') lines.push('', 'Update MEMORY.md index lines if files are added, renamed, or removed.');
+  const cited = paths.length ? paths : f.files || [];
+  if (cited.length) lines.push(`Files: ${cited.join(', ')}`);
+  // The index note only applies to auto-memory files; a CLAUDE.md or SKILL.md
+  // fix has no MEMORY.md to keep in sync.
+  const touchesMemory = paths.length ? sources.some((s) => s.scope === 'memory') : f.scope !== 'user';
+  if (touchesMemory) lines.push('', 'Update MEMORY.md index lines if files are added, renamed, or removed.');
   return lines.join('\n');
 }
 

package/server.js

@@ -850,6 +850,25 @@ const RUBRIC_CLAUDE_MD_USER = [
   '- Preferences should carry their why: a bare prohibition gets overridden when inconvenient; a one-clause reason makes it generalize.',
 ].join('\n');
 
+// The server already knows every `@import` a file makes: parseImports() carries the
+// grammar (npm scopes excluded, extension required) and resolveImport() the resolution
+// (~ = home, else relative to the importing file). Handing the reviewer that answer as
+// fact beats shipping it a prose reimplementation it would run differently each time.
+// Hard `@` imports only — markdown links are references, not inlined content.
+function importLines(src) {
+  const lines = [`PATH: ${src.path}`];
+  const resolved = [];
+  const missing = [];
+  for (const imp of parseImports(src.content).imports) {
+    const abs = resolveImport(imp, src.path);
+    if (fs.existsSync(abs)) resolved.push(abs);
+    else missing.push(`${imp} (tried ${abs})`);
+  }
+  if (resolved.length) lines.push(`IMPORTS: ${resolved.join(', ')}`);
+  if (missing.length) lines.push(`MISSING IMPORTS: ${missing.join(', ')}`);
+  return lines;
+}
+
 function buildAnalyzePrompt(memSources, skillSources, agentSources, claudeMdSources, userSrc, userAudited) {
   const fullSkills = skillSources || [];
   const fullAgent = agentSources || [];
@@ -885,8 +904,9 @@ function buildAnalyzePrompt(memSources, skillSources, agentSources, claudeMdSour
   parts.push(
     '',
     'Rules:',
-    `- You are the orchestrator; do not review files yourself. Your working directory is the project root. For every audited file, launch the type-matched reviewer subagent via your Agent tool — "memory-reviewer" for memory and agent-memory files, "skill-reviewer" for skills, "claude-md-reviewer" for project CLAUDE.md files${userAudited ? ', "claude-md-user-reviewer" for the user-level CLAUDE.md' : ''} — all in a single parallel batch of blocking calls (never background/async agents — you must hold your final report until every reviewer has returned). Pass each one only the file name and its full content; the reviewers carry their own criteria and verify claims against the repo${userAudited ? ' (the user-level reviewer verifies against the machine, never the repo)' : ''}.`,
+    `- You are the orchestrator; do not review files yourself. Your working directory is the project root. For every audited file, launch the type-matched reviewer subagent via your Agent tool — "memory-reviewer" for memory and agent-memory files, "skill-reviewer" for skills, "claude-md-reviewer" for project CLAUDE.md files${userAudited ? ', "claude-md-user-reviewer" for the user-level CLAUDE.md' : ''} — all in a single parallel batch of blocking calls (never background/async agents — you must hold your final report until every reviewer has returned). Pass each one only the file name, its full content, and — for skills and CLAUDE.md files — the PATH:, IMPORTS:, and MISSING IMPORTS: lines from its block below; the reviewers carry their own criteria and verify claims against the repo${userAudited ? ' (the user-level reviewer verifies against the machine, never the repo)' : ''}.`,
     `- Your own job: merge the reviewers' per-file findings and add the cross-file kinds (duplicate, contradiction, merge, promote${crossScope ? ', override, shadow' : ''}) by comparing the files side by side.`,
+    '- @imports are inlined content: the files on a block\'s IMPORTS: line load as part of that file. Reviewers read them, so treat what they report from an import as belonging to the importing file when you compare files side by side — a rule imported by one file and written out in another is still a duplicate. Imported files are never audited on their own; attribute every finding to the importer.',
     '- Verification is a filter: drop any finding a reviewer\'s claim checks disproved, and never report "likely outdated" for a claim a reviewer confirmed still HOLDS. Record what was checked in the finding\'s "evidence" field (one sentence, internal bookkeeping — it is not shown to the user). Omit "evidence" for judgment-only findings.',
     '- files: the exact file names involved as listed below (e.g. feedback_foo.md, MEMORY.md, or a skill name like my-skill). Bare names only — never append scope markers like "(user)"; scope is carried by the scope field.',
     '- scope: "user" if the finding only cites the user-level CLAUDE.md (demote findings are always "user"); "cross" if it cites both the user-level file and any project-side file (override, shadow, and promote findings are "cross"); "project" for everything else.',
@@ -900,9 +920,12 @@ function buildAnalyzePrompt(memSources, skillSources, agentSources, claudeMdSour
     '',
   );
   if (userAudited) {
-    parts.push('USER CLAUDE.MD (audit this with claude-md-user-reviewer):', `=== FILE (user): ${userSrc.name} ===`, userSrc.content, '');
+    parts.push('USER CLAUDE.MD (audit this with claude-md-user-reviewer):', `=== FILE (user): ${userSrc.name} ===`, ...importLines(userSrc), userSrc.content, '');
   } else {
-    parts.push('GLOBAL CLAUDE.md (reference only, do not audit it):', '<<<', userSrc?.content || '(none)', '>>>', '');
+    parts.push(
+      'GLOBAL CLAUDE.md (reference only, do not audit it):',
+      ...(userSrc ? importLines(userSrc).slice(1).map((l) => `${l} — inlined into the global file; read these before judging a rule missing from it`) : []),
+      '<<<', userSrc?.content || '(none)', '>>>', '');
   }
   if (memSources.length) {
     parts.push('MEMORY FILES:');
@@ -913,7 +936,7 @@ function buildAnalyzePrompt(memSources, skillSources, agentSources, claudeMdSour
   if (fullSkills.length) {
     parts.push('PROJECT SKILLS (audit these):');
     for (const s of fullSkills) {
-      parts.push(`=== SKILL: ${s.name} ===`, s.content, '');
+      parts.push(`=== SKILL: ${s.name} ===`, ...importLines(s), s.content, '');
     }
   }
   if (fullAgent.length) {
@@ -925,7 +948,7 @@ function buildAnalyzePrompt(memSources, skillSources, agentSources, claudeMdSour
   if (fullClaudeMd.length) {
     parts.push('CLAUDE.MD FILES (audit these):');
     for (const s of fullClaudeMd) {
-      parts.push(`=== FILE (${s.scope}): ${s.name} ===`, s.content, '');
+      parts.push(`=== FILE (${s.scope}): ${s.name} ===`, ...importLines(s), s.content, '');
     }
   }
   return parts.join('\n');
@@ -940,6 +963,7 @@ const REVIEWER_COMMON = [
   'You review exactly one file that shapes Claude Code behavior; the parent passes its name and full content.',
   'Verify before judging: for every claim that references the repository in your working directory — a file, directory, command, script, flag, or path — check whether it still holds with your read-only tools. For tools the file expects on the machine, check existence with `command -v` / `which` / `where` (the only Bash commands you may run). Never call something "likely stale" when you can check it.',
   'Also judge whether the content is still needed at all: if the thing it guards against is gone (the tool was removed, the convention is enforced elsewhere, the referenced file no longer exists), say so explicitly.',
+  'A check you could not run is not evidence of absence. If a probe is denied by permissions or errors out, report that claim as UNCHECKED and say why — never turn a failed check into a stale or invalidate finding.',
 ];
 
 // The user reviewer swaps repo verification for machine verification — the working
@@ -948,6 +972,7 @@ const REVIEWER_COMMON_USER = [
   'You review the user-level (global) CLAUDE.md that loads in every session of every project; the parent passes its name and full content.',
   'Verify before judging, against the machine only: check tools the file names with `command -v` / `which` / `where` (the only Bash commands you may run), and check files, skills, or agents it references under ~/.claude with your read tools. NEVER read or judge against the repository in your working directory — it is one arbitrary project and proves nothing about a global rule.',
   'Also judge whether the content is still needed at all: if the tool it references is gone from the machine or the file it points to no longer exists, say so explicitly.',
+  'A check you could not run is not evidence of absence. If a probe is denied by permissions or errors out, report that claim as UNCHECKED and say why — never turn a failed check into a stale or invalidate finding.',
 ];
 
 const REVIEWER_REPORT = [
@@ -956,10 +981,24 @@ const REVIEWER_REPORT = [
   '2. FINDINGS: candidate findings for this file only (kind: stale, invalidate, or quality; severity high/med/low; title; detail; one-sentence fix). An empty list is a valid answer — do not pad.',
 ];
 
+// `@path/to/file.md` in a CLAUDE.md or a skill is an import: Claude Code inlines the
+// target's content where the token sits. A reviewer that judges only the text in front
+// of it reads an import as a dangling reference and never sees the rules the file
+// actually loads. `importLines()` resolves the graph server-side and states it as fact,
+// so the rubric only has to say what an import means. Memory files are excluded: the
+// imports they make are audited as sources in their own right.
+const RUBRIC_IMPORTS = [
+  'Import notation (@path):',
+  '- The IMPORTS: line of your file block lists absolute paths Claude Code inlines into this file at load time. Read each one and judge its content against every criterion above as part of this file — including imports of imports. Duplication between the file and its own import, contradictions across its imports, and bloat pulled in through an import all count against the importing file.',
+  '- An @path token is an import, never a broken link or an unexplained reference: do not flag the pointer itself as vague or undefined. Anything on the MISSING IMPORTS: line resolves to nothing, and is the only missing-import finding to report (kind: stale).',
+].join('\n');
+
+// `rubric` takes one rubric constant or a list of them, so a reviewer can stack the
+// shared import rubric on top of its per-type one without a second parameter.
 function reviewerAgent(description, rubric, common = REVIEWER_COMMON) {
   return {
     description,
-    prompt: [common.join('\n'), RUBRIC_CORE, rubric, REVIEWER_REPORT.join('\n')].join('\n\n'),
+    prompt: [common.join('\n'), RUBRIC_CORE, ...[].concat(rubric), REVIEWER_REPORT.join('\n')].join('\n\n'),
     // Bash is permission-scoped to command -v / which / where by the spawn's
     // --allowedTools — anything else the reviewer tries is auto-denied in -p mode.
     tools: ['Read', 'Grep', 'Glob', 'Bash'],
@@ -973,15 +1012,15 @@ const ANALYSIS_AGENTS = {
   ),
   'skill-reviewer': reviewerAgent(
     'Reviews and verifies one SKILL.md file against the skill rubric and the repository. One per skill, in parallel.',
-    RUBRIC_SKILL,
+    [RUBRIC_SKILL, RUBRIC_IMPORTS],
   ),
   'claude-md-reviewer': reviewerAgent(
     'Reviews and verifies one CLAUDE.md instruction file against the CLAUDE.md rubric and the repository. One per file, in parallel.',
-    RUBRIC_CLAUDE_MD,
+    [RUBRIC_CLAUDE_MD, RUBRIC_IMPORTS],
   ),
   'claude-md-user-reviewer': reviewerAgent(
     'Reviews and verifies the user-level (global) CLAUDE.md against the user rubric, PATH, and ~/.claude — never against the working repository.',
-    RUBRIC_CLAUDE_MD_USER,
+    [RUBRIC_CLAUDE_MD_USER, RUBRIC_IMPORTS],
     REVIEWER_COMMON_USER,
   ),
 };
@@ -1017,7 +1056,15 @@ function runClaudeAnalysis(prompt, model, cwd) {
       try {
         const envelope = JSON.parse(out);
         if (envelope.is_error) return finish({ ok: false, error: String(envelope.result || 'Claude Code reported an error') });
-        finish({ ok: true, data: envelope.structured_output, costUsd: envelope.total_cost_usd, durationMs: envelope.duration_ms });
+        // A run can exit clean without structured_output (schema retries exhausted,
+        // truncated stdout). Spreading that absence downstream yields an empty
+        // findings list, which the UI cannot tell apart from a genuine all-clear —
+        // so treat a missing payload as a failure rather than as "no problems".
+        const data = envelope.structured_output;
+        if (!data || !Array.isArray(data.findings)) {
+          return finish({ ok: false, error: 'Claude Code returned no structured output — the audit did not complete, so no result is being shown.' });
+        }
+        finish({ ok: true, data, costUsd: envelope.total_cost_usd, durationMs: envelope.duration_ms });
       } catch {
         finish({ ok: false, error: `Claude Code returned an invalid JSON envelope${err ? `: ${err.slice(0, 300)}` : ''}` });
       }