refactor(yok): split the facade surface into subsystem contracts

IInjector recomposes from per-subsystem faces - CommandRegistry,
KeyCommandRegistry, ModuleRegistry, PublicApiBuilder - each an @contract
token the facade registers itself under. One object still implements
everything until the subsystems are physically extracted; extraction
then becomes a provider swap for the face's token instead of a consumer
migration. Consumers can depend on the narrow face they actually use,
and deprecation becomes per-face instead of a flat everything-is-legacy.

The contracts are internal (lib/common/contracts) and deliberately not
re-exported from nativescript/contracts; promoting one is a per-contract
decision.

Author: edusperoni

lib/common/contracts/command-registry.ts

@@ -0,0 +1,31 @@
+import { Contract } from "../di/contract";
+import type { ICommand } from "../definitions/commands";
+
+/**
+ * The command-registry face of the injector facade. Transitional contract: it
+ * mirrors what consumers call today, so that extracting the registry from the
+ * facade later is a provider swap for this token, not a consumer migration.
+ * Members slated for replacement keep their deprecation markers.
+ */
+@Contract({ name: "commandRegistry" })
+export abstract class CommandRegistry {
+	/**
+	 * @deprecated Path-based command registration; slated for replacement by
+	 * manifest-declared commands.
+	 */
+	abstract requireCommand(names: string | string[], file: string): void;
+	abstract registerCommand(names: string | string[], resolver: any): void;
+	abstract resolveCommand(name: string): ICommand;
+	abstract getRegisteredCommandsNames(includeDev: boolean): string[];
+	abstract getChildrenCommandsNames(commandName: string): string[];
+	abstract buildHierarchicalCommand(
+		parentCommandName: string,
+		commandLineArguments: string[],
+	): any;
+	/** Side-effecting: fails with help output on a bad subcommand. */
+	abstract isValidHierarchicalCommand(
+		commandName: string,
+		commandArguments: string[],
+	): Promise<boolean>;
+	abstract isDefaultCommand(commandName: string): boolean;
+}

lib/common/contracts/index.ts

@@ -0,0 +1,10 @@
+// Internal subsystem contracts of the injector facade. Deliberately NOT
+// re-exported from nativescript/contracts: promoting one to the public
+// surface is a one-line decision that should be made per contract, not by
+// default. Each token resolves to the facade itself until its subsystem is
+// physically extracted — at which point the provider is swapped and consumers
+// keep working unchanged.
+export { CommandRegistry } from "./command-registry";
+export { KeyCommandRegistry } from "./key-command-registry";
+export { ModuleRegistry } from "./module-registry";
+export { PublicApiBuilder } from "./public-api-builder";

lib/common/contracts/key-command-registry.ts

@@ -0,0 +1,15 @@
+import { Contract } from "../di/contract";
+import type { IKeyCommand, IValidKeyName } from "../definitions/key-commands";
+
+/**
+ * The key-command face of the injector facade (the `keyCommands.` namespace).
+ * Kept separate from CommandRegistry because the two registries are redesigned
+ * on different tracks.
+ */
+@Contract({ name: "keyCommandRegistry" })
+export abstract class KeyCommandRegistry {
+	abstract requireKeyCommand(name: IValidKeyName, file: string): void;
+	abstract registerKeyCommand(name: IValidKeyName, resolver: any): void;
+	abstract resolveKeyCommand(name: string): IKeyCommand;
+	abstract getRegisteredKeyCommandsNames(): string[];
+}

lib/common/contracts/module-registry.ts

@@ -0,0 +1,13 @@
+import { Contract } from "../di/contract";
+
+/**
+ * @deprecated The lazy module-loader face of the injector facade — the
+ * require-time path map. Wholly replaced by provideLazy(); this contract
+ * exists so its remaining consumers are typed against exactly what they use
+ * until the bootstrap migrates.
+ */
+@Contract({ name: "moduleRegistry" })
+export abstract class ModuleRegistry {
+	abstract require(names: string | string[], file: string): void;
+	abstract overrideAlreadyRequiredModule: boolean;
+}

lib/common/contracts/public-api-builder.ts

