@unoverse-platform/studio 0.1.97 → 0.1.99

package/vendor/base/src/lint/objects/index.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Types for the objects and pipelines linter, which is plain JavaScript.
+ *
+ * Same arrangement as ../design/index.d.mts and ../nodes/index.d.mts: the linter stays
+ * .mjs so the CLIs run it under bare node, and TypeScript consumers (the publish gate,
+ * Studio) get a shape rather than `any`.
+ */
+
+export interface Finding {
+  level: "error" | "warn" | "hint";
+  file: string;
+  line?: number;
+  msg: string;
+}
+
+export interface ObjectsResult {
+  problems: Finding[];
+  objectCount: number;
+  pipelineCount: number;
+  designRoot: string;
+}
+
+export interface LintObjectsOptions {
+  /** Absolute path -> text that stands in for what is on disk (Studio's unsaved editor). */
+  overlay?: Record<string, string>;
+}
+
+/** Lint every object and pipeline folder under `designRoot`, every tier. Prints nothing, throws nothing for a lint failure. */
+export function lintObjects(designRoot: string, options?: LintObjectsOptions): ObjectsResult;
+
+/** True when anything would fail a build. */
+export function hasErrors(result: ObjectsResult): boolean;

package/vendor/base/src/lint/objects/index.mjs

