web: Fix failing web mode due to fs-extra import (aws#5248)

* docs: Update web mode docs

- Add information about a common error so that developers can hopefully ctrl+f this when
  debugging
- Remove the more complex image of dependency cruiser as it just causes confusion

Signed-off-by: Nikolas Komonen <[email protected]>

* web: make 'common' codewhisperer export module

Problem:

When importing the codewhisperer exports module from index.ts in web mode
it was breaking due to a transitive fs-extra import.

Solution:

Export a separate module from indexCommon.ts for code that works in web
or node. This file is a subset of index.ts, so behavior remains the same.

Signed-off-by: Nikolas Komonen <[email protected]>

---------

Signed-off-by: Nikolas Komonen <[email protected]>

Author: nkomonen-amazon

docs/images/dependency-graph.svg

@@ -92,6 +92,8 @@ If you need to manage npm modules required for Web mode, such as a [browserfied
 For example, if I have a Typescript module, `myFile.ts`, that imports a module which imports another module (transitive dependency) such as `fs-extra`,
 when I execute `myFile.ts` in the browser it will break due to `fs-extra` not being browser compatible.
 
+> INFO: A common error is `Cannot read properties of undefined (reading 'native')` caused by `fs-extra`
+
 It may be difficult to determine which module imported `fs-extra` due to a nested chain of transitive dependencies.
 
 As a solution, we can use [`dependency-cruiser`](https://www.npmjs.com/package/dependency-cruiser) to generate a dependency diagram
@@ -102,10 +104,11 @@ to help us visualize the imports and determine which module is importing a certa
 1. Install the `graphviz` cli, this provides the `dot` cli command
     - Mac: `brew install graphviz`
     - Others: [See documentation](https://www.graphviz.org/download/)
-2. Run `npx depcruise {RELATIVE_PATH_TO_FILE}  --output-type dot | dot -T svg > dependency-graph.svg`
-    - For example, `npx depcruise src/srcShared/fs.ts  --output-type dot | dot -T svg > dependency-graph.svg` generates the following which shows `fs-extra` is imported by `fileSystemUtilities.ts`:
-      ![Dependency Graph](./images/dependency-graph.svg)
-    - Additionally specify a certain dependency with `--reaches` , `npx depcruise src/srcShared/fs.ts --reaches "fs-extra" --output-type dot | dot -T svg > dependency-graph.svg`, to hide unrelated dependencies:
+2. Temporarily install `dependency-cruiser`
+    - IMPORTANT: You will want to revert this install when done
+    - `npm i dependency-cruiser`
+3. Run `npx depcruise {RELATIVE_PATH_TO_FILE}  --reaches "{YOUR_MODULE}" --output-type dot | dot -T svg > dependency-graph.svg`
+    - For example `npx depcruise src/srcShared/fs.ts --reaches "fs-extra" --output-type dot | dot -T svg > dependency-graph.svg`, generates the following which shows that `fs-extra` is imported by `fileSystemUtilities.ts`:
       ![Dependency Graph](./images/dependency-graph-small.svg)
 
 ## Behavior of module exports in tests

docs/web.md

@@ -11,7 +11,7 @@ import {
     shutdown as shutdownCodeWhisperer,
     amazonQDismissedKey,
     AuthUtil,
-} from 'aws-core-vscode/codewhisperer'
+} from 'aws-core-vscode/codewhispererCommon'
 import {
     ExtContext,
     initialize,

packages/amazonq/src/extensionCommon.ts

@@ -34,6 +34,7 @@
         "./common": "./dist/src/common/index.js",
         "./amazonq": "./dist/src/amazonq/index.js",
         "./codewhisperer": "./dist/src/codewhisperer/index.js",
+        "./codewhispererCommon": "./dist/src/codewhisperer/indexCommon.js",
         "./shared": "./dist/src/shared/index.js",
         "./srcShared": "./dist/src/srcShared/index.js",
         "./auth": "./dist/src/auth/index.js",

packages/core/package.json

@@ -3,11 +3,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-export { activate, shutdown } from './activation'
-export * from './util/authUtil'
+export * from './indexCommon'
+
 export * from './models/model'
 export * as model from './models/model'
-export * from './models/constants'
 export * as CodeWhispererConstants from './models/constants'
 export * from './commands/basicCommands'
 export * from './commands/types'

packages/core/src/codewhisperer/index.ts

@@ -0,0 +1,14 @@
+/*!
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * This module is a subset of `./index.js` except it is for 'common' code only.
+ *
+ * See "Shared vs Common" in our docs/ folder for the meaning of 'common'
+ */
+
+export { activate, shutdown } from './activation'
+export * from './util/authUtil'
+export * from './models/constants'