@@ -0,0 +1,13 @@
+import { Contract } from "../di/contract";
+
+/**
+ * The public-API-builder face of the injector facade: the machinery behind
+ * `require('nativescript')`. Bound by the compatibility constraints of the
+ * published library surface; do not add new entries through it.
+ */
+@Contract({ name: "publicApiBuilder" })
+export abstract class PublicApiBuilder {
+	abstract requirePublic(names: string | string[], file: string): void;
+	abstract requirePublicClass(names: string | string[], file: string): void;
+	abstract publicApi: any;
+}

lib/common/definitions/yok.d.ts

@@ -1,46 +1,24 @@
 import { IDictionary } from "../declarations";
-import { ICommand } from "./commands";
-import { IKeyCommand, IValidKeyName } from "./key-commands";
 import { Injector } from "../di/injector";
 import { Provider } from "../di/providers";
+import { CommandRegistry } from "../contracts/command-registry";
+import { KeyCommandRegistry } from "../contracts/key-command-registry";
+import { ModuleRegistry } from "../contracts/module-registry";
+import { PublicApiBuilder } from "../contracts/public-api-builder";
 
 /**
  * The legacy injector facade surface. It extends the token-based `Injector` —
  * the facade IS an injector — and adds the legacy subsystems, whose members
  * are individually @deprecated. Only the `Yok` class hierarchy implements
  * this; the interface survives until the hook/extension deprecation completes.
  */
