@lucent-lang/lucent 0.0.4

package/runtime/test/jsi/harness.cpp

@@ -0,0 +1,181 @@
+// Test host: runs JavaScript in Hermes with Lucent modules installed, the way
+// the React Native TurboModule does on device.
+//
+//   harness <script.js>...
+//
+// Globals available to scripts:
+//   __lucent            object with every registered Lucent module
+//   print(...args)      writes a line to stdout
+//   __reference         undefined unless a reference script defines it
+//
+// The event loop runs JS tasks posted by Lucent, Hermes microtasks and
+// timers until nothing is pending.
+#include <hermes/hermes.h>
+#include <jsi/jsi.h>
+
+#include <chrono>
+#include <condition_variable>
+#include <cstdio>
+#include <deque>
+#include <fstream>
+#include <iostream>
+#include <mutex>
+#include <sstream>
+
+#include "lucent/jsi/convert.h"
+#include "lucent/jsi/host.h"
+
+namespace jsi = facebook::jsi;
+using lucent::js::Host;
+using lucent::js::JsTask;
+
+namespace {
+
+std::mutex queueMutex;
+std::condition_variable queueCv;
+std::deque<JsTask> queue;
+
+void post(JsTask task) {
+  {
+    std::lock_guard<std::mutex> g(queueMutex);
+    queue.push_back(std::move(task));
+  }
+  queueCv.notify_one();
+}
+
+struct Timer {
+  std::chrono::steady_clock::time_point at;
+  std::shared_ptr<jsi::Function> fn;
+};
+std::vector<Timer> timers;
+
+std::string readFile(const char* path) {
+  std::ifstream in(path);
+  if (!in) {
+    std::fprintf(stderr, "cannot read %s\n", path);
+    std::exit(2);
+  }
+  std::stringstream ss;
+  ss << in.rdbuf();
+  return ss.str();
+}
+
+bool runLoop(jsi::Runtime& rt, double timeoutMs) {
+  auto deadline = std::chrono::steady_clock::now() + std::chrono::milliseconds(static_cast<int64_t>(timeoutMs));
+  for (;;) {
+    rt.drainMicrotasks();
+    JsTask task;
+    {
+      std::unique_lock<std::mutex> g(queueMutex);
+      if (!queue.empty()) {
+        task = std::move(queue.front());
+        queue.pop_front();
+      }
+    }
+    if (task) {
+      task(rt);
+      continue;
+    }
+    auto now = std::chrono::steady_clock::now();
+    bool ranTimer = false;
+    for (size_t i = 0; i < timers.size(); i++) {
+      if (timers[i].at <= now) {
+        auto fn = timers[i].fn;
+        timers.erase(timers.begin() + static_cast<std::ptrdiff_t>(i));
+        fn->call(rt);
+        ranTimer = true;
+        break;
+      }
+    }
+    if (ranTimer) continue;
+    bool lucentIdle = lucent::Scheduler::instance().pendingWork() == 0;
+    if (lucentIdle && timers.empty()) {
+      // Give in-flight posts a moment to land.
+      std::unique_lock<std::mutex> g(queueMutex);
+      if (queue.empty() && !queueCv.wait_for(g, std::chrono::milliseconds(20), [] { return !queue.empty(); })) {
+        if (lucent::Scheduler::instance().pendingWork() == 0) return true;
+      }
+      continue;
+    }
+    if (now > deadline) return false;
+    std::unique_lock<std::mutex> g(queueMutex);
+    queueCv.wait_for(g, std::chrono::milliseconds(1));
+  }
+}
+
+}  // namespace
+
+/// Replaced by hosts that add globals of their own (scripts/bench.ts).
+__attribute__((weak)) void installHarnessExtras(jsi::Runtime&) {}
+
+int main(int argc, char** argv) {
+  if (argc < 2) {
+    std::fprintf(stderr, "usage: harness <script.js>...\n");
+    return 2;
+  }
+  auto config = ::hermes::vm::RuntimeConfig::Builder().withMicrotaskQueue(true).build();
+  std::unique_ptr<jsi::Runtime> runtime = facebook::hermes::makeHermesRuntime(config);
+  jsi::Runtime& rt = *runtime;
+  int status = 0;
+  {
+    std::shared_ptr<Host> host = Host::create(rt, post);
+    rt.global().setProperty(rt, "__lucent", host->modules(rt));
+    // What @lucent-lang/runtime's loader looks for outside React Native.
+    rt.global().setProperty(rt, "__lucentModules", rt.global().getProperty(rt, "__lucent"));
+    installHarnessExtras(rt);
+    // A new host for this runtime, the old one invalidated, as when an app
+    // reinstalls Lucent without a new runtime (tests of the exports JS kept).
+    rt.global().setProperty(rt, "__lucentReplaceHost",
+                            jsi::Function::createFromHostFunction(rt, jsi::PropNameID::forAscii(rt, "__lucentReplaceHost"), 0,
+                                                                  [&host](jsi::Runtime& rt, const jsi::Value&, const jsi::Value*, size_t) {
+                                                                    host->invalidate();
+                                                                    host = Host::create(rt, post);
+                                                                    return jsi::Value::undefined();
+                                                                  }));
+    rt.global().setProperty(
+        rt, "print",
+        jsi::Function::createFromHostFunction(rt, jsi::PropNameID::forAscii(rt, "print"), 1,
+                                              [](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t n) {
+                                                std::string line;
+                                                for (size_t i = 0; i < n; i++) {
+                                                  if (i) line += " ";
+                                                  line += args[i].toString(rt).utf8(rt);
+                                                }
+                                                std::printf("%s\n", line.c_str());
+                                                std::fflush(stdout);
+                                                return jsi::Value::undefined();
+                                              }));
+    rt.global().setProperty(
+        rt, "setTimeout",
+        jsi::Function::createFromHostFunction(rt, jsi::PropNameID::forAscii(rt, "setTimeout"), 2,
+                                              [](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t n) {
+                                                double ms = n > 1 && args[1].isNumber() ? args[1].getNumber() : 0;
+                                                timers.push_back(Timer{std::chrono::steady_clock::now() + std::chrono::microseconds(static_cast<int64_t>(ms * 1000)),
+                                                                       std::make_shared<jsi::Function>(args[0].getObject(rt).getFunction(rt))});
+                                                return jsi::Value::undefined();
+                                              }));
+    try {
+      for (int i = 1; i < argc; i++) {
+        rt.evaluateJavaScript(std::make_shared<jsi::StringBuffer>(readFile(argv[i])), argv[i]);
+        if (!runLoop(rt, 20000)) {
+          std::fprintf(stderr, "timed out waiting for pending work\n");
+          status = 3;
+        }
+      }
+      jsi::Value failures = rt.global().getProperty(rt, "__failures");
+      if (failures.isNumber() && failures.getNumber() > 0) status = 1;
+    } catch (const jsi::JSError& e) {
+      std::fprintf(stderr, "Uncaught JS error: %s\n%s\n", e.getMessage().c_str(), e.getStack().c_str());
+      status = 1;
+    }
+    timers.clear();
+    {
+      std::lock_guard<std::mutex> g(queueMutex);
+      queue.clear();
+    }
+    host->invalidate();
+  }
+  rt.global().setProperty(rt, "__lucentHost", jsi::Value::undefined());
+  runtime.reset();
+  return status;
+}

