@nudojs/parser 1.4.23 → 1.5.0

package/dist/index.d.ts

@@ -170,6 +170,7 @@ type FunctionWithDirectives = {
     name: string;
     directives: Directive[];
 };
+
 type DirectiveDiag = {
     code: string;
     message: string;
@@ -181,12 +182,6 @@ type DirectiveDiag = {
  * 的 D1 段）。fn 内显式传 diags 的 extract 自成新去重域。
  */
 declare function runWithDirectiveDiags<T>(diags: DirectiveDiag[], fn: () => T): T;
-/**
- * case 实参 / 指令类型表达式唯一文法：约束构建器优先，其余为具体字面量、
- * 结构字面量与箭头函数。`T.*` 文法已物理删除。
- * depth 按包含关系逐层 +1 线程化传递（兄弟共享父深度，不用共享可变计数器）。
- */
-declare function parseCaseArgExpr(expr: string, depth?: number): Abs;
 /**
  * extractDirectives 显式诊断通道 opts。
  *
@@ -198,6 +193,14 @@ declare function parseCaseArgExpr(expr: string, depth?: number): Abs;
 type ExtractDirectivesOpts = {
     diags?: DirectiveDiag[];
 };
+
+/**
+ * case 实参 / 指令类型表达式唯一文法：约束构建器优先，其余为具体字面量、
+ * 结构字面量与箭头函数。`T.*` 文法已物理删除。
+ * depth 按包含关系逐层 +1 线程化传递（兄弟共享父深度，不用共享可变计数器）。
+ */
+declare function parseCaseArgExpr(expr: string, depth?: number): Abs;
+
 /**
  * D6=G2：指令绑定 AST 最近 Function（含 nested function、class method）。
  * 作用域清单与 refine 的 @nudo:contract 同源（core directive-scan），
@@ -210,6 +213,7 @@ declare function extractDirectives(ast: Node, opts?: ExtractDirectivesOpts): Fun
  * 需要诊断的调用方用 extractDirectives(ast, { diags })。
  */
 declare function extractDirectivesQuiet(ast: Node): FunctionWithDirectives[];
+
 /**
  * 行内指令（@nudo:as / @nudo:replace）抽取，源为节点的 leadingComments。
  * 诊断通道与 extractDirectives 同形：传 opts.diags 落调用方数组（单次调用
@@ -217,6 +221,15 @@ declare function extractDirectivesQuiet(ast: Node): FunctionWithDirectives[];
  * runWithDirectiveDiags 域（无则丢弃，纯查询形态）。
  */
 declare function extractInlineDirectives(node: Node, opts?: ExtractDirectivesOpts): InlineDirective[];
-declare function extractFileDirectives(ast: Node): FileDirective[];
+
+/**
+ * 从 AST 抽文件级指令（`@nudo:env` / `@nudo:mock-module`，只认行注释）。
+ *
+ * `diags`：调用方自备的诊断累积数组——JSDoc/块注释内错位的文件级指令族
+ * 标签发 nudo:directive-syntax 警告（单次调用内同文案去重）。不传时为
+ * 纯查询形态：诊断丢弃；若外层有 runWithDirectiveDiags 活动域，则落入
+ * 该域并与其共享去重。
+ */
+declare function extractFileDirectives(ast: Node, opts?: ExtractDirectivesOpts): FileDirective[];
 
 export { type AsDirective, type CaseDirective, type Directive, type DirectiveDiag, type EnvDirective, type ExtractDirectivesOpts, type FileDirective, type FunctionWithDirectives, type InlineDirective, type InstanceMethod, type MockDirective, type MockModuleDirective, type PureDirective, type ReplaceDirective, type SampleDirective, type SinonExpression, type SkipDirective, asAssignmentExpression, asExpression, asIdentifier, asMemberExpression, asProgram, classIdName, classInstanceMethods, classMemberKey, classMemberKeyName, exportSpecifierExportedName, exportSpecifierLocalName, extractDirectives, extractDirectivesQuiet, extractFileDirectives, extractInlineDirectives, fnOrClassIdLoc, fnOrClassIdName, getClassMembers, getDeclarations, getDeclaratorId, getDeclaratorInit, getExportDeclaration, getExportSpecifiers, getExpressionStatementExpression, getFirstDeclaratorId, identifierName, isModuleExportsMember, memberObjectName, memberPropertyKey, memberPropertyName, methodFunctionNode, nameOrStringValue, paramDisplayName, paramName, parse, parseCaseArgExpr, programBody, runWithDirectiveDiags, unwrapDefaultExport, unwrapExport };

package/dist/index.js

@@ -175,37 +175,7 @@ function unwrapDefaultExport(mod) {
   return mod.default;
 }
 
-// src/directives.ts
-import {
-  stub,
-  spy,
-  mock,
-  abs as makeAbs,
-  numLit,
-  strLit,
-  boolLit,
-  absFunction,
-  joinAbs,
-  execNudoModule,
-  isNudoConstraint,
-  constraintToEntryAbs,
-  CONSTRAINT_BUILDER_NAMES,
-  CONSTRAINT_EXPR_RE,
-  SELF,
-  listFnDirectiveScopes,
-  parseEnvPayload,
-  parseMockModulePayload,
-  scanCaseArgSpans,
-  scanCaseTags,
-  extractBalancedParens
-} from "@nudojs/core";
-import { absLit } from "@nudojs/core/internal";
-function absExact(shape) {
-  return makeAbs(shape, void 0, void 0, "exact");
-}
-function absUnknown() {
-  return makeAbs({ k: "unknown" }, void 0, void 0, "partial");
-}
+// src/directives/diag.ts
 var activeDiagSink = null;
 function runWithDirectiveDiags(diags, fn) {
   const prev = activeDiagSink;
@@ -223,15 +193,158 @@ function emitDirectiveDiag(d) {
   activeDiagSink.seen.add(key);
   activeDiagSink.list.push(d);
 }
-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 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 SAMPLE_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*|\/[ \t]*)?@nudo:sample\b(?:[ \t]+(\S+))?/g;
-var SAMPLE_NUM_RE = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+// src/directives/case-arg.ts
+import {
+  abs as makeAbs,
+  absFunction,
+  joinAbs,
+  numLit,
+  strLit,
+  boolLit,
+  execNudoModule,
+  isNudoConstraint,
+  constraintToEntryAbs,
+  CONSTRAINT_BUILDER_NAMES,
+  CONSTRAINT_EXPR_RE,
+  SELF
+} from "@nudojs/core";
+import { absLit, DIAG } from "@nudojs/core/internal";
+
+// src/directives/expr-scan.ts
+function scanWithStrings(s, onChar, onStructural) {
+  let depth = 0;
+  let inString = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inString) {
+      onChar(ch, i);
+      if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      onChar(ch, i);
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") {
+      depth++;
+      onChar(ch, i);
+      onStructural(ch, i, depth);
+      continue;
+    }
+    if (ch === ")" || ch === "]" || ch === "}") {
+      depth--;
+      onChar(ch, i);
+      onStructural(ch, i, depth);
+      continue;
+    }
+    onChar(ch, i);
+    onStructural(ch, i, depth);
+  }
+}
+function splitTopLevelArgs(s) {
+  const result = [];
+  let current = "";
+  let depth = 0;
+  let inString = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inString) {
+      current += ch;
+      if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      current += ch;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") depth++;
+    if (ch === ")" || ch === "]" || ch === "}") depth--;
+    if (ch === "," && depth === 0) {
+      result.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) result.push(current.trim());
+  return result;
+}
+function findTopLevelColon(s) {
+  let found = -1;
+  scanWithStrings(
+    s,
+    () => {
+    },
+    (ch, i, depth) => {
+      if (found === -1 && ch === ":" && depth === 0) found = i;
+    }
+  );
+  return found;
+}
+function findTopLevelArrow(s) {
+  let depth = 0;
+  let inString = null;
+  for (let i = 0; i < s.length - 1; i++) {
+    const ch = s[i];
+    if (inString) {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") depth--;
+    else if (depth === 0 && ch === "=" && s[i + 1] === ">") return i;
+  }
+  return -1;
+}
+function parseArrowFunctionExpr(expr) {
+  try {
+    const wrapped = `const __mock = ${expr};`;
+    const ast = parse(wrapped);
+    const decl = ast.program.body[0];
+    if (decl.type !== "VariableDeclaration") return null;
+    const init = decl.declarations[0]?.init;
+    if (!init || init.type !== "ArrowFunctionExpression" && init.type !== "FunctionExpression") {
+      return null;
+    }
+    const params = [];
+    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);
+      }
+    }
+    return { params, body: init.body, paramPatterns };
+  } catch {
+    return null;
+  }
+}
+
+// src/directives/case-arg.ts
+function absExact(shape) {
+  return makeAbs(shape, void 0, void 0, "exact");
+}
+function absUnknown() {
+  return makeAbs({ k: "unknown" }, void 0, void 0, "partial");
+}
 var TYPE_EXPR_CHAIN_METHODS = /* @__PURE__ */ new Set([
   "gt",
   "ge",
@@ -306,7 +419,7 @@ function tryParseConstraint(expr) {
   if (!CONSTRAINT_EXPR_RE.test(s)) return void 0;
   if (!isSafeTypeExprSource(s)) {
     emitDirectiveDiag({
-      code: "nudo:directive-syntax",
+      code: DIAG.directiveSyntax,
       message: `Unsafe constraint expression rejected: ${s.slice(0, 80)} (only builder calls, chain methods, and literals are allowed)`
     });
     return void 0;
@@ -385,7 +498,7 @@ function constraintToCaseArgAbs(c, depth) {
 var MAX_CASE_ARG_DEPTH = 32;
 function depthCapDiag(expr) {
   emitDirectiveDiag({
-    code: "nudo:directive-syntax",
+    code: DIAG.directiveSyntax,
     message: `Type expression nesting exceeds depth ${MAX_CASE_ARG_DEPTH}: ${expr.trim().slice(0, 40)} \u2026 (deeper structure collapses to unknown)`
   });
   return absUnknown();
@@ -454,131 +567,6 @@ function parseObjectLiteral(content, depth) {
   }
   return absExact({ k: "obj", slots });
 }
-function scanWithStrings(s, onChar, onStructural) {
-  let depth = 0;
-  let inString = null;
-  for (let i = 0; i < s.length; i++) {
-    const ch = s[i];
-    if (inString) {
-      onChar(ch, i);
-      if (ch === inString) inString = null;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      inString = ch;
-      onChar(ch, i);
-      continue;
-    }
-    if (ch === "(" || ch === "[" || ch === "{") {
-      depth++;
-      onChar(ch, i);
-      onStructural(ch, i, depth);
-      continue;
-    }
-    if (ch === ")" || ch === "]" || ch === "}") {
-      depth--;
-      onChar(ch, i);
-      onStructural(ch, i, depth);
-      continue;
-    }
-    onChar(ch, i);
-    onStructural(ch, i, depth);
-  }
-}
-function splitTopLevelArgs(s) {
-  const result = [];
-  let current = "";
-  let depth = 0;
-  let inString = null;
-  for (let i = 0; i < s.length; i++) {
-    const ch = s[i];
-    if (inString) {
-      current += ch;
-      if (ch === inString) inString = null;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      inString = ch;
-      current += ch;
-      continue;
-    }
-    if (ch === "(" || ch === "[" || ch === "{") depth++;
-    if (ch === ")" || ch === "]" || ch === "}") depth--;
-    if (ch === "," && depth === 0) {
-      result.push(current.trim());
-      current = "";
-      continue;
-    }
-    current += ch;
-  }
-  if (current.trim()) result.push(current.trim());
-  return result;
-}
-function findTopLevelColon(s) {
-  let found = -1;
-  scanWithStrings(
-    s,
-    () => {
-    },
-    (ch, i, depth) => {
-      if (found === -1 && ch === ":" && depth === 0) found = i;
-    }
-  );
-  return found;
-}
-function findTopLevelArrow(s) {
-  let depth = 0;
-  let inString = null;
-  for (let i = 0; i < s.length - 1; i++) {
-    const ch = s[i];
-    if (inString) {
-      if (ch === "\\") {
-        i++;
-        continue;
-      }
-      if (ch === inString) inString = null;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      inString = ch;
-      continue;
-    }
-    if (ch === "(" || ch === "[" || ch === "{") depth++;
-    else if (ch === ")" || ch === "]" || ch === "}") depth--;
-    else if (depth === 0 && ch === "=" && s[i + 1] === ">") return i;
-  }
-  return -1;
-}
-function parseArrowFunctionExpr(expr) {
-  try {
-    const wrapped = `const __mock = ${expr};`;
-    const ast = parse(wrapped);
-    const decl = ast.program.body[0];
-    if (decl.type !== "VariableDeclaration") return null;
-    const init = decl.declarations[0]?.init;
-    if (!init || init.type !== "ArrowFunctionExpression" && init.type !== "FunctionExpression") {
-      return null;
-    }
-    const params = [];
-    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);
-      }
-    }
-    return { params, body: init.body, paramPatterns };
-  } catch {
-    return null;
-  }
-}
 function isExplicitUnknownExpr(expr) {
   const s = expr.trim();
   return s === "unknown" || s === "any" || s === "any()";
@@ -590,42 +578,24 @@ function parseAbsExprDiag(expr, context) {
   const abs = parseCaseArgExpr(expr);
   if (abs.shape.k === "unknown" && !abs.term && !isExplicitUnknownExpr(expr)) {
     emitDirectiveDiag({
-      code: "nudo:directive-syntax",
+      code: DIAG.directiveSyntax,
       message: `Unrecognized type expression in ${context}: ${expr.trim()} (use constraint builders, literals, or structure syntax)`
     });
   }
   return abs;
 }
-function parseSkipReturnsExpr(rest) {
-  if (rest === void 0) return void 0;
-  const s = rest.trim();
-  if (s === "") return void 0;
-  if (s.startsWith("=>")) {
-    const expr = s.slice(2).trim();
-    if (expr === "") {
-      emitDirectiveDiag({
-        code: "nudo:directive-syntax",
-        message: `@nudo:skip => requires a type expression (e.g. @nudo:skip => number())`
-      });
-      return void 0;
-    }
-    return parseAbsExprDiag(expr, "@nudo:skip =>");
-  }
-  if (s.startsWith("(")) {
-    const inner = extractBalancedParens(s, 0);
-    if (inner !== null && s.slice(inner.length + 2).trim() === "") {
-      return parseAbsExprDiag(inner, "@nudo:skip (...)");
-    }
-    if (inner === null) {
-      emitDirectiveDiag({
-        code: "nudo:directive-syntax",
-        message: `@nudo:skip type expression has unclosed parenthesis (expected @nudo:skip (<typeExpr>)) \u2014 got: ${s.slice(0, 60)}`
-      });
-      return void 0;
-    }
-  }
-  return void 0;
-}
+
+// src/directives/fn-directives.ts
+import {
+  extractBalancedParens,
+  listFnDirectiveScopes,
+  scanCaseArgSpans,
+  scanCaseTags
+} from "@nudojs/core";
+import { DIAG as DIAG2 } from "@nudojs/core/internal";
+
+// src/directives/mock-expr.ts
+import { absFunction as absFunction2, mock, spy, stub } from "@nudojs/core";
 function parseSinonExpr(expr) {
   const s = expr.trim();
   const stubReturnsMatch = s.match(/^sinon\.stub\(\)\.returns\((.+)\)$/);
@@ -690,7 +660,7 @@ function parseSinonExpr(expr) {
     if (arrowFn) {
       return {
         type: "stub",
-        returnValue: absFunction(arrowFn.params, {
+        returnValue: absFunction2(arrowFn.params, {
           body: arrowFn.body
         })
       };
@@ -790,6 +760,47 @@ function parseNudoMockExpr(expr) {
   }
   return null;
 }
+
+// src/directives/fn-directives.ts
+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 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 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();
+  if (s === "") return void 0;
+  if (s.startsWith("=>")) {
+    const expr = s.slice(2).trim();
+    if (expr === "") {
+      emitDirectiveDiag({
+        code: DIAG2.directiveSyntax,
+        message: `@nudo:skip => requires a type expression (e.g. @nudo:skip => number())`
+      });
+      return void 0;
+    }
+    return parseAbsExprDiag(expr, "@nudo:skip =>");
+  }
+  if (s.startsWith("(")) {
+    const inner = extractBalancedParens(s, 0);
+    if (inner !== null && s.slice(inner.length + 2).trim() === "") {
+      return parseAbsExprDiag(inner, "@nudo:skip (...)");
+    }
+    if (inner === null) {
+      emitDirectiveDiag({
+        code: DIAG2.directiveSyntax,
+        message: `@nudo:skip type expression has unclosed parenthesis (expected @nudo:skip (<typeExpr>)) \u2014 got: ${s.slice(0, 60)}`
+      });
+      return void 0;
+    }
+  }
+  return void 0;
+}
 function parseDirectivesFromCommentTexts(comments) {
   const directives = [];
   for (const { text, startLine: commentStartLine } of comments) {
@@ -880,7 +891,7 @@ function parseDirectivesFromCommentTexts(comments) {
       const raw = sampleMatch[1];
       if (raw === void 0 || !SAMPLE_NUM_RE.test(raw)) {
         emitDirectiveDiag({
-          code: "nudo:directive-syntax",
+          code: DIAG2.directiveSyntax,
           message: `Malformed @nudo:sample: expected a numeric count (integer, decimal, or negative) \u2014 got: @nudo:sample ${raw ?? "(missing count)"}`
         });
         continue;
@@ -902,7 +913,7 @@ function scanMalformedCaseNames(text, caseArgSpans) {
       const parenIdx = m.index + m[0].length - m[1].length + legal[0].length - 1;
       if (extractBalancedParens(text, parenIdx) === null) {
         emitDirectiveDiag({
-          code: "nudo:directive-syntax",
+          code: DIAG2.directiveSyntax,
           message: `Malformed @nudo:case: unclosed argument list (missing closing ")") \u2014 got: @nudo:case ${rest.slice(0, 60)}`
         });
       }
@@ -921,7 +932,7 @@ function scanMalformedCaseNames(text, caseArgSpans) {
       reason = `missing quoted name (expected @nudo:case "name" (\u2026))`;
     }
     emitDirectiveDiag({
-      code: "nudo:directive-syntax",
+      code: DIAG2.directiveSyntax,
       message: `Malformed @nudo:case: ${reason} \u2014 got: @nudo:case ${rest.slice(0, 60)}`
     });
   }
@@ -936,7 +947,7 @@ function scanMalformedMockNames(text, caseArgSpans) {
     const nameMatch = rest.match(/^([^\s=]+)(?:\s*=|\s+from\b)/);
     if (!nameMatch) {
       emitDirectiveDiag({
-        code: "nudo:directive-syntax",
+        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)}`
       });
       continue;
@@ -944,7 +955,7 @@ function scanMalformedMockNames(text, caseArgSpans) {
     const name = nameMatch[1];
     if (!JS_IDENT_RE.test(name)) {
       emitDirectiveDiag({
-        code: "nudo:directive-syntax",
+        code: DIAG2.directiveSyntax,
         message: `Malformed @nudo:mock name '${name}': not a valid identifier (use letters, digits, _, $; Unicode letters allowed)`
       });
       continue;
@@ -952,7 +963,7 @@ function scanMalformedMockNames(text, caseArgSpans) {
     const afterName = rest.slice(name.length);
     if (/^[ \t]+from[ \t]+(?:"[^"\n]*|'[^'\n]*)$/.test(afterName)) {
       emitDirectiveDiag({
-        code: "nudo:directive-syntax",
+        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)}`
       });
     }
@@ -960,13 +971,7 @@ function scanMalformedMockNames(text, caseArgSpans) {
 }
 function extractDirectives(ast, opts) {
   if (!opts?.diags) return collectFnDirectives(ast);
-  const prev = activeDiagSink;
-  activeDiagSink = { list: opts.diags, seen: /* @__PURE__ */ new Set() };
-  try {
-    return collectFnDirectives(ast);
-  } finally {
-    activeDiagSink = prev;
-  }
+  return runWithDirectiveDiags(opts.diags, () => collectFnDirectives(ast));
 }
 function collectFnDirectives(ast) {
   const results = [];
@@ -987,6 +992,10 @@ function collectFnDirectives(ast) {
 function extractDirectivesQuiet(ast) {
   return extractDirectives(ast, { diags: [] });
 }
+
+// src/directives/inline-directives.ts
+import { CONSTRAINT_EXPR_RE as CONSTRAINT_EXPR_RE2 } from "@nudojs/core";
+import { DIAG as DIAG3 } from "@nudojs/core/internal";
 function stripInlineCommentPrefix(line, kind) {
   const s = kind === "block" ? line.replace(/^\s*\*\s?/, "") : line.replace(/^\//, "");
   return s.trim();
@@ -1017,13 +1026,7 @@ function extractInlineDirectives(node, opts) {
   const comments = node.leadingComments;
   if (!comments) return [];
   if (!opts?.diags) return collectInlineDirectivesFromComments(comments);
-  const prev = activeDiagSink;
-  activeDiagSink = { list: opts.diags, seen: /* @__PURE__ */ new Set() };
-  try {
-    return collectInlineDirectivesFromComments(comments);
-  } finally {
-    activeDiagSink = prev;
-  }
+  return runWithDirectiveDiags(opts.diags, () => collectInlineDirectivesFromComments(comments));
 }
 function collectInlineDirectivesFromComments(comments) {
   const results = [];
@@ -1039,7 +1042,7 @@ function collectInlineDirectivesFromComments(comments) {
         if (trailingIdx !== -1) {
           const typePart = rawExpr.slice(0, trailingIdx).trim();
           emitDirectiveDiag({
-            code: "nudo:directive-syntax",
+            code: DIAG3.directiveSyntax,
             message: `Trailing comment in @nudo:as type expression: '${rawExpr}' (remove the comment; the type must be a clean expression)`
           });
           results.push({ kind: "as", typeAbs: typePart ? parseAbsExprDiag(typePart, "@nudo:as") : absUnknown() });
@@ -1050,7 +1053,7 @@ function collectInlineDirectivesFromComments(comments) {
       }
       if (AS_BARE_RE.test(line)) {
         emitDirectiveDiag({
-          code: "nudo:directive-syntax",
+          code: DIAG3.directiveSyntax,
           message: `@nudo:as requires a type expression (e.g. @nudo:as number())`
         });
         continue;
@@ -1069,7 +1072,7 @@ function collectInlineDirectivesFromComments(comments) {
           });
         } else {
           emitDirectiveDiag({
-            code: "nudo:directive-syntax",
+            code: DIAG3.directiveSyntax,
             message: `Malformed @nudo:replace: cannot separate target from type (expected @nudo:replace <target> <typeExpr>) \u2014 got: ${raw.slice(0, 60)}`
           });
         }
@@ -1077,7 +1080,7 @@ function collectInlineDirectivesFromComments(comments) {
       }
       if (REPLACE_BARE_RE.test(line)) {
         emitDirectiveDiag({
-          code: "nudo:directive-syntax",
+          code: DIAG3.directiveSyntax,
           message: `@nudo:replace requires a target and type expression (expected @nudo:replace <target> <typeExpr>)`
         });
       }
@@ -1108,20 +1111,44 @@ function findReplaceSeparator(raw) {
     }
     if (ch === " " && depth === 0) {
       const rest = raw.slice(i + 1).trimStart();
-      if (CONSTRAINT_EXPR_RE.test(rest) || rest.startsWith("{") || rest.startsWith("[") || rest.startsWith('"') || rest.startsWith("'") || rest === "true" || rest === "false" || rest === "null" || rest === "undefined" || rest === "unknown" || rest === "any" || rest === "never" || /^-?\d+(\.\d+)?$/.test(rest) || rest.includes("=>") || /^function\s*[\w$]*\s*\(/.test(rest)) {
+      if (CONSTRAINT_EXPR_RE2.test(rest) || rest.startsWith("{") || rest.startsWith("[") || rest.startsWith('"') || rest.startsWith("'") || rest === "true" || rest === "false" || rest === "null" || rest === "undefined" || rest === "unknown" || rest === "any" || rest === "never" || /^-?\d+(\.\d+)?$/.test(rest) || rest.includes("=>") || /^function\s*[\w$]*\s*\(/.test(rest)) {
         return i;
       }
     }
   }
   return -1;
 }
+
+// src/directives/file-directives.ts
+import { parseEnvPayload, parseMockModulePayload } from "@nudojs/core";
+import { DIAG as DIAG4 } from "@nudojs/core/internal";
 var ENV_REGEX = /^\/?\s*@nudo:env\s+(.+)/;
 var MOCK_MODULE_REGEX = /^\/?\s*@nudo:mock-module\s+(.+)/;
-function extractFileDirectives(ast) {
+var FILE_TAG_IN_BLOCK_REGEX = /(?:^|\n)[ \t]*(?:\*[ \t]*)?@nudo:(env|mock-module)\b/g;
+function warnMisplacedFileTags(blockText) {
+  FILE_TAG_IN_BLOCK_REGEX.lastIndex = 0;
+  let m;
+  while (m = FILE_TAG_IN_BLOCK_REGEX.exec(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)`
+    });
+  }
+}
+function extractFileDirectives(ast, opts) {
+  if (!opts?.diags) return collectFileDirectives(ast);
+  return runWithDirectiveDiags(opts.diags, () => collectFileDirectives(ast));
+}
+function collectFileDirectives(ast) {
   const results = [];
   if (ast.type !== "File") return results;
   const comments = ast.comments ?? [];
   for (const comment of comments) {
+    if (comment.type === "CommentBlock") {
+      warnMisplacedFileTags(comment.value);
+      continue;
+    }
     if (comment.type !== "CommentLine") continue;
     const text = comment.value;
     const mockModuleMatch = text.match(MOCK_MODULE_REGEX);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nudojs/parser",
-  "version": "1.4.23",
+  "version": "1.5.0",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "description": "Babel-based parser and directive extraction for Nudo",
   "type": "module",
@@ -39,7 +39,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@nudojs/core": "1.14.0",
+    "@nudojs/core": "1.15.0",
     "@babel/types": "^8.0.6"
   },
   "scripts": {