@nudojs/parser 1.0.0 → 1.1.0

package/README.md

@@ -4,15 +4,15 @@ Babel-based parser and directive extraction for [Nudo](https://github.com/nudojs
 
 ## What is Nudo?
 
-Nudo is a type inference engine for JavaScript. Instead of a separate type system, it runs your code with symbolic type values via abstract interpretation — no TypeScript, no build step.
+Nudo is a type inference engine for JavaScript. The type system is Abs (`shape × term × pred × conf`); analysis runs Abs-native via abstract interpretation — no TypeScript, no build step.
 
 ## This package
 
 `@nudojs/parser` handles source code parsing and Nudo directive extraction:
 
 - **Parsing** — wraps Babel parser for JavaScript/TypeScript source files
-- **Directives** — extracts `@nudo:case`, `@nudo:mock`, `@nudo:pure`, `@nudo:skip`, `@nudo:sample`, `@nudo:env`, `@nudo:mock-module`, `@nudo:as`, and `@nudo:replace` from comments. `@nudo:refine` / `@nudo:import` are parsed in `@nudojs/core` (`algebra/refine.ts`).
-- **Type expressions** — parses inline type value expressions used in directives
+- **Directives** — extracts `@nudo:case`, `@nudo:mock`, `@nudo:pure`, `@nudo:skip`, `@nudo:sample`, `@nudo:env`, `@nudo:mock-module`, `@nudo:as`, and `@nudo:replace` from comments. `@nudo:contract` / `@nudo:import` are parsed in `@nudojs/core` (`algebra/refine.ts`).
+- **Case arg expressions** — parses constraint builders and concrete literals used in directives
 
 ## Install
 

package/dist/index.d.ts

@@ -1,9 +1,13 @@
-import { File, Node } from '@babel/types';
+import { File, Node, AssignmentExpression, Expression, Identifier, MemberExpression, Program, ClassBody, VariableDeclarator, ExportSpecifier, ExportDefaultSpecifier, ExportNamespaceSpecifier, Statement } from '@babel/types';
 import { Abs, MockHelper } from '@nudojs/core';
 export { stripTypes } from '@nudojs/core';
 
 /**
- * 与 core `parseSource` 同一实现与 AST LRU：
+ * 所有权：Babel 解析与 TS 剥除的**实现**在 `@nudojs/core`
+ * （`algebra/parse-source.ts` / `strip-types.ts`）—— core 代数层
+ * （check/scan/generalize）需要 AST 且不能反向依赖本包。本包职责是
+ * `@nudo:` 指令抽取与 AST 卫兵；`parse()` 是宿主入口，委托 core 同一实现与 AST LRU。
+ *
  * 决策：parse() 统一做 TS 剥除（不按 .ts 路径开关）。理由：parse() 的产物被
  * CLI/service/LSP/evaluator 全链消费，按调用方 opt-in 会漏掉无法感知文件扩展名
  * 的消费方（analyzer 的模块解析、LSP 等）；对纯 JS 源码剥除是结构性 no-op，
@@ -15,6 +19,91 @@ declare function parse(source: string, opts?: {
     errorRecovery?: boolean;
 }): File;
 
+/** File → its Program; Program → itself. Replaces `(ast as File).program ?? ast`. */
+declare function asProgram(ast: Node | File | Program | null | undefined): Program | undefined;
+/** Top-level statements of a File/Program (empty when neither). */
+declare function programBody(ast: Node | File | Program | null | undefined): Statement[];
+declare function asIdentifier(node: Node | null | undefined): Identifier | undefined;
+declare function asExpression(node: Node | null | undefined): Expression | undefined;
+declare function asAssignmentExpression(node: Node | null | undefined): AssignmentExpression | undefined;
+/** Identifier.name, else StringLiteral.value (module string export names). */
+declare function nameOrStringValue(node: Node | null | undefined): string | undefined;
+/** Identifier.name only (undefined for string export names). */
+declare function identifierName(node: Node | null | undefined): string | undefined;
+/** VariableDeclaration.declarations; empty for other nodes. */
+declare function getDeclarations(node: Node | null | undefined): VariableDeclarator[];
+/** First declarator's init (fn-binding extraction). */
+declare function getDeclaratorInit(node: Node | null | undefined): Expression | undefined;
+/** First declarator of a VariableDeclaration, narrowed to Identifier id. */
+declare function getFirstDeclaratorId(node: Node | null | undefined): Identifier | undefined;
+/** VariableDeclarator id narrowed to Identifier. */
+declare function getDeclaratorId(node: Node | null | undefined): Identifier | undefined;
+/** Inner declaration of `export default` / `export …` (undefined for other nodes). */
+declare function getExportDeclaration(node: Node | null | undefined): Node | undefined;
+/**
+ * Unwrap an export form: named/default exports yield their inner declaration
+ * with `exported: true`; any other statement is returned as-is with `exported: false`.
+ */
+declare function unwrapExport(node: Node | null | undefined): {
+    declaration: Node;
+    exported: boolean;
+};
+/** ExportNamedDeclaration.specifiers (empty for other nodes). */
+declare function getExportSpecifiers(node: Node | null | undefined): (ExportSpecifier | ExportDefaultSpecifier | ExportNamespaceSpecifier)[];
+/** ExportSpecifier local name — Identifier only (matches `local.name`). */
+declare function exportSpecifierLocalName(spec: Node | null | undefined): string | undefined;
+/** ExportSpecifier exported name (`exported.name ?? exported.value`). */
+declare function exportSpecifierExportedName(spec: Node | null | undefined): string | number | undefined;
+/** ExpressionStatement.expression. */
+declare function getExpressionStatementExpression(node: Node | null | undefined): Expression | undefined;
+/** Function/Class declaration or expression `id?.name`. */
+declare function fnOrClassIdName(node: Node | null | undefined): string | undefined;
+/** ClassDeclaration/ClassExpression `id?.name`. */
+declare function classIdName(node: Node | null | undefined): string | undefined;
+/** `id.loc` of a named function/class (undefined when anonymous or unlocated). */
+declare function fnOrClassIdLoc(node: Node | null | undefined): Node["loc"];
+/** Non-computed member property key text (Identifier.name or StringLiteral.value). */
+declare function memberPropertyKey(member: Node | null | undefined): string | null;
+/** Identifier name of a non-computed member's object (e.g. `module` in `module.exports`). */
+declare function memberObjectName(member: Node | null | undefined): string | undefined;
+/** Identifier name of a non-computed member's property (e.g. `exports`). */
+declare function memberPropertyName(member: Node | null | undefined): string | undefined;
+/** `module.exports` / `module["exports"]` is rejected here: computed keys return false. */
+declare function isModuleExportsMember(member: Node | null | undefined): boolean;
+declare function asMemberExpression(node: Node | null | undefined): MemberExpression | undefined;
+/** Class body members; empty when node is not a class. */
+declare function getClassMembers(node: Node | null | undefined): ClassBody["body"];
+/**
+ * `key.name ?? key.value` on a class/object member key.
+ * Handles Identifier / StringLiteral / NumericLiteral and ESTree-shaped keys.
+ */
+declare function classMemberKeyName(member: Node | null | undefined): string | number | undefined;
+/** Key node of a class member (for range selection). */
+declare function classMemberKey(member: Node | null | undefined): Node | undefined;
+type InstanceMethod = {
+    name: string;
+    node: Node;
+};
+/**
+ * Instance methods of a class-like node. Accepts Babel `ClassMethod` /
+ * `TSDeclareMethod` and ESTree `MethodDefinition` (whose function lives in `value`).
+ * Skips getters/setters/constructors and static members.
+ */
+declare function classInstanceMethods(node: Node | null | undefined): InstanceMethod[];
+/** Class/TSDeclare method function node (ESTree MethodDefinition → its `value`). */
+declare function methodFunctionNode(member: Node | null | undefined): Node | undefined;
+/**
+ * Parameter display label: `name`, `...rest`, or `_`.
+ * Non-identifier rest arguments keep the historical `...undefined` string form.
+ */
+declare function paramDisplayName(param: Node | null | undefined): string;
+/** RestElement argument name, else plain Identifier name. */
+declare function paramName(param: Node | null | undefined): string | undefined;
+/** CJS/ESM default interop: callable module or `{ default }` wrapper. */
+declare function unwrapDefaultExport<T>(mod: T | {
+    default: T;
+}): T;
+
 type CaseDirective = {
     kind: "case";
     name: string;
@@ -90,4 +179,4 @@ declare function extractDirectives(ast: Node): FunctionWithDirectives[];
 declare function extractInlineDirectives(node: Node): InlineDirective[];
 declare function extractFileDirectives(ast: Node): FileDirective[];
 
-export { type AsDirective, type CaseDirective, type Directive, type EnvDirective, type FileDirective, type FunctionWithDirectives, type InlineDirective, type MockDirective, type MockModuleDirective, type PureDirective, type ReplaceDirective, type SampleDirective, type SinonExpression, type SkipDirective, extractDirectives, extractFileDirectives, extractInlineDirectives, parse, parseCaseArgExpr };
+export { type AsDirective, type CaseDirective, type Directive, type EnvDirective, 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, extractFileDirectives, extractInlineDirectives, fnOrClassIdLoc, fnOrClassIdName, getClassMembers, getDeclarations, getDeclaratorId, getDeclaratorInit, getExportDeclaration, getExportSpecifiers, getExpressionStatementExpression, getFirstDeclaratorId, identifierName, isModuleExportsMember, memberObjectName, memberPropertyKey, memberPropertyName, methodFunctionNode, nameOrStringValue, paramDisplayName, paramName, parse, parseCaseArgExpr, programBody, unwrapDefaultExport, unwrapExport };

package/dist/index.js

@@ -7,6 +7,173 @@ function parse(source, opts) {
 // src/index.ts
 import { stripTypes } from "@nudojs/core";
 
+// src/ast-guards.ts
+import { isExpression } from "@babel/types";
+function asProgram(ast) {
+  if (!ast) return void 0;
+  if (ast.type === "File") return ast.program;
+  if (ast.type === "Program") return ast;
+  return void 0;
+}
+function programBody(ast) {
+  return asProgram(ast)?.body ?? [];
+}
+function asIdentifier(node) {
+  return node?.type === "Identifier" ? node : void 0;
+}
+function asExpression(node) {
+  return node && isExpression(node) ? node : void 0;
+}
+function asAssignmentExpression(node) {
+  return node?.type === "AssignmentExpression" ? node : void 0;
+}
+function nameOrStringValue(node) {
+  if (!node) return void 0;
+  if (node.type === "Identifier") return node.name;
+  if (node.type === "StringLiteral") return node.value;
+  return void 0;
+}
+function identifierName(node) {
+  return node?.type === "Identifier" ? node.name : void 0;
+}
+function getDeclarations(node) {
+  return node?.type === "VariableDeclaration" ? node.declarations : [];
+}
+function getDeclaratorInit(node) {
+  const decl = node?.type === "VariableDeclarator" ? node : void 0;
+  return decl?.init ?? void 0;
+}
+function getFirstDeclaratorId(node) {
+  const decl = getDeclarations(node)[0];
+  return decl?.id.type === "Identifier" ? decl.id : void 0;
+}
+function getDeclaratorId(node) {
+  const decl = node?.type === "VariableDeclarator" ? node : void 0;
+  return decl?.id.type === "Identifier" ? decl.id : void 0;
+}
+function getExportDeclaration(node) {
+  if (!node) return void 0;
+  if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") {
+    return node.declaration ?? void 0;
+  }
+  return void 0;
+}
+function unwrapExport(node) {
+  if (node?.type === "ExportNamedDeclaration" && node.declaration) {
+    return { declaration: node.declaration, exported: true };
+  }
+  if (node?.type === "ExportDefaultDeclaration") {
+    return { declaration: node.declaration, exported: true };
+  }
+  return { declaration: node, exported: false };
+}
+function getExportSpecifiers(node) {
+  return node?.type === "ExportNamedDeclaration" ? node.specifiers : [];
+}
+function exportSpecifierLocalName(spec) {
+  return spec?.type === "ExportSpecifier" ? identifierName(spec.local) : void 0;
+}
+function exportSpecifierExportedName(spec) {
+  if (spec?.type !== "ExportSpecifier") return void 0;
+  const exported = spec.exported;
+  return exported.type === "Identifier" ? exported.name : exported.value;
+}
+function getExpressionStatementExpression(node) {
+  return node?.type === "ExpressionStatement" ? node.expression : void 0;
+}
+function fnOrClassIdName(node) {
+  if (!node) return void 0;
+  if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ClassDeclaration" || node.type === "ClassExpression" || node.type === "TSDeclareFunction") {
+    return node.id?.name;
+  }
+  return void 0;
+}
+function classIdName(node) {
+  if (!node) return void 0;
+  if (node.type === "ClassDeclaration" || node.type === "ClassExpression") {
+    return node.id?.name;
+  }
+  return void 0;
+}
+function fnOrClassIdLoc(node) {
+  if (!node) return void 0;
+  if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ClassDeclaration" || node.type === "ClassExpression" || node.type === "TSDeclareFunction") {
+    return node.id?.loc ?? void 0;
+  }
+  return void 0;
+}
+function memberPropertyKey(member) {
+  if (member?.type !== "MemberExpression" || member.computed) return null;
+  return nameOrStringValue(member.property) ?? null;
+}
+function memberObjectName(member) {
+  if (member?.type !== "MemberExpression") return void 0;
+  return identifierName(member.object);
+}
+function memberPropertyName(member) {
+  if (member?.type !== "MemberExpression" || member.computed) return void 0;
+  return identifierName(member.property);
+}
+function isModuleExportsMember(member) {
+  return memberObjectName(member) === "module" && memberPropertyName(member) === "exports";
+}
+function asMemberExpression(node) {
+  return node?.type === "MemberExpression" ? node : void 0;
+}
+function getClassMembers(node) {
+  if (node?.type === "ClassDeclaration" || node?.type === "ClassExpression") {
+    return node.body.body;
+  }
+  return [];
+}
+function classMemberKeyName(member) {
+  const key = member?.key;
+  return key?.name ?? key?.value;
+}
+function classMemberKey(member) {
+  return member?.key ?? void 0;
+}
+function classInstanceMethods(node) {
+  const out = [];
+  for (const raw of getClassMembers(node)) {
+    const m = raw;
+    const isMethod = m.type === "MethodDefinition" || m.type === "ClassMethod" || m.type === "TSDeclareMethod";
+    if (!isMethod) continue;
+    if (m.kind && m.kind !== "method") continue;
+    if (m.static) continue;
+    const keyName = m.key?.type === "Identifier" ? m.key.name : void 0;
+    if (!keyName) continue;
+    const methodNode = m.type === "MethodDefinition" ? m.value ?? void 0 : raw;
+    if (!methodNode) continue;
+    out.push({ name: keyName, node: methodNode });
+  }
+  return out;
+}
+function methodFunctionNode(member) {
+  const m = member;
+  if (!m) return void 0;
+  return m.type === "MethodDefinition" ? m.value ?? void 0 : member;
+}
+function paramDisplayName(param) {
+  if (!param) return "_";
+  if (param.type === "Identifier") return param.name;
+  if (param.type === "RestElement") {
+    const arg = param.argument;
+    return `...${arg.name}`;
+  }
+  return "_";
+}
+function paramName(param) {
+  if (!param) return void 0;
+  if (param.type === "Identifier") return param.name;
+  if (param.type === "RestElement") return identifierName(param.argument);
+  return void 0;
+}
+function unwrapDefaultExport(mod) {
+  if (typeof mod === "function") return mod;
+  return mod.default;
+}
+
 // src/directives.ts
 import {
   stub,
@@ -636,10 +803,43 @@ function extractFileDirectives(ast) {
   return results;
 }
 export {
+  asAssignmentExpression,
+  asExpression,
+  asIdentifier,
+  asMemberExpression,
+  asProgram,
+  classIdName,
+  classInstanceMethods,
+  classMemberKey,
+  classMemberKeyName,
+  exportSpecifierExportedName,
+  exportSpecifierLocalName,
   extractDirectives,
   extractFileDirectives,
   extractInlineDirectives,
+  fnOrClassIdLoc,
+  fnOrClassIdName,
+  getClassMembers,
+  getDeclarations,
+  getDeclaratorId,
+  getDeclaratorInit,
+  getExportDeclaration,
+  getExportSpecifiers,
+  getExpressionStatementExpression,
+  getFirstDeclaratorId,
+  identifierName,
+  isModuleExportsMember,
+  memberObjectName,
+  memberPropertyKey,
+  memberPropertyName,
+  methodFunctionNode,
+  nameOrStringValue,
+  paramDisplayName,
+  paramName,
   parse,
   parseCaseArgExpr,
-  stripTypes
+  programBody,
+  stripTypes,
+  unwrapDefaultExport,
+  unwrapExport
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nudojs/parser",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "engines": {
     "node": ">=20"
   },
@@ -39,7 +39,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@nudojs/core": "2.1.0"
+    "@nudojs/core": "1.1.0",
+    "@babel/types": "^8.0.6"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts"