fix: rank files explicitly named in the task into context (#37)

Files named verbatim in the task text (tests/auth.test.ts, server.ts)
never reached contextFiles because test files are excluded from ranking
candidates, so agents only saw them via testRoutes[].relatedFiles.

- extract file-path mentions from the task text and match them against
  repository paths (exact, path-suffix, or mention-suffix with a /
  boundary); ambiguous bare filenames matching more than 5 files are
  ignored
- mentioned files bypass the test/lockfile/benchmark candidate filters
  and score +12 with an inspectable 'explicitly named in the task'
  reason, ranking them high-confidence
- add JavaScript/TypeScript reserved words (async, await, throw, class,
  null, undefined, ...) to the stop list so generic code tokens no
  longer count as content matches
- add an evaluation case locking in explicit-mention ranking

Fixes #22

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: aryamthecodebreaker

benchmarks/cases.json

@@ -22,5 +22,9 @@
   {
     "task": "Improve the contributor setup guide and pull request instructions",
     "expected": ["CONTRIBUTING.md"]
+  },
+  {
+    "task": "packages/core/test/rank.test.ts fails because files explicitly named in the task drop out of context ranking",
+    "expected": ["packages/core/test/rank.test.ts", "packages/core/src/rank.ts"]
   }
 ]

packages/action/dist/index.mjs

@@ -12,19 +12,33 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "and",
   "any",
   "are",
+  "async",
+  "await",
   "been",
   "being",
   "both",
+  "break",
   "but",
   "can",
   "cannot",
+  "case",
+  "catch",
+  "class",
   "const",
+  "continue",
   "could",
+  "debugger",
   "default",
+  "delete",
   "did",
   "doe",
   "does",
   "down",
+  "else",
+  "enum",
+  "extends",
+  "false",
+  "finally",
   "each",
   "even",
   "export",
@@ -41,23 +55,29 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "him",
   "his",
   "how",
+  "implements",
   "import",
   "index",
+  "instanceof",
   "instead",
+  "interface",
   "into",
   "its",
   "just",
+  "let",
   "main",
   "may",
   "might",
   "more",
   "most",
   "must",
   "name",
+  "namespace",
   "new",
   "node",
   "not",
   "now",
+  "null",
   "off",
   "only",
   "other",
@@ -66,15 +86,22 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "over",
   "package",
   "packages",
+  "private",
+  "protected",
+  "public",
+  "readonly",
   "return",
   "run",
   "same",
   "she",
   "should",
   "some",
   "src",
+  "static",
   "still",
   "such",
+  "super",
+  "switch",
   "than",
   "that",
   "the",
@@ -86,11 +113,17 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "they",
   "this",
   "those",
+  "throw",
   "true",
+  "try",
   "type",
+  "typeof",
   "under",
+  "undefined",
   "uses",
+  "var",
   "very",
+  "void",
   "was",
   "were",
   "what",
@@ -103,16 +136,29 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "will",
   "with",
   "would",
+  "yield",
   "you",
   "your"
 ]);
+var FILE_MENTION_PATTERN = /[A-Za-z0-9_@$][A-Za-z0-9_.$/\\-]*\.[A-Za-z][A-Za-z0-9]*/g;
 function extractTaskSignals(input) {
   const tokens = tokenizeText([input.issueText ?? "", extractDiffContentLines(input.diffText ?? "")].join("\n"));
   return {
     tokens,
-    changedFiles: new Set(input.changedFiles ?? [])
+    changedFiles: new Set(input.changedFiles ?? []),
+    fileMentions: extractFileMentions(input.issueText ?? "")
   };
 }
