trimcode 0.0.0-stage → 0.1.1

package/src/parse.js

@@ -0,0 +1,64 @@
+import { parse } from 'acorn';
+
+/** Thrown when the source cannot be parsed. `line` is 1-based, `column` is 1-based. */
+export class ParseError extends Error {
+  constructor(message, { line, column } = {}) {
+    super(message);
+    this.name = 'ParseError';
+    this.line = line;
+    this.column = column;
+  }
+}
+
+const BASE_OPTIONS = {
+  ecmaVersion: 'latest',
+  locations: true,
+  allowHashBang: true,
+  // CommonJS files may `return` at the top level, and scripts run through
+  // wrappers may `await` there.
+  allowReturnOutsideFunction: true,
+  allowAwaitOutsideFunction: true,
+};
+
+function toParseError(err) {
+  const line = err?.loc?.line;
+  const column = typeof err?.loc?.column === 'number' ? err.loc.column + 1 : undefined;
+  const message = String(err?.message ?? err).replace(/\s*\(\d+:\d+\)$/, '');
+  return new ParseError(message, { line, column });
+}
+
+/**
+ * Parse JavaScript source.
+ *
+ * With `sourceType: 'auto'` the code is parsed as an ES module first and, if
+ * that fails, as a sloppy-mode script (old CommonJS code can use `with`,
+ * octal literals and so on). When both fail, the module error is reported.
+ */
+export function parseSource(code, sourceType = 'auto') {
+  const comments = [];
+  const attempt = (type) => {
+    comments.length = 0;
+    return parse(code, { ...BASE_OPTIONS, sourceType: type, onComment: comments });
+  };
+
+  try {
+    if (sourceType === 'module' || sourceType === 'script') {
+      return { ast: attempt(sourceType), comments };
+    }
+    if (sourceType !== 'auto') {
+      throw new TypeError(`Unknown sourceType "${sourceType}" (expected "auto", "module" or "script")`);
+    }
+    try {
+      return { ast: attempt('module'), comments };
+    } catch (moduleError) {
+      try {
+        return { ast: attempt('script'), comments };
+      } catch {
+        throw moduleError;
+      }
+    }
+  } catch (err) {
+    if (err instanceof TypeError) throw err;
+    throw toParseError(err);
+  }
+}

package/src/util.js

@@ -0,0 +1,119 @@
+/** Name of a non-dynamic property key, or null when it cannot be known statically. */
+export function propKey(key, computed = false) {
+  if (!key) return null;
+  if (key.type === 'PrivateIdentifier') return `#${key.name}`;
+  if (!computed && key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' && (typeof key.value === 'string' || typeof key.value === 'number')) {
+    return String(key.value);
+  }
+  return null;
+}
+
+/** Property name of a MemberExpression (`a.b`, `a['b']`, `this.#b`), or null. */
+export function propName(member) {
+  if (member?.type !== 'MemberExpression') return null;
+  return propKey(member.property, member.computed);
+}
+
+/**
+ * Dotted path for member chains rooted at an identifier, `this` or `super`:
+ * `module.exports.foo` -> "module.exports.foo". Returns null for anything else.
+ */
+export function memberPath(node) {
+  if (!node) return null;
+  switch (node.type) {
+    case 'Identifier':
+      return node.name;
+    case 'ThisExpression':
+      return 'this';
+    case 'Super':
+      return 'super';
+    case 'MemberExpression': {
+      const prop = propName(node);
+      const base = memberPath(node.object);
+      return prop !== null && base ? `${base}.${prop}` : null;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Printable name for a call target. Chains through calls are shown with "()":
+ * `db.query(x).then(y)` -> "db.query().then". Returns null if it cannot be named.
+ */
+export function calleeName(callee) {
+  const direct = memberPath(callee);
+  if (direct) return direct;
+  if (callee?.type === 'MemberExpression') {
+    const prop = propName(callee);
+    let object = callee.object;
+    if (object.type === 'ChainExpression') object = object.expression;
+    if (prop !== null && object.type === 'CallExpression') {
+      const inner = calleeName(object.callee);
+      if (inner) return `${inner}().${prop}`;
+    }
+  }
+  return null;
+}
+
+/** String value of a string literal or an expression-free template literal, else null. */
+export function stringArg(node) {
+  if (!node) return null;
+  if (node.type === 'Literal' && typeof node.value === 'string') return node.value;
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis[0].value.cooked ?? null;
+  }
+  return null;
+}
+
+/** Source text of a node on one line, shortened to `max` characters. */
+export function snippet(code, node, max = 60) {
+  const text = code.slice(node.start, node.end).replace(/\s+/g, ' ').trim();
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** All identifiers bound by a destructuring pattern. */
+export function patternNames(pattern) {
+  if (!pattern) return [];
+  switch (pattern.type) {
+    case 'Identifier':
+      return [pattern.name];
+    case 'ObjectPattern':
+      return pattern.properties.flatMap((p) =>
+        p.type === 'RestElement' ? patternNames(p.argument) : patternNames(p.value),
+      );
+    case 'ArrayPattern':
+      return pattern.elements.flatMap((el) => patternNames(el));
+    case 'AssignmentPattern':
+      return patternNames(pattern.left);
+    case 'RestElement':
+      return patternNames(pattern.argument);
+    default:
+      return [];
+  }
+}
+
+/** True for `require(...)` calls (any argument). */
+export function isRequireCall(node) {
+  return (
+    node?.type === 'CallExpression' &&
+    node.callee.type === 'Identifier' &&
+    node.callee.name === 'require' &&
+    node.arguments.length > 0
+  );
+}
+
+/** First sentence of a JSDoc block's description, or undefined if it has none. */
+export function jsdocSummary(raw) {
+  const lines = raw.split('\n').map((l) => l.replace(/^\s*\*+ ?/, '').trim());
+  const description = [];
+  for (const line of lines) {
+    if (line.startsWith('@')) break;
+    description.push(line);
+  }
+  const text = description.join(' ').replace(/\s+/g, ' ').trim();
+  if (!text) return undefined;
+  const first = /^(.+?[.!?])(\s|$)/.exec(text)?.[1] ?? text;
+  return first.length > 160 ? `${first.slice(0, 159)}…` : first;
+}

package/src/walk.js

@@ -0,0 +1,32 @@
+const SKIP = new Set(['type', 'start', 'end', 'loc', 'range']);
+
+/**
+ * Depth-first AST walk with enter/leave hooks.
+ *
+ * Both hooks receive `(node, ancestors)` where `ancestors` is the chain of
+ * parents, nearest parent last. The array is reused between calls, so copy it
+ * if you need to keep it.
+ */
+export function walk(root, { enter, leave } = {}) {
+  const ancestors = [];
+
+  function visit(node) {
+    if (enter) enter(node, ancestors);
+    ancestors.push(node);
+    for (const key in node) {
+      if (SKIP.has(key)) continue;
+      const value = node[key];
+      if (Array.isArray(value)) {
+        for (const child of value) {
+          if (child && typeof child.type === 'string') visit(child);
+        }
+      } else if (value && typeof value.type === 'string') {
+        visit(value);
+      }
+    }
+    ancestors.pop();
+    if (leave) leave(node, ancestors);
+  }
+
+  visit(root);
+}