feat: diff spec databases (#596)

Adds a diffing tool to the service spec repository. Its goal is to print
the differences between 2 database files, in terms of services and their
properties added, removed and updated. By default, the diff is printed
in a nice ASCII art tree, but it can also be printed in JSON format by
passing the `--json` flag.

This diff tool will be used in the future to make sure that when we
refactor how the spec database is loaded, we can ensure that the
database before the refactor and after the refactor is the same (because
the diff will be empty).

We've decided that while the `tskb` project could potentially support a
generic database-level diff, it's probably easiest for now to just diff
at the application level (i.e., the code doing the diffing knows about
services, resources, properties and attributes).

* Diff types have been added to the `service-spec-types` package.
* The diff tool itself lives in the `service-spec-build` package.

NOTE: the ASCII tree print is currently broken, but we are merging this
early because we need the diffing functionality itself to validate other
changes.

---------

Co-authored-by: Kaizen Conroy <[email protected]>

.projenrc.ts

@@ -113,7 +113,7 @@ const serviceSpecBuild = new TypeScriptWorkspace({
   parent: repo,
   name: '@aws-cdk/service-spec-build',
   description: 'Build the service spec from service-spec-sources to service-spec',
-  deps: [tsKb, serviceSpecSources, serviceSpecTypes],
+  deps: [tsKb, serviceSpecTypes, 'commander', 'chalk@^4', serviceSpecSources],
   devDeps: ['source-map-support'],
   private: true,
 });
@@ -125,6 +125,10 @@ serviceSpecBuild.tasks.addTask('analyze:db', {
   exec: 'ts-node src/cli/analyze-db',
   receiveArgs: true,
 });
+serviceSpecBuild.tasks.addTask('diff:db', {
+  exec: 'ts-node src/cli/diff-db',
+  receiveArgs: true,
+});
 serviceSpecBuild.gitignore.addPatterns('db.json');
 serviceSpecBuild.gitignore.addPatterns('build-report');
 

packages/@aws-cdk/service-spec-build/src/cli/diff-db.ts

@@ -0,0 +1,42 @@
+import { loadDatabase } from '@aws-cdk/service-spec-types';
+import { Command } from 'commander';
+import { DbDiff } from '../db-diff';
+import { DiffFormatter } from '../diff-fmt';
+
+async function main() {
+  const program = new Command();
+
+  program
+    .name('diff-db')
+    .description('Calculate differences between two databases')
+    .argument('<db1>', 'First database file')
+    .argument('<db2>', 'Second database file')
+    .option('-j, --json', 'Output json', false)
+    .parse();
+  const options = program.opts();
+  const args = program.args;
+
+  const db1 = await loadDatabase(args[0]);
+  const db2 = await loadDatabase(args[1]);
+
+  const result = new DbDiff(db1, db2).diff();
+
+  const hasChanges =
+    Object.keys(result.services.added ?? {}).length +
+      Object.keys(result.services.removed ?? {}).length +
+      Object.keys(result.services.updated ?? {}).length >
+    0;
+
+  if (options.json) {
+    console.log(JSON.stringify(result, undefined, 2));
+  } else {
+    console.log(new DiffFormatter(db1, db2).format(result));
+  }
+
+  process.exitCode = hasChanges ? 1 : 0;
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exitCode = 1;
+});

packages/@aws-cdk/service-spec-build/src/db-diff.ts

