feat(metadata): apply native-api-usage.json rules in metadata trim

Declared rules are merged with what the bundle analysis finds, following
the same whitelist-plugins-usages semantics as ns prepare. Projects are
read automatically for iOS and Android; other hosts pass --native-api-usage.

Author: NathanWalker

docs/man_pages/project/configuration/metadata-trim.md

@@ -9,6 +9,8 @@ position: 26
 
 Reduces the native API metadata an app ships to what its JavaScript uses. The app's emitted bundle is analyzed for the native symbols it references, and the generator keeps those plus the types they depend on.
 
+Rules in `native-api-usage.json` still apply. Entries from `whitelist` and from plugins' `uses` are kept in addition to what the analysis finds, and `blacklist` entries are removed. A blacklisted type that a kept API's signature needs can't be removed: on Apple platforms it stays in the metadata, and on Android the build fails and names it. In a NativeScript project these files are found automatically for iOS and Android; other hosts pass them with `--native-api-usage`.
+
 If the bundle reads globals dynamically (an alias of `globalThis`, for example), its usage cannot be determined and nothing is trimmed.
 
 ### Commands
@@ -27,6 +29,7 @@ Write the whitelist for an Android project | `$ ns metadata trim android <Bundle
 
 * `--out` - Output directory. Defaults to `metadata-trim`.
 * `--keep` - A `Module:Symbol` pattern to keep regardless of the analysis. Repeat for several.
+* `--native-api-usage` - A `native-api-usage.json` file to apply, in the app or plugin format. Repeat for several.
 * `--analyzer` - `ns-metadata-symbols` on Apple platforms; overrides the runtime's `seed.js` on Android.
 * `--generator` - `objc-metadata-generator`. Use the one from the runtime release the app ships.
 * `--framework` - A `NativeScript.framework` to copy into the output directory with the trimmed metadata embedded.

lib/commands/metadata-trim.ts

@@ -6,13 +6,21 @@ import {
 	stringOption,
 } from "../common/define-command";
 import { inject } from "../common/di";
-import { IMetadataTrimService } from "../definitions/metadata-trim-service";
+import { IMetadataFilteringService } from "../definitions/metadata-filtering-service";
+import {
+	IDeclaredMetadataRules,
+	IMetadataTrimService,
+} from "../definitions/metadata-trim-service";
+import { IProjectData } from "../definitions/project";
+import { IProjectHelper } from "../common/declarations";
+import { readDeclaredRules } from "../services/metadata-trim/declared-rules";
 
 const PLATFORMS = ["ios", "macos", "android"];
 
 const metadataTrimOptions = {
 	out: stringOption(),
 	keep: arrayOption(),
+	nativeApiUsage: arrayOption(),
 	analyzer: stringOption(),
 	generator: stringOption(),
 	framework: stringOption(),
@@ -37,9 +45,14 @@ export class MetadataTrimCommand extends Command({
 	params: "any",
 }) {
 	private $logger = inject<ILogger>("logger");
+	private $metadataFilteringService = inject<IMetadataFilteringService>(
+		"metadataFilteringService",
+	);
 	private $metadataTrimService = inject<IMetadataTrimService>(
 		"metadataTrimService",
 	);
+	private $projectData = inject<IProjectData>("projectData");
+	private $projectHelper = inject<IProjectHelper>("projectHelper");
 
 	public canExecute(): boolean {
 		const [platform, ...bundles] = this.args;
@@ -57,11 +70,13 @@ export class MetadataTrimCommand extends Command({
 	public async run(): Promise<void> {
 		const [platform, ...bundles] = this.args;
 		const options = this.options;
+		const declared = this.declaredRules(platform.toLowerCase());
 		const result = await this.$metadataTrimService.trim({
 			platform: platform.toLowerCase(),
 			bundles: bundles.map((bundle) => path.resolve(bundle)),
 			outDir: path.resolve(options.out ?? "metadata-trim"),
-			keep: options.keep ?? [],
+			keep: [...(options.keep ?? []), ...declared.keep],
+			blacklist: declared.blacklist,
 			analyzerPath: resolved(options.analyzer),
 			generatorPath: resolved(options.generator),
 			framework: resolved(options.framework),
@@ -71,6 +86,11 @@ export class MetadataTrimCommand extends Command({
 			minVersion: options.minVersion,
 		});
 
+		if (declared.keep.length || declared.blacklist.length) {
+			this.$logger.info(
+				`Applied native-api-usage.json: ${declared.keep.length} kept, ${declared.blacklist.length} removed.`,
+			);
+		}
 		if (result.metadataBytes !== undefined) {
 			this.$logger.info(
 				`Generated ${formatBytes(result.metadataBytes)} of metadata: ${result.metadataPath}`,
@@ -86,4 +106,24 @@ export class MetadataTrimCommand extends Command({
 			this.$logger.info(result.nextStep);
 		}
 	}
+
+	private declaredRules(platform: string): IDeclaredMetadataRules {
+		const files = (this.options.nativeApiUsage ?? []).map((file) =>
+			readDeclaredRules(path.resolve(file)),
+		);
+		// A standard project's files only exist for iOS and Android.
+		if (this.$projectHelper.projectDir && platform !== "macos") {
+			this.$projectData.initializeProjectData();
+			files.push(
+				this.$metadataFilteringService.getDeclaredRules(
+					this.$projectData,
+					platform,
+				),
+			);
+		}
+		return {
+			keep: files.flatMap((rules) => rules.keep),
+			blacklist: files.flatMap((rules) => rules.blacklist),
+		};
+	}
 }

lib/definitions/metadata-filtering-service.d.ts

@@ -1,4 +1,5 @@
 import { IProjectData } from "./project";
+import { IDeclaredMetadataRules } from "./metadata-trim-service";
 
 /**
  * Describes service used to generate necessary files to filter the native metadata generation.
@@ -45,4 +46,15 @@ interface IMetadataFilteringService {
 	 * @returns {void}
 	 */
 	generateMetadataFilters(projectData: IProjectData, platform: string): void;
+
+	/**
+	 * Reads the rules the app and its plugins declare in native-api-usage.json.
+	 * @param {IProjectData} projectData Information about the current project.
+	 * @param {string} platform The platform to read rules for.
+	 * @returns {IDeclaredMetadataRules} The patterns to keep and to remove.
+	 */
+	getDeclaredRules(
+		projectData: IProjectData,
+		platform: string,
+	): IDeclaredMetadataRules;
 }

lib/definitions/metadata-trim-service.d.ts

@@ -6,6 +6,8 @@ export interface IMetadataTrimOptions {
 	outDir: string;
 	/** Filter patterns (`Module:Symbol`) to keep regardless of what is found. */
 	keep: string[];
+	/** Filter patterns to remove even if the app references them. */
+	blacklist?: string[];
 	analyzerPath?: string;
 	generatorPath?: string;
 	/** A NativeScript.framework to embed the trimmed metadata into. */
@@ -17,6 +19,12 @@ export interface IMetadataTrimOptions {
 	minVersion?: string;
 }
 
+/** What native-api-usage.json files declare, as filter patterns. */
+export interface IDeclaredMetadataRules {
+	keep: string[];
+	blacklist: string[];
+}
+
 /** The native symbols an app's JavaScript can reach. */
 export interface IMetadataUsage {
 	whitelistPath: string;

lib/services/metadata-filtering-service.ts

@@ -4,6 +4,8 @@ import { MetadataFilteringConstants } from "../constants";
 import { IPluginsService } from "../definitions/plugins";
 import { IPlatformsDataService } from "../definitions/platform";
 import { IProjectData } from "../definitions/project";
+import { IDeclaredMetadataRules } from "../definitions/metadata-trim-service";
+import { mergeDeclaredRules } from "./metadata-trim/declared-rules";
 import {
 	IMetadataFilteringService,
 	INativeApiUsageConfiguration,
@@ -18,43 +20,66 @@ export class MetadataFilteringService implements IMetadataFilteringService {
 		private $pluginsService: IPluginsService,
 		private $mobileHelper: Mobile.IMobileHelper,
 		private $platformsDataService: IPlatformsDataService,
-		private $logger: ILogger
+		private $logger: ILogger,
 	) {}
 
 	public generateMetadataFilters(
 		projectData: IProjectData,
-		platform: string
+		platform: string,
 	): void {
 		this.generateWhitelist(projectData, platform);
 		this.generateBlacklist(projectData, platform);
 	}
 
+	public getDeclaredRules(
+		projectData: IProjectData,
+		platform: string,
+	): IDeclaredMetadataRules {
+		const pluginConfigurations = this.$pluginsService
+			.getAllProductionPlugins(projectData, platform)
+			.map((plugin) =>
+				path.join(
+					plugin.pluginPlatformsFolderPath(platform),
+					MetadataFilteringConstants.NATIVE_API_USAGE_FILE_NAME,
+				),
+			)
+			.filter((configPath) => this.$fs.exists(configPath))
+			.map(
+				(configPath): INativeApiUsagePluginConfiguration =>
+					this.$fs.readJson(configPath) || {},
+			);
+
+		return mergeDeclaredRules(
+			this.getNativeApiConfigurationForPlatform(projectData, platform),
+			pluginConfigurations,
+		);
+	}
+
 	private generateWhitelist(projectData: IProjectData, platform: string): void {
 		const platformsDirPath = this.getPlatformsDirPath(projectData, platform);
 		const pathToWhitelistFile = path.join(
 			platformsDirPath,
-			MetadataFilteringConstants.WHITELIST_FILE_NAME
+			MetadataFilteringConstants.WHITELIST_FILE_NAME,
 		);
 		this.$fs.deleteFile(pathToWhitelistFile);
 
 		const nativeApiConfiguration = this.getNativeApiConfigurationForPlatform(
 			projectData,
-			platform
+			platform,
 		);
 		if (nativeApiConfiguration) {
 			const whitelistedItems: string[] = [];
 			if (nativeApiConfiguration["whitelist-plugins-usages"]) {
 				const plugins = this.$pluginsService.getAllProductionPlugins(
 					projectData,
-					platform
+					platform,
 				);
 				for (const pluginData of plugins) {
-					const pathToPlatformsDir = pluginData.pluginPlatformsFolderPath(
-						platform
-					);
+					const pathToPlatformsDir =
+						pluginData.pluginPlatformsFolderPath(platform);
 					const pathToPluginsMetadataConfig = path.join(
 						pathToPlatformsDir,
-						MetadataFilteringConstants.NATIVE_API_USAGE_FILE_NAME
+						MetadataFilteringConstants.NATIVE_API_USAGE_FILE_NAME,
 					);
 					if (this.$fs.exists(pathToPluginsMetadataConfig)) {
 						const pluginConfig: INativeApiUsagePluginConfiguration =
@@ -63,17 +88,17 @@ export class MetadataFilteringService implements IMetadataFilteringService {
 							`Adding content of ${pathToPluginsMetadataConfig} to whitelisted items of metadata filtering: ${JSON.stringify(
 								pluginConfig,
 								null,
-								2
-							)}`
+								2,
+							)}`,
 						);
 						const itemsToAdd = pluginConfig.uses || [];
 						if (itemsToAdd.length) {
 							whitelistedItems.push(
-								`// Added from: ${pathToPluginsMetadataConfig}`
+								`// Added from: ${pathToPluginsMetadataConfig}`,
 							);
 							whitelistedItems.push(...itemsToAdd);
 							whitelistedItems.push(
-								`// Finished part from ${pathToPluginsMetadataConfig}${os.EOL}`
+								`// Finished part from ${pathToPluginsMetadataConfig}${os.EOL}`,
 							);
 						}
 					}
