@nudojs/service 0.2.1 → 0.3.0

package/src/semantic-tokens.ts

@@ -0,0 +1,216 @@
+import { dirname } from "node:path";
+import type { Node } from "@babel/types";
+import { createEnvironment, type Environment } from "@nudojs/core";
+import { parse } from "@nudojs/parser";
+import {
+  evaluateProgram,
+  setModuleResolver,
+  setCurrentFileDir,
+  resetMemo,
+} from "@nudojs/cli/evaluator";
+import { resolveModule } from "./analyzer.ts";
+
+/**
+ * Semantic tokens 图例（tokenTypes 下标即 LSP 编码里的 tokenType 值）。
+ * 与 LSP server capabilities 里声明的 legend 必须逐字对齐——server.ts 直接
+ * 导入本常量注册，保证「提取端索引」与「客户端图例」单一来源。
+ * 顺序沿用 lsp 包原 legend（function/variable/parameter/property 在前），
+ * 末尾追加 method（对象字面量方法键），只追加不重排，客户端索引稳定。
+ */
+export const SEMANTIC_TOKEN_TYPES = [
+  "function",
+  "variable",
+  "parameter",
+  "property",
+  "type",
+  "keyword",
+  "string",
+  "number",
+  "comment",
+  "decorator",
+  "method",
+] as const;
+
+export const SEMANTIC_TOKEN_MODIFIERS = [
+  "declaration",
+  "readonly",
+  "deprecated",
+  "unreachable",
+] as const;
+
+export type SemanticToken = {
+  line: number;
+  char: number;
+  length: number;
+  typeIndex: number;
+  modifierBitmask: number;
+};
+
+/** LSP 标准相对五元组编码：deltaLine/deltaStartChar/length/tokenType/tokenModifiers。 */
+export function encodeSemanticTokens(tokens: SemanticToken[]): number[] {
+  const result: number[] = [];
+  let prevLine = 0;
+  let prevChar = 0;
+
+  for (const token of tokens) {
+    const deltaLine = token.line - prevLine;
+    const deltaChar = deltaLine === 0 ? token.char - prevChar : token.char;
+
+    result.push(deltaLine, deltaChar, token.length, token.typeIndex, token.modifierBitmask);
+
+    prevLine = token.line;
+    prevChar = token.char;
+  }
+
+  return result;
+}
+
+const TYPE_FUNCTION = SEMANTIC_TOKEN_TYPES.indexOf("function");
+const TYPE_VARIABLE = SEMANTIC_TOKEN_TYPES.indexOf("variable");
+const TYPE_PARAMETER = SEMANTIC_TOKEN_TYPES.indexOf("parameter");
+const TYPE_PROPERTY = SEMANTIC_TOKEN_TYPES.indexOf("property");
+const TYPE_METHOD = SEMANTIC_TOKEN_TYPES.indexOf("method");
+const MOD_DECLARATION = 1 << SEMANTIC_TOKEN_MODIFIERS.indexOf("declaration");
+
+/**
+ * 从源码提取 semantic tokens 并按 LSP 相对编码返回扁平 number[]。
+ *
+ * 上色范围（声明位优先，未解析的 token 一律不上色）：
+ * - 顶层 const/let/var 声明的绑定名：推断为函数绑定 → function，否则 variable
+ *   （函数体内部的声明不做 env 反查——外层同名绑定会串味，统一 variable）；
+ * - 函数声明/函数表达式的名字 → function；所有函数的参数 → parameter；
+ * - 对象字面量的键：值为函数 → method，否则 property。
+ *
+ * 推断复用 evaluateProgram 的绑定分析（与补全/诊断同一求值链），不另建
+ * 符号体系；解析失败返回 []，求值中断则按已绑定的部分结果继续上色。
+ */
+export function buildSemanticTokens(filePath: string, source: string): number[] {
+  let ast: Node;
+  try {
+    ast = parse(source);
+  } catch {
+    return [];
+  }
+
+  const env = createEnvironment();
+  resetMemo();
+  setModuleResolver(resolveModule);
+  setCurrentFileDir(dirname(filePath));
+  try {
+    evaluateProgram(ast, env);
+  } catch {
+    // 求值中断（如未支持语法）：尽力而为，用已落进 env 的绑定继续上色
+  } finally {
+    setModuleResolver(null);
+  }
+
+  const program = (ast as { program?: Node }).program ?? ast;
+  const ownBindings = env.getOwnBindings();
+  // 顶层声明器节点集合：仅这些绑定名做 env 反查区分 function/variable
+  const topLevelDeclarators = new Set<unknown>();
+  for (const stmt of ((program as { body?: Node[] }).body ?? []) as Node[]) {
+    const decl =
+      stmt.type === "ExportNamedDeclaration" || stmt.type === "ExportDefaultDeclaration"
+        ? ((stmt as { declaration?: Node }).declaration ?? null)
+        : stmt;
+    if (decl && decl.type === "VariableDeclaration") {
+      for (const d of (decl as unknown as { declarations: Node[] }).declarations) {
+        topLevelDeclarators.add(d);
+      }
+    }
+  }
+
+  const tokens: SemanticToken[] = [];
+  const pushIdentifier = (id: Node, typeIndex: number): void => {
+    const loc = (id as { loc?: { start: { line: number; column: number } } }).loc;
+    const name = (id as { name?: string }).name;
+    if (!loc || typeof name !== "string") return;
+    tokens.push({
+      line: loc.start.line - 1,
+      char: loc.start.column,
+      length: name.length,
+      typeIndex,
+      modifierBitmask: MOD_DECLARATION,
+    });
+  };
+
+  const collectParams = (params: Node[]): void => {
+    for (const p of params) {
+      if (!p) continue;
+      if (p.type === "Identifier") pushIdentifier(p, TYPE_PARAMETER);
+      else if (p.type === "AssignmentPattern" && (p as { left?: Node }).left?.type === "Identifier") {
+        pushIdentifier((p as { left: Node }).left, TYPE_PARAMETER);
+      } else if (p.type === "RestElement" && (p as { argument?: Node }).argument?.type === "Identifier") {
+        pushIdentifier((p as { argument: Node }).argument, TYPE_PARAMETER);
+      }
+      // 解构模式（ObjectPattern/ArrayPattern）内部不上色：子绑定的
+      // function/variable 区分没有可靠推断依据，宁缺毋滥
+    }
+  };
+
+  const isFunctionValue = (name: string): boolean =>
+    ownBindings[name]?.kind === "function";
+
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== "object") return;
+    const n = node as Record<string, unknown>;
+
+    switch (n.type) {
+      case "VariableDeclarator": {
+        const id = n.id as Node | undefined;
+        if (id?.type === "Identifier") {
+          const isTopLevel = topLevelDeclarators.has(node);
+          const typeIndex =
+            isTopLevel && isFunctionValue((id as { name: string }).name) ? TYPE_FUNCTION : TYPE_VARIABLE;
+          pushIdentifier(id, typeIndex);
+        }
+        break;
+      }
+      case "FunctionDeclaration":
+      case "FunctionExpression": {
+        const id = n.id as Node | undefined;
+        if (id?.type === "Identifier") pushIdentifier(id, TYPE_FUNCTION);
+        collectParams((n.params as Node[] | undefined) ?? []);
+        break;
+      }
+      case "ArrowFunctionExpression":
+        collectParams((n.params as Node[] | undefined) ?? []);
+        break;
+      case "ObjectMethod": {
+        const key = n.key as Node | undefined;
+        if (key?.type === "Identifier" && !n.computed) pushIdentifier(key, TYPE_METHOD);
+        collectParams((n.params as Node[] | undefined) ?? []);
+        break;
+      }
+      case "ObjectProperty": {
+        const key = n.key as Node | undefined;
+        const value = n.value as Node | undefined;
+        if (key?.type === "Identifier" && !n.computed) {
+          const isFn =
+            value?.type === "FunctionExpression" || value?.type === "ArrowFunctionExpression";
+          pushIdentifier(key, isFn ? TYPE_METHOD : TYPE_PROPERTY);
+        }
+        break;
+      }
+    }
+
+    for (const key of Object.keys(n)) {
+      if (key === "loc" || key === "start" || key === "end" || key === "leadingComments" || key === "trailingComments" || key === "innerComments") continue;
+      const child = n[key];
+      if (Array.isArray(child)) {
+        for (const item of child) {
+          if (item && typeof item === "object" && typeof (item as { type?: unknown }).type === "string") {
+            visit(item);
+          }
+        }
+      } else if (child && typeof child === "object" && typeof (child as { type?: unknown }).type === "string") {
+        visit(child);
+      }
+    }
+  };
+
+  visit(program);
+
+  tokens.sort((a, b) => a.line - b.line || a.char - b.char);
+  return encodeSemanticTokens(tokens);
+}

