@lucent-lang/lucent 0.0.4 → 0.1.1

package/schemas/check.schema.json

@@ -2,7 +2,7 @@
   "$id": "https://lucent-lang.dev/schemas/check.schema.json",
   "title": "lucent check --json",
   "type": "object",
-  "required": ["ok", "modules", "diagnostics", "errors", "ms"],
+  "required": ["ok", "modules", "diagnostics", "warnings", "errors", "ms"],
   "additionalProperties": false,
   "properties": {
     "ok": {
@@ -58,10 +58,65 @@
           "docs": {
             "type": "string",
             "description": "Where the code is explained"
+          },
+          "severity": {
+            "const": "warning",
+            "description": "Present on warnings only"
           }
         }
       }
     },
+    "warnings": {
+      "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"
+          },
+          "severity": {
+            "const": "warning",
+            "description": "Present on warnings only"
+          }
+        }
+      },
+      "description": "Warnings: reported, but the build goes on"
+    },
     "errors": {
       "type": "integer",
       "minimum": 0

package/schemas/lucent.schema.json

@@ -1,7 +1,7 @@
 {
   "$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.",
+  "description": "What a Lucent package's platform code needs from the app that installs it, next to the package's package.json. The app's build merges every package's needs into .lucent/native/resolved.json, naming the package each came from. Needs that cannot all hold fail the build, naming both packages.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -12,13 +12,182 @@
       "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" }
+          "description": "CocoaPods the native package depends on: pod name → version requirement, as in a Podfile (\"~> 1.0\", \">= 1.2, < 2\"). Every package's requirement on a pod goes to CocoaPods, which picks the version; requirements no version can meet fail the build. Their frameworks can be imported from lucent:ios/* once installed.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "frameworks": {
+          "type": "array",
+          "description": "Apple frameworks the native package links, such as \"CoreHaptics\". Frameworks of the lucent:ios/* modules the code imports are linked without listing them here.",
+          "items": {
+            "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" }
+          "description": "Info.plist entries: key → a string, a boolean or an array of strings. Packages must agree on a key's value, except arrays, which join. The Expo config plugin adds them: a key the app sets keeps the app's value, and an array gains the values it lacks. For bare apps, lucent build names the keys and array values the app's Info.plist lacks.",
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            ]
+          }
+        },
+        "nativeSources": {
+          "type": "array",
+          "description": "Directories of native sources compiled into the native package's pod: C, C++, Objective-C and Swift (.h, .hpp, .m, .mm, .c, .cc, .cpp, .swift). Each directory is also a header search path. Paths are relative to the package; lucent build copies them into .lucent/native/packages/<package>/.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "resources": {
+          "type": "array",
+          "description": "Files or directories copied into the app bundle's root under their own names, such as \"assets/chime.caf\". Two that would land on the same name fail the build, naming both packages: namespace one with resourceBundles.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "resourceBundles": {
+          "type": "object",
+          "description": "Resource bundles: bundle name → files or directories copied into <name>.bundle in the app. A bundle name belongs to one package.",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "vendoredFrameworks": {
+          "type": "array",
+          "description": "Prebuilt .framework or .xcframework directories the pod links and embeds. lucent:ios binds their modules (an XCFramework's through its iOS simulator slice). Two with the same framework name fail the build, naming both packages.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "swiftPackages": {
+          "type": "object",
+          "description": "Swift packages the pod depends on: package URL → { requirement, products }. The requirement is Xcode's, such as { \"kind\": \"upToNextMajorVersion\", \"minimumVersion\": \"1.2.0\" }. Packages must agree on a URL's requirement; their products join. React Native's spm_dependency adds them at pod install.",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["requirement", "products"],
+            "properties": {
+              "requirement": {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["kind", "minimumVersion"],
+                    "properties": {
+                      "kind": {
+                        "enum": ["upToNextMajorVersion", "upToNextMinorVersion"]
+                      },
+                      "minimumVersion": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["kind", "version"],
+                    "properties": {
+                      "kind": {
+                        "const": "exactVersion"
+                      },
+                      "version": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["kind", "minimumVersion", "maximumVersion"],
+                    "properties": {
+                      "kind": {
+                        "const": "versionRange"
+                      },
+                      "minimumVersion": {
+                        "type": "string"
+                      },
+                      "maximumVersion": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["kind", "branch"],
+                    "properties": {
+                      "kind": {
+                        "const": "branch"
+                      },
+                      "branch": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["kind", "revision"],
+                    "properties": {
+                      "kind": {
+                        "const": "revision"
+                      },
+                      "revision": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                ]
+              },
+              "products": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "entitlements": {
+          "type": "object",
+          "description": "The app's entitlements: key → a string, a boolean or an array of strings. Packages must agree on a key's value, except arrays, which join. The Expo config plugin adds them like Info.plist entries. For bare apps, lucent build names what the app's .entitlements file lacks.",
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            ]
+          }
+        },
+        "deploymentTarget": {
+          "type": "string",
+          "pattern": "^\\d+(\\.\\d+){0,2}$",
+          "description": "The lowest iOS version the package runs on, such as \"15.1\". The pod requires the highest any package needs, and never less than React Native's minimum. CocoaPods fails an app target below it."
         }
       }
     },
@@ -29,13 +198,330 @@
       "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" }
+          "description": "Gradle artifacts: \"group:artifact\" → version. They become api dependencies of the native package, so lucent:android/* can import their classes. Every package's version of an artifact goes to Gradle, which picks one; a strict version (\"1.0!!\") that another package's excludes fails the build.",
+          "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" }
+          "description": "Android permissions for the manifest, such as \"android.permission.CAMERA\". Each is declared once, however many packages list it. Permissions the SDK methods you call require are added without listing them here.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "nativeSources": {
+          "type": "array",
+          "description": "Java and Kotlin source roots of the native package's Android library, such as \"native/android\". Their C and C++ files (.c, .cc, .cpp) are compiled with the runtime. Each directory is also a header search path. Kotlin sources apply the Kotlin Android plugin.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "resources": {
+          "type": "array",
+          "description": "Android resource directories (the res layout: drawable/, values/…). A file-based resource two packages both have fails the build, naming both; Android's resource merger reports duplicate value resources.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "assets": {
+          "type": "array",
+          "description": "Asset directories, packaged into the app's assets. Two files with the same path fail the build, naming both packages.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "libraries": {
+          "type": "array",
+          "description": "Prebuilt .aar or .jar files, api dependencies of the native package's library. lucent:android binds their classes, before the app's Gradle build has run. Two with the same file name fail the build, naming both packages.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "nativeLibraries": {
+          "type": "array",
+          "description": "Directories of prebuilt native libraries by ABI (arm64-v8a/liborbit.so), packaged into the app. Two with the same path fail the build, naming both packages.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "components": {
+          "type": "array",
+          "description": "Components for the library's manifest, which Android merges into the app's: services, receivers, activities and providers. A class is declared once; packages that declare it differently fail the build, naming both.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "name"],
+            "if": {
+              "properties": {
+                "kind": {
+                  "const": "provider"
+                }
+              }
+            },
+            "then": {
+              "required": ["authorities"]
+            },
+            "properties": {
+              "kind": {
+                "enum": ["activity", "service", "receiver", "provider"]
+              },
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z_$][\\w$]*(\\.[A-Za-z_$][\\w$]*)+$",
+                "description": "Fully qualified class name."
+              },
+              "exported": {
+                "type": "boolean"
+              },
+              "enabled": {
+                "type": "boolean"
+              },
+              "permission": {
+                "type": "string"
+              },
+              "authorities": {
+                "type": "string"
+              },
+              "grantUriPermissions": {
+                "type": "boolean"
+              },
+              "foregroundServiceType": {
+                "type": "string"
+              },
+              "theme": {
+                "type": "string",
+                "description": "An activity's theme, such as \"@android:style/Theme.Translucent.NoTitleBar\"."
+              },
+              "configChanges": {
+                "type": "string",
+                "description": "The configuration changes an activity handles itself instead of being recreated, such as \"orientation|screenSize\"."
+              },
+              "intentFilters": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["actions"],
+                  "properties": {
+                    "actions": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "categories": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                          "scheme": {
+                            "type": "string"
+                          },
+                          "host": {
+                            "type": "string"
+                          },
+                          "port": {
+                            "type": "string"
+                          },
+                          "path": {
+                            "type": "string"
+                          },
+                          "pathPrefix": {
+                            "type": "string"
+                          },
+                          "pathPattern": {
+                            "type": "string"
+                          },
+                          "mimeType": {
+                            "type": "string"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              },
+              "metaData": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "minSdk": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The lowest Android API level the package runs on. The library requires the highest any package needs, and never less than the app's minSdkVersion. Android's manifest merger fails an app below it."
+        }
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Extension name → a native extension, imported as lucent:ext/<name>. A name belongs to one package of the app.",
+      "propertyNames": {
+        "pattern": "^[A-Za-z][\\w-]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "description": "A native extension: a C header whose functions Lucent code imports from lucent:ext/<name>, with what C declarations cannot say. Every name is checked against the header as clang reads it.",
+        "additionalProperties": false,
+        "required": ["header"],
+        "properties": {
+          "header": {
+            "type": "string",
+            "description": "The C header, relative to the package, in a directory both ios.nativeSources and android.nativeSources list: both builds compile the extension and search that directory. It must compile as C and as C++, declaring its functions in extern \"C\" when C++ includes it. Functions it declares that need no declaration here (numbers and booleans) are bound as they are; one that takes a handle must be named here."
+          },
+          "handles": {
+            "type": "object",
+            "description": "Opaque struct (declared, not defined, in the header) → the handle Lucent code holds, a class of lucent:ext/<name>. Handles cannot cross the JavaScript boundary: a Lucent class keeps one.",
+            "propertyNames": {
+              "pattern": "^[A-Za-z_]\\w*$"
+            },
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["create", "destroy"],
+              "properties": {
+                "create": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_]\\w*$",
+                  "description": "The function that makes one: it returns a pointer to the struct, null when it fails (declare failsWhen: null). It is the class's constructor."
+                },
+                "destroy": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_]\\w*$",
+                  "description": "void f(T *): runs once, when the handle closes (close(), a using declaration, or its last reference going)."
+                },
+                "methods": {
+                  "type": "object",
+                  "description": "Method name → the function it calls, with the handle as its first argument.",
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z_]\\w*$"
+                  }
+                },
+                "affinity": {
+                  "enum": ["any", "main"],
+                  "description": "The thread: any, one call at a time (the default), or the main thread, where Lucent code uses it inside main(() => …)."
+                }
+              }
+            }
+          },
+          "functions": {
+            "type": "object",
+            "description": "C function name → what its parameters and result mean.",
+            "propertyNames": {
+              "pattern": "^[A-Za-z_]\\w*$"
+            },
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "params": {
+                  "type": "object",
+                  "description": "C parameter name → what the pointer is. Numbers, booleans and handles need nothing; nothing escapes the call.",
+                  "propertyNames": {
+                    "pattern": "^[A-Za-z_]\\w*$"
+                  },
+                  "additionalProperties": {
+                    "oneOf": [
+                      {
+                        "type": "object",
+                        "description": "Bytes the function reads or writes: a Uint8Array in Lucent, as many bytes as its length. The pointer must point to 8-bit integers or void, and to non-const ones for write.",
+                        "additionalProperties": false,
+                        "required": ["bytes", "length"],
+                        "properties": {
+                          "bytes": {
+                            "enum": ["read", "write"]
+                          },
+                          "length": {
+                            "type": "string",
+                            "pattern": "^[A-Za-z_]\\w*$",
+                            "description": "The integer parameter holding the byte count: Lucent passes the array's length."
+                          }
+                        }
+                      },
+                      {
+                        "type": "object",
+                        "description": "A NUL-terminated UTF-8 string (const char *): a string in Lucent, valid during the call.",
+                        "additionalProperties": false,
+                        "required": ["string"],
+                        "properties": {
+                          "string": {
+                            "enum": ["utf8"]
+                          }
+                        }
+                      },
+                      {
+                        "type": "object",
+                        "description": "The error struct the function fills in when it fails; Lucent passes it and throws its message.",
+                        "additionalProperties": false,
+                        "required": ["error"],
+                        "properties": {
+                          "error": {
+                            "type": "string",
+                            "pattern": "^[A-Za-z_]\\w*$",
+                            "description": "A struct declared in errors."
+                          }
+                        }
+                      }
+                    ]
+                  }
+                },
+                "failsWhen": {
+                  "enum": ["null", "negative", "nonzero", "zero", "false"],
+                  "description": "How the result says the call failed, which throws an Error with the error struct's message and code. With nonzero or false the result is a status, and the Lucent function returns nothing."
+                },
+                "affinity": {
+                  "enum": ["any", "main"],
+                  "description": "The thread: any, one call at a time (the default), or the main thread, where Lucent code uses it inside main(() => …)."
+                },
+                "blocking": {
+                  "type": "boolean",
+                  "description": "It may block (I/O, locks, long work): calling it inside main(() => …) is a warning."
+                }
+              }
+            }
+          },
+          "errors": {
+            "type": "object",
+            "description": "C struct name (defined in the header) → the error its functions fill in.",
+            "propertyNames": {
+              "pattern": "^[A-Za-z_]\\w*$"
+            },
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["message"],
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_]\\w*$",
+                  "description": "An integer field: the Error's code."
+                },
+                "message": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_]\\w*$",
+                  "description": "A const char * field: the Error's message, copied before the call returns."
+                },
+                "release": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_]\\w*$",
+                  "description": "void f(E *), called after every call that takes the struct, once it was read, when it holds something to free."
+                }
+              }
+            }
+          }
         }
       }
     }

