@observablehq/notebook-kit 1.0.0

package/dist/src/javascript/imports/npm.js

@@ -0,0 +1,47 @@
+/** Note: specifier here does not start with `npm:`. */
+function parseNpmSpecifier(specifier) {
+    const parts = specifier.split("/");
+    const namerange = specifier.startsWith("@")
+        ? [parts.shift(), parts.shift()].join("/")
+        : parts.shift();
+    const ranged = namerange.indexOf("@", 1);
+    const name = ranged > 0 ? namerange.slice(0, ranged) : namerange;
+    const range = ranged > 0 ? namerange.slice(ranged) : "";
+    const path = parts.length > 0 ? `/${parts.join("/")}` : "";
+    return { name, range, path };
+}
+/** If specifier is an npm: protocol import, resolves it. */
+export function resolveNpmImport(specifier) {
+    if (!specifier.startsWith("npm:"))
+        return specifier;
+    const { name, range, path } = parseNpmSpecifier(specifier.slice(4));
+    return `https://cdn.jsdelivr.net/npm/${name}${range || getDefaultRange(name)}${path
+        ? !/(\.\w+|\/|\/\+esm)$/.test(path) // if not file, directory, or /+esm
+            ? `${path}/+esm` // then append /+esm
+            : path // otherwise keep as-is
+        : getDefaultPath(name)}`;
+}
+function getDefaultRange(name) {
+    switch (name) {
+        case "@duckdb/duckdb-wasm":
+            return "@1.29.0"; // https://github.com/duckdb/duckdb-wasm/issues/1994
+        default:
+            return "";
+    }
+}
+function getDefaultPath(name) {
+    switch (name) {
+        case "mermaid":
+            return "/dist/mermaid.esm.min.mjs/+esm";
+        case "echarts":
+            return "/dist/echarts.esm.min.js/+esm";
+        case "jquery-ui":
+            return "/dist/jquery-ui.js/+esm";
+        case "deck.gl":
+            return "/dist.min.js/+esm";
+        case "react-dom":
+            return "/client/+esm";
+        default:
+            return "/+esm";
+    }
+}

package/dist/src/javascript/imports/npm.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/javascript/imports/npm.test.js

@@ -0,0 +1,32 @@
+import { assert, test } from "vitest";
+import { resolveNpmImport } from "./npm.js";
+test("adds /+esm as expected", () => {
+    assert.strictEqual(resolveNpmImport("npm:prettier"), "https://cdn.jsdelivr.net/npm/prettier/+esm" // defaults to /+esm
+    );
+    assert.strictEqual(resolveNpmImport("npm:prettier/"), "https://cdn.jsdelivr.net/npm/prettier/" // no /+esm because trailing slash
+    );
+    assert.strictEqual(resolveNpmImport("npm:prettier/+esm"), "https://cdn.jsdelivr.net/npm/prettier/+esm" // preserve existing /+esm
+    );
+    assert.strictEqual(resolveNpmImport("npm:prettier/plugins/acorn"), "https://cdn.jsdelivr.net/npm/prettier/plugins/acorn/+esm");
+    assert.strictEqual(resolveNpmImport("npm:prettier/plugins/acorn/+esm"), "https://cdn.jsdelivr.net/npm/prettier/plugins/acorn/+esm" // preserve existing /+esm
+    );
+    assert.strictEqual(resolveNpmImport("npm:prettier/plugins/acorn/"), "https://cdn.jsdelivr.net/npm/prettier/plugins/acorn/" // no /+esm because trailing slash
+    );
+    assert.strictEqual(resolveNpmImport("npm:prettier/plugins/acorn.js"), "https://cdn.jsdelivr.net/npm/prettier/plugins/acorn.js" // no /+esm because file extension
+    );
+    assert.strictEqual(resolveNpmImport("npm:prettier/plugins/acorn.js/+esm"), "https://cdn.jsdelivr.net/npm/prettier/plugins/acorn.js/+esm" // preserve existing /+esm
+    );
+    assert.strictEqual(resolveNpmImport("npm:prettier/plugins/estree"), "https://cdn.jsdelivr.net/npm/prettier/plugins/estree/+esm");
+});
+test("sets the default version of @duckdb/duckdb-wasm", () => {
+    assert.strictEqual(resolveNpmImport("npm:@duckdb/duckdb-wasm"), "https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.29.0/+esm");
+    assert.strictEqual(resolveNpmImport("npm:@duckdb/duckdb-wasm/+esm"), "https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.29.0/+esm");
+    assert.strictEqual(resolveNpmImport("npm:@duckdb/duckdb-wasm/dist/duckdb-mvp.wasm"), "https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.29.0/dist/duckdb-mvp.wasm");
+});
+test("sets the default path for various libraries", () => {
+    assert.strictEqual(resolveNpmImport("npm:mermaid"), "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs/+esm");
+    assert.strictEqual(resolveNpmImport("npm:echarts"), "https://cdn.jsdelivr.net/npm/echarts/dist/echarts.esm.min.js/+esm");
+    assert.strictEqual(resolveNpmImport("npm:jquery-ui"), "https://cdn.jsdelivr.net/npm/jquery-ui/dist/jquery-ui.js/+esm");
+    assert.strictEqual(resolveNpmImport("npm:deck.gl"), "https://cdn.jsdelivr.net/npm/deck.gl/dist.min.js/+esm");
+    assert.strictEqual(resolveNpmImport("npm:react-dom"), "https://cdn.jsdelivr.net/npm/react-dom/client/+esm");
+});

