Deprecate global controller lookup

Author: tolyo

@types/core/controller/controller.d.ts

@@ -1,54 +1,46 @@
-export function identifierForController(controller: any, ident: any): string;
 /**
- * The {@link ng.$controller $controller service} is used by AngularTS to create new
- * controllers.
- *
- * This provider allows controller registration via the
- * {@link ng.$controllerProvider#register register} method.
+ * @param {string | InjectableController | undefined} controller
+ * @param {string} [ident]
+ * @returns {string|undefined}
  */
+export function identifierForController(
+  controller: string | InjectableController | undefined,
+  ident?: string,
+): string | undefined;
 export class ControllerProvider {
-  /**
-   * @type {Map<string, Function|Object>}
-   * @private
-   */
+  /** @type {Map<string, InjectableController>} @private */
   private controllers;
-  /**
-   * Check if a controller with a given name exists.
-   *
-   * @param {string} name Controller name to check.
-   * @returns {boolean} True if the controller exists, false otherwise.
-   */
+  /** @param {string} name @returns {boolean} */
   has(name: string): boolean;
   /**
-   * Register a controller.
-   *
-   * @param {string|Object} name Controller name, or an object map of controllers where the keys are
-   *    the names and the values are the constructors.
-   * @param {Function|Array} constructor Controller constructor function (optionally decorated with DI
-   *    annotations in the array notation).
+   * @param {string | Record<string, unknown>} name
+   * @param {unknown} [constructor]
    */
-  register(name: string | any, constructor: Function | any[]): void;
+  register(name: string | Record<string, unknown>, constructor?: unknown): void;
   /**
-   * $get method for dependency injection.
+   * @type {import("../../interface.ts").AnnotatedFactory<(injector: ng.InjectorService) => ControllerService>}
    */
-  $get: (
-    | string
-    | ((
-        $injector: ng.InjectorService,
-      ) => import("./interface.ts").ControllerService)
-  )[];
+  $get: import("../../interface.ts").AnnotatedFactory<
+    (injector: ng.InjectorService) => ControllerService
+  >;
   /**
-   * Adds an identifier to the controller instance in the given locals' scope.
-   *
-   * @param {Object} locals The locals object containing the scope.
-   * @param {string} identifier The identifier to assign.
-   * @param {Object} instance The controller instance.
-   * @param {string} name The name of the controller.
+   * @param {ControllerLocals | undefined} locals
+   * @param {string} identifier
+   * @param {object} instance
+   * @param {string} name
    */
   addIdentifier(
-    locals: any,
+    locals: ControllerLocals | undefined,
     identifier: string,
-    instance: any,
+    instance: object,
     name: string,
   ): void;
 }
+export type ControllerConstructor =
+  import("../../interface.ts").ControllerConstructor;
+export type InjectableController =
+  import("../../interface.ts").Injectable<ControllerConstructor>;
+export type ControllerService = import("./interface.ts").ControllerService;
+export type ControllerLocals = import("./interface.ts").ControllerLocals;
+export type ControllerExpression =
+  import("./interface.ts").ControllerExpression;

@types/core/controller/interface.d.ts

@@ -1,6 +1,11 @@
+import { ControllerConstructor, Injectable } from "../../interface.ts";
 export type ControllerService = (
-  expression: string | Function | ng.AnnotatedFactory<any>,
-  locals?: Record<string, any>,
+  expression: ControllerExpression,
+  locals?: ControllerLocals,
   later?: boolean,
   ident?: string,
 ) => object | (() => object);
+export type ControllerExpression = string | Injectable<ControllerConstructor>;
+export type ControllerLocals = Record<string, any> & {
+  $scope?: ng.Scope;
+};

src/core/controller/controller-design-notes.md

