@unoverse-platform/studio 0.1.90 → 0.1.92

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

@@ -0,0 +1,82 @@
+/**
+ * The declarative node linter, as a LIBRARY. Rules in, findings out.
+ *
+ * It prints nothing and exits nothing, because four callers need the same rules and each
+ * presents them differently:
+ *
+ *   `unoverse lint nodes`  coloured lines in a terminal (scripts/lib/lint-nodes.mjs)
+ *   Studio                 findings beside the definition you are editing
+ *   POST /publish          a refusal, so a broken manifest never reaches the database
+ *   CI                     a non-zero exit
+ *
+ * It lived in scripts/ as a CLI, which meant the universe could not use it. Publishing
+ * without it is the gap LOCAL_STUDIO.md:246 names: "a malformed definition is one restart
+ * from a broken server", and a published row does not even need the restart.
+ *
+ * FOUR TIERS (docs/architecture/DECLARATIVE_NODES.md §6). This is tiers 2 and 3.
+ *   1  editor    $schema pointers + .vscode yaml.schemas, no tool
+ *   2  structural   every part validated against nodes/_schema/*.json
+ *   3  semantic     the cross-file rules a schema cannot express
+ *   4  dry run      `unoverse node test`, executes against testData, not here
+ */
+import { readdirSync, existsSync, statSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { problems, derivedKinds, reset, report } from "../context.mjs";
+import { loadSchemas } from "./schema.mjs";
+import { lintPackage } from "./package.mjs";
+
+/**
+ * Lint every node package under `nodesHome`.
+ *
+ * Returns findings rather than printing them, and NEVER throws for a lint failure: a
+ * missing directory or unreadable schema is itself reported, so a caller gets one shape
+ * of answer whatever went wrong.
+ */
+/**
+ * Where the node schemas are, for this run.
+ *
+ * The platform's own tree carries them at `nodes/_schema/`, and every node file points at
+ * them with `$schema:` for editor squiggles. A DEVELOPER'S WORKSPACE DOES NOT: it holds only
+ * their packages, and a linter that then warned "no schema found" on every file was
+ * validating nothing while looking busy. So the schemas travel with the linter. In dist
+ * they sit beside this file (copy-lint.mjs puts them there, and the CLI vendors that
+ * folder); from source they are the monorepo's copy, five levels up.
+ */
+function schemaHome(home) {
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const c of [join(home, "_schema"), join(here, "_schema"), resolve(here, "../../../../../apps/unoverse/nodes/_schema")])
+    if (existsSync(c)) return c;
+  return join(home, "_schema");
+}
+
+export function lintNodes(nodesHome) {
+  const home = resolve(nodesHome);
+  reset(home, schemaHome(home));
+
+  if (!existsSync(home)) {
+    report("error", home, "no nodes directory here");
+    return { problems: [...problems], derivedKinds: new Map(), nodeCount: 0, pkgCount: 0, nodesHome: home };
+  }
+
+  loadSchemas();
+
+  let nodeCount = 0,
+    pkgCount = 0;
+  for (const entry of readdirSync(home)) {
+    const dir = join(home, entry);
+    if (entry.startsWith("_") || entry.startsWith(".") || !statSync(dir).isDirectory()) continue;
+    if (!existsSync(join(dir, "nodes")) && !existsSync(join(dir, "package.yaml"))) continue; // pure code package
+    pkgCount++;
+    nodeCount += lintPackage(dir);
+  }
+
+  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, derivedKinds: new Map(derivedKinds), nodeCount, pkgCount, nodesHome: home };
+}
+
+/** 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/nodes/load.mjs

@@ -0,0 +1,126 @@
+/**
+ * Reading a node off disk: YAML parsing, $ref resolution, and where shared/ lives.
+ *
+ * $refs are resolved HERE rather than by the schema validator so a broken reference is a
+ * lint finding pointing at the file that made it, not a validation error deep in a
+ * composed document nobody wrote.
+ */
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { report, rel, refCounts } from "../context.mjs";
+
+const require_ = createRequire(import.meta.url);
+let YAML;
+try {
+  YAML = require_("yaml");
+} catch {
+  throw new Error("the node linter needs yaml (npm install -D yaml)");
+}
+
+export function readYaml(file) {
+  try {
+    const doc = YAML.parse(readFileSync(file, "utf8"));
+    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;
+  }
+}
+
+/**
+ * Resolve a `$ref` against the package's `shared/` folder.
+ *
+ * SHORT FORM, and the one to write:
+ *     url:  { $ref: endpoints#responses }
+ *     enum: { $ref: models#enum }
+ *     toolExchange:
+ *       $ref: tools          # whole file
+ *       maxTurns: 5          # local keys layer on top and win
+ *
+ * No path, because there was never a real path: shared fragments are package-scoped and
+ * the directory part was always thrown away. `../../shared/endpoints.yaml#/responses`
+ * still works, but it is arithmetic that buys nothing.
+ *
+ * A LONE $ref REPLACES. A $ref WITH SIBLINGS MERGES, local winning, which is what lets a
+ * node import a whole shared block and adjust one field.
+ */
+/**
+ * DEEP for plain objects, so overriding one field does not delete its siblings.
+ *
+ * A shallow spread made `{ $ref: x, body: { mode: 'intent' } }` REPLACE the imported body
+ * entirely: every other key — the filters, the result cap, the query itself — vanished, and
+ * the request still went out, valid and wrong. Nothing failed, because a body with fewer
+ * keys is a legal body. That is the worst shape of bug this format can produce, and the
+ * whole point of a $ref with siblings is "import a block and adjust one field".
+ *
+ * Arrays REPLACE rather than concatenating: a list is an ordered whole, and merging two
+ * would give an author no way to shorten one.
+ */
+function deepMerge(base, over) {
+  if (base === null || typeof base !== "object" || Array.isArray(base)) return over;
+  if (over === null || typeof over !== "object" || Array.isArray(over)) return over;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) out[k] = k in base ? deepMerge(base[k], v) : v;
+  return out;
+}
+
+export function resolveRefs(value, baseDir, file, seen = new Set()) {
+  if (Array.isArray(value)) return value.map((v) => resolveRefs(v, baseDir, file, seen));
+  if (!value || typeof value !== "object") return value;
+
+  const keys = Object.keys(value);
+  if (typeof value.$ref === "string") {
+    const [target, frag = ""] = value.$ref.split("#");
+    // `endpoints`, `endpoints.yaml`, or a full relative path — all the same file.
+    const stem = (target.split("/").pop() ?? "").replace(/\.ya?ml$/, "");
+    const abs = target.includes("/")
+      ? resolve(baseDir, target)
+      : [join(sharedDirFor(baseDir), `${stem}.yaml`), join(sharedDirFor(baseDir), `${stem}.yml`)].find(existsSync) ??
+        join(sharedDirFor(baseDir), `${stem}.yaml`);
+    if (seen.has(value.$ref)) {
+      report("error", file, `$ref cycle at "${value.$ref}"`);
+      return null;
+    }
+    if (!existsSync(abs)) {
+      report("error", file, `$ref "${value.$ref}" points at a file that does not exist`);
+      return null;
+    }
+    const doc = readYaml(abs);
+    if (doc === null) return null;
+    const hit = frag
+      .replace(/^\//, "")
+      .split("/")
+      .filter(Boolean)
+      .reduce((a, k) => (a == null ? a : a[k]), doc);
+    if (hit === undefined) {
+      report("error", file, `$ref "${value.$ref}" resolved to nothing. Check the fragment path`);
+      return null;
+    }
+    // Count distinct CONSUMERS, not $ref sites: one config.yaml referencing a
+    // fragment twice (enum + enumNames) is still a single consumer.
+    if (!refCounts.has(abs)) refCounts.set(abs, new Set());
+    refCounts.get(abs).add(file);
+    // Recurse with the ORIGINAL baseDir, not the fragment's own directory. A $ref stem is
+    // package-scoped (compose.ts resolves every one against pkg.shared), so re-basing onto
+    // shared/ made a nested ref look for <pkg>/../shared and report a missing file. It
+    // only stayed hidden because no shared fragment had contained a $ref before.
+    const imported = resolveRefs(hit, baseDir, file, new Set([...seen, value.$ref]));
+    if (keys.length === 1) return imported;
+    const local = Object.fromEntries(
+      keys.filter((k) => k !== "$ref").map((k) => [k, resolveRefs(value[k], baseDir, file, seen)]),
+    );
+    if (imported === null || typeof imported !== "object" || Array.isArray(imported)) {
+      report("error", file, `$ref "${value.$ref}" is not an object, so it cannot be merged with sibling keys`);
+      return local;
+    }
+    return deepMerge(imported, local);
+  }
+  return Object.fromEntries(keys.map((k) => [k, resolveRefs(value[k], baseDir, file, seen)]));
+}
+/** A node dir is <pkg>/nodes/<Node>, so shared/ is two levels up. */
+export function sharedDirFor(nodeDir) {
+  return join(nodeDir, "..", "..", "shared");
+}
+