@nudojs/harvester 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { TypeValue } from '@nudojs/core';
+
+/**
+ * The result of harvesting a set of `.d.ts` files: a Nudo env shaped exactly
+ * like `EnvDefinition` (`{ globals, modules }`), plus harvest statistics.
+ */
+type HarvestedEnv = {
+    globals: Record<string, TypeValue>;
+    modules: Record<string, Record<string, TypeValue>>;
+    stats: {
+        files: number;
+        symbols: number;
+        skipped: number;
+    };
+};
+declare function harvestDts(files: string[]): HarvestedEnv;
+declare function emitEnvModule(env: HarvestedEnv, pkgName: string): string;
+
+export { type HarvestedEnv, emitEnvModule, harvestDts };

package/dist/index.js

@@ -0,0 +1,562 @@
+// src/index.ts
+import { readFileSync } from "fs";
+import ts from "typescript";
+import { typeValueEquals, getFnSig, T } from "@nudojs/core";
+var MAX_ALIAS_DEPTH = 8;
+function scopeKey(scope) {
+  return scope.moduleName ?? "\0global";
+}
+function harvestDts(files) {
+  const ctx = {
+    globals: {},
+    modules: {},
+    interfaces: /* @__PURE__ */ new Map(),
+    qualifiedInterfaces: /* @__PURE__ */ new Map(),
+    aliases: /* @__PURE__ */ new Map(),
+    qualifiedAliases: /* @__PURE__ */ new Map(),
+    classes: /* @__PURE__ */ new Map(),
+    instanceCache: /* @__PURE__ */ new Map(),
+    expanding: /* @__PURE__ */ new Set(),
+    moduleAliases: [],
+    importEquals: /* @__PURE__ */ new Map(),
+    declaredModules: /* @__PURE__ */ new Set(),
+    pending: [],
+    symbols: 0,
+    skipped: 0
+  };
+  for (const file of files) {
+    const content = readFileSync(file, "utf8");
+    const sourceFile = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
+    collectStatements(ctx, sourceFile.statements, { moduleName: void 0, ns: [] });
+  }
+  materialize(ctx);
+  return {
+    globals: ctx.globals,
+    modules: ctx.modules,
+    stats: { files: files.length, symbols: ctx.symbols, skipped: ctx.skipped }
+  };
+}
+function emitEnvModule(env, pkgName) {
+  const moduleEntries = Object.entries(env.modules);
+  const keysByRecord = /* @__PURE__ */ new Map();
+  for (const [moduleName, record] of moduleEntries) {
+    const keys = keysByRecord.get(record);
+    if (keys) keys.push(moduleName);
+    else keysByRecord.set(record, [moduleName]);
+  }
+  const constNameByRecord = /* @__PURE__ */ new Map();
+  const constLines = [];
+  let constIndex = 0;
+  for (const [record, keys] of keysByRecord) {
+    if (keys.length < 2) continue;
+    const constName = `mod${constIndex++}`;
+    constNameByRecord.set(record, constName);
+    constLines.push(`  const ${constName}: Record<string, TypeValue> = {`);
+    emitEntries(constLines, record, 2);
+    constLines.push(`  };`);
+    constLines.push("");
+  }
+  const lines = [];
+  lines.push("// Auto-generated by nudo harvest \u2014 DO NOT EDIT");
+  lines.push(`// Source package: ${pkgName}`);
+  if (constLines.length > 0) {
+    lines.push('import { type TypeValue, T } from "@nudojs/core";');
+  } else {
+    lines.push(`import { T } from "@nudojs/core";`);
+  }
+  lines.push("");
+  lines.push("export function defineEnv() {");
+  lines.push(...constLines);
+  lines.push("  return {");
+  lines.push("    globals: {");
+  emitEntries(lines, env.globals, 3);
+  lines.push("    },");
+  lines.push("    modules: {");
+  for (const [moduleName, record] of moduleEntries) {
+    const constName = constNameByRecord.get(record);
+    if (constName !== void 0) {
+      lines.push(`${indent(3)}${emitKey(moduleName)}: ${constName},`);
+      continue;
+    }
+    lines.push(`${indent(3)}${emitKey(moduleName)}: {`);
+    emitEntries(lines, record, 4);
+    lines.push(`${indent(3)}},`);
+  }
+  lines.push("    },");
+  lines.push("  };");
+  lines.push("}");
+  lines.push("");
+  return lines.join("\n");
+}
+function recordFor(ctx, scope) {
+  if (scope.moduleName === void 0) return ctx.globals;
+  let rec = ctx.modules[scope.moduleName];
+  if (!rec) {
+    rec = {};
+    ctx.modules[scope.moduleName] = rec;
+  }
+  return rec;
+}
+function collectStatements(ctx, statements, scope) {
+  for (const stmt of statements) {
+    collectStatement(ctx, stmt, scope);
+  }
+}
+function collectStatement(ctx, stmt, scope) {
+  if (ts.isModuleDeclaration(stmt)) {
+    const body = stmt.body;
+    if (!body || !ts.isModuleBlock(body)) {
+      ctx.skipped++;
+      return;
+    }
+    if (ts.isStringLiteral(stmt.name)) {
+      ctx.declaredModules.add(stmt.name.text);
+      collectStatements(ctx, body.statements, { moduleName: stmt.name.text, ns: [] });
+    } else if (stmt.name.text === "global") {
+      collectStatements(ctx, body.statements, { moduleName: void 0, ns: [] });
+    } else {
+      collectStatements(ctx, body.statements, { moduleName: scope.moduleName, ns: [...scope.ns, stmt.name.text] });
+    }
+    return;
+  }
+  if (ts.isFunctionDeclaration(stmt)) {
+    if (!stmt.name) {
+      ctx.skipped++;
+      return;
+    }
+    const name = stmt.name.text;
+    const existing = ctx.pending.find((p) => p.t === "fn" && p.name === name && scopeKey(p.scope) === scopeKey(scope));
+    if (existing && existing.t === "fn") {
+      existing.decls.push(stmt);
+      return;
+    }
+    ctx.pending.push({ t: "fn", scope, name, decls: [stmt] });
+    ctx.symbols++;
+    return;
+  }
+  if (ts.isVariableStatement(stmt)) {
+    for (const decl of stmt.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name)) {
+        ctx.skipped++;
+        continue;
+      }
+      ctx.pending.push({ t: "var", scope, name: decl.name.text, typeNode: decl.type });
+      ctx.symbols++;
+    }
+    return;
+  }
+  if (ts.isInterfaceDeclaration(stmt)) {
+    registerTypeDecl(ctx, scope, stmt.name.text, stmt);
+    return;
+  }
+  if (ts.isTypeAliasDeclaration(stmt)) {
+    registerAlias(ctx, scope, stmt);
+    return;
+  }
+  if (ts.isClassDeclaration(stmt)) {
+    if (!stmt.name) {
+      ctx.skipped++;
+      return;
+    }
+    registerTypeDecl(ctx, scope, stmt.name.text, stmt);
+    if (!ctx.classes.has(stmt.name.text)) ctx.classes.set(stmt.name.text, stmt);
+    ctx.pending.push({ t: "value", scope, name: stmt.name.text });
+    ctx.symbols++;
+    return;
+  }
+  if (ts.isEnumDeclaration(stmt)) {
+    if (stmt.name) {
+      ctx.pending.push({ t: "enum", scope, name: stmt.name.text });
+      ctx.symbols++;
+    }
+    return;
+  }
+  if (ts.isImportDeclaration(stmt)) {
+    return;
+  }
+  if (ts.isImportEqualsDeclaration(stmt)) {
+    if (ts.isIdentifier(stmt.name) && stmt.moduleReference && ts.isExternalModuleReference(stmt.moduleReference) && ts.isStringLiteral(stmt.moduleReference.expression)) {
+      const key = scopeKey(scope);
+      let bindings = ctx.importEquals.get(key);
+      if (!bindings) {
+        bindings = /* @__PURE__ */ new Map();
+        ctx.importEquals.set(key, bindings);
+      }
+      bindings.set(stmt.name.text, stmt.moduleReference.expression.text);
+    }
+    return;
+  }
+  if (ts.isExportDeclaration(stmt)) {
+    const specifier = stmt.moduleSpecifier;
+    if (specifier && ts.isStringLiteral(specifier)) {
+      if (stmt.exportClause && ts.isNamespaceExport(stmt.exportClause)) {
+        ctx.skipped++;
+        return;
+      }
+      if (!stmt.exportClause) {
+        if (scope.moduleName !== void 0) {
+          ctx.moduleAliases.push([scope.moduleName, specifier.text]);
+        }
+        return;
+      }
+      ctx.skipped++;
+      return;
+    }
+    if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+      for (const el of stmt.exportClause.elements) {
+        const localName = (el.propertyName ?? el.name).text;
+        const exportedName = el.name.text;
+        const isValue = ctx.classes.has(localName) || !el.isTypeOnly && (ctx.interfaces.has(localName) || ctx.qualifiedInterfaces.has(localName));
+        if (isValue) {
+          ctx.pending.push({ t: "value", scope, name: exportedName, lookup: localName });
+          ctx.symbols++;
+        } else {
+          ctx.skipped++;
+        }
+      }
+      return;
+    }
+    ctx.skipped++;
+    return;
+  }
+  if (ts.isExportAssignment(stmt)) {
+    if (stmt.expression && ts.isIdentifier(stmt.expression) && scope.moduleName !== void 0) {
+      const target = ctx.importEquals.get(scopeKey(scope))?.get(stmt.expression.text);
+      if (target !== void 0) {
+        ctx.moduleAliases.push([scope.moduleName, target]);
+        return;
+      }
+    }
+    ctx.skipped++;
+    return;
+  }
+  ctx.skipped++;
+}
+function registerTypeDecl(ctx, scope, name, decl) {
+  if (!ctx.interfaces.has(name)) ctx.interfaces.set(name, decl);
+  if (ts.isClassDeclaration(decl)) return;
+  const qualified = [...scope.ns, name].join(".");
+  if (qualified !== name && !ctx.qualifiedInterfaces.has(qualified)) {
+    ctx.qualifiedInterfaces.set(qualified, decl);
+  }
+}
+function registerAlias(ctx, scope, stmt) {
+  const name = stmt.name.text;
+  if (!ctx.aliases.has(name)) ctx.aliases.set(name, stmt);
+  const qualified = [...scope.ns, name].join(".");
+  if (qualified !== name && !ctx.qualifiedAliases.has(qualified)) {
+    ctx.qualifiedAliases.set(qualified, stmt);
+  }
+}
+function materialize(ctx) {
+  for (const p of ctx.pending) {
+    const rec = recordFor(ctx, p.scope);
+    if (p.t === "fn") {
+      if (rec[p.name] !== void 0) continue;
+      const value = signatureToFnSig(ctx, p.decls[0]);
+      const sig = getFnSig(value);
+      if (sig) {
+        const returns = [];
+        for (const decl of p.decls) {
+          if (!decl.type) continue;
+          const ret = mapType(ctx, decl.type, 0);
+          if (ret.kind !== "unknown") returns.push(ret);
+        }
+        sig.returnType = returns.length > 0 ? returns.reduce((acc, r) => typeValueEquals(acc, r) ? acc : T.union(acc, r)) : T.unknown;
+      }
+      rec[p.name] = value;
+      continue;
+    }
+    if (rec[p.name] !== void 0) continue;
+    switch (p.t) {
+      case "var": {
+        const mapped = p.typeNode ? mapType(ctx, p.typeNode, 0) : T.unknown;
+        if (mapped.kind === "unknown") {
+          ctx.skipped++;
+          break;
+        }
+        rec[p.name] = mapped;
+        break;
+      }
+      case "value": {
+        const cls = ctx.classes.get(p.lookup ?? p.name);
+        if (cls) {
+          const ctor = cls.members.find(ts.isConstructorDeclaration);
+          const params = [];
+          if (ctor) {
+            for (const param of ctor.parameters) {
+              let type = param.type ? mapType(ctx, param.type, 0) : T.unknown;
+              if (param.questionToken) type = T.union(type, T.undefined);
+              params.push(type);
+            }
+          }
+          rec[p.name] = T.fnSig(params, instanceFor(ctx, p.lookup ?? p.name));
+        } else {
+          rec[p.name] = instanceFor(ctx, p.lookup ?? p.name);
+        }
+        break;
+      }
+      case "enum":
+        rec[p.name] = T.unknown;
+        break;
+    }
+  }
+  for (const [alias, target] of ctx.moduleAliases) {
+    if (ctx.modules[target] && !ctx.modules[alias]) {
+      ctx.modules[alias] = ctx.modules[target];
+    }
+  }
+}
+function typeNameString(name) {
+  if (ts.isIdentifier(name)) return name.text;
+  return `${typeNameString(name.left)}.${name.right.text}`;
+}
+function memberName(node) {
+  const n = node.name;
+  if (!n) return void 0;
+  if (ts.isIdentifier(n) || ts.isStringLiteral(n) || ts.isNumericLiteral(n)) return n.text;
+  return void 0;
+}
+function instanceFor(ctx, key) {
+  const cached = ctx.instanceCache.get(key);
+  if (cached !== void 0) return cached;
+  const decl = ctx.interfaces.get(key) ?? ctx.qualifiedInterfaces.get(key);
+  if (!decl) return T.unknown;
+  if (ctx.expanding.has(key)) {
+    return T.instanceOf(decl.name?.text ?? key, {});
+  }
+  ctx.expanding.add(key);
+  const properties = {};
+  try {
+    const members = decl.members;
+    for (const member of members) {
+      const modifiers = member.modifiers;
+      if (modifiers?.some((mod) => mod.kind === ts.SyntaxKind.StaticKeyword)) continue;
+      if (ts.isPropertySignature(member) || ts.isPropertyDeclaration(member)) {
+        const name = memberName(member);
+        if (name === void 0) continue;
+        let type = member.type ? mapType(ctx, member.type, 0) : T.unknown;
+        if (member.questionToken) type = T.union(type, T.undefined);
+        properties[name] = type;
+      } else if (ts.isMethodSignature(member) || ts.isMethodDeclaration(member)) {
+        const name = memberName(member);
+        if (name === void 0 || properties[name] !== void 0) continue;
+        properties[name] = signatureToFnSig(ctx, member);
+      } else if (ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)) {
+        const name = memberName(member);
+        if (name === void 0 || properties[name] !== void 0 || !member.type) continue;
+        properties[name] = mapType(ctx, member.type, 0);
+      }
+    }
+  } finally {
+    ctx.expanding.delete(key);
+  }
+  const value = T.instanceOf(decl.name?.text ?? key, properties);
+  ctx.instanceCache.set(key, value);
+  return value;
+}
+function signatureToFnSig(ctx, sig) {
+  const paramTypes = sig.parameters.map((param) => {
+    let type;
+    if (param.dotDotDotToken) {
+      const inner = param.type && ts.isArrayTypeNode(param.type) ? param.type.elementType : param.type;
+      type = inner ? T.array(mapType(ctx, inner, 0)) : T.unknown;
+    } else {
+      type = param.type ? mapType(ctx, param.type, 0) : T.unknown;
+    }
+    if (param.questionToken && !param.dotDotDotToken) type = T.union(type, T.undefined);
+    return type;
+  });
+  const returnType = sig.type ? mapType(ctx, sig.type, 0) : T.unknown;
+  return T.fnSig(paramTypes, returnType);
+}
+function mapTypeMembers(ctx, members, depth) {
+  const properties = {};
+  for (const member of members) {
+    if (ts.isPropertySignature(member)) {
+      const name = memberName(member);
+      if (name === void 0) continue;
+      let type = member.type ? mapType(ctx, member.type, depth) : T.unknown;
+      if (member.questionToken) type = T.union(type, T.undefined);
+      properties[name] = type;
+    } else if (ts.isMethodSignature(member)) {
+      const name = memberName(member);
+      if (name === void 0 || properties[name] !== void 0) continue;
+      properties[name] = signatureToFnSig(ctx, member);
+    }
+  }
+  return properties;
+}
+function mapTypeRef(ctx, node, depth) {
+  const name = typeNameString(node.typeName);
+  const args = node.typeArguments ?? [];
+  if ((name === "Array" || name === "ReadonlyArray") && args.length >= 1) {
+    return T.array(mapType(ctx, args[0], depth));
+  }
+  if (name === "Promise" && args.length >= 1) {
+    return T.promise(mapType(ctx, args[0], depth));
+  }
+  if (name === "Record") {
+    return T.object({});
+  }
+  if (ctx.interfaces.has(name) || ctx.qualifiedInterfaces.has(name)) {
+    return instanceFor(ctx, name);
+  }
+  const alias = ctx.aliases.get(name) ?? ctx.qualifiedAliases.get(name);
+  if (alias) return mapType(ctx, alias.type, depth + 1);
+  return T.unknown;
+}
+function mapType(ctx, node, depth) {
+  if (!node || depth > MAX_ALIAS_DEPTH) return T.unknown;
+  if (ts.isParenthesizedTypeNode(node)) return mapType(ctx, node.type, depth);
+  if (ts.isTypeReferenceNode(node)) return mapTypeRef(ctx, node, depth);
+  if (ts.isArrayTypeNode(node)) return T.array(mapType(ctx, node.elementType, depth));
+  if (ts.isTupleTypeNode(node)) {
+    for (const element of node.elements) {
+      const inner = ts.isNamedTupleMember(element) ? element.type : element;
+      return T.array(mapType(ctx, inner, depth));
+    }
+    return T.unknown;
+  }
+  if (ts.isUnionTypeNode(node)) {
+    return T.union(...node.types.map((t) => mapType(ctx, t, depth)));
+  }
+  if (ts.isIntersectionTypeNode(node)) {
+    const members = node.types.map((t) => mapType(ctx, t, depth));
+    if (members.length > 0 && members.every((m) => m.kind === "object")) {
+      const properties = {};
+      for (const member of members) {
+        Object.assign(properties, member.properties);
+      }
+      return T.object(properties);
+    }
+    return members[0] ?? T.unknown;
+  }
+  if (ts.isLiteralTypeNode(node)) {
+    const lit = node.literal;
+    if (ts.isStringLiteral(lit)) return T.literal(lit.text);
+    if (ts.isNumericLiteral(lit)) return T.literal(Number(lit.text));
+    if (lit.kind === ts.SyntaxKind.TrueKeyword) return T.literal(true);
+    if (lit.kind === ts.SyntaxKind.FalseKeyword) return T.literal(false);
+    if (ts.isPrefixUnaryExpression(lit) && lit.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(lit.operand)) {
+      return T.literal(-Number(lit.operand.text));
+    }
+    return T.unknown;
+  }
+  if (ts.isFunctionTypeNode(node)) return signatureToFnSig(ctx, node);
+  if (ts.isTypeLiteralNode(node)) {
+    const ctor = node.members.find(ts.isConstructSignatureDeclaration);
+    if (ctor) {
+      const params = [];
+      for (const param of ctor.parameters) {
+        let type = param.type ? mapType(ctx, param.type, depth) : T.unknown;
+        if (param.questionToken) type = T.union(type, T.undefined);
+        params.push(type);
+      }
+      return T.fnSig(params, ctor.type ? mapType(ctx, ctor.type, depth) : T.unknown);
+    }
+    return T.object(mapTypeMembers(ctx, node.members, depth));
+  }
+  if (ts.isTypeOperatorNode(node)) {
+    return node.operator === ts.SyntaxKind.ReadonlyKeyword ? mapType(ctx, node.type, depth) : T.unknown;
+  }
+  switch (node.kind) {
+    case ts.SyntaxKind.StringKeyword:
+      return T.string;
+    case ts.SyntaxKind.NumberKeyword:
+      return T.number;
+    case ts.SyntaxKind.BooleanKeyword:
+      return T.boolean;
+    case ts.SyntaxKind.BigIntKeyword:
+      return T.bigint;
+    case ts.SyntaxKind.SymbolKeyword:
+      return T.symbol;
+    case ts.SyntaxKind.AnyKeyword:
+    case ts.SyntaxKind.UnknownKeyword:
+    case ts.SyntaxKind.ObjectKeyword:
+      return T.unknown;
+    case ts.SyntaxKind.VoidKeyword:
+    case ts.SyntaxKind.UndefinedKeyword:
+      return T.undefined;
+    case ts.SyntaxKind.NeverKeyword:
+      return T.never;
+    case ts.SyntaxKind.NullKeyword:
+      return T.null;
+    default:
+      return T.unknown;
+  }
+}
+function indent(level) {
+  return "  ".repeat(level);
+}
+function emitKey(key) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}
+function emitEntries(lines, record, level) {
+  for (const [key, value] of Object.entries(record)) {
+    lines.push(`${indent(level)}${emitKey(key)}: ${emitType(value, /* @__PURE__ */ new Set())},`);
+  }
+}
+function emitType(tv, expanding) {
+  switch (tv.kind) {
+    case "literal":
+      if (tv.value === null) return "T.null";
+      if (tv.value === void 0) return "T.undefined";
+      return `T.literal(${JSON.stringify(tv.value)})`;
+    case "primitive":
+      return `T.${tv.type}`;
+    case "unknown":
+      return "T.unknown";
+    case "never":
+      return "T.never";
+    case "array":
+      return `T.array(${emitType(tv.element, expanding)})`;
+    case "tuple":
+      return `T.tuple([${tv.elements.map((e) => emitType(e, expanding)).join(", ")}])`;
+    case "promise":
+      return `T.promise(${emitType(tv.value, expanding)})`;
+    case "object": {
+      const entries = Object.entries(tv.properties).map(
+        ([key, value]) => `${emitKey(key)}: ${emitType(value, expanding)}`
+      );
+      return `T.object({ ${entries.join(", ")} })`;
+    }
+    case "instance": {
+      if (expanding.has(tv.className)) {
+        return `T.instanceOf(${JSON.stringify(tv.className)}, {})`;
+      }
+      expanding.add(tv.className);
+      try {
+        const entries = Object.entries(tv.properties).map(
+          ([key, value]) => `${emitKey(key)}: ${emitType(value, expanding)}`
+        );
+        return `T.instanceOf(${JSON.stringify(tv.className)}, { ${entries.join(", ")} })`;
+      } finally {
+        expanding.delete(tv.className);
+      }
+    }
+    case "union": {
+      if (tv.members.length === 0) return "T.never";
+      if (tv.members.length === 1) return emitType(tv.members[0], expanding);
+      return `T.union(${tv.members.map((m) => emitType(m, expanding)).join(", ")})`;
+    }
+    case "function": {
+      const sig = getFnSig(tv);
+      if (!sig) return "T.unknown";
+      const params = sig.paramTypes.map((p) => emitType(p, expanding)).join(", ");
+      const ret = emitType(sig.returnType, expanding);
+      if (sig.throwsType && sig.throwsType.kind !== "never") {
+        return `T.fnSig([${params}], ${ret}, ${emitType(sig.throwsType, expanding)})`;
+      }
+      return `T.fnSig([${params}], ${ret})`;
+    }
+    case "refined":
+      return emitType(tv.base, expanding);
+    default:
+      return "T.unknown";
+  }
+}
+export {
+  emitEnvModule,
+  harvestDts
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@nudojs/harvester",
+  "version": "0.1.0",
+  "description": "Harvests TypeScript .d.ts declarations into Nudo env definitions",
+  "type": "module",
+  "license": "MIT",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nudojs/nudo.git",
+    "directory": "packages/harvester"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts"
+  },
+  "dependencies": {
+    "@nudojs/core": "workspace:*",
+    "typescript": "^5.8.0"
+  }
+}