+function extractFileMentions(text) {
+  const mentions = /* @__PURE__ */ new Set();
+  for (const match of text.matchAll(FILE_MENTION_PATTERN)) {
+    const cleaned = match[0].replace(/\\/g, "/").replace(/^\.\.?\//, "");
+    if (cleaned.length >= 4) {
+      mentions.add(cleaned);
+    }
+  }
+  return mentions;
+}
 function extractDiffContentLines(diffText) {
   if (!diffText) {
     return "";
@@ -155,14 +201,16 @@ var DEPLOYMENT_TERMS = [
   "502"
 ];
 var LOCKFILES = /* @__PURE__ */ new Set(["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock"]);
+var MAX_FILES_PER_MENTION = 5;
 function rankContextFiles(repo, input, limit = 8) {
   const signals = extractTaskSignals({
     issueText: input.issueText ?? "",
     diffText: input.diffText ?? "",
     changedFiles: repo.changedFiles
   });
+  const mentionedPaths = matchMentionedPaths(signals.fileMentions, repo.files.map((file) => file.path));
   const taskTargetsEvaluation = hasAny(signals.tokens, ["benchmark", "benchmarks", "evaluation", "evaluate"]);
-  const candidates = repo.files.filter((file) => file.isSource && !file.isTest && !LOCKFILES.has(file.path.split("/").pop() ?? "") && (!file.path.startsWith("benchmarks/") || taskTargetsEvaluation));
+  const candidates = repo.files.filter((file) => mentionedPaths.has(file.path) || file.isSource && !file.isTest && !LOCKFILES.has(file.path.split("/").pop() ?? "") && (!file.path.startsWith("benchmarks/") || taskTargetsEvaluation));
   const contentTokensByPath = new Map(candidates.map((file) => [file.path, tokenizeText(file.textSample)]));
   const commonTokens = findCommonTokens(contentTokensByPath);
   const taskTargetsDocumentation = hasAny(signals.tokens, ["docs", "documentation", "readme", "guide", "copy"]);
@@ -176,6 +224,10 @@ function rankContextFiles(repo, input, limit = 8) {
       score += 20;
       reasons.push("changed file");
     }
+    if (mentionedPaths.has(file.path)) {
+      score += 12;
+      reasons.push("explicitly named in the task");
+    }
     const pathTokens = tokenizePath(file.path);
     const pathOverlap = [...pathTokens].filter((token2) => signals.tokens.has(token2));
     if (pathOverlap.length > 0) {
@@ -234,6 +286,18 @@ function confidenceForScore(score, isChanged) {
 function hasAny(tokens, values) {
   return values.some((value) => tokens.has(value));
 }
+function matchMentionedPaths(mentions, repoPaths) {
+  const matched = /* @__PURE__ */ new Set();
+  for (const mention of mentions) {
+    const matches = repoPaths.filter((path) => path === mention || path.endsWith(`/${mention}`) || mention.endsWith(`/${path}`));
+    if (matches.length > 0 && matches.length <= MAX_FILES_PER_MENTION) {
+      for (const path of matches) {
+        matched.add(path);
+      }
+    }
+  }
+  return matched;
+}
 function findCommonTokens(contentTokensByPath) {
   const fileCount = contentTokensByPath.size;
   if (fileCount < 4) {

packages/core/src/rank.ts

@@ -5,6 +5,7 @@ const DEPLOYMENT_TERMS = [
   "deploy", "deployment", "vercel", "netlify", "docker", "kubernetes", "hosting", "serverless", "production", "404", "500", "502"
 ];
 const LOCKFILES = new Set(["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock"]);
+const MAX_FILES_PER_MENTION = 5;
 
 export function rankContextFiles(
   repo: RepoMap,
@@ -17,12 +18,14 @@ export function rankContextFiles(
     changedFiles: repo.changedFiles
   });
 
+  const mentionedPaths = matchMentionedPaths(signals.fileMentions, repo.files.map((file) => file.path));
   const taskTargetsEvaluation = hasAny(signals.tokens, ["benchmark", "benchmarks", "evaluation", "evaluate"]);
   const candidates = repo.files.filter((file) =>
-    file.isSource &&
-    !file.isTest &&
-    !LOCKFILES.has(file.path.split("/").pop() ?? "") &&
-    (!file.path.startsWith("benchmarks/") || taskTargetsEvaluation)
+    mentionedPaths.has(file.path) ||
+    (file.isSource &&
+      !file.isTest &&
+      !LOCKFILES.has(file.path.split("/").pop() ?? "") &&
+      (!file.path.startsWith("benchmarks/") || taskTargetsEvaluation))
   );
   const contentTokensByPath = new Map(candidates.map((file) => [file.path, tokenizeText(file.textSample)]));
   const commonTokens = findCommonTokens(contentTokensByPath);
@@ -41,6 +44,11 @@ export function rankContextFiles(
         reasons.push("changed file");
       }
 
+      if (mentionedPaths.has(file.path)) {
+        score += 12;
+        reasons.push("explicitly named in the task");
+      }
+
       const pathTokens = tokenizePath(file.path);
       const pathOverlap = [...pathTokens].filter((token) => signals.tokens.has(token));
       if (pathOverlap.length > 0) {
@@ -110,6 +118,23 @@ function hasAny(tokens: Set<string>, values: string[]): boolean {
   return values.some((value) => tokens.has(value));
 }
 
+function matchMentionedPaths(mentions: Set<string>, repoPaths: string[]): Set<string> {
+  const matched = new Set<string>();
+
+  for (const mention of mentions) {
+    const matches = repoPaths.filter(
+      (path) => path === mention || path.endsWith(`/${mention}`) || mention.endsWith(`/${path}`)
+    );
+    if (matches.length > 0 && matches.length <= MAX_FILES_PER_MENTION) {
+      for (const path of matches) {
+        matched.add(path);
+      }
+    }
+  }
+
+  return matched;
+}
+
 function findCommonTokens(contentTokensByPath: Map<string, Set<string>>): Set<string> {
   const fileCount = contentTokensByPath.size;
   if (fileCount < 4) {