@@ -0,0 +1,150 @@
+import {
+  Attribute,
+  Property,
+  PropertyType,
+  Resource,
+  RichPropertyType,
+  Service,
+  SpecDatabase,
+  SpecDatabaseDiff,
+  TypeDefinition,
+  UpdatedAttribute,
+  UpdatedProperty,
+  UpdatedResource,
+  UpdatedService,
+  UpdatedTypeDefinition,
+} from '@aws-cdk/service-spec-types';
+import {
+  diffByKey,
+  collapseUndefined,
+  diffScalar,
+  collapseEmptyDiff,
+  jsonEq,
+  diffMap,
+  diffList,
+  diffField,
+} from './diff-helpers';
+
+export class DbDiff {
+  constructor(private readonly db1: SpecDatabase, private readonly db2: SpecDatabase) {}
+
+  public diff(): SpecDatabaseDiff {
+    return {
+      services: diffByKey(
+        this.db1.all('service'),
+        this.db2.all('service'),
+        (service) => service.name,
+        (a, b) => this.diffService(a, b),
+      ),
+    };
+  }
+
+  private diffService(a: Service, b: Service): UpdatedService | undefined {
+    return collapseUndefined({
+      capitalized: diffScalar(a, b, 'capitalized'),
+      cloudFormationNamespace: diffScalar(a, b, 'cloudFormationNamespace'),
+      name: diffScalar(a, b, 'name'),
+      shortName: diffScalar(a, b, 'shortName'),
+      resourceDiff: this.diffServiceResources(a, b),
+    });
+  }
+
+  private diffServiceResources(a: Service, b: Service): UpdatedService['resourceDiff'] {
+    const aRes = this.db1.follow('hasResource', a).map((r) => r.entity);
+    const bRes = this.db2.follow('hasResource', b).map((r) => r.entity);
+
+    return collapseEmptyDiff(
+      diffByKey(
+        aRes,
+        bRes,
+        (resource) => resource.cloudFormationType,
+        (x, y) => this.diffResource(x, y),
+      ),
+    );
+  }
+
+  private diffResource(a: Resource, b: Resource): UpdatedResource | undefined {
+    return collapseUndefined({
+      cloudFormationTransform: diffScalar(a, b, 'cloudFormationTransform'),
+      documentation: diffScalar(a, b, 'documentation'),
+      cloudFormationType: diffScalar(a, b, 'cloudFormationType'),
+      isStateful: diffScalar(a, b, 'isStateful'),
+      identifier: diffField(a, b, 'identifier', jsonEq),
+      name: diffScalar(a, b, 'name'),
+      scrutinizable: diffScalar(a, b, 'scrutinizable'),
+      tagInformation: diffField(a, b, 'tagInformation', jsonEq),
+      attributes: collapseEmptyDiff(diffMap(a.attributes, b.attributes, (x, y) => this.diffAttribute(x, y))),
+      properties: collapseEmptyDiff(diffMap(a.properties, b.properties, (x, y) => this.diffProperty(x, y))),
+      typeDefinitionDiff: this.diffResourceTypeDefinitions(a, b),
+    });
+  }
+
+  private diffAttribute(a: Attribute, b: Attribute): UpdatedAttribute | undefined {
+    const eqType = this.eqType.bind(this);
+
+    const anyDiffs = collapseUndefined({
+      documentation: diffScalar(a, b, 'documentation'),
+      previousTypes: collapseEmptyDiff(diffList(a.previousTypes ?? [], b.previousTypes ?? [], eqType)),
+      type: diffField(a, b, 'type', eqType),
+    });
+
+    if (anyDiffs) {
+      return { old: a, new: b };
+    }
+    return undefined;
+  }
+
+  private diffProperty(a: Property, b: Property): UpdatedProperty | undefined {
+    const eqType = this.eqType.bind(this);
+
+    const anyDiffs = collapseUndefined({
+      documentation: diffScalar(a, b, 'documentation'),
+      defaultValue: diffScalar(a, b, 'defaultValue'),
+      deprecated: diffScalar(a, b, 'deprecated'),
+      required: diffScalar(a, b, 'required'),
+      scrutinizable: diffScalar(a, b, 'scrutinizable'),
+      previousTypes: collapseEmptyDiff(diffList(a.previousTypes ?? [], b.previousTypes ?? [], eqType)),
+      type: diffField(a, b, 'type', eqType),
+    });
+
+    if (anyDiffs) {
+      return { old: a, new: b };
+    }
+    return undefined;
+  }
+
+  private diffResourceTypeDefinitions(a: Resource, b: Resource): UpdatedResource['typeDefinitionDiff'] {
+    const aTypes = this.db1.follow('usesType', a).map((r) => r.entity);
+    const bTypes = this.db2.follow('usesType', b).map((r) => r.entity);
+
+    return collapseEmptyDiff(
+      diffByKey(
+        aTypes,
+        bTypes,
+        (type) => type.name,
+        (x, y) => this.diffTypeDefinition(x, y),
+      ),
+    );
+  }
+
+  private diffTypeDefinition(a: TypeDefinition, b: TypeDefinition): UpdatedTypeDefinition | undefined {
+    return collapseUndefined({
+      documentation: diffScalar(a, b, 'documentation'),
+      name: diffScalar(a, b, 'name'),
+      mustRenderForBwCompat: diffScalar(a, b, 'mustRenderForBwCompat'),
+      properties: collapseEmptyDiff(diffMap(a.properties, b.properties, (x, y) => this.diffProperty(x, y))),
+    });
+  }
+
+  /**
+   * Tricky -- we have to deep-compare all the type references which will have different ids in
+   * different databases.
+   *
+   * Solve it by doing a string-render and comparing those (for now).
+   */
+  private eqType(a: PropertyType, b: PropertyType): boolean {
+    const s1 = new RichPropertyType(a).stringify(this.db1, false);
+    const s2 = new RichPropertyType(b).stringify(this.db2, false);
+    return s1 === s2;
+  }
+}