package/src/session-cache.ts

@@ -0,0 +1,50 @@
+/**
+ * 会话缓存失效入口（宿主契约的唯一接线点）。
+ *
+ * analyzeFile / tryRunBPath / generalize L0 的键都不含「依赖模块内容」——
+ * 入口 source 未变但 dep 变了时，必须由宿主主动逐出，否则会命中陈旧结果。
+ * LSP 走定向逐出；CLI watch / vite-plugin 走这里。
+ */
+import {
+  resetGeneralizeMemo,
+  resetCheckSourceMemo,
+  resetNudoModuleExecCache,
+  resetParseSourceCache,
+} from "@nudojs/core";
+import { clearAbsModuleCache, evictAbsModuleCacheFiles } from "./abs-modules-graph.ts";
+import { clearBPathCache, evictBPathCacheForFiles } from "./bpath-run.ts";
+import { clearAnalysisFileCache, evictAnalysisFileCacheForFiles } from "./analysis-file-cache.ts";
+import { clearFnAnalysisCache, evictFnAnalysisCacheForFiles } from "./fn-analysis-cache.ts";
+
+/**
+ * 依赖内容变更后：按入口文件定向逐出 service 层缓存。
+ * 调用方应传「以这些文件为入口」的路径（脏集里的 dependents），
+ * 而不是变更的 dep 文件本身——dep 自己 source 变了会自然 miss。
+ */
+export function evictAnalysisCachesForFiles(files: string[]): void {
+  if (files.length === 0) return;
+  evictBPathCacheForFiles(files);
+  evictAnalysisFileCacheForFiles(files);
+  evictFnAnalysisCacheForFiles(files);
+  evictAbsModuleCacheFiles(files);
+}
+
+/**
+ * 清空全部会话级分析缓存（service + core）。
+ * 适用于：CLI watch 增量批前、vite buildStart / watchChange、测试隔离。
+ * 比定向逐出重，但保证无陈旧命中；单次 analyze 内部的 per-fn / generalize
+ * memo 不受影响（它们在同一轮里先写后读）。
+ */
+export function clearAnalysisSessionCaches(): void {
+  clearBPathCache(); // cascades analysis-file + fn-analysis
+  clearAbsModuleCache();
+  resetGeneralizeMemo();
+  resetCheckSourceMemo();
+  resetNudoModuleExecCache();
+}
+
+/** 比 clearAnalysisSessionCaches 更彻底：再丢 AST LRU（测试 / 进程复用场景） */
+export function resetAllAnalysisCaches(): void {
+  clearAnalysisSessionCaches();
+  resetParseSourceCache();
+}

