@nerviq/cli 1.27.0 → 1.29.0

package/src/shallow-risk/patterns/agent-config-missing-file.js

@@ -1,11 +1,15 @@
 'use strict';
 
+const path = require('path');
+
 const {
   SHALLOW_RISK_DOC_URL,
   escapeRegExp,
+  findFirstRepoPath,
   getAgentConfigEntries,
   getScannableLines,
   isKnownConventionPath,
+  lineHasExampleContext,
   looksLikeRelativeFileReference,
   normalizeCandidatePath,
   resolveRepoPath,
@@ -13,6 +17,236 @@ const {
 } = require('../shared');
 
 const POINTER_RE = /(?:^|[\s([`'"])(@?(?:\.{1,2}\/)?[A-Za-z0-9._/-]+)(?=$|[\s)\]`'",:;!?])/g;
+const MARKDOWN_LINK_RE = /\[[^\]]+\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const BACKTICK_TOKEN_RE = /`([^`]+)`/g;
+const PLACEHOLDER_PATH_RE = /(?:^|\/)(?:path(?:_to)?|to)(?:\/|$)|(?:^|\/)test_file\.py$|(?:^|\/)path_to_test\.py$|(?:^|\/)module_name\.[A-Za-z0-9._-]+$/i;
+const ENV_POLICY_RE = /\b(?:dotenv|environment variables?|api keys?|secrets?|credential|gitignore|removed\s+\.env|look for\s+\.env|via\s+`?\.env|defaults?\s+to|do not commit)\b/i;
+const OWNERSHIP_CONTEXT_RE = /\b(?:subdirectory|integration|folder|workspace|extension|module|package|component|app|generated file|composition root|entrypoint|directory structure|utility functions|updated in|register feature|build from)s?(?:['’]s)?\b/i;
+const SOFT_REFERENCE_CONTEXT_RE = /\b(?:can be deleted afterwards|quality scale|search result|scrape the web page content)\b/i;
+const ALWAYS_AMBIGUOUS_BASENAMES = new Set([
+  'findings.md',
+  'manifest.json',
+  'progress.md',
+  'quality_scale.yaml',
+  'task_plan.md',
+  'todo.md',
+]);
+
+function repoHasBasename(ctx, basename, state) {
+  if (!basename) {
+    return false;
+  }
+  if (state.basenameCache.has(basename)) {
+    return state.basenameCache.get(basename);
+  }
+
+  const match = findFirstRepoPath(ctx, (_relPath, entryName) => entryName === basename, { maxDepth: 10 });
+  const exists = Boolean(match);
+  state.basenameCache.set(basename, exists);
+  return exists;
+}
+
+function repoHasPathSuffix(ctx, candidate, state) {
+  const normalized = toPosix(candidate || '').replace(/^\.?\//, '');
+  if (!normalized) {
+    return false;
+  }
+  if (state.suffixCache.has(normalized)) {
+    return state.suffixCache.get(normalized);
+  }
+
+  const match = findFirstRepoPath(
+    ctx,
+    (relPath) => {
+      const normalizedPath = toPosix(relPath);
+      return normalizedPath === normalized || normalizedPath.endsWith(`/${normalized}`);
+    },
+    { maxDepth: 10 },
+  );
+  const exists = Boolean(match);
+  state.suffixCache.set(normalized, exists);
+  return exists;
+}
+
+function lineHasEnvPolicyContext(line) {
+  return ENV_POLICY_RE.test(String(line || ''));
+}
+
+function lineHasScopedOwnershipContext(line) {
+  const text = String(line || '');
+  return OWNERSHIP_CONTEXT_RE.test(text) || SOFT_REFERENCE_CONTEXT_RE.test(text) || /<[^>]+>/.test(text);
+}
+
+function extractLineAnchors(line) {
+  const anchors = new Set();
+  const text = String(line || '');
+
+  BACKTICK_TOKEN_RE.lastIndex = 0;
+  let match = BACKTICK_TOKEN_RE.exec(text);
+  while (match) {
+    const rawToken = String(match[1] || '');
+    const token = normalizeCandidatePath(rawToken)
+      .replace(/<[^>]+>/g, '')
+      .replace(/^\/+/, '')
+      .replace(/\/+$/, '');
+    if (!token || !rawToken.includes('/')) {
+      match = BACKTICK_TOKEN_RE.exec(text);
+      continue;
+    }
+    anchors.add(token);
+    match = BACKTICK_TOKEN_RE.exec(text);
+  }
+
+  MARKDOWN_LINK_RE.lastIndex = 0;
+  match = MARKDOWN_LINK_RE.exec(text);
+  while (match) {
+    const rawToken = String(match[1] || '');
+    const token = normalizeCandidatePath(rawToken)
+      .replace(/<[^>]+>/g, '')
+      .replace(/^\/+/, '')
+      .replace(/\/+$/, '');
+    if (!token || !rawToken.includes('/')) {
+      match = MARKDOWN_LINK_RE.exec(text);
+      continue;
+    }
+    anchors.add(token);
+    match = MARKDOWN_LINK_RE.exec(text);
+  }
+
+  return [...anchors];
+}
+
+function anchorDirsForToken(token) {
+  if (!token) {
+    return [];
+  }
+
+  const normalized = normalizeCandidatePath(token)
+    .replace(/<[^>]+>/g, '')
+    .replace(/^\/+/, '')
+    .replace(/\/+$/, '');
+  if (!normalized) {
+    return [];
+  }
+
+  const dirs = new Set();
+  const looksFileLike = looksLikeRelativeFileReference(normalized);
+  const direct = normalized.includes('/')
+    ? (looksFileLike ? path.posix.dirname(normalized) : normalized)
+    : normalized;
+  if (direct && direct !== '.') {
+    dirs.add(direct);
+  }
+
+  const parent = path.posix.dirname(direct || normalized);
+  if (parent && parent !== '.' && parent !== direct) {
+    dirs.add(parent);
+  }
+
+  return [...dirs];
+}
+
+function lineResolvesBareCandidate(ctx, line, candidate, state) {
+  const base = path.posix.basename(candidate);
+  const anchors = extractLineAnchors(line);
+
+  for (const anchor of anchors) {
+    const normalizedAnchor = normalizeCandidatePath(anchor);
+    if (path.posix.basename(normalizedAnchor) === base && (ctx.fileContent(normalizedAnchor) !== null || repoHasPathSuffix(ctx, normalizedAnchor, state))) {
+      return true;
+    }
+
+    for (const dir of anchorDirsForToken(anchor)) {
+      const match = findFirstRepoPath(
+        ctx,
+        (relPath, entryName) => entryName === base && toPosix(relPath).startsWith(`${dir}/`),
+        { maxDepth: 10 },
+      );
+      if (match) {
+        return true;
+      }
+    }
+  }
+
+  if (anchors.length > 0 && repoHasBasename(ctx, base, state)) {
+    return true;
+  }
+
+  if (lineHasScopedOwnershipContext(line) && repoHasBasename(ctx, base, state)) {
+    return true;
+  }
+
+  return false;
+}
+
+function lineHasAnchorContext(line) {
+  return extractLineAnchors(line).length > 0;
+}
+
+function lineResolvesPathSuffix(ctx, line, candidate, state) {
+  if (!candidate || !candidate.includes('/')) {
+    return false;
+  }
+  if (!lineHasAnchorContext(line) && !lineHasScopedOwnershipContext(line)) {
+    return false;
+  }
+  return repoHasPathSuffix(ctx, candidate, state);
+}
+
+function shouldIgnoreCandidate(ctx, line, candidate, state) {
+  const normalized = String(candidate || '');
+  const base = path.posix.basename(normalized);
+  if (!normalized) {
+    return true;
+  }
+  if (PLACEHOLDER_PATH_RE.test(normalized)) {
+    return true;
+  }
+  if (ALWAYS_AMBIGUOUS_BASENAMES.has(base) && repoHasBasename(ctx, base, state)) {
+    return true;
+  }
+  if (SOFT_REFERENCE_CONTEXT_RE.test(String(line || '')) && (base === 'PLAN.md' || base === 'web_scraper.py')) {
+    return true;
+  }
+  if (normalized === '.env' && lineHasEnvPolicyContext(line)) {
+    return true;
+  }
+  if (lineResolvesPathSuffix(ctx, line, normalized, state)) {
+    return true;
+  }
+  if (!normalized.includes('/') && lineResolvesBareCandidate(ctx, line, normalized, state)) {
+    return true;
+  }
+  return false;
+}
+
+function resolveMissingCandidate(ctx, fromFile, candidate) {
+  const isNestedAgentDoc = toPosix(fromFile).includes('/');
+  const prefersRepoRoot = isNestedAgentDoc && !candidate.startsWith('../');
+  const modes = prefersRepoRoot
+    ? ['repo-root', 'relative-to-file']
+    : ['relative-to-file', 'repo-root'];
+
+  let firstMissing = null;
+  for (const mode of modes) {
+    const resolvedPath = resolveRepoPath(ctx, fromFile, candidate, mode);
+    if (!resolvedPath || isKnownConventionPath(resolvedPath)) {
+      continue;
+    }
+    if (!firstMissing) {
+      firstMissing = resolvedPath;
+    }
+    if (ctx.fileContent(resolvedPath) !== null) {
+      return { exists: true, resolvedPath };
+    }
+  }
+
+  return { exists: false, resolvedPath: firstMissing };
+}
+
+function rewriteMarkdownLinksForScanning(text) {
+  return String(text || '').replace(MARKDOWN_LINK_RE, (_match, target) => ` ${target} `);
+}
 
 module.exports = {
   key: 'agent-config-missing-file',
@@ -23,35 +257,46 @@ module.exports = {
   run(ctx) {
     const findings = [];
     const seen = new Set();
+    const state = {
+      basenameCache: new Map(),
+      suffixCache: new Map(),
+    };
 
     for (const entry of getAgentConfigEntries(ctx)) {
       if (!/\.(?:md|mdc|txt|rst)$/i.test(entry.path) && !/\.cursorrules$|\.windsurfrules$/i.test(entry.path)) {
         continue;
       }
       for (const { lineNumber, text } of getScannableLines(entry.content)) {
+        const scanText = rewriteMarkdownLinksForScanning(text);
         POINTER_RE.lastIndex = 0;
-        let match = POINTER_RE.exec(text);
+        let match = POINTER_RE.exec(scanText);
         while (match) {
           const candidate = normalizeCandidatePath(match[1]);
           if (!looksLikeRelativeFileReference(candidate)) {
-            match = POINTER_RE.exec(text);
+            match = POINTER_RE.exec(scanText);
+            continue;
+          }
+
+          if (lineHasExampleContext(text)) {
+            match = POINTER_RE.exec(scanText);
             continue;
           }
 
-          const resolvedPath = resolveRepoPath(ctx, entry.path, candidate, 'relative-to-file');
-          if (!resolvedPath || isKnownConventionPath(resolvedPath)) {
-            match = POINTER_RE.exec(text);
+          if (shouldIgnoreCandidate(ctx, text, candidate, state)) {
+            match = POINTER_RE.exec(scanText);
             continue;
           }
 
-          if (ctx.fileContent(resolvedPath) !== null) {
-            match = POINTER_RE.exec(text);
+          const resolution = resolveMissingCandidate(ctx, entry.path, candidate);
+          if (!resolution.resolvedPath || resolution.exists) {
+            match = POINTER_RE.exec(scanText);
             continue;
           }
+          const resolvedPath = resolution.resolvedPath;
 
           const dedupeKey = `${entry.path}:${toPosix(resolvedPath)}`;
           if (seen.has(dedupeKey)) {
-            match = POINTER_RE.exec(text);
+            match = POINTER_RE.exec(scanText);
             continue;
           }
           seen.add(dedupeKey);
@@ -62,7 +307,7 @@ module.exports = {
             fix: `${entry.path} references \`${toPosix(resolvedPath)}\`, but the file is missing. Create the file or update the agent guidance to point at a real repo path.`,
           });
 
-          match = POINTER_RE.exec(text);
+          match = POINTER_RE.exec(scanText);
         }
       }
     }

package/src/shallow-risk/shared.js

@@ -74,17 +74,71 @@ const SPECIAL_FILE_BASENAMES = new Set([
   'Dockerfile',
   'Makefile',
   'justfile',
+  'manifest.json',
   'package.json',
   'pyproject.toml',
   'go.mod',
   'Cargo.toml',
 ]);
 
+const COMMON_DOTFILE_BASENAMES = new Set([
+  '.editorconfig',
+  '.env',
+  '.env.example',
+  '.env.sample',
+  '.env.template',
+  '.gitattributes',
+  '.gitignore',
+  '.npmrc',
+  '.nvmrc',
+  '.prettierrc',
+  '.python-version',
+  '.tool-versions',
+]);
+
 const KNOWN_CONVENTION_PATHS = new Set([
   'CODEOWNERS',
   '.github/CODEOWNERS',
 ]);
 
+const FILE_REFERENCE_EXTENSION_RE = /\.(?:md|mdc|txt|rst|json|jsonc|ya?ml|toml|conf|sh|ps1|js|cjs|mjs|ts|tsx|jsx|cts|mts|py|go|rs|java|kt|kts|gradle|cs|rb|php|swift|pbxproj|xcconfig|xcworkspace|xcodeproj|h|hpp|c|cc|cpp|m|mm|sql|ini|cfg|properties|xml|html|css|scss|sass|lock)$/i;
+const KNOWN_DOMAIN_TLDS = new Set([
+  'ai',
+  'app',
+  'co',
+  'com',
+  'dev',
+  'io',
+  'net',
+  'org',
+  'sh',
+]);
+const KNOWN_HIDDEN_PATH_SEGMENTS = new Set([
+  '.claude',
+  '.codex',
+  '.cursor',
+  '.gemini',
+  '.github',
+  '.opencode',
+  '.vscode',
+  '.windsurf',
+]);
+const FRAMEWORK_LABEL_TOKENS = new Set([
+  'd3.js',
+  'go',
+  'golang',
+  'javascript',
+  'kotlin',
+  'next',
+  'next.js',
+  'node',
+  'node.js',
+  'python',
+  'rust',
+  'swift',
+  'typescript',
+]);
+
 const LOCAL_MCP_BINARIES = new Set([
   'context7-mcp',
   'nerviq-mcp',
@@ -127,8 +181,9 @@ function existsSyncSafe(targetPath) {
 function isLikelyTextFile(relPath) {
   const base = path.posix.basename(toPosix(relPath));
   if (SPECIAL_FILE_BASENAMES.has(base)) return true;
+  if (COMMON_DOTFILE_BASENAMES.has(base)) return true;
   if (base === '.cursorrules' || base === '.windsurfrules') return true;
-  return /\.(?:md|mdc|txt|rst|json|jsonc|ya?ml|toml|conf|sh|ps1|js|cjs|mjs|ts|tsx|jsx|py|go|rs|java|kt|cs|rb|php|swift)$/i.test(base);
+  return hasKnownFileExtension(base);
 }
 
 function fileExists(ctx, relPath) {
@@ -235,27 +290,69 @@ function stripWrapperChars(value) {
 function normalizeCandidatePath(rawValue) {
   let value = stripWrapperChars(rawValue);
   if (value.startsWith('@')) value = value.slice(1);
+  if (/^mdc:/i.test(value)) value = value.slice(4);
   return value;
 }
 
+function hasKnownFileExtension(baseName) {
+  return FILE_REFERENCE_EXTENSION_RE.test(baseName || '');
+}
+
+function isVersionLikeToken(candidate) {
+  return /^v?\d+(?:\.\d+)+(?:[a-z]+\d*|\.[xX*])?$/i.test(candidate || '');
+}
+
+function isFrameworkLabelToken(candidate) {
+  return FRAMEWORK_LABEL_TOKENS.has(String(candidate || '').toLowerCase());
+}
+
+function isDomainLikeToken(candidate) {
+  if (!candidate || candidate.includes('/')) return false;
+  const parts = String(candidate).split('.');
+  if (parts.length < 2) return false;
+  const tld = parts[parts.length - 1].toLowerCase();
+  if (!KNOWN_DOMAIN_TLDS.has(tld)) return false;
+  return parts.slice(0, -1).every((part) => /^[A-Za-z0-9-]+$/.test(part));
+}
+
+function lineHasExampleContext(line) {
+  const text = String(line || '');
+  if (/^\s*\|/.test(text)) return true;
+  if (/^\s*#{1,6}\s+/.test(text)) return true;
+  return /\b(?:e\.g\.?|for example|examples?|sample|placeholder|template|snippet|user request|problem|solution)\b/i.test(text);
+}
+
 function looksLikeRelativeFileReference(candidate) {
   if (!candidate) return false;
   if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(candidate)) return false;
-  if (/^[A-Za-z0-9-]+\.[A-Za-z]{2,}\//.test(candidate)) return false;
   if (candidate.startsWith('#')) return false;
+  if (/[<>{}|]/.test(candidate)) return false;
 
   const normalized = candidate.replace(/^\.\//, '');
   const base = path.posix.basename(normalized);
+  const lowered = normalized.toLowerCase();
 
-  if (KNOWN_CONVENTION_PATHS.has(normalized) || SPECIAL_FILE_BASENAMES.has(base)) {
-    return true;
+  if (isDomainLikeToken(normalized)) return false;
+  if (isVersionLikeToken(normalized)) return false;
+  if (isFrameworkLabelToken(normalized)) return false;
+  if (base.startsWith('.') && !COMMON_DOTFILE_BASENAMES.has(base) && !COMMON_DOTFILE_BASENAMES.has(lowered)) {
+    return false;
+  }
+  if (normalized.split('/').some((segment) => /^\.[A-Za-z0-9_-]+$/.test(segment) && !COMMON_DOTFILE_BASENAMES.has(segment.toLowerCase()) && !KNOWN_HIDDEN_PATH_SEGMENTS.has(segment.toLowerCase()))) {
+    return false;
+  }
+  if (/^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z][A-Za-z0-9_-]*){2,}$/i.test(normalized) && !hasKnownFileExtension(base)) {
+    return false;
+  }
+  if (/^\.[A-Za-z0-9_-]+\.[A-Za-z0-9._-]+$/.test(base) && !COMMON_DOTFILE_BASENAMES.has(base) && !COMMON_DOTFILE_BASENAMES.has(lowered)) {
+    return false;
   }
 
-  if (normalized.includes('/')) {
-    return /\.(?:md|mdc|txt|rst|json|jsonc|ya?ml|toml|conf|sh|ps1|js|cjs|mjs|ts|tsx|jsx|py|go|rs|java|kt|cs|rb|php|swift)$/i.test(base);
+  if (KNOWN_CONVENTION_PATHS.has(normalized) || SPECIAL_FILE_BASENAMES.has(base) || COMMON_DOTFILE_BASENAMES.has(base) || COMMON_DOTFILE_BASENAMES.has(lowered)) {
+    return true;
   }
 
-  return /^(?:\.?[A-Za-z0-9_-]+\.)[A-Za-z0-9._-]+$/i.test(normalized);
+  return hasKnownFileExtension(base);
 }
 
 function resolveRepoPath(ctx, fromFile, candidate, mode = 'relative-to-file') {
@@ -277,11 +374,34 @@ function getScannableLines(content) {
   const lines = String(content || '').split(/\r?\n/);
   const output = [];
   let fence = null;
+  let htmlComment = false;
+  let frontmatter = false;
+  let frontmatterConsumed = false;
 
   for (let index = 0; index < lines.length; index++) {
     const line = lines[index];
     const trimmed = line.trim();
 
+    if (!frontmatterConsumed && index === 0 && /^(---|\+\+\+)$/.test(trimmed)) {
+      frontmatter = true;
+      frontmatterConsumed = true;
+      continue;
+    }
+
+    if (frontmatter) {
+      if (/^(---|\+\+\+)$/.test(trimmed)) {
+        frontmatter = false;
+      }
+      continue;
+    }
+
+    if (!fence && htmlComment) {
+      if (trimmed.includes('-->')) {
+        htmlComment = false;
+      }
+      continue;
+    }
+
     if (!fence && /^(```|~~~)/.test(trimmed)) {
       fence = trimmed.slice(0, 3);
       continue;
@@ -294,6 +414,13 @@ function getScannableLines(content) {
       continue;
     }
 
+    if (/^<!--/.test(trimmed)) {
+      if (!trimmed.includes('-->')) {
+        htmlComment = true;
+      }
+      continue;
+    }
+
     output.push({ lineNumber: index + 1, text: line });
   }
 
@@ -512,6 +639,7 @@ module.exports = {
   hasLegacyAiderPin,
   isClearlyLocalMcpBinary,
   isKnownConventionPath,
+  lineHasExampleContext,
   looksLikeRelativeFileReference,
   normalizeCandidatePath,
   platformForFile,