-interface IInjector extends Injector {
-	/**
-	 * @deprecated Use provideLazy() — the same deferred loading, token-based.
-	 */
-	require(name: string, file: string): void;
-	/**
-	 * @deprecated Use provideLazy() — the same deferred loading, token-based.
-	 */
-	require(names: string[], file: string): void;
-	/**
-	 * @deprecated Legacy public-API builder.
-	 */
-	requirePublic(names: string | string[], file: string): void;
-	/**
-	 * @deprecated Legacy public-API builder.
-	 */
-	requirePublicClass(names: string | string[], file: string): void;
-	/**
-	 * @deprecated Path-based command registration; slated for replacement by
-	 * manifest-declared commands.
-	 */
-	requireCommand(name: string, file: string): void;
-	/**
-	 * @deprecated Path-based command registration; slated for replacement by
-	 * manifest-declared commands.
-	 */
-	requireCommand(names: string[], file: string): void;
-	/**
-	 * @deprecated Replaced together with the command registry.
-	 */
-	requireKeyCommand(name: IValidKeyName, file: string): void;
+interface IInjector
+	extends
+		Injector,
+		CommandRegistry,
+		KeyCommandRegistry,
+		ModuleRegistry,
+		PublicApiBuilder {
 	/**
 	 * Resolves an implementation by constructor function.
 	 * The injector will create new instances for every call.
@@ -62,43 +40,12 @@ interface IInjector extends Injector {
 	 */
 	resolve<T>(name: string, ctorArguments?: IDictionary<any>): T;
 
-	/**
-	 * @deprecated Legacy command-registry lookup.
-	 */
-	resolveCommand(name: string): ICommand;
-	/**
-	 * @deprecated Legacy command-registry lookup.
-	 */
-	resolveKeyCommand(key: string): IKeyCommand;
 	/**
 	 * @deprecated Legacy name-based registration. Use the Provider overload or
 	 * provide(); a contract's token name keeps string spellings resolvable.
 	 */
 	register(name: string, resolver: any, shared?: boolean): void;
 	register(providers: Provider | Provider[]): void;
-	/**
-	 * @deprecated Slated for replacement by defineCommand and manifest-declared
-	 * commands.
-	 */
-	registerCommand(name: string, resolver: any): void;
-	/**
-	 * @deprecated Slated for replacement by defineCommand and manifest-declared
-	 * commands.
-	 */
-	registerCommand(names: string[], resolver: any): void;
-	/**
-	 * @deprecated Replaced together with the command registry.
-	 */
-	registerKeyCommand(key: IValidKeyName, resolver: any): void;
-	/**
-	 * @deprecated Legacy command-registry enumeration; feeds shell
-	 * autocompletion and help.
-	 */
-	getRegisteredCommandsNames(includeDev: boolean): string[];
-	/**
-	 * @deprecated Legacy command-registry enumeration.
-	 */
-	getRegisteredKeyCommandsNames(): string[];
 	/**
 	 * @deprecated String-reflective help templating; removable only together
 	 * with the help-template pipeline.
@@ -108,43 +55,6 @@ interface IInjector extends Injector {
 	 * @deprecated See dynamicCallRegex.
 	 */
 	dynamicCall(call: string, args?: any[]): Promise<any>;
-	/**
-	 * @deprecated Legacy command-registry routing.
-	 */
-	isDefaultCommand(commandName: string): boolean;
-	/**
-	 * @deprecated Legacy command-registry routing.
-	 * Side-effecting: fails with help output on a bad subcommand.
-	 */
-	isValidHierarchicalCommand(
-		commandName: string,
-		commandArguments: string[],
-	): Promise<boolean>;
-	/**
-	 * @deprecated Legacy command-registry routing.
-	 */
-	getChildrenCommandsNames(commandName: string): string[];
-	/**
-	 * @deprecated Hierarchical-routing internals of the legacy command
-	 * registry.
-	 */
-	buildHierarchicalCommand(
-		parentCommandName: string,
-		commandLineArguments: string[],
-	): any;
-	/**
-	 * @deprecated Backing store of the require('nativescript') surface.
-	 * Do not add new entries through it.
-	 */
-	publicApi: any;
-
-	/**
-	 * Defines if it's allowed to override already required module.
-	 * This can be used in order to allow redefinition of modules, for example $logger can be replaced by a plugin.
-	 * Default value is false.
-	 * @deprecated Escape hatch of the legacy require-time module map.
-	 */
-	overrideAlreadyRequiredModule: boolean;
 }
 
 /**

lib/common/yok.ts

@@ -10,6 +10,12 @@ import { ICommandArgument, ICommand } from "./definitions/commands";
 import { IKeyCommand, IValidKeyName } from "./definitions/key-commands";
 import { Injector } from "./di/injector";
 import type { Provider } from "./di/providers";
+import {
+	CommandRegistry,
+	KeyCommandRegistry,
+	ModuleRegistry,
+	PublicApiBuilder,
+} from "./contracts";
 
 /**
  * The legacy global facade binding. New code should obtain the container via
@@ -63,6 +69,15 @@ export class Yok extends Injector implements IInjector {
 	constructor() {
 		super();
 		this.register("injector", this);
+		// Each subsystem face resolves to the facade until it is physically
+		// extracted; extraction then swaps the provider without touching
+		// consumers of the token.
+		this.register([
+			{ provide: CommandRegistry, useValue: this },
+			{ provide: KeyCommandRegistry, useValue: this },
+			{ provide: ModuleRegistry, useValue: this },
+			{ provide: PublicApiBuilder, useValue: this },
+		]);
 	}
 
 	private COMMANDS_NAMESPACE: string = "commands";

test/compat/injector-facade-surface.ts

@@ -1,6 +1,12 @@
 import { assert } from "chai";
 import { Yok } from "../../lib/common/yok";
 import { Injector, inject, runInInjectionContext } from "../../lib/common/di";
+import {
+	CommandRegistry,
+	KeyCommandRegistry,
+	ModuleRegistry,
+	PublicApiBuilder,
+} from "../../lib/common/contracts";
 
 // Pins the externally reachable injector surface: every IInjector member
 // (lib/common/definitions/yok.d.ts) plus dispose, subclassability, the
@@ -84,6 +90,24 @@ describe("injector facade surface", () => {
 		});
 	});
 
+	it("registers its subsystem faces as tokens that resolve to the facade", () => {
+		const inj = new Yok();
+
+		for (const token of [
+			CommandRegistry,
+			KeyCommandRegistry,
+			ModuleRegistry,
+			PublicApiBuilder,
+		]) {
+			assert.strictEqual(inj.get(<any>token), inj);
+		}
+		assert.strictEqual(inj.resolve("commandRegistry"), inj);
+
+		runInInjectionContext(inj, () => {
+			assert.strictEqual(inject(CommandRegistry), inj);
+		});
+	});
+
 	it("calls lowercase/anonymous resolvers as factories instead of new-ing them", () => {
 		const inj = new Yok();
 		inj.register("factoryMade", function () {