You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
refactor: separate toolkit into core library (aws#4475)
In order to share code between multiple extensions we need to create a core library. Rather than create a core lib package, we decided to rename the current toolkit as a core library and create a barebones replacement that will generate the extension by importing from the core lib. This is easier than searching for common components, unwiring them, and hoisting them into an empty core lib package.
List of commits:
* initial restructuring and code moving
* rename toolkit to core
* rename stuff to core, 'inherit' fields from core package.json
* rename toolkit2 to toolkit, cleanup
* debugging works (non chrome/webpack only)
* run in browser (but debugging doesnt work)
* delete resources, package.nls.json
* move/update auxillary files, e.g. types/, templates/, etc
* update vscode configurations, build scripts, core lib tests.
* update infra configs (e.g. root package.json, codecov)
* remove unnecessary changes
* update AWS.Token import error comments
* fix web tests by adding webCompile to core
* generalize .vscodeignore, remove dev artifacts
* fix package.json scripts
* update documentation
* fix import from mainline commit, fix prepublish script
* remove compile from postinstall in core lib
* try compiling on install with bigger heap size
* try to fix flaky linux unit tests
* add more docs + workspace file for easier opening
* fix up configs
* update docs to specify how to import from core lib
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+7-7
Original file line number
Diff line number
Diff line change
@@ -9,8 +9,9 @@ codebase and sending pull requests.
9
9
## Getting Started
10
10
11
11
This project is set up as a typescript monorepo. The documentation throughout this project
12
-
is referring to the subproject in [`packages/toolkit/`](./packages/toolkit/). For more information,
13
-
see [ARCHITECTURE.md](./docs/ARCHITECTURE.md#monorepo-structure)
12
+
is referring to the subprojects [`packages/toolkit/`](./packages/toolkit/) and [`packages/core/`](./packages/core/).
13
+
Please see [ARCHITECTURE.md](./docs/ARCHITECTURE.md#monorepo-structure) to understand the
14
+
structure of thispackage before contributing.
14
15
15
16
### Find things to do
16
17
@@ -40,8 +41,8 @@ Then clone the repository and install NPM packages:
40
41
41
42
### Run
42
43
43
-
Due to the monorepo structure of the project, you can run the extension in VSCode by either opening the
44
-
`aws-toolkit-vscode/packages/toolkit` folder directly, or adding it as a root folder in the VSCode Workspace.
44
+
Due to the monorepo structure of the project, you must have the `aws-toolkit-vscode/packages/toolkit` folder open as root folder in the workspace.
45
+
The easiest way to open the project: File > Open Workspace from File > choose `aws-toolkit-vscode/aws-toolkit-vscode.code-workspace`
45
46
46
47
To run the extension from VSCode as a Node.js app:
47
48
@@ -161,9 +162,8 @@ See [web.md](./docs/web.md) for working with the web mode implementation of the
161
162
See [TESTPLAN.md](./docs/TESTPLAN.md) to understand the project's test
162
163
structure, mechanics and philosophy.
163
164
164
-
You can run tests directly from VSCode. Due to the monorepo structure of the project, you must either open
165
-
the `aws-toolkit-vscode/packages/toolkit/` folder directly, or add it as a root folder in the VSCode Workspace.
166
-
Then:
165
+
You can run tests directly from VSCode. Due to the monorepo structure of the project, you must have the `aws-toolkit-vscode/packages/toolkit` folder open as root folder in the workspace.
166
+
The easiest way to open the project: File > Open Workspace from File > choose `aws-toolkit-vscode/aws-toolkit-vscode.code-workspace`
167
167
168
168
1. Select `View > Debug`, or select the Debug pane from the sidebar.
169
169
2. From the dropdown at the top of the Debug pane, select the `Extension Tests` configuration.
Copy file name to clipboardExpand all lines: designs/credentials/credentials-management.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -31,11 +31,11 @@ A formatted version of the Credentials Provider Id may be surfaced to users, how
31
31
32
32
When the user connects to AWS in the Toolkit, a Credentials Provider is requested, which is then used to obtain credentials. The toolkit requests a Credentials Provider by checking which credentials provider factories support the provider's credentials type. The factories of interest are queried to see which (if any) have the requested Credentials Provider.
33
33
34
-
At the time this document was written, Shared Credentials are the only supported Credentials. Additional credentials providers will reside at [/src/credentials/providers](/packages/toolkit/src/credentials/providers) as they are implemented.
34
+
At the time this document was written, Shared Credentials are the only supported Credentials. Additional credentials providers will reside at [/src/credentials/providers](/packages/core/src/credentials/providers) as they are implemented.
35
35
36
36
### Shared Credentials Profiles
37
37
38
-
Profiles are retrieved from the user's shared credentials files. The profile is handled and validated differently based on which fields are present. Handling and validation logic can be found in [sharedCredentialsProvider.ts](/packages/toolkit/src/credentials/providers/sharedCredentialsProvider.ts).
38
+
Profiles are retrieved from the user's shared credentials files. The profile is handled and validated differently based on which fields are present. Handling and validation logic can be found in [sharedCredentialsProvider.ts](/packages/core/src/credentials/providers/sharedCredentialsProvider.ts).
39
39
40
40
Only profiles that are considered valid are provided to the toolkit. When validation issues are detected, they are written to the logs to help users understand why the toolkit is having difficulties with a profile. Users running the 'Connect to AWS' command will not see invalid profiles in the list of Credentials.
Copy file name to clipboardExpand all lines: designs/modify-resources-attached-to-code-pipeline.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -150,7 +150,7 @@ The confirmation prompt can be implemented using one of two UI facilities:
150
150
151
151
### API Client
152
152
153
-
The `ResourceGroupsTaggingAPI` service client will be used. The client will be set up in a manner consistent with the Lambda and CloudFormation clients, allowing the clients to be stubbed out in unit tests. See the Toolkit's Lambda Client [Interface](/packages/toolkit/src/shared/clients/lambdaClient.ts) and [Implementation](/packages/toolkit/src/shared/clients/defaultLambdaClient.ts) as an example. A new client factory will be added to [ToolkitClientBuilder](/packages/toolkit/src/shared/clients/toolkitClientBuilder.ts) and [DefaultToolkitClientBuilder](/packages/toolkit/src/shared/clients/defaultToolkitClientBuilder.ts).
153
+
The `ResourceGroupsTaggingAPI` service client will be used. The client will be set up in a manner consistent with the Lambda and CloudFormation clients, allowing the clients to be stubbed out in unit tests. See the Toolkit's Lambda Client [Interface](/packages/core/src/shared/clients/lambdaClient.ts) and [Implementation](/packages/core/src/shared/clients/defaultLambdaClient.ts) as an example. A new client factory will be added to [ToolkitClientBuilder](/packages/core/src/shared/clients/toolkitClientBuilder.ts) and [DefaultToolkitClientBuilder](/packages/core/src/shared/clients/defaultToolkitClientBuilder.ts).
Copy file name to clipboardExpand all lines: docs/ARCHITECTURE.md
+33-10
Original file line number
Diff line number
Diff line change
@@ -4,13 +4,29 @@ An overview of the architecture for various components within the Toolkit.
4
4
5
5
## Monorepo Structure
6
6
7
-
This project is currently set up as a typescript monorepo with a single subproject.
8
-
We are currently working on splitting the Toolkit into various subprojects to help with
9
-
sharing code between modules, Web mode development, etc. For now, there is just
10
-
one monolithic subproject with all the extension functionality: [`packages/toolkit/`](./packages/toolkit/).
7
+
**The easiest way to open the project for running/debugging:** File > Open Workspace from File > choose `aws-toolkit-vscode/aws-toolkit-vscode.code-workspace`
8
+
9
+
This project is currently set up as a typescript monorepo with the following subprojects:
10
+
11
+
-[`packages/core/`](./packages/core/)
12
+
- Currently, this package contains almost all of the functionality required for the extension.
13
+
It was created by moving all of the code from `packages/tookit/` to here.
14
+
We are currently working on separating non-shareable code out of the core library into the relevant
15
+
subproject. Running tests for most of the toolkit extension logic occurs in this subproject.
16
+
-[`packages/toolkit/`](./packages/toolkit/)
17
+
- Currently, this package is a barebones wrapper that calls activation functions from the core library.
18
+
As we discover what code cannot be shared across other projects, it will be moved to this package.
19
+
Running and packaging the extension occurs from this subproject.
20
+
21
+
If you are considering contributing, please consider whether your implementation should live in the core
22
+
library or in `packages/toolkit`. If your work could be re-used by other packages (e.g. auth mechanisms,
23
+
utilities), then it may belong in the core library. If instead you are adding something toolkit specific
24
+
(eg. an integration to a new AWS service in the Explorer Tree), consider putting it in `packages/toolkit`.
25
+
To import from the core library, please export your desired code using `index.ts` files, and add an appropriate `exports` statement
26
+
in `packages/core/package.json`.
11
27
12
28
Unless otherwise stated, the documentation throughout this project is referring to the code and
13
-
functionality of that subproject.
29
+
functionality in `packages/core/` and `packages/toolkit`.
14
30
15
31
Current quirks of the current monorepo status that should be resolved/evaluated in later versions (TODO):
16
32
@@ -26,20 +42,27 @@ Current quirks of the current monorepo status that should be resolved/evaluated
26
42
for more info on how `node_modules/` hoisting works.
27
43
- Because of `node_modules/` hoisting, references to this folder in code access the root project modules folder. This may be
28
44
an issue if more subprojects are added and the contents of the root and local modules folders differ.
29
-
-[`globalSetup.test.ts`](../packages/toolkit/src/test/globalSetup.test.ts) should be configured to work as a library/run tests for all subprojects.
45
+
-[`globalSetup.test.ts`](../packages/core/src/test/globalSetup.test.ts) should be configured to work as a library/run tests for all subprojects.
30
46
- Subproject `tsconfig.json`s should extend a root `tsconfig.packages.json`.
31
47
- Linting tests should run at the root level, not subproject level.
32
-
-`packages/toolkit/scripts/` should be generalized and moved to the root of the project as needed.
48
+
-`packages/*/scripts/` should be generalized and moved to the root of the project as needed.
33
49
- LICENSE, README.md, and other non-code artifacts that must be packaged into the .vsix are currently
34
50
being copied into the packaging subproject directory from the root project directory as part of the `copyFiles` task.
35
51
- Pre-release only publishes packages/toolkit extension directly. It should be extended to other added extensions. See [`release.yml`](../.github/workflows/release.yml)
36
52
- VSCode does not support inheriting/extending `.vscode/` settings: https://github.com/microsoft/vscode/issues/15909
37
53
54
+
Additional quirks introduced by creating a core library from the original extension code:
55
+
56
+
- Tests are ran from `packages/core/`
57
+
- Extension runs from `packages/toolkit`
58
+
- Extension tests run from the core lib. Since some of the tests require an extension context/sandbox, we initiate a "fake" extension to run these tests. This is also why there are vscode extensionproperties in the package.json
59
+
- Some of original extension code (that now lives in `packages/core`) depends on the package.json, specifically the contributes section. This section is very large AND needs to be present in both the core library and toolkit extension package.jsons. The core library code needs access to this section to create types, set up SAM debuggers, etc. The toolkit needs this section during packaging/debugging so that the extension can run in vscode. The short term solution was to creat a [build script](../packages/toolkit/scripts/build/handlePackageJson.ts) to copy necessary fields over to the toolkit extension during packaging and debugging.
60
+
38
61
## Commands
39
62
40
63
Many parts of the VS Code API relies on the use of 'commands' which are simply functions bound to a global ID. For small projects, this simplicity is great. But the base API doesn't offer a lot of common functionality that a large project might want: logging, error handling, etc.
41
64
42
-
For the Toolkit, common command functionality is implemented in [Commands](../packages/toolkit/src/shared/vscode/commands2.ts). The goal with this abstraction is to increase consistency across the Toolkit for anything related to commands.
65
+
For the Toolkit, common command functionality is implemented in [Commands](../packages/core/src/shared/vscode/commands2.ts). The goal with this abstraction is to increase consistency across the Toolkit for anything related to commands.
43
66
44
67
### Examples
45
68
@@ -123,7 +146,7 @@ _See also [CODE_GUIDELINES.md](./CODE_GUIDELINES.md#exceptions)._
0 commit comments