Add app metadata introspection APIs (#703)

* Add app metadata system APIs

* fix(#673): bake metadata in JS emit, dedupe perry.toml parse, regen API docs

Address review feedback on PR #703:

- JS emit path (`crates/perry-codegen-js`) now intercepts `getAppVersion` /
  `getAppBuildNumber` / `getBundleId` and emits string/number literals from
  AppMetadata, instead of falling through to `console.warn('… not available
  in browser')`. Web/JS builds now resolve the same values as native.
- `read_app_metadata` takes `Option<&toml::Table>` instead of `Option<&Path>`,
  so `perry.toml` is parsed exactly once in `run_with_parse_cache` and
  shared with the existing i18n block.
- `CompilationContext.app_metadata` exposes the resolved metadata to all
  codegen backends — used by the web/JS target wiring above and available
  for future arkts / wasm consumers.
- Tests: add the missing `version` assertion in `cli_bundle_id_overrides_…`
  and a new `package_json_bundle_id_falls_back_…` case covering the
  package.json fallback branch.
- Regenerate `docs/api/perry.d.ts` and `docs/src/api/reference.md` —
  fixes the `api-docs-drift` CI gate that was failing on this PR.

Author: TheHypnoo

crates/perry-api-manifest/src/entries.rs

@@ -1845,6 +1845,9 @@ pub static API_MANIFEST: &[ApiEntry] = &[
     method("perry/system", "getDeviceIdiom", false, None),
     method("perry/system", "getDeviceModel", false, None),
     method("perry/system", "getLocale", false, None),
+    method("perry/system", "getAppVersion", false, None),
+    method("perry/system", "getAppBuildNumber", false, None),
+    method("perry/system", "getBundleId", false, None),
     method("perry/system", "getAppIcon", false, None),
     method("perry/system", "openURL", false, None),
     method("perry/system", "keychainSave", false, None),

crates/perry-codegen-js/src/emit.rs

@@ -7,6 +7,28 @@ use perry_types::{FuncId, GlobalId, LocalId};
 use std::collections::{BTreeMap, BTreeSet};
 use std::fmt::Write as FmtWrite;
 
+/// App metadata baked into compile-time `perry/system` introspection APIs
+/// (`getAppVersion`/`getAppBuildNumber`/`getBundleId`) when emitting JS.
+///
+/// Mirrors `perry_codegen::AppMetadata` — duplicated here so this crate
+/// doesn't take a backend dep on perry-codegen.
+#[derive(Debug, Clone)]
+pub struct AppMetadata {
+    pub version: String,
+    pub build_number: i64,
+    pub bundle_id: String,
+}
+
+impl Default for AppMetadata {
+    fn default() -> Self {
+        Self {
+            version: "1.0.0".to_string(),
+            build_number: 1,
+            bundle_id: "com.perry.app".to_string(),
+        }
+    }
+}
+
 /// JavaScript code emitter that translates HIR to JavaScript.
 pub struct JsEmitter {
     /// Output buffer
@@ -29,10 +51,16 @@ pub struct JsEmitter {
     minify: bool,
     /// Counter for generating short mangled names
     mangle_counter: usize,
+    /// App metadata baked into compile-time `perry/system` introspection APIs.
+    app_metadata: AppMetadata,
 }
 
 impl JsEmitter {
     pub fn new(module_name: &str, minify: bool) -> Self {
+        Self::with_metadata(module_name, minify, AppMetadata::default())
+    }
+
+    pub fn with_metadata(module_name: &str, minify: bool, app_metadata: AppMetadata) -> Self {
         Self {
             output: String::with_capacity(8192),
             indent: 0,
@@ -44,6 +72,7 @@ impl JsEmitter {
             exported_names: BTreeSet::new(),
             minify,
             mangle_counter: 0,
+            app_metadata,
         }
     }
 
@@ -3160,6 +3189,17 @@ impl JsEmitter {
             "getDeviceModel" | "get_device_model" => {
                 self.output.push_str("perry_system_get_device_model()");
             }
+            "getAppVersion" | "get_app_version" => {
+                let s = self.quote_string(&self.app_metadata.version.clone());
+                self.output.push_str(&s);
+            }
+            "getAppBuildNumber" | "get_app_build_number" => {
+                let _ = write!(self.output, "{}", self.app_metadata.build_number);
+            }
+            "getBundleId" | "get_bundle_id" => {
+                let s = self.quote_string(&self.app_metadata.bundle_id.clone());
+                self.output.push_str(&s);
+            }
             _ => {
                 let _ = write!(
                     self.output,

crates/perry-codegen-js/src/lib.rs

@@ -6,6 +6,8 @@
 pub mod emit;
 pub mod minify;
 
+pub use emit::AppMetadata;
+
 use anyhow::Result;
 use perry_hir::ir::{Module, Stmt};
 use std::collections::BTreeSet;
@@ -16,7 +18,17 @@ const WEB_RUNTIME_JS: &str = include_str!("web_runtime.js");
 /// Compile a single HIR module to JavaScript source code.
 /// Returns (js_source, exported_names).
 pub fn compile_module_to_js(module: &Module, minify_names: bool) -> (String, BTreeSet<String>) {
-    let emitter = emit::JsEmitter::new(&module.name, minify_names);
+    compile_module_to_js_with_metadata(module, minify_names, AppMetadata::default())
+}
+
+/// Compile a single HIR module to JavaScript source code, baking the supplied
+/// app metadata into compile-time `perry/system` introspection APIs.
+pub fn compile_module_to_js_with_metadata(
+    module: &Module,
+    minify_names: bool,
+    app_metadata: AppMetadata,
+) -> (String, BTreeSet<String>) {
+    let emitter = emit::JsEmitter::with_metadata(&module.name, minify_names, app_metadata);
 
     // Collect names that have runtime values (not type-only exports)
     let mut runtime_names = BTreeSet::new();
@@ -61,6 +73,17 @@ pub fn compile_modules_to_html(
     modules: &[(String, Module)], // (module_name, hir_module)
     title: &str,
     minify: bool,
+) -> Result<String> {
+    compile_modules_to_html_with_metadata(modules, title, minify, AppMetadata::default())
+}
+
+/// Same as `compile_modules_to_html` but bakes the supplied app metadata into
+/// compile-time `perry/system` introspection APIs.
+pub fn compile_modules_to_html_with_metadata(
+    modules: &[(String, Module)],
+    title: &str,
+    minify: bool,
+    app_metadata: AppMetadata,
 ) -> Result<String> {
     let mut all_js = String::with_capacity(32768);
     let mut declared_names = BTreeSet::new();
@@ -71,7 +94,8 @@ pub fn compile_modules_to_html(
     for (i, (mod_name, module)) in modules.iter().enumerate() {
         let is_entry = i == entry_idx;
 
-        let (js, exported_names) = compile_module_to_js(module, minify);
+        let (js, exported_names) =
+            compile_module_to_js_with_metadata(module, minify, app_metadata.clone());
 
         if is_entry {
             // Entry module: emit directly (no IIFE wrapper)

crates/perry-codegen/src/codegen.rs

@@ -41,6 +41,25 @@ use crate::stmt;
 use crate::strings::StringPool;
 use crate::types::{LlvmType, DOUBLE, I32, I64, I8, PTR, VOID};
 
+/// Per-application metadata read from `perry.toml` by the CLI and baked into
+/// compile-time system APIs.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AppMetadata {
+    pub version: String,
+    pub build_number: i64,
+    pub bundle_id: String,
+}
+
+impl Default for AppMetadata {
+    fn default() -> Self {
+        Self {
+            version: "1.0.0".to_string(),
+            build_number: 1,
+            bundle_id: "com.perry.app".to_string(),
+        }
+    }
+}
+
 /// Options controlling code generation for a single module.
 #[derive(Debug, Clone, Default)]
 pub struct CompileOptions {
@@ -186,6 +205,8 @@ pub struct CompileOptions {
     /// Drives `crate::block::FAST_MATH`; included in the object cache
     /// key so toggling it invalidates cached `.o` bytes.
     pub fast_math: bool,
+    /// App metadata backing `perry/system` compile-time introspection APIs.
+    pub app_metadata: AppMetadata,
 }
 
 /// A class imported from another native module.
@@ -342,6 +363,8 @@ pub(crate) struct CrossModuleCtx {
     /// dead branches (which may reference FFI functions that don't exist on
     /// the current target).
     pub compile_time_constants: std::collections::HashMap<u32, f64>,
+    /// App metadata backing compile-time `perry/system` introspection APIs.
+    pub app_metadata: AppMetadata,
     /// Functions with a 3-param clamp pattern: fid → true. Call sites
     /// emit `@llvm.smax.i32` + `@llvm.smin.i32` instead of a function call.
     pub clamp3_functions: std::collections::HashSet<u32>,
@@ -1088,6 +1111,7 @@ pub fn compile_module(hir: &HirModule, opts: CompileOptions) -> Result<Vec<u8>>
         geisterhand_port: opts.geisterhand_port,
         needs_js_runtime: opts.needs_js_runtime,
         compile_time_constants,
+        app_metadata: opts.app_metadata.clone(),
         clamp3_functions: hir
             .functions
             .iter()
@@ -2928,6 +2952,7 @@ fn compile_function(
         local_id_to_name: HashMap::new(),
         imported_vars: &cross_module.imported_vars,
         compile_time_constants: &cross_module.compile_time_constants,
+        app_metadata: &cross_module.app_metadata,
         scalar_replaced: std::collections::HashMap::new(),
         scalar_replaced_arrays: std::collections::HashMap::new(),
         scalar_ctor_target: Vec::new(),
@@ -3306,6 +3331,7 @@ fn compile_closure(
         local_id_to_name: HashMap::new(),
         imported_vars: &cross_module.imported_vars,
         compile_time_constants: &cross_module.compile_time_constants,
+        app_metadata: &cross_module.app_metadata,
         scalar_replaced: std::collections::HashMap::new(),
         scalar_replaced_arrays: std::collections::HashMap::new(),
         scalar_ctor_target: Vec::new(),
@@ -3529,6 +3555,7 @@ fn compile_method(
         local_id_to_name: HashMap::new(),
         imported_vars: &cross_module.imported_vars,
         compile_time_constants: &cross_module.compile_time_constants,
+        app_metadata: &cross_module.app_metadata,
         scalar_replaced: std::collections::HashMap::new(),
         scalar_replaced_arrays: std::collections::HashMap::new(),
         scalar_ctor_target: Vec::new(),
@@ -3959,6 +3986,7 @@ fn compile_module_entry(
             local_id_to_name: HashMap::new(),
             imported_vars: &cross_module.imported_vars,
             compile_time_constants: &cross_module.compile_time_constants,
+            app_metadata: &cross_module.app_metadata,
             scalar_replaced: std::collections::HashMap::new(),
             scalar_replaced_arrays: std::collections::HashMap::new(),
             scalar_ctor_target: Vec::new(),
@@ -4219,6 +4247,7 @@ fn compile_module_entry(
             local_id_to_name: HashMap::new(),
             imported_vars: &cross_module.imported_vars,
             compile_time_constants: &cross_module.compile_time_constants,
+            app_metadata: &cross_module.app_metadata,
             scalar_replaced: std::collections::HashMap::new(),
             scalar_replaced_arrays: std::collections::HashMap::new(),
             scalar_ctor_target: Vec::new(),
@@ -4928,6 +4957,7 @@ fn compile_static_method(
         local_id_to_name: HashMap::new(),
         imported_vars: &cross_module.imported_vars,
         compile_time_constants: &cross_module.compile_time_constants,
+        app_metadata: &cross_module.app_metadata,
         scalar_replaced: std::collections::HashMap::new(),
         scalar_replaced_arrays: std::collections::HashMap::new(),
         scalar_ctor_target: Vec::new(),

crates/perry-codegen/src/expr.rs

@@ -13,6 +13,7 @@ use perry_hir::{BinaryOp, CompareOp, Expr, UnaryOp, UpdateOp};
 use perry_types::Type as HirType;
 
 use crate::block::LlBlock;
+use crate::codegen::AppMetadata;
 use crate::function::LlFunction;
 use crate::lower_call::{lower_call, lower_native_method_call, lower_new};
 use crate::lower_conditional::{lower_conditional, lower_logical, lower_truthy};
@@ -556,6 +557,8 @@ pub(crate) struct FnCtx<'a> {
     /// may reference extern FFI functions that don't exist on the current
     /// target (e.g., iOS-only `hone_get_documents_dir` on macOS).
     pub compile_time_constants: &'a std::collections::HashMap<u32, f64>,
+    /// App metadata backing compile-time `perry/system` introspection APIs.
+    pub app_metadata: &'a AppMetadata,
 
     /// Scalar-replaced non-escaping objects. When `let p = new Point(x, y)`
     /// and `p` never escapes, instead of heap-allocating, each field gets a

crates/perry-codegen/src/lib.rs

@@ -25,7 +25,9 @@ pub mod stubs;
 pub(crate) mod type_analysis;
 pub mod types;
 
-pub use codegen::{compile_module, resolve_target_triple, CompileOptions, ImportedClass};
+pub use codegen::{
+    compile_module, resolve_target_triple, AppMetadata, CompileOptions, ImportedClass,
+};
 
 /// One row of the native-module dispatch table, projected to just
 /// the manifest-relevant fields (module / method / has_receiver /

crates/perry-codegen/src/lower_call.rs

@@ -817,6 +817,21 @@ pub(crate) fn lower_call(ctx: &mut FnCtx<'_>, callee: &Expr, args: &[Expr]) -> R
                 ctx.block().call_void("js_gc_collect", &[]);
                 return Ok(double_literal(f64::from_bits(crate::nanbox::TAG_UNDEFINED)));
             }
+            "getAppVersion" if args.is_empty() => {
+                let version = ctx.app_metadata.version.clone();
+                let idx = ctx.strings.intern(&version);
+                let handle_global = format!("@{}", ctx.strings.entry(idx).handle_global);
+                return Ok(ctx.block().load(DOUBLE, &handle_global));
+            }
+            "getAppBuildNumber" if args.is_empty() => {
+                return Ok(double_literal(ctx.app_metadata.build_number as f64));
+            }
+            "getBundleId" if args.is_empty() => {
+                let bundle_id = ctx.app_metadata.bundle_id.clone();
+                let idx = ctx.strings.intern(&bundle_id);
+                let handle_global = format!("@{}", ctx.strings.entry(idx).handle_global);
+                return Ok(ctx.block().load(DOUBLE, &handle_global));
+            }
             // JSX runtime calls: `jsx(type, props)` and `jsxs(type, props)`.
             // The HIR lowers <div>…</div> to ExternFuncRef { name: "jsx" } and
             // <div><a/><b/></div> (multiple children) to "jsxs".  The first arg

crates/perry-codegen/src/lower_call/native.rs

@@ -1057,6 +1057,26 @@ pub(crate) fn lower_native_method_call(
         if method == "notificationSchedule" {
             return lower_notification_schedule(ctx, args);
         }
+        if args.is_empty() {
+            match method {
+                "getAppVersion" => {
+                    let version = ctx.app_metadata.version.clone();
+                    let idx = ctx.strings.intern(&version);
+                    let handle_global = format!("@{}", ctx.strings.entry(idx).handle_global);
+                    return Ok(ctx.block().load(DOUBLE, &handle_global));
+                }
+                "getAppBuildNumber" => {
+                    return Ok(double_literal(ctx.app_metadata.build_number as f64));
+                }
+                "getBundleId" => {
+                    let bundle_id = ctx.app_metadata.bundle_id.clone();
+                    let idx = ctx.strings.intern(&bundle_id);
+                    let handle_global = format!("@{}", ctx.strings.entry(idx).handle_global);
+                    return Ok(ctx.block().load(DOUBLE, &handle_global));
+                }
+                _ => {}
+            }
+        }
         if let Some(sig) = perry_system_table_lookup(method) {
             return lower_perry_ui_table_call(ctx, sig, args);
         }

crates/perry-dispatch/src/lib.rs

@@ -2228,6 +2228,24 @@ pub static PERRY_SYSTEM_TABLE: &[MethodRow] = &[
         args: &[],
         ret: ReturnKind::Str,
     },
+    MethodRow {
+        method: "getAppVersion",
+        runtime: "perry_system_get_app_version",
+        args: &[],
+        ret: ReturnKind::Str,
+    },
+    MethodRow {
+        method: "getAppBuildNumber",
+        runtime: "perry_system_get_app_build_number",
+        args: &[],
+        ret: ReturnKind::F64,
+    },
+    MethodRow {
+        method: "getBundleId",
+        runtime: "perry_system_get_bundle_id",
+        args: &[],
+        ret: ReturnKind::Str,
+    },
     MethodRow {
         method: "getAppIcon",
         runtime: "perry_system_get_app_icon",