feat(android): Gradle facts file, unique plugin aar names and opt-in read-only node_modules

- `ns prepare android` writes platforms/android/nativescript-gradle.json next
  to dependencies.json (project dirs and every native plugin's package dir,
  native dir and aar, paths relative to the file, plus the hash of
  dependencies.json) and passes -Pnativescript.factsFile to app and plugin
  Gradle builds. org.nativescript:gradle-api reads it.
- Plugins whose short names clash (@foo/plugin-x and @bar/plugin-x) get
  scope-qualified aar names, temp build dirs and namespace fallbacks. Names
  that don't clash are unchanged. An aar left under a plugin's previous name is
  deleted when it is the CLI's own output, otherwise prepare stops.
- `android.readOnlyNodeModules` in nativescript.config: plugins' Android files
  and package.json are mirrored into platforms/android/.ns-plugins, aars are
  built and include.gradle is migrated there, dependencies.json points at the
  mirrors, and plugin aar builds also apply the plugin's own buildscript.gradle
  and the gradle-api library.

Author: edusperoni

lib/bootstrap.ts

@@ -48,6 +48,10 @@ injector.require(
 	"gradleBuildArgsService",
 	"./services/android/gradle-build-args-service",
 );
+injector.require(
+	"androidPluginMirrorService",
+	"./services/android/android-plugin-mirror-service",
+);
 injector.require(
 	"androidBundleToolService",
 	"./services/android/android-bundle-tool-service",

lib/common/helpers.ts

@@ -125,6 +125,71 @@ function sanitizePluginName(pluginName: string): string {
 	return pluginName.split("/").pop();
 }
 
+function getScopeQualifiedPluginName(pluginName: string): string | null {
+	const parts = pluginName.split("/");
+	if (parts.length < 2 || !parts[0].startsWith("@")) {
+		return null;
+	}
+
+	const scope = parts[0].slice(1).replace(/[^A-Za-z0-9_]/g, "_");
+	return `${scope}_${getShortPluginName(pluginName)}`;
+}
+
+// The aar name doubles as a Java package segment (the `org.nativescript.<name>`
+// namespace fallback), which cannot start with a digit.
+function withoutLeadingDigit(name: string): string {
+	return /^[0-9]/.test(name) ? `_${name}` : name;
+}
+
+/**
+ * Maps each plugin name to a file-system and Java-package safe name for its aar
+ * that is unique among `pluginNames`. A plugin whose short name is not shared
+ * keeps `getShortPluginName(name)`, so projects without clashes keep their names.
+ * Throws if two plugins still end up with the same name.
+ */
+export function getUniqueShortPluginNames(
+	pluginNames: string[],
+): Map<string, string> {
+	const sortedNames = _.sortBy(_.uniq(pluginNames));
+	const namesByShortName = _.groupBy(sortedNames, getShortPluginName);
+	const result = new Map<string, string>();
+	const owners = new Map<string, string>();
+
+	for (const pluginName of sortedNames) {
+		const shortName = getShortPluginName(pluginName);
+		const aarName =
+			namesByShortName[shortName].length === 1
+				? shortName
+				: withoutLeadingDigit(
+						getScopeQualifiedPluginName(pluginName) ?? shortName,
+					);
+
+		const owner = owners.get(aarName);
+		if (owner !== undefined) {
+			throw new Error(
+				`The plugins "${owner}" and "${pluginName}" both need the Android aar name "${aarName}". Remove one of them from the project.`,
+			);
+		}
+
+		owners.set(aarName, pluginName);
+		result.set(pluginName, aarName);
+	}
+
+	return result;
+}
+
+/**
+ * Every aar name `getUniqueShortPluginNames` can give this plugin, depending on
+ * which other plugins are installed.
+ */
+export function getCandidateAarNames(pluginName: string): string[] {
+	const shortName = getShortPluginName(pluginName);
+	return _.uniq([
+		shortName,
+		withoutLeadingDigit(getScopeQualifiedPluginName(pluginName) ?? shortName),
+	]);
+}
+
 export async function executeActionByChunks<T>(
 	initialData: T[] | IDictionary<T>,
 	chunkSize: number,

lib/common/test/unit-tests/helpers.ts

@@ -1111,4 +1111,129 @@ const test = require("./test");`,
 			assert.deepStrictEqual(seen.sink, ["kept"]);
 		});
 	});
+
+	describe("getUniqueShortPluginNames", () => {
+		const toObject = (names: string[]) =>
+			Object.fromEntries(helpers.getUniqueShortPluginNames(names));
+
+		it("keeps the short name of plugins without a clash", () => {
+			assert.deepStrictEqual(
+				toObject([
+					"@nativescript/core",
+					"nativescript-plugin",
+					"@scope/my-plugin",
+					"9-lives",
+				]),
+				{
+					"@nativescript/core": "core",
+					"nativescript-plugin": "nativescript_plugin",
+					"@scope/my-plugin": "my_plugin",
+					"9-lives": "9_lives",
+				},
+			);
+		});
+
+		it("qualifies clashing scoped plugins with their scope", () => {
+			assert.deepStrictEqual(
+				toObject(["@foo/plugin-x", "@bar/plugin-x", "@nativescript/core"]),
+				{
+					"@foo/plugin-x": "foo_plugin_x",
+					"@bar/plugin-x": "bar_plugin_x",
+					"@nativescript/core": "core",
+				},
+			);
+		});
+
+		it("lets an unscoped plugin keep its name when it clashes with a scoped one", () => {
+			assert.deepStrictEqual(toObject(["plugin-x", "@foo/plugin-x"]), {
+				"plugin-x": "plugin_x",
+				"@foo/plugin-x": "foo_plugin_x",
+			});
+		});
+
+		it("replaces characters a scope may contain but a name may not", () => {
+			assert.deepStrictEqual(toObject(["@my.org~x/plugin", "@a/plugin"]), {
+				"@my.org~x/plugin": "my_org_x_plugin",
+				"@a/plugin": "a_plugin",
+			});
+		});
+
+		it("prefixes clashing names that would start with a digit", () => {
+			assert.deepStrictEqual(toObject(["@1password/plugin", "@a/plugin"]), {
+				"@1password/plugin": "_1password_plugin",
+				"@a/plugin": "a_plugin",
+			});
+			assert.deepStrictEqual(toObject(["9-lives", "@a/9-lives"]), {
+				"9-lives": "_9_lives",
+				"@a/9-lives": "a_9_lives",
+			});
+		});
+
+		it("fails when two plugins still share a name", () => {
+			assert.throws(
+				() =>
+					helpers.getUniqueShortPluginNames(["@foo/plugin-x", "@foo/plugin_x"]),
+				/"@foo\/plugin-x" and "@foo\/plugin_x"/,
+			);
+			assert.throws(
+				() =>
+					helpers.getUniqueShortPluginNames([
+						"foo-plugin-x",
+						"@foo/plugin-x",
+						"@bar/plugin-x",
+					]),
+				/"@foo\/plugin-x" and "foo-plugin-x".*"foo_plugin_x"/,
+			);
+		});
+
+		it("does not depend on the order of the plugins", () => {
+			const names = ["@foo/plugin-x", "plugin-x", "@bar/plugin-x", "other"];
+			const expected = toObject(names);
+			assert.deepStrictEqual(toObject([...names].reverse()), expected);
+			assert.deepStrictEqual(
+				toObject([names[2], names[0], names[3], names[1]]),
+				expected,
+			);
+			assert.throws(
+				() =>
+					helpers.getUniqueShortPluginNames(["@foo/plugin_x", "@foo/plugin-x"]),
+				/"@foo\/plugin-x" and "@foo\/plugin_x"/,
+			);
+		});
+	});
+
+	describe("getCandidateAarNames", () => {
+		it("lists the short and the scope-qualified name of a scoped plugin", () => {
+			assert.deepStrictEqual(helpers.getCandidateAarNames("@foo/plugin-x"), [
+				"plugin_x",
+				"foo_plugin_x",
+			]);
+		});
+
+		it("lists the short name of an unscoped plugin", () => {
+			assert.deepStrictEqual(helpers.getCandidateAarNames("plugin-x"), [
+				"plugin_x",
+			]);
+			assert.deepStrictEqual(helpers.getCandidateAarNames("9-lives"), [
+				"9_lives",
+				"_9_lives",
+			]);
+		});
+
+		it("covers every name getUniqueShortPluginNames gives", () => {
+			const projects = [
+				["@foo/plugin-x"],
+				["@foo/plugin-x", "@bar/plugin-x"],
+				["plugin-x", "@foo/plugin-x"],
+				["@1a/plugin", "@b/plugin", "plugin", "9-lives", "@c/9-lives"],
+			];
+			for (const project of projects) {
+				for (const [name, aarName] of helpers.getUniqueShortPluginNames(
+					project,
+				)) {
+					assert.include(helpers.getCandidateAarNames(name), aarName);
+				}
+			}
+		});
+	});
 });

lib/constants.ts

@@ -73,6 +73,8 @@ export const CONFIG_FILE_NAME_DISPLAY = "nativescript.config.(js|ts)";
 export const CONFIG_FILE_NAME_JS = "nativescript.config.js";
 export const CONFIG_FILE_NAME_TS = "nativescript.config.ts";
 export const DEPENDENCIES_JSON_NAME = "dependencies.json";
+export const GRADLE_FACTS_FILE_NAME = "nativescript-gradle.json";
+export const ANDROID_PLUGIN_MIRRORS_DIR_NAME = ".ns-plugins";
 export const APK_EXTENSION_NAME = ".apk";
 export const AAB_EXTENSION_NAME = ".aab";
 export const APKS_EXTENSION_NAME = ".apks";

lib/definitions/android-plugin-migrator.d.ts

@@ -3,6 +3,20 @@ import { IProjectDir } from "../common/declarations";
 
 interface IPluginBuildOptions extends IAndroidBuildOptions {
 	projectDir?: string;
+	/**
+	 * File name (without extension) of the built aar and of its temp build dir.
+	 * Defaults to the plugin's short name.
+	 */
+	aarName?: string;
+	/**
+	 * The project keeps node_modules read-only, so `aarOutputDir` is a CLI-owned
+	 * copy of the plugin's platforms/android.
+	 */
+	readOnlyNodeModules?: boolean;
+	/**
+	 * The project's nativescript-gradle.json, passed to the plugin's Gradle build when it exists.
+	 */
+	gradleFactsFile?: string;
 }
 
 interface IAndroidBuildOptions {
@@ -17,6 +31,33 @@ interface IAndroidBuildOptions {
 interface IAndroidPluginBuildService {
 	buildAar(options: IPluginBuildOptions): Promise<boolean>;
 	migrateIncludeGradle(options: IPluginBuildOptions): boolean;
+	/**
+	 * Whether the plugin has sources to build but `aarOutputDir` lacks its aar
+	 * or still holds one under another of its candidate names.
+	 */
+	hasOutdatedAar(options: IPluginBuildOptions): boolean;
+}
+
+interface IAndroidPluginMirror {
+	pluginName: string;
+	/**
+	 * The installed npm package.
+	 */
+	packageDir: string;
+	mirrorDir: string;
+	/**
+	 * Paths relative to the package's platforms/android that are not copied.
+	 */
+	excludedNativeFiles?: string[];
+}
+
+interface IAndroidPluginMirrorService {
+	/**
+	 * Brings `<mirrorsRoot>/<dir>` in line with each plugin's package.json and
+	 * platforms/android, and removes mirrors of plugins not in `mirrors`.
+	 * @returns The names of the plugins whose mirror changed.
+	 */
+	syncMirrors(mirrorsRoot: string, mirrors: IAndroidPluginMirror[]): string[];
 }
 
 /**
@@ -49,4 +90,14 @@ interface IBuildAndroidPluginData extends Partial<IProjectDir> {
 	 * Optional custom Gradle arguments.
 	 */
 	gradleArgs?: string;
+
+	/**
+	 * The project keeps node_modules read-only (`android.readOnlyNodeModules`).
+	 */
+	readOnlyNodeModules?: boolean;
+
+	/**
+	 * Absolute path of the project's nativescript-gradle.json, when it exists.
+	 */
+	gradleFactsFile?: string;
 }

lib/definitions/gradle-facts.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Contents of platforms/android/nativescript-gradle.json, read by
+ * org.nativescript:gradle-api. Mirrors gradle-api/schema/nativescript-gradle.schema.json:
+ * fields are only ever added, and every path is relative to the file's
+ * directory with forward slashes.
+ */
+export interface INativeScriptGradleFacts {
+	schemaVersion: number;
+	cli?: { version?: string };
+	runtime?: { name?: string; version?: string };
+	capabilities?: string[];
+	/**
+	 * Identifies the dependencies.json written together with these facts, so a
+	 * reader can tell when a CLI that does not write facts has replaced it since.
+	 */
+	dependenciesJson: { sha256: string };
+	project: INativeScriptGradleFactsProject;
+	plugins: INativeScriptGradleFactsPlugin[];
+}
+
+export interface INativeScriptGradleFactsProject {
+	root: string;
+	appDir: string;
+	appResourcesDir: string;
+}
+
+export interface INativeScriptGradleFactsPlugin {
+	name: string;
+	packageDir: string;
+	nativeDir: string;
+	aarName: string;
+	aar: string;
+	dependencies: string[];
+	options?: Record<string, unknown>;
+}

lib/definitions/project.d.ts

@@ -179,6 +179,12 @@ interface INsConfigAndroid extends INsConfigPlaform {
 	 * Custom runtime package name
 	 */
 	runtimePackageName?: string;
+
+	/**
+	 * Never write into node_modules: each plugin's Android files are copied to
+	 * `platforms/android/.ns-plugins/` and its aar is built there.
+	 */
+	readOnlyNodeModules?: boolean;
 }
 
 interface INsConfigHooks {