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

package/cli/changes.js

@@ -0,0 +1,235 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { uncommitted } = require('./app');
+const { unifiedDiff } = require('./diff');
+
+/**
+ * A file a command looked at and what happens to it:
+ * - create: a new file, `next` is its text, or `image` its bytes;
+ * - change: `before` becomes `next`, or the file becomes `image`;
+ * - remove: the file or folder goes, `before` is its text;
+ * - done: it is as the command would make it already;
+ * - manual: the command can't make the change (the file was changed by hand, or wasn't found); `howTo` says what to do.
+ * @typedef {{
+ *   name: string;
+ *   platform: string;
+ *   file?: string;
+ *   status: 'create' | 'change' | 'remove' | 'done' | 'manual';
+ *   note: string;
+ *   before?: string;
+ *   next?: string;
+ *   image?: Buffer;
+ *   howTo?: string;
+ * }} FileChange
+ */
+
+/**
+ * What a command came to, the same for every command; `--json` prints it for CI, tools and AI agents.
+ * - ok: nothing stopped the command and nothing is left to change by hand;
+ * - applied: the changes were written (not on a dry run, a refusal, or `--json` without `--yes`);
+ * - files: every file the command looked at, a change with its unified diff from the app's root;
+ * - errors: what stopped the command, each with a code that tells it apart;
+ * - next: what to run after the changes.
+ * @typedef {{
+ *   command: string;
+ *   ok: boolean;
+ *   applied: boolean;
+ *   files: {
+ *     name: string;
+ *     platform: string;
+ *     file?: string;
+ *     status: FileChange['status'];
+ *     note: string;
+ *     diff?: string;
+ *     howTo?: string;
+ *   }[];
+ *   warnings: string[];
+ *   errors: { code: string; message: string }[];
+ *   next: string[];
+ * }} Result
+ */
+
+/** @typedef {ReturnType<typeof import('./ui').createUI>} UI */
+
+/**
+ * The run of a command that changes files. In text mode it talks to the terminal as it goes; with `json` it says
+ * nothing and prints its result once, at the end, so the output is one JSON document.
+ * @param {{
+ *   command: string;
+ *   root: string;
+ *   json?: boolean;
+ *   ui: UI;
+ *   out?: { write(text: string): unknown };
+ * }} options
+ */
+function createRun({ command, root, json = false, ui, out = process.stdout }) {
+  /** @type {Result} */
+  const result = {
+    command,
+    ok: true,
+    applied: false,
+    files: [],
+    warnings: [],
+    errors: [],
+    next: [],
+  };
+
+  /** @param {number} code */
+  function finish(code) {
+    if (json) out.write(JSON.stringify(result, null, 2) + '\n');
+    return code;
+  }
+
+  /** @param {string} message */
+  function warn(message) {
+    result.warnings.push(message);
+    if (!json) ui.warn(message);
+  }
+
+  return {
+    result,
+    json,
+
+    /**
+     * A problem that stops the command, or several of one kind: its exit code is 1.
+     * @param {string} code tells the problem apart, such as `react-native-missing`
+     * @param {string | string[]} message
+     */
+    fail(code, message) {
+      result.ok = false;
+      for (const text of Array.isArray(message) ? message : [message]) {
+        result.errors.push({ code, message: text });
+        if (!json) ui.error(text);
+      }
+      return finish(1);
+    },
+
+    warn,
+
+    /**
+     * Shows the files and the changes, asks unless `yes`, and writes them; a dry run only shows them.
+     * @param {FileChange[]} changes
+     * @param {{
+     *   yes: boolean;
+     *   dryRun: boolean;
+     *   next?: string[];
+     *   done?: string;
+     *   nothingToDo?: string;
+     *   afterWrite?: (result: Result) => void | Promise<void>;
+     * }} options `done` and `nothingToDo` are what it says at the end; `afterWrite` runs once the files are written,
+     *   before the end is said, and may add to the result (`setup` installs the pods there)
+     * @returns {Promise<number>} the exit code: 1 when files are left to change by hand or `afterWrite` found a
+     *   problem, else 0
+     */
+    async apply(
+      changes,
+      { yes, dryRun, next = [], done = 'Done', nothingToDo = 'Nothing to change.', afterWrite }
+    ) {
+      const pending = changes.filter(({ status }) =>
+        ['change', 'create', 'remove'].includes(status)
+      );
+      const manual = changes.filter(({ status }) => status === 'manual');
+      const relative = (/** @type {string | undefined} */ file) =>
+        file && path.relative(root, file);
+      result.files = changes.map(
+        ({ name, platform, file, status, note, before = '', next: after, image, howTo }) => ({
+          name,
+          platform,
+          ...(file && { file: relative(file) }),
+          status,
+          note,
+          // An image has no diff.
+          ...(!image &&
+            (after !== undefined || status === 'remove') && {
+              diff: unifiedDiff(relative(file) ?? name, before, after ?? ''),
+            }),
+          ...(howTo && { howTo }),
+        })
+      );
+      result.ok = manual.length === 0;
+      const left = manual.length > 0 ? 1 : 0;
+
+      if (!json) {
+        ui.files(
+          changes.map(({ status, name, platform, note }) => ({
+            kind: status,
+            file: name,
+            platform,
+            note,
+          }))
+        );
+        for (const { name, file, howTo = '' } of manual) {
+          ui.warn(`${name}${file ? `  ${relative(file)}` : ''}`);
+          howTo.split('\n').forEach((line) => ui.muted(`    ${line}`));
+          ui.line('');
+        }
+      }
+      if (pending.length === 0) {
+        if (!json) {
+          if (manual.length > 0) ui.warn('The files above need a change by hand.');
+          else ui.done(nothingToDo);
+        }
+        return finish(left);
+      }
+
+      if (!json) {
+        for (const { name, before = '', next: after = '', image } of pending) {
+          if (!image) ui.diff(name, before, after);
+        }
+      }
+      if (dryRun) {
+        if (!json) ui.muted('  Dry run: nothing written.');
+        return finish(0);
+      }
+      // A tool can't answer a question: without --yes it gets the plan, and nothing is written.
+      if (json && !yes) {
+        result.warnings.push('Nothing written: run with --yes to apply the changes.');
+        return finish(0);
+      }
+
+      const files = pending.flatMap(({ file }) => (file ? [file] : []));
+      const dirty = uncommitted(root, files);
+      if (dirty.length > 0) warn(`Not committed yet: ${dirty.join(', ')}`);
+      if (!json) ui.rule();
+      const confirmed =
+        yes ||
+        (await ui.confirm(
+          `Apply ${pending.length} ${pending.length === 1 ? 'change' : 'changes'}?`
+        ));
+      if (!confirmed) {
+        ui.muted(
+          process.stdin.isTTY
+            ? '  Nothing written.'
+            : '  Nothing written. Run with --yes to apply without asking.'
+        );
+        return finish(0);
+      }
+
+      for (const { file, status, next: after = '', image } of pending) {
+        if (!file) continue;
+        if (status === 'remove') {
+          // A folder too: an asset set of the iOS catalog.
+          fs.rmSync(file, { force: true, recursive: true });
+          continue;
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, image ?? after);
+      }
+      result.applied = true;
+      result.next = [...next];
+      if (afterWrite) await afterWrite(result);
+      if (!json) {
+        ui.line('');
+        if (!result.ok && manual.length === 0) ui.warn('Written, with the problem above left.');
+        else ui.done(manual.length > 0 ? 'Done, apart from the files above.' : done);
+        if (result.next.length > 0) ui.next(result.next);
+      }
+      return finish(result.ok ? 0 : 1);
+    },
+  };
+}
+
+module.exports = { createRun };

