mason-context 0.6.0 → 0.8.0

package/dist/mason-mcp.js

@@ -1269,6 +1269,7 @@ async function getReferences(rootDir, targetFiles) {
   const targetSet = new Set(targetFiles);
   const filesToSearch = allSourceFiles.filter((f) => !targetSet.has(f));
   const results = /* @__PURE__ */ new Map();
+  const importLine = /^\s*(import\b|from\b.*\bimport\b|const\b.*=\s*require\(|use\b|#include\b|require\s*\()/;
   const batchSize = 50;
   for (let i = 0; i < filesToSearch.length; i += batchSize) {
     const batch = filesToSearch.slice(i, i + batchSize);
@@ -1279,11 +1280,17 @@ async function getReferences(rootDir, targetFiles) {
             path9.join(rootDir, file),
             "utf-8"
           );
+          const lines = content.split("\n");
           for (const name of searchNames) {
             const regex = new RegExp(`\\b${escapeRegex(name)}\\b`);
-            if (regex.test(content)) {
-              if (!results.has(file)) results.set(file, /* @__PURE__ */ new Set());
-              results.get(file).add(name);
+            if (!regex.test(content)) continue;
+            if (!results.has(file)) {
+              results.set(file, { matches: /* @__PURE__ */ new Set(), isImport: false });
+            }
+            const entry = results.get(file);
+            entry.matches.add(name);
+            if (!entry.isImport && lines.some((l) => regex.test(l) && importLine.test(l))) {
+              entry.isImport = true;
             }
           }
         } catch {
@@ -1291,10 +1298,14 @@ async function getReferences(rootDir, targetFiles) {
       })
     );
   }
-  return [...results.entries()].map(([file, matches]) => ({
+  return [...results.entries()].map(([file, { matches, isImport }]) => ({
     file,
-    matches: [...matches]
-  })).sort((a, b) => b.matches.length - a.matches.length);
+    matches: [...matches],
+    kind: isImport ? "import" : "mention"
+  })).sort((a, b) => {
+    if (a.kind !== b.kind) return a.kind === "import" ? -1 : 1;
+    return b.matches.length - a.matches.length;
+  });
 }
 async function getRelatedTests(rootDir, targetFiles) {
   const testPatterns = [
@@ -2320,13 +2331,13 @@ async function exportToConfluence(rootDir, config, options = {}, deps) {
   const confluence = config.confluence;
   if (!confluence) {
     throw new Error(
-      'No Confluence credentials configured. Run "mason set-confluence" first.'
+      "No Confluence credentials configured. Ask your assistant to call mason_set_confluence first."
     );
   }
   const snapshot = await loadSnapshot(rootDir);
   if (!snapshot) {
     throw new Error(
-      'No snapshot found. Run "mason snapshot" first to build the concept map.'
+      "No snapshot found. Build the concept map first (ask your assistant to run mason_init and follow the playbook)."
     );
   }
   const client = deps?.client ?? createConfluenceClient(confluence);
@@ -2931,15 +2942,15 @@ function uninitializedResponse(action) {
 var CLAUDE_MD_SECTION = `<!-- mason:start -->
 ## Mason concept map
 
-This project has a Mason concept map (\`.mason/snapshot.json\`) served over MCP. Use it BEFORE exploring the codebase with grep, glob, or file reads:
+This project has a Mason concept map (\`.mason/snapshot.json\`) and decision store (\`.mason/decisions/\`) served over MCP. Use them BEFORE grep, glob, or file reads:
 
-- Given a task, bug, or change request \u2192 call \`get_context\` with the task text first. One call returns the relevant features, files, tests, blast radius, freshness, and recorded decisions.
-- Asked how something works or where it lives \u2192 call \`get_snapshot\` first.
-- Before editing any file \u2192 call \`get_impact\` for co-change history, references, and related tests.
-- Learned something the code alone can't tell you \u2014 a failed approach ("we tried X, it broke Y"), a deprecation ("don't extend Z"), a workaround and its reason, a convention settled in review \u2192 call \`save_decision\` to record it for the team. Best moments: the end of a debugging session, right after a design choice. Records are git-committed and PR-reviewed like code. Do NOT record anything derivable by reading the code, session trivia, or secrets.
-- Decisions returned by \`get_context\` are constraints \u2014 follow them. If one is marked stale, verify it still holds before relying on it.
+- Task, bug, or change request \u2192 \`get_context\` with the task text: relevant features, files, tests, blast radius, freshness, and decisions in one call.
+- "How does X work / where is Y" \u2192 \`get_snapshot\` first.
+- Before editing any file \u2192 \`get_impact\`.
+- Learned something the code can't tell you (a failed approach, a deprecation, a workaround's reason, a review-settled convention) \u2192 record it with \`save_decision\`. Never record code-derivable facts, session trivia, or secrets.
+- Decisions returned by \`get_context\` are constraints \u2014 follow them; verify any marked stale before relying on it.
 
-Fall back to manual exploration only for details the map doesn't answer.
+Fall back to manual exploration only for what the map doesn't answer.
 <!-- mason:end -->`;
 var SETUP_PLAYBOOK = `You are walking the user through one-time Mason setup for this project. Mason persists a concept map of this codebase so future questions don't re-explore from scratch. The map is built via a Map-Reduce pattern so it covers the WHOLE codebase, not just a sample. Surface each question to the user in plain language and wait for their answer before proceeding.
 
@@ -2994,9 +3005,13 @@ If the credentials are rejected with a 401/403 the tool returns a friendly error
 PHASE 4 \u2014 Assistant instructions (recommended)
 Goal: make sure future assistant sessions actually use the map instead of re-exploring.
 
-Tell the user: "Assistants reliably follow project instructions (CLAUDE.md) but often ignore available tools. Mason works best if I add a short section to this project's CLAUDE.md telling assistants to consult the concept map first. Add it?"
+Tell the user: "Assistants reliably follow project instruction files but often ignore available tools. Mason works best if I add a short section to this project's instruction file telling assistants to consult the concept map first. Add it?"
 On no: skip to Phase 5.
-On yes: append the following section verbatim to the project's CLAUDE.md (create the file with just this section if it doesn't exist; if the \`<!-- mason:start -->\` marker is already present, replace the marked block instead of appending):
+On yes, pick the target file by what the project already uses:
+  - \`AGENTS.md\` exists \u2192 put the section there (it's the tool-agnostic standard). If a \`CLAUDE.md\` also exists and doesn't reference AGENTS.md, add a one-line pointer to it.
+  - only \`CLAUDE.md\` (or \`.claude/CLAUDE.md\`) exists \u2192 put the section there.
+  - neither exists \u2192 create \`CLAUDE.md\` with just the section.
+Append the following section verbatim; if the \`<!-- mason:start -->\` marker is already present in the target file, replace the marked block instead of appending:
 
 ${CLAUDE_MD_SECTION}
 
@@ -3153,7 +3168,7 @@ async function getCodeSamples(dir, count = 15) {
   const rootDir = path14.resolve(dir);
   const samples = await sampleFiles(rootDir, count);
   const output = {
-    note: "These are previews (first ~60 lines). Use get_file_content to read the full file if needed.",
+    note: "These are previews (first ~60 lines). Read the file directly with your own tools to see it in full.",
     files: samples.map((s) => ({
       path: s.path,
       reason: s.reason,
@@ -3260,7 +3275,7 @@ async function getSnapshot(dir) {
   if (!snapshot) {
     return JSON.stringify({
       exists: false,
-      hint: "Project is initialized but no concept map exists yet. Call generate_snapshot, then save_snapshot."
+      hint: "Project is initialized but no concept map exists yet. Run mason_init for the setup playbook (generate_snapshot_batch \u2192 save_partial_snapshot per batch, then reduce_snapshot and save_snapshot)."
     });
   }
   const drift = await computeDrift(rootDir);
@@ -3530,7 +3545,7 @@ async function fullAnalysis(dir) {
     loadSnapshot(rootDir)
   ]);
   const output = {
-    note: "Full project analysis. Code samples are previews (~60 lines). Use get_file_content to read any file in full.",
+    note: "Full project analysis. Code samples are previews (~60 lines). Read files directly with your own tools to see them in full.",
     analysis: JSON.parse(analysis),
     structure: JSON.parse(structure),
     codeSamples: JSON.parse(samples),
@@ -3542,7 +3557,7 @@ async function fullAnalysis(dir) {
       features: snapshot.features,
       flows: snapshot.flows
     };
-    output.note = "Full project analysis with concept map. The concept map shows which files implement each feature and how data flows through them. Use it to jump straight to relevant files instead of exploring. Use get_file_content to read specific files.";
+    output.note = "Full project analysis with concept map. The concept map shows which files implement each feature and how data flows through them. Use it to jump straight to relevant files instead of exploring, then read them directly with your own tools.";
   }
   return JSON.stringify(output, null, 2);
 }
@@ -3932,7 +3947,7 @@ function createMcpServer() {
   const server = new McpServer(
     {
       name: "mason",
-      version: "0.6.0"
+      version: "0.8.0"
     },
     {
       instructions: "Mason maintains a persistent feature-to-file concept map of this codebase so you can skip manual exploration. RULE: when given a task, bug, or change request, call `get_context` with the task text first \u2014 one call returns the relevant features, files, tests, blast radius, and freshness. Before answering ANY question about features, architecture, data flows, or where something lives \u2014 and before any grep/glob/file-read exploration for such a question \u2014 call `get_snapshot` first. One call returns the whole map and replaces 5-10 search round-trips; if it has drifted it says so and self-corrects. Likewise call `get_impact` BEFORE editing or refactoring a file (git co-change history + references + related tests \u2014 signals you cannot get from reading the file itself), and `mason_check_drift` to verify the map is fresh in long sessions. When you learn something the code alone can't tell you \u2014 a failed approach, a deprecation, a workaround's reason, a review-settled convention \u2014 record it with `save_decision` so the whole team's assistants inherit it; `get_context` returns matching decisions as constraints. If `get_snapshot` reports no snapshot exists, offer to set Mason up: `mason_init` returns a setup playbook (a Map-Reduce loop of `generate_snapshot_batch` + `save_partial_snapshot`, then `reduce_snapshot` + `save_snapshot`, optionally `mason_set_confluence`, then `mason_complete_init`). `full_analysis`, `analyze_project`, and `get_code_samples` are read-only diagnostics for unmapped projects and never need init. Mason has no CLI; everything happens through these tools."