## What
Include packages/ subdirectories in medusa-dev packages discovery.
## Why
We started to use subdirectories in the monorepo `packages/` directory in order to better organize packages.
Packages in subdirectories were invisible to `medusa-dev` and could not be copied.
## How
Rely on monorepo package.json workspace glob patterns to discover packages that can be published to the local npm registry.
## What
Allow `medusa-oas` CLI to generate API client code from an OAS json file.
## Why
Manually maintaining API clients is time consuming and error prone. We wish to automate the process by using code generation strategies.
We also wish to eliminate direct import from `@medusajs/medusa` in clients which can lead to unwanted side effects like importing unnecessary dependencies.
## How
Fork and customize an OAS code generator library that is TypeScript friendly.
Attempt to match the interface and signature of our current client packages: `@medusajs/medusa-js`, `medusa-react`
Add a new `client` command to the `medusa-oas` CLI as the main interface to interact with the code generation tooling.
## Test
### Prerequisites
* From the root of the monorepo:
* `yarn install`
* `yarn build`
### Case - all in one build
* From the root of the monorepo:
* Run `yarn medusa-oas oas --out-dir ~/tmp/oas --type store`
* Run `yarn medusa-oas client --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/client-store --type store`
* Expect `~/tmp/client-store` to contain the following files and directories:
```
core/
hooks/
models/
services/
index.ts
MedusaStore.ts
useMedusaStore.tsx
```
### Case - types only
* From the root of the monorepo:
* Run `yarn medusa-oas oas --out-dir ~/tmp/oas --type store`
* Run `yarn medusa-oas client --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/client-types --type store --component types`
* Expect `~/tmp/client-types` to contain the following files and directories:
```
models/
index.ts
```
### Case - client only
* From the root of the monorepo:
* Run `yarn medusa-oas oas --out-dir ~/tmp/oas --type store`
* Run `yarn medusa-oas client --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/client-only --type store --component client --types-package @medusajs/client-types`
* Expect `~/tmp/client-only` to contain the following files and directories:
```
core/
services/
index.ts
MedusaStore.ts
```
## What
Introduce a CLI for extracting OAS from the core `medusa` package.
## Why
We need to decouple OAS tooling from documentation tooling in order to allow packages and external systems to leverage our OAS has a dependency.
## How
Introduce a new OAS workspace within packages in order to organize current and future OAS related package. Only 1 OAS package for now.
Introduce a new CLI only package to act as the main gateway for all upcoming OAS tooling. Only 1 command for now.
Update documentation tooling pertaining to OAS to use the CLI instead.
## Test
### Prerequisite
From the monorepo root:
* `yarn install`
* `yarn build`
### Documentation
#### Case - validation only - success
* Run `yarn openapi:generate --dry-run`
* Expect console output `🟢 Valid OAS` but no mention of `🔵 Exported OAS`
#### Case - validation only - invalid
* Introduce a bug by renaming `@schema Cart` to `@schema Kart` in [models/cart.ts](0adb0d9ff9/packages/medusa/src/models/cart.ts (L2))
* Run `yarn build` to update `@medusajs/medusa` package with the bug.
* Run `yarn openapi:generate --dry-run`
* Expect console output `🔴 Invalid OAS` with a stack trace of the issue.
#### Case - docs generation
* Run `yarn openapi:generate`
* Expect `docs/api/` directory to contain:
* `admin.oas.json` (raw OAS)
* `store.oas.json` (raw OAS)
* `admin.oas.yaml` (sanitized OAS)
* `store.oas.yaml` (sanitized OAS)
* `admin/` (updated redocly split output)
* `store/` (updated redocly split output)
### CLI
#### Case - crawl additional paths
* From a local medusa server (`medusa-starter-default`), add an `index.ts` file in `src/models/`
* In the `index.ts`, add dummy OAS JSDoc like `/** @schema Foobar */`
* From the root of the monorepo, run `yarn medusa-oas --type store --paths path-to-medusa-server/src`
* Expect a `store.oas.json` to be created at the root of the monorepo.
* The `store.oas.json` should contain an additional `Foobar` entry in `components.schemas`.
### What
Add OAS build step to patch known circular references that prevent Redocly from rendering the API documentation.
### Why
We've encountered crashing and loading issues with Redocly when the OAS contained circular references. We have been working around the limitation by omitting some known problematic $ref in our source OAS. We wish to move away from this strategy in order to always explicitly include $ref in our OAS.
### How
We are introducing a custom Redocly CLI plugin that will replace `$ref` by `type: object` base on a configurable set of instructions. These instructions can be modified in `docs-util/redocly/config.yaml`
We are adding a `redocly bundle` step in the current OAS build process in order to sanitize problematic circular references.
We updated the redocly-cli package version in order to ensure that plugins are supported.
### Test
We will use [Cart.payment](fd5c185159/packages/medusa/src/models/cart.ts (L72-L74)) to ensure that the new process is properly sanitizing.
* Run `yarn openapi:generate`
* Open `docs/api/store/components/schemas/Cart.yaml`
* Expect the `payment` property to have been sanitized to `type: object`
* Run `yarn redocly preview-docs docs/api/store/openapi.yaml --config=docs-util/redocly/config.yaml`
* Visit http://127.0.0.1:8080/#tag/Cart/operation/GetCartsCart
* In the response, expect cart.payment to not list the properties of the Payment schema.
**What:**
Introduces a new folder under which repository specs will be placed.
Why:
We don't currently have a good place to test ORM logic or custom queries against the database. The repository folder tests are a place for just exactly that.
How:
Creates an internal package similar to other integration tests - api and plugins.
CORE-965
### What
Explicitly declare `@medusajs/medusa` as a devDependency for `@medusajs/medusa-js` client package.
### Why
With our latest version upgrade of `turbo`, peerDependencies aren't taken into account in the build graph. The recommendation is to also explicitly declare them in devDependencies.
### Test
* Run `yarn build --graph`
* Expect to see medusa-js having a dependency on medusa
```
"[root] @medusajs/medusa-js#build" -> "[root] @medusajs/medusa#build"
```
### What
Flip Turborepo cache glob pattern from an allow-list to deny-list pattern.
### Why
Packages within medusa's monorepo will output their build to a `dist` directory.
This convention does not apply to plugins since the core plugin loader expects the content of plugin packages `src` directory to be outputted at the root of the package.
i.e. `packages/foobar-plugin/src/utils/index.ts` -> `packages/foobar-plugin/utils/index.js`
Manually maintaining an allow-list of known plugin output directories is not scalable. When a directory exists in a plugin package but is not know to the allow-list, the directory will not be re-built on subsequent builds. Troubleshooting the issue requires intimate knowledge of Turborepo caching strategies.
### How
By using a deny-list glob pattern, plugin packages can now declare any not-known directory within their `src` folder without facing any potential omission issues during the build process.
We declare `src` and its content as the only directory for turbo cache to ignore.
### Additional scope
* Use `turbo.json` file content in cache hashing algorithm in order to break CI cache when changes are made to the Turborepo config.
* Upgraded turbo minor verion.
* Added missing dependency to medusa package.
### Test
* Delete previously built output in packages. Run `yarn build --force` (replace any existing cache)
* Expect all src content to be outputted
* Run `yarn build` right after
* Expect a fast build time since cache will be fresh
* Add a new directory with an index.ts file in a plugin package src folder. Run `yarn build`
* Expect a fast build time, except for the modified plugin package.
* Expect the newly added directory to be outputted.
* Delete the newly outputted directory. Run `yarn build`
* Expect the outputted directory to reappear.
### References
* 5093b82f3a/packages/medusa/src/loaders/plugins.ts
* https://turbo.build/repo/docs/reference/configuration#outputs
* https://turbo.build/repo/docs/reference/configuration#globaldependencies
Resolves CORE-891
### What
Leverage yarn workspaces and Turborepo for integration-tests in order to accelerate development and reduce DevX complexity.
### Why
The current solution for running integration tests requires using `medusa-dev-cli` in order to publish packages to a local npm repository. The package where the command is executed will have its package.json altered for any known medusa dependency in order to install from the local npm. The process is taxing on the host machine resources and prevents rapid iterations when working with integration tests.
For more information, see documentation: f0cc1b324c/docs/content/usage/local-development.md (run-api-integration-tests)
### How
By declaring `integeration-tests/**/*` as a workspace, Turborepo can now be leveraged to build and run integration test as if there were packages. The build process will take care of interdependency between package in order to ensure local dependency are met.
In addition, within each integration-tests "packages", we can declare local dependencies as "*" which will translate to using the one that is part of the current build, regardless of the dependency's version number. No more fiddling with version numbers.
Github actions pertaining to integration-tests have been streamlined to use the new behavior.
The integration-tests packages have been marked as `private:true` in order to avoid publishing them to the public npm registry.
### Testing
```
cd root-of-medusajs-medusa-repo/
yarn install
yarn build
yarn test:integration:api
yarn test:integration:plugins
```
After a code change, `yarn build` must be run before re-running an integration test, which is the same procedure as for unit tests.
Resolves: CORE-845
