@knighted/module 1.3.0 → 1.3.1

package/dist/cjs/formatVisitor.d.cts

@@ -0,0 +1,42 @@
+import type MagicString from 'magic-string';
+import type { Node, CallExpressionNode } from '../helpers/ast.cjs';
+import type { IdentifierName } from 'oxc-parser';
+import type { WarnOnce } from './exportBagToEsm.cjs';
+import type { FormatterOptions, ExportsMeta } from '../types.cjs';
+type AssignmentExpressionFn = (typeof import('../formatters/assignmentExpression.cjs'))['assignmentExpression'];
+type IdentifierFn = (typeof import('../formatters/identifier.cjs'))['identifier'];
+type MemberExpressionFn = (typeof import('../formatters/memberExpression.cjs'))['memberExpression'];
+type MetaPropertyFn = (typeof import('../formatters/metaProperty.cjs'))['metaProperty'];
+type VisitorThis = {
+    skip(): void;
+};
+type FormatWalkState = {
+    importMetaRef: boolean;
+    requireMainNeedsRealpath: boolean;
+    needsCreateRequire: boolean;
+    needsRequireResolveHelper: boolean;
+};
+type FormatWalkContext = {
+    code: MagicString;
+    opts: FormatterOptions;
+    warnOnce: WarnOnce;
+    shadowedBindings: Set<string>;
+    requireMainStrategy: FormatterOptions['requireMainStrategy'];
+    nestedRequireStrategy: FormatterOptions['nestedRequireStrategy'];
+    shouldRaiseEsm: boolean;
+    fullTransform: boolean;
+    useExportsBag: boolean;
+    exportsMeta: ExportsMeta;
+    isRequireMainMember: (node: Node, shadowed: Set<string>) => boolean;
+    isRequireCall: (node: Node, shadowed: Set<string>) => node is CallExpressionNode;
+    isStaticRequire: (node: Node, shadowed: Set<string>) => node is CallExpressionNode;
+    isAsyncContext: (ancestors: Node[]) => boolean;
+    isValidUrl: (value: string) => boolean;
+    isIdentifierName: (node: Node) => node is IdentifierName;
+    assignmentExpression: AssignmentExpressionFn;
+    metaProperty: MetaPropertyFn;
+    memberExpression: MemberExpressionFn;
+    identifier: IdentifierFn;
+};
+declare const buildFormatVisitor: (ctx: FormatWalkContext, state: FormatWalkState) => (this: VisitorThis, node: Node, ancestors: Node[]) => Promise<void>;
+export { buildFormatVisitor, type FormatWalkState };

package/dist/cjs/helpers/async.cjs

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isAsyncContext = exports.hasTopLevelAwait = void 0;
+var _ast = require("./ast.cjs");
+const hasTopLevelAwait = program => {
+  let found = false;
+  const walkNode = (node, inFunction) => {
+    if (found) return;
+    if (!(0, _ast.isAstNode)(node)) return;
+    switch (node.type) {
+      case 'FunctionDeclaration':
+      case 'FunctionExpression':
+      case 'ArrowFunctionExpression':
+      case 'ClassDeclaration':
+      case 'ClassExpression':
+        inFunction = true;
+        break;
+    }
+    if (!inFunction && node.type === 'AwaitExpression') {
+      found = true;
+      return;
+    }
+    for (const value of Object.values(node)) {
+      if (!value) continue;
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (item && typeof item === 'object') {
+            walkNode(item, inFunction);
+            if (found) return;
+          }
+        }
+      } else if (value && typeof value === 'object') {
+        walkNode(value, inFunction);
+        if (found) return;
+      }
+    }
+  };
+  walkNode(program, false);
+  return found;
+};
+exports.hasTopLevelAwait = hasTopLevelAwait;
+const isAsyncContext = ancestors => {
+  for (let i = ancestors.length - 1; i >= 0; i -= 1) {
+    const node = ancestors[i];
+    if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {
+      return !!node.async;
+    }
+    if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') {
+      return false;
+    }
+  }
+  return true;
+};
+exports.isAsyncContext = isAsyncContext;

package/dist/cjs/idiomaticPlan.d.cts