@@ -87,8 +112,8 @@ export class MetadataFilteringService implements IMetadataFilteringService {
 					`Adding content from application to whitelisted items of metadata filtering: ${JSON.stringify(
 						applicationWhitelistedItems,
 						null,
-						2
-					)}`
+						2,
+					)}`,
 				);
 
 				whitelistedItems.push(`// Added from application`);
@@ -106,28 +131,27 @@ export class MetadataFilteringService implements IMetadataFilteringService {
 		const platformsDirPath = this.getPlatformsDirPath(projectData, platform);
 		const pathToBlacklistFile = path.join(
 			platformsDirPath,
-			MetadataFilteringConstants.BLACKLIST_FILE_NAME
+			MetadataFilteringConstants.BLACKLIST_FILE_NAME,
 		);
 		this.$fs.deleteFile(pathToBlacklistFile);
 
 		const nativeApiConfiguration = this.getNativeApiConfigurationForPlatform(
 			projectData,
-			platform
+			platform,
 		);
 		if (nativeApiConfiguration) {
 			const blacklistedItems: string[] = nativeApiConfiguration.blacklist || [];
 			if (nativeApiConfiguration["whitelist-plugins-usages"]) {
 				const plugins = this.$pluginsService.getAllProductionPlugins(
 					projectData,
-					platform
+					platform,
 				);
 				for (const pluginData of plugins) {
-					const pathToPlatformsDir = pluginData.pluginPlatformsFolderPath(
-						platform
-					);
+					const pathToPlatformsDir =
+						pluginData.pluginPlatformsFolderPath(platform);
 					const pathToPluginsMetadataConfig = path.join(
 						pathToPlatformsDir,
-						MetadataFilteringConstants.NATIVE_API_USAGE_FILE_NAME
+						MetadataFilteringConstants.NATIVE_API_USAGE_FILE_NAME,
 					);
 					if (this.$fs.exists(pathToPluginsMetadataConfig)) {
 						const pluginConfig: INativeApiUsagePluginConfiguration =
@@ -136,17 +160,17 @@ export class MetadataFilteringService implements IMetadataFilteringService {
 							`Adding content of ${pathToPluginsMetadataConfig} to whitelisted items of metadata filtering: ${JSON.stringify(
 								pluginConfig,
 								null,
-								2
-							)}`
+								2,
+							)}`,
 						);
 						const itemsToAdd = pluginConfig.blacklist || [];
 						if (itemsToAdd.length) {
 							blacklistedItems.push(
-								`// Added from: ${pathToPluginsMetadataConfig}`
+								`// Added from: ${pathToPluginsMetadataConfig}`,
 							);
 							blacklistedItems.push(...itemsToAdd);
 							blacklistedItems.push(
-								`// Finished part from ${pathToPluginsMetadataConfig}${os.EOL}`
+								`// Finished part from ${pathToPluginsMetadataConfig}${os.EOL}`,
 							);
 						}
 					}
@@ -157,20 +181,18 @@ export class MetadataFilteringService implements IMetadataFilteringService {
 			}
 		} else {
 			this.$logger.trace(
-				`There's no application configuration for metadata filtering for platform ${platform}. Full metadata will be generated.`
+				`There's no application configuration for metadata filtering for platform ${platform}. Full metadata will be generated.`,
 			);
 		}
 	}
 
 	private getNativeApiConfigurationForPlatform(
 		projectData: IProjectData,
-		platform: string
+		platform: string,
 	): INativeApiUsageConfiguration {
 		let config: INativeApiUsageConfiguration = null;
-		const pathToApplicationConfigurationFile = this.getPathToApplicationConfigurationForPlatform(
-			projectData,
-			platform
-		);
+		const pathToApplicationConfigurationFile =
+			this.getPathToApplicationConfigurationForPlatform(projectData, platform);
 		if (this.$fs.exists(pathToApplicationConfigurationFile)) {
 			config = this.$fs.readJson(pathToApplicationConfigurationFile);
 		}
@@ -180,23 +202,23 @@ export class MetadataFilteringService implements IMetadataFilteringService {
 
 	private getPlatformsDirPath(
 		projectData: IProjectData,
-		platform: string
+		platform: string,
 	): string {
 		const platformData = this.$platformsDataService.getPlatformData(
 			platform,
-			projectData
+			projectData,
 		);
 		return platformData.projectRoot;
 	}
 
 	private getPathToApplicationConfigurationForPlatform(
 		projectData: IProjectData,
-		platform: string
+		platform: string,
 	): string {
 		return path.join(
 			projectData.appResourcesDirectoryPath,
 			this.$mobileHelper.normalizePlatformName(platform),
-			MetadataFilteringConstants.NATIVE_API_USAGE_FILE_NAME
+			MetadataFilteringConstants.NATIVE_API_USAGE_FILE_NAME,
 		);
 	}
 }

lib/services/metadata-trim/android-toolchain.ts

@@ -11,6 +11,7 @@ import { readFilterPatterns } from "./apple-toolchain";
 
 const SEED_SCRIPT = path.join("build-tools", "metadata-filter", "seed.js");
 const WHITELIST_NAME = "whitelist.mdg";
+const BLACKLIST_NAME = "blacklist.mdg";
 
 /** Android's metadata generator runs in Gradle; this produces its whitelist. */
 export class AndroidMetadataToolchain implements IMetadataToolchain {
@@ -82,6 +83,12 @@ export class AndroidMetadataToolchain implements IMetadataToolchain {
 	> {
 		const installedTo = path.join(options.androidProject, WHITELIST_NAME);
 		fs.copyFileSync(usage.whitelistPath, installedTo);
+		if (options.blacklist?.length) {
+			fs.writeFileSync(
+				path.join(options.androidProject, BLACKLIST_NAME),
+				options.blacklist.join("\n") + "\n",
+			);
+		}
 		return {
 			installedTo,
 			// Without this flag Gradle filters by the list as written, dropping