@nudojs/service 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @nudojs/service
 
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [0fd0718]
+  - @nudojs/cli@0.2.1
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,27 @@
+# @nudojs/service
+
+Shared inference service for [Nudo](https://github.com/nudojs/nudo) IDE integrations.
+
+## 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.
+
+## This package
+
+`@nudojs/service` provides the high-level analysis API used by editor extensions and build tools:
+
+- **File analysis** — `analyzeFile` returns diagnostics, function analyses, and case results
+- **IDE features** — `getTypeAtPosition`, `getCompletionsAtPosition`, `getCasesForFile`
+- **DTS generation** — `generateDts` and `typeValueToTSType` for producing `.d.ts` output
+- **Zod schema generation** — `typeValueToZodSchema` converts inferred types to Zod schema strings
+- **Guard generation** — `generateGuardFunction` produces zero-dependency runtime type guards
+
+## Install
+
+```bash
+npm install @nudojs/service
+```
+
+## License
+
+[MIT](https://github.com/nudojs/nudo/blob/main/LICENSE)

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { Node } from '@babel/types';
 import { TypeValue } from '@nudojs/core';
+import { CallRecord } from '@nudojs/cli/evaluator';
+export { CallRecord } from '@nudojs/cli/evaluator';
 
 type SourceLocation = {
     start: {
@@ -18,6 +20,14 @@ type Diagnostic = {
     severity: DiagnosticSeverity;
     message: string;
     tags?: DiagnosticTag[];
+    code?: string;
+    suggestions?: string[];
+    data?: unknown;
+    /** provenance of the receiver value (callsite argument that flowed into the error) */
+    origin?: {
+        line: number;
+        column: number;
+    };
 };
 type CaseResult = {
     name: string;
@@ -25,13 +35,28 @@ type CaseResult = {
     result: TypeValue;
     throws: TypeValue;
     throwLoc?: SourceLocation;
+    source?: "directive" | "callsite";
+    /** number of additional call sites folded into a symbolic case */
+    aggregatedFrom?: number;
 };
 type FunctionAnalysis = {
     name: string;
     loc: SourceLocation;
+    paramNames: string[];
     cases: CaseResult[];
     combined?: TypeValue;
     assertionErrors?: string[];
+    entryOnly?: boolean;
+    skipped?: boolean;
+    /**
+     * True for functions collected from CJS-style bindings/assignments
+     * (`exports.X = fn`, `module.exports = fn`, `const f = fn`): their name has
+     * no declaration-level stability, so .d.ts generation skips them while
+     * infer/JSON output still reports them.
+     */
+    noDeclaration?: boolean;
+    /** absolute path of the module this function is imported from (externalFunctions only) */
+    fromModule?: string;
 };
 type BindingInfo = {
     type: TypeValue;
@@ -48,13 +73,63 @@ type AnalysisResult = {
     bindings: Map<string, BindingInfo>;
     nodeTypeMap: Map<Node, TypeValue>;
     caseHints: CaseHint[];
+    /** functions imported from other modules, synthesized from cross-file call sites observed while analyzing this file */
+    externalFunctions?: FunctionAnalysis[];
 };
 type CompletionItem = {
     label: string;
     kind: "property" | "method" | "variable";
     detail?: string;
 };
-declare function analyzeFile(filePath: string, source: string, activeCases?: Map<string, number>): AnalysisResult;
+type SymbolInfo = {
+    name: string;
+    kind: "function" | "variable" | "class" | "parameter";
+    loc: SourceLocation;
+    uri?: string;
+};
+type ReferenceInfo = {
+    name: string;
+    loc: SourceLocation;
+    uri?: string;
+};
+type SymbolTable = {
+    definitions: Map<string, SymbolInfo>;
+    references: ReferenceInfo[];
+};
+/** mtime 边缓存：key 为文件路径，edges 为已抽取的相对 import 边（与 buildModuleGraph 返回语义一致）。 */
+type ModuleGraphCache = Map<string, {
+    mtimeMs: number;
+    size: number;
+    edges: string[];
+}>;
+/** Statically extract each file's relative import edges (extension resolution identical to CLI resolveModule: ''/'.js'/'.ts'/'.mjs'; bare npm specifiers skipped). */
+declare function buildModuleGraph(files: string[], cache?: ModuleGraphCache): {
+    imports: Map<string, Set<string>>;
+    dependents: Map<string, Set<string>>;
+};
+/** changed plus its transitive dependents (reverse-edge BFS); cycle-safe via visited. */
+declare function computeDirtySet(dependents: Map<string, Set<string>>, changedFile: string): string[];
+/** Topological order with dependencies before dependents (only imports edges internal to dirty; cycles tolerated — remaining files appended in arbitrary order). */
+declare function topoSortDirty(imports: Map<string, Set<string>>, dirty: string[]): string[];
+/**
+ * Async entry to analyzeFile: preloads path-based env files
+ * (`/// @nudo:env ./nudo-harvest-node.ts`) via dynamic import — impossible
+ * synchronously in ESM — then runs the sync analysis, which picks the
+ * preloaded factories up from the env-loader cache. The sync analyzeFile
+ * signature is unchanged for existing consumers (LSP, MCP, vite-plugin).
+ */
+declare function analyzeFileAsync(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[]): Promise<AnalysisResult>;
+/**
+ * 调用点发现（阶段一）：在"使用现场"文件（测试 / 上层应用）中求值
+ * 顶层代码，收集它对（外部模块导出的）函数的调用记录。每条记录带
+ * 真实的实参类型与结果类型——后续 analyzeFile 将其注入合成 case，
+ * 使被使用方从 entry-only（参数全 unknown）升级为真实调用形态。
+ *
+ * 只做求值与记录，不产出诊断；求值异常不抛出（使用现场文件可能
+ * 依赖未 mock 的全局，收集不到就收集不到，不能拖垮主分析）。
+ */
+declare function collectCallRecords(filePath: string, source: string): CallRecord[];
+declare function analyzeFile(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[]): AnalysisResult;
 type CaseInfo = {
     functionName: string;
     caseName: string;
@@ -68,10 +143,70 @@ declare function getCasesForFile(filePath: string, source: string): {
     }[];
     loc: SourceLocation;
 }[];
+/** Async entry to getTypeAtPosition with path-env preloading (see analyzeFileAsync). */
+declare function getTypeAtPositionAsync(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): Promise<TypeValue | null>;
 declare function getTypeAtPosition(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): TypeValue | null;
 declare function getCompletionsAtPosition(filePath: string, source: string, line: number, column: number): CompletionItem[];
 
 declare function typeValueToTSType(tv: TypeValue): string;
+/**
+ * 为单个函数生成 .d.ts 声明行（JSDoc + 单一 widen 主签名）。
+ * service 的 generateDts 与 CLI `--dts`（infer/watch）共用本函数，
+ * 两条路径输出保持一致。
+ */
+declare function generateFunctionDtsLines(fn: FunctionAnalysis): string[];
 declare function generateDts(result: AnalysisResult): string;
 
-export { type AnalysisResult, type BindingInfo, type CaseHint, type CaseInfo, type CaseResult, type CompletionItem, type Diagnostic, type DiagnosticSeverity, type DiagnosticTag, type FunctionAnalysis, type SourceLocation, analyzeFile, generateDts, getCasesForFile, getCompletionsAtPosition, getTypeAtPosition, typeValueToTSType };
+declare function typeValueToZodSchema(tv: TypeValue): string;
+
+declare function generateGuardFunction(name: string, tv: TypeValue): string;
+
+/** 单个 TypeValue → parseTypeValueExpr 可解析回去的表达式文本；不可表达返回 null */
+declare function serializeCaseArg(tv: TypeValue): string | null;
+/**
+ * 组装单行 ` * @nudo:case "name" (a, b)` 指令文本（无尾换行）。
+ * 任一实参不可序列化、或名字含双引号/换行（名字正则 `"([^"]+)"` 承载不了）→ 整体 null。
+ */
+declare function buildCaseDirective(name: string, args: TypeValue[]): string | null;
+/**
+ * 从源码剥离所有本模块生成的 @nudo:case 指令（名字以 call@ 开头，整行删除）。
+ * 若所属 JSDoc 块因此只剩空 ` *` 行（无其他 @nudo:* 指令、无文字内容），
+ * 连块首 `/**` 行与块尾行整块删除。绝不碰非 case 指令与普通注释。
+ * 注意：手写但以 call@ 命名的 case 同样会被删——call@ 前缀保留为生成物标记。
+ * removed 返回被删指令名列表（按出现顺序）。
+ */
+declare function stripGeneratedCaseDirectives(source: string): {
+    source: string;
+    removed: string[];
+};
+type EmitSkipReason = "hand-written" | "already-generated" | "entry-only" | "no-serializable-cases" | "no-declaration" | "skipped";
+type EmitResult = {
+    source: string;
+    changed: boolean;
+    written: Array<{
+        fn: string;
+        cases: string[];
+    }>;
+    skipped: Array<{
+        fn: string;
+        reason: EmitSkipReason;
+        detail?: string;
+    }>;
+};
+/**
+ * 把 analysis 中的合成 case（source === "callsite"）固化为源码指令：
+ *
+ * 1. 源码已有任何非 call@ 命名的 case → skip "hand-written"；
+ *    已有 call@ case → skip "already-generated"。
+ * 2. fn.skipped / fn.noDeclaration / fn.entryOnly → 对应 skip。
+ * 3. 逐 case 序列化；个别不可序列化的丢弃并在 skipped 记
+ *    no-serializable-cases（函数整体仍写可序列化子集，全不可序列化才整函数跳过）。
+ * 4. 写入位置：函数声明行正上方——已有 JSDoc 块则插到 `/**` 行后，
+ *    无块则新建三行块。缩进取声明行的 loc.start.column（babel 0 基列）。
+ *    多函数编辑按行号从下往上应用，避免行号漂移。
+ */
+declare function insertGeneratedCaseDirectives(source: string, analysis: AnalysisResult): EmitResult;
+/** 行级 unified diff：`--- a/path` 头 + `@@` hunk + 上下文 3 行；相同返回 "" */
+declare function unifiedDiff(a: string, b: string, path: string): string;
+
+export { type AnalysisResult, type BindingInfo, type CaseHint, type CaseInfo, type CaseResult, type CompletionItem, type Diagnostic, type DiagnosticSeverity, type DiagnosticTag, type EmitResult, type EmitSkipReason, type FunctionAnalysis, type ModuleGraphCache, type ReferenceInfo, type SourceLocation, type SymbolInfo, type SymbolTable, analyzeFile, analyzeFileAsync, buildCaseDirective, buildModuleGraph, collectCallRecords, computeDirtySet, generateDts, generateFunctionDtsLines, generateGuardFunction, getCasesForFile, getCompletionsAtPosition, getTypeAtPosition, getTypeAtPositionAsync, insertGeneratedCaseDirectives, serializeCaseArg, stripGeneratedCaseDirectives, topoSortDirty, typeValueToTSType, typeValueToZodSchema, unifiedDiff };