package/schemas/build.schema.json

@@ -0,0 +1,152 @@
+{
+  "$id": "https://lucent-lang.dev/schemas/build.schema.json",
+  "title": "lucent build --json",
+  "type": "object",
+  "required": ["ok", "upToDate", "out", "modules", "steps", "diagnostics", "notices", "next", "ms"],
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "description": "The native package was written (or was up to date); the exit code is 0 exactly then"
+    },
+    "upToDate": {
+      "type": "boolean",
+      "description": "Nothing changed since the last build, so nothing was done"
+    },
+    "out": {
+      "type": "string",
+      "description": "Absolute path of the native package"
+    },
+    "modules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "platforms"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "platforms": {
+            "type": "array",
+            "items": {
+              "enum": ["ios", "android", "shared"]
+            },
+            "description": "The platforms the module has code for, or shared"
+          }
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "label", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "enum": ["android-dependencies", "up-to-date", "sdk", "check", "generate", "package"]
+          },
+          "label": {
+            "type": "string"
+          },
+          "status": {
+            "enum": ["ok", "cached", "skipped", "failed"]
+          },
+          "detail": {
+            "type": "string"
+          },
+          "ms": {
+            "type": "number",
+            "minimum": 0
+          }
+        }
+      }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["code", "message"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^LUCENT\\d{4}$",
+            "description": "Stable code; lucent explain <code> describes it"
+          },
+          "message": {
+            "type": "string"
+          },
+          "file": {
+            "type": "string",
+            "description": "Relative to the project root"
+          },
+          "line": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "column": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "start": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Offset of the span in the file"
+          },
+          "length": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "fix": {
+            "type": "string",
+            "description": "How to fix it, in one line"
+          },
+          "docs": {
+            "type": "string",
+            "description": "Where the code is explained"
+          }
+        }
+      }
+    },
+    "notices": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["level", "text"],
+        "additionalProperties": false,
+        "properties": {
+          "level": {
+            "enum": ["ok", "warn"]
+          },
+          "text": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "next": {
+      "type": "object",
+      "required": ["rebuild", "podInstall", "reload"],
+      "additionalProperties": false,
+      "properties": {
+        "rebuild": {
+          "type": "boolean",
+          "description": "Native code changed: rebuild the app"
+        },
+        "podInstall": {
+          "type": "boolean",
+          "description": "Native files were added or removed: run pod install before the iOS build"
+        },
+        "reload": {
+          "type": "boolean",
+          "description": "Only the JavaScript proxies changed: reloading the app is enough"
+        }
+      }
+    },
+    "ms": {
+      "type": "number",
+      "minimum": 0
+    }
+  }
+}

