@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.1

package/cli/doctor/checks/icons.js

@@ -0,0 +1,69 @@
+// @ts-check
+'use strict';
+
+const { readConfig } = require('../../config');
+const { readColorHash } = require('../../icons/android');
+const { readIconSet } = require('../../icons/ios');
+const { iconsHash, resolveIconSettings } = require('../../icons/settings');
+
+/** @typedef {import('../types').Check} Check */
+/** @typedef {import('../../project').Project} Project */
+
+const ICONS = { label: 'npx apex-navigation icons', run: /** @type {const} */ ('icons') };
+
+/**
+ * The app icon: made from its settings in package.json on both platforms; without settings, an iOS icon set with no
+ * image, which the App Store refuses.
+ * @param {string} root
+ * @param {Project} project
+ * @returns {Check[]}
+ */
+function iconChecks(root, project) {
+  const saved = readConfig(root).icons;
+  const set = readIconSet(project);
+  if (!saved) {
+    if (set && set.images === 0) {
+      return [
+        {
+          group: 'app',
+          title: 'App icon',
+          status: 'warn',
+          detail: 'the iOS icon set has no image: the App Store refuses the app',
+          fix: { label: 'npx apex-navigation icons --logo assets/logo.png --background "#FFFFFF"' },
+        },
+      ];
+    }
+    return [];
+  }
+  const resolved = resolveIconSettings(root, {}, saved);
+  if ('errors' in resolved) {
+    return [
+      {
+        group: 'app',
+        title: 'App icon',
+        status: 'warn',
+        detail: resolved.errors[0],
+        fix: { label: 'npx apex-navigation icons' },
+      },
+    ];
+  }
+  const hash = iconsHash(root, resolved.settings);
+  const stale = [
+    ...(project.infoPlist && set?.hash !== hash ? ['iOS'] : []),
+    ...(project.manifest && readColorHash(project) !== hash ? ['Android'] : []),
+  ];
+  if (stale.length === 0) {
+    return [{ group: 'app', title: 'App icon', status: 'ok', detail: 'made from its settings' }];
+  }
+  return [
+    {
+      group: 'app',
+      title: 'App icon',
+      status: 'warn',
+      detail: `${stale.join(' and ')}: not made from the settings in package.json`,
+      fix: ICONS,
+    },
+  ];
+}
+
+module.exports = { iconChecks };

package/cli/doctor/checks/ios.js