@@ -0,0 +1,28 @@
+import type MagicString from 'magic-string';
+import type { ExportsMap } from '../helpers/ast.cjs';
+import type { FormatterOptions } from '../types.cjs';
+type Replacement = {
+    start: number;
+    end: number;
+};
+type IdiomaticPlan = {
+    replacements: Replacement[];
+    exports: string[];
+};
+type IdiomaticPlanResult = {
+    ok: true;
+    plan: IdiomaticPlan;
+} | {
+    ok: false;
+    reason: string;
+};
+type BuildIdiomaticPlanParams = {
+    src: string;
+    code: MagicString;
+    exportTable: ExportsMap;
+    shadowedBindings: Set<string>;
+    idiomaticMode: FormatterOptions['idiomaticExports'];
+};
+declare const buildIdiomaticPlan: ({ src, code, exportTable, shadowedBindings, idiomaticMode, }: BuildIdiomaticPlanParams) => IdiomaticPlanResult;
+export { buildIdiomaticPlan };
+export type { IdiomaticPlan, IdiomaticPlanResult };

package/dist/cjs/interopHelpers.d.cts

@@ -0,0 +1,5 @@
+declare const defaultInteropName = "__interopDefault";
+declare const interopHelper = "const __interopDefault = mod => (mod && mod.__esModule ? mod.default : mod);\n";
+declare const requireInteropName = "__requireDefault";
+declare const requireInteropHelper = "const __requireDefault = mod => (mod && typeof mod === 'object' && 'default' in mod ? mod.default : mod);\n";
+export { defaultInteropName, interopHelper, requireInteropHelper, requireInteropName };

package/dist/cjs/lowerCjsRequireToImports.d.cts

@@ -0,0 +1,17 @@
+import MagicString from 'magic-string';
+import { type CallExpressionNode, type ProgramNode, type Node } from '../helpers/ast.cjs';
+type RequireTransform = {
+    start: number;
+    end: number;
+    code: string;
+};
+declare const isStaticRequire: (node: Node, shadowed: Set<string>) => node is CallExpressionNode;
+declare const isRequireCall: (node: Node, shadowed: Set<string>) => node is CallExpressionNode;
+declare const lowerCjsRequireToImports: (program: ProgramNode, code: MagicString, shadowed: Set<string>) => {
+    transforms: RequireTransform[];
+    imports: string[];
+    hoisted: string[];
+    needsCreateRequire: boolean;
+    needsInteropHelper: boolean;
+};
+export { isRequireCall, isStaticRequire, lowerCjsRequireToImports, type RequireTransform };

package/dist/cjs/lowerEsmToCjs.d.cts

@@ -0,0 +1,22 @@
+import MagicString from 'magic-string';
+import { type ProgramNode } from '../helpers/ast.cjs';
+import type { FormatterOptions } from '../types.cjs';
+declare const exportAssignment: (name: string, expr: string, live: "strict" | "loose" | "off") => string;
+type ImportTransform = {
+    start: number;
+    end: number;
+    code: string;
+    needsInterop: boolean;
+};
+type ExportTransform = {
+    start: number;
+    end: number;
+    code: string;
+    needsInterop?: boolean;
+};
+declare const lowerEsmToCjs: (program: ProgramNode, code: MagicString, opts: FormatterOptions, containsTopLevelAwait: boolean) => {
+    importTransforms: ImportTransform[];
+    exportTransforms: ExportTransform[];
+    needsInterop: boolean;
+};
+export { exportAssignment, lowerEsmToCjs, type ExportTransform, type ImportTransform };

package/dist/cjs/pipeline/buildEsmPrelude.cjs

