Skip to main content

@nudojs/parser

The parser package handles source code parsing and directive extraction. It produces Babel-compatible ASTs and structured directive data for the evaluator.

parse​

parse(source: string, opts?: { errorRecovery?: boolean }): File

Parses JavaScript/TypeScript source into a Babel File AST, then runs stripTypes on it — the returned AST contains no TS-only nodes, which is why .ts inputs work in every downstream consumer (evaluator, analyzer, LSP) without per-caller wiring.

Fixed Babel options: sourceType: "module", plugins: ["typescript", "jsx"], attachComment: true (required for directive extraction).

opts.errorRecovery enables Babel error recovery for best-effort passes (e.g. collectCallRecords over legacy CJS usage-site files); the default false fails fast on syntax errors.

Returns: Babel File node (root AST), with TS-only syntax stripped in place.


stripTypes​

stripTypes<T extends Node>(ast: T): T

Strips TS-only syntax from a Babel AST in place and returns the same tree — no loc/start/end is rewritten and sibling order is preserved (@nudo:case comments align by comment loc). parse() runs this pass unconditionally, so you only need it directly when you parsed with @babel/parser yourself.

What it removes or unwraps: type assertions (as, satisfies, <T>x, x!) are unwrapped to their expression; interfaces, type aliases, declare statements, TS enums, and type-only imports/exports are deleted; parameter/return type annotations and type parameter lists are dropped. Enum references degrade to unknown-global diagnostics — the evaluator has no enum semantics. Non-declare namespaces and import x = require(...) are left in place and evaluate as unknown.


Directive Types​

Directives are extracted from comments using the @nudo: namespace. Function-level directives come from the leading comments (block or line) of top-level statements; file-level and inline directives come from line comments (see extractFileDirectives / extractInlineDirectives).

The Directive union covers the five function-level kinds:

type Directive =
| CaseDirective
| MockDirective
| PureDirective
| SkipDirective
| SampleDirective;

CaseDirective​

type CaseDirective = {
kind: "case";
name: string;
argsAbs: Abs[];
expected?: Abs;
commentLine?: number;
}

Debug witness case with input arguments (constraint builders + concrete literals). Optional expected for nudo test return-type assertions.

MockDirective​

type MockDirective = {
kind: "mock";
name: string;
expression?: string; // inline expression (raw text)
fromPath?: string; // path to mock module
arrowFn?: { params: string[]; body: Node; paramPatterns: Node[] }; // parsed inline arrow function
sinonExpr?: SinonExpression; // stub()/spy()/mock() expression
nudoMock?: MockHelper; // parsed mock-helper form (from @nudojs/core)
}

Replaces a binding with an Abs-aware mock implementation. An inline arrow function (@nudo:mock fetch = (url) => ({ ok: true })) is parsed into arrowFn; sinon-style and stub()-style expressions are normalized into nudoMock (a MockHelper from @nudojs/core).

SinonExpression​

type SinonExpression = {
type: "stub" | "spy" | "mock";
returnValue?: Abs;
resolvedValue?: Abs;
rejectedValue?: Abs;
}

The sinon-flavored form of @nudo:mock (@nudo:mock fetch = sinon.stub().resolves({...})), normalized from the stub()/spy()/mock() prefix.

PureDirective​

type PureDirective = { kind: "pure" }

Marks the function as pure for memoization.

SkipDirective​

type SkipDirective = {
kind: "skip";
returns?: Abs;
}

Skips evaluation; uses returns or existing type annotations.

SampleDirective​

type SampleDirective = {
kind: "sample";
count: number;
}

Requested loop iteration count. Parsed for source compatibility but not consumed by the analyzer — loop evaluation uses bounded unrolling, so this directive has no effect on output.

FileDirective​

Line comments anywhere in the file, shared by every function in it:

type FileDirective = EnvDirective | MockModuleDirective;

type EnvDirective = {
kind: "env";
envs: string[]; // named or path-based envs, comma-separated
}

type MockModuleDirective = {
kind: "mock-module";
source: string; // import specifier to replace
fromPath: string; // file providing the mock module
names?: string[]; // partial form: only these exports are mocked
}

