@nudojs/parser 1.5.0 → 1.5.3

package/dist/index.d.ts

@@ -118,10 +118,20 @@ type MockDirective = {
     name: string;
     expression?: string;
     fromPath?: string;
+    /**
+     * 内联箭头 mock 的扫描结果：形参（源码形态）+ 体 + async 标志。
+     * - `params`：1:1 于形参个数的**源码形态**（签名用；默认形参保留默认值、
+     *   rest 保留 `...`、解构形参保留 `{ a, b }`）。
+     * - `paramPatterns`：形参 AST（原样）——消费面可自行解构绑定。
+     * - `boundNames`：每个形参**绑定的名字**（作用域用；解构列出顶层绑定名）。
+     * - `async`：`async (x) => …` 的 async 语义（Bug 857）。
+     */
     arrowFn?: {
         params: string[];
         body: Node;
         paramPatterns: Node[];
+        async?: boolean;
+        boundNames?: string[][];
     };
     sinonExpr?: SinonExpression;
     nudoMock?: MockHelper;
@@ -171,9 +181,27 @@ type FunctionWithDirectives = {
     directives: Directive[];
 };
 
+/**
+ * 指令文法诊断。
+ *
+ * `at`：**出错指令在源码中的位置**（行 1-based / 列 0-based）。
+ *
+ * Bug 848：去重身份此前只有 `code + message`（**无位置**）⇒ 同文件两处
+ * **逐字相同**的畸形指令**塌缩成一条** ⇒ 第二处**完全不可见**（用户修好
+ * 第一处后以为已经修完）。身份必须含位置：同一处同一问题仍去重（extract
+ * + 再解析共域），**不同位置**的同文案问题各报一条。
+ *
+ * 不传 `at` 的调用点保持旧身份（`code + message`）——兼容未升级的调用方，
+ * 但**同文案塌缩**在这些族上仍存在（见交付报告的「需收口」清单）。
+ */
 type DirectiveDiag = {
     code: string;
     message: string;
+    /** 出错指令的位置（行 1-based / 列 0-based）；缺省 ⇒ 旧身份（无位置） */
+    at?: {
+        line: number;
+        column: number;
+    };
 };
 /**
  * 在指定诊断数组上执行 fn：fn 内所有指令文法诊断（含不传 diags 的 extract

package/dist/index.js

@@ -188,7 +188,9 @@ function runWithDirectiveDiags(diags, fn) {
 }
 function emitDirectiveDiag(d) {
   if (!activeDiagSink) return;
-  const key = `${d.code}\0${d.message}`;
+  const at = d.at;
+  const posKey = at ? `${at.line}:${at.column}` : "";
+  const key = `${d.code}\0${d.message}\0${posKey}`;
   if (activeDiagSink.seen.has(key)) return;
   activeDiagSink.seen.add(key);
   activeDiagSink.list.push(d);
@@ -202,6 +204,8 @@ import {
   numLit,
   strLit,
   boolLit,
+  bigintLit,
+  litValue,
   execNudoModule,
   isNudoConstraint,
   constraintToEntryAbs,
@@ -212,6 +216,7 @@ import {
 import { absLit, DIAG } from "@nudojs/core/internal";
 
 // src/directives/expr-scan.ts
+import { formalParamsFromNodes } from "@nudojs/core";
 function scanWithStrings(s, onChar, onStructural) {
   let depth = 0;
   let inString = null;
@@ -307,9 +312,32 @@ function findTopLevelArrow(s) {
   }
   return -1;
 }
+var ARROW_WRAPPER_PREFIX = "const __mock = ";
+function paramSource(param, expr) {
+  const start = param.start;
+  const end = param.end;
+  if (typeof start === "number" && typeof end === "number") {
+    const from = start - ARROW_WRAPPER_PREFIX.length;
+    const to = end - ARROW_WRAPPER_PREFIX.length;
+    if (from >= 0 && to <= expr.length && from < to) return expr.slice(from, to);
+  }
+  return "";
+}
+function boundNamesOf(formal) {
+  if (!formal) return [];
+  switch (formal.kind) {
+    case "id":
+    case "default":
+      return [formal.name];
+    case "rest":
+      return [formal.name];
+    case "pattern":
+      return [...formal.bound];
+  }
+}
 function parseArrowFunctionExpr(expr) {
   try {
-    const wrapped = `const __mock = ${expr};`;
+    const wrapped = `${ARROW_WRAPPER_PREFIX}${expr};`;
     const ast = parse(wrapped);
     const decl = ast.program.body[0];
     if (decl.type !== "VariableDeclaration") return null;
@@ -317,27 +345,68 @@ function parseArrowFunctionExpr(expr) {
     if (!init || init.type !== "ArrowFunctionExpression" && init.type !== "FunctionExpression") {
       return null;
     }
+    const rawParams = init.params.filter(
+      (p) => !(p.type === "Identifier" && p.name === "this")
+    );
+    const formals = formalParamsFromNodes(rawParams);
     const params = [];
+    const boundNames = [];
     const paramPatterns = [];
-    for (let i = 0; i < init.params.length; i++) {
-      const param = init.params[i];
-      if (param.type === "Identifier") {
-        params.push(param.name);
-        paramPatterns.push(param);
-      } else if (param.type === "RestElement" && param.argument.type === "Identifier") {
-        params.push(`...${param.argument.name}`);
-        paramPatterns.push(param);
-      } else if (param.type === "ArrayPattern" || param.type === "ObjectPattern") {
-        params.push(`__destructured_${i}`);
-        paramPatterns.push(param);
-      }
+    for (let i = 0; i < rawParams.length; i++) {
+      const param = rawParams[i];
+      paramPatterns.push(param);
+      params.push(paramSource(param, expr));
+      boundNames.push(boundNamesOf(formals[i]));
     }
-    return { params, body: init.body, paramPatterns };
+    return {
+      params,
+      body: init.body,
+      paramPatterns,
+      async: init.async === true,
+      boundNames
+    };
   } catch {
     return null;
   }
 }
 
+// src/directives/string-literal.ts
+function findClosingQuote(s, quote) {
+  for (let i = 1; i < s.length; i++) {
+    const c = s[i];
+    if (c === "\\") {
+      i += 1;
+      continue;
+    }
+    if (c === quote) return i;
+  }
+  return -1;
+}
+function scanStringLiteral(text) {
+  const s = text.trim();
+  const quote = s[0];
+  if (quote !== '"' && quote !== "'") {
+    return { kind: "not-literal", reason: "not-quoted" };
+  }
+  const close = findClosingQuote(s, quote);
+  if (close === -1) return { kind: "not-literal", reason: "unterminated" };
+  if (close !== s.length - 1) return { kind: "not-literal", reason: "trailing-text" };
+  try {
+    const ast = parse(`(${s});`);
+    const stmt = ast.program.body[0];
+    if (!stmt || stmt.type !== "ExpressionStatement") {
+      return { kind: "not-literal", reason: "not-parseable" };
+    }
+    const expr = stmt.expression;
+    if (expr.type !== "StringLiteral") {
+      return { kind: "not-literal", reason: "not-parseable" };
+    }
+    return { kind: "literal", value: expr.value };
+  } catch {
+    return { kind: "not-literal", reason: "not-parseable" };
+  }
+}
+
 // src/directives/case-arg.ts
 function absExact(shape) {
   return makeAbs(shape, void 0, void 0, "exact");
@@ -482,7 +551,13 @@ function constraintToCaseArgAbs(c, depth) {
   if (c.fields) {
     const slots = {};
     for (const [key, field] of Object.entries(c.fields)) {
-      slots[key] = { value: constraintToCaseArgAbs(field.constraint, depth + 1) };
+      slots[key] = {
+        value: constraintToCaseArgAbs(field.constraint, depth + 1),
+        // 可选标记必须投影进槽（与 core 的 constraintToEntryAbs 同口径）：
+        // 丢掉它 ⇒ 可选槽变必填 ⇒ 缺该字段的**合法**实际值被判红，
+        // 且报出的 expected 文案不带 `?`（与契约面同文法自相矛盾）。
+        ...field.optional || field.constraint.isOptional ? { optional: true } : {}
+      };
     }
     return absExact({ k: "obj", slots });
   }
@@ -536,23 +611,70 @@ function parseLiteralOrStructure(expr, depth) {
       return absFunction(fnExpr.params, { body: fnExpr.body });
     }
   }
-  if (/^-?\d+(\.\d+)?$/.test(s)) return absLit(Number(s));
-  if (s.startsWith('"') && s.endsWith('"') || s.startsWith("'") && s.endsWith("'")) {
-    return absLit(s.slice(1, -1));
+  const numAbs = parseNumberLiteralExpr(s);
+  if (numAbs) return numAbs;
+  if (s.startsWith('"') || s.startsWith("'")) {
+    const scan = scanStringLiteral(s);
+    if (scan.kind === "literal") return absLit(scan.value);
+    return absUnknown();
+  }
+  if (s.startsWith("{") || s.startsWith("[")) {
+    if (literalNestingDepth(s) > MAX_CASE_ARG_DEPTH) return depthCapDiag(s);
+    const kind = structureLiteralKind(s);
+    if (kind === "obj") {
+      return parseObjectLiteral(s.slice(1, -1).trim(), depth);
+    }
+    if (kind === "arr") {
+      const content = s.slice(1, -1).trim();
+      if (!content) return absExact({ k: "tuple", elements: [] });
+      const elements = splitTopLevelArgs(content);
+      return absExact({
+        k: "tuple",
+        elements: elements.map((e) => parseCaseArgExpr(e, depth + 1))
+      });
+    }
+    return absUnknown();
   }
-  if (s.startsWith("{") && s.endsWith("}")) {
-    return parseObjectLiteral(s.slice(1, -1).trim(), depth);
+  const templateAbs = parseTemplateLiteralExpr(s);
+  if (templateAbs) return templateAbs;
+  return absUnknown();
+}
+function literalNestingDepth(s) {
+  let depth = 0;
+  let max = 0;
+  let inString = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inString) {
+      if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") {
+      depth++;
+      if (depth > max) max = depth;
+    } else if (ch === ")" || ch === "]" || ch === "}") {
+      depth--;
+    }
   }
-  if (s.startsWith("[") && s.endsWith("]")) {
-    const content = s.slice(1, -1).trim();
-    if (!content) return absExact({ k: "tuple", elements: [] });
-    const elements = splitTopLevelArgs(content);
-    return absExact({
-      k: "tuple",
-      elements: elements.map((e) => parseCaseArgExpr(e, depth + 1))
-    });
+  return max;
+}
+function structureLiteralKind(s) {
+  try {
+    const ast = parse(`(${s});`);
+    if (ast.program.body.length !== 1) return void 0;
+    const stmt = ast.program.body[0];
+    if (stmt.type !== "ExpressionStatement") return void 0;
+    const expr = stmt.expression;
+    if (expr.type === "ObjectExpression") return "obj";
+    if (expr.type === "ArrayExpression") return "arr";
+    return void 0;
+  } catch {
+    return void 0;
   }
-  return absUnknown();
 }
 function parseObjectLiteral(content, depth) {
   if (!content) return absExact({ k: "obj", slots: {} });
@@ -560,7 +682,13 @@ function parseObjectLiteral(content, depth) {
   const slots = {};
   for (const entry of entries) {
     const colonIdx = findTopLevelColon(entry);
-    if (colonIdx === -1) continue;
+    if (colonIdx === -1) {
+      emitDirectiveDiag({
+        code: DIAG.directiveSyntax,
+        message: `Unrecognized property in object literal: ${entry.slice(0, 60)} (getter / method shorthand / shorthand property are not supported in directive payloads)`
+      });
+      return absUnknown();
+    }
     const key = entry.slice(0, colonIdx).trim().replace(/^["']|["']$/g, "");
     const val = entry.slice(colonIdx + 1).trim();
     slots[key] = { value: parseCaseArgExpr(val, depth + 1) };
@@ -577,13 +705,93 @@ function parseAbsExpr(expr) {
 function parseAbsExprDiag(expr, context) {
   const abs = parseCaseArgExpr(expr);
   if (abs.shape.k === "unknown" && !abs.term && !isExplicitUnknownExpr(expr)) {
-    emitDirectiveDiag({
-      code: DIAG.directiveSyntax,
-      message: `Unrecognized type expression in ${context}: ${expr.trim()} (use constraint builders, literals, or structure syntax)`
-    });
+    emitUnrecognizedExprDiag(expr, context);
+    if (isCaseExpectedContext(context)) return absParseFailure();
   }
   return abs;
 }
+function emitUnrecognizedExprDiag(expr, context) {
+  emitDirectiveDiag({
+    code: DIAG.directiveSyntax,
+    message: `Unrecognized type expression in ${context}: ${expr.trim()} (use constraint builders, literals, or structure syntax)`
+  });
+}
+function absParseFailure() {
+  return absExact({ k: "never" });
+}
+function isCaseExpectedContext(context) {
+  return /^@nudo:case\b/.test(context) && /=>\s*expected\s*$/.test(context);
+}
+var PLAIN_DECIMAL_RE = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/;
+var LEGACY_LEADING_ZERO_RE = /^([+-]?)0([0-9]+)$/;
+function legacyLeadingZeroValue(s) {
+  const m = LEGACY_LEADING_ZERO_RE.exec(s);
+  if (!m) return void 0;
+  const sign = m[1] === "-" ? -1 : 1;
+  const digits = `0${m[2]}`;
+  if (/^0[0-7]+$/.test(digits)) return sign * parseInt(digits, 8);
+  return sign * Number(digits);
+}
+function parseDirectiveExprNode(s) {
+  try {
+    const ast = parse(`(${s});`);
+    if (ast.program.body.length !== 1) return void 0;
+    const stmt = ast.program.body[0];
+    if (stmt.type !== "ExpressionStatement") return void 0;
+    return stmt.expression;
+  } catch {
+    return void 0;
+  }
+}
+function numericNodeValue(node) {
+  switch (node.type) {
+    case "NumericLiteral":
+      return typeof node.value === "number" ? node.value : void 0;
+    case "BigIntLiteral": {
+      const raw = node.value;
+      try {
+        return typeof raw === "bigint" ? raw : BigInt(raw);
+      } catch {
+        return void 0;
+      }
+    }
+    case "UnaryExpression": {
+      if (node.operator !== "+" && node.operator !== "-") return void 0;
+      const inner = numericNodeValue(node.argument);
+      if (inner === void 0) return void 0;
+      if (node.operator === "+") return inner;
+      return typeof inner === "bigint" ? -inner : -inner;
+    }
+    case "Identifier":
+      if (node.name === "Infinity") return Infinity;
+      if (node.name === "NaN") return NaN;
+      return void 0;
+    default:
+      return void 0;
+  }
+}
+function parseNumberLiteralExpr(s) {
+  const body = s.trim();
+  if (PLAIN_DECIMAL_RE.test(body)) return numLit(Number(body));
+  const legacy = legacyLeadingZeroValue(body);
+  if (legacy !== void 0) return numLit(legacy);
+  const node = parseDirectiveExprNode(body);
+  if (!node) return void 0;
+  const value = numericNodeValue(node);
+  if (value === void 0) return void 0;
+  if (typeof value === "bigint") return bigintLit(value);
+  return numLit(value);
+}
+function parseTemplateLiteralExpr(s) {
+  const body = s.trim();
+  if (!body.startsWith("`") || !body.endsWith("`") || body.length < 2) return void 0;
+  const node = parseDirectiveExprNode(body);
+  if (!node || node.type !== "TemplateLiteral") return void 0;
+  if (node.expressions.length > 0) return void 0;
+  const cooked = node.quasis[0]?.value.cooked;
+  if (typeof cooked !== "string") return void 0;
+  return strLit(cooked);
+}
 
 // src/directives/fn-directives.ts
 import {
@@ -706,7 +914,14 @@ function parseNudoMockExpr(expr) {
   if (stubCallsFakeMatch) {
     const arrowFn = parseArrowFunctionExpr(stubCallsFakeMatch[1].trim());
     if (arrowFn) {
-      return stub.callsFake({ params: arrowFn.params, body: arrowFn.body, async: false });
+      return stub.callsFake({
+        params: arrowFn.params,
+        body: arrowFn.body,
+        // Bug 857 的第三处：sinon 路径此前也把 async 硬编码成 false ⇒
+        // `stub().callsFake(async (x) => …)` 被建模成同步函数 ⇒ 调用点
+        // `.then(…)` 报「method 'then' missing」。
+        async: arrowFn.async === true
+      });
     }
     return { kind: "mock-helper" };
   }
@@ -762,18 +977,18 @@ function parseNudoMockExpr(expr) {
 }
 
 // src/directives/fn-directives.ts
-var CASE_TAG_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:case\b[ \t]*([^\n]*)/g;
+var CASE_TAG_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:case\b([ \t]*)([^\n]*)/g;
 var JS_IDENT_RE = /^[\p{L}$_][\p{L}\p{N}$_]*$/u;
-var MOCK_INLINE_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:mock\b[ \t]+([^\s=]+)[ \t]*=[ \t]*(.+)/g;
-var MOCK_FROM_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:mock\b[ \t]+([^\s]+)[ \t]+from[ \t]+(?:"([^"\n]+)"|'([^'\n]+)')/g;
-var MOCK_TAG_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:mock\b[ \t]*([^\n]*)/g;
+var MOCK_INLINE_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:mock(?![-\w])[ \t]+([^\s=]+)[ \t]*=[ \t]*(.+)/g;
+var MOCK_FROM_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:mock(?![-\w])[ \t]+([^\s]+)[ \t]+from[ \t]+(?:"([^"\n]+)"|'([^'\n]+)')/g;
+var MOCK_TAG_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:mock(?!-)([ \t]*)([^\n]*)/g;
 var PURE_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:pure\b/g;
-var SKIP_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:skip\b(?:[ \t]+(\S[^\n]*))?/g;
+var SKIP_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:skip\b[ \t]*(.*)/g;
 var SAMPLE_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:sample\b(?:[ \t]+(\S+))?/g;
 var SAMPLE_NUM_RE = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
 function parseSkipReturnsExpr(rest) {
   if (rest === void 0) return void 0;
-  const s = rest.trim();
+  const s = stripTrailingComment(rest);
   if (s === "") return void 0;
   if (s.startsWith("=>")) {
     const expr = s.slice(2).trim();
@@ -801,14 +1016,51 @@ function parseSkipReturnsExpr(rest) {
   }
   return void 0;
 }
+function siteInCommentText(text, startLine, offset) {
+  const before = text.slice(0, Math.max(0, offset));
+  const nl = before.lastIndexOf("\n");
+  const newlines = before.split("\n").length - 1;
+  return {
+    line: startLine + newlines,
+    column: nl < 0 ? offset : offset - nl - 1
+  };
+}
+function stripTrailingComment(text) {
+  let quote = null;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quote !== null) {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "/") return text.slice(0, i).trim();
+  }
+  return text.trim();
+}
 function parseDirectivesFromCommentTexts(comments) {
   const directives = [];
   for (const { text, startLine: commentStartLine } of comments) {
     const caseArgSpans = scanCaseArgSpans(text);
     const caseTags = scanCaseTags(text);
-    scanMalformedCaseNames(text, caseArgSpans);
+    scanMalformedCaseNames(text, caseArgSpans, commentStartLine);
+    for (const tag of caseTags) {
+      if (!tag.expectedIssue) continue;
+      emitDirectiveDiag({
+        code: DIAG2.directiveSyntax,
+        message: `Malformed @nudo:case: ${tag.expectedIssue} \u2014 got: @nudo:case "${tag.name}" (\u2026)`,
+        at: siteInCommentText(text, commentStartLine, tag.tagOffset)
+      });
+    }
     const inCaseArgs = (idx) => caseArgSpans.some(([s, e]) => idx >= s && idx < e);
-    scanMalformedMockNames(text, caseArgSpans);
+    scanMalformedMockNames(text, caseArgSpans, commentStartLine);
     MOCK_FROM_REGEX.lastIndex = 0;
     let mockFromMatch;
     const mockFromRanges = [];
@@ -833,6 +1085,7 @@ function parseDirectivesFromCommentTexts(comments) {
       const mockName = mockMatch[1];
       if (!JS_IDENT_RE.test(mockName)) continue;
       const expr = mockMatch[2].trim();
+      if (expr === "") continue;
       let arrowFn = parseArrowFunctionExpr(expr);
       const sinonExpr = parseSinonExpr(expr);
       const nudoMock = parseNudoMockExpr(expr);
@@ -856,7 +1109,8 @@ function parseDirectivesFromCommentTexts(comments) {
       const cleaned = tag.argsText.split("\n").map((line) => line.replace(/^\s*\*\s?/, "")).join("\n");
       const rawArgs = splitTopLevelArgs(cleaned);
       const argsAbs = rawArgs.map((a) => parseAbsExprDiag(a, `@nudo:case "${name}" argument`));
-      const expected = tag.expectedText !== void 0 ? parseAbsExprDiag(tag.expectedText, `@nudo:case "${name}" => expected`) : void 0;
+      const expectedText = tag.expectedText !== void 0 ? stripTrailingComment(tag.expectedText) : void 0;
+      const expected = expectedText !== void 0 ? parseAbsExprDiag(expectedText, `@nudo:case "${name}" => expected`) : void 0;
       const linesBeforeMatch = text.slice(0, tag.tagOffset).split("\n").length - 1;
       const commentLine = commentStartLine + linesBeforeMatch;
       directives.push({
@@ -892,7 +1146,8 @@ function parseDirectivesFromCommentTexts(comments) {
       if (raw === void 0 || !SAMPLE_NUM_RE.test(raw)) {
         emitDirectiveDiag({
           code: DIAG2.directiveSyntax,
-          message: `Malformed @nudo:sample: expected a numeric count (integer, decimal, or negative) \u2014 got: @nudo:sample ${raw ?? "(missing count)"}`
+          message: `Malformed @nudo:sample: expected a numeric count (integer, decimal, or negative) \u2014 got: @nudo:sample ${raw ?? "(missing count)"}`,
+          at: siteInCommentText(text, commentStartLine, sampleMatch.index)
         });
         continue;
       }
@@ -901,20 +1156,30 @@ function parseDirectivesFromCommentTexts(comments) {
   }
   return directives;
 }
-function scanMalformedCaseNames(text, caseArgSpans) {
+function scanMalformedCaseNames(text, caseArgSpans, startLine) {
   const inCaseArgs = (idx) => caseArgSpans.some(([s, e]) => idx >= s && idx < e);
   CASE_TAG_REGEX.lastIndex = 0;
   let m;
   while ((m = CASE_TAG_REGEX.exec(text)) !== null) {
     if (inCaseArgs(m.index)) continue;
-    const rest = m[1].trim();
+    const separator = m[1];
+    const rest = m[2].trim();
+    if (separator === "" && rest.startsWith('"')) {
+      emitDirectiveDiag({
+        code: DIAG2.directiveSyntax,
+        message: `Malformed @nudo:case: expected a space between '@nudo:case' and the name (expected @nudo:case "name" (\u2026)) \u2014 got: @nudo:case${rest.slice(0, 60)}`,
+        at: siteInCommentText(text, startLine, m.index)
+      });
+      continue;
+    }
     const legal = rest.match(/^("[^"]+")[ \t]*\(/);
     if (legal) {
-      const parenIdx = m.index + m[0].length - m[1].length + legal[0].length - 1;
+      const parenIdx = m.index + m[0].length - m[2].length + legal[0].length - 1;
       if (extractBalancedParens(text, parenIdx) === null) {
         emitDirectiveDiag({
           code: DIAG2.directiveSyntax,
-          message: `Malformed @nudo:case: unclosed argument list (missing closing ")") \u2014 got: @nudo:case ${rest.slice(0, 60)}`
+          message: `Malformed @nudo:case: unclosed argument list (missing closing ")") \u2014 got: @nudo:case ${rest.slice(0, 60)}`,
+          at: siteInCommentText(text, startLine, m.index)
         });
       }
       continue;
@@ -933,22 +1198,41 @@ function scanMalformedCaseNames(text, caseArgSpans) {
     }
     emitDirectiveDiag({
       code: DIAG2.directiveSyntax,
-      message: `Malformed @nudo:case: ${reason} \u2014 got: @nudo:case ${rest.slice(0, 60)}`
+      message: `Malformed @nudo:case: ${reason} \u2014 got: @nudo:case ${rest.slice(0, 60)}`,
+      at: siteInCommentText(text, startLine, m.index)
     });
   }
 }
-function scanMalformedMockNames(text, caseArgSpans) {
+function mockStrictGrammarHits(text, index) {
+  MOCK_INLINE_REGEX.lastIndex = index;
+  const inline = MOCK_INLINE_REGEX.exec(text);
+  if (inline !== null && inline.index === index && inline[2].trim() !== "") return true;
+  MOCK_FROM_REGEX.lastIndex = index;
+  const from = MOCK_FROM_REGEX.exec(text);
+  return from !== null && from.index === index;
+}
+function scanMalformedMockNames(text, caseArgSpans, startLine) {
   const inCaseArgs = (idx) => caseArgSpans.some(([s, e]) => idx >= s && idx < e);
   MOCK_TAG_REGEX.lastIndex = 0;
   let m;
   while ((m = MOCK_TAG_REGEX.exec(text)) !== null) {
     if (inCaseArgs(m.index)) continue;
-    const rest = m[1].trim();
+    const separator = m[1];
+    const rest = m[2].trim();
+    if (separator === "" && /^[A-Za-z_$]/.test(rest)) {
+      emitDirectiveDiag({
+        code: DIAG2.directiveSyntax,
+        message: `Malformed @nudo:mock: expected a space between '@nudo:mock' and the name (expected @nudo:mock <ident> = <expr> or @nudo:mock <ident> from "path" / 'path') \u2014 got: @nudo:mock${rest.slice(0, 60)}`,
+        at: siteInCommentText(text, startLine, m.index)
+      });
+      continue;
+    }
     const nameMatch = rest.match(/^([^\s=]+)(?:\s*=|\s+from\b)/);
     if (!nameMatch) {
       emitDirectiveDiag({
         code: DIAG2.directiveSyntax,
-        message: `Malformed @nudo:mock: cannot parse name (expected @nudo:mock <ident> = <expr> or @nudo:mock <ident> from "path" / 'path') \u2014 got: ${rest.slice(0, 60)}`
+        message: `Malformed @nudo:mock: cannot parse name (expected @nudo:mock <ident> = <expr> or @nudo:mock <ident> from "path" / 'path') \u2014 got: ${rest.slice(0, 60)}`,
+        at: siteInCommentText(text, startLine, m.index)
       });
       continue;
     }
@@ -956,7 +1240,8 @@ function scanMalformedMockNames(text, caseArgSpans) {
     if (!JS_IDENT_RE.test(name)) {
       emitDirectiveDiag({
         code: DIAG2.directiveSyntax,
-        message: `Malformed @nudo:mock name '${name}': not a valid identifier (use letters, digits, _, $; Unicode letters allowed)`
+        message: `Malformed @nudo:mock name '${name}': not a valid identifier (use letters, digits, _, $; Unicode letters allowed)`,
+        at: siteInCommentText(text, startLine, m.index)
       });
       continue;
     }
@@ -964,7 +1249,16 @@ function scanMalformedMockNames(text, caseArgSpans) {
     if (/^[ \t]+from[ \t]+(?:"[^"\n]*|'[^'\n]*)$/.test(afterName)) {
       emitDirectiveDiag({
         code: DIAG2.directiveSyntax,
-        message: `Malformed @nudo:mock from: unclosed quote in path (expected @nudo:mock ${name} from "path" / 'path') \u2014 got: @nudo:mock ${rest.slice(0, 60)}`
+        message: `Malformed @nudo:mock from: unclosed quote in path (expected @nudo:mock ${name} from "path" / 'path') \u2014 got: @nudo:mock ${rest.slice(0, 60)}`,
+        at: siteInCommentText(text, startLine, m.index)
+      });
+      continue;
+    }
+    if (!mockStrictGrammarHits(text, m.index)) {
+      emitDirectiveDiag({
+        code: DIAG2.directiveSyntax,
+        message: `Malformed @nudo:mock: empty or invalid payload (expected @nudo:mock ${name} = <expr> or @nudo:mock ${name} from "path" / 'path') \u2014 got: @nudo:mock ${rest.slice(0, 60)}`,
+        at: siteInCommentText(text, startLine, m.index)
       });
     }
   }
@@ -1000,10 +1294,48 @@ function stripInlineCommentPrefix(line, kind) {
   const s = kind === "block" ? line.replace(/^\s*\*\s?/, "") : line.replace(/^\//, "");
   return s.trim();
 }
-var AS_LINE_REGEX = /^@nudo:as[ \t]+(.+)$/;
 var REPLACE_LINE_REGEX = /^@nudo:replace[ \t]+(.+)$/;
-var AS_BARE_RE = /^@nudo:as[ \t]*$/;
 var REPLACE_BARE_RE = /^@nudo:replace[ \t]*$/;
+var REPLACE_GLUED_RE = /^@nudo:replace[A-Za-z0-9_$]/;
+var AS_TAG = "@nudo:as";
+function asPayloadOf(line) {
+  if (!line.startsWith(AS_TAG)) return null;
+  const rest = line.slice(AS_TAG.length);
+  const next = rest[0];
+  if (next !== void 0 && /[A-Za-z0-9_$]/.test(next)) return null;
+  return rest.trim();
+}
+function unwrapOuterParens(s) {
+  let cur = s.trim();
+  while (cur.length >= 2 && cur.startsWith("(") && cur.endsWith(")") && outerParensWrapAll(cur)) {
+    cur = cur.slice(1, -1).trim();
+  }
+  return cur;
+}
+function outerParensWrapAll(s) {
+  let depth = 0;
+  let inString = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inString) {
+      if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === ")") {
+      depth--;
+      if (depth === 0) return i === s.length - 1;
+    }
+  }
+  return false;
+}
 function findTrailingCommentStart(expr) {
   let inString = null;
   for (let i = 0; i < expr.length; i++) {
@@ -1016,12 +1348,23 @@ function findTrailingCommentStart(expr) {
       inString = ch;
       continue;
     }
+    if (ch === "/" && (expr[i + 1] === "/" || expr[i + 1] === "*")) {
+      if (!looksLikeDivision(expr, i)) return i;
+      continue;
+    }
     if ((ch === " " || ch === "	") && /^[ \t]+(?:\/\/|\/\*)/.test(expr.slice(i))) {
       return i;
     }
   }
   return -1;
 }
+function looksLikeDivision(expr, slashIdx) {
+  let left = slashIdx - 1;
+  while (left >= 0 && (expr[left] === " " || expr[left] === "	")) left--;
+  const ch = left >= 0 ? expr[left] : "";
+  if (ch !== "." && !/^[0-9]$/.test(ch)) return false;
+  return /^[0-9.]/.test(expr.slice(slashIdx + 2));
+}
 function extractInlineDirectives(node, opts) {
   const comments = node.leadingComments;
   if (!comments) return [];
@@ -1033,29 +1376,36 @@ function collectInlineDirectivesFromComments(comments) {
   for (const comment of comments) {
     if (comment.type !== "CommentLine" && comment.type !== "CommentBlock") continue;
     const kind = comment.type === "CommentLine" ? "line" : "block";
-    for (const rawLine of comment.value.split("\n")) {
+    const rawLines = comment.value.split("\n");
+    for (let lineIdx = 0; lineIdx < rawLines.length; lineIdx++) {
+      const rawLine = rawLines[lineIdx];
       const line = stripInlineCommentPrefix(rawLine, kind);
-      const asMatch = line.match(AS_LINE_REGEX);
-      if (asMatch) {
-        const rawExpr = asMatch[1].trim();
-        const trailingIdx = findTrailingCommentStart(rawExpr);
+      const at = commentSite(comment, rawLine, lineIdx, line);
+      const asPayload = asPayloadOf(line);
+      if (asPayload !== null) {
+        if (asPayload === "") {
+          emitDirectiveDiag({
+            code: DIAG3.directiveSyntax,
+            message: `@nudo:as requires a type expression (e.g. @nudo:as number())`,
+            at
+          });
+          continue;
+        }
+        const trailingIdx = findTrailingCommentStart(asPayload);
         if (trailingIdx !== -1) {
-          const typePart = rawExpr.slice(0, trailingIdx).trim();
+          const typePart = asPayload.slice(0, trailingIdx).trim();
           emitDirectiveDiag({
             code: DIAG3.directiveSyntax,
-            message: `Trailing comment in @nudo:as type expression: '${rawExpr}' (remove the comment; the type must be a clean expression)`
+            message: `Trailing comment in @nudo:as type expression: '${asPayload}' (remove the comment; the type must be a clean expression)`,
+            at
+          });
+          results.push({
+            kind: "as",
+            typeAbs: typePart ? parseAbsExprDiag(unwrapOuterParens(typePart), "@nudo:as") : absUnknown()
           });
-          results.push({ kind: "as", typeAbs: typePart ? parseAbsExprDiag(typePart, "@nudo:as") : absUnknown() });
           continue;
         }
-        results.push({ kind: "as", typeAbs: parseAbsExprDiag(rawExpr, "@nudo:as") });
-        continue;
-      }
-      if (AS_BARE_RE.test(line)) {
-        emitDirectiveDiag({
-          code: DIAG3.directiveSyntax,
-          message: `@nudo:as requires a type expression (e.g. @nudo:as number())`
-        });
+        results.push({ kind: "as", typeAbs: parseAbsExprDiag(unwrapOuterParens(asPayload), "@nudo:as") });
         continue;
       }
       const replaceMatch = line.match(REPLACE_LINE_REGEX);
@@ -1073,7 +1423,8 @@ function collectInlineDirectivesFromComments(comments) {
         } else {
           emitDirectiveDiag({
             code: DIAG3.directiveSyntax,
-            message: `Malformed @nudo:replace: cannot separate target from type (expected @nudo:replace <target> <typeExpr>) \u2014 got: ${raw.slice(0, 60)}`
+            message: `Malformed @nudo:replace: cannot separate target from type (expected @nudo:replace <target> <typeExpr>) \u2014 got: ${raw.slice(0, 60)}`,
+            at
           });
         }
         continue;
@@ -1081,13 +1432,33 @@ function collectInlineDirectivesFromComments(comments) {
       if (REPLACE_BARE_RE.test(line)) {
         emitDirectiveDiag({
           code: DIAG3.directiveSyntax,
-          message: `@nudo:replace requires a target and type expression (expected @nudo:replace <target> <typeExpr>)`
+          message: `@nudo:replace requires a target and type expression (expected @nudo:replace <target> <typeExpr>)`,
+          at
+        });
+        continue;
+      }
+      if (REPLACE_GLUED_RE.test(line)) {
+        emitDirectiveDiag({
+          code: DIAG3.directiveSyntax,
+          message: `Malformed @nudo:replace directive '${line.slice(0, 60)}' (expected a space after the tag: @nudo:replace <target> <typeExpr>)`,
+          at
         });
+        continue;
       }
     }
   }
   return results;
 }
+function commentSite(comment, rawLine, lineIdx, stripped) {
+  const locStart = comment.loc?.start;
+  if (!locStart) return void 0;
+  const base = lineIdx === 0 ? locStart.column + 2 : 0;
+  const inLine = stripped.length > 0 ? rawLine.indexOf(stripped) : 0;
+  return {
+    line: locStart.line + lineIdx,
+    column: base + (inLine < 0 ? 0 : inLine)
+  };
+}
 function findReplaceSeparator(raw) {
   let depth = 0;
   let inString = null;
@@ -1120,11 +1491,16 @@ function findReplaceSeparator(raw) {
 }
 
 // src/directives/file-directives.ts
-import { parseEnvPayload, parseMockModulePayload } from "@nudojs/core";
+import {
+  listFnDirectiveScopes as listFnDirectiveScopes2,
+  parseEnvPayload,
+  parseMockModulePayload
+} from "@nudojs/core";
 import { DIAG as DIAG4 } from "@nudojs/core/internal";
 var ENV_REGEX = /^\/?\s*@nudo:env\s+(.+)/;
+var ENV_BARE_REGEX = /^\/?\s*@nudo:env\b[ \t]*$/;
 var MOCK_MODULE_REGEX = /^\/?\s*@nudo:mock-module\s+(.+)/;
-var FILE_TAG_IN_BLOCK_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*)?@nudo:(env|mock-module)\b/g;
+var FILE_TAG_IN_BLOCK_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*)?@nudo:(env|mock-module|import)\b/g;
 function warnMisplacedFileTags(blockText) {
   FILE_TAG_IN_BLOCK_REGEX.lastIndex = 0;
   let m;
@@ -1132,10 +1508,48 @@ function warnMisplacedFileTags(blockText) {
     const tag = m[1];
     emitDirectiveDiag({
       code: DIAG4.directiveSyntax,
-      message: tag === "env" ? `@nudo:env is a file-level directive \u2014 use '/// @nudo:env node' at the top of the file (JSDoc block form is ignored)` : `@nudo:mock-module is a file-level directive \u2014 use '/// @nudo:mock-module "fs" from "./mock-fs.js"' at the top of the file (JSDoc block form is ignored)`
+      message: tag === "env" ? `@nudo:env is a file-level directive \u2014 use '/// @nudo:env node' at the top of the file (JSDoc block form is ignored)` : tag === "mock-module" ? `@nudo:mock-module is a file-level directive \u2014 use '/// @nudo:mock-module "fs" from "./mock-fs.js"' at the top of the file (JSDoc block form is ignored)` : `@nudo:import is a file-level directive \u2014 use '/// @nudo:import { a } from "./x.nudo.js"' at the top of the file (JSDoc block form is ignored)`
     });
   }
 }
+function warnMisplacedFileTagLine(tag) {
+  emitDirectiveDiag({
+    code: DIAG4.directiveSyntax,
+    message: tag === "env" ? `@nudo:env is a file-level directive \u2014 use '/// @nudo:env node' at the top of the file (line comment inside a function/class/object/array/destructuring body is ignored)` : `@nudo:mock-module is a file-level directive \u2014 use '/// @nudo:mock-module "fs" from "./mock-fs.js"' at the top of the file (line comment inside a function/class/object/array/destructuring body is ignored)`
+  });
+}
+function functionBodyRanges(ast) {
+  if (ast.type !== "File") return [];
+  return listFnDirectiveScopes2(ast).map((scope) => [
+    scope.node.start ?? 0,
+    scope.node.end ?? 0
+  ]);
+}
+function nestedBodyRanges(ast) {
+  const out = [];
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item);
+      return;
+    }
+    const n = node;
+    if ((n.type === "ClassBody" || n.type === "ObjectExpression" || n.type === "ArrayExpression" || n.type === "ObjectPattern" || n.type === "ArrayPattern") && typeof n.start === "number" && typeof n.end === "number") {
+      out.push([n.start, n.end]);
+    }
+    for (const key of Object.keys(n)) {
+      if (key === "loc" || key === "leadingComments" || key === "trailingComments" || key === "innerComments" || key === "comments" || key === "tokens" || key === "extra") {
+        continue;
+      }
+      visit(n[key]);
+    }
+  };
+  visit(ast);
+  return out;
+}
+function inRanges(ranges, offset) {
+  return ranges.some(([s, e]) => offset >= s && offset < e);
+}
 function extractFileDirectives(ast, opts) {
   if (!opts?.diags) return collectFileDirectives(ast);
   return runWithDirectiveDiags(opts.diags, () => collectFileDirectives(ast));
@@ -1144,6 +1558,8 @@ function collectFileDirectives(ast) {
   const results = [];
   if (ast.type !== "File") return results;
   const comments = ast.comments ?? [];
+  const fnRanges = functionBodyRanges(ast);
+  const bodyRanges = nestedBodyRanges(ast);
   for (const comment of comments) {
     if (comment.type === "CommentBlock") {
       warnMisplacedFileTags(comment.value);
@@ -1151,6 +1567,12 @@ function collectFileDirectives(ast) {
     }
     if (comment.type !== "CommentLine") continue;
     const text = comment.value;
+    const misplaced = typeof comment.start === "number" && (inRanges(fnRanges, comment.start) || inRanges(bodyRanges, comment.start));
+    if (misplaced) {
+      if (MOCK_MODULE_REGEX.test(text)) warnMisplacedFileTagLine("mock-module");
+      else if (ENV_REGEX.test(text) || ENV_BARE_REGEX.test(text)) warnMisplacedFileTagLine("env");
+      continue;
+    }
     const mockModuleMatch = text.match(MOCK_MODULE_REGEX);
     if (mockModuleMatch) {
       const rec = parseMockModulePayload(mockModuleMatch[1]);
@@ -1163,11 +1585,30 @@ function collectFileDirectives(ast) {
         });
         continue;
       }
+      emitDirectiveDiag({
+        code: DIAG4.directiveSyntax,
+        message: `Unrecognized @nudo:mock-module form (expected '"src" from "path"' or '"src" { a, b } from "path"')`
+      });
+      continue;
     }
     const envMatch = text.match(ENV_REGEX);
     if (envMatch) {
       const envs = parseEnvPayload(envMatch[1]);
-      if (envs.length > 0) results.push({ kind: "env", envs });
+      if (envs.length > 0) {
+        results.push({ kind: "env", envs });
+      } else {
+        emitDirectiveDiag({
+          code: DIAG4.directiveSyntax,
+          message: `Unrecognized @nudo:env list (expected env names, e.g. '/// @nudo:env node, web')`
+        });
+      }
+      continue;
+    }
+    if (ENV_BARE_REGEX.test(text)) {
+      emitDirectiveDiag({
+        code: DIAG4.directiveSyntax,
+        message: `@nudo:env requires at least one env name (e.g. '/// @nudo:env node')`
+      });
     }
   }
   return results;
@@ -1180,7 +1621,7 @@ import {
   extractNudoImportRecords,
   findFnDirectiveScope,
   fnDirectiveCommentLines,
-  listFnDirectiveScopes as listFnDirectiveScopes2,
+  listFnDirectiveScopes as listFnDirectiveScopes3,
   parseEnvPayload as parseEnvPayload2,
   parseMockModulePayload as parseMockModulePayload2,
   parseNudoImportPayload,
@@ -1222,7 +1663,7 @@ export {
   getFirstDeclaratorId,
   identifierName,
   isModuleExportsMember,
-  listFnDirectiveScopes2 as listFnDirectiveScopes,
+  listFnDirectiveScopes3 as listFnDirectiveScopes,
   memberObjectName,
   memberPropertyKey,
   memberPropertyName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nudojs/parser",
-  "version": "1.5.0",
+  "version": "1.5.3",
   "engines": {
     "node": ">=22"
   },
@@ -39,7 +39,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@nudojs/core": "1.15.0",
+    "@nudojs/core": "1.16.0",
     "@babel/types": "^8.0.6"
   },
   "scripts": {