@volter/editor-react 0.5.66

package/contributions/component-contracts.service.ts

@@ -0,0 +1,18 @@
+/**
+ * The component-contract analyzer, registered for the browser (a `workspace.service`
+ * contribution): what the kit's Content index reads when it indexes a project from storage,
+ * with no session server to ask (`@volter/editor-sdk/source-analysis`). The session's server
+ * registers the same analyzer through this package's `vgai.serving` module.
+ */
+
+import { registerComponentContractAnalyzer } from '@volter/editor-sdk/source-analysis';
+import { analyzeR3fComponentContracts, builtinR3fContractsForSource } from '../src/source/oid-transform';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  registerComponentContractAnalyzer((source, path) =>
+    analyzeR3fComponentContracts(source, path, builtinR3fContractsForSource(source, path)),
+  );
+  return () => registerComponentContractAnalyzer(null);
+}

package/dist-node/component-prop-worker.mjs

@@ -0,0 +1,335 @@
+// serving/component-prop-worker.ts
+import { parentPort } from "node:worker_threads";
+
+// src/source/component-prop-types.ts
+import { statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import ts from "typescript";
+function componentParameterOf(declaration) {
+  if (ts.isFunctionDeclaration(declaration)) return declaration.parameters[0] ?? null;
+  if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+    const init = declaration.initializer;
+    if (ts.isArrowFunction(init) || ts.isFunctionExpression(init))
+      return init.parameters[0] ?? null;
+  }
+  return null;
+}
+function componentParameter(sf, componentName) {
+  let found = null;
+  const visit = (node) => {
+    if (found) return;
+    const name = ts.isFunctionDeclaration(node) ? node.name?.text : ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) ? node.name.text : void 0;
+    if (name === componentName) found = componentParameterOf(node);
+    if (!found) ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return found;
+}
+function jsxTag(sf, tagName) {
+  let found = null;
+  const visit = (node) => {
+    if (found) return;
+    if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName) && node.tagName.text === tagName) {
+      found = node;
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return found;
+}
+function componentDeclaration(identifier, checker) {
+  let symbol = checker.getSymbolAtLocation(identifier);
+  for (let hop = 0; symbol && symbol.flags & ts.SymbolFlags.Alias && hop < 8; hop += 1) {
+    const next = checker.getAliasedSymbol(symbol);
+    if (next === symbol) break;
+    symbol = next;
+  }
+  return symbol?.valueDeclaration ?? symbol?.declarations?.[0] ?? null;
+}
+function contextlessPropsType(declaration, checker) {
+  const parameter = componentParameterOf(declaration);
+  return parameter?.type ? checker.getTypeAtLocation(parameter.type) : null;
+}
+var PROJECT = "(project)";
+var NODE_MODULES_PKG_RE = /node_modules\/((?:@[^/]+\/)?[^/]+)\//;
+function packageOfFile(fileName) {
+  return NODE_MODULES_PKG_RE.exec(fileName)?.[1] ?? PROJECT;
+}
+function packageOfDeclaration(node) {
+  return packageOfFile(node.getSourceFile().fileName);
+}
+function ownProps(propsType, homePackage) {
+  const own = [];
+  for (const symbol of propsType.getProperties()) {
+    const declaration = symbol.declarations?.find(
+      (candidate) => packageOfDeclaration(candidate) === homePackage
+    );
+    if (declaration) own.push({ symbol, declaration });
+  }
+  return own;
+}
+function widgetForType(type, checker) {
+  const bare = checker.getNonNullableType(type);
+  if (bare.flags & ts.TypeFlags.BooleanLike) return { type: "boolean" };
+  if (bare.isUnion()) {
+    const members = bare.types.filter((member) => !(member.flags & ts.TypeFlags.Undefined));
+    if (members.length && members.every((member) => member.isStringLiteral())) {
+      return {
+        type: "enum",
+        options: members.map((member) => member.value)
+      };
+    }
+    if (members.length && members.every((member) => member.isNumberLiteral())) {
+      return {
+        type: "enum",
+        options: members.map((member) => member.value)
+      };
+    }
+    if (members.length === 1) return widgetForType(members[0], checker);
+    return { type: null };
+  }
+  if (bare.flags & ts.TypeFlags.StringLike) return { type: "string" };
+  if (bare.flags & ts.TypeFlags.NumberLike) return { type: "number" };
+  const sequenceLength = numericSequenceLength(bare, checker);
+  if (sequenceLength === 3) return { type: "vec3" };
+  if (sequenceLength !== null) return { type: "json" };
+  return { type: null };
+}
+function numericSequenceLength(type, checker) {
+  const isNumeric = (member) => Boolean(checker.getNonNullableType(member).flags & ts.TypeFlags.NumberLike);
+  if (checker.isTupleType(type)) {
+    const args = checker.getTypeArguments(type);
+    return args.length > 0 && args.every(isNumeric) ? args.length : null;
+  }
+  if (checker.isArrayType(type)) {
+    const element = checker.getTypeArguments(type)[0];
+    return element && isNumeric(element) ? -1 : null;
+  }
+  return null;
+}
+function literalValue(node) {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  if (ts.isNumericLiteral(node)) return Number(node.text);
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
+    const operand = literalValue(node.operand);
+    return typeof operand === "number" ? -operand : void 0;
+  }
+  if (ts.isArrayLiteralExpression(node)) {
+    const values = node.elements.map(literalValue);
+    return values.every((value) => typeof value === "number") ? values : void 0;
+  }
+  if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node))
+    return literalValue(node.expression);
+  return void 0;
+}
+function destructuring(parameter, sf) {
+  const order = [];
+  const defaults = /* @__PURE__ */ new Map();
+  if (!ts.isObjectBindingPattern(parameter.name)) return { order, defaults };
+  for (const element of parameter.name.elements) {
+    if (element.dotDotDotToken) continue;
+    const name = element.propertyName?.getText(sf) ?? element.name.getText(sf);
+    order.push(name);
+    if (element.initializer) defaults.set(name, element.initializer);
+  }
+  return { order, defaults };
+}
+function docOf(symbol, checker) {
+  const prose = ts.displayPartsToString(symbol.getDocumentationComment(checker)).replace(/\s+/g, " ").trim();
+  return prose || void 0;
+}
+function declaredSpec(symbol, declaration, checker, defaults) {
+  const name = symbol.getName();
+  const widget = widgetForType(checker.getTypeOfSymbolAtLocation(symbol, declaration), checker);
+  const doc = docOf(symbol, checker);
+  return {
+    name,
+    type: widget.type,
+    ...widget.options ? { options: widget.options } : {},
+    optional: Boolean(symbol.flags & ts.SymbolFlags.Optional) || defaults.has(name),
+    ...doc ? { doc } : {}
+  };
+}
+function withDefault(spec, initializer, sf) {
+  if (!initializer) return spec;
+  const value = literalValue(initializer);
+  return {
+    ...spec,
+    defaultText: initializer.getText(sf),
+    ...value === void 0 ? {} : { defaultValue: value }
+  };
+}
+function orderedByDestructuring(specs, order) {
+  const ordered = [];
+  for (const name of order) {
+    const spec = specs.get(name);
+    if (spec) {
+      ordered.push(spec);
+      specs.delete(name);
+    }
+  }
+  return [...ordered, ...specs.values()];
+}
+var ComponentPropResolver = class {
+  service;
+  rootFiles;
+  projectRoot;
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    const configPath = ts.findConfigFile(projectRoot, ts.sys.fileExists, "tsconfig.json");
+    const parsed = configPath ? ts.parseJsonConfigFileContent(
+      ts.readConfigFile(configPath, ts.sys.readFile).config,
+      ts.sys,
+      dirname(configPath)
+    ) : { fileNames: [], options: {} };
+    this.rootFiles = parsed.fileNames;
+    const options = {
+      ...parsed.options,
+      // Types are all this asks for; emitting or reporting errors is not its job.
+      noEmit: true,
+      skipLibCheck: true,
+      jsx: parsed.options.jsx ?? ts.JsxEmit.ReactJSX
+    };
+    const host = {
+      getScriptFileNames: () => this.rootFiles,
+      getScriptVersion: (fileName) => this.versionOf(fileName),
+      getScriptSnapshot: (fileName) => {
+        const text = ts.sys.readFile(fileName);
+        return text === void 0 ? void 0 : ts.ScriptSnapshot.fromString(text);
+      },
+      getCurrentDirectory: () => projectRoot,
+      getCompilationSettings: () => options,
+      getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+      fileExists: ts.sys.fileExists,
+      readFile: ts.sys.readFile,
+      readDirectory: ts.sys.readDirectory,
+      directoryExists: ts.sys.directoryExists,
+      getDirectories: ts.sys.getDirectories,
+      ...ts.sys.realpath ? { realpath: ts.sys.realpath } : {}
+    };
+    this.service = ts.createLanguageService(host, ts.createDocumentRegistry());
+  }
+  /** Only project sources are re-stamped: a dependency's `.d.ts` does not
+   *  change under a running editor, and stat-ing thousands of them per query
+   *  would cost more than the answer is worth. */
+  versionOf(fileName) {
+    if (fileName.includes("/node_modules/")) return "1";
+    if (!fileName.startsWith(this.projectRoot)) return "1";
+    try {
+      return String(statSync(fileName).mtimeMs);
+    } catch {
+      return "0";
+    }
+  }
+  /** Make a file known to the program even if the tsconfig did not list it. */
+  ensureRoot(file) {
+    const absolute = resolve(this.projectRoot, file);
+    if (!this.rootFiles.includes(absolute)) this.rootFiles.push(absolute);
+  }
+  /**
+   * The props `componentName` declares, as defined in `file`. Returns an empty
+   * list when the component or its props type cannot be found — never a guess.
+   */
+  propsFor(file, componentName) {
+    const context = this.context(file);
+    if (!context) return [];
+    const parameter = componentParameter(context.sf, componentName);
+    if (!parameter?.type) return [];
+    return this.specsFor(
+      context.checker.getTypeAtLocation(parameter.type),
+      packageOfDeclaration(parameter),
+      parameter,
+      context.checker
+    );
+  }
+  /**
+   * The props behind a JSX tag USED in `callsiteFile` — `<Enemy …>` in a world
+   * whose `Enemy` is imported from anywhere. The tag identifier is resolved
+   * through the checker, so aliased imports, re-exports and barrel files all
+   * land on the real definition without a module-resolution guess here.
+   */
+  propsForTag(callsiteFile, tagName) {
+    const context = this.context(callsiteFile);
+    if (!context) return [];
+    const tag = jsxTag(context.sf, tagName);
+    if (!tag) return [];
+    const declaration = componentDeclaration(tag.tagName, context.checker);
+    if (!declaration) return [];
+    const propsType = context.checker.getContextualType(tag.attributes) ?? contextlessPropsType(declaration, context.checker);
+    if (!propsType) return [];
+    const parameter = componentParameterOf(declaration);
+    return this.specsFor(propsType, packageOfDeclaration(declaration), parameter, context.checker);
+  }
+  context(file) {
+    this.ensureRoot(file);
+    const program = this.service.getProgram();
+    const sf = program?.getSourceFile(resolve(this.projectRoot, file));
+    return program && sf ? { sf, checker: program.getTypeChecker() } : null;
+  }
+  specsFor(propsType, homePackage, parameter, checker) {
+    const sf = parameter?.getSourceFile();
+    const { order, defaults } = parameter ? destructuring(parameter, parameter.getSourceFile()) : { order: [], defaults: /* @__PURE__ */ new Map() };
+    const specs = /* @__PURE__ */ new Map();
+    for (const { symbol, declaration } of ownProps(propsType, homePackage)) {
+      specs.set(symbol.getName(), declaredSpec(symbol, declaration, checker, defaults));
+    }
+    for (const name of order) {
+      if (specs.has(name)) continue;
+      const symbol = propsType.getProperty(name);
+      if (!symbol) {
+        specs.set(name, { name, type: null, optional: defaults.has(name) });
+        continue;
+      }
+      const widget = widgetForType(checker.getTypeOfSymbol(symbol), checker);
+      const doc = docOf(symbol, checker);
+      specs.set(name, {
+        name,
+        type: widget.type,
+        ...widget.options ? { options: widget.options } : {},
+        optional: Boolean(symbol.flags & ts.SymbolFlags.Optional) || defaults.has(name),
+        ...doc ? { doc } : {}
+      });
+    }
+    if (sf) {
+      for (const [name, spec] of specs) specs.set(name, withDefault(spec, defaults.get(name), sf));
+    }
+    return orderedByDestructuring(specs, order);
+  }
+  dispose() {
+    this.service.dispose();
+  }
+};
+
+// serving/component-prop-worker.ts
+var resolvers = /* @__PURE__ */ new Map();
+function resolverFor(projectRoot) {
+  const existing = resolvers.get(projectRoot);
+  if (existing) return existing;
+  const resolver = new ComponentPropResolver(projectRoot);
+  resolvers.set(projectRoot, resolver);
+  return resolver;
+}
+if (parentPort === null) {
+  throw new Error(
+    "component-prop-worker is a worker-thread entry point: it must be spawned with `new Worker(...)` and never imported on the main thread."
+  );
+}
+var port = parentPort;
+port.on("message", (message) => {
+  try {
+    const resolver = resolverFor(message.projectRoot);
+    const props = {};
+    for (const request of message.requests) {
+      props[request.key] = request.definition ? resolver.propsFor(request.file, request.tag) : resolver.propsForTag(request.file, request.tag);
+    }
+    port.postMessage({ id: message.id, props });
+  } catch (error) {
+    port.postMessage({
+      id: message.id,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+});