refactor(toolkit): split notices code into separate files (#445)

No code changes. This is in preparation of #399 to make the diff more
manageable.

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

Author: mrgrain

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

@@ -0,0 +1,74 @@
+import * as fs from 'fs-extra';
+import type { Notice, NoticeDataSource } from './types';
+import type { IoDefaultMessages } from '../io/private';
+
+interface CachedNotices {
+  expiration: number;
+  notices: Notice[];
+}
+
+const TIME_TO_LIVE_SUCCESS = 60 * 60 * 1000; // 1 hour
+const TIME_TO_LIVE_ERROR = 1 * 60 * 1000; // 1 minute
+
+export class CachedDataSource implements NoticeDataSource {
+  constructor(
+    private readonly ioMessages: IoDefaultMessages,
+    private readonly fileName: string,
+    private readonly dataSource: NoticeDataSource,
+    private readonly skipCache?: boolean) {
+  }
+
+  async fetch(): Promise<Notice[]> {
+    const cachedData = await this.load();
+    const data = cachedData.notices;
+    const expiration = cachedData.expiration ?? 0;
+
+    if (Date.now() > expiration || this.skipCache) {
+      const freshData = await this.fetchInner();
+      await this.save(freshData);
+      return freshData.notices;
+    } else {
+      this.ioMessages.debug(`Reading cached notices from ${this.fileName}`);
+      return data;
+    }
+  }
+
+  private async fetchInner(): Promise<CachedNotices> {
+    try {
+      return {
+        expiration: Date.now() + TIME_TO_LIVE_SUCCESS,
+        notices: await this.dataSource.fetch(),
+      };
+    } catch (e) {
+      this.ioMessages.debug(`Could not refresh notices: ${e}`);
+      return {
+        expiration: Date.now() + TIME_TO_LIVE_ERROR,
+        notices: [],
+      };
+    }
+  }
+
+  private async load(): Promise<CachedNotices> {
+    const defaultValue = {
+      expiration: 0,
+      notices: [],
+    };
+
+    try {
+      return fs.existsSync(this.fileName)
+        ? await fs.readJSON(this.fileName) as CachedNotices
+        : defaultValue;
+    } catch (e) {
+      this.ioMessages.debug(`Failed to load notices from cache: ${e}`);
+      return defaultValue;
+    }
+  }
+
+  private async save(cached: CachedNotices): Promise<void> {
+    try {
+      await fs.writeJSON(this.fileName, cached);
+    } catch (e) {
+      this.ioMessages.debug(`Failed to store notices in the cache: ${e}`);
+    }
+  }
+}

packages/@aws-cdk/toolkit-lib/lib/api/notices/cached-data-source.ts

@@ -0,0 +1,253 @@
+import * as semver from 'semver';
+import { IO, type IoDefaultMessages } from '../io/private';
+import type { ConstructTreeNode } from '../tree';
+import { loadTreeFromDir } from '../tree';
+import type { BootstrappedEnvironment, Component, Notice } from './types';
+
+/**
+ * Normalizes the given components structure into DNF form
+ */
+function normalizeComponents(xs: Array<Component | Component[]>): Component[][] {
+  return xs.map(x => Array.isArray(x) ? x : [x]);
+}
+
+function renderConjunction(xs: Component[]): string {
+  return xs.map(c => `${c.name}: ${c.version}`).join(' AND ');
+}
+
+interface ActualComponent {
+  /**
+   * Name of the component
+   */
+  readonly name: string;
+
+  /**
+   * Version of the component
+   */
+  readonly version: string;
+
+  /**
+   * If matched, under what name should it be added to the set of dynamic values
+   *
+   * These will be used to substitute placeholders in the message string, where
+   * placeholders look like `{resolve:XYZ}`.
+   *
+   * If there is more than one component with the same dynamic name, they are
+   * joined by ','.
+   *
+   * @default - Don't add to the set of dynamic values.
+   */
+  readonly dynamicName?: string;
+
+  /**
+   * If matched, what we should put in the set of dynamic values insstead of the version.
+   *
+   * Only used if `dynamicName` is set; by default we will add the actual version
+   * of the component.
+   *
+   * @default - The version.
+   */
+  readonly dynamicValue?: string;
+}
+
+export interface NoticesFilterFilterOptions {
+  readonly data: Notice[];
+  readonly cliVersion: string;
+  readonly outDir: string;
+  readonly bootstrappedEnvironments: BootstrappedEnvironment[];
+}
+
+export class NoticesFilter {
+  constructor(private readonly ioMessages: IoDefaultMessages) {
+  }
+
+  public filter(options: NoticesFilterFilterOptions): FilteredNotice[] {
+    const components = [
+      ...this.constructTreeComponents(options.outDir),
+      ...this.otherComponents(options),
+    ];
+
+    return this.findForNamedComponents(options.data, components);
+  }
+
+  /**
+   * From a set of input options, return the notices components we are searching for
+   */
+  private otherComponents(options: NoticesFilterFilterOptions): ActualComponent[] {
+    return [
+      // CLI
+      {
+        name: 'cli',
+        version: options.cliVersion,
+      },
+
+      // Node version
+      {
+        name: 'node',
+        version: process.version.replace(/^v/, ''), // remove the 'v' prefix.
+        dynamicName: 'node',
+      },
+
+      // Bootstrap environments
+      ...options.bootstrappedEnvironments.flatMap(env => {
+        const semverBootstrapVersion = semver.coerce(env.bootstrapStackVersion);
+        if (!semverBootstrapVersion) {
+          // we don't throw because notices should never crash the cli.
+          this.ioMessages.warning(`While filtering notices, could not coerce bootstrap version '${env.bootstrapStackVersion}' into semver`);
+          return [];
+        }
+
+        return [{
+          name: 'bootstrap',
+          version: `${semverBootstrapVersion}`,
+          dynamicName: 'ENVIRONMENTS',
+          dynamicValue: env.environment.name,
+        }];
+      }),
+    ];
+  }
+
+  /**
+   * Based on a set of component names, find all notices that match one of the given components
+   */
+  private findForNamedComponents(data: Notice[], actualComponents: ActualComponent[]): FilteredNotice[] {
+    return data.flatMap(notice => {
+      const ors = this.resolveAliases(normalizeComponents(notice.components));
+
+      // Find the first set of the disjunctions of which all components match against the actual components.
+      // Return the actual components we found so that we can inject their dynamic values. A single filter
+      // component can match more than one actual component
+      for (const ands of ors) {
+        const matched = ands.map(affected => actualComponents.filter(actual =>
+          this.componentNameMatches(affected, actual) && semver.satisfies(actual.version, affected.version, { includePrerelease: true })));
+
+        // For every clause in the filter we matched one or more components
+        if (matched.every(xs => xs.length > 0)) {
+          const ret = new FilteredNotice(notice);
+          this.addDynamicValues(matched.flatMap(x => x), ret);
+          return [ret];
+        }
+      }
+
+      return [];
+    });
+  }
+
+  /**
+   * Whether the given "affected component" name applies to the given actual component name.
+   *
+   * The name matches if the name is exactly the same, or the name in the notice
+   * is a prefix of the node name when the query ends in '.'.
+   */
+  private componentNameMatches(pattern: Component, actual: ActualComponent): boolean {
+    return pattern.name.endsWith('.') ? actual.name.startsWith(pattern.name) : pattern.name === actual.name;
+  }
+
+  /**
+   * Adds dynamic values from the given ActualComponents
+   *
+   * If there are multiple components with the same dynamic name, they are joined
+   * by a comma.
+   */
+  private addDynamicValues(comps: ActualComponent[], notice: FilteredNotice) {
+    const dynamicValues: Record<string, string[]> = {};
+    for (const comp of comps) {
+      if (comp.dynamicName) {
+        dynamicValues[comp.dynamicName] = dynamicValues[comp.dynamicName] ?? [];
+        dynamicValues[comp.dynamicName].push(comp.dynamicValue ?? comp.version);
+      }
+    }
+    for (const [key, values] of Object.entries(dynamicValues)) {
+      notice.addDynamicValue(key, values.join(','));
+    }
+  }
+
+  /**
+   * Treat 'framework' as an alias for either `aws-cdk-lib.` or `@aws-cdk/core.`.
+   *
+   * Because it's EITHER `aws-cdk-lib` or `@aws-cdk/core`, we need to add multiple
+   * arrays at the top level.
+   */
+  private resolveAliases(ors: Component[][]): Component[][] {
+    return ors.flatMap(ands => {
+      const hasFramework = ands.find(c => c.name === 'framework');
+      if (!hasFramework) {
+        return [ands];
+      }
+
+      return [
+        ands.map(c => c.name === 'framework' ? { ...c, name: '@aws-cdk/core.' } : c),
+        ands.map(c => c.name === 'framework' ? { ...c, name: 'aws-cdk-lib.' } : c),
+      ];
+    });
+  }
+
+  /**
+   * Load the construct tree from the given directory and return its components
+   */
+  private constructTreeComponents(manifestDir: string): ActualComponent[] {
+    const tree = loadTreeFromDir(manifestDir, (msg: string) => void this.ioMessages.notify(IO.DEFAULT_ASSEMBLY_TRACE.msg(msg)));
+    if (!tree) {
+      return [];
+    }
+
+    const ret: ActualComponent[] = [];
+    recurse(tree);
+    return ret;
+
+    function recurse(x: ConstructTreeNode) {
+      if (x.constructInfo?.fqn && x.constructInfo?.version) {
+        ret.push({
+          name: x.constructInfo?.fqn,
+          version: x.constructInfo?.version,
+        });
+      }
+
+      for (const child of Object.values(x.children ?? {})) {
+        recurse(child);
+      }
+    }
+  }
+}
+
+/**
+ * Notice after passing the filter. A filter can augment a notice with
+ * dynamic values as it has access to the dynamic matching data.
+ */
+export class FilteredNotice {
+  private readonly dynamicValues: { [key: string]: string } = {};
+
+  public constructor(public readonly notice: Notice) {
+  }
+
+  public addDynamicValue(key: string, value: string) {
+    this.dynamicValues[`{resolve:${key}}`] = value;
+  }
+
+  public format(): string {
+    const componentsValue = normalizeComponents(this.notice.components).map(renderConjunction).join(', ');
+    return this.resolveDynamicValues([
+      `${this.notice.issueNumber}\t${this.notice.title}`,
+      this.formatOverview(),
+      `\tAffected versions: ${componentsValue}`,
+      `\tMore information at: https://github.com/aws/aws-cdk/issues/${this.notice.issueNumber}`,
+    ].join('\n\n') + '\n');
+  }
+
+  private formatOverview() {
+    const wrap = (s: string) => s.replace(/(?![^\n]{1,60}$)([^\n]{1,60})\s/g, '$1\n');
+
+    const heading = 'Overview: ';
+    const separator = `\n\t${' '.repeat(heading.length)}`;
+    const content = wrap(this.notice.overview)
+      .split('\n')
+      .join(separator);
+
+    return '\t' + heading + content;
+  }
+
+  private resolveDynamicValues(input: string): string {
+    const pattern = new RegExp(Object.keys(this.dynamicValues).join('|'), 'g');
+    return input.replace(pattern, (matched) => this.dynamicValues[matched] ?? matched);
+  }
+}

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

@@ -0,0 +1 @@
+export * from './notices';