akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/packages/cli/src/lib/acl.ts

@@ -0,0 +1,420 @@
+
+
+import type { AclGrant, Platform, ResolvedAcl } from "../../../core/src/index.ts";
+import type { Capability, CapabilityPermission } from "../config.ts";
+import { CliError } from "./log.ts";
+import type { PluginManifest, ResolvedPlugin } from "./project.ts";
+
+export type { Capability, CapabilityPermission } from "../config.ts";
+
+export interface PermissionSet {
+  description?: string;
+  /** Local identifiers: allow-*, allow-listen-*, other set names, "all". */
+  permissions: string[];
+}
+
+const PLATFORMS: readonly Platform[] = ["web", "macos", "windows", "linux", "ios", "android"];
+const CORE = "core";
+const CORE_ITEMS = ["print"];
+const NAME = /^[a-z][a-z0-9-]*$/;
+
+type Expanded = { kind: "allow"; items: "*" | string[] } | { kind: "deny"; items: string[] };
+
+/**
+ * Every item of a plugin: its methods and `listen:<event>` subscriptions. boot.json names them
+ * instead of "*" (architecture review 2026-09-26), so a host never grants a name the manifest does
+ * not declare, whatever a module implements.
+ */
+function everything(manifest: PluginManifest): string[] {
+  return [...manifest.methods, ...(manifest.events ?? []).map((e) => `listen:${e}`)];
+}
+
+/** One local identifier of a plugin (without "<plugin>:"), or an error message. */
+function expandLocal(manifest: PluginManifest, name: string, stack: string[] = []): Expanded | string {
+  const id = manifest.id;
+  const events = manifest.events ?? [];
+  if (name === "all") return { kind: "allow", items: everything(manifest) };
+  if (name === "default") {
+    if (!manifest.defaultPermissions) return { kind: "allow", items: everything(manifest) };
+    return union(manifest, manifest.defaultPermissions, [...stack, "default"]);
+  }
+  for (const kind of ["allow", "deny"] as const) {
+    if (name.startsWith(`${kind}-listen-`)) {
+      const event = name.slice(`${kind}-listen-`.length);
+      if (!events.includes(event)) return `${id}:${name}: ${id} has no event "${event}"${hint(event, events)}`;
+      return { kind, items: [`listen:${event}`] };
+    }
+    if (name.startsWith(`${kind}-`)) {
+      const method = name.slice(kind.length + 1);
+      if (!manifest.methods.includes(method))
+        return `${id}:${name}: ${id} has no method "${method}"${hint(method, manifest.methods)}`;
+      return { kind, items: [method] };
+    }
+  }
+  const set = manifest.permissionSets?.[name];
+  if (set) {
+    if (stack.includes(name))
+      return `${id}: permission set "${name}" includes itself (${[...stack, name].join(" → ")})`;
+    return union(manifest, set.permissions, [...stack, name]);
+  }
+  return `unknown permission ${id}:${name}${hint(name, knownLocal(manifest))}`;
+}
+
+function union(manifest: PluginManifest, names: string[], stack: string[]): Expanded | string {
+  let items: "*" | Set<string> = new Set();
+  for (const name of names) {
+    const one = expandLocal(manifest, name, stack);
+    if (typeof one === "string") return one;
+    if (one.kind === "deny") return `${manifest.id}: "${name}" denies; sets and defaultPermissions may only allow`;
+    if (one.items === "*") items = "*";
+    else if (items !== "*") for (const item of one.items) items.add(item);
+  }
+  return { kind: "allow", items: items === "*" ? "*" : [...items] };
+}
+
+function knownLocal(manifest: PluginManifest): string[] {
+  const events = manifest.events ?? [];
+  return [
+    "default",
+    "all",
+    ...manifest.methods.flatMap((m) => [`allow-${m}`, `deny-${m}`]),
+    ...events.flatMap((e) => [`allow-listen-${e}`, `deny-listen-${e}`]),
+    ...Object.keys(manifest.permissionSets ?? {}),
+  ];
+}
+
+/** Problems in a plugin manifest's permission fields (checked when the plugin is loaded). */
+export function manifestPermissionProblems(manifest: PluginManifest): string[] {
+  const problems: string[] = [];
+  const id = manifest.id;
+  if (manifest.defaultPermissions !== undefined) {
+    if (
+      !Array.isArray(manifest.defaultPermissions) ||
+      !manifest.defaultPermissions.every((p) => typeof p === "string")
+    ) {
+      problems.push(`${id}: defaultPermissions must be an array of permission names`);
+    }
+  }
+  const sets = manifest.permissionSets;
+  if (sets !== undefined) {
+    if (!sets || typeof sets !== "object" || Array.isArray(sets))
+      problems.push(`${id}: permissionSets must be an object`);
+    else {
+      for (const [name, set] of Object.entries(sets)) {
+        if (
+          !NAME.test(name) ||
+          name === "default" ||
+          name === "all" ||
+          name.startsWith("allow-") ||
+          name.startsWith("deny-")
+        ) {
+          problems.push(`${id}: invalid permission set name "${name}" (lowercase, not default/all/allow-*/deny-*)`);
+        } else if (!set || !Array.isArray(set.permissions) || !set.permissions.every((p) => typeof p === "string")) {
+          problems.push(`${id}: permissionSets.${name}.permissions must be an array of permission names`);
+        }
+      }
+    }
+  }
+  const scope = manifest.scope;
+  if (
+    scope !== undefined &&
+    (!scope ||
+      typeof scope !== "object" ||
+      !scope.fields ||
+      typeof scope.fields !== "object" ||
+      Object.keys(scope.fields).length === 0)
+  ) {
+    problems.push(`${id}: scope must be { fields: { <name>: "<description>" } }`);
+  } else if (scope) {
+    for (const key of ["urlFields", "pathFields"] as const) {
+      const list = scope[key];
+      if (list !== undefined && (!Array.isArray(list) || list.some((f) => !Object.hasOwn(scope.fields, f))))
+        problems.push(`${id}: scope.${key} must list fields of scope.fields`);
+    }
+    
+    if (Object.hasOwn(scope.fields, "url") && !scope.urlFields?.includes("url"))
+      problems.push(`${id}: scope field "url" must be listed in scope.urlFields (URL patterns)`);
+  }
+  const defaults = manifest.defaultScope;
+  if (defaults !== undefined) {
+    if (!defaults || typeof defaults !== "object" || Array.isArray(defaults))
+      problems.push(`${id}: defaultScope must be { allow?, deny? }`);
+    else
+      problems.push(
+        ...scopeProblems(`${id}: defaultScope.allow`, defaults.allow, manifest),
+        ...scopeProblems(`${id}: defaultScope.deny`, defaults.deny, manifest),
+      );
+  }
+  if (problems.length === 0) {
+    for (const name of [...(manifest.defaultPermissions ?? []), ...Object.keys(sets ?? {})]) {
+      const one = expandLocal(manifest, name);
+      if (typeof one === "string") problems.push(one);
+      else if (one.kind === "deny") problems.push(`${id}: defaultPermissions may only allow (got ${name})`);
+    }
+  }
+  return problems;
+}
+
+function scopeProblems(where: string, entries: unknown, manifest: PluginManifest | null): string[] {
+  if (entries === undefined) return [];
+  if (!manifest) return [`${where}: core permissions take no scopes`];
+  if (!manifest.scope) return [`${where}: plugin ${manifest.id} takes no scopes`];
+  if (!Array.isArray(entries)) return [`${where} must be an array of scope entries`];
+  const fields = Object.keys(manifest.scope.fields);
+  const problems: string[] = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      problems.push(`${where}: a scope entry must be an object like { ${fields[0]}: "…" }`);
+      continue;
+    }
+    for (const [field, value] of Object.entries(entry)) {
+      if (!fields.includes(field))
+        problems.push(`${where}: ${manifest.id} scopes have no field "${field}" (fields: ${fields.join(", ")})`);
+      else if (typeof value !== "string") problems.push(`${where}: scope field ${field} must be a string (glob)`);
+      else problems.push(...patternProblems(where, field, value, manifest));
+    }
+  }
+  return problems;
+}
+
+/**
+ * Checks the app's capabilities against the registered plugins and resolves them for one platform.
+ * Throws a CliError listing every problem.
+ */
+export function resolveAcl(
+  capabilities: Capability[] | undefined,
+  plugins: ResolvedPlugin[],
+  platform: Platform,
+): ResolvedAcl {
+  const byId = new Map(plugins.map((p) => [p.manifest.id, p.manifest]));
+  const grants: AclGrant[] = [];
+  const denied = new Map<string, Set<string>>();
+  const problems: string[] = [];
+
+  if (capabilities === undefined) {
+    for (const { manifest } of plugins) {
+      const expanded = expandLocal(manifest, "default");
+      if (typeof expanded === "string") problems.push(expanded);
+      else grants.push({ plugin: manifest.id, windows: "*", items: expanded.items, ...defaultScope(manifest, {}) });
+    }
+  } else if (!Array.isArray(capabilities)) {
+    problems.push("capabilities must be an array");
+  } else {
+    const seen = new Set<string>();
+    for (const [index, capability] of capabilities.entries()) {
+      const at = `capabilities[${index}]`;
+      if (!capability || typeof capability !== "object") {
+        problems.push(`${at} must be an object`);
+        continue;
+      }
+      const name = capability.identifier;
+      if (typeof name !== "string" || !NAME.test(name))
+        problems.push(`${at}.identifier must be lowercase letters, digits and "-" (got ${JSON.stringify(name)})`);
+      else if (seen.has(name)) problems.push(`capability "${name}" is defined twice`);
+      else seen.add(name);
+      const label = typeof name === "string" ? `capability "${name}"` : at;
+
+      let windows: "*" | number[] = "*";
+      if (capability.windows !== undefined) {
+        if (!Array.isArray(capability.windows) || capability.windows.length === 0)
+          problems.push(`${label}: windows must be a non-empty array`);
+        else {
+          const ids = new Set<number>();
+          for (const w of capability.windows) {
+            if (w === "*") windows = "*";
+            else if (w === "main") ids.add(1);
+            else if (typeof w === "number" && Number.isInteger(w) && w > 0) ids.add(w);
+            else problems.push(`${label}: windows entries are "main", "*" or window ids (got ${JSON.stringify(w)})`);
+          }
+          if (!capability.windows.includes("*")) windows = [...ids].sort((a, b) => a - b);
+        }
+      }
+      if (capability.platforms !== undefined) {
+        if (!Array.isArray(capability.platforms) || capability.platforms.some((p) => !PLATFORMS.includes(p))) {
+          problems.push(`${label}: platforms must list ${PLATFORMS.join(", ")}`);
+        }
+      }
+      const applies = !Array.isArray(capability.platforms) || capability.platforms.includes(platform);
+      if (!Array.isArray(capability.permissions)) {
+        problems.push(`${label}: permissions must be an array`);
+        continue;
+      }
+      for (const permission of capability.permissions) {
+        const entry: CapabilityPermission | null =
+          typeof permission === "string"
+            ? { identifier: permission }
+            : permission && typeof permission === "object"
+              ? permission
+              : null;
+        if (!entry || typeof entry.identifier !== "string") {
+          problems.push(
+            `${label}: a permission is "<plugin>:<name>" or { identifier, allow?, deny? } (got ${JSON.stringify(permission)})`,
+          );
+          continue;
+        }
+        const colon = entry.identifier.indexOf(":");
+        const pluginId = colon > 0 ? entry.identifier.slice(0, colon) : "";
+        const local = colon > 0 ? entry.identifier.slice(colon + 1) : "";
+        const where = `${label}: ${entry.identifier}`;
+        let expanded: Expanded | string;
+        let manifest: PluginManifest | null = null;
+        if (pluginId === CORE) {
+          expanded =
+            local === "default" || local === "allow-print"
+              ? { kind: "allow", items: CORE_ITEMS }
+              : local === "deny-print"
+                ? { kind: "deny", items: ["print"] }
+                : `unknown permission ${entry.identifier}${hint(local, ["default", "allow-print", "deny-print"])}`;
+        } else if (!byId.has(pluginId)) {
+          expanded = pluginId
+            ? `${where}: plugin "${pluginId}" is not in the app's plugins${hint(pluginId, [...byId.keys(), CORE])}`
+            : `${where}: expected "<plugin>:<name>"`;
+        } else {
+          manifest = byId.get(pluginId)!;
+          expanded = expandLocal(manifest, local);
+        }
+        if (typeof expanded === "string") {
+          problems.push(expanded.startsWith(label) ? expanded : `${label}: ${expanded}`);
+          continue;
+        }
+        if (expanded.kind === "deny") {
+          if (entry.allow !== undefined || entry.deny !== undefined)
+            problems.push(`${where}: deny permissions take no scopes (put deny scopes on the allowing permission)`);
+          if (applies) {
+            const set = denied.get(pluginId) ?? new Set<string>();
+            for (const item of expanded.items) set.add(item);
+            denied.set(pluginId, set);
+          }
+          continue;
+        }
+        const scopeIssues = [
+          ...scopeProblems(`${where} allow`, entry.allow, manifest),
+          ...scopeProblems(`${where} deny`, entry.deny, manifest),
+        ];
+        problems.push(...scopeIssues);
+        if (!applies || scopeIssues.length) continue;
+        const scopes =
+          local === "default" && manifest ? defaultScope(manifest, entry) : { allow: entry.allow, deny: entry.deny };
+        grants.push({
+          plugin: pluginId,
+          windows,
+          items: expanded.items,
+          ...(scopes.allow ? { allow: scopes.allow } : {}),
+          ...(scopes.deny ? { deny: scopes.deny } : {}),
+        });
+      }
+    }
+  }
+  if (problems.length) throw new CliError(`invalid capabilities:\n  - ${problems.join("\n  - ")}`);
+  
+  grants.push({ plugin: CORE, windows: "*", items: CORE_ITEMS });
+  const acl: ResolvedAcl = { grants };
+  if (denied.size) acl.denied = Object.fromEntries([...denied].map(([plugin, items]) => [plugin, [...items].sort()]));
+  return acl;
+}
+
+/** The scopes of a `<plugin>:default` grant: the capability's allow, else the manifest's; both denies. */
+/**
+ * Patterns written in the syntax before the 2026-09-26 architecture review, with the fix: URL
+ * patterns name their scheme (one without matches nothing now), and path patterns are relative
+ * with "/" separators and no "..".
+ */
+function patternProblems(where: string, field: string, value: string, manifest: PluginManifest): string[] {
+  if (manifest.scope?.urlFields?.includes(field)) {
+    if (!/^\**$/.test(value) && !/^[A-Za-z*][A-Za-z0-9+.*-]*:/.test(value)) {
+      return [
+        `${where}: ${field} "${value}" names no scheme, so it matches nothing; write "https://${value}" (or "*://${value}")`,
+      ];
+    }
+  }
+  if (manifest.scope?.pathFields?.includes(field)) {
+    if (value.startsWith("/"))
+      return [`${where}: ${field} "${value}" is relative to its base: write "${value.replace(/^\/+/, "")}"`];
+    if (value.includes("\\"))
+      return [`${where}: ${field} "${value}" uses "/" as separator: write "${value.replaceAll("\\", "/")}"`];
+    if (value.split("/").includes(".."))
+      return [`${where}: ${field} "${value}" cannot contain ".." (paths never leave their base)`];
+  }
+  return [];
+}
+
+/**
+ * Scopes that build but likely do not say what the app meant. A URL deny written for https:// only
+ * leaves the same host open over http:// (and a URL field matches the scheme exactly).
+ */
+export function aclWarnings(acl: ResolvedAcl, plugins: ResolvedPlugin[]): string[] {
+  const warnings = new Set<string>();
+  for (const grant of acl.grants) {
+    const urlFields = plugins.find((p) => p.manifest.id === grant.plugin)?.manifest.scope?.urlFields ?? [];
+    
+    for (const entry of grant.allow ?? []) {
+      for (const field of urlFields) {
+        const m =
+          entry[field] === undefined
+            ? null
+            : /^([a-z*]+):\/\/(localhost|127\.0\.0\.1|\[::1\])(\/.*)?$/i.exec(entry[field]!);
+        if (m)
+          warnings.add(
+            `${grant.plugin}: the allow scope ${field} "${entry[field]}" has no port, so only the default port; write "${m[1]}://${m[2]}:*${m[3] ?? "/*"}" for any port`,
+          );
+      }
+    }
+    for (const entry of grant.deny ?? []) {
+      for (const field of urlFields) {
+        const pattern = entry[field];
+        const m = pattern === undefined ? null : /^https:(\/\/.*)$/i.exec(pattern);
+        if (!m) continue;
+        const covered = (grant.deny ?? []).some(
+          (other) =>
+            other[field] !== undefined &&
+            /^(http|\*|http\*):/i.test(other[field]!) &&
+            other[field]!.slice(other[field]!.indexOf(":")) === `:${m[1]}`,
+        );
+        if (!covered)
+          warnings.add(
+            `${grant.plugin}: the deny scope ${field} "${pattern}" only covers https://; write "*:${m[1]}" to deny every scheme`,
+          );
+      }
+    }
+  }
+  return [...warnings];
+}
+
+function defaultScope(
+  manifest: PluginManifest,
+  entry: { allow?: Record<string, string>[]; deny?: Record<string, string>[] },
+): Pick<AclGrant, "allow" | "deny"> {
+  const allow = entry.allow ?? manifest.defaultScope?.allow;
+  const deny = [...(manifest.defaultScope?.deny ?? []), ...(entry.deny ?? [])];
+  return { ...(allow ? { allow } : {}), ...(deny.length ? { deny } : {}) };
+}
+
+function hint(name: string, known: string[]): string {
+  const lower = name.toLowerCase();
+  const prefixed =
+    lower.length >= 3
+      ? known.filter((k) => k.toLowerCase().startsWith(lower)).sort((a, b) => a.length - b.length)[0]
+      : undefined;
+  if (prefixed) return ` (did you mean "${prefixed}"?)`;
+  let best = "";
+  let bestDistance = Infinity;
+  for (const candidate of known) {
+    const d = distance(name.toLowerCase(), candidate.toLowerCase());
+    if (d < bestDistance) [best, bestDistance] = [candidate, d];
+  }
+  return best && bestDistance <= Math.max(2, Math.floor(name.length / 3)) ? ` (did you mean "${best}"?)` : "";
+}
+
+function distance(a: string, b: string): number {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0]!;
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const current = row[j]!;
+      row[j] = Math.min(row[j]! + 1, row[j - 1]! + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = current;
+    }
+  }
+  return row[b.length]!;
+}

