chore: move replaceAssembly to @jsii/spec and expose it (#3696)

This PR is meant to do two things:

- move `replaceAssembly` to `assembly-utils.ts` in `@jsii/spec`, because it is currently being duplicated in `cdk-generate-synthetic-examples`. This causes problems whenever we try to change `replaceAssembly`, as we did in this [commit](https://github.com/aws/jsii/pull/3669/files), because we will forget to change the function in `cdk-generate-synthetic-examples`. The plan is to have `cdk-generate-synthetic-examples` reference the `replaceAssembly` function in `@jsii/spec` in a separate PR.
- finish the effort started in this closed [PR](#3146), where we meant to make sure that we don't re-fingerprint assemblies after they've been changed. It was closed due to staleness.

---

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

[Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0

packages/@jsii/spec/src/assembly-utils.ts

@@ -40,6 +40,32 @@ export function findAssemblyFile(directory: string) {
   return dotJsiiFile;
 }
 
+/**
+ * Replaces the file where the original assembly file *should* be found with a new assembly file.
+ * Detects whether or not there is a compressed assembly, and if there is, compresses the new assembly also.
+ * Replaces the fingerprint with '**********' rather than recalculating it, since we have modified the assembly.
+ */
+export function replaceAssembly(assembly: Assembly, directory: string) {
+  writeAssembly(directory, _fingerprint(assembly), {
+    compress: compressedAssemblyExists(directory),
+  });
+}
+
+/**
+ * Replaces the old fingerprint with '***********'.
+ *
+ * We could recalculate the fingerprint here so that it looks like the assembly was not modified. However,
+ * 1) we are not actually validating the fingerprint in any way, and
+ * 2) it feels disingenuous to have a mechanism against tampering and then tamper with it.
+ *
+ * So, instead of keeping the old (wrong) fingerprint or spending extra time calculating a new fingerprint,
+ * we replace with '**********' that demonstrates the fingerprint has changed.
+ */
+function _fingerprint(assembly: Assembly): Assembly {
+  assembly.fingerprint = '*'.repeat(10);
+  return assembly;
+}
+
 /**
  * Writes the assembly file either as .jsii or .jsii.gz if zipped
  *

packages/jsii-rosetta/lib/commands/infuse.ts

@@ -1,14 +1,9 @@
 import * as spec from '@jsii/spec';
+import { replaceAssembly } from '@jsii/spec';
 import * as fs from 'fs';
 import * as path from 'path';
 
-import {
-  loadAssemblies,
-  replaceAssembly,
-  loadAllDefaultTablets,
-  LoadedAssembly,
-  allTypeScriptSnippets,
-} from '../jsii/assemblies';
+import { loadAssemblies, loadAllDefaultTablets, LoadedAssembly, allTypeScriptSnippets } from '../jsii/assemblies';
 import { renderMetadataline, TypeScriptSnippet } from '../snippet';
 import { SnippetSelector, mean, meanLength, shortest, longest } from '../snippet-selectors';
 import { snippetKey } from '../tablets/key';

packages/jsii-rosetta/lib/jsii/assemblies.ts

@@ -1,12 +1,5 @@
 import * as spec from '@jsii/spec';
-import {
-  compressedAssemblyExists,
-  loadAssemblyFromFile,
-  loadAssemblyFromPath,
-  findAssemblyFile,
-  writeAssembly,
-} from '@jsii/spec';
-import * as crypto from 'crypto';
+import { loadAssemblyFromFile, loadAssemblyFromPath, findAssemblyFile } from '@jsii/spec';
 import { promises as fsPromises } from 'fs';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -28,9 +21,6 @@ import { enforcesStrictMode } from '../strict';
 import { LanguageTablet, DEFAULT_TABLET_NAME, DEFAULT_TABLET_NAME_COMPRESSED } from '../tablets/tablets';
 import { fmap, mkDict, sortBy } from '../util';
 
-// eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
-const sortJson = require('sort-json');
-
 /**
  * The JSDoc tag users can use to associate non-visible metadata with an example
  *
@@ -236,26 +226,6 @@ export async function allTypeScriptSnippets(
   );
 }
 
-/**
- * Replaces the file where the original assembly file *should* be found with a new assembly file.
- * Detects whether or not there is a compressed assembly, and if there is, compresses the new assembly also.
- * Recalculates the fingerprint of the assembly to avoid tampering detection.
- */
-export function replaceAssembly(assembly: spec.Assembly, directory: string) {
-  writeAssembly(directory, _fingerprint(assembly), { compress: compressedAssemblyExists(directory) });
-}
-
-/**
- * This function is copied from `packages/jsii/lib/assembler.ts`.
- * We should make sure not to change one without changing the other as well.
- */
-function _fingerprint(assembly: spec.Assembly): spec.Assembly {
-  delete (assembly as any).fingerprint;
-  assembly = sortJson(assembly);
-  const fingerprint = crypto.createHash('sha256').update(JSON.stringify(assembly)).digest('base64');
-  return { ...assembly, fingerprint };
-}
-
 export interface TypeLookupAssembly {
   readonly packageJson: any;
   readonly assembly: spec.Assembly;

packages/jsii-rosetta/package.json

@@ -29,7 +29,6 @@
     "@jsii/spec": "0.0.0",
     "commonmark": "^0.30.0",
     "typescript": "~3.9.10",
-    "sort-json": "^2.0.1",
     "@xmldom/xmldom": "^0.8.2",
     "workerpool": "^6.2.1",
     "yargs": "^16.2.0",