@ng-native/nx 0.2.0 → 0.4.0

package/library/index.cjs

@@ -0,0 +1,336 @@
+/**
+ * `nx g @ng-native/nx:library packages/ui`: a library of native components, tested the way an
+ * Angular Native app is.
+ *
+ * The library itself is the workspace's own kind: `@nx/angular:library` where the workspace has
+ * `@nx/angular`, and `@nx/js:library` in the TypeScript preset, which cannot take `@nx/angular`
+ * because Angular does not support TypeScript project references. Either is run without its
+ * tests, which would be Analog on jsdom or a plain Vitest, neither of which can render a native
+ * component. In their place this writes the app's `vitest.config.mts`, a `test` target that runs
+ * it once, a `tsconfig.spec.json` for the tests, and a native component with a test for the fake
+ * Fabric in place of the one the generator wrote.
+ */
+const { readFileSync } = require('node:fs');
+const nodePath = require('node:path');
+const path = nodePath.posix;
+const {
+  addDependenciesToPackageJson,
+  ensurePackage,
+  formatFiles,
+  getProjects,
+  installPackagesTask,
+  joinPathFragments,
+  names,
+  readNxJson,
+  readJson,
+  writeJson,
+  updateJson,
+  updateProjectConfiguration,
+} = require('@nx/devkit');
+const native = require('../native-app.cjs');
+const { workspaceNxVersion } = require('../init/index.cjs');
+const { hasPathAliases } = require('../application/index.cjs');
+const { usesWorkspaces } = require('../application/workspaces.cjs');
+const { asSaved } = require('../save-exact.cjs');
+const { writeComponent } = require('../component/index.cjs');
+
+/**
+ * The defaults a generator's schema gives its options, from the copy installed at `root`.
+ *
+ * @param {string} root
+ * @param {string} pkg
+ * @param {string} generator
+ * @returns {Record<string, unknown>}
+ */
+function schemaDefaults(root, pkg, generator) {
+  let manifest;
+  try {
+    manifest = require.resolve(`${pkg}/package.json`, { paths: [root] });
+  } catch {
+    return {};
+  }
+  const read = (file) =>
+    JSON.parse(readFileSync(nodePath.join(nodePath.dirname(manifest), file), 'utf8'));
+  const entry = read(read('package.json').generators).generators[generator];
+  const { properties = {} } = read(entry.schema);
+  return Object.fromEntries(
+    Object.entries(properties)
+      .filter(([, property]) => 'default' in property)
+      .map(([name, property]) => [name, property.default]),
+  );
+}
+
+/**
+ * The options `nx g <pkg>:<generator>` starts from: its schema's defaults, then the workspace's
+ * own in `nx.json`. A generator called from another gets neither, and `@nx/angular:library` called
+ * bare writes a library with strict type checking off.
+ *
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {string} pkg
+ * @param {string} generator
+ */
+function generatorDefaults(tree, pkg, generator, root = tree.root) {
+  const workspace = readNxJson(tree)?.generators ?? {};
+  return {
+    ...schemaDefaults(root, pkg, generator),
+    ...workspace[pkg]?.[generator],
+    ...workspace[`${pkg}:${generator}`],
+  };
+}
+
+/** The library generators this one builds on, at the workspace's Nx. Replaced in tests. */
+const bases = {
+  /** @param {import('@nx/devkit').Tree} tree @param {object} options */
+  async angular(tree, options) {
+    // Only run where the workspace lists `@nx/angular`, whose root export has no generators.
+    const { libraryGenerator } = ensurePackage('@nx/angular/generators', workspaceNxVersion(tree));
+    return libraryGenerator(tree, {
+      ...generatorDefaults(tree, '@nx/angular', 'library'),
+      ...options,
+    });
+  },
+  /** @param {import('@nx/devkit').Tree} tree @param {object} options */
+  async js(tree, options) {
+    const { libraryGenerator } = ensurePackage('@nx/js', workspaceNxVersion(tree));
+    return libraryGenerator(tree, { ...generatorDefaults(tree, '@nx/js', 'library'), ...options });
+  },
+};
+
+/** What the component and its test import. */
+const imports = {
+  dependencies: {
+    '@angular/core': native.dependencies['@angular/core'],
+    '@ng-native/components': native.dependencies['@ng-native/components'],
+  },
+  devDependencies: {
+    '@ng-native/testing': native.devDependencies['@ng-native/testing'],
+    vitest: native.devDependencies.vitest,
+  },
+};
+
+/** What `nx typecheck` runs for a library in the TypeScript preset: `ngc`, which reads templates. */
+const typecheckDependencies = {
+  '@angular/compiler-cli': native.devDependencies['@angular/compiler-cli'],
+};
+
+function projectAt(tree, root) {
+  for (const [name, project] of getProjects(tree))
+    if (project.root === root) return { name, project };
+  throw new Error(`No project was generated in ${root}.`);
+}
+
+/**
+ * The native component and its test, where the generator put its own component: in a folder of
+ * its own under `src/lib` from `@nx/angular`, with an external template and stylesheet this
+ * leaves out, or as `src/lib/<name>.ts` from `@nx/js`. `src/index.ts` already exports it.
+ */
+function replaceComponent(tree, project, file) {
+  const lib = joinPathFragments(project.root, 'src', 'lib');
+  const folder = tree.exists(joinPathFragments(lib, file, `${file}.ts`))
+    ? joinPathFragments(lib, file)
+    : lib;
+  for (const extension of ['html', 'css', 'spec.ts']) {
+    const own = joinPathFragments(folder, `${file}.${extension}`);
+    if (tree.exists(own)) tree.delete(own);
+  }
+  writeComponent(tree, folder, file, project.prefix);
+}
+
+/**
+ * A `tsconfig.spec.json` like the one each generator writes with its tests, including the tests
+ * and the Vitest config. The tests import their component as `./ui.ts`, as the template's do.
+ */
+function writeSpecConfig(tree, root, angular) {
+  const include = ['vitest.config.mts', 'src/**/*.test.ts'];
+  const spec = angular
+    ? {
+        extends: './tsconfig.json',
+        compilerOptions: { noEmit: true, allowImportingTsExtensions: true },
+        include,
+      }
+    : {
+        // A project reference of the TypeScript preset's, which emits declarations only.
+        extends: readJson(tree, joinPathFragments(root, 'tsconfig.lib.json')).extends,
+        compilerOptions: { outDir: './out-tsc/vitest', allowImportingTsExtensions: true },
+        include,
+        references: [{ path: './tsconfig.lib.json' }],
+      };
+  tree.write(joinPathFragments(root, 'tsconfig.spec.json'), JSON.stringify(spec, null, 2) + '\n');
+  updateJson(tree, joinPathFragments(root, 'tsconfig.json'), (config) => {
+    const references = config.references ?? [];
+    if (!references.some((reference) => reference.path === './tsconfig.spec.json')) {
+      references.push({ path: './tsconfig.spec.json' });
+    }
+    return { ...config, references };
+  });
+  updateJson(tree, joinPathFragments(root, 'tsconfig.lib.json'), (config) => {
+    const exclude = config.exclude ?? [];
+    if (!exclude.includes('src/**/*.test.ts')) exclude.push('src/**/*.test.ts');
+    return { ...config, exclude };
+  });
+}
+
+/**
+ * Lets the library's source import as its test, the template and the documentation do, with
+ * `.ts`: `allowImportingTsExtensions` in `tsconfig.lib.json`, and `src/index.ts` written that way
+ * in place of the `.js` `@nx/js` gives it.
+ *
+ * TypeScript takes the option only where no JavaScript is emitted, which is the TypeScript
+ * preset's own setting (`emitDeclarationOnly`, which `@nx/js` writes into `tsconfig.lib.json`). A
+ * workspace that has turned that off keeps `.js`.
+ */
+function importWithTsExtensions(tree, root) {
+  const config = joinPathFragments(root, 'tsconfig.lib.json');
+  if (!emitsDeclarationsOnly(tree, config)) return;
+  updateJson(tree, config, (lib) => ({
+    ...lib,
+    compilerOptions: { ...lib.compilerOptions, allowImportingTsExtensions: true },
+  }));
+  const index = joinPathFragments(root, 'src', 'index.ts');
+  if (!tree.exists(index)) return;
+  const source = tree.read(index, 'utf-8');
+  tree.write(index, source.replace(/(from\s+['"]\.{1,2}\/[^'"]*)\.js(['"])/g, '$1.ts$2'));
+}
+
+/** The config `nx typecheck` gives `ngc` for a library, beside the one it is built with. */
+const TYPECHECK_CONFIG = 'tsconfig.typecheck.json';
+
+/**
+ * A config `ngc` can check the library's templates with, as an app's `typecheck` does. `@nx/js`
+ * infers a `typecheck` that runs `tsc`, which reads no template: a misspelled input passes.
+ *
+ * `tsconfig.lib.json` itself will not do: `ngc` refuses `emitDeclarationOnly`, and a project that
+ * is `composite` has to emit. The Angular options are the generated app's: a native view has no
+ * DOM to check a host binding or an event against.
+ */
+function writeTypecheckConfig(tree, root) {
+  writeJson(tree, joinPathFragments(root, TYPECHECK_CONFIG), {
+    extends: './tsconfig.lib.json',
+    compilerOptions: { noEmit: true, composite: false, emitDeclarationOnly: false },
+    angularCompilerOptions: {
+      strictTemplates: true,
+      typeCheckHostBindings: false,
+      strictDomEventTypes: false,
+    },
+  });
+}
+
+/** `nx typecheck <library>`: `ngc`, in place of the `tsc` `@nx/js` infers. */
+function typecheckTarget(root) {
+  return {
+    executor: 'nx:run-commands',
+    options: { cwd: root, command: `ngc -p ${TYPECHECK_CONFIG}` },
+    cache: true,
+    inputs: ['default', '^production'],
+  };
+}
+
+/** Whether a tsconfig emits declarations and no JavaScript, once what it extends is merged in. */
+function emitsDeclarationsOnly(tree, file) {
+  const { noEmit, emitDeclarationOnly } = emitOptions(tree, file, new Set());
+  return noEmit === true || emitDeclarationOnly === true;
+}
+
+/**
+ * `noEmit` and `emitDeclarationOnly` as the compiler reads them: each from the nearest config that
+ * sets it, and a later entry of an `extends` list over an earlier one.
+ */
+function emitOptions(tree, file, seen) {
+  if (seen.has(file) || !tree.exists(file)) return {};
+  // The configs on the way here, to stop at a cycle. Not every config read: two entries of a list
+  // may share an ancestor, and each is read whole.
+  const above = new Set(seen).add(file);
+  const { compilerOptions = {}, extends: base = [] } = readJson(tree, file);
+  // ponytail: a config that comes from a package is not followed, so a library under one keeps
+  // `.js`. Resolve the specifier from the config's directory if a workspace needs it.
+  const inherited = [base]
+    .flat()
+    .filter((from) => typeof from === 'string' && from.startsWith('.'))
+    .map((from) => joinPathFragments(path.dirname(file), from))
+    .map((from) => emitOptions(tree, from.endsWith('.json') ? from : `${from}.json`, above));
+  const { noEmit, emitDeclarationOnly } = compilerOptions;
+  return Object.assign(
+    {},
+    ...inherited,
+    noEmit === undefined ? {} : { noEmit },
+    emitDeclarationOnly === undefined ? {} : { emitDeclarationOnly },
+  );
+}
+
+/**
+ * The packages the component and its test import: in the library's own `package.json` when it is
+ * a workspace package, which pnpm links from, and at the root otherwise. A version already there
+ * is left alone.
+ */
+async function addImports(tree, root, alsoDev = {}) {
+  const devDependencies = { ...imports.devDependencies, ...alsoDev };
+  const manifest = joinPathFragments(root, 'package.json');
+  const rootManifest = readJson(tree, 'package.json');
+  if (tree.exists(manifest)) {
+    const own = async (wanted) => asSaved(tree, native.reuseRootRanges(wanted, rootManifest));
+    return addDependenciesToPackageJson(
+      tree,
+      await own(imports.dependencies),
+      await own(devDependencies),
+      manifest,
+      true,
+    );
+  }
+  const existing = Object.keys({ ...rootManifest.dependencies, ...rootManifest.devDependencies });
+  return addDependenciesToPackageJson(
+    tree,
+    await asSaved(tree, imports.dependencies, existing),
+    await asSaved(tree, devDependencies, existing),
+    'package.json',
+    true,
+  );
+}
+
+/**
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {{ directory: string, name?: string, tags?: string, skipInstall?: boolean, skipFormat?: boolean }} options
+ */
+async function library(tree, options) {
+  const directory = path.normalize(options.directory).replace(/\/$/, '');
+  const { dependencies, devDependencies } = readJson(tree, 'package.json');
+  const angular = Boolean({ ...dependencies, ...devDependencies }['@nx/angular']);
+  const shared = { directory, name: options.name, tags: options.tags, unitTestRunner: 'none' };
+  if (angular) await bases.angular(tree, { ...shared, skipFormat: true });
+  else await bases.js(tree, { ...shared, bundler: 'none', skipFormat: true });
+
+  const { name, project } = projectAt(tree, directory);
+  const file = names(options.name ?? path.basename(directory)).fileName;
+  replaceComponent(tree, project, file);
+
+  const aliases = hasPathAliases(tree, usesWorkspaces(tree));
+  tree.write(joinPathFragments(directory, 'vitest.config.mts'), native.vitestConfig(aliases));
+  writeSpecConfig(tree, directory, angular);
+  if (!angular) importWithTsExtensions(tree, directory);
+  if (!angular) writeTypecheckConfig(tree, directory);
+  updateProjectConfiguration(tree, name, {
+    ...project,
+    targets: {
+      ...project.targets,
+      ...(angular ? {} : { typecheck: typecheckTarget(directory) }),
+      test: {
+        executor: 'nx:run-commands',
+        options: { cwd: directory, command: 'vitest run' },
+        cache: true,
+        inputs: ['default', '^production'],
+      },
+    },
+  });
+
+  await addImports(tree, directory, angular ? {} : typecheckDependencies);
+  // `nxViteTsPaths()`, which the Vitest config uses to reach the workspace's other libraries.
+  if (aliases) {
+    const vite = { '@nx/vite': workspaceNxVersion(tree) };
+    addDependenciesToPackageJson(tree, {}, vite, 'package.json', true);
+  }
+
+  if (!options.skipFormat) await formatFiles(tree);
+  if (options.skipInstall) return () => {};
+  return () => installPackagesTask(tree, true);
+}
+
+module.exports = { library, bases, generatorDefaults };