@@ -0,0 +1,186 @@
+# ControllerProvider — Design Notes
+
+## Purpose
+
+`ControllerProvider` implements AngularTS’s `$controller` mechanism. It is responsible for:
+
+- registering controller definitions during configuration
+- resolving controller expressions at runtime
+- instantiating controllers with DI support
+- supporting `ctrl as` syntax and explicit identifiers
+- optionally deferring instantiation (`later` mode)
+
+The design closely mirrors AngularJS semantics while tightening types and removing legacy behaviors (e.g. global/window lookup).
+
+---
+
+## Core Concepts
+
+### Controller Definition
+
+A **controller definition** is normalized at registration time into an:
+
+```
+Injectable<ControllerConstructor>
+```
+
+Supported forms:
+- constructor function
+- ES class
+- DI-annotated array (`['dep1', ..., ControllerFn]`)
+
+Unsupported:
+- plain objects
+- non-callables
+
+This invariant is enforced by `normalizeControllerDef()` and relied on everywhere else.
+
+---
+
+## Internal State
+
+### `controllers: Map<string, InjectableController>`
+
+- Keys are **literal controller names**
+- Values are **normalized injectables**
+- No fallback to `window` or dotted-path resolution
+- Dotted names (`"a.b.Ctrl"`) are treated as plain keys
+
+---
+
+## Registration Phase
+
+### `register(name, constructor)`
+
+Supports:
+- single controller registration
+- bulk registration
+
+Behavior:
+- controller names are validated
+- definitions are normalized eagerly
+- invalid definitions throw `ctrlreg`
+
+---
+
+## Runtime: `$controller` Service
+
+### Signature (conceptual)
+
+```
+$controller(expression, locals?, later?, ident?)
+  → instance | () => instance
+```
+
+### Expression Resolution
+
+If `expression` is a **string**:
+- must match `CNTRL_REG`
+- extracts controller name and optional `as` identifier
+- resolves only from the internal registry
+- throws `ctrlfmt` or `ctrlreg` on failure
+
+If `expression` is **not a string**:
+- treated as a controller injectable directly
+
+---
+
+## Controller Unwrapping
+
+### `unwrapController(injectable)`
+
+Central helper that:
+- extracts the underlying constructor function
+- asserts callability
+- exposes:
+  - `func`
+  - `prototype`
+  - `name`
+
+This removes duplicated logic and provides a single point of truth.
+
+---
+
+## Instantiation Modes
+
+### Normal Mode
+
+- controller instantiated immediately via `$injector.instantiate`
+- object/function return values replace the instance
+- primitive return values are ignored
+- identifier export happens after instantiation
+
+### Deferred Mode (`later === true`)
+
+- instance shell created via `Object.create(prototype)`
+- identifier export happens before invocation
+- returned function invokes the controller and may replace the instance
+- identifier is rebound if replacement occurs
+
+---
+
+## Identifier (`ctrl as`) Handling
+
+Sources of identifier (priority order):
+1. explicit `ident` argument
+2. `as` syntax in controller string
+
+Rules:
+- identifier requires `locals.$scope`
+- exports instance to scope and sets `$controllerIdentifier`
+- missing `$scope` throws `noscp`
+
+---
+
+## Locals Handling
+
+- `locals` is a DI locals map
+- `$scope` is optional unless exporting
+- locals override injectable dependencies
+- no implicit scope creation
+
+---
+
+## `$scopename` Propagation
+
+If a controller defines `$scopename`, it is propagated to `locals.$scope`
+in both normal and deferred modes when a scope is present.
+
+---
+
+## Error Semantics
+
+| Code     | Condition |
+|----------|-----------|
+| ctrlfmt  | malformed controller string |
+| ctrlreg  | unknown controller or invalid definition |
+| noscp    | identifier export without `$scope` |
+| badname  | illegal controller registration name |
+
+---
+
+## Design Invariants
+
+- controllers are always normalized
+- no global/window lookup
+- deferred mode preserves prototype semantics
+- identifier export is explicit and scoped
+
+---
+
+## Non-Goals
+
+- no object-literal controllers
+- no dotted-path resolution
+- no implicit scope creation
+- no silent fallbacks
+
+---
+
+## Summary
+
+`ControllerProvider` favors explicitness and predictability:
+- strict registration
+- centralized normalization
+- well-defined error cases
+- compatibility where it matters, simplicity everywhere else