InlineDirective​

Line comments attached to an inner statement or expression:

type InlineDirective = AsDirective | ReplaceDirective;

type AsDirective = {
kind: "as";
typeAbs: Abs; // assumed type: // @nudo:as string
}

type ReplaceDirective = {
kind: "replace";
targetSource: string; // expression text to override
typeAbs: Abs; // replacement type
}

FunctionWithDirectives​

type FunctionWithDirectives = {
node: Node; // Babel AST node (function declaration/expression)
name: string; // function name
directives: Directive[];
}

A top-level function with its associated directives.


extractDirectives​

extractDirectives(ast: Node): FunctionWithDirectives[]

Extracts @nudo:* directives from the leading comments (block or line) of top-level statements. Only statements with at least one directive are included. Supports:

  • FunctionDeclaration
  • ExportDefaultDeclaration (with FunctionDeclaration)
  • VariableDeclaration (first declaration)

Returns: Array of functions with their directives, one entry per annotated statement.


extractFileDirectives​

extractFileDirectives(ast: Node): FileDirective[]

Extracts file-level directives from the AST's line comments (any position): /// @nudo:env (one or more comma-separated envs) and /// @nudo:mock-module "source" from "path" (optionally with a { a, b } names list for partial mocking). Non-File nodes return an empty array.

Example:

/// @nudo:env node, ./nudo-harvest-node.ts

extractInlineDirectives​

extractInlineDirectives(node: Node): InlineDirective[]

