@pithy-sh/cli 0.1.0

package/src/capabilities/configImports.ts

@@ -0,0 +1,397 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * One named import found in a `pithy.config.ts`. The three commands that write that file — `add`,
+ * `remove`, and `eject` — all need the same answer about it, and each used to hand-build the exact
+ * line it expected instead. That is why `pithy add secrets` could write an import `remove` would not
+ * take out and `eject` would not find.
+ */
+export interface ConfigImport {
+  /** The statement exactly as it appears — leading indentation and trailing `;` included. */
+  statement: string;
+  /** The module specifier it imports from, unquoted. */
+  specifier: string;
+  /** Where the statement starts in the source it was found in — the anchor every edit splices at. */
+  start: number;
+  /**
+   * The span to cut to drop this one binding: the name, plus the comma joining it to its neighbor.
+   * Meaningless on its own — {@link withoutBinding} is what reads it.
+   */
+  bindingStart: number;
+  bindingEnd: number;
+  /** True when the clause binds nothing else, so dropping the name drops the whole statement. */
+  soleBinding: boolean;
+}
+
+/**
+ * A named import statement — `import { a, type B, c as d } from "…";`.
+ *
+ * Leading whitespace is tolerated: indentation is cosmetic, and a config formatted with an indented
+ * import is still one. `import type { … }` does not match — it binds no value, so it cannot be the
+ * import a registration call needs. Neither do the default and namespace forms (`import auth from …`,
+ * `import * as auth from …`): a capability factory is a named export, and an adopter who binds the
+ * name that way collides at typecheck, loudly, rather than getting the wrong thing composed.
+ *
+ * The pattern is only ever run over {@link scanConfig}'s output, never over raw file text.
+ */
+const NAMED_IMPORT = /^[ \t]*import\s*\{([^}]*)\}\s*from\s*(["'])([^"']+)\2;?/gm;
+
+/**
+ * A named re-export statement — `export { MultiplayerSession } from "…";`.
+ *
+ * The same shape one statement keyword over, and read by the same machinery below: a Durable Object's
+ * export in a Worker entry is the second half of a binding `pithy add` writes (#428), and it is found,
+ * skipped and cut by exactly the rules an import is. A second scanner would be a second idea of what a
+ * comment is.
+ *
+ * `export { a }` with no `from` is not matched: it re-exports nothing, so it cannot be the line that
+ * puts a capability's class on the module.
+ */
+const NAMED_EXPORT = /^[ \t]*export\s*\{([^}]*)\}\s*from\s*(["'])([^"']+)\2;?/gm;
+
+/**
+ * Any named export clause — `export { X };` as well as `export { X } from "…";`.
+ *
+ * The pattern above answers "which statement points at that module", which is what an edit needs. This
+ * one answers the wider question `pithy add` asks before writing anything: **is that name already on this
+ * module**, however it got there. A bare clause re-exports nothing, so it is never a line we would write,
+ * and it still makes a second `export { X } from "…"` a duplicate the build refuses.
+ */
+const EXPORT_CLAUSE = /^[ \t]*export\s*\{([^}]*)\}(?:\s*from\s*(["'])([^"']+)\2)?;?/gm;
+
+/**
+ * A value declaration exported where it is declared — `export class X {}`, `export const X = …`,
+ * `export async function* X() {}`.
+ *
+ * The third way a name lands on a module, and the one that made the claim above untrue: an adopter who
+ * wrote their own Durable Object into the entry got ours appended beside it and a duplicate export (#428).
+ *
+ * `default` is deliberately absent from the alternation. `export default class X {}` puts `default` on
+ * the module and nothing else, so wrangler's `class_name` still resolves to nothing. So are `type`,
+ * `interface` and `enum`: the first two are erased by `verbatimModuleSyntax`, and neither is a class.
+ */
+const EXPORTED_DECLARATION =
+  /^[ \t]*export\s+(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:class|function\s*\*?|const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm;
+
+/** Which statement form {@link findNamedBinding} reads. Both bind names from another module. */
+export type ClauseKind = "import" | "export";
+
+/** A source file's text with everything that only *looks* like code taken out of the way. */
+interface ScannedConfig {
+  /**
+   * The source with every comment blanked to spaces — same length, same offsets, same line breaks, so
+   * a match here indexes straight back into the original.
+   */
+  code: string;
+  /** True at each offset that sits inside a string or template literal. */
+  inLiteral: boolean[];
+}
+
+/**
+ * Blank the comments and mark the literals in a `pithy.config.ts`.
+ *
+ * The pattern above is a regex over file text, and text does not know what a comment is: a
+ * commented-out `import { auth } from "@pithy-sh/auth/src/index";` above the real binding answered
+ * the "is this already imported?" question on its behalf, so `pithy add` wrote the registration and
+ * no import. A one-character scanner is the bounded fix. **It is not a parser**, and two things it
+ * deliberately does not understand: a regex literal (telling `/…/` from division needs the grammar,
+ * so an import inside one still reads as code), and `${…}` inside a template literal (treated as more
+ * literal, which can only make it blind, never fooled). The real answer is a TypeScript parse, and
+ * TS 7 ships no `createSourceFile` to do it with — `catalog.test.ts` records the same constraint.
+ */
+function scanConfig(source: string): ScannedConfig {
+  type State = "code" | "line-comment" | "block-comment" | "string" | "template";
+  let code = "";
+  const inLiteral = new Array<boolean>(source.length).fill(false);
+  let state: State = "code";
+  let quote = "";
+  let index = 0;
+
+  while (index < source.length) {
+    const char = source[index] ?? "";
+    const next = source[index + 1] ?? "";
+
+    if (state === "code") {
+      if (char === "/" && (next === "/" || next === "*")) {
+        state = next === "/" ? "line-comment" : "block-comment";
+        code += "  ";
+        index += 2;
+        continue;
+      }
+      if (char === '"' || char === "'" || char === "`") {
+        state = char === "`" ? "template" : "string";
+        quote = char;
+      }
+      code += char;
+      index += 1;
+      continue;
+    }
+
+    if (state === "line-comment") {
+      // A newline ends it, and is kept: the pattern is line-anchored, so line breaks have to survive.
+      if (char === "\n") state = "code";
+      code += char === "\n" ? "\n" : " ";
+      index += 1;
+      continue;
+    }
+
+    if (state === "block-comment") {
+      if (char === "*" && next === "/") {
+        state = "code";
+        code += "  ";
+        index += 2;
+        continue;
+      }
+      code += char === "\n" ? "\n" : " ";
+      index += 1;
+      continue;
+    }
+
+    // A string or template literal, kept verbatim: an import's own specifier is one, so blanking it
+    // would take the answer with it. The flag is what rejects a match that *starts* inside one.
+    inLiteral[index] = true;
+    code += char;
+    if (char === "\\" && index + 1 < source.length) {
+      inLiteral[index + 1] = true;
+      code += next;
+      index += 2;
+      continue;
+    }
+    if (char === quote) state = "code";
+    index += 1;
+  }
+
+  return { code, inLiteral };
+}
+
+/**
+ * Every named import statement in a config, in source order, with the comments and literals already
+ * ruled out. The one place file text becomes imports — `findNamedImport` and `parseEjectedCapabilities`
+ * both read a config through it, so neither can quietly grow its own idea of what an import is.
+ */
+function* namedClauses(source: string, pattern: RegExp): Generator<RegExpExecArray> {
+  const { code, inLiteral } = scanConfig(source);
+  for (const match of code.matchAll(pattern)) {
+    if (inLiteral[match.index]) continue; // an import inside a string is a string
+    yield match;
+  }
+}
+
+/** The module specifier of every named import in a config, in source order. Duplicates included. */
+export function importedSpecifiers(source: string): string[] {
+  return [...namedClauses(source, NAMED_IMPORT)].map((match) => match[3] ?? "");
+}
+
+/** One comma-separated name in an import clause, and where it sits in the source. */
+interface ClauseSegment {
+  /** The segment verbatim, padding and all — `" auth "` in `{ a, auth }`. */
+  text: string;
+  /** Its absolute span in the source. The commas are the gaps between one segment and the next. */
+  start: number;
+  end: number;
+}
+
+/** Split a clause on its commas, carrying each piece's offset. `offset` is where the clause starts. */
+function clauseSegments(clause: string, offset: number): ClauseSegment[] {
+  const segments: ClauseSegment[] = [];
+  let at = offset;
+  for (const text of clause.split(",")) {
+    segments.push({ text, start: at, end: at + text.length });
+    at += text.length + 1; // the comma
+  }
+  return segments;
+}
+
+/**
+ * The named import that binds `name`, or `undefined` when nothing does.
+ *
+ * **Keyed on the binding, not the specifier.** Where a capability is imported from is the adopter's
+ * business — a deep path, an ejected copy — but the *name* is the thing a registration call resolves
+ * through, so that is what identifies the import. Where that specifier actually points is a separate
+ * question each caller answers with {@link importOrigin}.
+ */
+export function findNamedImport(source: string, name: string): ConfigImport | undefined {
+  return findNamedBinding(source, name, "import");
+}
+
+/**
+ * The named import **or** re-export that binds `name`, or `undefined` when nothing does.
+ *
+ * One search for both keywords, because the two questions are the same one: which statement puts this
+ * name on this module, and what does it point at. `pithy add` asks it of a capability's import in
+ * `pithy.config.ts` and of a Durable Object's export in the Worker entry, and a second implementation
+ * would be a second answer to "is that a comment" — the bug the scanner exists for.
+ */
+export function findNamedBinding(source: string, name: string, kind: ClauseKind): ConfigImport | undefined {
+  for (const match of namedClauses(source, kind === "import" ? NAMED_IMPORT : NAMED_EXPORT)) {
+    const clause = match[1] ?? "";
+    const segments = clauseSegments(clause, match.index + match[0].indexOf("{") + 1);
+    for (const [index, segment] of segments.entries()) {
+      const trimmed = segment.text.trim();
+      if (trimmed === "" || trimmed.startsWith("type ")) continue;
+      // `x as y` binds `y`; an alias means the adopter is using a different name, and this is not it.
+      const parts = trimmed.split(/\s+as\s+/);
+      if ((parts[1] ?? parts[0] ?? "").trim() !== name) continue;
+
+      // What an edit would cut. The first name takes the comma after it (`{ auth, b }` → `{ b }`); a
+      // later one takes the comma before it and stops at the name, so the clause keeps its padding
+      // (`{ a, auth }` → `{ a }`). A sole binding is cut whole and the statement goes with it.
+      const soleBinding = segments.every((other, at) => at === index || other.text.trim() === "");
+      const trailing = segment.text.length - segment.text.trimEnd().length;
+      const after = segments[index + 1]?.start ?? segment.end;
+      const before = segments[index - 1]?.end ?? segment.start;
+      // Sliced from the source, not taken from the match: a comment inside the statement is blank in
+      // `code`, and the statement callers edit is the one the adopter wrote.
+      return {
+        statement: source.slice(match.index, match.index + match[0].length),
+        specifier: match[3] ?? "",
+        start: match.index,
+        bindingStart: soleBinding || index === 0 ? segment.start : before,
+        bindingEnd: soleBinding ? segment.end : index === 0 ? after : segment.end - trailing,
+        soleBinding,
+      };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Every named re-export in a module — the statement verbatim, the module it points at, and where it
+ * starts — in source order.
+ *
+ * Keyed on the specifier rather than on a name, because `pithy add --eject` asks the opposite question
+ * from the rest of this file: not "which statement binds this name" but "which statements still point into
+ * the package we have just forked". A fork whose entry re-exports the package runs the package's class
+ * (#428).
+ *
+ * **`start` is not decoration.** The pattern is anchored at `^[ \t]*`, so a statement begins at the
+ * `export` keyword — and a line reading `// export { X } from "…";` contains that statement as a literal
+ * substring. An edit that found its target with `String.replace` repointed the adopter's commented-out
+ * copy and left the live export pointing at the package, which is the one outcome repointing exists to
+ * prevent. The offset is the anchor: a caller splices at it, exactly as {@link withoutBinding} does.
+ */
+export function namedReexports(source: string): { statement: string; specifier: string; start: number }[] {
+  return [...namedClauses(source, NAMED_EXPORT)].map((match) => ({
+    statement: source.slice(match.index, match.index + match[0].length),
+    specifier: match[3] ?? "",
+    start: match.index,
+  }));
+}
+
+/**
+ * Whether the module puts `name` on itself at runtime, in any spelling that survives to the bundle.
+ *
+ * The question `pithy add` asks before writing a Durable Object's export: a class already exported is a
+ * class wrangler's `class_name` resolves, whoever put it there, and appending a second statement for the
+ * same name is a duplicate export the build stops on. So all three spellings count — a re-export, a bare
+ * clause over a local declaration, and a declaration exported in place.
+ *
+ * **Runtime, not syntax.** `export type { X }` and `export { type X }` are erased by
+ * `verbatimModuleSyntax`, so they leave the module carrying nothing and are not this. Same fact
+ * `hasDefaultExport` turns on for #426, one keyword over.
+ *
+ * A scanner, not a parser — {@link scanConfig} says what that costs.
+ */
+export function exportsName(source: string, name: string): boolean {
+  for (const match of namedClauses(source, EXPORT_CLAUSE)) {
+    for (const segment of (match[1] ?? "").split(",")) {
+      const trimmed = segment.trim();
+      if (trimmed === "" || trimmed.startsWith("type ")) continue;
+      // `X as Y` puts `Y` on the module; `X` alone puts `X`.
+      const parts = trimmed.split(/\s+as\s+/);
+      if ((parts[1] ?? parts[0] ?? "").trim() === name) return true;
+    }
+  }
+  for (const match of namedClauses(source, EXPORTED_DECLARATION)) {
+    if (match[1] === name) return true;
+  }
+  return false;
+}
+
+/**
+ * The module specifier a capability's factory is imported from — the package's `src/index` barrel.
+ *
+ * Exported because it is a claim about another package's files, and `catalog.test.ts` checks it
+ * against them. `@pithy-sh/secrets` shipped with no `src/index.ts`, so `pithy add secrets` wrote a
+ * specifier nothing answered and every later `pithy` command failed loading the config. The test
+ * reads this string rather than a copy of it, so the two cannot drift apart again.
+ */
+export function capabilityImportSpecifier(pkg: string): string {
+  return `${pkg}/src/index`;
+}
+
+/** Where an import that binds a capability's name actually points. */
+export type ImportOrigin =
+  /** The capability itself: its package barrel, a deeper path into it, or the ejected local copy. */
+  | "capability"
+  /** Ours, but pointing at nothing that loads — the bare package specifier. */
+  | "unresolvable"
+  /** Someone else's module that happens to bind the same name. Not ours to rewrite or delete. */
+  | "foreign";
+
+/**
+ * Whether `specifier` is `base` itself or a path *inside* it, with no way back out.
+ *
+ * The `..` check is the point. The specifier is unresolved text, and Bun — which is what actually
+ * `import()`s a `pithy.config.ts` (`project/config.ts`) — resolves `@pithy-sh/auth/../../elsewhere`
+ * to wherever that lands. A `startsWith` prefix test called that the capability's own import, so the
+ * guard on "is this really ours?" answered yes for anything that walked straight back out of the
+ * package. Deciding on the shape of the resolved path instead means no traversal can change the
+ * answer. Exported because `eject.ts` asks it of the fork directory, and the two must agree.
+ */
+export function isInside(specifier: string, base: string): boolean {
+  if (specifier === base) return true;
+  if (!specifier.startsWith(`${base}/`)) return false;
+  const rest = specifier.slice(base.length + 1);
+  return rest !== "" && !rest.split("/").includes("..");
+}
+
+/**
+ * Where an import of the capability's name points: the capability, the capability by a specifier that
+ * resolves to nothing, or somebody else's module.
+ *
+ * Deep paths are the capability because an adopter reaching past the barrel is still importing *this
+ * capability*, and the three commands have to agree on that. They did not: `add` blessed a hand-edited
+ * deep import, `remove` left it behind while uninstalling the package, and `eject` refused to find it.
+ *
+ * The bare package is its own verdict because it is **ours and broken**: every capability package
+ * exports `./src/*` and nothing else, so `import { auth } from "@pithy-sh/auth"` throws at load
+ * (`catalog.test.ts` holds that against all fifteen). `remove` and `eject` still own it — leaving it
+ * behind while the package is uninstalled is the unloadable config `remove` exists to undo — but `add`
+ * must not read it as wiring already done.
+ */
+export function importOrigin(specifier: string, pkg: string, ejectPath: string): ImportOrigin {
+  if (specifier === pkg) return "unresolvable";
+  if (isInside(specifier, pkg) || isInside(specifier, ejectPath)) return "capability";
+  return "foreign";
+}
+
+/**
+ * Whether the import is the capability's to rewrite or take out — every origin but `foreign`.
+ *
+ * The question `remove` and `eject` ask. Whether it also *loads* is a separate one, and only `add`
+ * needs it: see {@link importOrigin}.
+ */
+export function isCapabilityImport(specifier: string, pkg: string, ejectPath: string): boolean {
+  return importOrigin(specifier, pkg, ejectPath) !== "foreign";
+}
+
+/**
+ * The source with one **binding** taken out — the whole statement only when that binding was the last
+ * name in the clause, including the newline it sat on so no blank line is left behind.
+ *
+ * The binding, not the statement, because `findNamedImport` deliberately matches one name inside a
+ * multi-name clause: deleting the statement took `import { auth, hashPassword } from …` down to
+ * nothing and left a config that no longer compiles, over bindings that were never the capability's.
+ * What remains may still import a package that is about to be uninstalled — that is a typecheck
+ * failure the adopter can read, which beats silently deleting code they wrote.
+ *
+ * A no-op if the statement is no longer where {@link ConfigImport} says it is.
+ */
+export function withoutBinding(source: string, found: ConfigImport): string {
+  const end = found.start + found.statement.length;
+  if (source.slice(found.start, end) !== found.statement) return source;
+  if (!found.soleBinding) return source.slice(0, found.bindingStart) + source.slice(found.bindingEnd);
+  return source.slice(0, found.start) + source.slice(source.startsWith("\n", end) ? end + 1 : end);
+}