@ng-native/nx 0.1.1 → 0.1.3

package/application/index.cjs

@@ -7,7 +7,9 @@
  * `test`, which runs Vitest once rather than watching. It also replaces the inferred `start`,
  * which is `@nx/expo:start`, an executor Nx deprecates and warns about on every run, with the
  * `expo start` that executor runs, as the plugin already infers `run-ios` and `export`. Once the
- * plugin infers `start` as a command too, this one can go.
+ * plugin infers `start` as a command too, this one can go. And it replaces the inferred `serve`,
+ * `expo start --web`, which the plugin adds to every Expo app, with `expo start` too: the app has
+ * no web platform.
  *
  * Where the dependencies go depends on the workspace. With package-manager workspaces, the Nx
  * default since 20, the app is a workspace package and lists them itself, which pnpm needs in
@@ -28,6 +30,7 @@ const {
 const native = require('../native-app.cjs');
 const { init, workspaceNxVersion } = require('../init/index.cjs');
 const { usesWorkspaces, includeInWorkspaces } = require('./workspaces.cjs');
+const { asSaved } = require('../save-exact.cjs');
 
 function names(tree, options) {
   const directory = path.normalize(options.directory).replace(/\/$/, '');
@@ -36,7 +39,50 @@ function names(tree, options) {
   const workspaces = usesWorkspaces(tree);
   // A workspace package is named for the workspace's scope, as Nx names its own.
   const projectName = workspaces && scope ? `${scope}/${name}` : name;
-  return { directory, name, projectName, workspaces };
+  const bundleIdentifier = options.bundleIdentifier ?? native.bundleIdentifier(name, scope);
+  return { directory, name, projectName, workspaces, bundleIdentifier };
+}
+
+/**
+ * Whether the workspace's `tsconfig.base.json` is where its libraries' path aliases live, or will.
+ * With package-manager workspaces, only when it has a `paths` list, as the `angular-monorepo`
+ * preset's does: the TypeScript preset's has none, and its libraries are packages linked instead.
+ */
+function hasPathAliases(tree, workspaces) {
+  if (!tree.exists('tsconfig.base.json')) return false;
+  return !workspaces || 'paths' in baseCompilerOptions(tree);
+}
+
+/**
+ * The compiler options `file` ends up with, those it inherits through `extends` included, as
+ * TypeScript merges them: each option from the last config that sets it.
+ */
+function baseCompilerOptions(tree, file = 'tsconfig.base.json', ancestors = []) {
+  if (ancestors.includes(file) || !tree.exists(file)) return {};
+  const config = readJson(tree, file);
+  const inherited = [config.extends ?? []]
+    .flat()
+    .map((parent) => extendedFile(tree, path.dirname(file), parent))
+    .filter(Boolean)
+    .map((parent) => baseCompilerOptions(tree, parent, [...ancestors, file]));
+  return Object.assign({}, ...inherited, config.compilerOptions);
+}
+
+/**
+ * The file an `extends` entry in `directory` names: a path, or a package in a `node_modules` from
+ * `directory` up, where a workspace's own shared-config package is linked. A bare package name
+ * means its `tsconfig.json`.
+ */
+function extendedFile(tree, directory, parent) {
+  const withJson = (file) => (tree.exists(file) || file.endsWith('.json') ? file : `${file}.json`);
+  if (/^\.\.?\//.test(parent)) return withJson(path.join(directory, parent));
+  const bare = /^(@[^/]+\/)?[^/]+$/.test(parent);
+  for (let dir = directory; ; dir = path.dirname(dir)) {
+    const file = path.join(dir, 'node_modules', parent);
+    const found = bare ? path.join(file, 'tsconfig.json') : withJson(file);
+    if (tree.exists(found)) return found;
+    if (dir === '.' || dir === '/') return undefined;
+  }
 }
 
 function targets(directory) {
@@ -49,6 +95,7 @@ function targets(directory) {
     },
     test: { ...run('vitest run'), cache: true, inputs: ['default', '^production'] },
     start: { ...run('expo start'), continuous: true },
+    serve: { ...run('expo start'), continuous: true },
   };
 }
 
@@ -72,30 +119,49 @@ function commands(name) {
   ].join('\n');
 }
 
-function writeFiles(tree, { directory, projectName, workspaces }) {
+/**
+ * What a workspace package's app lists: the root's version of a package the root already has,
+ * where the app can use it, and its own otherwise, exact if the workspace saves exact versions.
+ */
+async function appDependencies(tree, root, wanted) {
+  const pinned = native.reuseRootRanges(wanted, root);
+  // By what the root lists, not by what changed: the root's range can be the app's own text.
+  const installed = { ...root.devDependencies, ...root.dependencies };
+  const settled = Object.keys(wanted).filter((pkg) => pinned[pkg] === installed[pkg]);
+  return asSaved(tree, pinned, settled);
+}
+
+/** The packages a manifest lists, which adding a dependency leaves at the version they have. */
+function listed(manifest) {
+  return Object.keys({ ...manifest.dependencies, ...manifest.devDependencies });
+}
+
+async function writeFiles(tree, { directory, projectName, workspaces, bundleIdentifier }) {
   const file = (name, content) => tree.write(joinPathFragments(directory, name), content);
   for (const name of native.SOURCE_FILES) file(name, native.sourceFile(name));
-  file('app.json', native.appJson(projectName));
+  file('app.json', native.appJson(projectName, bundleIdentifier));
   file('AGENTS.md', native.agentsFile(commands(projectName)));
   file('CLAUDE.md', '@AGENTS.md\n');
   file('metro.config.js', native.METRO_CONFIG);
+  // The template's own, for the native projects `expo prebuild` writes beside app.json.
+  file('.gitignore', '# generated native folders\n/ios\n/android\n');
 
-  const base = !workspaces && tree.exists('tsconfig.base.json');
+  const base = hasPathAliases(tree, workspaces);
   const workspaceBase = base ? `${offsetFromRoot(directory)}tsconfig.base.json` : undefined;
-  const conditions = tree.exists('tsconfig.base.json')
-    ? (readJson(tree, 'tsconfig.base.json').compilerOptions?.customConditions ?? [])
-    : [];
+  const conditions = baseCompilerOptions(tree).customConditions ?? [];
   file('tsconfig.json', JSON.stringify(native.tsconfig(workspaceBase, conditions), null, 2) + '\n');
   file('vitest.config.mts', native.vitestConfig(Boolean(base)));
 
   const manifest = { name: projectName, version: '0.0.1', private: true, main: 'src/main.ts' };
+  const root = readJson(tree, 'package.json');
   if (workspaces) {
+    const root = readJson(tree, 'package.json');
     Object.assign(manifest, {
-      dependencies: native.dependencies,
-      devDependencies: native.devDependencies,
+      dependencies: await appDependencies(tree, root, native.dependencies),
+      devDependencies: await appDependencies(tree, root, native.devDependencies),
     });
   } else {
-    manifest.dependencies = native.prebuildPins(readJson(tree, 'package.json'));
+    manifest.dependencies = native.prebuildPins(root);
   }
   file('package.json', JSON.stringify(manifest, null, 2) + '\n');
 }
@@ -110,11 +176,17 @@ function ignoreExpo(tree) {
 
 /**
  * @param {import('@nx/devkit').Tree} tree
- * @param {{ directory: string, name?: string, tags?: string, skipInstall?: boolean, skipFormat?: boolean }} options
+ * @param {{ directory: string, name?: string, bundleIdentifier?: string, tags?: string, skipInstall?: boolean, skipFormat?: boolean }} options
  */
 async function application(tree, options) {
   const resolved = names(tree, options);
   const { directory, projectName, workspaces } = resolved;
+  if (!native.isBundleIdentifier(resolved.bundleIdentifier)) {
+    throw new Error(
+      `${resolved.bundleIdentifier} is not a bundle identifier both iOS and Android accept: ` +
+        'two or more dot-separated segments, each a letter and then letters or digits, none a Java keyword.',
+    );
+  }
   if (tree.exists(joinPathFragments(directory, 'package.json'))) {
     throw new Error(`${directory} already has a package.json. Choose another directory.`);
   }
@@ -124,21 +196,23 @@ async function application(tree, options) {
     includeInWorkspaces(tree, directory);
   } else {
     for (const problem of native.conflicts(readJson(tree, 'package.json'))) logger.warn(problem);
-    // `nxViteTsPaths()`, which the app's Vitest config uses to reach the workspace's libraries.
-    // Added now rather than only when present, because a library generated later is the ordinary
-    // case and nothing would come back to add it then.
-    const aliases = tree.exists('tsconfig.base.json')
-      ? { '@nx/vite': workspaceNxVersion(tree) }
-      : {};
+    const existing = listed(readJson(tree, 'package.json'));
     addDependenciesToPackageJson(
       tree,
-      native.dependencies,
-      { ...native.devDependencies, ...aliases },
+      await asSaved(tree, native.dependencies, existing),
+      await asSaved(tree, native.devDependencies, existing),
       'package.json',
       true,
     );
   }
-  writeFiles(tree, resolved);
+  // `nxViteTsPaths()`, which the app's Vitest config uses to reach the workspace's libraries.
+  // Added now rather than only when present, because a library generated later is the ordinary
+  // case and nothing would come back to add it then.
+  if (hasPathAliases(tree, workspaces)) {
+    const vite = { '@nx/vite': workspaceNxVersion(tree) };
+    addDependenciesToPackageJson(tree, {}, vite, 'package.json', true);
+  }
+  await writeFiles(tree, resolved);
   addProjectConfiguration(tree, projectName, {
     root: directory,
     sourceRoot: directory,

package/application/schema.json

@@ -2,6 +2,7 @@
   "$schema": "https://json-schema.org/schema",
   "$id": "NgNativeNxApplication",
   "title": "Angular Native application",
+  "description": "An Angular Native app: an Expo project with start, run-ios, run-android, export, test and typecheck targets.",
   "type": "object",
   "properties": {
     "directory": {
@@ -15,6 +16,10 @@
       "description": "The project name. Defaults to the directory's last segment.",
       "pattern": "^[a-z][a-z0-9-]*$"
     },
+    "bundleIdentifier": {
+      "type": "string",
+      "description": "The iOS bundle identifier and Android package: com.acme.mobile. Defaults to com.<workspace scope>.<name>."
+    },
     "tags": {
       "type": "string",
       "description": "Comma-separated tags for the project."

package/application/workspaces.cjs

@@ -38,7 +38,9 @@ function usesWorkspaces(tree) {
 }
 
 /**
- * Adds `<parent>/*` for the app's directory when no glob already covers it.
+ * Adds the app's directory when no glob already covers it: as `<parent>/*` when that takes in
+ * nothing else, as Nx adds its own projects, and as the directory itself when a sibling already
+ * has a `package.json`, which the workspace either lists one by one or has left out.
  *
  * @param {import('@nx/devkit').Tree} tree
  * @param {string} directory
@@ -48,7 +50,9 @@ function includeInWorkspaces(tree, directory) {
   const including = globs(tree).filter((glob) => !glob.startsWith('!'));
   if (including.some((glob) => minimatch(directory, glob))) return;
   const parent = directory.includes('/') ? directory.slice(0, directory.lastIndexOf('/')) : '';
-  const glob = parent ? `${parent}/*` : directory;
+  const siblings = parent ? tree.children(parent).map((child) => `${parent}/${child}`) : [];
+  const alone = !siblings.some((dir) => dir !== directory && tree.exists(`${dir}/package.json`));
+  const glob = parent && alone ? `${parent}/*` : directory;
 
   if (tree.exists(PNPM)) {
     const yaml = tree.read(PNPM, 'utf-8') ?? '';

package/files/AGENTS.md

@@ -8,7 +8,7 @@ The whole documentation, for reading before a change: https://ng-native.com/llms
 outline with a line per page: https://ng-native.com/llms.txt.
 
 Angular's own rules apply as well: https://angular.dev/assets/context/best-practices.md. Its
-browser-only parts do not: there is no `NgOptimizedImage` (use `<image>`), and no AXE or ARIA
+browser-only parts do not: there is no `NgOptimizedImage` (use `<image>`), and no AXE
 (accessibility is the props below). Where the two disagree, this file wins.
 
 ## Commands
@@ -41,7 +41,9 @@ change; both are fast.
 - **No backticks inside an inline template**, even in an HTML comment: they end the template string
   and the build fails with a misleading parse error.
 - **Accessibility is props:** `accessibilityRole="button"`, `accessibilityLabel`,
-  `[accessibilityState]`. Screen readers and the testing library's `getByRole` both read them.
+  `[accessibilityState]`. The web spellings work too, as aliases: `role`, and the `aria-*` names
+  React Native maps (`aria-label`, `aria-checked`, `aria-hidden` and so on). Screen readers and
+  the testing library's `getByRole` both read them.
 
 ## Styling
 

package/files/src/app/app.ts

@@ -1,24 +1,26 @@
 import { Component, signal } from '@angular/core';
-import { Pressable, SafeAreaView, Text, View } from '@ng-native/components';
+import { Pressable, SafeAreaProvider, SafeAreaView, Text, View } from '@ng-native/components';
 
 /**
  * Element names are lowercase, and that is load-bearing rather than style: an uppercase name is
  * read as an unknown Angular component and commits as a plain view with nothing in it.
  */
 @Component({
-  imports: [Pressable, SafeAreaView, Text, View],
+  imports: [Pressable, SafeAreaProvider, SafeAreaView, Text, View],
   selector: 'app-root',
   template: `
-    <safe-area-view class="screen">
-      <view class="body">
-        <text class="title">Angular, natively</text>
-        <text class="hint">Real native views. React is never in the render path.</text>
+    <safe-area-provider>
+      <safe-area-view class="screen">
+        <view class="body">
+          <text class="title">Angular, natively</text>
+          <text class="hint">Real native views. React is never in the render path.</text>
 
-        <pressable accessibilityRole="button" class="button" (press)="count.set(count() + 1)">
-          <text class="label">Tapped {{ count() }} times</text>
-        </pressable>
-      </view>
-    </safe-area-view>
+          <pressable accessibilityRole="button" class="button" (press)="count.set(count() + 1)">
+            <text class="label">Tapped {{ count() }} times</text>
+          </pressable>
+        </view>
+      </safe-area-view>
+    </safe-area-provider>
   `,
   styles: `
     :host {

package/init/index.cjs

@@ -27,7 +27,10 @@ const {
   updateNxJson,
   NX_VERSION,
 } = require('@nx/devkit');
+const semver = require('semver');
 const native = require('../native-app.cjs');
+const { usesWorkspaces } = require('../application/workspaces.cjs');
+const { asSaved, savesExact } = require('../save-exact.cjs');
 
 /** The plugin entry `@nx/expo:init` itself writes, so the target names are the ones Nx documents. */
 const EXPO_PLUGIN = {
@@ -47,10 +50,16 @@ const EXPO_PLUGIN = {
   },
 };
 
-/** The Nx this workspace installed, which every `@nx/*` package in it has to match. */
+/**
+ * The Nx this workspace installed, which every `@nx/*` package in it has to match: the version
+ * running now when the workspace saves exact versions and lists Nx at a range, rather than the
+ * newest the range allows, which may not be the one installed.
+ */
 function workspaceNxVersion(tree) {
   const manifest = readJson(tree, 'package.json');
-  return manifest.devDependencies?.nx ?? manifest.dependencies?.nx ?? NX_VERSION;
+  const nx = manifest.devDependencies?.nx ?? manifest.dependencies?.nx ?? NX_VERSION;
+  const running = !semver.valid(nx) && savesExact(tree) && semver.satisfies(NX_VERSION, nx);
+  return running ? NX_VERSION : nx;
 }
 
 function registerExpoPlugin(tree) {
@@ -63,16 +72,35 @@ function registerExpoPlugin(tree) {
   updateNxJson(tree, { ...nxJson, plugins: [...plugins, EXPO_PLUGIN] });
 }
 
+/**
+ * What goes beside `@nx/expo` at the root. With package-manager workspaces the app's own
+ * `package.json` lists Expo, React and React Native, and the root lists none of them, so pnpm
+ * resolves `@nx/expo`'s `expo` peer, and that Expo's own peers, in the root's context at the
+ * newest versions there are: a second React Native and React in the lockfile. Pinning them here
+ * at the app's versions makes the root's copies the app's. `react-dom` stays for `@nx/react`'s
+ * peer, which needs a React beside it. `@expo/cli` is left out: `@nx/expo` runs the CLI through
+ * `expo/bin/cli`, and `@expo/cli` peers on Expo and React Native too.
+ */
+function rootDependencies(tree) {
+  if (!usesWorkspaces(tree)) return native.expoCompanions;
+  const { '@expo/cli': _cli, ...companions } = native.expoCompanions;
+  const { expo, react, 'react-native': reactNative } = native.dependencies;
+  return { ...companions, expo, react, 'react-native': reactNative };
+}
+
 /**
  * @param {import('@nx/devkit').Tree} tree
  * @param {{ skipInstall?: boolean, skipFormat?: boolean }} options
  */
 async function init(tree, options = {}) {
   registerExpoPlugin(tree);
+  const { dependencies, devDependencies } = readJson(tree, 'package.json');
+  const existing = Object.keys({ ...dependencies, ...devDependencies });
+  const companions = await asSaved(tree, rootDependencies(tree), existing);
   const install = addDependenciesToPackageJson(
     tree,
     {},
-    { '@nx/expo': workspaceNxVersion(tree), ...native.expoCompanions },
+    { '@nx/expo': workspaceNxVersion(tree), ...companions },
     'package.json',
     true,
   );

package/init/schema.json

@@ -2,6 +2,7 @@
   "$schema": "https://json-schema.org/schema",
   "$id": "NgNativeNxInit",
   "title": "Set up Angular Native",
+  "description": "Registers @nx/expo's plugin, which infers the Expo targets. nx add runs this.",
   "type": "object",
   "properties": {
     "skipInstall": {

package/native-app.cjs

@@ -38,8 +38,9 @@ const dependencies = {
   ...Object.fromEntries(FRAMEWORK.map((name) => [name, version])),
   '@angular/common': '^22.0.0',
   '@angular/core': '^22.0.0',
-  expo: '~57.0.20',
+  expo: '~57.0.26',
   'expo-status-bar': '~57.0.1',
+  'expo-system-ui': '~57.0.4',
   react: '19.2.3',
   'react-native': '0.86.3',
   'react-native-safe-area-context': '~5.7.0',
@@ -52,7 +53,7 @@ const dependencies = {
  */
 const expoCompanions = {
   'react-dom': dependencies.react,
-  '@expo/cli': '^57.0.22',
+  '@expo/cli': '^57.0.27',
   '@babel/runtime': '^7.20.0',
 };
 
@@ -90,14 +91,56 @@ function agentsFile(commands) {
   );
 }
 
+/** Java's reserved words, which Android refuses as a segment of a package name. */
+const JAVA_KEYWORDS = new Set(
+  (
+    'abstract assert boolean break byte case catch char class const continue default do double ' +
+    'else enum extends false final finally float for goto if implements import instanceof int ' +
+    'interface long native new null package private protected public return short static ' +
+    'strictfp super switch synchronized this throw throws transient true try void volatile while'
+  ).split(' '),
+);
+
+/**
+ * Whether iOS takes `id` as a bundle identifier and Android as a package name: two or more
+ * segments, each a letter and then letters or digits (iOS refuses `_`, Android `-`), none of them
+ * a Java keyword.
+ *
+ * @param {string} id
+ */
+function isBundleIdentifier(id) {
+  const segments = id.split('.');
+  return (
+    segments.length > 1 &&
+    segments.every((s) => /^[a-z][a-z0-9]*$/i.test(s) && !JAVA_KEYWORDS.has(s))
+  );
+}
+
+/**
+ * `com.<scope>.<name>`, for an app given no `--bundleIdentifier`, where prebuild would otherwise
+ * make it `com.anonymous.<name>`. The scope is left out when it cannot be made a segment.
+ *
+ * @param {string} name the app's name, without a scope
+ * @param {string | undefined} scope the workspace's npm scope, `@acme`
+ */
+function bundleIdentifier(name, scope) {
+  const clean = (text) => text.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const valid = (segment) => /^[a-z]/.test(segment) && !JAVA_KEYWORDS.has(segment);
+  const org = clean(scope ?? '');
+  const app = clean(name);
+  return ['com', ...(valid(org) ? [org] : []), valid(app) ? app : `app${app}`].join('.');
+}
+
 /**
  * The template's `app.json`, named for this app, without the template's icons: they are the
  * template's branding, and Expo draws its own default until `icon` is set.
  *
  * @param {string} name the project name, which is also the Expo slug
+ * @param {string} [id] the iOS bundle identifier and Android package, by default one from `name`
  */
-function appJson(name) {
+function appJson(name, id) {
   const slug = name.replace(/^@[^/]+\//, '');
+  const bundle = id ?? bundleIdentifier(slug, name.match(/^@[^/]+/)?.[0]);
   const expo = {
     name: slug,
     slug,
@@ -106,11 +149,12 @@ function appJson(name) {
     platforms: ['ios', 'android'],
     orientation: 'portrait',
     userInterfaceStyle: 'dark',
-    ios: { supportsTablet: true },
-    android: { predictiveBackGestureEnabled: false },
+    ios: { supportsTablet: true, bundleIdentifier: bundle },
+    android: { package: bundle, predictiveBackGestureEnabled: false },
     scheme: slug.replace(/[^a-z0-9]/gi, '').toLowerCase(),
     // The template's: Expo otherwise guesses a router root from src/app and says so on every start.
     extra: { router: { root: 'src/app' } },
+    plugins: ['@ng-native/metro'],
   };
   return JSON.stringify({ expo }, null, 2) + '\n';
 }
@@ -140,12 +184,12 @@ function tsconfig(workspaceBase, conditions = []) {
     typeCheckHostBindings: false,
     strictDomEventTypes: false,
   };
+  // The workspace's custom conditions, which a library in Nx's TypeScript preset exports its
+  // source under; the Metro preset and the Vitest plugin read them from here too. Beside
+  // Expo's own `react-native`, which setting the option would otherwise replace.
+  const customConditions = ['react-native', ...conditions.filter((c) => c !== 'react-native')];
   if (!workspaceBase) {
-    // The workspace's custom conditions, which a library in Nx's TypeScript preset exports its
-    // source under; the Metro preset and the Vitest plugin read them from here too. Beside
-    // Expo's own `react-native`, which setting the option would otherwise replace.
-    const extra = conditions.filter((c) => c !== 'react-native');
-    if (extra.length) compilerOptions.customConditions = ['react-native', ...extra];
+    if (customConditions.length > 1) compilerOptions.customConditions = customConditions;
     return { extends: 'expo/tsconfig.base', compilerOptions, angularCompilerOptions };
   }
   // The workspace's base is written for a web build or for emitting declarations, and wins over
@@ -160,7 +204,7 @@ function tsconfig(workspaceBase, conditions = []) {
       target: 'ESNext',
       module: 'preserve',
       moduleResolution: 'bundler',
-      customConditions: ['react-native'],
+      customConditions,
       composite: false,
       declaration: false,
       emitDeclarationOnly: false,
@@ -208,6 +252,30 @@ function prebuildPins(root) {
  */
 const accepted = { vitest: '^4.0.8 || ^5.0.0' };
 
+/**
+ * The ranges a workspace package's `package.json` lists: the root's own where everything it can
+ * resolve to is a version Angular Native accepts, so that pnpm does not install a second Vitest
+ * beside the root's. A wider root range is not reused: React Native needs its exact React, not
+ * whatever `^19.0.0` resolves to.
+ *
+ * @param {Record<string, string>} wanted
+ * @param {{ dependencies?: Record<string, string>, devDependencies?: Record<string, string> }} root
+ */
+function reuseRootRanges(wanted, root) {
+  const installed = { ...root.devDependencies, ...root.dependencies };
+  return Object.fromEntries(
+    Object.entries(wanted).map(([name, range]) => {
+      const existing = installed[name];
+      const reuse =
+        existing &&
+        !name.startsWith('@ng-native/') &&
+        semver.validRange(existing) &&
+        semver.subset(existing, accepted[name] ?? range);
+      return [name, reuse ? existing : range];
+    }),
+  );
+}
+
 /**
  * Why an existing dependency would stop this app installing or running, as a sentence each.
  *
@@ -243,10 +311,13 @@ module.exports = {
   sourceFile,
   agentsFile,
   appJson,
+  bundleIdentifier,
+  isBundleIdentifier,
   METRO_CONFIG,
   tsconfig,
   vitestConfig,
   prebuildPins,
+  reuseRootRanges,
   expoCompanions,
   conflicts,
   accepted,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-native/nx",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Nx generators for Angular Native: nx add, and an Expo app project whose targets run it.",
   "keywords": [
     "angular",

package/save-exact.cjs

@@ -0,0 +1,123 @@
+/**
+ * Whether the workspace saves exact versions, and the dependencies written that way when it does.
+ *
+ * Each package manager has its own setting for it, and a generator that writes ranges into such a
+ * workspace lets the app's Angular and TypeScript drift from the versions the rest of it pins.
+ */
+const { exec } = require('node:child_process');
+const { promisify } = require('node:util');
+const semver = require('semver');
+
+/** The rest of a line, which in YAML and TOML may end in a comment. */
+const END = String.raw`[ \t]*(#.*)?$`;
+
+const SETTINGS = {
+  'pnpm-workspace.yaml': [
+    new RegExp(`^saveExact:[ \\t]*true${END}`, 'm'),
+    new RegExp(`^savePrefix:[ \\t]*(''|"")${END}`, 'm'),
+  ],
+  '.npmrc': [
+    /^[ \t]*save-exact[ \t]*=[ \t]*true[ \t]*$/m,
+    /^[ \t]*save-prefix[ \t]*=[ \t]*(''|"")?[ \t]*$/m,
+  ],
+  '.yarnrc': [new RegExp(`^save-prefix[ \\t]+(''|"")${END}`, 'm')],
+  '.yarnrc.yml': [new RegExp(`^defaultSemverRangePrefix:[ \\t]*(''|"")${END}`, 'm')],
+  'bunfig.toml': [new RegExp(`^[ \\t]*exact[ \\t]*=[ \\t]*true${END}`, 'm')],
+};
+
+/** @param {import('@nx/devkit').Tree} tree */
+function savesExact(tree) {
+  return Object.entries(SETTINGS).some(
+    ([file, patterns]) =>
+      tree.exists(file) && patterns.some((pattern) => pattern.test(tree.read(file, 'utf-8') ?? '')),
+  );
+}
+
+/**
+ * The registry, as npm sees it from the workspace's root, so a registry set in its `.npmrc` is the
+ * one asked. Replaced in tests, which never reach the network.
+ */
+const registry = {
+  /**
+   * @param {string} name
+   * @param {string} cwd
+   * @returns {Promise<string[]>}
+   */
+  async versions(name, cwd) {
+    // A command line rather than arguments, which Windows needs to run `npm.cmd`. The name is one
+    // of this package's own dependencies, and the range, whose `^` cmd.exe would eat, stays out.
+    const { stdout } = await promisify(exec)(`npm view ${name} versions --json`, {
+      cwd,
+      timeout: 10_000,
+      windowsHide: true,
+    });
+    return [JSON.parse(stdout)].flat();
+  },
+};
+
+/**
+ * The version `pnpm add` saves for a range with exact versions on: the newest the registry has
+ * that the range allows, or the lowest it allows when the registry cannot be reached.
+ *
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {string} name
+ * @param {string} range
+ */
+async function newest(tree, name, range) {
+  if (semver.valid(range) || !semver.validRange(range)) return range;
+  const floor = semver.minVersion(range)?.version ?? range;
+  try {
+    return semver.maxSatisfying(await registry.versions(name, tree.root), range) ?? floor;
+  } catch {
+    return floor;
+  }
+}
+
+/**
+ * The range an Angular package resolves within: also the root's `@angular/core`, where the two
+ * overlap, since every Angular package peers on the others at exactly its own version.
+ *
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {string} name
+ * @param {string} range
+ */
+function withinAngular(tree, name, range) {
+  if (!name.startsWith('@angular/') || !tree.exists('package.json')) return range;
+  const { dependencies, devDependencies } = JSON.parse(tree.read('package.json', 'utf-8') ?? '{}');
+  const core = { ...devDependencies, ...dependencies }['@angular/core'];
+  if (!core || !semver.validRange(core) || !semver.validRange(range)) return range;
+  // Alternative by alternative, as joining two ranges with `||` in them would let either side's
+  // other alternatives through on their own.
+  const alternatives = (one) => semver.validRange(one).split('||');
+  const both = alternatives(range).flatMap((ours) =>
+    alternatives(core)
+      .filter((theirs) => semver.intersects(ours, theirs))
+      .map((theirs) => `${ours} ${theirs}`),
+  );
+  return both.length ? both.join(' || ') : range;
+}
+
+/**
+ * Each range as the exact version it resolves to when the workspace saves exact versions, and as
+ * it is otherwise. The packages in `settled`, which take a version the workspace already has, are
+ * left as they are.
+ *
+ * @param {import('@nx/devkit').Tree} tree
+ * @param {Record<string, string>} dependencies
+ * @param {Iterable<string>} [settled]
+ * @returns {Promise<Record<string, string>>}
+ */
+async function asSaved(tree, dependencies, settled = []) {
+  if (!savesExact(tree)) return dependencies;
+  const skip = new Set(settled);
+  return Object.fromEntries(
+    await Promise.all(
+      Object.entries(dependencies).map(async ([name, range]) => [
+        name,
+        skip.has(name) ? range : await newest(tree, name, withinAngular(tree, name, range)),
+      ]),
+    ),
+  );
+}
+
+module.exports = { savesExact, asSaved, registry };