@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/src/cucumber.ts

@@ -0,0 +1,230 @@
+import { Writable } from "node:stream";
+import { supportCodeLibraryBuilder } from "@cucumber/cucumber";
+import { type IRunOptions, type ISupportCodeLibrary, runCucumber } from "@cucumber/cucumber/api";
+import { type CucumberExpression, type Node, NodeType } from "@cucumber/cucumber-expressions";
+import { IdGenerator, type Pickle, type PickleStep, TestStepResultStatus } from "@cucumber/messages";
+import { Query } from "@cucumber/query";
+
+/*
+ * Cucumber, as Sanoma runs it: a support code library built from data (never from files it
+ * imports), and runs of feature files in this process, one after another, read back through
+ * Cucumber's own `Query` of its messages. Internal: `scenario.ts` says what the steps mean.
+ * Server-side only.
+ *
+ * Each step definition's code hands the step to the run's World (`SanomaWorld.step`), so one
+ * library serves every kind of run (compiling a scenario, checking a run, an operation's own
+ * test): only the World differs, and each run makes its own.
+ */
+
+/** A parameter type the steps' expressions use, as Cucumber's `defineParameterType` takes it. */
+export interface ParameterTypeSpec {
+  name: string;
+  regexp: RegExp | string | readonly (RegExp | string)[];
+  transformer: (...match: string[]) => unknown;
+}
+
+/** What one run does with its scenarios' steps. */
+export interface SanomaWorld {
+  /** Called before the scenario's first step. */
+  begin(pickle: Pickle): void;
+  /** Runs one step: `expression` is the expression it matched, `values` its parameters. */
+  step(expression: string, values: unknown[], pickleStep: PickleStep): unknown;
+}
+
+/**
+ * Builds a support code library: the parameter types, then one step definition per expression,
+ * each handing its step to the World. Cucumber keeps one builder per process, so the library is
+ * built here, by hand, in one synchronous stretch (`reset`, register, `finalize`): building it
+ * again in the same process gives the same definitions, where a second `loadSupport` would
+ * import nothing new and find none.
+ */
+export function buildLibrary(
+  parameterTypes: readonly ParameterTypeSpec[],
+  expressions: Iterable<string>,
+): ISupportCodeLibrary {
+  const builder = supportCodeLibraryBuilder;
+  builder.reset(process.cwd(), IdGenerator.uuid(), {
+    requireModules: [],
+    requirePaths: [],
+    importPaths: [],
+    loaders: [],
+  });
+  const { defineParameterType, defineStep, Before, BeforeStep } = builder.methods;
+  for (const { name, regexp, transformer } of parameterTypes) {
+    defineParameterType({ name, regexp: regexp as RegExp, transformer, useForSnippets: false });
+  }
+  for (const expression of expressions) defineStep(expression, stepCode(expression));
+  Before(function (this: Current, { pickle }) {
+    if (this.run.skips(pickle)) return "skipped";
+    this.begin(pickle);
+    return undefined;
+  });
+  BeforeStep(function (this: Current, { pickleStep }) {
+    this.current = pickleStep;
+  });
+  const library = builder.finalize();
+  // Cucumber checks a definition's code's `length` against what it passes: the expression's
+  // parameters, then the step's doc string or table, or else a callback. Its own parse of each
+  // expression says how many parameters it has.
+  for (const { code, expression } of library.stepDefinitions) {
+    Object.defineProperty(code, "length", {
+      value: countParameters((expression as CucumberExpression).ast) + 1,
+    });
+  }
+  return library;
+}
+
+/** The World as the library's code sees it: the run's, with the run's state and the step being run. */
+type Current = SanomaWorld & { current: PickleStep; run: RunState };
+
+/** What a run's Worlds share: which scenarios it skips, and where a bug in a step's code goes. */
+interface RunState {
+  skips(pickle: Pickle): boolean;
+  caught(err: unknown): void;
+}
+
+const countParameters = (node: Node): number =>
+  node.type === NodeType.parameter ? 1 : (node.nodes ?? []).reduce((n, child) => n + countParameters(child), 0);
+
+/**
+ * A step definition's code. Cucumber passes the expression's values, then the step's doc string
+ * or table when it has one, then a callback: with one more argument than the parameters it took
+ * the callback of a step with no argument (the callback interface), and with two more, the
+ * argument of a step that has one (the promise interface). The World reads the argument from
+ * the pickle step, so the code answers both.
+ */
+function stepCode(expression: string) {
+  const code = function (this: Current, ...args: unknown[]) {
+    const parameters = code.length - 1;
+    const result = Promise.resolve()
+      .then(() => this.step(expression, args.slice(0, parameters), this.current))
+      .catch((err: unknown) => {
+        this.run.caught(err);
+        throw err;
+      });
+    if (args.length > parameters + 1) return result;
+    const done = args.at(-1) as (error: unknown, result?: unknown) => void;
+    result.then(
+      (value) => done(null, value),
+      (err: unknown) => done(err),
+    );
+    return undefined;
+  };
+  return code;
+}
+
+/** How one step ended. */
+export interface StepResult {
+  status: TestStepResultStatus;
+  /** Why it failed: its error's message. */
+  message?: string;
+  /** The expressions that match it: none for an undefined step, more than one for an ambiguous one. */
+  matches: string[];
+}
+
+/** What a run read: Cucumber's `Query` of its messages, each file's text, and the files Gherkin could not parse. */
+export interface Report {
+  query: Query;
+  /** Each file's text, by its path relative to the run's `cwd`. */
+  texts: Map<string, string>;
+  /** Files Gherkin could not parse; none of the run's scenarios ran when there are any. */
+  parseErrors: { uri: string; line?: number; message: string }[];
+}
+
+/** How each step of a run ended, by its pickle step's id; a step of a pickle that did not run has none. */
+export function stepResults({ query }: Report): Map<string, StepResult> {
+  const results = new Map<string, StepResult>();
+  for (const finished of query.findAllTestStepFinished()) {
+    const testStep = query.findTestStepBy(finished);
+    if (!testStep?.pickleStepId) continue;
+    const { status, message, exception } = finished.testStepResult;
+    const why = exception?.message ?? message;
+    results.set(testStep.pickleStepId, {
+      status,
+      matches: query.findStepDefinitionsBy(testStep).map((d) => d.pattern.source),
+      ...(why !== undefined && { message: why }),
+    });
+  }
+  return results;
+}
+
+/** A pickle's line: its examples row's, or its scenario's. */
+export const lineOf = (report: Report, pickle: Pickle) => report.query.findLocationOf(pickle)?.line ?? 1;
+
+/** A stream that drops what it is given: Cucumber's formatters and logger write nowhere. */
+const sink = () =>
+  new Writable({
+    write(_chunk, _encoding, callback) {
+      callback();
+    },
+  });
+
+/**
+ * A path as a glob that matches it alone: Cucumber globs each path it is given, and reads one
+ * whose name starts with `@` as a list of paths. Brackets escape what they can; brace
+ * expansion reads braces and commas before brackets, so those (and backslashes) match any
+ * character instead.
+ */
+const literal = (path: string) => path.replaceAll(/[*?[\]()+@]/g, "[$&]").replaceAll(/[{},\\]/g, "?");
+
+/**
+ * Runs the feature files `files` (relative to `cwd`) with the library, serially, in this
+ * process, and reads back what happened. `line`, with a single file, runs only the scenario or
+ * examples row at that line. `makeWorld` makes each scenario's World, given the report so far
+ * (every file and pickle, read before the first scenario starts). A dry run matches the steps
+ * and runs none. A step's error that is a bug in code (`isBug`) is rethrown once the run is
+ * over, rather than reported as the step's failure.
+ */
+export async function runFeatures(
+  library: ISupportCodeLibrary,
+  makeWorld: (report: Report) => SanomaWorld,
+  {
+    cwd,
+    files,
+    line,
+    dryRun = false,
+    isBug,
+  }: { cwd: string; files: string[]; line?: number; dryRun?: boolean; isBug: (err: unknown) => boolean },
+): Promise<Report> {
+  const report: Report = { query: new Query(), texts: new Map(), parseErrors: [] };
+  let bug: unknown;
+  const run: RunState = {
+    skips: (pickle) => line !== undefined && lineOf(report, pickle) !== line,
+    caught: (err) => {
+      if (isBug(err)) bug ??= err;
+    },
+  };
+  // Cucumber makes a scenario's World with `new`: a constructor that returns an object gives that object.
+  function World() {
+    return Object.assign(makeWorld(report), { run });
+  }
+  const configuration: IRunOptions = {
+    sources: { defaultDialect: "en", paths: files.map(literal), names: [], tagExpression: "", order: "defined" },
+    support: { ...library, World } as ISupportCodeLibrary,
+    runtime: {
+      dryRun,
+      failFast: false,
+      filterStacktraces: true,
+      parallel: 0,
+      retry: 0,
+      retryTagFilter: "",
+      strict: true,
+      worldParameters: {},
+    },
+    // Cucumber always formats to stdout, here a sink: `rerun` is the formatter that does least.
+    formats: { stdout: "rerun", files: {}, publish: false, options: {} },
+  };
+  await runCucumber(configuration, { cwd, stdout: sink(), stderr: sink(), env: {} }, (envelope) => {
+    report.query.update(envelope);
+    const { source, parseError } = envelope;
+    if (source) report.texts.set(source.uri, source.data);
+    if (parseError) {
+      const { uri = "", location } = parseError.source;
+      report.parseErrors.push({ uri, ...(location && { line: location.line }), message: parseError.message });
+    }
+  });
+  if (bug !== undefined) throw bug;
+  return report;
+}
+
+export { TestStepResultStatus as StepStatus };