package/dist/src/javascript/imports/observable.d.ts

@@ -0,0 +1,8 @@
+import type { ImportDeclaration } from "acorn";
+/** If specifier is an observable: protocol import, resolves it. */
+export declare function resolveObservableImport(specifier: string): string;
+export declare function isObservableImport(node: ImportDeclaration, specifier: string): boolean;
+/** Note: mutates inputs! */
+export declare function renderObservableImport(source: string, node: ImportDeclaration, inputs: string[]): string;
+/** Turns e.g. "viewof$foo" into "viewof foo", and "$$" into "$". */
+export declare function dedollar(input: string): string;

package/dist/src/javascript/imports/observable.js

@@ -0,0 +1,64 @@
+import { getImportedName } from "../imports.js";
+const CODE_DOLLAR = 36;
+/** If specifier is an observable: protocol import, resolves it. */
+export function resolveObservableImport(specifier) {
+    if (!specifier.startsWith("observable:"))
+        return specifier;
+    return `https://api.observablehq.com/${specifier.slice("observable:".length)}.js?v=4`;
+}
+export function isObservableImport(node, specifier) {
+    const type = node.attributes?.find((a) => getImportAttributeKey(a) === "type")?.value;
+    return type ? type.value === "observable" : specifier.startsWith("observable:");
+}
+function getImportAttributeKey(node) {
+    return node.key.type === "Identifier" ? node.key.name : String(node.key.value);
+}
+/** Note: mutates inputs! */
+export function renderObservableImport(source, node, inputs) {
+    if (!inputs.includes("__ojs_runtime"))
+        inputs.push("__ojs_runtime");
+    if (!inputs.includes("__ojs_observer"))
+        inputs.push("__ojs_observer");
+    return `(import(${JSON.stringify(source)}).then((_) => {
+  const observers = {};
+  const module = __ojs_runtime.module(_.default);
+  const main = __ojs_runtime.module();${node.specifiers
+        .map((specifier) => {
+        if (specifier.type === "ImportNamespaceSpecifier")
+            throw new SyntaxError("observable namespace imports are not supported");
+        const iname = getImportedName(specifier);
+        const vname = dedollar(iname);
+        return `
+  if (!module.defines("${vname}")) throw new SyntaxError(\`export '${vname}' not found\`);
+  main.variable(observers.${iname} = __ojs_observer()).import("${vname}", module);`;
+    })
+        .join("")}
+  return observers;
+}))`;
+}
+/** Turns e.g. "viewof$foo" into "viewof foo", and "$$" into "$". */
+export function dedollar(input) {
+    const start = 0;
+    const end = input.length;
+    let dollars = 0;
+    for (let i = start; i < end; ++i) {
+        switch (input.charCodeAt(i)) {
+            case CODE_DOLLAR: {
+                ++dollars;
+                break;
+            }
+            default: {
+                if (dollars > 0) {
+                    input = `${input.slice(0, i - 1)}${dollars === 1 ? " " : ""}${input.slice(i)}`;
+                    dollars = 0;
+                }
+                break;
+            }
+        }
+    }
+    if (dollars > 0) {
+        input = `${input.slice(0, end - 1)}${dollars === 1 ? " " : ""}`;
+        dollars = 0;
+    }
+    return input;
+}

package/dist/src/javascript/imports/observable.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/javascript/imports/observable.test.js

@@ -0,0 +1,13 @@
+import { assert, test } from "vitest";
+import { dedollar } from "./observable.js";
+test("unescapes dollar signs in imported symbols", () => {
+    assert.strictEqual(dedollar("viewof$foo"), "viewof foo");
+    assert.strictEqual(dedollar("viewof$"), "viewof ");
+    assert.strictEqual(dedollar("$viewof"), " viewof");
+    assert.strictEqual(dedollar("viewof$$foo"), "viewof$foo");
+    assert.strictEqual(dedollar("viewof$$$foo"), "viewof$$foo");
+    assert.strictEqual(dedollar("$"), " ");
+    assert.strictEqual(dedollar("$$"), "$");
+    assert.strictEqual(dedollar("$$$"), "$$");
+    assert.strictEqual(dedollar("$$_"), "$_");
+});

package/dist/src/javascript/imports.d.ts

@@ -0,0 +1,21 @@
+import type { CallExpression, MemberExpression, Node } from "acorn";
+import type { ImportDefaultSpecifier, ImportSpecifier } from "acorn";
+import type { Sourcemap } from "./sourcemap.js";
+type NamedImportSpecifier = ImportSpecifier | ImportDefaultSpecifier;
+/** Throws a syntax error if any export declarations are found. */
+export declare function checkExports(body: Node, input: string): void;
+/** Returns true if the body includes an import declaration. */
+export declare function hasImportDeclaration(body: Node): boolean;
+/** Returns true if the given node is a import.meta.resolve(…) call. */
+export declare function isImportMetaResolve(node: CallExpression): boolean;
+/** Returns true if the given node is a import.meta.url expression. */
+export declare function isImportMetaUrl(node: MemberExpression): boolean;
+export type RewriteImportOptions = {
+    /** If true, resolve local imports relative to document.baseURI. */
+    resolveLocalImports?: boolean;
+};
+export declare function rewriteImportExpressions(output: Sourcemap, body: Node, { resolveLocalImports }?: RewriteImportOptions): void;
+/** Note: mutates inputs! */
+export declare function rewriteImportDeclarations(output: Sourcemap, body: Node, inputs: string[], { resolveLocalImports }?: RewriteImportOptions): void;
+export declare function getImportedName(node: NamedImportSpecifier): string;
+export {};

package/dist/src/javascript/imports.js

@@ -0,0 +1,146 @@
+import { resolveJsrImport } from "./imports/jsr.js";
+import { resolveNpmImport } from "./imports/npm.js";
+import { resolveObservableImport } from "./imports/observable.js";
+import { isObservableImport, renderObservableImport } from "./imports/observable.js";
+import { getStringLiteralValue, isStringLiteral } from "./strings.js";
+import { syntaxError } from "./syntaxError.js";
+import { simple } from "./walk.js";
+/** Throws a syntax error if any export declarations are found. */
+export function checkExports(body, input) {
+    function checkExport(child) {
+        throw syntaxError("Unexpected token 'export'", child, input);
+    }
+    simple(body, {
+        ExportAllDeclaration: checkExport,
+        ExportNamedDeclaration: checkExport
+    });
+}
+/** Returns true if the body includes an import declaration. */
+export function hasImportDeclaration(body) {
+    let has = false;
+    simple(body, {
+        ImportDeclaration() {
+            has = true;
+        }
+    });
+    return has;
+}
+/** Returns true if the given node is a import.meta.resolve(…) call. */
+export function isImportMetaResolve(node) {
+    return (node.callee.type === "MemberExpression" &&
+        node.callee.object.type === "MetaProperty" &&
+        node.callee.object.meta.name === "import" &&
+        node.callee.object.property.name === "meta" &&
+        node.callee.property.type === "Identifier" &&
+        node.callee.property.name === "resolve" &&
+        node.arguments.length > 0);
+}
+/** Returns true if the given node is a import.meta.url expression. */
+export function isImportMetaUrl(node) {
+    return (node.object.type === "MetaProperty" &&
+        node.object.meta.name === "import" &&
+        node.object.property.name === "meta" &&
+        node.property.type === "Identifier" &&
+        node.property.name === "url");
+}
+function resolveImport(specifier) {
+    return resolveObservableImport(resolveJsrImport(resolveNpmImport(specifier)));
+}
+export function rewriteImportExpressions(output, body, { resolveLocalImports } = {}) {
+    function rewriteImportSource(source, node = source) {
+        const value = getStringLiteralValue(source);
+        const resolution = resolveImport(value);
+        output.replaceLeft(node.start, node.end, resolveLocalImports && isLocalImport(resolution)
+            ? `new URL(${JSON.stringify(resolution)}, document.baseURI).href`
+            : JSON.stringify(resolution));
+    }
+    simple(body, {
+        ImportExpression(node) {
+            const source = node.source;
+            if (isStringLiteral(source)) {
+                rewriteImportSource(source);
+            }
+        },
+        MemberExpression(node) {
+            if (resolveLocalImports && isImportMetaUrl(node)) {
+                output.replaceLeft(node.start, node.end, "document.baseURI");
+            }
+        },
+        CallExpression(node) {
+            const source = node.arguments[0];
+            if (isImportMetaResolve(node) && isStringLiteral(source)) {
+                rewriteImportSource(source, node);
+            }
+        }
+    });
+}
+/** Note: mutates inputs! */
+export function rewriteImportDeclarations(output, body, inputs, { resolveLocalImports } = {}) {
+    const declarations = [];
+    simple(body, {
+        ImportDeclaration(node) {
+            if (isStringLiteral(node.source)) {
+                declarations.push([node, node.source]);
+            }
+        }
+    });
+    const specifiers = [];
+    const imports = [];
+    for (const [node, source] of declarations) {
+        output.delete(node.start, node.end + +(output.input[node.end] === "\n"));
+        specifiers.push(rewriteImportSpecifiers(node));
+        const value = getStringLiteralValue(source);
+        const resolution = resolveImport(value);
+        imports.push(isObservableImport(node, value)
+            ? renderObservableImport(resolution, node, inputs)
+            : renderImport(resolveLocalImports && isLocalImport(resolution)
+                ? `new URL(${JSON.stringify(resolution)}, document.baseURI)`
+                : JSON.stringify(resolution), node, output.input));
+    }
+    if (declarations.length > 1) {
+        output.insertLeft(0, `const [${specifiers.join(", ")}] = await Promise.all([${imports.join(", ")}]);\n`);
+    }
+    else if (declarations.length === 1) {
+        output.insertLeft(0, `const ${specifiers[0]} = await ${imports[0]};\n`);
+    }
+}
+function renderImport(source, node, input) {
+    const names = node.specifiers.filter(isNamedSpecifier).map(getImportedName);
+    return `import(${source}${node.attributes.length > 0
+        ? `, {with: {${input.slice(node.attributes[0].start, node.attributes[node.attributes.length - 1].end)}}}`
+        : ""})${names.length > 0
+        ? `.then((module) => {${names.map((name) => `
+  if (!("${name}" in module)) throw new SyntaxError(\`export '${name}' not found\`);`).join("")}
+  return module;
+})`
+        : ""}`;
+}
+function getLocalName(node) {
+    return node.local.name;
+}
+export function getImportedName(node) {
+    return node.type === "ImportDefaultSpecifier"
+        ? "default"
+        : node.imported.type === "Identifier"
+            ? node.imported.name
+            : node.imported.raw;
+}
+function isLocalImport(source) {
+    return ["./", "../", "/"].some((prefix) => source.startsWith(prefix));
+}
+function isNamespaceSpecifier(node) {
+    return node.type === "ImportNamespaceSpecifier";
+}
+function isNamedSpecifier(node) {
+    return node.type !== "ImportNamespaceSpecifier";
+}
+function rewriteImportSpecifiers(node) {
+    return node.specifiers.some(isNamedSpecifier)
+        ? `{${node.specifiers.filter(isNamedSpecifier).map(rewriteImportSpecifier).join(", ")}}`
+        : (node.specifiers.find(isNamespaceSpecifier)?.local.name ?? "{}");
+}
+function rewriteImportSpecifier(node) {
+    return getImportedName(node) === getLocalName(node)
+        ? getLocalName(node)
+        : `${getImportedName(node)}: ${getLocalName(node)}`;
+}

