fix(@angular-devkit/schematics): update Rule type to support returning a Promise of Tree

The `Rule` type has been updated to align with its intended functionality, allowing it to return a `Promise<Tree>`. Previously, this behavior was supported but not properly typed.

Closes #22783

(cherry picked from commit 4f80308)

Author: alan-agius4

goldens/public-api/angular_devkit/schematics/index.api.md

@@ -722,7 +722,7 @@ interface RequiredWorkflowExecutionContext {
 }
 
 // @public (undocumented)
-export type Rule = (tree: Tree_2, context: SchematicContext) => Tree_2 | Observable<Tree_2> | Rule | Promise<void | Rule> | void;
+export type Rule = (tree: Tree_2, context: SchematicContext) => Tree_2 | Observable<Tree_2> | Rule | Promise<void | Tree_2 | Rule> | void;
 
 // @public
 export type RuleFactory<T extends object> = (options: T) => Rule;

packages/angular_devkit/schematics/src/engine/interface.ts

@@ -236,4 +236,4 @@ export type Source = (context: SchematicContext) => Tree | Observable<Tree>;
 export type Rule = (
   tree: Tree,
   context: SchematicContext,
-) => Tree | Observable<Tree> | Rule | Promise<void | Rule> | void;
+) => Tree | Observable<Tree> | Rule | Promise<void | Tree | Rule> | void;

packages/angular_devkit/schematics/src/rules/base_spec.ts

@@ -47,6 +47,29 @@ describe('chain', () => {
       .then(done, done.fail);
   });
 
+  it('works with async rules', (done) => {
+    const rulesCalled: Tree[] = [];
+
+    const tree0 = empty();
+    const tree1 = empty();
+    const tree2 = empty();
+    const tree3 = empty();
+
+    const rule0: Rule = async (tree: Tree) => ((rulesCalled[0] = tree), tree1);
+    const rule1: Rule = async (tree: Tree) => ((rulesCalled[1] = tree), tree2);
+    const rule2: Rule = async (tree: Tree) => ((rulesCalled[2] = tree), tree3);
+
+    lastValueFrom(callRule(chain([rule0, rule1, rule2]), tree0, context))
+      .then((result) => {
+        expect(result).not.toBe(tree0);
+        expect(rulesCalled[0]).toBe(tree0);
+        expect(rulesCalled[1]).toBe(tree1);
+        expect(rulesCalled[2]).toBe(tree2);
+        expect(result).toBe(tree3);
+      })
+      .then(done, done.fail);
+  });
+
   it('works with a sync generator of rules', async () => {
     const rulesCalled: Tree[] = [];