@backmatter/core 0.0.17 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {

package/src/node/eval-model.ts

@@ -1,15 +1,18 @@
 // packages/core/src/node/eval-model.ts
-// Sandbox-eval a convention `models/{type}.ts` blob (GitHub import). Only
-// `defineModel` / `field` from @backmatter/core or @backmatter/next are in scope —
-// never import() the customer checkout.
+// Sandbox-eval convention model and object files (GitHub import). The allowed
+// surface is the same one `discoverModels` / `discoverObjects` run: `defineModel`,
+// `defineObject`, and `field` from @backmatter/core or @backmatter/next, plus
+// `import name from "../objects/<name>"`. Never import() the customer checkout.
 import { runInNewContext } from "node:vm";
 import { defineModel, type ModelDef } from "../model";
+import { defineObject, type ObjectDef } from "../object";
 import { field } from "../fields";
 
 const SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs)$/;
 const IGNORED = /(\.test\.|\.spec\.|\.d\.ts$|\.stories\.)/;
 const ALLOWED_IMPORT = /^\s*import\s+\{([^}]+)\}\s+from\s+["'](@backmatter\/core|@backmatter\/next)["']\s*;?\s*$/gm;
 const ALLOWED_NAMES = new Set(["defineModel", "field"]);
+const OBJECT_NAMES = new Set(["defineObject", "field"]);
 const FORBIDDEN = [
   { re: /\brequire\s*\(/, name: "require" },
   { re: /\bimport\s*\(/, name: "import" },
@@ -44,38 +47,61 @@ function stemOf(repoPath: string): string {
   return name.replace(SOURCE_EXT, "");
 }
 
-function stripAllowedImports(source: string): string {
+function stripAllowedImports(
+  source: string,
+  allowed: Set<string> = ALLOWED_NAMES,
+  label = "defineModel and field",
+): string {
+  ALLOWED_IMPORT.lastIndex = 0;
   const names = new Set<string>();
   const stripped = source.replace(ALLOWED_IMPORT, (_full, specifiers: string) => {
     for (const part of specifiers.split(",")) {
       const name = part.trim();
       if (!name) continue;
-      if (/\bas\b/.test(name) || !ALLOWED_NAMES.has(name)) {
-        throw new Error(`import "${name}" is not allowed; only defineModel and field`);
+      if (/\bas\b/.test(name) || !allowed.has(name)) {
+        throw new Error(`import "${name}" is not allowed; only ${label}`);
       }
       names.add(name);
     }
     return "";
   });
   if (/^\s*import\b/m.test(stripped)) {
-    throw new Error("import is not allowed except defineModel/field from @backmatter/core or @backmatter/next");
+    throw new Error(
+      `import is not allowed except ${label} from @backmatter/core or @backmatter/next`,
+    );
   }
   return stripped;
 }
 
-function assertNoForbidden(source: string): void {
+/** `import name from "../objects/<file>"` — the only local import a model may use. */
+function takeObjectImports(source: string): {
+  source: string;
+  bindings: Array<{ local: string; stem: string }>;
+} {
+  const bindings: Array<{ local: string; stem: string }> = [];
+  const re =
+    /^\s*import\s+([A-Za-z_$][\w$]*)\s+from\s+["']\.\.\/objects\/([A-Za-z][A-Za-z0-9]*)(?:\.(?:ts|tsx|js|jsx|mjs))?["']\s*;?\s*$/gm;
+  const next = source.replace(re, (_full, local: string, stem: string) => {
+    bindings.push({ local, stem });
+    return "";
+  });
+  return { source: next, bindings };
+}
+
+function assertNoForbidden(source: string, kind = "model"): void {
   for (const { re, name } of FORBIDDEN) {
-    if (re.test(source)) throw new Error(`${name} is not allowed in model files`);
+    re.lastIndex = 0;
+    if (re.test(source)) throw new Error(`${name} is not allowed in ${kind} files`);
   }
 }
 
-function rewriteDefaultExport(source: string): string {
+function rewriteDefaultExport(source: string, what = "defineModel({ ... })"): string {
   if (!/\bexport\s+default\b/.test(source)) {
-    throw new Error("must export default defineModel({ ... })");
+    throw new Error(`must export default ${what}`);
   }
   const rewritten = source.replace(/\bexport\s+default\s+/, "return ");
   if (/\bexport\b/.test(rewritten)) {
-    throw new Error("must export default defineModel({ ... })");
+    throw new Error(`must export default ${what}`);
   }
   return rewritten;
 }
@@ -85,18 +111,75 @@ function transpile(source: string): string {
   return transpiler.transformSync(source);
 }
 
+function isObjectDef(value: unknown): value is ObjectDef {
+  if (!value || typeof value !== "object") return false;
+  const object = value as Record<string, unknown>;
+  return typeof object.name === "string" && typeof object.fields === "object" && !("type" in object);
+}
+
+/**
+ * Evaluate one `objects/{name}.ts` blob. Same rule as `discoverObjects`:
+ * the file stem must equal `object.name`.
+ */
+export function evalObjectSource(source: string, stem: string): ObjectDef {
+  const body = rewriteDefaultExport(
+    stripAllowedImports(source, OBJECT_NAMES, "defineObject and field"),
+    "defineObject({ ... })",
+  );
+  assertNoForbidden(body, "object");
+  const wrapped = `(function () {\n${body}\n})()`;
+  const js = transpile(wrapped);
+  const sandbox = Object.create(null) as {
+    defineObject: typeof defineObject;
+    field: typeof field;
+  };
+  sandbox.defineObject = defineObject;
+  sandbox.field = field;
+  Object.freeze(sandbox);
+
+  let result: unknown;
+  try {
+    result = runInNewContext(js, sandbox, {
+      timeout: EVAL_TIMEOUT_MS,
+      filename: `${stem}.js`,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`object "${stem}" failed to evaluate: ${message}`);
+  }
+  if (!isObjectDef(result)) {
+    throw new Error("must export default defineObject({ ... })");
+  }
+  if (result.name !== stem) {
+    throw new Error(
+      `defines name "${result.name}" but the file is named "${stem}"; rename one so they match`,
+    );
+  }
+  return result;
+}
+
 /**
  * Evaluate one convention model file. `stem` is the file name without extension
- * and must equal `model.type`.
+ * and must equal `model.type`. `objects` supplies `import x from "../objects/<file>"`.
  */
-export function evalModelSource(source: string, stem: string): ModelDef {
-  const body = rewriteDefaultExport(stripAllowedImports(source));
+export function evalModelSource(
+  source: string,
+  stem: string,
+  objects: Readonly<Record<string, ObjectDef>> = {},
+): ModelDef {
+  const taken = takeObjectImports(source);
+  const body = rewriteDefaultExport(stripAllowedImports(taken.source));
   assertNoForbidden(body);
   const wrapped = `(function () {\n${body}\n})()`;
   const js = transpile(wrapped);
-  const sandbox = Object.create(null) as { defineModel: typeof defineModel; field: typeof field };
+  const sandbox = Object.create(null) as Record<string, unknown>;
   sandbox.defineModel = defineModel;
   sandbox.field = field;
+  for (const binding of taken.bindings) {
+    const object = objects[binding.stem];
+    if (!object) throw new Error(`import "../objects/${binding.stem}" was not found`);
+    sandbox[binding.local] = object;
+  }
   Object.freeze(sandbox);
 
   let result: unknown;
@@ -125,6 +208,11 @@ export function evalModelsFromTree(
   files: Array<{ path: string; source: string }>,
   modelsDir = "models",
 ): ModelDef[] {
+  const objects: Record<string, ObjectDef> = {};
+  for (const file of files.filter((f) => isModelSourcePath(f.path, "objects"))) {
+    const stem = stemOf(file.path);
+    objects[stem] = evalObjectSource(file.source, stem);
+  }
   const models: ModelDef[] = [];
   const types = new Set<string>();
   const sorted = files
@@ -132,7 +220,7 @@ export function evalModelsFromTree(
     .sort((a, b) => a.path.localeCompare(b.path));
   for (const file of sorted) {
     const stem = stemOf(file.path);
-    const model = evalModelSource(file.source, stem);
+    const model = evalModelSource(file.source, stem, objects);
     if (types.has(model.type)) {
       throw new Error(`duplicate model type "${model.type}" (${file.path})`);
     }

package/src/node/index.ts

@@ -18,7 +18,7 @@ export {
   toIdentifier,
 } from "./discover";
 export type { BlockFile, ModelFile } from "./discover";
-export { evalModelSource, evalModelsFromTree, isModelSourcePath } from "./eval-model";
+export { evalModelSource, evalModelsFromTree, evalObjectSource, isModelSourcePath } from "./eval-model";
 export {
   evalBlockSource,
   evalBlocksFromTree,