package/schemas/check.schema.json

@@ -0,0 +1,74 @@
+{
+  "$id": "https://lucent-lang.dev/schemas/check.schema.json",
+  "title": "lucent check --json",
+  "type": "object",
+  "required": ["ok", "modules", "diagnostics", "errors", "ms"],
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "description": "No errors; the exit code is 0 exactly then"
+    },
+    "modules": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Module names, as JavaScript loads them"
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["code", "message"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^LUCENT\\d{4}$",
+            "description": "Stable code; lucent explain <code> describes it"
+          },
+          "message": {
+            "type": "string"
+          },
+          "file": {
+            "type": "string",
+            "description": "Relative to the project root"
+          },
+          "line": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "column": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "start": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Offset of the span in the file"
+          },
+          "length": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "fix": {
+            "type": "string",
+            "description": "How to fix it, in one line"
+          },
+          "docs": {
+            "type": "string",
+            "description": "Where the code is explained"
+          }
+        }
+      }
+    },
+    "errors": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "ms": {
+      "type": "number",
+      "minimum": 0
+    }
+  }
+}

package/schemas/doctor.schema.json

@@ -0,0 +1,40 @@
+{
+  "$id": "https://lucent-lang.dev/schemas/doctor.schema.json",
+  "title": "lucent doctor --json",
+  "type": "object",
+  "required": ["ok", "checks"],
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "description": "No check failed; the exit code is 0 exactly then"
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "status", "detail"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable: node, package-manager, react-native, expo, xcode, simulator, cocoapods, android-sdk, ndk, jdk, gradle-task, metro, tsconfig, sdk-cache, versions"
+          },
+          "label": {
+            "type": "string"
+          },
+          "status": {
+            "enum": ["ok", "warn", "fail", "skip"]
+          },
+          "detail": {
+            "type": "string"
+          },
+          "fix": {
+            "type": "string",
+            "description": "What to do about a failure or warning"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/lucent.schema.json

@@ -0,0 +1,43 @@
+{
+  "$id": "https://lucent-lang.dev/schemas/lucent.schema.json",
+  "title": "lucent.json",
+  "description": "What a Lucent package's platform code needs from the app that installs it. It sits next to the package's package.json. The app's build merges it with its other Lucent packages'; two packages that disagree on a value fail the build.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "ios": {
+      "type": "object",
+      "description": "What the iOS code needs.",
+      "additionalProperties": false,
+      "properties": {
+        "pods": {
+          "type": "object",
+          "description": "CocoaPods the native package depends on: pod name → version requirement, as in a Podfile (\"~> 1.0\"). Their frameworks can be imported from lucent:ios/* once installed.",
+          "additionalProperties": { "type": "string" }
+        },
+        "infoPlist": {
+          "type": "object",
+          "description": "Info.plist entries: key → string value. The Expo config plugin adds them, unless the app sets the key itself. For bare apps, lucent build names the keys the app's Info.plist lacks.",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "android": {
+      "type": "object",
+      "description": "What the Android code needs.",
+      "additionalProperties": false,
+      "properties": {
+        "dependencies": {
+          "type": "object",
+          "description": "Gradle artifacts: \"group:artifact\" → version. They become api dependencies of the native package, so lucent:android/* can import their classes.",
+          "additionalProperties": { "type": "string" }
+        },
+        "permissions": {
+          "type": "array",
+          "description": "Android permissions for the manifest, such as \"android.permission.CAMERA\". Permissions the SDK methods you call require are added without listing them here.",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/sdk-prefetch.schema.json

@@ -0,0 +1,37 @@
+{
+  "$id": "https://lucent-lang.dev/schemas/sdk-prefetch.schema.json",
+  "title": "lucent sdk prefetch --json",
+  "type": "object",
+  "required": ["ok", "modules"],
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "modules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["module", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "module": {
+            "type": "string",
+            "description": "lucent:<platform>/<module>"
+          },
+          "status": {
+            "enum": ["ok", "cached", "failed"],
+            "description": "ok: extracted now"
+          },
+          "ms": {
+            "type": "number",
+            "minimum": 0
+          },
+          "error": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/sdk-search.schema.json

@@ -0,0 +1,54 @@
+{
+  "$id": "https://lucent-lang.dev/schemas/sdk-search.schema.json",
+  "title": "lucent sdk search --json",
+  "type": "object",
+  "required": ["term", "searched", "matches"],
+  "additionalProperties": false,
+  "properties": {
+    "term": {
+      "type": "string"
+    },
+    "searched": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Modules searched: the project's imports and the SDK cache"
+    },
+    "matches": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["platform", "module", "kind", "name", "import"],
+        "additionalProperties": false,
+        "properties": {
+          "platform": {
+            "enum": ["ios", "android"]
+          },
+          "module": {
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "class",
+              "protocol",
+              "interface",
+              "enum",
+              "struct",
+              "method",
+              "property",
+              "function",
+              "constant"
+            ]
+          },
+          "name": {
+            "type": "string",
+            "description": "The type, or Type.member(params) for members"
+          },
+          "import": {
+            "type": "string",
+            "description": "The import line that brings the type in"
+          }
+        }
+      }
+    }
+  }
+}

package/ts-plugin/index.d.ts

@@ -0,0 +1,4 @@
+import type ts from "typescript";
+
+declare const init: ts.server.PluginModuleFactory;
+export = init;

package/ts-plugin/index.js

@@ -0,0 +1,99 @@
+"use strict";
+// TypeScript language-service plugin: adds Lucent diagnostics to *.lucent.ts
+// (index.js, not .cjs: tsserver resolves plugin paths without "exports").
+// files. tsserver loads plugins with require() and its own `typescript`,
+// while the compiler is an ES module that walks ASTs from its own
+// `typescript`; so the plugin imports the compiler asynchronously and hands
+// it file paths and unsaved text, never the editor's AST.
+
+const LUCENT_FILE = /\.lucent\.tsx?$/;
+const TYPESCRIPT_PASSTHROUGH = "LUCENT9001";
+
+function createPlugin(loadCompiler) {
+  return function init({ typescript: ts }) {
+    function create(info) {
+      const log = (msg) => info.project.projectService.logger.info(`[lucent] ${msg}`);
+      let compiler;
+      loadCompiler().then(
+        (c) => {
+          compiler = c;
+          info.project.refreshDiagnostics();
+        },
+        (e) => log(`could not load the Lucent compiler: ${e && e.stack ? e.stack : e}`),
+      );
+
+      // One check serves every file until any Lucent source changes.
+      let cache = { key: undefined, byFile: new Map() };
+      function lucentDiagnostics(fileName) {
+        const files = info.project.getFileNames().filter((f) => LUCENT_FILE.test(f));
+        const key = files
+          .map((f) => `${f}@${info.languageServiceHost.getScriptVersion(f)}`)
+          .join("|");
+        if (cache.key !== key) {
+          const byFile = new Map();
+          const readSource = (f) => {
+            const snap = files.includes(f)
+              ? info.languageServiceHost.getScriptSnapshot(f)
+              : undefined;
+            return snap ? snap.getText(0, snap.getLength()) : undefined;
+          };
+          for (const d of compiler.checkSources(files, readSource)) {
+            if (d.code === TYPESCRIPT_PASSTHROUGH || !d.file) continue;
+            const list = byFile.get(d.file) || [];
+            list.push(d);
+            byFile.set(d.file, list);
+          }
+          cache = { key, byFile };
+        }
+        return cache.byFile.get(fileName) || [];
+      }
+
+      const proxy = Object.create(null);
+      for (const k of Object.keys(info.languageService)) {
+        const member = info.languageService[k];
+        proxy[k] = typeof member === "function" ? member.bind(info.languageService) : member;
+      }
+      proxy.getSemanticDiagnostics = (fileName) => {
+        const own = info.languageService.getSemanticDiagnostics(fileName);
+        if (!compiler || !LUCENT_FILE.test(fileName)) return own;
+        let extra;
+        try {
+          const file = info.languageService.getProgram()?.getSourceFile(fileName);
+          extra = lucentDiagnostics(fileName).map((d) => ({
+            file,
+            start: d.start ?? 0,
+            length: d.length ?? 0,
+            messageText: [
+              `${d.code}: ${d.message}`,
+              d.fix && `fix: ${d.fix}`,
+              d.docs && `docs: ${d.docs}`,
+            ]
+              .filter(Boolean)
+              .join("\n"),
+            category: ts.DiagnosticCategory.Error,
+            code: Number(d.code.replace(/^LUCENT/, "")),
+            source: "lucent",
+          }));
+        } catch (e) {
+          log(`check failed: ${e && e.stack ? e.stack : e}`);
+          return own;
+        }
+        return [...own, ...extra];
+      };
+      return proxy;
+    }
+    return { create };
+  };
+}
+
+// Published, the compiler is bundled into dist/; in this repository (which
+// has the sources) it is the workspace package.
+const path = require("node:path");
+const fs = require("node:fs");
+const { pathToFileURL } = require("node:url");
+const compiler = fs.existsSync(path.join(__dirname, "../src"))
+  ? "@lucent-lang/compiler"
+  : pathToFileURL(path.join(__dirname, "../dist/compiler.js")).href;
+
+module.exports = createPlugin(() => import(compiler));
+module.exports.createPlugin = createPlugin;