refactor(cli): tree api with injectable logging (#276)

Updates the `tree.ts` APIs to use an injectable trace function, so that
it can easily be used from old and new code paths. At some point in the
future this should just take an `IoHelper`, but not now.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

---------

Signed-off-by: github-actions <[email protected]>
Co-authored-by: github-actions <[email protected]>

Author: mrgrain

packages/@aws-cdk/cli-plugin-contract/lib/index.ts

@@ -107,7 +107,7 @@ export interface CredentialProviderSource {
   /**
    * Construct a credential provider for the given account and the given access mode
    *
-   * Guaranteed to be called only if canProvideCredentails() returned true at some point.
+   * Guaranteed to be called only if canProvideCredentials() returned true at some point.
    *
    * While it is possible for the plugin to return a static set of credentials, it is
    * recommended to return a provider.

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/messages.ts

@@ -375,6 +375,11 @@ export const IO = {
   }),
 
   // Assembly codes
+  DEFAULT_ASSEMBLY_TRACE: make.trace({
+    code: 'CDK_ASSEMBLY_I0000',
+    description: 'Default trace messages emitted from Cloud Assembly operations',
+  }),
+
   CDK_ASSEMBLY_I0010: make.debug({
     code: 'CDK_ASSEMBLY_I0010',
     description: 'Generic environment preparation debug messages',

packages/@aws-cdk/toolkit-lib/docs/message-registry.md

@@ -73,6 +73,7 @@ group: Documents
 | `CDK_TOOLKIT_W0101` | A notice that is marked as a warning | `warn` | n/a |
 | `CDK_TOOLKIT_E0101` | A notice that is marked as an error | `error` | n/a |
 | `CDK_TOOLKIT_I0101` | A notice that is marked as informational | `info` | n/a |
+| `CDK_ASSEMBLY_I0000` | Default trace messages emitted from Cloud Assembly operations | `trace` | n/a |
 | `CDK_ASSEMBLY_I0010` | Generic environment preparation debug messages | `debug` | n/a |
 | `CDK_ASSEMBLY_W0010` | Emitted if the found framework version does not support context overflow | `warn` | n/a |
 | `CDK_ASSEMBLY_I0042` | Writing updated context | `debug` | {@link UpdatedContext} |

packages/@aws-cdk/toolkit-lib/lib/api/aws-cdk.ts

@@ -11,6 +11,7 @@ export { ResourceMigrator } from '../../../../aws-cdk/lib/api/resource-import';
 export { CloudWatchLogEventMonitor, findCloudWatchLogGroups } from '../../../../aws-cdk/lib/api/logs';
 export { type WorkGraph, WorkGraphBuilder, AssetBuildNode, AssetPublishNode, StackNode, Concurrency } from '../../../../aws-cdk/lib/api/work-graph';
 export { Bootstrapper } from '../../../../aws-cdk/lib/api/bootstrap';
+export { loadTree, some } from '../../../../aws-cdk/lib/api/tree';
 
 // Context Providers
 export * as contextproviders from '../../../../aws-cdk/lib/context-providers';
@@ -20,9 +21,6 @@ export { HotswapMode } from '../../../../aws-cdk/lib/api/hotswap/common';
 export { HotswapPropertyOverrides, EcsHotswapProperties } from '../../../../aws-cdk/lib/api/hotswap/common';
 export { RWLock, type ILock } from '../../../../aws-cdk/lib/api/util/rwlock';
 
-// @todo Not yet API probably should be
-export { loadTree, some } from '../../../../aws-cdk/lib/tree';
-
 // @todo Cloud Assembly and Executable - this is a messy API right now
 export { CloudAssembly, sanitizePatterns, StackCollection, ExtendedStackSelection } from '../../../../aws-cdk/lib/api/cxapp/cloud-assembly';
 export { prepareDefaultEnvironment, prepareContext, spaceAvailableForContext } from '../../../../aws-cdk/lib/api/cxapp/exec';

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/private/prepare-source.ts

@@ -130,8 +130,8 @@ export async function withContext<T>(
  *
  * @param assembly the assembly to check
  */
-export async function checkContextOverflowSupport(assembly: cxapi.CloudAssembly, ioHost: IoHelper): Promise<void> {
-  const tree = loadTree(assembly);
+export async function checkContextOverflowSupport(assembly: cxapi.CloudAssembly, ioHelper: IoHelper): Promise<void> {
+  const tree = loadTree(assembly, (msg: string) => void ioHelper.notify(IO.DEFAULT_ASSEMBLY_TRACE.msg(msg)));
   const frameworkDoesNotSupportContextOverflow = some(tree, node => {
     const fqn = node.constructInfo?.fqn;
     const version = node.constructInfo?.version;
@@ -142,7 +142,7 @@ export async function checkContextOverflowSupport(assembly: cxapi.CloudAssembly,
   // We're dealing with an old version of the framework here. It is unaware of the temporary
   // file, which means that it will ignore the context overflow.
   if (frameworkDoesNotSupportContextOverflow) {
-    await ioHost.notify(IO.CDK_ASSEMBLY_W0010.msg('Part of the context could not be sent to the application. Please update the AWS CDK library to the latest version.'));
+    await ioHelper.notify(IO.CDK_ASSEMBLY_W0010.msg('Part of the context could not be sent to the application. Please update the AWS CDK library to the latest version.'));
   }
 }
 

packages/aws-cdk/lib/api/cxapp/exec.ts

@@ -6,11 +6,11 @@ import * as cxapi from '@aws-cdk/cx-api';
 import * as fs from 'fs-extra';
 import * as semver from 'semver';
 import { ToolkitError } from '../../../../@aws-cdk/tmp-toolkit-helpers/src/api';
+import { loadTree, some } from '../../api/tree';
 import type { Configuration } from '../../cli/user-configuration';
 import { PROJECT_CONFIG, USER_DEFAULTS } from '../../cli/user-configuration';
 import { versionNumber } from '../../cli/version';
-import { debug, warning } from '../../logging';
-import { loadTree, some } from '../../tree';
+import { debug, trace, warning } from '../../logging';
 import { splitBySize } from '../../util';
 import type { SdkProvider } from '../aws-auth';
 import type { Settings } from '../settings';
@@ -293,7 +293,7 @@ function contextOverflowCleanup(location: string | undefined, assembly: cxapi.Cl
   if (location) {
     fs.removeSync(path.dirname(location));
 
-    const tree = loadTree(assembly);
+    const tree = loadTree(assembly, trace);
     const frameworkDoesNotSupportContextOverflow = some(tree, node => {
       const fqn = node.constructInfo?.fqn;
       const version = node.constructInfo?.version;

packages/aws-cdk/lib/tree.ts renamed to packages/aws-cdk/lib/api/tree.ts

@@ -1,7 +1,6 @@
-import * as path from 'path';
+import * as path from 'node:path';
 import type { CloudAssembly } from '@aws-cdk/cx-api';
 import * as fs from 'fs-extra';
-import { trace } from './logging';
 
 /**
  * Source information on a construct (class fqn and version)
@@ -37,7 +36,7 @@ export function some(node: ConstructTreeNode | undefined, predicate: (n: Constru
   }
 }
 
-export function loadTree(assembly: CloudAssembly): ConstructTreeNode | undefined {
+export function loadTree(assembly: CloudAssembly, trace: (msg: string) => void): ConstructTreeNode | undefined {
   try {
     const outdir = assembly.directory;
     const fileName = assembly.tree()?.file;
@@ -48,7 +47,7 @@ export function loadTree(assembly: CloudAssembly): ConstructTreeNode | undefined
   }
 }
 
-export function loadTreeFromDir(outdir: string): ConstructTreeNode | undefined {
+export function loadTreeFromDir(outdir: string, trace: (msg: string) => void): ConstructTreeNode | undefined {
   try {
     return fs.readJSONSync(path.join(outdir, 'tree.json')).tree;
   } catch (e) {

packages/aws-cdk/lib/notices.ts

@@ -8,10 +8,10 @@ import * as semver from 'semver';
 import type { SdkHttpOptions } from './api';
 import { AwsCliCompatible } from './api/aws-auth/awscli-compatible';
 import type { Context } from './api/context';
+import type { ConstructTreeNode } from './api/tree';
+import { loadTreeFromDir } from './api/tree';
 import type { IIoHost } from './cli/io-host';
 import { versionNumber } from './cli/version';
-import type { ConstructTreeNode } from './tree';
-import { loadTreeFromDir } from './tree';
 import { cdkCacheDir, formatErrorMessage } from './util';
 import { ToolkitError } from '../../@aws-cdk/tmp-toolkit-helpers/src/api';
 import { IO, asIoHelper, IoDefaultMessages } from '../../@aws-cdk/tmp-toolkit-helpers/src/api/io/private';
@@ -211,7 +211,7 @@ export class NoticesFilter {
    * Load the construct tree from the given directory and return its components
    */
   private constructTreeComponents(manifestDir: string): ActualComponent[] {
-    const tree = loadTreeFromDir(manifestDir);
+    const tree = loadTreeFromDir(manifestDir, (msg: string) => void this.ioMessages.notify(IO.DEFAULT_ASSEMBLY_TRACE.msg(msg)));
     if (!tree) {
       return [];
     }

packages/aws-cdk/test/tree.test.ts renamed to packages/aws-cdk/test/api/tree.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable import/order */
 import * as path from 'path';
-import { ConstructTreeNode, loadTreeFromDir, some } from '../lib/tree';
+import { ConstructTreeNode, loadTreeFromDir, some } from '../../lib/api/tree';
 
 describe('some', () => {
   const tree: ConstructTreeNode = {
@@ -104,12 +104,12 @@ describe('some', () => {
 
 describe('loadTreeFromDir', () => {
   test('can find tree', () => {
-    const tree = loadTreeFromDir(path.join(__dirname, 'cloud-assembly-trees', 'built-with-1_144_0'));
+    const tree = loadTreeFromDir(path.join(__dirname, '..', 'cloud-assembly-trees', 'built-with-1_144_0'), () => {});
     expect(tree?.id).toEqual('App');
   });
 
   test('cannot find tree', () => {
-    const tree = loadTreeFromDir(path.join(__dirname, 'cloud-assembly-trees', 'foo'));
+    const tree = loadTreeFromDir(path.join(__dirname, '..', 'cloud-assembly-trees', 'foo'), () => {});
     expect(tree).toEqual(undefined);
   });
 });

packages/aws-cdk/test/notices.test.ts

@@ -786,7 +786,9 @@ describe(Notices, () => {
 
     test('nothing when there are no notices', async () => {
       Notices.create({ ioHost, context: new Context() }).display();
-      expect(ioHost.messages).toEqual([]);
+      // expect a single trace that the tree.json was not found, but nothing else
+      expect(ioHost.messages.length).toBe(1);
+      ioHost.expectMessage({ level: 'trace', containing: 'Failed to get tree.json file' });
     });
 
     test('total count when show total is true', async () => {