@specbook/vite 0.3.0 → 0.5.0

package/dist/index.js

@@ -4,7 +4,7 @@ import { mkdir as mkdir2, readFile as readFile6, writeFile as writeFile2 } from
 import { createRequire } from "module";
 import { basename, dirname, join as join5, relative as relative4, resolve as resolve2, sep as sep4 } from "path";
 
-// ../core/src/faker.ts
+// ../core/src/faker-runtime.ts
 var KEY = "__specbookFaker";
 var store = globalThis;
 var faker = new Proxy({}, {
@@ -18,10 +18,21 @@ var faker = new Proxy({}, {
     return current[key];
   }
 });
+function fakerLocaleNames(config = {}, locale) {
+  const name = locale ?? config.default ?? "en";
+  return [.../* @__PURE__ */ new Set([...config.locales?.[name] ?? [name, "en"], "base"])];
+}
+function fakerLocaleExports(config = {}) {
+  const names = /* @__PURE__ */ new Set(["en", ...fakerLocaleNames(config)]);
+  for (const name of Object.keys(config.locales ?? {}))
+    for (const n of fakerLocaleNames(config, name)) names.add(n);
+  return [...names].sort();
+}
 
 // ../core/src/template.ts
-var WHOLE = /^\s*\{\{\s*([\w.$-]+)\s*\}\}\s*$/;
-var EMBED = /\{\{\s*([\w.$-]+)\s*\}\}/g;
+var NAME = String.raw`[\w.$\[\]-]+`;
+var WHOLE = new RegExp(String.raw`^\s*\{\{\s*(${NAME})\s*\}\}\s*$`);
+var EMBED = new RegExp(String.raw`\{\{\s*(${NAME})\s*\}\}`, "g");
 var DEFERRED_NAMESPACES = ["secrets", "session"];
 var TemplateError = class extends Error {
   constructor(variable) {
@@ -36,21 +47,32 @@ function isDeferred(name) {
   return DEFERRED_NAMESPACES.includes(ns) && name.includes(".");
 }
 var isFakerName = (name) => name.startsWith("faker.");
-function fromFaker(path) {
-  let parent = faker;
-  let cur = faker;
-  for (const part of path.split(".").slice(1)) {
-    parent = cur;
-    cur = cur?.[part];
-    if (cur === void 0) return { found: false };
+var FakerPlaceholderError = class extends TemplateError {
+  constructor(variable, message) {
+    super(variable);
+    this.message = message;
+    this.name = "FakerPlaceholderError";
   }
-  return { found: true, value: typeof cur === "function" ? cur.call(parent) : cur };
+  message;
+};
+function fromFaker(path) {
+  const [, group, method, ...rest] = path.split(".");
+  const unknown = () => new FakerPlaceholderError(
+    path,
+    `Unknown faker generator "{{${path}}}": use faker.<module>.<method>`
+  );
+  if (!group || !method || rest.length > 0) throw unknown();
+  const mod = faker[group];
+  const fn = typeof mod === "object" && mod !== null ? mod[method] : void 0;
+  if (typeof fn !== "function" || method === "constructor") throw unknown();
+  return { found: true, value: fn.call(mod) };
 }
+var steps = (path) => path.replace(/\[(\d+)\]/g, ".$1").split(".");
 function lookup(scope, path) {
   if (isFakerName(path)) return fromFaker(path);
   let cur = scope;
-  for (const part of path.split(".")) {
-    if (cur !== null && typeof cur === "object" && part in cur) {
+  for (const part of steps(path)) {
+    if (cur !== null && typeof cur === "object" && Object.hasOwn(cur, part)) {
       cur = cur[part];
     } else {
       return { found: false };
@@ -58,7 +80,19 @@ function lookup(scope, path) {
   }
   return { found: true, value: cur };
 }
+function rejectFakerCall(s) {
+  if (!s.includes("faker")) return;
+  const left = /\{\{\s*(faker\.[\s\S]*?)(?:\}\}|$)/.exec(s.replace(EMBED, ""));
+  if (left) {
+    const name = left[1].trim();
+    throw new FakerPlaceholderError(
+      name,
+      `"{{${name}}}" is not a faker placeholder: placeholders take no arguments. Use faker in a request file for those.`
+    );
+  }
+}
 function renderString(s, scope) {
+  rejectFakerCall(s);
   const whole = WHOLE.exec(s);
   if (whole) {
     const name = whole[1];
@@ -727,7 +761,7 @@ async function writeEnvKey(file, key, value) {
 import { relative as relative2, sep as sep2 } from "path";
 import fg2 from "fast-glob";
 var IGNORE = ["**/node_modules/**", "**/.generated/**", "**/dist/**", "**/.git/**"];
-var NAME = /\.example\.json$/;
+var NAME2 = /\.example\.json$/;
 async function scanExamples(root, outDir, operations) {
   const examples = {};
   const assets = {};
@@ -745,7 +779,7 @@ async function scanExamples(root, outDir, operations) {
     const [svc, , id, file] = relative2(gen, abs).split(sep2);
     if (!operations.has(`${svc}/${id}`)) continue;
     add(`${svc}/${id}`, {
-      name: file.replace(NAME, ""),
+      name: file.replace(NAME2, ""),
       abs,
       source: "generated",
       dir: `${svc}/${id}@generated`
@@ -759,7 +793,7 @@ async function scanExamples(root, outDir, operations) {
     const key = `${svc}/${id}`;
     if (!svc || !id || !operations.has(key)) continue;
     add(key, {
-      name: file.replace(NAME, ""),
+      name: file.replace(NAME2, ""),
       abs,
       source: "project",
       dir: `${svc}/${id}@project`
@@ -774,7 +808,7 @@ async function scanExamples(root, outDir, operations) {
     list.sort((a, b) => order(a) - order(b) || a.name.localeCompare(b.name));
   return { examples, assets };
 }
-var order = (e) => e.source === "project" ? 0 : e.name === "default" ? 2 : e.name === "dynamic" ? 3 : 1;
+var order = (e) => e.source === "project" ? 0 : e.name === "default" ? 2 : 1;
 
 // src/files.ts
 import { existsSync as existsSync2 } from "fs";
@@ -1079,7 +1113,7 @@ async function readBody2(req) {
     req.on("error", fail);
   });
 }
-function fakerLocales(entry) {
+function fakerLocales(entry, cfg) {
   const names = /* @__PURE__ */ new Set(["en", "base"]);
   const dir = join5(dirname(entry), "locale");
   if (existsSync3(dir))
@@ -1087,8 +1121,11 @@ function fakerLocales(entry) {
       const m = /^([A-Za-z0-9_]+)\.js$/.exec(f);
       if (m) names.add(m[1]);
     }
-  return [...names].sort();
+  if (!cfg) return [...names].sort();
+  const wanted = new Set(fakerLocaleExports(cfg));
+  return [...names].filter((n) => wanted.has(n)).sort();
 }
+var USES_FAKER = /@specbook\/core\/faker|\{\{\s*faker\./;
 function slim(manifests) {
   return Object.fromEntries(
     Object.entries(manifests).map(([k, m]) => [
@@ -1187,6 +1224,14 @@ function specbook(options) {
       fakerEntry = createRequire(join5(root, "package.json")).resolve("@faker-js/faker");
     } catch {
     }
+    if (!fakerEntry) {
+      for (const f of [...files.requests, ...files.sequences]) {
+        if (USES_FAKER.test(await readFile6(join5(root, f), "utf8").catch(() => "")))
+          throw new Error(
+            `${f} uses faker, but @faker-js/faker is not installed in this project. Add it to devDependencies (npm install --save-dev @faker-js/faker).`
+          );
+      }
+    }
     const operationEntries = Object.values(manifests).flatMap((m) => {
       const mm = m;
       return mm.operations.map(
@@ -1558,7 +1603,10 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
         const r = await this.resolve("@faker-js/faker", join5(root, "package.json"), {
           skipSelf: true
         });
-        if (!r) return "export {}";
+        if (!r)
+          throw new Error(
+            "@faker-js/faker could not be resolved from this project. Add it to devDependencies."
+          );
         const pkg = JSON.stringify(r.id);
         if (id.startsWith(RESOLVED_FAKER_LOCALE))
           return `export { ${id.slice(RESOLVED_FAKER_LOCALE.length)} as default } from ${pkg}`;
@@ -1567,7 +1615,7 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
           entry = createRequire(join5(root, "package.json")).resolve("@faker-js/faker");
         } catch {
         }
-        const names = fakerLocales(entry);
+        const names = fakerLocales(entry, options.faker);
         return `export { Faker, base } from ${pkg}
 export const locales = {
 ${names.map((n) => `  ${JSON.stringify(n)}: () => import(${JSON.stringify(`${VIRTUAL_FAKER_LOCALE}${n}`)}).then((m) => m.default)`).join(",\n")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/vite",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The Specbook plugin for Vite: the registry, the docs UI hooks and the dev server credential proxy.",
   "keywords": [
     "specbook",
@@ -34,8 +34,8 @@
     }
   },
   "dependencies": {
-    "@specbook/codegen": "0.3.0",
-    "@specbook/core": "0.3.0",
+    "@specbook/codegen": "0.5.0",
+    "@specbook/core": "0.5.0",
     "fast-glob": "3.3.2",
     "marked": "^18.1.1"
   },

package/src/examples.ts

@@ -74,6 +74,5 @@ export async function scanExamples(
   return { examples, assets }
 }
 
-/** Spec and project examples first, then the generated default and dynamic ones. */
-const order = (e: ExampleEntry) =>
-  e.source === 'project' ? 0 : e.name === 'default' ? 2 : e.name === 'dynamic' ? 3 : 1
+/** Project examples first, then the spec's, then the generated default. */
+const order = (e: ExampleEntry) => (e.source === 'project' ? 0 : e.name === 'default' ? 2 : 1)

package/src/index.ts

@@ -3,7 +3,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { createRequire } from 'node:module'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
-import { environmentNames } from '@specbook/core'
+import { environmentNames, type FakerConfig, fakerLocaleExports } from '@specbook/core'
 import fg from 'fast-glob'
 import type { Plugin, ViteDevServer } from 'vite'
 import { type AddressConfig, addressesFor, NO_ADDRESSES } from './addresses'
@@ -44,6 +44,11 @@ export interface SpecbookPluginOptions {
    * reveals the rest of the API.
    */
   operations?: Set<string>
+  /**
+   * The project's `faker` config. A build ships only the locales it can reach (its chains, plus `en` and `base`);
+   * without it every locale faker has is available.
+   */
+  faker?: FakerConfig
 }
 
 const VIRTUAL = 'virtual:specbook/registry'
@@ -85,7 +90,7 @@ async function readBody(req: IncomingMessage): Promise<string> {
 }
 
 /** Locale names a faker install ships (`de`, `en_US`, ...), from its `locale/` folder next to the entry. */
-function fakerLocales(entry: string): string[] {
+function fakerLocales(entry: string, cfg?: FakerConfig): string[] {
   const names = new Set<string>(['en', 'base'])
   const dir = join(dirname(entry), 'locale')
   if (existsSync(dir))
@@ -93,9 +98,14 @@ function fakerLocales(entry: string): string[] {
       const m = /^([A-Za-z0-9_]+)\.js$/.exec(f)
       if (m) names.add(m[1] as string)
     }
-  return [...names].sort()
+  if (!cfg) return [...names].sort()
+  const wanted = new Set(fakerLocaleExports(cfg))
+  return [...names].filter((n) => wanted.has(n)).sort()
 }
 
+/** Whether a request or flow file uses faker: it imports `@specbook/core/faker` or has a `{{faker.` placeholder. */
+const USES_FAKER = /@specbook\/core\/faker|\{\{\s*faker\./
+
 /** What the sidebar and palette need; descriptions and example titles load per operation (`operationDocs`). */
 function slim(manifests: Record<string, any>) {
   return Object.fromEntries(
@@ -223,7 +233,15 @@ export function specbook(options: SpecbookPluginOptions): Plugin {
     try {
       fakerEntry = createRequire(join(root, 'package.json')).resolve('@faker-js/faker')
     } catch {
-      /* optional peer dependency */
+      /* not installed: fine unless a file uses it, checked below */
+    }
+    if (!fakerEntry) {
+      for (const f of [...files.requests, ...files.sequences]) {
+        if (USES_FAKER.test(await readFile(join(root, f), 'utf8').catch(() => '')))
+          throw new Error(
+            `${f} uses faker, but @faker-js/faker is not installed in this project. Add it to devDependencies (npm install --save-dev @faker-js/faker).`,
+          )
+      }
     }
     const operationEntries = Object.values(manifests).flatMap((m) => {
       const mm = m as { service: string; operations: { id: string }[] }
@@ -604,7 +622,10 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
         const r = await this.resolve('@faker-js/faker', join(root, 'package.json'), {
           skipSelf: true,
         })
-        if (!r) return 'export {}'
+        if (!r)
+          throw new Error(
+            '@faker-js/faker could not be resolved from this project. Add it to devDependencies.',
+          )
         const pkg = JSON.stringify(r.id)
         if (id.startsWith(RESOLVED_FAKER_LOCALE))
           return `export { ${id.slice(RESOLVED_FAKER_LOCALE.length)} as default } from ${pkg}`
@@ -617,7 +638,7 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
         } catch {
           /* fall back to the resolved id */
         }
-        const names = fakerLocales(entry)
+        const names = fakerLocales(entry, options.faker)
         return `export { Faker, base } from ${pkg}
 export const locales = {
 ${names.map((n) => `  ${JSON.stringify(n)}: () => import(${JSON.stringify(`${VIRTUAL_FAKER_LOCALE}${n}`)}).then((m) => m.default)`).join(',\n')}