@@ -0,0 +1,324 @@
+/**
+ * The objects and pipelines linter, as a LIBRARY. Rules in, findings out.
+ *
+ * A THIRD SIBLING of ../design/ and ../nodes/ (docs/unoverse/data/objects/README.md 9a,
+ * 2026-09-10). An object and a pipeline are folders in the node grammar, so they are linted
+ * the way nodes are: tier 2, every file against a schema (packages/docs/schemas/objects and
+ * /pipelines); tier 3, the rules a schema cannot say (rules.mjs, the SAME functions the
+ * loaders refuse a file with). Not the design linter's way: there is no primitive tree here.
+ *
+ * Callers: `unoverse lint` and `POST /publish` through items/publish lintForPublish; Studio's
+ * save and draft lint; CI. Prints nothing, exits nothing, throws nothing for a lint failure.
+ *
+ * `options.overlay` maps an absolute path to text that STANDS IN for what is on disk, so
+ * Studio's editor lints what the developer has typed before it is saved, through these
+ * rules and no others.
+ */
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join, resolve, dirname, relative, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { problems, reset, report, state } from "../context.mjs";
+import { validateAgainst, Validator } from "../nodes/schema.mjs";
+import {
+  envelopeFindings, propsFindings, fromFindings, serviceFindings, makeFindings, rowKeyFindings, objectTestFindings,
+  pipelineFindings, pipelineFolderFindings,
+} from "./rules.mjs";
+
+const require_ = createRequire(import.meta.url);
+let YAML;
+try {
+  YAML = require_("yaml");
+} catch {
+  throw new Error("the objects linter needs yaml (npm install -D yaml)");
+}
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const SCHEMA_ID = {
+  object: "https://docs.unoverse.ai/schemas/objects/object.schema.json",
+  props: "https://docs.unoverse.ai/schemas/objects/props.schema.json",
+  service: "https://docs.unoverse.ai/schemas/objects/service.schema.json",
+  make: "https://docs.unoverse.ai/schemas/objects/make.schema.json",
+  objectTest: "https://docs.unoverse.ai/schemas/objects/test.schema.json",
+  dataset: "https://docs.unoverse.ai/schemas/objects/dataset.schema.json",
+  pipeline: "https://docs.unoverse.ai/schemas/pipelines/pipeline.schema.json",
+  config: "https://docs.unoverse.ai/schemas/pipelines/config.schema.json",
+  interface: "https://docs.unoverse.ai/schemas/pipelines/interface.schema.json",
+  pipelineTest: "https://docs.unoverse.ai/schemas/pipelines/test.schema.json",
+};
+
+/**
+ * Where the schemas are, for this run. Their home is packages/docs/schemas/{objects,
+ * pipelines,nodes}, served by the docs site; in dist they sit beside this file
+ * (copy-lint.mjs puts them there, the CLI vendors that folder). The node schemas ride too:
+ * a pipeline's config, interface and test files ARE a node's, and the object schemas
+ * reach into _defs for an expression.
+ */
+function schemaDirs() {
+  const out = [];
+  for (const kind of ["objects", "pipelines", "nodes"]) {
+    for (const c of [join(HERE, "_schema", kind), resolve(HERE, `../../../../docs/schemas/${kind}`), join(HERE, "../nodes/_schema")]) {
+      if (existsSync(c)) {
+        out.push(c);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+function loadAllSchemas() {
+  for (const dir of schemaDirs())
+    for (const f of readdirSync(dir).filter((f) => f.endsWith(".json")))
+      try {
+        const s = JSON.parse(readFileSync(join(dir, f), "utf8"));
+        if (s.$id && !state.schemas[s.$id]) state.schemas[s.$id] = s;
+      } catch (e) {
+        report("error", join(dir, f), `is not valid JSON: ${e.message}`);
+      }
+}
+
+const isDir = (p) => existsSync(p) && statSync(p).isDirectory();
+const isRecord = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+
+/**
+ * Lint every object and pipeline folder under `designRoot`: the marketplace tier and every
+ * org's. Returns `{ problems, objectCount, pipelineCount, designRoot }`.
+ */
+export function lintObjects(designRoot, options = {}) {
+  const ROOT = resolve(designRoot);
+  reset(ROOT, "");
+  const overlay = {};
+  for (const [k, v] of Object.entries(options.overlay ?? {})) overlay[resolve(k)] = v;
+  const readText = (f) => (overlay[resolve(f)] === undefined ? readFileSync(f, "utf8") : overlay[resolve(f)]);
+  const rel = (f) => relative(process.cwd(), f).startsWith("..") ? f : relative(process.cwd(), f);
+
+  const readYaml = (file) => {
+    if (!existsSync(file) && overlay[resolve(file)] === undefined) return null;
+    try {
+      const doc = YAML.parse(readText(file));
+      if (doc && typeof doc === "object") delete doc.$schema;
+      return doc ?? {};
+    } catch (e) {
+      report("error", rel(file), `is not valid YAML: ${e.message.split("\n")[0]}`);
+      return null;
+    }
+  };
+
+  if (!isDir(ROOT)) {
+    report("error", ROOT, "no design/ folder here");
+    return { problems: [...problems], objectCount: 0, pipelineCount: 0, designRoot: ROOT };
+  }
+  if (!Validator) {
+    report("error", ROOT, "the objects linter needs @cfworker/json-schema");
+    return { problems: [...problems], objectCount: 0, pipelineCount: 0, designRoot: ROOT };
+  }
+  loadAllSchemas();
+
+  // ── the tiers: the marketplace, then every org folder ──
+  const marketplace = join(ROOT, "marketplace");
+  const tiers = [];
+  if (isDir(marketplace)) tiers.push({ org: undefined, dir: marketplace });
+  for (const e of readdirSync(ROOT)) {
+    if (e.startsWith(".") || e === "marketplace" || e === "_schema") continue;
+    const d = join(ROOT, e);
+    if (isDir(d)) tiers.push({ org: e, dir: d });
+  }
+
+  /**
+   * WHAT A TIER CAN SEE. A node named by a call or a collect step must be one the org
+   * has: the marketplace's, or its own under design/<org>/nodes/. A developer's workspace
+   * carries no marketplace on disk (it is installed, never baked), so when the marketplace
+   * tier is absent the existence rules step back to a hint rather than reporting every
+   * shipped node as unknown: a rule that cannot see must not read that as clean, nor as
+   * wrong.
+   */
+  const nodeTypesIn = (tierDir) => {
+    const out = new Set();
+    const home = join(tierDir, "nodes");
+    if (!isDir(home)) return out;
+    for (const pkg of readdirSync(home)) {
+      const nodes = join(home, pkg, "nodes");
+      if (!isDir(nodes)) continue;
+      for (const n of readdirSync(nodes)) {
+        const nodeYaml = join(nodes, n, "node.yaml");
+        if (!existsSync(nodeYaml)) continue;
+        const m = /^type:\s*([A-Za-z0-9_]+)/m.exec(readFileSync(nodeYaml, "utf8"));
+        out.add(m ? m[1] : n);
+      }
+    }
+    return out;
+  };
+  const foldersIn = (tierDir, kind) => {
+    const home = join(tierDir, kind);
+    if (!isDir(home)) return [];
+    return readdirSync(home).filter((e) => !e.startsWith(".") && !e.startsWith("_") && isDir(join(home, e)));
+  };
+  const marketplaceSeen = tiers.some((t) => t.org === undefined);
+  const marketplaceNodes = marketplaceSeen ? nodeTypesIn(marketplace) : null;
+  const marketplaceObjects = new Set(marketplaceSeen ? foldersIn(marketplace, "objects") : []);
+  const marketplacePipelines = new Set(marketplaceSeen ? foldersIn(marketplace, "pipelines") : []);
+  const visible = (tier, kind) => {
+    const own = new Set(foldersIn(tier.dir, kind));
+    if (!marketplaceSeen) return null;
+    for (const n of kind === "objects" ? marketplaceObjects : marketplacePipelines) own.add(n);
+    return own;
+  };
+  const visibleNodes = (tier) => {
+    if (!marketplaceSeen) return null;
+    const s = new Set(marketplaceNodes);
+    if (tier.org) for (const n of nodeTypesIn(tier.dir)) s.add(n);
+    return s;
+  };
+
+  // ── objects ──
+  // An object's folder, read raw: envelope, own props, service, test. The lint composes
+  // `extends` itself (across tiers, the org's first) so the row keys can be checked against
+  // every field the object carries, the base's included.
+  const objectFolder = (dir, name) => {
+    const envFile = [`${name}.yaml`, `${name}.json`].map((f) => join(dir, f)).find((f) => existsSync(f) || overlay[resolve(f)] !== undefined);
+    if (!envFile) return null;
+    const envelope = readYaml(envFile);
+    let props = isRecord(envelope) ? envelope.props : undefined;
+    let propsFile = envFile;
+    if (isRecord(props) && typeof props.$include === "string") {
+      propsFile = join(dir, `${props.$include}.yaml`);
+      props = readYaml(propsFile);
+      if (props === null && !existsSync(propsFile)) report("error", rel(envFile), `object ${name}: props $include "${envelope.props.$include}" resolves to no file in the folder`);
+    }
+    const servicePath = join(dir, "api", "service.yaml");
+    const service = existsSync(servicePath) || overlay[resolve(servicePath)] !== undefined ? readYaml(servicePath) : undefined;
+    // THE PRIVATE MAKE FUNCTION (objects README 4b, 2026-09-14): api/make.yaml, one function, `make`.
+    const makePath = join(dir, "api", "make.yaml");
+    const make = existsSync(makePath) || overlay[resolve(makePath)] !== undefined ? readYaml(makePath) : undefined;
+    const testPath = join(dir, "test.yaml");
+    const test = existsSync(testPath) || overlay[resolve(testPath)] !== undefined ? readYaml(testPath) : undefined;
+    // THE TABLE IT OWNS (objects README 4f, dataset.md): dataset.yaml, never table.yaml, which
+    // would be the envelope of an object NAMED table.
+    const datasetPath = join(dir, "dataset.yaml");
+    const dataset = datasetPath !== envFile && (existsSync(datasetPath) || overlay[resolve(datasetPath)] !== undefined) ? readYaml(datasetPath) : undefined;
+    return { dir, name, envFile, envelope, props, propsFile, service, servicePath, make, makePath, test, testPath, dataset, datasetPath };
+  };
+  const objectIndex = new Map(); // `${org ?? ""}/${name}` -> folder
+  const datasetTables = new Map(); // the table a dataset would own -> the object that owns it
+  for (const tier of tiers) for (const name of foldersIn(tier.dir, "objects")) {
+    const f = objectFolder(join(tier.dir, "objects", name), name);
+    if (f) objectIndex.set(`${tier.org ?? ""}/${name}`, { ...f, org: tier.org });
+  }
+  const findObject = (name, org) => objectIndex.get(`${org ?? ""}/${name}`) ?? objectIndex.get(`/${name}`) ?? null;
+  /** The composed props of an object, or null on a cycle or a missing base (reported by the caller). */
+  const composedProps = (folder, chain = []) => {
+    const own = isRecord(folder.props) ? folder.props : {};
+    const base = isRecord(folder.envelope) ? folder.envelope.extends : undefined;
+    if (typeof base !== "string") return { ...own };
+    if (chain.includes(folder.name) || chain.includes(base)) return null;
+    const parent = findObject(base, folder.org);
+    if (!parent) return null;
+    const pp = composedProps(parent, [...chain, folder.name]);
+    return pp ? { ...pp, ...own } : null;
+  };
+
+  /** An object's own functions by name: api/service.yaml's, and `make` from api/make.yaml. */
+  const ownFunctions = (folder) => ({ ...(isRecord(folder.service) ? folder.service : {}), ...(folder.make != null ? { make: folder.make } : {}) });
+  /** The functions an object can call: its own over every base's (objects README 5, "Inheritance is whole"). */
+  const composedService = (folder, chain = []) => {
+    const own = ownFunctions(folder);
+    const base = isRecord(folder.envelope) ? folder.envelope.extends : undefined;
+    if (typeof base !== "string" || chain.includes(folder.name) || chain.includes(base)) return { ...own };
+    const parent = findObject(base, folder.org);
+    return parent ? { ...composedService(parent, [...chain, folder.name]), ...own } : { ...own };
+  };
+
+  let objectCount = 0;
+  for (const [, f] of objectIndex) {
+    objectCount++;
+    const tier = { org: f.org, dir: f.org ? join(ROOT, f.org) : marketplace };
+    const at = (file) => rel(join(f.dir, file));
+    if (f.envelope === null) continue;
+    validateAgainst(SCHEMA_ID.object, f.envelope, rel(f.envFile), `object ${f.name}: the envelope`);
+    if (f.props != null && f.propsFile !== f.envFile) validateAgainst(SCHEMA_ID.props, f.props, rel(f.propsFile), `object ${f.name}: the props`);
+    if (f.service != null) validateAgainst(SCHEMA_ID.service, f.service, rel(f.servicePath), `object ${f.name}: the functions`);
+    if (f.make != null) validateAgainst(SCHEMA_ID.make, f.make, rel(f.makePath), `object ${f.name}: the make function`);
+    if (f.test != null) validateAgainst(SCHEMA_ID.objectTest, f.test, rel(f.testPath), `object ${f.name}: the test`);
+    if (f.dataset != null) validateAgainst(SCHEMA_ID.dataset, f.dataset, rel(f.datasetPath), `object ${f.name}: the table it owns`);
+    // TWO OBJECTS MAY NOT ARRIVE AT ONE TABLE. A dataset's table is named from its object and its
+    // org, squeezed to letters, digits and underscores, so "my-thing" and "my_thing" would be one
+    // table and the second object would quietly write into the first's rows.
+    if (f.dataset != null) {
+      const table = `dataset_${[f.org, f.name].filter(Boolean).map((p) => String(p).replace(/[^a-z0-9]+/gi, "_").toLowerCase()).join("_")}`;
+      const taken = datasetTables.get(table);
+      if (taken && taken !== `${f.org ?? ""}/${f.name}`) report("error", rel(f.datasetPath), `object ${f.name}: its table would be "${table}", which "${taken}" already owns. Two objects cannot share a table: rename one.`);
+      else datasetTables.set(table, `${f.org ?? ""}/${f.name}`);
+    }
+
+    const say = (list) => {
+      for (const x of list) report(x.level ?? "error", at(x.file), x.msg);
+    };
+    say(envelopeFindings(f.name, f.envelope, basename(f.envFile)));
+
+    // extends: resolves, no cycle, across the tiers the org can see.
+    let parentProps = null;
+    const base = isRecord(f.envelope) ? f.envelope.extends : undefined;
+    if (typeof base === "string") {
+      const parent = findObject(base, f.org);
+      if (!parent) report("error", rel(f.envFile), `object ${f.name}: extends "${base}", which no tier holds`);
+      else {
+        parentProps = composedProps(parent, [f.name]);
+        if (parentProps === null) report("error", rel(f.envFile), `object ${f.name}: extends cycle through ${base}`);
+      }
+    }
+    say(propsFindings(f.name, f.props, parentProps, base, basename(f.propsFile)));
+    if (isRecord(f.props)) for (const [k, p] of Object.entries(f.props)) if (isRecord(p) && p.from != null) say(fromFindings(f.name, k, p.from, composedService(f), basename(f.propsFile)));
+    say(serviceFindings(f.name, f.service, visibleNodes(tier)));
+    say(makeFindings(f.name, f.make, f.service, visibleNodes(tier)));
+    if (!marketplaceSeen && isRecord(f.service)) report("hint", rel(f.servicePath), `object ${f.name}: the marketplace is not on disk here, so the nodes its calls name were not checked`);
+    const all = composedProps(f) ?? (isRecord(f.props) ? f.props : {});
+    say(rowKeyFindings(f.name, f.envelope, all, basename(f.envFile)));
+    say(objectTestFindings(f.name, f.test, ownFunctions(f)));
+    // An org may never take a marketplace name: a bare object_type must stay unambiguous.
+    if (f.org && marketplaceObjects.has(f.name)) report("error", rel(f.envFile), `object ${f.name}: an org's object may not take a marketplace object's name; the row's object_type would be ambiguous. Rename it, or extend ${f.name} under a name of its own`);
+  }
+
+  // ── pipelines ──
+  let pipelineCount = 0;
+  for (const tier of tiers) for (const name of foldersIn(tier.dir, "pipelines")) {
+    pipelineCount++;
+    const dir = join(tier.dir, "pipelines", name);
+    const at = (file) => rel(join(dir, file));
+    const filePath = join(dir, "pipeline.yaml");
+    const file = readYaml(filePath);
+    if (file === null) {
+      if (!existsSync(filePath)) report("error", at("pipeline.yaml"), `pipeline ${name}: the folder has no pipeline.yaml`);
+      continue;
+    }
+    const configPath = join(dir, "config.yaml");
+    const config = existsSync(configPath) || overlay[resolve(configPath)] !== undefined ? readYaml(configPath) : undefined;
+    const ifacePath = join(dir, "interface.yaml");
+    const iface = existsSync(ifacePath) || overlay[resolve(ifacePath)] !== undefined ? readYaml(ifacePath) : undefined;
+    const testPath = join(dir, "test.yaml");
+    const test = existsSync(testPath) || overlay[resolve(testPath)] !== undefined ? readYaml(testPath) : undefined;
+
+    validateAgainst(SCHEMA_ID.pipeline, file, at("pipeline.yaml"), `pipeline ${name}`);
+    if (config != null) validateAgainst(SCHEMA_ID.config, config, at("config.yaml"), `pipeline ${name}: the Import form`);
+    if (iface != null) validateAgainst(SCHEMA_ID.interface, iface, at("interface.yaml"), `pipeline ${name}: the interface`);
+    if (test != null) validateAgainst(SCHEMA_ID.pipelineTest, test, at("test.yaml"), `pipeline ${name}: the test`);
+
+    const say = (list) => {
+      for (const x of list) report(x.level ?? "error", at(x.file), x.msg);
+    };
+    say(pipelineFindings(name, file));
+    say(pipelineFolderFindings(name, { file, config: config ?? null, test }, { nodeTypes: visibleNodes(tier), objectNames: visible(tier, "objects") }));
+    if (!marketplaceSeen) report("hint", at("pipeline.yaml"), `pipeline ${name}: the marketplace is not on disk here, so the nodes its steps name and the objects it makes were not checked`);
+    if (tier.org && marketplacePipelines.has(name)) report("error", at("pipeline.yaml"), `pipeline ${name}: an org's pipeline may not take a marketplace pipeline's name; the connector's name would be ambiguous`);
+  }
+
+  const rank = { error: 0, warn: 1, hint: 2 };
+  const sorted = [...problems].sort((a, b) => rank[a.level] - rank[b.level] || a.file.localeCompare(b.file));
+  return { problems: sorted, objectCount, pipelineCount, designRoot: ROOT };
+}
+
+/** True when anything would fail a build. Warnings and hints inform, errors stop. */
+export function hasErrors(result) {
+  return result.problems.some((p) => p.level === "error");
+}

package/vendor/base/src/lint/objects/rules.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Types for rules.mjs: the pure rules an object or a pipeline file answers to, shared by
+ * the linter and the loaders in definitions/registry (one spelling of every rule).
+ */
+
+export interface RuleFinding {
+  /** The folder-relative file the mistake is in (`deal.yaml`, `props.yaml`, `api/service.yaml`, `pipeline.yaml`). */
+  file: string;
+  msg: string;
+  /** Absent means error. */
+  level?: "error" | "warn" | "hint";
+  /** A loader cannot read past this one: the grammar itself. The rest is the linter's to report. */
+  refuses?: boolean;
+}
+
+export const KEBAB: RegExp;
+export const ELEMENTS: Set<string>;
+export const FACE_KEYS: string[];
+export const PROP_KEYS: Set<string>;
+export const LIMIT_KEYS: string[];
+
+export function envelopeFindings(name: string, envelope: unknown, file?: string): RuleFinding[];
+export function propsFindings(name: string, ownProps: unknown, parentProps?: Record<string, unknown> | null, base?: string | null, file?: string): RuleFinding[];
+export function fromFindings(name: string, prop: string, from: unknown, service: unknown, file?: string): RuleFinding[];
+export function functionFindings(name: string, fn: string, raw: unknown, file?: string): RuleFinding[];
+export function serviceFindings(name: string, service: unknown, nodeTypes?: Set<string> | null, file?: string): RuleFinding[];
+/** api/make.yaml: the private make function, one function with no name inside it; api/service.yaml never declares it. */
+export function makeFindings(name: string, make: unknown, service: unknown, nodeTypes?: Set<string> | null, file?: string): RuleFinding[];
+export function rowKeyFindings(name: string, envelope: unknown, props: unknown, file?: string): RuleFinding[];
+export function objectTestFindings(name: string, test: unknown, service: unknown, file?: string): RuleFinding[];
+/** The words a `make` block says about its read; every other key is an object that read makes. */
+export const PIPELINE_READ_KEYS: Set<string>;
+export function pipelineFindings(name: string, file: unknown, fileName?: string): RuleFinding[];
+export function collectRefs(value: unknown): Set<string>;
+export function configRefs(value: unknown): Set<string>;
+export function pipelineFolderFindings(
+  name: string,
+  parts: { file: unknown; config: unknown; test: unknown },
+  seen?: { nodeTypes?: Set<string> | null; objectNames?: Set<string> | null },
+): RuleFinding[];
+/** The first error's message; null when none. */
+export function firstError(findings: RuleFinding[]): string | null;
+/** The first finding a loader cannot read past; null when the file loads. */
+export function firstRefusal(findings: RuleFinding[]): string | null;