package/schemas/sdk-diff.schema.json

@@ -0,0 +1,70 @@
+{
+  "$id": "https://lucent-lang.dev/schemas/sdk-diff.schema.json",
+  "title": "lucent sdk diff --json",
+  "type": "object",
+  "required": ["ok", "unavailable", "artifacts", "used"],
+  "additionalProperties": false,
+  "definitions": {
+    "change": {
+      "type": "object",
+      "required": ["change", "platform", "module", "key", "display", "signature", "details"],
+      "additionalProperties": false,
+      "properties": {
+        "change": { "enum": ["removed", "changed", "added", "unchanged"] },
+        "platform": { "enum": ["ios", "android"] },
+        "module": { "type": "string" },
+        "key": { "type": "string", "description": "The symbol's key in the lock" },
+        "display": { "type": "string", "description": "As the lock names it: Tracker.level" },
+        "signature": { "type": "string", "description": "As installed (as locked, when removed)" },
+        "details": {
+          "type": "array",
+          "description": "What changed; why, for a removed module",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  },
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "description": "Every locked target has its SDK, and no used symbol was removed or changed"
+    },
+    "unavailable": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["platform", "reason"],
+        "additionalProperties": false,
+        "properties": {
+          "platform": { "enum": ["ios", "android"] },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "description": "Used modules now read from other artifacts than the lock records",
+      "items": {
+        "type": "object",
+        "required": ["module", "found"],
+        "additionalProperties": false,
+        "properties": {
+          "module": { "type": "string" },
+          "locked": { "type": "array", "items": { "type": "string" } },
+          "found": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "used": { "type": "array", "items": { "$ref": "#/definitions/change" } },
+    "others": {
+      "type": "array",
+      "description": "With --all: changes to the other members of the used modules",
+      "items": { "$ref": "#/definitions/change" }
+    },
+    "uncached": {
+      "type": "array",
+      "description": "With --all: modules whose locked schema this machine's SDK cache does not hold",
+      "items": { "type": "string" }
+    }
+  }
+}