package/dist/src/javascript/observable.d.ts

@@ -0,0 +1,2 @@
+import type { TranspiledJavaScript, TranspileOptions } from "./transpile.js";
+export declare function transpileObservable(input: string, options?: TranspileOptions): TranspiledJavaScript;

package/dist/src/javascript/observable.js

@@ -0,0 +1,72 @@
+import { parseCell } from "@observablehq/parser";
+import { rewriteFileExpressions } from "./files.js";
+import { Sourcemap } from "./sourcemap.js";
+import { transpileJavaScript } from "./transpile.js";
+import { simple } from "./walk.js";
+export function transpileObservable(input, options) {
+    const cell = parseCell(input);
+    if (!cell.body)
+        return transpileJavaScript(input);
+    if (cell.tag)
+        throw new Error("tagged ojs cells are not supported");
+    const output = new Sourcemap(input).trim();
+    if (cell.body.type === "ImportDeclaration") {
+        rewriteImportSource(output, cell.body);
+        return transpileJavaScript(String(output));
+    }
+    if (options?.resolveFiles)
+        rewriteFileExpressions(output, cell.body);
+    rewriteSpecialReferences(output, cell.body);
+    const inputs = Array.from(new Set(cell.references.map(asReference)));
+    let start = "";
+    let end = "";
+    start += `${cell.async ? "async " : ""}function${cell.generator ? "*" : ""}`;
+    if (cell.id)
+        start += ` ${asReference(cell.id)}`;
+    start += `(${inputs})`;
+    if (cell.body.type !== "BlockStatement") {
+        start += "{return(";
+        end += ")}";
+    }
+    output.replaceLeft(0, cell.body.start, `${start}\n`);
+    output.replaceRight(cell.body.end, input.length, `\n${end}`);
+    return {
+        body: String(output),
+        inputs,
+        output: cell.id ? asDeclaration(cell.id) : undefined,
+        autodisplay: true,
+        automutable: cell.id?.type === "MutableExpression",
+        autoview: cell.id?.type === "ViewExpression"
+    };
+}
+function rewriteImportSource(output, body) {
+    const specifier = body.source.value;
+    if (typeof specifier === "string" && !/^\w+:/.test(specifier))
+        output.insertLeft(body.source.start + 1, "observable:");
+    output.insertRight(body.end, ";");
+}
+// Rewrite viewof x ↦ viewof$x, and mutable x ↦ mutable$x.value.
+function rewriteSpecialReferences(output, body) {
+    simple(body, {
+        MutableExpression(node) {
+            output.replaceLeft(node.start, node.end, `${asReference(node)}.value`);
+        },
+        ViewExpression(node) {
+            output.replaceLeft(node.start, node.end, asReference(node));
+        }
+    });
+}
+function asReference(ref) {
+    return ref.type === "ViewExpression"
+        ? `viewof$${ref.id.name}`
+        : ref.type === "MutableExpression"
+            ? `mutable$${ref.id.name}`
+            : ref.name;
+}
+function asDeclaration(ref) {
+    return ref.type === "ViewExpression"
+        ? `viewof$${ref.id.name}`
+        : ref.type === "MutableExpression"
+            ? `mutable ${ref.id.name}` // "initial x", really
+            : ref.name;
+}