package/vendor/@akanjs/native/packages/cli/src/lib/apilevel.ts

@@ -0,0 +1,245 @@
+
+
+import { existsSync, readFileSync } from "node:fs";
+import { inflateRawSync } from "node:zlib";
+import { readZip } from "./apk.ts";
+
+export interface ApiClass {
+  since: number;
+  supers: string[];
+  members: Map<string, number>;
+}
+export type ApiVersions = Map<string, ApiClass>;
+
+const parsed = new Map<string, ApiVersions>();
+
+/** Reads api-versions.xml (one element per line, as the SDK ships it). */
+export function loadApiVersions(path: string): ApiVersions {
+  const cached = parsed.get(path);
+  if (cached) return cached;
+  const api: ApiVersions = new Map();
+  let current: ApiClass | null = null;
+  
+  const since = (tag: string) => /\ssince="(\d+)"/.exec(tag)?.[1];
+  const name = (tag: string) => /\sname="([^"]+)"/.exec(tag)![1]!.replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (line.startsWith("\t<class ")) {
+      current = { since: Number(since(line) ?? 1), supers: [], members: new Map() };
+      api.set(name(line), current);
+      continue;
+    }
+    if (line.startsWith("\t</class>")) {
+      current = null;
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith("\t\t<extends ") || line.startsWith("\t\t<implements ")) {
+      if (!/\sremoved="/.test(line)) current.supers.push(name(line));
+    } else if (line.startsWith("\t\t<method ") || line.startsWith("\t\t<field ")) {
+      const added = since(line);
+      current.members.set(name(line), added ? Number(added) : current.since);
+    }
+  }
+  parsed.set(path, api);
+  return api;
+}
+
+export interface ClassInfo {
+  name: string;
+  superName: string | null;
+  interfaces: string[];
+  /** Classes named in the constant pool (array types stripped). */
+  classes: string[];
+  /** Field and method references: owner, name, descriptor. */
+  members: { owner: string; name: string; descriptor: string; field: boolean }[];
+  /** Interfaces an invokedynamic call site produces (lambdas turned into framework interfaces). */
+  lambdaTypes: string[];
+}
+
+/** The parts of a class file this check needs: the constant pool, this class, its supertypes. */
+export function readClass(bytes: Uint8Array): ClassInfo {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(0) !== 0xcafebabe) throw new Error("not a class file");
+  const count = view.getUint16(8);
+  const utf8: (string | undefined)[] = [];
+  const refs: { tag: number; a: number; b: number }[] = [];
+  let p = 10;
+  const decoder = new TextDecoder();
+  for (let i = 1; i < count; i++) {
+    const tag = bytes[p]!;
+    switch (tag) {
+      case 1: {
+        const length = view.getUint16(p + 1);
+        utf8[i] = decoder.decode(bytes.subarray(p + 3, p + 3 + length)); 
+        p += 3 + length;
+        break;
+      }
+      case 3:
+      case 4:
+        p += 5;
+        break;
+      case 5:
+      case 6:
+        p += 9;
+        i++;
+        break; 
+      case 7:
+      case 8:
+      case 16:
+      case 19:
+      case 20:
+        refs[i] = { tag, a: view.getUint16(p + 1), b: 0 };
+        p += 3;
+        break;
+      case 9:
+      case 10:
+      case 11:
+      case 12:
+      case 17:
+      case 18:
+        refs[i] = { tag, a: view.getUint16(p + 1), b: view.getUint16(p + 3) };
+        p += 5;
+        break;
+      case 15:
+        refs[i] = { tag, a: bytes[p + 1]!, b: view.getUint16(p + 2) };
+        p += 4;
+        break;
+      default:
+        throw new Error(`constant pool tag ${tag} at ${p}`);
+    }
+  }
+  const className = (index: number) => utf8[refs[index]!.a]!;
+  const stripArray = (name: string) => name.replace(/^\[+L?/, "").replace(/;$/, "");
+  const info: ClassInfo = { name: "", superName: null, interfaces: [], classes: [], members: [], lambdaTypes: [] };
+  refs.forEach((ref, index) => {
+    if (!ref) return;
+    if (ref.tag === 7) {
+      const name = stripArray(className(index));
+      if (name.includes("/")) info.classes.push(name);
+    } else if (ref.tag === 9 || ref.tag === 10 || ref.tag === 11) {
+      const nat = refs[ref.b]!;
+      info.members.push({
+        owner: stripArray(className(ref.a)),
+        name: utf8[nat.a]!,
+        descriptor: utf8[nat.b]!,
+        field: ref.tag === 9,
+      });
+    } else if (ref.tag === 18) {
+      const descriptor = utf8[refs[ref.b]!.b]!;
+      const produced = /\)L([^;]+);$/.exec(descriptor);
+      if (produced) info.lambdaTypes.push(produced[1]!);
+    }
+  });
+  info.name = className(view.getUint16(p + 2));
+  const superIndex = view.getUint16(p + 4);
+  info.superName = superIndex ? className(superIndex) : null;
+  const interfaces = view.getUint16(p + 6);
+  for (let i = 0; i < interfaces; i++) info.interfaces.push(className(view.getUint16(p + 8 + i * 2)));
+  return info;
+}
+
+/** The API level a class may use: minSdk, a plugin package's minSdk, or N for an `ApiN` class. */
+export function allowedLevel(
+  className: string,
+  minSdk: number,
+  packageLevels: [prefix: string, level: number][] = [],
+): number {
+  let level = minSdk;
+  for (const [prefix, packageLevel] of packageLevels)
+    if (className.startsWith(prefix)) level = Math.max(level, packageLevel);
+  const simple = className.slice(className.lastIndexOf("/") + 1);
+  for (const part of simple.split("$")) {
+    const m = /Api(\d+)$/.exec(part);
+    if (m) level = Math.max(level, Number(m[1]));
+  }
+  return level;
+}
+
+export interface ApiProblem {
+  className: string;
+  what: string;
+  since: number;
+  allowed: number;
+}
+
+/** Checks every class of a jar. */
+export function checkApiLevels(
+  jar: Uint8Array,
+  api: ApiVersions,
+  minSdk: number,
+  packageLevels: [string, number][] = [],
+): ApiProblem[] {
+  const classes: ClassInfo[] = [];
+  for (const entry of readZip(jar)) {
+    if (!entry.name.endsWith(".class")) continue;
+    const data = entry.method === 8 ? new Uint8Array(inflateRawSync(entry.data)) : entry.data;
+    classes.push(readClass(data));
+  }
+  const own = new Map(classes.map((c) => [c.name, c]));
+
+  /** When `member` of `owner` exists in the framework: the API that added it. */
+  const memberSince = (owner: string, member: string, seen = new Set<string>()): number | undefined => {
+    if (seen.has(owner)) return undefined;
+    seen.add(owner);
+    const framework = api.get(owner);
+    if (framework) {
+      const since = framework.members.get(member);
+      if (since !== undefined) return since;
+      for (const s of framework.supers) {
+        const found = memberSince(s, member, seen);
+        if (found !== undefined) return found;
+      }
+      return undefined;
+    }
+    const app = own.get(owner);
+    if (!app) return undefined;
+    for (const s of [app.superName, ...app.interfaces]) {
+      if (!s) continue;
+      const found = memberSince(s, member, seen);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+
+  const problems: ApiProblem[] = [];
+  for (const c of classes) {
+    const allowed = allowedLevel(c.name, minSdk, packageLevels);
+    const seen = new Set<string>();
+    const report = (what: string, since: number | undefined) => {
+      if (since === undefined || since <= allowed || seen.has(what)) return;
+      seen.add(what);
+      problems.push({ className: c.name, what, since, allowed });
+    };
+    const supertypes = new Set([c.superName, ...c.interfaces]);
+    for (const s of supertypes) if (s) report(`supertype ${s}`, api.get(s)?.since);
+    for (const name of c.classes) if (!supertypes.has(name)) report(`class ${name}`, api.get(name)?.since);
+    for (const name of c.lambdaTypes) report(`lambda type ${name}`, api.get(name)?.since);
+    for (const m of c.members) {
+      const key = m.field ? m.name : `${m.name}${m.descriptor}`;
+      report(`${m.field ? "field" : "method"} ${m.owner}.${key}`, memberSince(m.owner, key));
+    }
+  }
+  return problems;
+}
+
+/** One line per problem, grouped by class, for a build error. */
+export function formatApiProblems(problems: ApiProblem[], minSdk: number): string {
+  const lines = problems
+    .slice(0, 30)
+    .map(
+      (p) =>
+        `  ${p.className.replace(/\//g, ".")}: ${p.what} needs API ${p.since} (this class may use up to ${p.allowed})`,
+    );
+  if (problems.length > 30) lines.push(`  … and ${problems.length - 30} more`);
+  return [
+    `framework APIs above the app's minSdk ${minSdk}:`,
+    ...lines,
+    `Move each into a class or nested object named ApiN (N = the API it needs) and call it only when Build.VERSION.SDK_INT >= N.`,
+  ].join("\n");
+}
+
+/** api-versions.xml of the SDK platform that android.jar belongs to, when the SDK has it. */
+export function apiVersionsFor(androidJar: string): string | null {
+  const path = androidJar.replace(/android\.jar$/, "data/api-versions.xml");
+  return existsSync(path) ? path : null;
+}