package/src/datafile.ts

@@ -0,0 +1,409 @@
+import { basename, dirname, join } from "node:path";
+import type { Node } from "./ast.ts";
+import { inside, nearestDir, RELATIVE } from "./paths.ts";
+
+// The one definition of what a data file may hold, over an ESTree program from oxc: the reader
+// (`resources.ts`), `lintResources` (`lint.ts`) and the oxlint plugin (`plugin.ts`) all
+// read a file through `readDataFile`. Type imports only, so the plugin, which oxlint hands its
+// own tree, never loads oxc-parser.
+
+/** Something a data file may not hold, at UTF-16 offsets into its text. */
+export interface DataFileProblem {
+  start: number;
+  end: number;
+  message: string;
+}
+
+/** A name in a data file that refers to a declared resource: one imported from a data file, or exported by this one. */
+export class Reference {
+  readonly name: string;
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+
+/** A value in a data file: a literal, or a reference to a declared resource. */
+export type DataValue = null | boolean | number | string | Reference | DataValue[] | { [field: string]: DataValue };
+
+/** An `import { name } from "…"`: of a connector's constructors (`from "…/resources"`), or of another data file's resource. */
+export interface DataFileImport {
+  kind: "constructors" | "file";
+  /** The specifier as written. */
+  source: string;
+  /** The name the other module exports. */
+  imported: string;
+  /** The name it has in this file. */
+  local: string;
+  start: number;
+}
+
+/** An `export const name = vendor.type({ … })`. */
+export interface DataFileExport {
+  name: string;
+  /** The local name of the constructors it calls (`github`). */
+  vendor: string;
+  type: string;
+  desired: { [field: string]: DataValue };
+  /** The `export const` statement. */
+  start: number;
+  end: number;
+}
+
+export interface DataFile {
+  imports: DataFileImport[];
+  /** Each `export const` whose value is in the subset. */
+  exports: DataFileExport[];
+  /** Every name an `export const` declares, its value in the subset or not. */
+  declared: string[];
+  problems: DataFileProblem[];
+}
+
+/** A connector's constructors entry: a package specifier that ends in `/resources`. */
+const CONSTRUCTORS = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*\/resources$/;
+
+const SHAPE =
+  "a data file holds only imports, `export const <name> = <vendor>.<type>({ … })` and `export default [ … ]`";
+const IMPORTS =
+  "import resource constructors from a connector's resources entry " +
+  '(`import { github } from "@sanoma-ai/connector-github/resources"`) ' +
+  'and resources from other data files (`import { site } from "./github.ts"`)';
+const VALUES = "write a string, number, boolean, null, object or array, or name a declared resource";
+
+/**
+ * Reads a data file's program without running it: its imports, each `export const` resource
+ * with its fields evaluated, and everything outside the data-file subset as a problem that says
+ * what to write instead.
+ *
+ * The subset: named imports, from a connector's `…/resources` entry or a `.ts` data file;
+ * `export const <name> = <vendor>.<type>({ … })`, one per statement, its argument built of
+ * strings (template literals without `${}` too), numbers, booleans, null, objects and arrays,
+ * and names of resources this file declares or imports; and `export default [a, b]`.
+ *
+ * `root` is the directory relative imports must stay in: by default the nearest `resources/`
+ * directory above `filename`, else the file's own.
+ */
+export function readDataFile(
+  program: Node,
+  filename: string,
+  root: string = nearestDir(filename, ["resources"]),
+): DataFile {
+  const problems: DataFileProblem[] = [];
+  const fail = (node: { start: number; end: number }, message: string) =>
+    problems.push({ start: node.start, end: node.end, message });
+  const imports: DataFileImport[] = [];
+  const exports: DataFileExport[] = [];
+  // Names a refused import or declaration binds: reported once, where they are bound.
+  const refused = new Set<string>();
+
+  // Imports and top-level names first, each once: imports are hoisted, and a reference may name
+  // a resource declared further down. An unexported const is refused where it is declared, not
+  // again where it is used.
+  const bound = new Set<string>();
+  const bind = (id: Node) => {
+    if (bound.has(id.name)) fail(id, `${id.name} is declared twice in this file: give each its own name`);
+    bound.add(id.name);
+  };
+  const declared = new Set<string>();
+  for (const s of program.body) {
+    if (s.type === "ImportDeclaration") {
+      for (const sp of s.specifiers) bind(sp.local);
+      readImport(s);
+      continue;
+    }
+    const decl = s.type === "ExportNamedDeclaration" ? s.declaration : s;
+    if (decl?.type !== "VariableDeclaration") continue;
+    for (const d of decl.declarations) {
+      if (d.id.type !== "Identifier") continue;
+      bind(d.id);
+      (decl === s ? refused : declared).add(d.id.name);
+    }
+  }
+
+  for (const s of program.body) {
+    switch (s.type) {
+      case "ImportDeclaration":
+        break;
+      case "ExportNamedDeclaration":
+        readExport(s);
+        break;
+      case "ExportDefaultDeclaration":
+        readDefault(s);
+        break;
+      case "ExportAllDeclaration":
+        fail(s, `export * is not allowed in a data file: ${SHAPE}`);
+        break;
+      case "VariableDeclaration": {
+        const name = s.declarations[0]?.id?.name;
+        fail(
+          s,
+          name === undefined
+            ? `an unexported declaration is not allowed in a data file: ${SHAPE}`
+            : `\`${s.kind} ${name}\` is not allowed in a data file: export it as a resource, \`export const ${name} = <vendor>.<type>({ … })\`, or write its value where it is used`,
+        );
+        break;
+      }
+      default:
+        fail(s, `${describe(s)} is not allowed in a data file: ${SHAPE}`);
+    }
+  }
+
+  function readImport(s: Node) {
+    const spec: string = s.source.value;
+    if (s.importKind === "type") {
+      fail(s, "`import type` is not allowed in a data file: it holds values only, and the constructors type them");
+      return;
+    }
+    const refusal = whyRefused(spec);
+    if (refusal) {
+      fail(s.source, `import "${spec}" is not allowed in a data file: ${refusal}`);
+      for (const sp of s.specifiers) refused.add(sp.local.name);
+      return;
+    }
+    if (!s.specifiers.length) {
+      fail(s, `import "${spec}" is not allowed in a data file: it imports nothing, and a data file runs no code`);
+      return;
+    }
+    for (const sp of s.specifiers) {
+      if (sp.type !== "ImportSpecifier") {
+        const how = sp.type === "ImportNamespaceSpecifier" ? `import * as ${sp.local.name}` : `import ${sp.local.name}`;
+        fail(sp, `${how} is not allowed in a data file: import the names you use, \`import { name } from "${spec}"\``);
+        continue;
+      }
+      if (sp.importKind === "type") {
+        fail(sp, "`type` imports are not allowed in a data file: it holds values only, and the constructors type them");
+        continue;
+      }
+      const imported: string = sp.imported.name ?? sp.imported.value;
+      const kind = RELATIVE.test(spec) ? "file" : "constructors";
+      imports.push({ kind, source: spec, imported, local: sp.local.name, start: sp.start });
+    }
+  }
+
+  /** Why an import's specifier is not allowed in a data file, or undefined when it is. */
+  function whyRefused(spec: string): string | undefined {
+    if (!RELATIVE.test(spec)) return CONSTRUCTORS.test(spec) ? undefined : IMPORTS;
+    if (!spec.endsWith(".ts")) return "name the data file with its `.ts` extension";
+    if (!inside(root, join(dirname(filename), spec))) {
+      return `it reaches outside ${basename(root)}/; import only other data files`;
+    }
+    return undefined;
+  }
+
+  function readExport(s: Node) {
+    const decl = s.declaration;
+    if (!decl) {
+      fail(
+        s,
+        s.source
+          ? `export … from "${s.source.value}" is not allowed in a data file: import what you reference, and export only resources declared here`
+          : "export { … } is not allowed in a data file: export each resource where it is declared, `export const name = <vendor>.<type>({ … })`",
+      );
+      return;
+    }
+    if (decl.type !== "VariableDeclaration") {
+      fail(s, `${describe(decl)} is not allowed in a data file: ${SHAPE}`);
+      return;
+    }
+    if (decl.kind !== "const") {
+      fail(s, `\`export ${decl.kind}\` is not allowed in a data file: use \`export const\``);
+      return;
+    }
+    if (decl.declarations.length !== 1) {
+      fail(s, "declare one resource per `export const`");
+      return;
+    }
+    const [d] = decl.declarations;
+    if (d.id.type !== "Identifier") {
+      fail(d.id, "an `export const` names one resource: `export const name = <vendor>.<type>({ … })`");
+      return;
+    }
+    const name: string = d.id.name;
+    // A second declaration of the name was reported where it is bound.
+    if (exports.some((e) => e.name === name)) return;
+    const init = d.init;
+    const callee = init?.type === "CallExpression" ? init.callee : undefined;
+    if (
+      callee?.type !== "MemberExpression" ||
+      callee.computed ||
+      callee.object.type !== "Identifier" ||
+      callee.property.type !== "Identifier"
+    ) {
+      fail(
+        init ?? d,
+        `export const ${name} must be a resource constructor call, \`<vendor>.<type>({ … })\`, with <vendor> imported from a connector's resources entry`,
+      );
+      return;
+    }
+    const vendor: string = callee.object.name;
+    const type: string = callee.property.name;
+    if (refused.has(vendor)) return;
+    if (imports.find((i) => i.local === vendor)?.kind !== "constructors") {
+      fail(
+        callee.object,
+        `${vendor} is not a connector's resource constructors: import it from the connector's resources entry, \`import { ${vendor} } from "@sanoma-ai/connector-${vendor}/resources"\``,
+      );
+      return;
+    }
+    const [arg] = init.arguments;
+    if (init.arguments.length !== 1 || arg.type !== "ObjectExpression") {
+      fail(init, `${vendor}.${type} takes one object literal: \`${vendor}.${type}({ … })\``);
+      return;
+    }
+    const desired = value(arg);
+    if (desired !== undefined) {
+      exports.push({ name, vendor, type, desired: desired as DataFileExport["desired"], start: s.start, end: s.end });
+    }
+  }
+
+  function readDefault(s: Node) {
+    const list = s.declaration;
+    if (list.type !== "ArrayExpression") {
+      fail(list, "export default must list this file's resources: `export default [a, b]`");
+      return;
+    }
+    for (const el of list.elements) {
+      if (el?.type !== "Identifier") {
+        fail(el ?? list, "export default must list this file's resources by name: `export default [a, b]`");
+      } else if (!declared.has(el.name)) {
+        fail(el, `${el.name} is not declared in this file: export default lists this file's resources`);
+      }
+    }
+  }
+
+  /** The value an expression stands for, or undefined (with a problem) when the subset has none. */
+  function value(node: Node): DataValue | undefined {
+    switch (node.type) {
+      case "Literal":
+        if (node.regex) return refuse(node, "a regular expression is not allowed in a data file: write it as a string");
+        if (node.bigint !== undefined && node.bigint !== null)
+          return refuse(node, "a bigint is not allowed in a data file: write a number, or a string");
+        return node.value as null | boolean | number | string;
+      case "TemplateLiteral":
+        if (node.expressions.length) {
+          return refuse(node, "a template with `${…}` is not allowed in a data file: write the string out");
+        }
+        return node.quasis[0].value.cooked as string;
+      case "UnaryExpression":
+        if (node.operator === "-" && node.argument.type === "Literal" && typeof node.argument.value === "number") {
+          return -node.argument.value;
+        }
+        return refuse(node, `\`${node.operator}\` is not allowed in a data file: write the value out`);
+      case "ArrayExpression": {
+        const items: DataValue[] = [];
+        let ok = true;
+        for (const el of node.elements) {
+          const item =
+            el === null
+              ? refuse(node, "an empty array slot is not allowed in a data file: write null")
+              : el.type === "SpreadElement"
+                ? refuse(el, "a spread is not allowed in a data file: write the items out, so the reader sees each")
+                : value(el);
+          if (item === undefined) ok = false;
+          else items.push(item);
+        }
+        return ok ? items : undefined;
+      }
+      case "ObjectExpression": {
+        const fields = new Map<string, DataValue>();
+        let ok = true;
+        for (const p of node.properties) {
+          const field = property(p);
+          if (field && fields.has(field[0])) fail(p, `${field[0]} is given twice: give each field once`);
+          if (!field || fields.has(field[0])) ok = false;
+          else fields.set(...field);
+        }
+        // fromEntries makes each field an own property, even one named `__proto__`.
+        return ok ? Object.fromEntries(fields) : undefined;
+      }
+      case "Identifier":
+        return reference(node);
+      case "MemberExpression": {
+        let base = node;
+        while (base.type === "MemberExpression") base = base.object;
+        if (base.type === "Identifier" && base.name === "process") {
+          return refuse(
+            node,
+            "process is not allowed in a data file: it is read without running, so it cannot read the environment; write the value out, and leave secrets to drivers",
+          );
+        }
+        return refuse(
+          node,
+          "member access is not allowed in a data file: write the value out, or name the resource itself (`site`), not one of its fields",
+        );
+      }
+      case "CallExpression":
+        return refuse(
+          node,
+          node.callee.type === "MemberExpression" &&
+            node.callee.object.type === "Identifier" &&
+            imports.some((i) => i.kind === "constructors" && i.local === node.callee.object.name)
+            ? "a resource is declared at the top of a data file: give it its own `export const` and name it here"
+            : "a call is not allowed in a data file: write the value out; the reader never runs code",
+        );
+      case "NewExpression":
+        return refuse(node, "`new` is not allowed in a data file: write the value out (a date as an ISO 8601 string)");
+      case "ArrowFunctionExpression":
+      case "FunctionExpression":
+        return refuse(
+          node,
+          "a function is not allowed in a data file: a field holds a value, and code belongs in a workflow",
+        );
+      case "TSAsExpression":
+      case "TSSatisfiesExpression":
+      case "TSTypeAssertion":
+      case "TSNonNullExpression":
+        return refuse(
+          node,
+          "a type assertion is not allowed in a data file: leave it out; the constructor types the value",
+        );
+      default:
+        return refuse(node, `${describe(node)} is not allowed in a data file: ${VALUES}`);
+    }
+  }
+
+  function property(p: Node): [string, DataValue] | undefined {
+    if (p.type === "SpreadElement") {
+      return refuse(p, "a spread is not allowed in a data file: write the fields out, so the reader sees each");
+    }
+    if (p.kind !== "init" || p.method) {
+      return refuse(p, "a method or accessor is not allowed in a data file: a field holds a value");
+    }
+    if (p.computed) return refuse(p.key, "a computed key is not allowed in a data file: write the field's name");
+    const key = p.key.type === "Identifier" ? p.key.name : p.key.type === "Literal" ? String(p.key.value) : undefined;
+    if (key === undefined) return refuse(p.key, "write the field's name, or a string");
+    const v = value(p.value);
+    return v === undefined ? undefined : [key, v];
+  }
+
+  function reference(node: Node): Reference | undefined {
+    const name: string = node.name;
+    if (name === "undefined")
+      return refuse(node, "undefined is not allowed in a data file: leave the field out, or write null");
+    const imported = imports.find((i) => i.local === name);
+    if (imported?.kind === "constructors") {
+      return refuse(node, `${name} is a connector's resource constructors, not a resource: name a declared resource`);
+    }
+    if (imported || declared.has(name)) return new Reference(name);
+    if (refused.has(name)) return undefined;
+    return refuse(
+      node,
+      `${name} is not a resource this file declares or imports from a data file: write the value out, or import the resource`,
+    );
+  }
+
+  function refuse(node: { start: number; end: number }, message: string): undefined {
+    fail(node, message);
+    return undefined;
+  }
+
+  return { imports, exports, declared: [...declared], problems };
+}
+
+/** A node's kind, for a message: `a function declaration`, `an if statement`. */
+function describe(node: Node): string {
+  const words = String(node.type)
+    .replace(/^TS/, "TypeScript ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .toLowerCase();
+  return `${/^[aeiou]/.test(words) ? "an" : "a"} ${words}`;
+}