@@ -0,0 +1,187 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { PACKAGE, installedVersion, packageDir } = require('../../app');
+
+/** @typedef {import('../types').Check} Check */
+/** @typedef {import('../types').Context} Context */
+
+const PODS = { label: 'cd ios && pod install', run: /** @type {const} */ ('pods') };
+
+// The oldest Xcode with the iOS SDK the navigation builds with.
+const MIN_XCODE = 26;
+
+/**
+ * Xcode, CocoaPods, the pods of the installed navigation, and the oldest iOS the app runs on. macOS only.
+ * @param {Context} context
+ * @returns {Check[]}
+ */
+function iosChecks(context) {
+  if (context.platform !== 'darwin') return [];
+  const ios = path.join(context.root, 'ios');
+  const podfile = read(path.join(ios, 'Podfile'));
+  if (podfile === undefined) {
+    return [{ group: 'ios', title: 'iOS project', status: 'info', detail: 'none in ios/' }];
+  }
+  return [
+    xcodeCheck(context),
+    cocoaPodsCheck(context),
+    podsCheck(context.root, ios),
+    deploymentTargetCheck(context.root, podfile),
+  ];
+}
+
+/**
+ * @param {Context} context
+ * @returns {Check}
+ */
+function xcodeCheck({ run }) {
+  const result = run('xcodebuild', ['-version']);
+  if (!result.ok) {
+    return {
+      group: 'ios',
+      title: 'Xcode',
+      status: 'error',
+      detail: 'not found',
+      fix: { label: 'Install Xcode, then: sudo xcode-select -s /Applications/Xcode.app' },
+    };
+  }
+  const version = result.stdout.split('\n')[0].replace(/^Xcode\s*/, '');
+  // The navigation uses the iOS 26 SDK (Liquid Glass and the rest): an older Xcode doesn't build it.
+  if (Number(version.split('.')[0]) < MIN_XCODE) {
+    return {
+      group: 'ios',
+      title: 'Xcode',
+      status: 'error',
+      detail: `${version}: the navigation builds with Xcode ${MIN_XCODE} or newer`,
+      fix: { label: `Install Xcode ${MIN_XCODE} or newer` },
+    };
+  }
+  return { group: 'ios', title: 'Xcode', status: 'ok', detail: version };
+}
+
+/**
+ * CocoaPods through Bundler when the app pins it in a Gemfile, as the React Native template does.
+ * @param {Context} context
+ * @returns {Check}
+ */
+function cocoaPodsCheck({ root, run }) {
+  const bundler = fs.existsSync(path.join(root, 'Gemfile'));
+  const result = bundler
+    ? run('bundle', ['exec', 'pod', '--version'], { cwd: root })
+    : run('pod', ['--version'], { cwd: root });
+  if (result.ok)
+    return { group: 'ios', title: 'CocoaPods', status: 'ok', detail: result.stdout.trim() };
+  return {
+    group: 'ios',
+    title: 'CocoaPods',
+    status: 'error',
+    detail: 'not found',
+    fix: { label: bundler ? 'bundle install' : 'gem install cocoapods' },
+  };
+}
+
+/**
+ * The pods are installed, and installed with the navigation the app has now.
+ * @param {string} root
+ * @param {string} ios
+ * @returns {Check}
+ */
+function podsCheck(root, ios) {
+  const lock = read(path.join(ios, 'Podfile.lock'));
+  const manifest = read(path.join(ios, 'Pods', 'Manifest.lock'));
+  if (lock === undefined || manifest === undefined) {
+    return { group: 'ios', title: 'Pods', status: 'error', detail: 'not installed', fix: PODS };
+  }
+  const inPods = /^\s*- ApexNavigation \(([^)]+)\)/m.exec(lock)?.[1];
+  const installed = installedVersion(root, PACKAGE);
+  if (inPods && installed && inPods !== installed) {
+    return {
+      group: 'ios',
+      title: 'Pods out of date',
+      status: 'error',
+      detail: `navigation ${inPods} in Pods, ${installed} installed`,
+      fix: PODS,
+    };
+  }
+  if (lock !== manifest) {
+    return {
+      group: 'ios',
+      title: 'Pods out of date',
+      status: 'error',
+      detail: 'Podfile.lock changed',
+      fix: PODS,
+    };
+  }
+  return {
+    group: 'ios',
+    title: 'Pods',
+    status: 'ok',
+    detail: inPods ? `navigation ${inPods}` : undefined,
+  };
+}
+
+/**
+ * The iOS the Podfile targets is no older than React Native's oldest.
+ * @param {string} root
+ * @param {string} podfile
+ * @returns {Check}
+ */
+function deploymentTargetCheck(root, podfile) {
+  const platform = /^\s*platform\s+:ios\s*,\s*(.+)$/m.exec(podfile)?.[1]?.trim();
+  if (!platform || platform.includes('min_ios_version_supported')) {
+    return { group: 'ios', title: 'iOS version', status: 'ok', detail: "React Native's minimum" };
+  }
+  const version = /['"]([\d.]+)['"]/.exec(platform)?.[1];
+  const minimum = reactNativeMinimumIOS(root);
+  if (version && minimum && compare(version, minimum) < 0) {
+    return {
+      group: 'ios',
+      title: 'iOS version',
+      status: 'error',
+      detail: `${version}: React Native needs ${minimum}`,
+      fix: { label: 'platform :ios, min_ios_version_supported in the Podfile' },
+    };
+  }
+  return { group: 'ios', title: 'iOS version', status: 'ok', detail: version };
+}
+
+/**
+ * The oldest iOS React Native supports, from its CocoaPods scripts.
+ * @param {string} root
+ * @returns {string | undefined}
+ */
+function reactNativeMinimumIOS(root) {
+  const reactNative = packageDir(root, 'react-native');
+  if (!reactNative) return undefined;
+  const helpers = read(path.join(reactNative, 'scripts', 'cocoapods', 'helpers.rb')) ?? '';
+  return /def self\.min_ios_version_supported\s+return\s+'([\d.]+)'/.exec(helpers)?.[1];
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ */
+function compare(a, b) {
+  const [x, y] = [a, b].map((version) => version.split('.').map(Number));
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
+  }
+  return 0;
+}
+
+/**
+ * @param {string} file
+ * @returns {string | undefined}
+ */
+function read(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+module.exports = { iosChecks };

package/cli/doctor/checks/navigation.js

@@ -0,0 +1,285 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readConfig, screensDir } = require('../../config');
+const { planAndroid, planIos } = require('../../links');
+const { declaredLinks } = require('../../links/native');
+const { readLinking } = require('../../links/prefixes');
+const {
+  findConfig,
+  findScreens,
+  keysOf,
+  propertyValue,
+  resolveImport,
+} = require('../../typescript');
+const { openWorkspace } = require('../../workspace');
+
+/** @typedef {import('../types').Check} Check */
+/** @typedef {import('../types').Context} Context */
+/** @typedef {import('../../workspace').Workspace} Workspace */
+
+const LINKS = { label: 'npx apex-navigation links', run: /** @type {const} */ ('links') };
+// Folders of an app that hold no code of its own.
+const SKIP = new Set([
+  'node_modules',
+  'ios',
+  'android',
+  'build',
+  'Pods',
+  '.git',
+  'vendor',
+  'coverage',
+]);
+const SOURCE = /\.(tsx?|jsx?)$/;
+// The commands that name a screen first.
+const COMMANDS = ['push', 'replace', 'showModal', 'showInColumn'];
+// At most this many places are listed in a check.
+const LISTED = 5;
+
+/**
+ * The navigation of the app, from its code: its screens, its links on the native side, and, in a JavaScript app,
+ * screen names the commands give. None when the CLI can't read the app's code: the App group says why.
+ * @param {Context} context
+ * @returns {Check[]}
+ */
+function navigationChecks({ root, run }) {
+  const workspace = openWorkspace(root, run);
+  if ('code' in workspace) return [];
+  const names = screenNames(workspace);
+  /** @type {Check[]} */
+  const checks = [screensCheck(root, workspace, names)];
+  checks.push(...linksChecks(workspace));
+  if (!fs.existsSync(path.join(root, 'tsconfig.json'))) {
+    const named = screenNamesCheck(root, names.all);
+    if (named) checks.push(named);
+  }
+  return checks;
+}
+
+/**
+ * The names of the screens: those of `screens`, and of each group, with the names given twice.
+ * @param {Workspace} workspace
+ */
+function screenNames({ ts, navigation }) {
+  const screens = findScreens(ts, navigation);
+  /** @type {{ name: string; where: string }[]} */
+  const listed = (screens ? keysOf(ts, { ...screens, node: screens.object }) : []).map((name) => ({
+    name,
+    where: 'screens',
+  }));
+  const groups = findConfig(ts, navigation, 'groups');
+  if (groups) {
+    for (const group of keysOf(ts, groups)) {
+      const value = propertyValue(ts, groups, group);
+      const groupScreens = value && propertyValue(ts, value, 'screens');
+      for (const name of groupScreens ? keysOf(ts, groupScreens) : []) {
+        listed.push({ name, where: `the group ${group}` });
+      }
+    }
+  }
+  const seen = new Map();
+  /** @type {string[]} */
+  const twice = [];
+  for (const { name, where } of listed) {
+    if (seen.has(name)) twice.push(`${name} in ${seen.get(name)} and in ${where}`);
+    else seen.set(name, where);
+  }
+  return { all: new Set(seen.keys()), twice, count: seen.size };
+}
+
+/**
+ * One name per screen, and every screen file in `screens`: a file of the screens' folder with a `defineScreen` or
+ * `nativeScreen` export that no file of the app imports was likely made and never added.
+ * @param {string} root
+ * @param {Workspace} workspace
+ * @param {ReturnType<typeof screenNames>} names
+ * @returns {Check}
+ */
+function screensCheck(root, workspace, names) {
+  if (names.twice.length > 0) {
+    return {
+      group: 'navigation',
+      title: 'Screens',
+      status: 'error',
+      detail: `named twice: ${names.twice.slice(0, LISTED).join('; ')}`,
+      fix: { label: 'Give each screen a name of its own' },
+    };
+  }
+  const dir = path.join(root, screensDir(root, readConfig(root)));
+  const files = sourceFiles(root);
+  const imported = new Set(files.flatMap((file) => importsOf(file)));
+  const unused = sourceFiles(dir)
+    .filter(
+      (file) => !imported.has(file) && /[=]\s*(defineScreen|nativeScreen)\s*\(/.test(read(file))
+    )
+    .map((file) => path.relative(root, file));
+  if (unused.length > 0) {
+    return {
+      group: 'navigation',
+      title: 'Screens',
+      status: 'warn',
+      detail: `not in screens: ${unused.slice(0, LISTED).join(', ')}${unused.length > LISTED ? ` and ${unused.length - LISTED} more` : ''}`,
+      fix: { label: 'Add them to screens of createNavigation, or delete them' },
+    };
+  }
+  return { group: 'navigation', title: 'Screens', status: 'ok', detail: `${names.count}` };
+}
+
+/**
+ * The links of `linking` on the native side: each prefix declared on both platforms, the declarations no prefix has,
+ * and an Android activity that takes new links in itself.
+ * @param {Workspace} workspace
+ * @returns {Check[]}
+ */
+function linksChecks({ ts, navigation, project }) {
+  const linking = readLinking(ts, navigation);
+  if ('code' in linking) {
+    return linking.code === 'no-linking'
+      ? []
+      : [{ group: 'navigation', title: 'Links', status: 'info', detail: linking.message }];
+  }
+  const schemes = [
+    ...new Set(linking.prefixes.filter(({ web }) => !web).map(({ scheme }) => scheme)),
+  ];
+  const web = linking.prefixes.filter(({ web: isWeb }) => isWeb);
+  const hosts = [...new Set(web.map(({ host }) => host))];
+  /** @type {string[]} */
+  const singleTask = [];
+  const plans = [
+    ...planIos(project, schemes, hosts),
+    ...planAndroid(project, schemes, web, (message) => singleTask.push(message)),
+  ];
+  const missing = plans.filter(({ status }) => status !== 'done').map(({ name }) => name);
+  /** @type {Check[]} */
+  const checks = [
+    missing.length === 0
+      ? {
+          group: 'navigation',
+          title: 'Links',
+          status: 'ok',
+          detail: linking.prefixes.map(({ text }) => text).join(' · '),
+        }
+      : {
+          group: 'navigation',
+          title: 'Links',
+          status: 'warn',
+          detail: `not declared on the native side: ${missing.join(', ')}`,
+          fix: LINKS,
+        },
+  ];
+  const declared = declaredLinks(project);
+  const extra = [
+    ...declared.schemes
+      .filter((scheme) => !schemes.includes(scheme))
+      .map((scheme) => `${scheme}://`),
+    ...declared.hosts.filter((host) => !hosts.includes(host)),
+  ];
+  if (extra.length > 0) {
+    checks.push({
+      group: 'navigation',
+      title: 'Links',
+      status: 'info',
+      detail: `declared with no prefix in linking: ${[...new Set(extra)].join(', ')}`,
+    });
+  }
+  if (singleTask.length > 0) {
+    checks.push({
+      group: 'navigation',
+      title: 'Links on Android',
+      status: 'warn',
+      detail: "the main activity isn't singleTask: a link starts another copy of it",
+      fix: { label: 'android:launchMode="singleTask" on the main activity of AndroidManifest.xml' },
+    });
+  }
+  return checks;
+}
+
+/**
+ * In a JavaScript app, where no type checks them, the screen names the commands give that aren't screens.
+ * @param {string} root
+ * @param {Set<string>} names
+ * @returns {Check | undefined}
+ */
+function screenNamesCheck(root, names) {
+  // On the navigation only: `navigation.push('…')`, `nav.replace('…')`, not `errors.push('…')`.
+  const call = new RegExp(
+    String.raw`\b(?:navigation|nav|Navigation)\??\.(?:${COMMANDS.join('|')})\(\s*['"]([A-Za-z_$][\w$]*)['"]`,
+    'g'
+  );
+  /** @type {string[]} */
+  const unknown = [];
+  for (const file of sourceFiles(root)) {
+    const text = read(file);
+    for (const found of text.matchAll(call)) {
+      if (names.has(found[1])) continue;
+      const line = text.slice(0, found.index).split('\n').length;
+      unknown.push(`${found[1]} at ${path.relative(root, file)}:${line}`);
+    }
+  }
+  if (unknown.length === 0) return undefined;
+  return {
+    group: 'navigation',
+    title: 'Screen names',
+    status: 'warn',
+    detail: `not screens: ${unknown.slice(0, LISTED).join(', ')}${unknown.length > LISTED ? ` and ${unknown.length - LISTED} more` : ''}`,
+    fix: { label: 'Use a name of screens, or add the screen' },
+  };
+}
+
+/**
+ * The files of the app's own code under a folder.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function sourceFiles(dir) {
+  /** @type {string[]} */
+  const files = [];
+  /** @type {fs.Dirent[]} */
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || SKIP.has(entry.name) || entry.name === '__tests__') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...sourceFiles(full));
+    else if (SOURCE.test(entry.name) && !entry.name.endsWith('.d.ts')) files.push(full);
+  }
+  return files;
+}
+
+/**
+ * The files of the app a file imports: `import … from`, `export … from`, `import()` and `require()` of relative
+ * paths.
+ * @param {string} file
+ * @returns {string[]}
+ */
+function importsOf(file) {
+  const text = read(file);
+  const specifiers = [
+    ...text.matchAll(/\bfrom\s*['"](\.[^'"]+)['"]/g),
+    ...text.matchAll(/\b(?:import|require)\(\s*['"](\.[^'"]+)['"]\s*\)/g),
+  ].map((found) => found[1]);
+  return specifiers.flatMap((specifier) => {
+    const target = resolveImport(file, specifier);
+    return target ? [target] : [];
+  });
+}
+
+/**
+ * @param {string} file
+ * @returns {string}
+ */
+function read(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+module.exports = { navigationChecks };

package/cli/doctor/checks/splash.js

@@ -0,0 +1,102 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readConfig } = require('../../config');
+const { THEME } = require('../../splash/android');
+const { STORYBOARD } = require('../../splash/ios');
+const { resolveSettings, splashHash } = require('../../splash/settings');
+
+/** @typedef {import('../types').Check} Check */
+/** @typedef {import('../../project').Project} Project */
+
+const SPLASH = { label: 'npx apex-navigation splash' };
+// Android 12+ shows the logo in a circle of this diameter.
+const CIRCLE = 192;
+const LOGO_HEIGHT = /<dimen name="apex_navigation_splash_logo_height">([\d.]+)dp<\/dimen>/;
+
+/**
+ * The native splash: made from its settings in package.json on both platforms, its logo whole on Android 12+; without
+ * settings, a launch screen the navigation can't keep on screen until the first screen draws.
+ * @param {string} root
+ * @param {Project} project
+ * @returns {Check[]}
+ */
+function splashChecks(root, project) {
+  const plist = project.infoPlist && fs.readFileSync(project.infoPlist, 'utf8');
+  const saved = readConfig(root).splash;
+  if (!saved) {
+    // UILaunchScreen alone: iOS shows it, but the navigation keeps only a storyboard while the first screen renders.
+    if (
+      plist?.includes('<key>UILaunchScreen</key>') &&
+      !plist.includes('<key>UILaunchStoryboardName</key>')
+    ) {
+      return [
+        {
+          group: 'app',
+          title: 'Launch screen',
+          status: 'warn',
+          detail:
+            'UILaunchScreen in Info.plist: an empty window shows between it and the first screen',
+          fix: SPLASH,
+        },
+      ];
+    }
+    return [];
+  }
+  const resolved = resolveSettings(root, {}, saved);
+  if ('errors' in resolved) {
+    return [
+      { group: 'app', title: 'Splash', status: 'warn', detail: resolved.errors[0], fix: SPLASH },
+    ];
+  }
+  const { settings } = resolved;
+  const hash = splashHash(root, settings);
+
+  /** @type {string[]} */
+  const stale = [];
+  if (project.infoPlist && plist) {
+    const assets = path.join(path.dirname(project.infoPlist), 'Images.xcassets');
+    const made =
+      fs.existsSync(path.join(assets, `SplashLogo-${hash}.imageset`)) &&
+      new RegExp(`<key>UILaunchStoryboardName</key>\\s*<string>${STORYBOARD}</string>`).test(plist);
+    if (!made) stale.push('iOS');
+  }
+  const values =
+    project.manifest &&
+    path.join(path.dirname(project.manifest), 'res', 'values', 'apex_navigation_splash.xml');
+  const valuesText = values && fs.existsSync(values) ? fs.readFileSync(values, 'utf8') : undefined;
+  if (project.manifest) {
+    const made =
+      valuesText?.includes(`(${hash})`) &&
+      fs.readFileSync(project.manifest, 'utf8').includes(`android:theme="@style/${THEME}"`);
+    if (!made) stale.push('Android');
+  }
+
+  /** @type {Check[]} */
+  const checks = [
+    stale.length === 0
+      ? { group: 'app', title: 'Splash', status: 'ok', detail: 'made from its settings' }
+      : {
+          group: 'app',
+          title: 'Splash',
+          status: 'warn',
+          detail: `${stale.join(' and ')}: not made from the settings in package.json`,
+          fix: SPLASH,
+        },
+  ];
+  const height = Number(LOGO_HEIGHT.exec(valuesText ?? '')?.[1]);
+  if (height > 0 && Math.hypot(settings.logoWidth, height) > CIRCLE) {
+    checks.push({
+      group: 'app',
+      title: 'Splash logo',
+      status: 'warn',
+      detail: `Android 12+ shows it in a circle of ${CIRCLE} dp: its corners are cut`,
+      fix: { label: 'A smaller --logo-width, or a logo with room around it' },
+    });
+  }
+  return checks;
+}
+
+module.exports = { splashChecks };