package/cli/codegen/commands.js

@@ -0,0 +1,356 @@
+// @ts-check
+'use strict';
+
+const {
+  constantName,
+  kotlinIdentifier,
+  kotlinString,
+  memberName,
+  swiftIdentifier,
+  swiftString,
+  typeName,
+} = require('./names');
+
+/** @typedef {import('./read').Model} Model */
+/** @typedef {import('./read').Field} Field */
+/** @typedef {import('./read').CommandScreenModel} CommandScreenModel */
+
+const SHOW = [
+  [
+    'push',
+    'Shows a screen of the app over this one in its stack; returns the id of the screen shown.',
+  ],
+  ['showModal', 'Shows a screen of the app over everything, in a stack of its own.'],
+  ['showOverlay', 'Shows a screen of the app over everything, without taking the place of any.'],
+  ['showInColumn', 'Shows a screen of the app in a column of the split view this screen is in.'],
+];
+
+// Names a nested type of Swift can't have.
+const RESERVED = new Set(['Type', 'Protocol', 'Self']);
+
+/**
+ * The name of a type of a screen's props where the generated code declares it: the reader's name, with `Value` after
+ * it when it is a name Swift reserves or the name of the screen itself, which its types are nested in.
+ * @param {CommandScreenModel} screen
+ * @param {string} name
+ */
+function localType(screen, name) {
+  return RESERVED.has(name) || name === typeName(screen.name) ? `${name}Value` : name;
+}
+
+/**
+ * The typed commands in Swift: the screens of the app as an enum whose values carry the props a command gives, and
+ * the commands of `ScreenNavigation` that take one, `try await screen.navigation.push(.details(title: "Item"))`. The
+ * types of each screen's props are in a namespace of its name, `Screens.Details.Tab`. The types of Swift are written
+ * in full, as a screen may have the name of one.
+ * @param {CommandScreenModel[]} screens
+ * @returns {string}
+ */
+function swiftCommands(screens) {
+  const cases = screens.map((screen) => {
+    const name = swiftIdentifier(memberName(screen.name));
+    if (screen.fields.length === 0) return `  case ${name}`;
+    const values = screen.fields.map(
+      (field) =>
+        `${swiftIdentifier(field.name)}: ${swiftType(field.type, screen)}${field.optional ? '? = nil' : ''}`
+    );
+    return `  case ${name}(${values.join(', ')})`;
+  });
+  const names = screens.map(
+    (screen) =>
+      `    case .${swiftIdentifier(memberName(screen.name))}: return ${swiftString(screen.name)}`
+  );
+  const props = screens.map((screen) => {
+    const name = swiftIdentifier(memberName(screen.name));
+    if (screen.fields.length === 0) return `    case .${name}: return [:]`;
+    const bound = screen.fields.map((field) => swiftIdentifier(field.name)).join(', ');
+    return `    case let .${name}(${bound}): return presentFields(${swiftFields(screen.fields, screen)})`;
+  });
+  const namespaces = screens
+    .filter((screen) => screen.enums.length + screen.objects.length > 0)
+    .map((screen) => {
+      const enums = screen.enums.map(
+        (item) =>
+          `    enum ${localType(screen, item.name)}: Swift.String, CaseIterable {\n${item.values
+            .map(
+              (value) => `      case ${swiftIdentifier(memberName(value))} = ${swiftString(value)}`
+            )
+            .join('\n')}\n    }`
+      );
+      const objects = screen.objects.map((object) => {
+        const members = object.fields.map(
+          (field) =>
+            `      let ${swiftIdentifier(field.name)}: ${swiftType(field.type, screen)}${field.optional ? '?' : ''}`
+        );
+        const parameters = object.fields.map(
+          (field) =>
+            `${swiftIdentifier(field.name)}: ${swiftType(field.type, screen)}${field.optional ? '? = nil' : ''}`
+        );
+        const assignments = object.fields.map(
+          (field) => `        self.${field.name} = ${swiftIdentifier(field.name)}`
+        );
+        return `    struct ${localType(screen, object.name)} {
+${members.join('\n')}
+
+      init(${parameters.join(', ')}) {
+${assignments.join('\n')}
+      }
+
+      var json: [Swift.String: Any] { presentFields(${swiftFields(object.fields, screen)}) }
+    }`;
+      });
+      return `  /// The types of the props of \`${screen.name}\`.\n  enum ${typeName(screen.name)} {\n${[...enums, ...objects].join('\n\n')}\n  }`;
+    });
+  const show = SHOW.map(
+    ([command, doc]) => `  /// ${doc}
+  @discardableResult
+  func ${command}(_ screen: Screens) async throws -> Swift.String {
+    try await ${command}(screen.name, props: screen.props)
+  }`
+  );
+  return `// MARK: - The screens of the app
+
+/// The screens of the app with the props a command gives each, for the typed commands of \`ScreenNavigation\`:
+/// \`try await screen.navigation.push(.${screens[0] ? memberName(screens[0].name) : 'home'})\`.
+enum Screens {
+${cases.join('\n')}
+
+  /// The name of the screen in \`screens\`.
+  var name: Swift.String {
+    switch self {
+${names.join('\n')}
+    }
+  }
+
+  /// The props as JS gets them; a value that isn't there is left out.
+  var props: [Swift.String: Any] {
+    switch self {
+${props.join('\n')}
+    }
+  }
+}
+${namespaces.length > 0 ? `\nextension Screens {\n${namespaces.join('\n\n')}\n}\n` : ''}
+extension ScreenNavigation {
+${show.join('\n\n')}
+}
+
+/// The fields that have a value.
+private func presentFields(_ fields: [Swift.String: Any?]) -> [Swift.String: Any] {
+  fields.compactMapValues { $0 }
+}
+`;
+}
+
+/**
+ * The fields as a Swift dictionary literal of what JS gets.
+ * @param {Field[]} fields
+ * @param {CommandScreenModel} screen
+ */
+function swiftFields(fields, screen) {
+  if (fields.length === 0) return '[:]';
+  const entries = fields.map((field) => {
+    const value = swiftIdentifier(field.name);
+    const inner = swiftEncode(field.type, '$0', screen);
+    // A plain optional goes as it is: nil is left out.
+    const encoded = field.optional
+      ? inner === '$0'
+        ? value
+        : `${value}.map { ${inner} }`
+      : swiftEncode(field.type, value, screen);
+    return `${swiftString(field.name)}: ${encoded}`;
+  });
+  return `[${entries.join(', ')}]`;
+}
+
+/**
+ * @param {Model} model
+ * @param {CommandScreenModel} screen
+ * @returns {string}
+ */
+function swiftType(model, screen) {
+  switch (model.kind) {
+    case 'string':
+      return 'Swift.String';
+    case 'number':
+      return model.int ? 'Swift.Int' : 'Swift.Double';
+    case 'boolean':
+      return 'Swift.Bool';
+    case 'enum':
+    case 'object':
+      return `Screens.${typeName(screen.name)}.${localType(screen, model.name)}`;
+    case 'array':
+      return `[${swiftType(model.element, screen)}]`;
+    case 'function':
+      return 'Never';
+  }
+}
+
+/**
+ * The value JS gets for a value of Swift.
+ * @param {Model} model
+ * @param {string} value
+ * @param {CommandScreenModel} screen
+ * @returns {string}
+ */
+function swiftEncode(model, value, screen) {
+  switch (model.kind) {
+    case 'enum':
+      return `${value}.rawValue`;
+    case 'object':
+      return `${value}.json`;
+    case 'array': {
+      const element = swiftEncode(model.element, '$0', screen);
+      return element === '$0' ? value : `${value}.map { ${element} }`;
+    }
+    default:
+      return value;
+  }
+}
+
+/**
+ * The typed commands in Kotlin: the screens of the app as a sealed class, an object for a screen without props and a
+ * data class for one with them, with the types of its props inside, and the commands of `ScreenNavigation` that take
+ * one, `navigation.push(Screens.Details(title = "Item"))`. The classes have no members of their own, so a prop may have
+ * any name; their names and props for JS are extensions of the file, and the types of Kotlin are written in full, as a
+ * screen may have the name of one.
+ * @param {CommandScreenModel[]} screens
+ * @returns {string}
+ */
+function kotlinCommands(screens) {
+  const classes = screens.map((screen) => {
+    const name = typeName(screen.name);
+    if (screen.fields.length === 0) return `  object ${name} : Screens()`;
+    const parameters = screen.fields.map(
+      (field) =>
+        `    val ${kotlinIdentifier(field.name)}: ${kotlinType(field.type, screen)}${field.optional ? '? = null' : ''},`
+    );
+    const enums = screen.enums.map(
+      (item) => `    enum class ${localType(screen, item.name)}(val value: kotlin.String) {
+${item.values.map((value) => `      ${constantName(value)}(${kotlinString(value)}),`).join('\n')}
+    }`
+    );
+    const objects = screen.objects.map((object) => {
+      const fields = object.fields.map(
+        (field) =>
+          `      val ${kotlinIdentifier(field.name)}: ${kotlinType(field.type, screen)}${field.optional ? '? = null' : ''},`
+      );
+      return `    data class ${localType(screen, object.name)}(
+${fields.join('\n')}
+    ) {
+      fun json(): JSONObject = JSONObject(${kotlinFields(object.fields)})
+    }`;
+    });
+    const nested = [...enums, ...objects];
+    return `  data class ${name}(
+${parameters.join('\n')}
+  ) : Screens()${nested.length > 0 ? ` {\n${nested.join('\n\n')}\n  }` : ''}`;
+  });
+  const names = screens.map(
+    (screen) => `    is Screens.${typeName(screen.name)} -> ${kotlinString(screen.name)}`
+  );
+  const props = screens.map(
+    (screen) =>
+      `    is Screens.${typeName(screen.name)} -> ${
+        screen.fields.length === 0 ? 'emptyMap()' : kotlinFields(screen.fields)
+      }`
+  );
+  const show = SHOW.map(
+    ([command, doc]) => `/** ${doc} */
+suspend fun ScreenNavigation.${command}(screen: Screens): kotlin.String =
+  ${command}(screen.jsName, screen.jsProps)`
+  );
+  return `// The screens of the app
+
+/**
+ * The screens of the app with the props a command gives each, for the typed commands of [ScreenNavigation]:
+ * \`navigation.push(Screens.${screens[0] ? typeName(screens[0].name) : 'Home'})\`.
+ */
+sealed class Screens {
+${classes.join('\n\n')}
+}
+
+/** The name of the screen in \`screens\`. */
+private val Screens.jsName: kotlin.String
+  get() = when (this) {
+${names.join('\n')}
+  }
+
+/** The props as JS gets them; a value that isn't there is left out. */
+private val Screens.jsProps: kotlin.collections.Map<kotlin.String, kotlin.Any?>
+  get() = when (this) {
+${props.join('\n')}
+  }
+
+${show.join('\n\n')}
+
+/** The fields that have a value. */
+private fun presentFields(
+  vararg fields: kotlin.Pair<kotlin.String, kotlin.Any?>
+): kotlin.collections.Map<kotlin.String, kotlin.Any?> = fields.filter { it.second != null }.toMap()
+`;
+}
+
+/**
+ * The fields as a call of `presentFields` with what JS gets.
+ * @param {Field[]} fields
+ */
+function kotlinFields(fields) {
+  const entries = fields.map((field) => {
+    const value = kotlinIdentifier(field.name);
+    const inner = kotlinEncode(field.type, 'it');
+    // A plain optional goes as it is: null is left out.
+    const encoded = field.optional
+      ? inner === 'it'
+        ? value
+        : `${value}?.let { ${inner} }`
+      : kotlinEncode(field.type, value);
+    return `${kotlinString(field.name)} to ${encoded}`;
+  });
+  return `presentFields(${entries.join(', ')})`;
+}
+
+/**
+ * @param {Model} model
+ * @param {CommandScreenModel} screen
+ * @returns {string}
+ */
+function kotlinType(model, screen) {
+  switch (model.kind) {
+    case 'string':
+      return 'kotlin.String';
+    case 'number':
+      return model.int ? 'kotlin.Int' : 'kotlin.Double';
+    case 'boolean':
+      return 'kotlin.Boolean';
+    case 'enum':
+    case 'object':
+      return localType(screen, model.name);
+    case 'array':
+      return `kotlin.collections.List<${kotlinType(model.element, screen)}>`;
+    case 'function':
+      return 'kotlin.Nothing';
+  }
+}
+
+/**
+ * The value JS gets for a value of Kotlin.
+ * @param {Model} model
+ * @param {string} value
+ * @returns {string}
+ */
+function kotlinEncode(model, value) {
+  switch (model.kind) {
+    case 'enum':
+      return `${value}.value`;
+    case 'object':
+      return `${value}.json()`;
+    case 'array': {
+      const element = kotlinEncode(model.element, 'it');
+      return element === 'it' ? `JSONArray(${value})` : `JSONArray(${value}.map { ${element} })`;
+    }
+    default:
+      return value;
+  }
+}
+
+module.exports = { swiftCommands, kotlinCommands };