package/library/schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "NgNativeNxLibrary",
+  "title": "Angular Native library",
+  "description": "A library of native components, whose tests render on the fake Fabric as an app's do.",
+  "type": "object",
+  "properties": {
+    "directory": {
+      "type": "string",
+      "description": "Where the library goes, relative to the workspace root: packages/ui.",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "Which directory should the library be created in?"
+    },
+    "name": {
+      "type": "string",
+      "description": "The project name. Defaults to the directory's last segment.",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "tags": {
+      "type": "string",
+      "description": "Comma-separated tags for the project."
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "description": "Write the files without installing.",
+      "default": false
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Leave the generated files unformatted.",
+      "default": false,
+      "x-priority": "internal"
+    }
+  },
+  "required": ["directory"]
+}

package/migrations/run.cjs

@@ -0,0 +1,5 @@
+/**
+ * The migrations `nx migrate` runs, from `@ng-native/migrate`, where each one is written once for
+ * `nx migrate`, `ng update` and `npx @ng-native/migrate` alike.
+ */
+module.exports = require('@ng-native/migrate').forNx();

package/migrations.json

@@ -0,0 +1,24 @@
+{
+  "generators": {
+    "sync-app-versions": {
+      "version": "0.4.0",
+      "description": "Move the @ng-native packages each project's own package.json lists to the new version.",
+      "implementation": "./migrations/run.cjs#sync-app-versions"
+    },
+    "split-store-and-player": {
+      "version": "0.3.0",
+      "description": "Import Storage, SecureStorage, audioPlayer and videoPlayer from the entry points that now hold them.",
+      "implementation": "./migrations/run.cjs#split-store-and-player"
+    },
+    "tracking-available-getter": {
+      "version": "0.3.0",
+      "description": "Read Tracking's available as a property rather than calling it.",
+      "implementation": "./migrations/run.cjs#tracking-available-getter"
+    },
+    "device-react-native-import": {
+      "version": "0.3.0",
+      "description": "Note each import of reactNative or ReactNative from @ng-native/device, which no longer exports them.",
+      "implementation": "./migrations/run.cjs#device-react-native-import"
+    }
+  }
+}