package/dist/src/javascript/parse.d.ts

@@ -0,0 +1,11 @@
+import type { Expression, Identifier, Options, Program } from "acorn";
+export declare const acornOptions: Options;
+export interface JavaScriptCell {
+    body: Program | Expression;
+    declarations: Identifier[] | null;
+    references: Identifier[];
+    expression: boolean;
+    async: boolean;
+}
+export declare function maybeParseJavaScript(input: string): JavaScriptCell | undefined;
+export declare function parseJavaScript(input: string): JavaScriptCell;

package/dist/src/javascript/parse.js

@@ -0,0 +1,53 @@
+import { Parser, tokTypes } from "acorn";
+import { checkExports } from "./imports.js";
+import { findReferences } from "./references.js";
+import { checkAssignments } from "./assignments.js";
+import { findDeclarations } from "./declarations.js";
+import { findAwaits } from "./awaits.js";
+export const acornOptions = {
+    ecmaVersion: "latest",
+    sourceType: "module"
+};
+export function maybeParseJavaScript(input) {
+    try {
+        return parseJavaScript(input);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        return;
+    }
+}
+export function parseJavaScript(input) {
+    let expression = maybeParseExpression(input); // first attempt to parse as expression
+    if (expression?.type === "ClassExpression" && expression.id)
+        expression = null; // treat named class as program
+    if (expression?.type === "FunctionExpression" && expression.id)
+        expression = null; // treat named function as program
+    const body = expression ?? parseProgram(input); // otherwise parse as a program
+    checkExports(body, input);
+    const references = findReferences(body);
+    checkAssignments(body, references, input);
+    return {
+        body,
+        declarations: expression ? null : findDeclarations(body, input),
+        references,
+        expression: !!expression,
+        async: findAwaits(body).length > 0
+    };
+}
+function parseProgram(input) {
+    return Parser.parse(input, acornOptions);
+}
+function maybeParseExpression(input) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const parser = new Parser(acornOptions, input, 0); // private constructor
+    parser.nextToken();
+    try {
+        const node = parser.parseExpression();
+        return parser.type === tokTypes.eof ? node : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/javascript/references.d.ts

@@ -0,0 +1,8 @@
+import type { Identifier, Node } from "acorn";
+export declare function findReferences(node: Node, { globals, filterReference, filterDeclaration }?: {
+    globals?: Set<string>;
+    filterReference?: (identifier: Identifier) => boolean;
+    filterDeclaration?: (identifier: {
+        name: string;
+    }) => boolean;
+}): Identifier[];

package/dist/src/javascript/references.js

@@ -0,0 +1,129 @@
+import { defaultGlobals } from "./globals.js";
+import { ancestor } from "./walk.js";
+function isScope(node) {
+    return (node.type === "FunctionExpression" ||
+        node.type === "FunctionDeclaration" ||
+        node.type === "ArrowFunctionExpression" ||
+        node.type === "Program");
+}
+// prettier-ignore
+function isBlockScope(node) {
+    return (node.type === "BlockStatement" ||
+        node.type === "SwitchStatement" ||
+        node.type === "ForInStatement" ||
+        node.type === "ForOfStatement" ||
+        node.type === "ForStatement" ||
+        isScope(node));
+}
+export function findReferences(node, { globals = defaultGlobals, filterReference = (identifier) => !globals.has(identifier.name), filterDeclaration = () => true } = {}) {
+    const locals = new Map();
+    const references = [];
+    function hasLocal(node, name) {
+        const l = locals.get(node);
+        return l ? l.has(name) : false;
+    }
+    function declareLocal(node, id) {
+        if (!filterDeclaration(id))
+            return;
+        const l = locals.get(node);
+        if (l)
+            l.add(id.name);
+        else
+            locals.set(node, new Set([id.name]));
+    }
+    function declareClass(node) {
+        if (node.id)
+            declareLocal(node, node.id);
+    }
+    function declareFunction(node) {
+        node.params.forEach((param) => declarePattern(param, node));
+        if (node.id)
+            declareLocal(node, node.id);
+        if (node.type !== "ArrowFunctionExpression")
+            declareLocal(node, { name: "arguments" });
+    }
+    function declareCatchClause(node) {
+        if (node.param)
+            declarePattern(node.param, node);
+    }
+    function declarePattern(node, parent) {
+        switch (node.type) {
+            case "Identifier":
+                declareLocal(parent, node);
+                break;
+            case "ObjectPattern":
+                node.properties.forEach((node) => declarePattern(node.type === "Property" ? node.value : node, parent));
+                break;
+            case "ArrayPattern":
+                node.elements.forEach((node) => node && declarePattern(node, parent));
+                break;
+            case "RestElement":
+                declarePattern(node.argument, parent);
+                break;
+            case "AssignmentPattern":
+                declarePattern(node.left, parent);
+                break;
+        }
+    }
+    ancestor(node, {
+        VariableDeclaration(node, _state, parents) {
+            let parent = null;
+            for (let i = parents.length - 1; i >= 0 && parent === null; --i) {
+                if (node.kind === "var" ? isScope(parents[i]) : isBlockScope(parents[i])) {
+                    parent = parents[i];
+                }
+            }
+            node.declarations.forEach((declaration) => declarePattern(declaration.id, parent));
+        },
+        FunctionDeclaration(node, _state, parents) {
+            let parent = null;
+            for (let i = parents.length - 2; i >= 0 && parent === null; --i) {
+                if (isScope(parents[i])) {
+                    parent = parents[i];
+                }
+            }
+            if (node.id)
+                declareLocal(parent, node.id);
+            declareFunction(node);
+        },
+        FunctionExpression: declareFunction,
+        ArrowFunctionExpression: declareFunction,
+        ClassDeclaration(node, _state, parents) {
+            let parent = null;
+            for (let i = parents.length - 2; i >= 0 && parent === null; --i) {
+                if (isScope(parents[i])) {
+                    parent = parents[i];
+                }
+            }
+            if (node.id)
+                declareLocal(parent, node.id);
+        },
+        ClassExpression: declareClass,
+        CatchClause: declareCatchClause,
+        ImportDeclaration(node, _state, [root]) {
+            node.specifiers.forEach((specifier) => declareLocal(root, specifier.local));
+        }
+    });
+    function identifier(node, _state, parents) {
+        const name = node.name;
+        if (name === "undefined")
+            return;
+        for (let i = parents.length - 2; i >= 0; --i) {
+            if (hasLocal(parents[i], name)) {
+                return;
+            }
+        }
+        if (filterReference(node)) {
+            references.push(node);
+        }
+    }
+    ancestor(node, {
+        Pattern(node, _state, parents) {
+            if (node.type === "Identifier") {
+                identifier(node, _state, parents);
+            }
+        },
+        Identifier: identifier
+    });
+    return references;
+}

package/dist/src/javascript/references.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/javascript/references.test.js

@@ -0,0 +1,38 @@
+import { expect, test } from "vitest";
+import { parseJavaScript } from "./parse.js";
+function find(input) {
+    return parseJavaScript(input).references;
+}
+test("finds references in expressions", () => {
+    expect(find(`foo + bar`)).toMatchSnapshot();
+});
+test("finds references in statements", () => {
+    expect(find(`foo + bar;`)).toMatchSnapshot();
+});
+test("finds multiple references", () => {
+    expect(find(`const a = b + c;\nconst d = c - b;`)).toMatchSnapshot();
+});
+test("doesn’t consider the identifier a reference", () => {
+    expect(find(`function foo() { return bar; }`)).toMatchSnapshot();
+});
+test("local variables can mask references", () => {
+    expect(find(`{ let foo; foo + bar; }`)).toMatchSnapshot();
+});
+test("local variables can not mask references", () => {
+    expect(find(`{ foo + bar; { let foo; } }`)).toMatchSnapshot();
+});
+test("function parameters can mask references", () => {
+    expect(find(`foo => foo + bar`)).toMatchSnapshot();
+});
+test("function rest parameters can mask references", () => {
+    expect(find(`(...foo) => foo + bar`)).toMatchSnapshot();
+});
+test("destructured variables can mask references", () => {
+    expect(find(`{ let {foo} = null; foo + bar; }`)).toMatchSnapshot();
+});
+test("destructured rest variables can mask references", () => {
+    expect(find(`{ let {...foo} = null; foo + bar; }`)).toMatchSnapshot();
+});
+test("ignores globals", () => {
+    expect(find(`window + bar`)).toMatchSnapshot();
+});