package/src/static-imports.ts

@@ -0,0 +1,241 @@
+/**
+ * Host 侧多文件解析（非代数层）。
+ *
+ * 分层：
+ *   algebra = 纯抽象解释：吃 AST / source string，不碰 fs/path
+ *   host   = 读文件、解析相对 import/require、把 source 喂给代数
+ *   Node/打包器 = 真正的模块加载与执行
+ *
+ * 引擎不做 bundler；这里只为「跨文件类型事实」做最薄的静态扫描。
+ */
+
+import { parse } from "@nudojs/parser";
+import type { File, Node } from "@babel/types";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { generalizeFromAst, type PolyFn } from "@nudojs/core";
+
+export type ModuleExports = {
+  path: string;
+  named: Map<string, string>;
+  defaultExport?: string;
+  source: string;
+  poly: Map<string, PolyFn>;
+};
+
+function resolveRelative(fromFile: string, spec: string): string | undefined {
+  if (!spec.startsWith(".") && !spec.startsWith("/")) return undefined;
+  const base = resolve(dirname(fromFile), spec);
+  for (const cand of [
+    base,
+    base + ".js",
+    base + ".cjs",
+    base + ".mjs",
+    base + ".ts",
+    base + ".mts",
+    base + ".cts",
+    join(base, "index.js"),
+    join(base, "index.cjs"),
+    join(base, "index.mjs"),
+    join(base, "index.ts"),
+  ]) {
+    if (existsSync(cand)) return cand;
+  }
+  return undefined;
+}
+
+/** 从 AST 收集静态相对依赖（ESM import + CJS require） */
+export function collectDependencySpecs(ast: File): string[] {
+  const specs: string[] = [];
+  for (const stmt of ast.program.body) {
+    if (stmt.type === "ImportDeclaration") {
+      specs.push(stmt.source.value);
+    }
+    if (stmt.type === "ExportNamedDeclaration" && stmt.source) {
+      specs.push(stmt.source.value);
+    }
+    if (stmt.type === "ExportAllDeclaration" && stmt.source) {
+      specs.push(stmt.source.value);
+    }
+    // require("...") / require.resolve
+    collectRequires(stmt, specs);
+  }
+  return specs;
+}
+
+function collectRequires(node: Node, out: string[]): void {
+  const visit = (n: unknown): void => {
+    if (!n || typeof n !== "object") return;
+    const obj = n as {
+      type?: string;
+      callee?: { type?: string; name?: string };
+      arguments?: Array<{ type?: string; value?: unknown }>;
+      [k: string]: unknown;
+    };
+    if (
+      obj.type === "CallExpression" &&
+      obj.callee?.type === "Identifier" &&
+      obj.callee.name === "require" &&
+      obj.arguments?.[0]?.type === "StringLiteral"
+    ) {
+      const spec = obj.arguments[0].value;
+      if (typeof spec === "string") out.push(spec);
+    }
+    for (const key of Object.keys(obj)) {
+      if (key === "loc" || key === "start" || key === "end") continue;
+      const v = obj[key];
+      if (Array.isArray(v)) v.forEach(visit);
+      else if (v && typeof v === "object") visit(v);
+    }
+  };
+  visit(node);
+}
+
+/** 分析单文件导出 + 内涵签名（source 由 host 提供） */
+export function analyzeExportsFromSource(
+  filePath: string,
+  source: string,
+): ModuleExports {
+  const file = parse(source);
+  const named = new Map<string, string>();
+  let defaultExport: string | undefined;
+  const poly = new Map<string, PolyFn>();
+
+  for (const stmt of file.program.body) {
+    let decl: Node = stmt;
+    if (stmt.type === "ExportNamedDeclaration" && stmt.declaration) {
+      decl = stmt.declaration;
+    }
+    if (decl.type === "FunctionDeclaration" && decl.id) {
+      named.set(decl.id.name, decl.id.name);
+    }
+    if (decl.type === "VariableDeclaration") {
+      for (const d of decl.declarations) {
+        if (d.id.type === "Identifier") named.set(d.id.name, d.id.name);
+      }
+    }
+    if (decl.type === "ClassDeclaration" && decl.id) {
+      named.set(decl.id.name, decl.id.name);
+    }
+    if (stmt.type === "ExportDefaultDeclaration") {
+      const d = stmt.declaration;
+      if (d.type === "FunctionDeclaration" && d.id) defaultExport = d.id.name;
+      if (d.type === "Identifier") defaultExport = d.name;
+    }
+    // CJS: exports.foo = fn / module.exports = fn / module.exports = { a, b }
+    collectCjsExports(stmt, named, (n) => {
+      defaultExport = n;
+    });
+  }
+
+  for (const name of named.values()) {
+    const g = generalizeFromAst(name, source);
+    if (g) poly.set(name, g);
+  }
+  if (defaultExport) {
+    const g = generalizeFromAst(defaultExport, source);
+    if (g) poly.set("default", g);
+  }
+
+  return { path: filePath, named, defaultExport, source, poly };
+}
+
+function collectCjsExports(
+  stmt: Node,
+  named: Map<string, string>,
+  setDefault: (name: string) => void,
+): void {
+  const visit = (n: unknown): void => {
+    if (!n || typeof n !== "object") return;
+    const obj = n as Record<string, unknown> & { type?: string };
+    if (obj.type !== "AssignmentExpression") {
+      for (const key of Object.keys(obj)) {
+        if (key === "loc" || key === "start" || key === "end") continue;
+        const v = obj[key];
+        if (Array.isArray(v)) v.forEach(visit);
+        else if (v && typeof v === "object") visit(v);
+      }
+      return;
+    }
+    const left = obj.left as {
+      type?: string;
+      object?: { type?: string; name?: string };
+      property?: { type?: string; name?: string; value?: string };
+    };
+    const right = obj.right as Record<string, unknown> & { type?: string };
+
+    // exports.foo = ...
+    if (
+      left?.type === "MemberExpression" &&
+      left.object?.type === "Identifier" &&
+      left.object.name === "exports" &&
+      left.property?.type === "Identifier" &&
+      left.property.name
+    ) {
+      named.set(left.property.name, left.property.name);
+    }
+    // module.exports = fnName
+    if (
+      left?.type === "MemberExpression" &&
+      left.object?.type === "Identifier" &&
+      left.object.name === "module" &&
+      left.property?.type === "Identifier" &&
+      left.property.name === "exports"
+    ) {
+      if (right?.type === "Identifier" && typeof right.name === "string") {
+        named.set(right.name, right.name);
+        setDefault(right.name);
+      }
+      // module.exports = { foo, bar: baz }
+      if (right?.type === "ObjectExpression") {
+        const props = right.properties as Array<Record<string, unknown>>;
+        for (const p of props) {
+          if (p.type !== "ObjectProperty") continue;
+          const key = p.key as { type?: string; name?: string; value?: string };
+          const val = p.value as { type?: string; name?: string };
+          const exportName =
+            key?.type === "Identifier" ? key.name : key?.type === "StringLiteral" ? key.value : undefined;
+          if (exportName) named.set(exportName, exportName);
+          if (val?.type === "Identifier" && val.name && exportName) {
+            // exported binding may differ from local name — generalize uses local
+            // keep exportName as key; generalizeFromAst(exportName) may fail if local differs
+          }
+        }
+      }
+    }
+  };
+  visit(stmt);
+}
+
+/**
+ * 从入口文件沿静态相对 import/require 收集（仅类型事实，不是运行时加载器）。
+ * bare specifier（npm 包）跳过——交给 harvest / env。
+ */
+export function collectStaticImports(
+  entryFile: string,
+  maxDepth = 8,
+): Map<string, ModuleExports> {
+  const graph = new Map<string, ModuleExports>();
+  const queue: Array<{ file: string; depth: number }> = [
+    { file: resolve(entryFile), depth: 0 },
+  ];
+  const seen = new Set<string>();
+
+  while (queue.length > 0) {
+    const { file, depth } = queue.shift()!;
+    if (seen.has(file) || depth > maxDepth) continue;
+    seen.add(file);
+    if (!existsSync(file)) continue;
+
+    const source = readFileSync(file, "utf8");
+    const mod = analyzeExportsFromSource(file, source);
+    graph.set(file, mod);
+
+    const ast: File = parse(source);
+    for (const spec of collectDependencySpecs(ast)) {
+      const resolved = resolveRelative(file, spec);
+      if (resolved) queue.push({ file: resolved, depth: depth + 1 });
+    }
+  }
+  return graph;
+}

package/src/target-path.ts

@@ -0,0 +1,17 @@
+/**
+ * nudo 推断目标文件判定（纯扩展名规则，路径无需存在）。
+ *
+ * 规则：.js / .mjs / .ts 可作为推断目标；其余扩展（.cjs/.tsx/.jsx/.mts/.d.ts…）
+ * 一律 false。两类显式排除：
+ *  - .d.ts —— 类型声明文件（harvester 的输入），不是可求值的实现源码；
+ *  - .tsx / .jsx —— JSX 构造的求值超出 nudo 推断器范围。
+ *
+ * 消费方：CLI 的 collectNudoFiles/watch 过滤/doctor 目录展开（.ts 放开后统一
+ * 走本函数，避免各处手写 endsWith 漂移），以及 LSP 的 isNudoFile（接线由
+ * LSP 侧负责）。
+ */
+export function isNudoTargetPath(path: string): boolean {
+  const lower = path.toLowerCase();
+  if (lower.endsWith(".d.ts")) return false; // 类型声明，非推断目标
+  return lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".ts");
+}