Extracts @nudo:as and @nudo:replace directives from the line comments attached to a single node — the mechanism behind agent-side type assumptions (nudo.whatIf injects // @nudo:as <type> lines this way). The comment must sit on its own line above the statement (a same-line trailing comment is not a leading comment of the node); other comment types are ignored.

Example:

// @nudo:as string()
const y = f(x);

parseCaseArgExpr​

parseCaseArgExpr(expr: string): Abs

Parses a directive type expression into an Abs — the product grammar is constraint builders + concrete literals + structural literals. Used for @nudo:case args, @nudo:as/@nudo:replace, mock return values, and @nudo:skip return expressions.

Supported forms (in precedence order):

  • Constraint expressions (primary grammar): number(), number().gt(0), lit(...), union(…), shape({…}), array(…), fn({…}, …), and, partial/pick/omit
  • Bare literals: true, false, null, undefined, numbers, quoted strings
  • Functions: arrow expressions ((x) => x + 1) and function(x) { ... } — parsed into a real function Abs
  • JSON-like: { "key": value }, [a, b, c]

Returns: Parsed Abs, or unknown for unrecognized expressions.

Export inventory​

Generated by node scripts/gen-api-docs.mjs from package export surfaces (PUBLIC_API.md / src/index.ts) — do not edit this block (or regenerate via pnpm run docs:gen). Summaries quote the source JSDoc first sentence as-is — CJK text means the symbol's doc is not yet English, and — means no JSDoc at all. Each row's name carries a stable anchor #slug (the lowercased symbol name).

NameKindSummarySignature
asAssignmentExpressionfn—asAssignmentExpression( node: Node | null | undefined, ): AssignmentExpression | undefined
AsDirectivetype—AsDirective = { kind: "as"; typeAbs: Abs; }
asExpressionfn—asExpression(node: Node | null | undefined): Expression | undefined
asIdentifierfn—asIdentifier(node: Node | null | undefined): Identifier | undefined
asMemberExpressionfn—asMemberExpression( node: Node | null | undefined, ): MemberExpression | undefined
asProgramfnFile → its Program; Program → itself.asProgram(ast: Node | File | Program | null | undefined): Program | undefined
CaseDirectivetype—CaseDirective = { kind: "case"; name: string; argsAbs: Abs[]; expected?: Abs; commentLine?: number; }
CaseTagtype——
classIdNamefnClassDeclaration/ClassExpression id?.name.classIdName(node: Node | null | undefined): string | undefined
classInstanceMethodsfnInstance methods of a class-like node.classInstanceMethods(node: Node | null | undefined): InstanceMethod[]
classMemberKeyfnKey node of a class member (for range selection).classMemberKey(member: Node | null | undefined): Node | undefined
classMemberKeyNamefnkey.name ?? key.value on a class/object member key.classMemberKeyName(member: Node | null | undefined): string | number | undefined
Directivetype—Directive = CaseDirective | MockDirective | PureDirective | SkipDirective | SampleDirective
DirectiveDiagtype指令文法诊断。DirectiveDiag = { code: string; message: string; at?: { line: number; column: number }; }
EnvDirectivetype—EnvDirective = { kind: "env"; envs: string[]; }
exportSpecifierExportedNamefnExportSpecifier exported name (exported.name ?? exported.value).exportSpecifierExportedName( spec: Node | null | undefined, ): string | number | undefined
exportSpecifierLocalNamefnExportSpecifier local name — Identifier only (matches local.name).exportSpecifierLocalName(spec: Node | null | undefined): string | undefined
extractDirectivesfnD6=G2:指令绑定 AST 最近 Function(含 nested function、class method)。extractDirectives( ast: Node, opts?: ExtractDirectivesOpts, ): FunctionWithDirectives[]
ExtractDirectivesOptstypeextractDirectives 显式诊断通道 opts。ExtractDirectivesOpts = { diags?: DirectiveDiag[]; }
extractDirectivesQuietfn纯查询 extract:诊断丢弃——hover/completion/collectSkipReturns 等探测 路径不产诊断(不污染消费方待收的诊断,也不背走别人的在途诊断)。extractDirectivesQuiet(ast: Node): FunctionWithDirectives[]
extractFileDirectivesfn从 AST 抽文件级指令(@nudo:env / @nudo:mock-module,只认行注释)。extractFileDirectives(ast: Node, opts?: ExtractDirectivesOpts): FileDirective[]
extractFileEnvNamesconst——
extractInlineDirectivesfn行内指令(@nudo:as / @nudo:replace)抽取,源为节点的 leadingComments。extractInlineDirectives( node: Node, opts?: ExtractDirectivesOpts, ): InlineDirective[]
extractMockModuleRecordsconst——
extractNudoImportRecordsconst——
FileDirectivetype—FileDirective = EnvDirective | MockModuleDirective
findFnDirectiveScopeconst——
fnDirectiveCommentLinesconst——
FnDirectiveScopetype——
fnOrClassIdLocfnid.loc of a named function/class (undefined when anonymous or unlocated).fnOrClassIdLoc(node: Node | null | undefined): Node
fnOrClassIdNamefnFunction/Class declaration or expression id?.name.fnOrClassIdName(node: Node | null | undefined): string | undefined
FunctionWithDirectivestype—FunctionWithDirectives = { node: Node; name: string; directives: Directive[]; depth?: number; }
getClassMembersfnClass body members; empty when node is not a class.getClassMembers(node: Node | null | undefined): ClassBody
getDeclarationsfnVariableDeclaration.declarations; empty for other nodes.getDeclarations(node: Node | null | undefined): VariableDeclarator[]
getDeclaratorIdfnVariableDeclarator id narrowed to Identifier.getDeclaratorId(node: Node | null | undefined): Identifier | undefined
getDeclaratorInitfnFirst declarator's init (fn-binding extraction).getDeclaratorInit(node: Node | null | undefined): Expression | undefined
getExportDeclarationfnInner declaration of export default / export … (undefined for other nodes).getExportDeclaration(node: Node | null | undefined): Node | undefined
getExportSpecifiersfnExportNamedDeclaration.specifiers (empty for other nodes).getExportSpecifiers( node: Node | null | undefined, )
getExpressionStatementExpressionfnExpressionStatement.expression.getExpressionStatementExpression( node: Node | null | undefined, ): Expression | undefined
getFirstDeclaratorIdfnFirst declarator of a VariableDeclaration, narrowed to Identifier id.getFirstDeclaratorId(node: Node | null | undefined): Identifier | undefined
identifierNamefnIdentifier.name only (undefined for string export names).identifierName(node: Node | null | undefined): string | undefined
InlineDirectivetype—InlineDirective = AsDirective | ReplaceDirective
InstanceMethodtype—InstanceMethod = { name: string; node: Node }
isModuleExportsMemberfnmodule.exports / module["exports"] is rejected here: computed keys return false.isModuleExportsMember(member: Node | null | undefined): boolean
listFnDirectiveScopesconst——
memberObjectNamefnIdentifier name of a non-computed member's object (e.g.memberObjectName(member: Node | null | undefined): string | undefined
memberPropertyKeyfnNon-computed member property key text (Identifier.name or StringLiteral.value).memberPropertyKey(member: Node | null | undefined): string | null
memberPropertyNamefnIdentifier name of a non-computed member's property (e.g.memberPropertyName(member: Node | null | undefined): string | undefined
methodFunctionNodefnClass/TSDeclare method function node (ESTree MethodDefinition → its value).methodFunctionNode(member: Node | null | undefined): Node | undefined
MockDirectivetype—MockDirective = { kind: "mock"; name: string; expression?: string; fromPath?: string; arrowFn?: { params: string[]; body: Node; paramPatt...
MockModuleDirectivetype—MockModuleDirective = { kind: "mock-module"; source: string; names?: string[]; fromPath: string; }
MockModuleRecordtype——
nameOrStringValuefnIdentifier.name, else StringLiteral.value (module string export names).nameOrStringValue(node: Node | null | undefined): string | undefined
NudoImportRecordtype——
paramDisplayNamefnParameter display label: name, ...rest, or _.paramDisplayName(param: Node | null | undefined): string
parsefn所有权:Babel 解析与 TS 剥除的实现在 @nudojs/core (algebra/parse-source.ts / strip-types.ts)—— core 代数层 (check/scan/generalize)需要 AST 且不能反向依赖本包。本包职责是 @nudo: 指令抽取与 AST 卫兵;parse() 是宿主入口,委托 core 同一实现与 AST LRU。parse( source: string, opts?: { errorRecovery?: boolean; filename?: string }, ): File
parseCaseArgExprfncase 实参 / 指令类型表达式唯一文法:约束构建器优先,其余为具体字面量、 结构字面量与箭头函数。T.* 文法已物理删除。parseCaseArgExpr(expr: string, depth = 0): Abs
parseEnvPayloadconst——
parseMockModulePayloadconst——
parseNudoImportPayloadconst——
programBodyfnTop-level statements of a File/Program (empty when neither).programBody(ast: Node | File | Program | null | undefined): Statement[]
PureDirectivetype—PureDirective = { kind: "pure"; }
ReplaceDirectivetype—ReplaceDirective = { kind: "replace"; targetSource: string; typeAbs: Abs; }
runWithDirectiveDiagsfn在指定诊断数组上执行 fn:fn 内所有指令文法诊断(含不传 diags 的 extract 与再解析路径,如 @nudo:mock 表达式的 parseCaseArgExpr 复解析)落袋并共用 同一去重域——用于「extract + 复解析」必须共享 seen 的窗口(nudojs check 的 D1 段)。fn 内显式传 diags 的 extract 自成新去重域。runWithDirectiveDiags<T>(diags: DirectiveDiag[], fn: () => T): T
SampleDirectivetype—SampleDirective = { kind: "sample"; count: number; }
scanBudgetDeclconst——
scanCaseTagsconst——
scanContractSegmentsconst——
scanThrowsDeclconst——
SinonExpressiontype—SinonExpression = { type: "stub" | "spy" | "mock"; returnValue?: Abs; resolvedValue?: Abs; rejectedValue?: Abs; }
SkipDirectivetype—SkipDirective = { kind: "skip"; returns?: Abs; }
stripTypesconst——
unwrapDefaultExportfnCJS/ESM default interop: callable module or { default } wrapper.unwrapDefaultExport<T>(mod: T | { default: T }): T
unwrapExportfnUnwrap an export form: named/default exports yield their inner declaration with exported: true; any other statement is returned as-is with exported: false.unwrapExport(node: Node | null | undefined)