@@ -0,0 +1,65 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.buildEsmPrelude = void 0;
+var _exports = require("../utils/exports.cjs");
+var _interopHelpers = require("./interopHelpers.cjs");
+const buildEsmPrelude = options => {
+  const {
+    needsCreateRequire,
+    needsRequireResolveHelper,
+    requireMainNeedsRealpath,
+    hoistedImports,
+    hoistedStatements,
+    needsImportInterop,
+    importMetaPreludeMode,
+    useExportsBag
+  } = options;
+  let importMetaRef = options.importMetaRef;
+  const importPrelude = [];
+  if (needsCreateRequire || needsRequireResolveHelper) {
+    importMetaRef = true;
+  }
+  if (needsCreateRequire || needsRequireResolveHelper) {
+    importPrelude.push('import { createRequire } from "node:module";\n');
+  }
+  if (needsRequireResolveHelper) {
+    importPrelude.push('import { fileURLToPath } from "node:url";\n');
+  }
+  if (requireMainNeedsRealpath) {
+    importPrelude.push('import { realpathSync } from "node:fs";\n');
+    importPrelude.push('import { pathToFileURL } from "node:url";\n');
+  }
+  if (hoistedImports.length) {
+    importPrelude.push(...hoistedImports);
+  }
+  const setupPrelude = [];
+  if (needsImportInterop) {
+    setupPrelude.push(_interopHelpers.requireInteropHelper);
+  }
+  if (hoistedStatements.length) {
+    setupPrelude.push(...hoistedStatements);
+  }
+  const requireInit = needsCreateRequire ? 'const require = createRequire(import.meta.url);\n' : '';
+  const requireResolveInit = needsRequireResolveHelper ? needsCreateRequire ? `const __requireResolve = (id, parent) => {
+  const resolved = require.resolve(id, parent);
+  return resolved.startsWith("file://") ? fileURLToPath(resolved) : resolved;
+};\n` : `const __requireResolve = (id, parent) => {
+  const req = createRequire(parent ?? import.meta.url);
+  const resolved = req.resolve(id, parent);
+  return resolved.startsWith("file://") ? fileURLToPath(resolved) : resolved;
+};\n` : '';
+  const exportsBagInit = useExportsBag ? `let ${_exports.exportsRename} = {};
+` : '';
+  const modulePrelude = '';
+  const prelude = `${importPrelude.join('')}${importPrelude.length ? '\n' : ''}${setupPrelude.join('')}${setupPrelude.length ? '\n' : ''}${requireInit}${requireResolveInit}${exportsBagInit}${modulePrelude}`;
+  const importMetaTouch = (() => {
+    if (importMetaPreludeMode === 'on') return 'void import.meta.filename;\n';
+    if (importMetaPreludeMode === 'off') return '';
+    return importMetaRef ? 'void import.meta.filename;\n' : '';
+  })();
+  return `${prelude}${importMetaTouch}`;
+};
+exports.buildEsmPrelude = buildEsmPrelude;

package/dist/cjs/pipeline/exportBagToEsm.cjs

@@ -0,0 +1,81 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.exportBagToEsm = void 0;
+var _exports = require("../utils/exports.cjs");
+const exportBagToEsm = params => {
+  const {
+    code,
+    exportTable,
+    warnOnce
+  } = params;
+  let importMetaRef = params.importMetaRef;
+  const isValidExportName = name => /^[$A-Z_a-z][$\w]*$/.test(name);
+  const asExportName = name => isValidExportName(name) ? name : JSON.stringify(name);
+  const accessProp = name => isValidExportName(name) ? `${_exports.exportsRename}.${name}` : `${_exports.exportsRename}[${JSON.stringify(name)}]`;
+  const exportValueFor = name => {
+    if (name === '__dirname') {
+      importMetaRef = true;
+      return 'import.meta.dirname';
+    }
+    if (name === '__filename') {
+      importMetaRef = true;
+      return 'import.meta.filename';
+    }
+    return name;
+  };
+  const tempNameFor = name => {
+    const sanitized = name.replace(/[^$\w]/g, '_') || 'value';
+    const safe = /^[0-9]/.test(sanitized) ? `_${sanitized}` : sanitized;
+    return `__export_${safe}`;
+  };
+  for (const [key, entry] of exportTable) {
+    if (entry.reassignments.length) {
+      const loc = entry.reassignments[0];
+      warnOnce(`cjs-export-reassignment:${key}`, `Export '${key}' is reassigned after export; ESM live bindings may change consumer behavior.`, {
+        start: loc.start,
+        end: loc.end
+      });
+    }
+  }
+  const lines = [];
+  const defaultEntry = exportTable.get('default');
+  if (defaultEntry) {
+    const def = defaultEntry.fromIdentifier ?? _exports.exportsRename;
+    const defExpr = exportValueFor(def);
+    if (defExpr !== def) {
+      const temp = tempNameFor(def);
+      lines.push(`const ${temp} = ${defExpr};`);
+      lines.push(`export default ${temp};`);
+    } else {
+      lines.push(`export default ${defExpr};`);
+    }
+  }
+  for (const [key, entry] of exportTable) {
+    if (key === 'default') continue;
+    if (!isValidExportName(key)) {
+      warnOnce(`cjs-string-export:${key}`, `Synthesized string-literal export '${key}'. Some tooling may require bracket access to use it.`);
+    }
+    if (entry.fromIdentifier) {
+      const resolved = exportValueFor(entry.fromIdentifier);
+      if (resolved !== entry.fromIdentifier) {
+        const temp = tempNameFor(entry.fromIdentifier);
+        lines.push(`const ${temp} = ${resolved};`);
+        lines.push(`export { ${temp} as ${asExportName(key)} };`);
+      } else {
+        lines.push(`export { ${resolved} as ${asExportName(key)} };`);
+      }
+    } else {
+      const temp = tempNameFor(key);
+      lines.push(`const ${temp} = ${accessProp(key)};`);
+      lines.push(`export { ${temp} as ${asExportName(key)} };`);
+    }
+  }
+  if (lines.length) {
+    code.append(`\n${lines.join('\n')}\n`);
+  }
+  return importMetaRef;
+};
+exports.exportBagToEsm = exportBagToEsm;

