@lucent-lang/lucent 0.0.4 → 0.1.1

package/README.md

@@ -0,0 +1,97 @@
+# @lucent-lang/lucent
+
+> [!WARNING]
+> **Experimental: not for production.** APIs and the language subset change
+> without a migration path.
+
+Write React Native native modules in TypeScript. Lucent compiles a checked
+subset to C++ and calls it through JSI: no Swift or Kotlin to write, and no
+JavaScript engine in native code.
+
+```ts
+// src/geo.lucent.ts
+export type Point = { x: number; y: number };
+
+export function squaredDistance(a: Point, b: Point): number {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+  return dx * dx + dy * dy;
+}
+```
+
+```ts
+import { squaredDistance } from "./src/geo.lucent";
+squaredDistance({ x: 0, y: 0 }, { x: 3, y: 4 }); // 25, computed in C++
+```
+
+A module also calls the iOS and Android SDKs directly, typed from your Xcode
+and Android SDK. One module holds both platforms:
+
+```ts
+// src/clipboard.lucent.ts
+import { PLATFORM } from "lucent:platform";
+import { UIPasteboard } from "lucent:ios/UIKit";
+import { ClipboardManager, ClipDescription } from "lucent:android/android.content";
+import { appContext } from "lucent:android";
+import { main } from "lucent:thread";
+
+export async function hasStringAsync(): Promise<boolean> {
+  if (PLATFORM === "ios") {
+    return UIPasteboard.general.hasStrings;
+  } else {
+    return main(
+      () =>
+        appContext()
+          .getSystemService(ClipboardManager)
+          ?.getPrimaryClipDescription()
+          ?.hasMimeType(ClipDescription.MIMETYPE_TEXT_PLAIN) ?? false,
+    );
+  }
+}
+```
+
+## Install
+
+You need React Native 0.88 or later, or Expo SDK 58 in a development build,
+and Node 22.12 or later.
+
+```sh
+npm i -D @lucent-lang/lucent
+npx lucent init
+```
+
+`lucent init` sets the app up (the Metro config, the Expo plugin or the
+Gradle task, `tsconfig.json`, `.gitignore`, a first module), showing each
+change as a diff and asking before applying it. Lucent adds native code, so
+an Expo app runs as a development build (`npx expo run:ios`,
+`npx expo run:android`), not in Expo Go.
+
+`npx lucent doctor` checks your machine: Xcode, the Android SDK and NDK, the
+JDK, and the app's setup.
+
+## What's in the package
+
+- The `lucent` CLI: `init`, `build`, `check`, `dev`, `doctor`, `sdk` and
+  more (`npx lucent --help`).
+- The compiler, which Metro runs on `*.lucent.ts` files through
+  `@lucent-lang/lucent/metro`.
+- The Expo config plugin (`@lucent-lang/lucent` in `app.json`'s plugins).
+- An editor plugin that shows Lucent's diagnostics in TypeScript-aware
+  editors (`@lucent-lang/lucent/ts-plugin`).
+- `@lucent-lang/lucent/core`: the JavaScript version of `lucent:core`, for
+  tests that run Lucent modules as plain TypeScript.
+
+## Docs
+
+[What is Lucent](https://lucent-lang.dev/docs/) ·
+[Install](https://lucent-lang.dev/docs/install/) ·
+[Tutorial](https://lucent-lang.dev/docs/tutorial/1-shared-logic/) ·
+[How it works](https://lucent-lang.dev/docs/how-it-works/) ·
+[Guides](https://lucent-lang.dev/docs/guides/call-an-ios-api/) ·
+[Reference](https://lucent-lang.dev/docs/reference/language/) ·
+[Examples](https://lucent-lang.dev/docs/examples/) ·
+[Changelog](https://github.com/Fausto95/lucent/blob/main/packages/lucent/CHANGELOG.md)
+
+Issues and source: [github.com/Fausto95/lucent](https://github.com/Fausto95/lucent).
+
+MIT

package/app.plugin.js

@@ -21,6 +21,11 @@ function buildOnce(projectRoot) {
   });
   if (r.status !== 0)
     throw new Error("lucent build failed; fix the errors above and run prebuild again");
+  linkNativePackage(projectRoot);
+}
+
+/** Makes the app's react-native.config.js link the native package lucent build writes. */
+function linkNativePackage(projectRoot) {
   const rnConfig = path.join(projectRoot, "react-native.config.js");
   const entry = `"lucent": { root: require("path").join(__dirname, ".lucent", "native") }`;
   const text = fs.existsSync(rnConfig) ? fs.readFileSync(rnConfig, "utf8") : undefined;
@@ -29,7 +34,7 @@ function buildOnce(projectRoot) {
   } else if (text.includes('"lucent-native"')) {
     // Earlier versions named the dependency lucent-native.
     fs.writeFileSync(rnConfig, text.replace('"lucent-native"', '"lucent"'));
-  } else if (!/["']lucent["']\s*:/.test(text)) {
+  } else if (!/(^|[{,\s])(["']?)lucent\2\s*:/m.test(text)) {
     throw new Error(`Add ${entry} to the "dependencies" of react-native.config.js`);
   }
 }
@@ -52,15 +57,39 @@ function applyGradleTask(text) {
   return lines.join("\n");
 }
 
-/** Info.plist entries Lucent packages need (their lucent.json), as the last build recorded them. */
-function packagesInfoPlist(projectRoot) {
-  const manifest = path.join(projectRoot, ".lucent", "native", "manifest.json");
-  if (!fs.existsSync(manifest)) return {};
-  return JSON.parse(fs.readFileSync(manifest, "utf8")).infoPlist || {};
+/** What Lucent packages need (their lucent.json), as the last build resolved it. */
+function resolvedNative(projectRoot) {
+  const file = path.join(projectRoot, ".lucent", "native", "resolved.json");
+  if (!fs.existsSync(file)) return { ios: {} };
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+/**
+ * The app's plist entries (Info.plist, entitlements) with the packages'
+ * added: a key the app sets keeps the app's value, except arrays, which
+ * gain the values they lack.
+ */
+function withPackageEntries(app, packages) {
+  const out = { ...app };
+
+  for (const [key, { value }] of Object.entries(packages)) {
+    const own = out[key];
+
+    if (own === undefined) out[key] = value;
+    else if (Array.isArray(own) && Array.isArray(value))
+      out[key] = [...own, ...value.filter((v) => !own.includes(v))];
+  }
+
+  return out;
 }
 
 function withLucent(config) {
-  const { withAppBuildGradle, withDangerousMod, withInfoPlist } = require("expo/config-plugins");
+  const {
+    withAppBuildGradle,
+    withDangerousMod,
+    withEntitlementsPlist,
+    withInfoPlist,
+  } = require("expo/config-plugins");
   // Gradle builds run lucent build first, like `lucent init` sets up in bare apps.
   config = withAppBuildGradle(config, (c) => {
     if (c.modResults.language === "groovy")
@@ -70,9 +99,14 @@ function withLucent(config) {
   // Keys the app sets itself win.
   config = withInfoPlist(config, (c) => {
     buildOnce(c.modRequest.projectRoot);
-    for (const [key, { value }] of Object.entries(packagesInfoPlist(c.modRequest.projectRoot))) {
-      if (c.modResults[key] === undefined) c.modResults[key] = value;
-    }
+    const { ios } = resolvedNative(c.modRequest.projectRoot);
+    c.modResults = withPackageEntries(c.modResults, ios.infoPlist || {});
+    return c;
+  });
+  config = withEntitlementsPlist(config, (c) => {
+    buildOnce(c.modRequest.projectRoot);
+    const { ios } = resolvedNative(c.modRequest.projectRoot);
+    c.modResults = withPackageEntries(c.modResults, ios.entitlements || {});
     return c;
   });
   for (const platform of ["ios", "android"]) {
@@ -90,3 +124,5 @@ function withLucent(config) {
 module.exports = withLucent;
 module.exports.GRADLE_LINE = GRADLE_LINE;
 module.exports.applyGradleTask = applyGradleTask;
+module.exports.linkNativePackage = linkNativePackage;
+module.exports.withPackageEntries = withPackageEntries;

package/dist/{bench-CR3E7e2e.js → bench-eEez4jhQ.js}

@@ -1,12 +1,12 @@
-import { d as coreJsPath, g as projectFiles, m as moduleNameOf, n as compile, s as runtimeDir } from "./src-BD7f1_aZ.js";
+import { E as identityScript, N as projectFiles, O as coreJsPath, f as runtimeDir, j as moduleNameOf, n as compile } from "./src-ChnmWLwn.js";
 import { i as table } from "./format-D9fnIMEx.js";
-import { t as renderDiagnostic } from "./diagnostic-BM9sXmwl.js";
+import { t as renderDiagnostic } from "./diagnostic-BvwLZQS1.js";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import ts from "typescript";
-import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
 //#region ../runtime/test/sources.ts
 function runtimeSources(cppDir) {
 	const list = (dir, ext) => fs.readdirSync(path.join(cppDir, dir)).filter((f) => f.endsWith(ext)).map((f) => path.join(cppDir, dir, f));
@@ -61,7 +61,7 @@ async function run({ root, out }) {
 	if (!out.json) out.print(t.dim("building the native host (the first run compiles the runtime)…"));
 	const exe = await buildHost(work, generated, hermes);
 	const script = path.join(work, "bench.js");
-	fs.writeFileSync(script, benchScript(root, files, benches, result.proxies));
+	fs.writeFileSync(script, benchScript(root, files, benches, result.proxies, result.identity));
 	const r = spawnSync(exe, [script], {
 		encoding: "utf8",
 		timeout: 6e5,
@@ -213,7 +213,7 @@ async function buildHost(work, generated, hermes) {
 	if (r.status !== 0) throw new Error(`linking the benchmark host failed:\n${r.stderr}`);
 	return exe;
 }
-function benchScript(root, files, benches, proxies) {
+function benchScript(root, files, benches, proxies, identity) {
 	const defs = {};
 	const jsDeps = {};
 	const nativeDeps = {};
@@ -225,6 +225,7 @@ function benchScript(root, files, benches, proxies) {
 	const loader = fs.readFileSync(path.join(runtimeDir(), "js/index.js"), "utf8");
 	defs.core = fs.readFileSync(coreJsPath(), "utf8");
 	defs.loader = loader;
+	defs.identity = identityScript(identity);
 	defs["react-native"] = "module.exports = { TurboModuleRegistry: { get: function () { return undefined; } } };";
 	const resolve = (from, spec) => {
 		if (spec === "lucent:core") return "core";
@@ -250,13 +251,16 @@ function benchScript(root, files, benches, proxies) {
 		}
 	}
 	for (const [name, proxy] of proxies) {
+		const up = "../".repeat(name.split("/").length - 1) || "./";
 		defs[`proxy:${name}`] = proxy;
 		nativeDeps[`proxy:${name}`] = {
-			[`${"../".repeat(name.split("/").length - 1) || "./"}_lucent/runtime.js`]: "loader",
+			[`${up}_lucent/runtime.js`]: "loader",
+			[`${up}_lucent/identity.js`]: "identity",
 			"react-native": "react-native"
 		};
 	}
 	nativeDeps.loader = {};
+	nativeDeps.identity = {};
 	return `var defs = {
 ${Object.entries(defs).map(([id, code]) => `${JSON.stringify(id)}: function (module, exports, require) {\n${code}\n}`).join(",\n")}
 };

package/dist/{build-CAIrRSYA.js → build-CpUjeHFz.js}

@@ -1,4 +1,4 @@
-import { t as buildOrCheck } from "./build-check-QozuNJm5.js";
+import { t as buildOrCheck } from "./build-check-BA1ZEp9s.js";
 //#region src/cli/commands/build.ts
 function run(invocation) {
 	return buildOrCheck("build", invocation);

package/dist/{build-check-QozuNJm5.js → build-check-BA1ZEp9s.js}

@@ -1,13 +1,14 @@
 import { n as version } from "./version-bqpIO5sP.js";
 import { i as table, n as duration } from "./format-D9fnIMEx.js";
-import { t as renderDiagnostic } from "./diagnostic-BM9sXmwl.js";
-import { n as nextText, r as plural, t as buildProject } from "./pipeline-CH7-2cxu.js";
+import { t as renderDiagnostic } from "./diagnostic-BvwLZQS1.js";
+import { a as filesText, i as ACTION_TEXT, n as nextText, r as plural, t as buildProject } from "./pipeline-BM_VM2X_.js";
 import { t as plainSteps } from "./steps--_h-FFS7.js";
 import fs from "node:fs";
 import path from "node:path";
 //#region src/cli/commands/build-check.ts
 async function buildOrCheck(command, { root, flags, out }) {
 	const theme = out.theme;
+	const sources = /* @__PURE__ */ new Map();
 	const notices = [];
 	const notify = (n) => {
 		notices.push(n);
@@ -22,7 +23,8 @@ async function buildOrCheck(command, { root, flags, out }) {
 			force: !!flags.force,
 			platforms: typeof flags.platforms === "string" && flags.platforms ? flags.platforms.split(",") : void 0,
 			out: typeof flags.out === "string" ? flags.out : void 0,
-			prefetch: true
+			prefetch: true,
+			frozen: !!flags.frozen
 		}, steps, notify);
 	} finally {
 		await steps.close();
@@ -36,6 +38,7 @@ async function buildOrCheck(command, { root, flags, out }) {
 			ok: result.ok,
 			modules: result.modules.map((m) => m.name),
 			diagnostics: result.diagnostics,
+			warnings: result.warnings,
 			errors: result.diagnostics.length,
 			ms: result.ms
 		});
@@ -46,8 +49,10 @@ async function buildOrCheck(command, { root, flags, out }) {
 			modules: result.modules,
 			steps: steps.results,
 			diagnostics: result.diagnostics,
+			warnings: result.warnings,
 			notices,
 			next: result.next,
+			actions: result.actions,
 			ms: result.ms
 		});
 		return result.ok ? 0 : 1;
@@ -57,9 +62,13 @@ async function buildOrCheck(command, { root, flags, out }) {
 		return 1;
 	}
 	if (!result.ok) {
-		problems(result.diagnostics, result.modules.length, result.ms, command === "build");
+		problems([...result.diagnostics, ...result.warnings], result.modules.length, result.ms, command === "build");
 		return 1;
 	}
+	if (result.warnings.length) {
+		out.error("");
+		for (const d of result.warnings) out.error(`${renderDiagnostic(d, d.file ? source(d.file) : void 0, theme)}\n`);
+	}
 	if (command === "check") {
 		out.print(`${theme.success(theme.symbols.ok)} ${plural(result.modules.length, "module")}, no problems  ${theme.dim(result.upToDate ? `${duration(result.ms)} (unchanged since the last check)` : duration(result.ms))}`);
 		return 0;
@@ -72,19 +81,25 @@ async function buildOrCheck(command, { root, flags, out }) {
 		m.platforms.join(" ")
 	]))) out.print(line);
 	out.print(`${theme.dim("next")}     ${nextText(result.next)}`);
+	for (const line of table(result.actions.map((a, i) => [
+		i ? "" : theme.dim("actions"),
+		ACTION_TEXT[a.kind],
+		a.targets.join(", "),
+		filesText(a.files)
+	]))) out.print(line);
 	return 0;
+	function source(file) {
+		if (!sources.has(file)) {
+			const abs = path.resolve(root, file);
+			sources.set(file, fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : void 0);
+		}
+		return sources.get(file);
+	}
 	function problems(diagnostics, modules, ms, build) {
-		const sources = /* @__PURE__ */ new Map();
-		const source = (file) => {
-			if (!sources.has(file)) {
-				const abs = path.resolve(root, file);
-				sources.set(file, fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : void 0);
-			}
-			return sources.get(file);
-		};
 		out.error("");
 		for (const d of diagnostics) out.error(`${renderDiagnostic(d, d.file ? source(d.file) : void 0, theme)}\n`);
-		const summary = `${plural(diagnostics.length, "error")} ${theme.dim("·")} ${plural(modules, "module")} ${theme.dim("·")} ${duration(ms)}`;
+		const errors = diagnostics.filter((d) => d.severity !== "warning").length;
+		const summary = `${plural(errors, "error")} ${theme.dim("·")} ${plural(modules, "module")} ${theme.dim("·")} ${duration(ms)}`;
 		out.error(`  ${theme.error(summary)}${build ? theme.dim("  nothing was written") : ""}`);
 	}
 }

package/dist/{check-1SCmYlqA.js → check-BZx3FgI6.js}

@@ -1,4 +1,4 @@
-import { t as buildOrCheck } from "./build-check-QozuNJm5.js";
+import { t as buildOrCheck } from "./build-check-BA1ZEp9s.js";
 //#region src/cli/commands/check.ts
 function run(invocation) {
 	return buildOrCheck("check", invocation);

package/dist/cli.js

@@ -109,15 +109,22 @@ const commands = [
 				name: "out",
 				value: "dir",
 				description: "Where to write the native package (default: .lucent/native)"
+			},
+			{
+				name: "frozen",
+				description: "Fail unless the SDKs and SDK symbols are the ones lucent-sdk.lock.json records, with every target it lists (CI, releases)"
 			}
 		],
-		load: () => import("./build-CAIrRSYA.js")
+		load: () => import("./build-CpUjeHFz.js")
 	},
 	{
 		name: "check",
 		summary: "Type-check and validate every module without writing anything",
-		flags: [],
-		load: () => import("./check-1SCmYlqA.js")
+		flags: [{
+			name: "frozen",
+			description: "Fail unless the SDKs and SDK symbols are the ones lucent-sdk.lock.json records, with every target it lists (CI, releases)"
+		}],
+		load: () => import("./check-BZx3FgI6.js")
 	},
 	{
 		name: "dev",
@@ -126,13 +133,13 @@ const commands = [
 			name: "compact",
 			description: "One line per build instead of the dashboard (Metro runs it so)"
 		}],
-		load: () => import("./dev-BYWMP7oC.js")
+		load: () => import("./dev-DI5yL8zx.js")
 	},
 	{
 		name: "doctor",
 		summary: "Check the machine and the app: Node, React Native, Xcode, CocoaPods, the Android SDK, the JDK, the Metro config, versions",
 		flags: [],
-		load: () => import("./doctor-DdR4JnVc.js")
+		load: () => import("./doctor-CrgOAV5L.js")
 	},
 	{
 		name: "init",
@@ -166,13 +173,27 @@ const commands = [
 		name: "explain",
 		summary: "What a LUCENT diagnostic code means, and how to fix it (every code without one)",
 		flags: [],
-		load: () => import("./explain--vV1oaRl.js")
+		load: () => import("./explain-Byit07F-.js")
 	},
 	{
 		name: "bench",
 		summary: "Time the cases of your *.bench.ts files natively and as JavaScript, and show the speedup (needs a desktop Hermes)",
 		flags: [],
-		load: () => import("./bench-CR3E7e2e.js")
+		load: () => import("./bench-eEez4jhQ.js")
+	},
+	{
+		name: "trace",
+		summary: "Write the last build's steps and the runtime traces given as one Chrome trace (.lucent/trace.json), and how long each cause took",
+		flags: [{
+			name: "runtime",
+			value: "files",
+			description: "Runtime traces to include, comma-separated (written with LUCENT_TRACE=<file>.json)"
+		}, {
+			name: "out",
+			value: "file",
+			description: "Where to write it (default: .lucent/trace.json)"
+		}],
+		load: () => import("./trace-Bi4hkmPx.js")
 	},
 	{
 		name: "clean",
@@ -187,13 +208,13 @@ const commands = [
 		name: "sdk search",
 		summary: "Find SDK classes and members by name, with the import to copy (your imports and the SDK cache)",
 		flags: [],
-		load: () => import("./sdk-search-Iv4K3-8a.js")
+		load: () => import("./sdk-search-CPGJm_Ne.js")
 	},
 	{
 		name: "sdk show",
 		summary: "Print the declaration Lucent code sees for an SDK type or member: android.os.Vibrator, UIKit.UIDevice.current",
 		flags: [],
-		load: () => import("./sdk-show-CkrdlqlP.js")
+		load: () => import("./sdk-show-BUkLqRnA.js")
 	},
 	{
 		name: "sdk prefetch",
@@ -216,11 +237,30 @@ const commands = [
 				description: "Every module of every installed SDK"
 			}
 		],
-		load: () => import("./sdk-prefetch-mo04JDZV.js")
+		load: () => import("./sdk-prefetch-Bv2pNega.js")
+	},
+	{
+		name: "sdk lock",
+		summary: "Record the SDKs and SDK symbols the project uses in lucent-sdk.lock.json, for --frozen builds and sdk diff",
+		flags: [{
+			name: "platforms",
+			value: "list",
+			description: "Targets to record: ios, android (default: every platform the project has code for, each needing its SDK)"
+		}],
+		load: () => import("./sdk-lock-BQn7IyRs.js")
+	},
+	{
+		name: "sdk diff",
+		summary: "What the installed SDKs change for the SDK symbols lucent-sdk.lock.json records: removed and changed members, before rebuilding",
+		flags: [{
+			name: "all",
+			description: "Also the other members of the modules the project uses (the locked schemas must be in this machine's SDK cache)"
+		}],
+		load: () => import("./sdk-diff-ByJ1Gw-F.js")
 	},
 	{
 		name: "sdk coverage",
-		summary: "Per SDK module, the members Lucent code can call: idiomatic, raw, unrepresentable",
+		summary: "Per SDK module, how far members get: discovered, representable, generated by the last build, exercised",
 		flags: [
 			{
 				name: "ios",
@@ -236,9 +276,18 @@ const commands = [
 				name: "check",
 				value: "baseline",
 				description: "Fail when the unrepresentable share grows past a baseline JSON"
+			},
+			{
+				name: "exercised",
+				value: "file",
+				description: "A JSON array of the symbol keys tests or probes ran (see --members)"
+			},
+			{
+				name: "members",
+				description: "List every member with its stage, key and reason"
 			}
 		],
-		load: () => import("./sdk-coverage-BoW_3Efd.js")
+		load: () => import("./sdk-coverage-iiv3JqMp.js")
 	}
 ];
 //#endregion
@@ -401,6 +450,6 @@ function usesLucent(root) {
 }
 installCrashHandler(version());
 const status = await main(process.argv.slice(2));
-if (status >= 0) process.exit(status);
+if (status >= 0) process.stdout.write("", () => process.exit(status));
 //#endregion
 export {};