diff --git a/.changeset/breezy-countries-own.md b/.changeset/breezy-countries-own.md new file mode 100644 index 000000000..3738d9639 --- /dev/null +++ b/.changeset/breezy-countries-own.md @@ -0,0 +1,5 @@ +--- +'@shopify/theme-graph': patch +--- + +Include @shopify/theme-check-node as a dependency diff --git a/docs/contributing.md b/docs/contributing.md index 67201af0b..c96bc84b0 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -5,8 +5,6 @@ Thank you for your interest in contributing to theme-tools! Your contributions w ## Table of Contents - [Setting Up Your Environment](#setting-up-your-environment) -- [Setup for the VS Code Extension](#setup-for-the-vscode-extension) -- [Setup for the Online Store](#setup-for-the-online-store) - [Submitting a Pull Request](#submitting-a-pull-request) - [Reporting Issues](#reporting-issues) - [Code of Conduct](#code-of-conduct) @@ -39,10 +37,10 @@ Before you can start contributing to theme-tools, you'll need to set up your dev ```bash yarn test ``` + 5. **Start developing**: If you're developing changes to test against the vscode extension, all you need to do is add a breakpoint anywhere in a package used within the VS Code extension, hit `f5` in VS Code and your development instance of theme-check will automatically open. -### Developing for online-store-web -It is strongly recommended that you use the spin constellation: `theme-tools:online-store` as your development environment for this. +### Developing for online-store-web (Shopifolk only) To set up the package links to online-store-web, within this repo root run: `yarn admin:init` @@ -54,7 +52,7 @@ Once you've made some changes to your local theme-tools packages, to see those c Run the following command to start a browser instance that runs `@shopify/theme-language-server-browser`. -``` +```bash yarn playground ``` @@ -80,45 +78,45 @@ If ever you want to see how the VS Code extension or playground would behave bef 1. In a terminal, with VS Code closed, go to the Shopify/theme-liquid-docs directory. - ```sh - # Shopifolk - dev cd theme-liquid-docs + ```sh + # Shopifolk + dev cd theme-liquid-docs - # External - cd /path/to/theme-liquid-docs - ``` + # External + cd /path/to/theme-liquid-docs + ``` 2. Export the root of that repository in the `SHOPIFY_TLD_ROOT` environment variable - ```sh - export SHOPIFY_TLD_ROOT=$(pwd) - ``` + ```sh + export SHOPIFY_TLD_ROOT=$(pwd) + ``` 3. Go to the Shopify/theme-tools directory. - ```sh - # Shopifolk - dev cd theme-tools + ```sh + # Shopifolk + dev cd theme-tools - # External - cd /path/to/theme-tools - ``` + # External + cd /path/to/theme-tools + ``` 4. Update the docs and start VS Code from that directory. - ```sh - # update the docs - theme-docs download + ```sh + # update the docs + theme-docs download - # start vscode - code . - ``` + # start vscode + code . + ``` 5. (Repeat) You can repeat the `theme-docs download` command to have updated changes. - ```sh - theme-docs download - ``` + ```sh + theme-docs download + ``` 6. Proceed to debug the VS Code extension or playground as usual. diff --git a/packages/theme-graph/docs/how-it-works.md b/packages/theme-graph/docs/how-it-works.md index 221516661..6509f2251 100644 --- a/packages/theme-graph/docs/how-it-works.md +++ b/packages/theme-graph/docs/how-it-works.md @@ -3,8 +3,8 @@ ## Table of contents 1. [What it looks like](#what-it-looks-like) -1. [Concepts overview](#concepts-overview) -2. [Algorithm overview](#algorithm-overview) +1. [Concepts overview](#concepts) +1. [Algorithm overview](#algorithm-overview) ## What it looks like @@ -18,19 +18,22 @@ It's a web of modules and links between them. A **Graph** is a set of Nodes and Edges. -A **Theme Graph** is a set of *Modules* (nodes) and *References* (edges) defined by an array of *Entry Points*. It has these properties: +A **Theme Graph** is a set of _Modules_ (nodes) and _References_ (edges) defined by an array of _Entry Points_. It has these properties: + - `rootUri` - root of the theme, e.g. `file:/path/to/theme` - `entryPoints` - array of modules that define the theme (all templates and sections) - `modules` - all the modules in the theme indexed by URI A **Module** is an object that represents a theme file. It has these properties: + - `uri` - module identifier, e.g. `file:/path/to/theme/snippets/file.liquid` - `type` - e.g. `liquid`, `json`, `javascript`, `css`. - `kind` - e.g. `block`, `section`, `snippet`, `template`, etc. -- `references` - array of *References* that point to this module. -- `dependencies` - array of *References* that this module depends on. +- `references` - array of _References_ that point to this module. +- `dependencies` - array of _References_ that this module depends on. A **Reference** is an object that defines a link between two modules. It has these properties: + - `source` - a `uri` and `range` that defines which module depends on an other and _where_ in the source file, - `target` - a `uri` and `range` that defines which module is being dependended on and optionally what is being depended on in that file, - `type` - one of the following: @@ -38,22 +41,24 @@ A **Reference** is an object that defines a link between two modules. It has the - `preset` - the file has a preset that depends on an other file, e.g. a section that has a preset that includes `group` and `text` blocks. - `indirect` - the file loosely depends on the other, but not explicilty. e.g. when a file accepts all public theme blocks (`"type": "@theme"`)) - ## Algorithm overview To build the graph, we _traverse_ each module in the set of entry points. When we _traverse_ a module, we do the following: + - if the module was already visited, we return early, else - we extract dependencies from the module's AST, then - we _bind_ the module with its dependent modules, then - we _traverse_ the dependent modules (it's a recursive algorithm). When we _bind_ a parent module with a child module, we do the following: + - we add the child module to the parent's dependencies, - we add the parent module to the child's references In pseudo code, it looks a bit like this: + ``` INPUT rootUri OUTPUT graph diff --git a/packages/theme-graph/package.json b/packages/theme-graph/package.json index 939e570b9..5e27a88e4 100644 --- a/packages/theme-graph/package.json +++ b/packages/theme-graph/package.json @@ -31,11 +31,9 @@ "dependencies": { "@shopify/liquid-html-parser": "^2.9.0", "@shopify/theme-check-common": "^3.23.0", + "@shopify/theme-check-node": "^3.23.0", "acorn": "^8.14.1", "acorn-walk": "^8.3.4", "vscode-uri": "^3.0.7" - }, - "devDependencies": { - "@shopify/theme-check-node": "^3.23.0" } }