prosebook 0.0.1 → 0.1.0

package/src/tools/types.ts

@@ -0,0 +1,137 @@
+/**
+ * What kind of value an expression in JSX holds, so `extract` can write `{n, number}` for a number and
+ * `{d, date, medium}` for a date instead of a bare `{x}`, which is text and prints a number unformatted.
+ *
+ * The project's own TypeScript (7 or later, through its `unstable/async` API) answers where it can; the
+ * syntax of the expression answers where it can't: a JavaScript project, a file outside any tsconfig,
+ * or no TypeScript installed. Not the `unstable/sync` API: on Linux and macOS it reads the compiler's
+ * pipes through a Node internal (`stdout._handle.fd`) that Bun doesn't have, so under Bun it throws.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import type * as TsAsync from 'typescript/unstable/async';
+import type { Checker, Type } from 'typescript/unstable/async';
+
+// oxlint-disable-next-line typescript/no-explicit-any -- a loose ESTree node: the walk reads whichever fields each node type has
+type Node = { type: string; start: number; end: number; [field: string]: any };
+
+type TsNode = { pos: number; end: number; forEachChild(visit: (child: TsNode) => unknown): unknown };
+
+/** `node` is markup or an object, which a message can't hold as text. */
+export type ValueKind = 'string' | 'number' | 'date' | 'node' | 'unknown';
+
+export interface Span {
+  start: number;
+  end: number;
+}
+
+export interface TypeOracle {
+  /** Where the answers come from, for the report. */
+  readonly source: string;
+  /** The kind of each span's expression in `file`, or nothing where the oracle can't say. */
+  kinds(file: string, spans: readonly Span[]): Promise<(ValueKind | undefined)[]>;
+  close(): Promise<void>;
+}
+
+/** The nearest `tsconfig.json` at or above the file's folder. */
+function tsconfigFor(file: string): string | undefined {
+  for (let dir = dirname(resolve(file)); ; dir = dirname(dir)) {
+    const candidate = join(dir, 'tsconfig.json');
+    if (existsSync(candidate)) return candidate;
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+// TypeFlags, as the TypeScript 7 API numbers them.
+const ANY_OR_UNKNOWN = 3;
+const NUMBER_LIKE = 67648 | 4224;
+const STRING_LIKE = 12583968;
+const UNION = 134217728;
+const OBJECT = 1048576;
+
+/**
+ * An oracle over the projects the files belong to, or nothing where TypeScript 7 isn't installed or
+ * none of the files has a tsconfig. One compiler process serves every project and is closed by `close`.
+ */
+export async function typescriptOracle(root: string, files: readonly string[]): Promise<TypeOracle | undefined> {
+  const configs = [...new Set(files.map(tsconfigFor).filter((c) => c !== undefined))];
+  if (configs.length === 0) return undefined;
+  let ts: typeof TsAsync;
+  try {
+    ts = await import('typescript/unstable/async');
+  } catch {
+    return undefined;
+  }
+  let api: InstanceType<typeof ts.API>;
+  let snapshot: Awaited<ReturnType<InstanceType<typeof ts.API>['updateSnapshot']>>;
+  try {
+    api = new ts.API({ cwd: root });
+    snapshot = await api.updateSnapshot({ openProjects: configs });
+  } catch {
+    return undefined;
+  }
+
+  const classify = async (checker: Checker, type: Type | undefined): Promise<ValueKind | undefined> => {
+    if (type === undefined) return undefined;
+    const t = (await checker.getNonNullableType(type)) ?? type;
+    if ((t.flags & ANY_OR_UNKNOWN) !== 0) return 'unknown';
+    if ((t.flags & UNION) !== 0) {
+      const members = (await (t as Type & { getTypes(): Promise<readonly Type[] | undefined> }).getTypes()) ?? [];
+      const kinds = new Set(await Promise.all(members.map((m) => classify(checker, m))));
+      if (kinds.size === 1) return [...kinds][0];
+      return kinds.has('node') ? 'node' : 'unknown';
+    }
+    if ((t.flags & NUMBER_LIKE) !== 0) return 'number';
+    if ((t.flags & STRING_LIKE) !== 0) return 'string';
+    if ((await checker.typeToString(t)) === 'Date') return 'date';
+    if ((t.flags & OBJECT) !== 0) return 'node';
+    return 'unknown';
+  };
+
+  return {
+    source: 'TypeScript',
+    async kinds(file, spans) {
+      const project = await snapshot.getDefaultProjectForFile(resolve(file));
+      const sourceFile = await project?.program.getSourceFile(resolve(file));
+      if (project === undefined || sourceFile === undefined) return spans.map(() => undefined);
+      // The smallest node covering each span is the expression itself.
+      const nodes = spans.map(({ start, end }) => {
+        let node: TsNode = sourceFile;
+        for (;;) {
+          let next: TsNode | undefined;
+          node.forEachChild((child) => {
+            if (next === undefined && child.pos <= start && child.end >= end) next = child;
+          });
+          if (next === undefined) return node;
+          node = next;
+        }
+      });
+      const types = await project.checker.getTypeAtLocation(nodes as never[]);
+      return Promise.all(types.map((type) => classify(project.checker, type)));
+    },
+    close() {
+      return api.close();
+    },
+  };
+}
+
+/** The kind an expression's syntax gives away, where it does: `items.length`, `a * b`, `new Date()`. */
+export function syntaxKind(expr: Node): ValueKind | undefined {
+  switch (expr.type) {
+    case 'Literal':
+      return typeof expr.value === 'number' ? 'number' : typeof expr.value === 'string' ? 'string' : undefined;
+    case 'TemplateLiteral':
+      return 'string';
+    case 'MemberExpression':
+      return !expr.computed && ['length', 'size', 'count'].includes(expr.property?.name as string) ? 'number' : undefined;
+    case 'BinaryExpression':
+      return ['-', '*', '/', '%', '**'].includes(expr.operator as string) ? 'number' : undefined;
+    case 'NewExpression':
+      return expr.callee?.type === 'Identifier' && expr.callee.name === 'Date' ? 'date' : undefined;
+    case 'CallExpression':
+      return expr.callee?.type === 'MemberExpression' && expr.callee.object?.name === 'Math' ? 'number' : undefined;
+    default:
+      return undefined;
+  }
+}

package/src/vite.ts

@@ -0,0 +1,252 @@
+/**
+ * `prosebook/vite`: the catalog as part of the build.
+ *
+ * Generates on start and again whenever a catalog or translation file changes, so dev never runs on
+ * stale modules and a broken entry shows in the error overlay. A build ships only the messages the
+ * code names: each locale module is swapped for its messages less the keys no module references
+ * (see `tools/scan.ts` for how a reference is found, and why it errs towards keeping).
+ *
+ * In dev an edit doesn't reload the page: each generated locale module accepts its own update and
+ * hands the new messages to every copy (`HotHook`), which re-renders in the locale and state it was in.
+ * The index accepts its own too, since its doc comments change with the source text, and reloads the
+ * page only when a locale was added or removed. The page also gets the inspector (`inspector.ts`), and
+ * the server opens the entry it asks for through Vite's own `/__open-in-editor`, so the editor is
+ * whichever Vite already launches.
+ */
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { Plugin } from 'vite';
+
+import { CatalogError, entryLocation } from './tools/catalog.ts';
+import { compileLocale, localeExpression } from './tools/compile.ts';
+import { loadConfig, type ProsebookConfig, type ResolvedConfig } from './tools/config.ts';
+import { editEntry, readEntry, type EntryEdit } from './tools/entry.ts';
+import { generate, type Generated } from './tools/generate.ts';
+import { isReferenced, keyRefs, type KeyRefs } from './tools/scan.ts';
+
+export interface ProsebookPluginOptions {
+  /** The config, inline. Without it, `prosebook.config.*` at the Vite root is read. */
+  config?: ProsebookConfig;
+  /** Ship only the messages the code names. On by default. */
+  prune?: boolean;
+  /** Keys a build always keeps, exactly or as `prefix.*`: for keys built at runtime from data. */
+  keep?: string[];
+  /** In dev, Alt-click a string on the page to open its entry in the editor. On by default. */
+  inspect?: boolean;
+}
+
+const PLACEHOLDER = /__PROSEBOOK_LOCALE_(\d+)__/g;
+const DEV_ID = '\0prosebook/dev';
+
+const hotLocale = (locale: string) => `
+if (import.meta.hot) {
+  import.meta.hot.accept((next) => {
+    const hot = globalThis.__PROSEBOOK_HOT__;
+    if (next === undefined || hot === undefined) return import.meta.hot.invalidate();
+    for (const update of hot) update(${JSON.stringify(locale)}, next.default);
+  });
+}
+`;
+
+const HOT_INDEX = `
+if (import.meta.hot) {
+  import.meta.hot.accept((next) => {
+    if (next === undefined || next.catalog.locales.join() !== catalog.locales.join()) import.meta.hot.invalidate();
+  });
+}
+`;
+
+const normalize = (path: string) => resolve(path).replaceAll('\\', '/');
+
+// Beside this module: the source when run from source, the built file in dist.
+const inspectorPath = normalize(fileURLToPath(new URL(`./inspector${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url)));
+
+export function prosebook(options: ProsebookPluginOptions = {}): Plugin {
+  let config: ResolvedConfig;
+  let generated: Generated | undefined;
+  let building = false;
+  let base = '/';
+  let refs: KeyRefs = { exact: new Set(), prefixes: new Set() };
+  const placeholders: string[] = [];
+  const shipped = { total: 0, kept: 0 };
+
+  const describe = (e: unknown) => (e instanceof CatalogError ? e.message : e instanceof Error ? (e.stack ?? e.message) : String(e));
+
+  const localeOf = (id: string): string | undefined => {
+    const path = normalize(id.split('?', 1)[0]!);
+    const out = normalize(config.out);
+    if (!path.startsWith(`${out}/`)) return undefined;
+    const name = path.slice(out.length + 1).replace(/\.[jt]s$/, '');
+    return generated?.entries.has(name) === true ? name : undefined;
+  };
+
+  const isIndex = (id: string) => {
+    const path = normalize(id.split('?', 1)[0]!);
+    const out = normalize(config.out);
+    return path === `${out}/index.ts` || path === `${out}/index.js`;
+  };
+
+  const kept = (key: string) =>
+    isReferenced(key, refs) || (options.keep ?? []).some((k) => (k.endsWith('.*') ? key.startsWith(k.slice(0, -1)) : k === key));
+
+  return {
+    name: 'prosebook',
+
+    async configResolved(resolved) {
+      building = resolved.command === 'build';
+      base = resolved.base;
+      config = await loadConfig(resolved.root, options.config);
+    },
+
+    // First in <head>, so the hot hooks are there before any copy is created.
+    transformIndexHtml() {
+      if (building) return [];
+      return [{ tag: 'script', attrs: { type: 'module', src: `${base}@id/__x00__prosebook/dev` }, injectTo: 'head-prepend' }];
+    },
+
+    resolveId(id) {
+      return id === DEV_ID ? id : null;
+    },
+
+    buildStart() {
+      try {
+        generated = generate(config);
+      } catch (e) {
+        this.error(describe(e));
+      }
+      refs = { exact: new Set(), prefixes: new Set() };
+      placeholders.length = 0;
+      shipped.total = shipped.kept = 0;
+    },
+
+    configureServer(server) {
+      const dirs = [normalize(config.catalog), normalize(config.locales)];
+      server.watcher.add(dirs);
+      const onChange = (file: string) => {
+        const path = normalize(file);
+        if (!path.endsWith('.yaml') || !dirs.some((d) => path.startsWith(`${d}/`))) return;
+        try {
+          generated = generate(config);
+          server.config.logger.info(`prosebook: regenerated from ${path.slice(normalize(config.root).length + 1)}`, { timestamp: true });
+        } catch (e) {
+          server.config.logger.error(describe(e), { timestamp: true });
+          server.ws.send({ type: 'error', err: { message: describe(e), stack: '', plugin: 'prosebook' } });
+        }
+      };
+      server.watcher.on('change', onChange);
+      server.watcher.on('add', onChange);
+      server.watcher.on('unlink', onChange);
+      if (options.inspect === false) return;
+
+      // `?key=cart.items&locale=de`: the translation's entry, or the catalog's with `catalog` or when
+      // the locale has none. Handed on to Vite's `/__open-in-editor`, which comes later in the stack.
+      server.middlewares.use((req, res, next) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (url.pathname !== `${base}__prosebook/open`) return next();
+        const key = url.searchParams.get('key') ?? '';
+        const message = generated?.catalog.messages.find((m) => m.key === key);
+        if (message === undefined) {
+          res.statusCode = 404;
+          res.end(`no entry for "${key}" in the catalog: has it been renamed since the page loaded?`);
+          return;
+        }
+        const locale = url.searchParams.has('catalog') ? undefined : (url.searchParams.get('locale') ?? undefined);
+        const { file, line, column } = entryLocation(config, message, locale);
+        req.url = `${base}__open-in-editor?file=${encodeURIComponent(`${file}:${line}:${column}`)}`;
+        next();
+      });
+
+      // The inspector's dialog: GET `?key=…` reads an entry in every locale, POST `{ key, edit, write }`
+      // applies an edit (`tools/entry.ts`). A POST writes files, so only the page itself may send one:
+      // same origin, and JSON, which a form on another site can't send without asking first.
+      server.middlewares.use((req, res, next) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (url.pathname !== `${base}__prosebook/entry`) return next();
+        const reply = (status: number, body: unknown) => {
+          res.statusCode = status;
+          res.setHeader('Content-Type', 'application/json');
+          res.end(JSON.stringify(body));
+        };
+        const fail = (e: unknown) =>
+          reply(e instanceof CatalogError ? 409 : 400, {
+            problems: e instanceof CatalogError ? e.problems : [{ severity: 'error', message: e instanceof Error ? e.message : String(e) }],
+          });
+        if (req.method === 'GET') {
+          try {
+            reply(200, readEntry(config, url.searchParams.get('key') ?? ''));
+          } catch (e) {
+            fail(e);
+          }
+          return;
+        }
+        const origin = req.headers.origin;
+        const sameOrigin = origin === undefined || new URL(origin).host === req.headers.host;
+        if (req.method !== 'POST' || !sameOrigin || req.headers['content-type']?.startsWith('application/json') !== true) {
+          reply(403, { problems: [{ severity: 'error', message: 'edits come from the page, as JSON' }] });
+          return;
+        }
+        let body = '';
+        req.setEncoding('utf8');
+        req.on('data', (chunk: string) => (body += chunk));
+        req.on('end', () => {
+          try {
+            const { key, edit, write } = JSON.parse(body) as { key: string; edit: EntryEdit; write?: boolean };
+            const result = editEntry(config, key, edit, write === true);
+            reply(result.problems.length > 0 ? 422 : 200, result);
+          } catch (e) {
+            fail(e);
+          }
+        });
+      });
+    },
+
+    load(id) {
+      if (id === DEV_ID) {
+        const hot = 'globalThis.__PROSEBOOK_HOT__ ??= new Set();\n';
+        if (options.inspect === false) return hot;
+        return `import { install } from ${JSON.stringify(inspectorPath)};\n${hot}install(${JSON.stringify({ base })});\n`;
+      }
+      if (!building || options.prune === false || generated === undefined) return null;
+      const locale = localeOf(id);
+      if (locale === undefined) return null;
+      placeholders.push(locale);
+      return `export default __PROSEBOOK_LOCALE_${placeholders.length - 1}__;\n`;
+    },
+
+    transform(code, id) {
+      if (!building) {
+        const locale = localeOf(id);
+        if (locale !== undefined) return { code: code + hotLocale(locale), map: null };
+        return isIndex(id) ? { code: code + HOT_INDEX, map: null } : null;
+      }
+      if (options.prune === false || id.includes('/node_modules/') || id.startsWith('\0')) return null;
+      if (localeOf(id) !== undefined) return null;
+      keyRefs(code, refs);
+      return null;
+    },
+
+    renderChunk(code) {
+      if (!code.includes('__PROSEBOOK_LOCALE_') || generated === undefined) return null;
+      const entries = generated.entries;
+      const replaced = code.replace(PLACEHOLDER, (_match, index: string) => {
+        const locale = placeholders[Number(index)]!;
+        const list = entries.get(locale) ?? [];
+        const compiled = compileLocale(list, kept);
+        shipped.total += list.length;
+        shipped.kept += compiled.rows.length;
+        return localeExpression(compiled);
+      });
+      return { code: replaced, map: null };
+    },
+
+    generateBundle() {
+      if (shipped.total === 0) return;
+      this.info(
+        `shipped ${shipped.kept} of ${shipped.total} messages across ${placeholders.length} locale(s); pruned ${shipped.total - shipped.kept} no code names`,
+      );
+    },
+  };
+}
+
+export default prosebook;

package/index.js

@@ -1 +0,0 @@
-console.error("Package isn't ready yet. Please wait for the next release.");