package/dist/cjs/pipeline/formatVisitor.cjs

@@ -0,0 +1,171 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.buildFormatVisitor = void 0;
+var _exports = require("../utils/exports.cjs");
+// Narrow typing for ancestorWalk's `this`
+
+const buildFormatVisitor = (ctx, state) => {
+  return async function enter(node, ancestors) {
+    const parent = ancestors[ancestors.length - 2] ?? null;
+    const {
+      code,
+      opts,
+      warnOnce,
+      shadowedBindings,
+      requireMainStrategy,
+      nestedRequireStrategy,
+      shouldRaiseEsm,
+      fullTransform,
+      useExportsBag,
+      exportsMeta,
+      isRequireMainMember,
+      isRequireCall,
+      isStaticRequire,
+      isAsyncContext,
+      isValidUrl,
+      isIdentifierName,
+      assignmentExpression,
+      metaProperty,
+      memberExpression,
+      identifier
+    } = ctx;
+    if (shouldRaiseEsm && node.type === 'ReturnStatement' && parent?.type === 'Program') {
+      warnOnce('top-level-return', 'Top-level return is not allowed in ESM; the transformed module will fail to parse.', {
+        start: node.start,
+        end: node.end
+      });
+    }
+    if (shouldRaiseEsm && node.type === 'BinaryExpression') {
+      const op = node.operator;
+      const isEquality = op === '===' || op === '==' || op === '!==' || op === '!=';
+      if (isEquality) {
+        const leftMain = isRequireMainMember(node.left, shadowedBindings);
+        const rightMain = isRequireMainMember(node.right, shadowedBindings);
+        const leftModule = node.left.type === 'Identifier' && node.left.name === 'module' && !shadowedBindings.has('module');
+        const rightModule = node.right.type === 'Identifier' && node.right.name === 'module' && !shadowedBindings.has('module');
+        if (leftMain && rightModule || rightMain && leftModule) {
+          const negate = op === '!==' || op === '!=';
+          const mainExpr = requireMainStrategy === 'import-meta-main' ? 'import.meta.main' : 'import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href';
+          if (requireMainStrategy === 'realpath') {
+            state.requireMainNeedsRealpath = true;
+            state.importMetaRef = true;
+          }
+          if (requireMainStrategy === 'import-meta-main') {
+            state.importMetaRef = true;
+          }
+          code.update(node.start, node.end, negate ? `!(${mainExpr})` : mainExpr);
+          return;
+        }
+      }
+    }
+    if (shouldRaiseEsm && node.type === 'WithStatement') {
+      throw new Error('Cannot transform to ESM: with statements are not supported.');
+    }
+    if (shouldRaiseEsm && node.type === 'CallExpression' && node.callee.type === 'Identifier' && node.callee.name === 'eval' && !shadowedBindings.has('eval')) {
+      throw new Error('Cannot transform to ESM: eval is not supported.');
+    }
+    if (shouldRaiseEsm && node.type === 'CallExpression' && isRequireCall(node, shadowedBindings)) {
+      const isStatic = isStaticRequire(node, shadowedBindings);
+      const parent = ancestors[ancestors.length - 2] ?? null;
+      const grandparent = ancestors[ancestors.length - 3] ?? null;
+      const greatGrandparent = ancestors[ancestors.length - 4] ?? null;
+      const topLevelExprStmt = parent?.type === 'ExpressionStatement' && grandparent?.type === 'Program';
+      const topLevelVarDecl = parent?.type === 'VariableDeclarator' && grandparent?.type === 'VariableDeclaration' && greatGrandparent?.type === 'Program';
+      const hoistableTopLevel = isStatic && (topLevelExprStmt || topLevelVarDecl);
+      if (!isStatic || !hoistableTopLevel) {
+        if (nestedRequireStrategy === 'dynamic-import') {
+          const asyncCapable = isAsyncContext(ancestors);
+          if (asyncCapable) {
+            const arg = node.arguments[0];
+            const argSrc = arg ? code.slice(arg.start, arg.end) : 'undefined';
+            const literalVal = arg?.value;
+            const isJson = arg?.type === 'Literal' && typeof literalVal === 'string' && (literalVal.split(/[?#]/)[0] ?? literalVal).endsWith('.json');
+            const importTarget = isJson ? `${argSrc} with { type: "json" }` : argSrc;
+            code.update(node.start, node.end, `(await import(${importTarget}))`);
+            return;
+          }
+        }
+        state.needsCreateRequire = true;
+      }
+    }
+    if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {
+      const skipped = ['__filename', '__dirname'];
+      const skippedParams = node.params.filter(param => param.type === 'Identifier' && skipped.includes(param.name));
+      const skippedFuncIdentifier = node.id?.type === 'Identifier' && skipped.includes(node.id.name);
+      if (skippedParams.length || skippedFuncIdentifier) {
+        this.skip();
+      }
+    }
+    if (node.type === 'AssignmentExpression' && node.left.type === 'MemberExpression' && node.left.object.type === 'MetaProperty' && node.left.property.type === 'Identifier' && node.left.property.name === 'url') {
+      if (node.right.type === 'Literal' && typeof node.right.value === 'string') {
+        if (!isValidUrl(node.right.value)) {
+          const rhs = code.snip(node.right.start, node.right.end).toString();
+          const assignment = code.snip(node.start, node.end).toString();
+          code.update(node.start, node.end, `/* Invalid assignment: ${rhs} is not a URL. ${assignment} */`);
+          this.skip();
+        }
+      }
+    }
+    if (node.type === 'MemberExpression' && node.property.type === 'Identifier' && ['__filename', '__dirname'].includes(node.property.name)) {
+      this.skip();
+    }
+    if (node.type === 'MemberExpression' && node.object.type === 'Identifier' && node.object.name === 'module' && node.property.type === 'Identifier' && node.property.name === 'exports' && parent?.type === 'ExpressionStatement') {
+      if (opts.target === 'module') {
+        code.update(node.start, node.end, ';');
+        this.skip();
+      }
+    }
+    if (node.type === 'AssignmentExpression') {
+      await assignmentExpression({
+        node,
+        parent,
+        code,
+        opts,
+        meta: exportsMeta
+      });
+    }
+    if (node.type === 'MetaProperty') {
+      metaProperty(node, parent, code, opts);
+    }
+    if (node.type === 'MemberExpression') {
+      memberExpression(node, parent, code, opts, shadowedBindings, {
+        onRequireResolve: () => {
+          if (shouldRaiseEsm) state.needsRequireResolveHelper = true;
+        },
+        requireResolveName: '__requireResolve',
+        onDiagnostic: (codeId, message, loc) => {
+          if (shouldRaiseEsm) warnOnce(codeId, message, loc);
+        }
+      }, useExportsBag, fullTransform);
+    }
+    if (shouldRaiseEsm && node.type === 'ThisExpression') {
+      const bindsThis = ancestor => {
+        return ancestor.type === 'FunctionDeclaration' || ancestor.type === 'FunctionExpression' || ancestor.type === 'ClassDeclaration' || ancestor.type === 'ClassExpression';
+      };
+      const bindingAncestor = ancestors.find(ancestor => bindsThis(ancestor));
+      const isTopLevel = !bindingAncestor;
+      if (isTopLevel) {
+        code.update(node.start, node.end, _exports.exportsRename);
+        return;
+      }
+    }
+    if (isIdentifierName(node)) {
+      if (shouldRaiseEsm && (node.name === '__dirname' || node.name === '__filename')) {
+        state.importMetaRef = true;
+      }
+      identifier({
+        node,
+        ancestors,
+        code,
+        opts,
+        meta: exportsMeta,
+        shadowed: shadowedBindings,
+        useExportsBag
+      });
+    }
+  };
+};
+exports.buildFormatVisitor = buildFormatVisitor;