@platformos/platformos-graph 0.0.2

package/docs/how-it-works.md

@@ -0,0 +1,89 @@
+# How it works
+
+## Table of contents
+
+1. [What it looks like](#what-it-looks-like)
+1. [Concepts overview](#concepts-overview)
+2. [Algorithm overview](#algorithm-overview)
+
+## What it looks like
+
+A theme graph looks a bit like this:
+
+![Graph](./graph.png)
+
+It's a web of modules and links between them.
+
+## Concepts
+
+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:
+- `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.
+
+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:
+  - `direct` - the file can't exist without the other, e.g. `{% render 'child' %}`
+  - `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
+
+FUNCTION buildGraph(rootUri, entryPoints):
+  SET graph = { rootUri, entryPoints, modules: {} }
+  FOR module in entryPoints:
+    CALL traverse(module, graph)
+  ENDFOR
+ENDFUNCTION
+
+FUNCTION traverse(module, graph):
+  IF graph.modules has module:
+    RETURN -- nothing to do, already visited
+  ENDIF
+
+  -- signal that this module has been visited
+  SET graph.modules[module.uri] = module
+
+  EXTRACT references FROM module by visiting the AST
+
+  FOR reference in references:
+    dependency = getModule(reference.target.uri)
+    CALL bind(module, dependency, reference)
+    CALL traverse(dependency, graph)
+  ENDFOR
+ENDFUNCTION
+
+FUNCTION bind(parent, child, reference)
+  parent.dependencies.push(reference)
+  child.references.push(reference)
+ENDFUNCTION
+```

package/fixtures/skeleton/app/views/partials/child.liquid

@@ -0,0 +1,9 @@
+{% doc %}
+  Child fixture that depends on the child-element custom element
+
+  @param {string} children
+{% enddoc %}
+
+<child-element>
+  {{ children }}
+</child-element>

package/fixtures/skeleton/app/views/partials/parent.liquid

@@ -0,0 +1,9 @@
+{% doc %}
+  Parent snippet that renders the children and depends on the parent-element custom element
+
+  @param {string} children
+{% enddoc %}
+
+<parent-element>
+  {% render "child", children: children %}
+</parent-element>

package/fixtures/skeleton/assets/theme.js

@@ -0,0 +1,7 @@
+window.customElements.define('parent-element', class extends HTMLElement {
+
+});
+
+customElements.define('child-element', class extends HTMLElement {
+
+});

package/fixtures/skeleton/blocks/_private.liquid

@@ -0,0 +1 @@
+hoho I'm private

package/fixtures/skeleton/blocks/_static.liquid

@@ -0,0 +1,10 @@
+{% doc %}
+  this block is statically rendered
+
+  @param {string} content
+
+{% enddoc %}
+
+<div class="static-block">
+  {{ content }}
+</div>

package/fixtures/skeleton/blocks/group.liquid

@@ -0,0 +1,27 @@
+{% doc %}
+  Fixture block component that passes its blocks to the parent snippet
+{% enddoc %}
+
+{% capture children %}
+  {%- content_for "blocks" -%}
+{% endcapture %}
+
+{% render 'parent', children: children %}
+
+{% schema %}
+{
+  "name": "Group block",
+  "blocks": [{ "type": "@theme" }],
+  "presets": [
+    {
+      "name": "Group block",
+      "category": "Group",
+      "blocks": [
+        {
+          "type": "text"
+        }
+      ]
+    }
+  ]
+}
+{% endschema %}

package/fixtures/skeleton/blocks/render-static.liquid

@@ -0,0 +1,22 @@
+{% doc %}
+  This block renders the private _static block. Has no schema.
+{% enddoc %}
+
+<div class="static-block-wrapper">
+  {% content_for 'block',
+    type: '_static',
+    id: 'static',
+    content: 'hello world'
+  %}
+</div>
+
+{% schema %}
+{
+  "name": "render static block",
+  "presets": [
+    {
+      "name": "Render Static Block"
+    }
+  ]
+}
+{% endschema %}

package/fixtures/skeleton/blocks/text.liquid

@@ -0,0 +1,14 @@
+hello world
+
+{% schema %}
+{
+  "name": "Text block",
+  "settings": [],
+  "presets": [
+    {
+      "name": "Text block",
+      "category": "Text"
+    }
+  ]
+}
+{% endschema %}

package/fixtures/skeleton/jsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "baseUrl": "./assets",
+    "lib": ["es2020", "dom"],
+    "allowJs": true,
+    "checkJs": true
+  },
+  "include": ["./assets/**/*.js"],
+}

package/fixtures/skeleton/layout/theme.liquid

@@ -0,0 +1,14 @@
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+    <script type="module" src="{{ 'theme.js' | asset_url }}"></script>
+    {{ 'theme.css' | asset_url | stylesheet_tag }}
+    {{ content_for_header }}
+  </head>
+  <body>
+    {% sections 'header-group' %}
+    {{ content_for_layout }}
+  </body>
+</html>

package/fixtures/skeleton/sections/custom-section.liquid

@@ -0,0 +1,6 @@
+{% schema %}
+{
+  "name": "custom section",
+  "blocks": [{ "type": "@theme" }, { "type": "_private" }]
+}
+{% endschema %}

package/fixtures/skeleton/sections/header-group.json

@@ -0,0 +1,36 @@
+{
+  "sections": {
+    "header": {
+      "type": "custom-section",
+      "block_order": [
+        "header",
+        "render-static",
+      ],
+      "blocks": {
+        "header": {
+          "type": "group",
+          "block_order": [
+            "text"
+          ],
+          "blocks": {
+            "text": {
+              "type": "text",
+            }
+          },
+        },
+        "render-static": {
+          "type": "render-static",
+          "blocks": {
+            "static": {
+              "type": "_static",
+              "static": true,
+            }
+          }
+        }
+      }
+    }
+  },
+  "order": [
+    "header"
+  ],
+}

package/fixtures/skeleton/sections/header.liquid

@@ -0,0 +1 @@
+header content

package/fixtures/skeleton/templates/index.json

@@ -0,0 +1,20 @@
+{
+  "sections": {
+    "main": {
+      "type": "custom-section",
+      "blocks": [
+        {
+          "type": "group",
+          "blocks": {
+            "text1": {
+              "type": "text",
+            },
+          },
+          "block_order": [
+            "text1"
+          ]
+        }
+      ]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@platformos/platformos-graph",
+  "version": "0.0.2",
+  "description": "Shopify Theme Graph as a data structure",
+  "author": "platformOS",
+  "homepage": "https://github.com/Platform-OS/platformos-tools/tree/main/packages/platformos-graph#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Platform-OS/platformos-tools.git",
+    "directory": "packages/platformos-graph"
+  },
+  "bugs": {
+    "url": "https://github.com/Platform-OS/platformos-tools/issues"
+  },
+  "bin": {
+    "platformos-graph": "bin/platformos-graph"
+  },
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "@platformos:registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "yarn build:ts",
+    "build:ci": "yarn build",
+    "build:ts": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@platformos/liquid-html-parser": "^0.0.2",
+    "@platformos/platformos-check-common": "0.0.2",
+    "acorn": "^8.14.1",
+    "acorn-walk": "^8.3.4",
+    "vscode-uri": "^3.0.7"
+  },
+  "devDependencies": {
+    "@platformos/platformos-check-node": "0.0.2"
+  }
+}

package/src/getWebComponentMap.ts

@@ -0,0 +1,81 @@
+import { path, recursiveReadDirectory } from '@platformos/platformos-check-common';
+import { ancestor as visit } from 'acorn-walk';
+import { Dependencies, Void, WebComponentMap } from './types';
+import { CallExpression } from 'acorn';
+
+/**
+ * Regular expression for web component names
+ *
+ * Based on the HTML specification for valid custom element names.
+ *
+ * https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
+ */
+const wcre =
+  /^[a-z][-.\d_a-z\u00B7\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u037D\u037F-\u1FFF\u200C-\u200D\u203F-\u2040\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD]*([-][-.\d_a-z\u00B7\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u037D\u037F-\u1FFF\u200C-\u200D\u203F-\u2040\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD]*)$/u;
+
+/**
+ * Find all the web component definitions from the JavaScript files in the
+ * assets directory.
+ *
+ * From those, we'll be able to map `<custom-element-name>` to the definition in
+ * the corresponding asset file.
+ */
+export async function getWebComponentMap(
+  rootUri: string,
+  { fs, getSourceCode }: Pick<Dependencies, 'fs' | 'getSourceCode'>,
+): Promise<WebComponentMap> {
+  const webComponentDefs: WebComponentMap = new Map();
+  const assetRoot = path.join(rootUri, 'assets');
+  const jsFiles = await recursiveReadDirectory(fs, assetRoot, ([fileName]) =>
+    fileName.endsWith('.js'),
+  );
+
+  await Promise.all(
+    jsFiles.map((uri) =>
+      findWebComponentReferences(uri, assetRoot, getSourceCode, webComponentDefs),
+    ),
+  );
+
+  return webComponentDefs;
+}
+
+export async function findWebComponentReferences(
+  uri: string,
+  assetRoot: string,
+  getSourceCode: Dependencies['getSourceCode'],
+  result: WebComponentMap,
+): Promise<Void> {
+  const sourceCode = await getSourceCode(uri);
+  if (sourceCode.type !== 'javascript') {
+    return;
+  }
+
+  const ast = sourceCode.ast;
+  if (ast instanceof Error) {
+    return;
+  }
+
+  for (const node of ast.body) {
+    visit(node, {
+      Literal(node, _state, ancestors) {
+        if (typeof node.value === 'string' && wcre.test(node.value)) {
+          // Making sure we're looking at customElements.define calls
+          const parentNode = ancestors.at(-2);
+          if (!parentNode) return;
+          if (parentNode.type !== 'CallExpression') return;
+          const callee = (parentNode as CallExpression).callee;
+          if (callee.type !== 'MemberExpression') return;
+          const property = callee.property;
+          if (property.type !== 'Identifier') return;
+          if (property.name !== 'define') return;
+
+          result.set(node.value, {
+            assetName: path.relative(uri, assetRoot),
+            range: [property.start, node.end],
+          });
+        }
+        return null;
+      },
+    });
+  }
+}

package/src/graph/augment.ts

@@ -0,0 +1,34 @@
+import {
+  memoize,
+  memo,
+  recursiveReadDirectory as findAllFiles,
+  path,
+} from '@platformos/platformos-check-common';
+import { toSourceCode } from '../toSourceCode';
+import { AugmentedDependencies, IDependencies } from '../types';
+import { identity } from '../utils';
+
+export function augmentDependencies(rootUri: string, ideps: IDependencies): AugmentedDependencies {
+  return {
+    fs: ideps.fs,
+    getBlockSchema: memoize(ideps.getBlockSchema, identity),
+    getSectionSchema: memoize(ideps.getSectionSchema, identity),
+
+    // parse at most once
+    getSourceCode: memoize(
+      ideps.getSourceCode ??
+        async function defaultGetSourceCode(uri) {
+          const contents = await ideps.fs.readFile(uri);
+          return toSourceCode(uri, contents);
+        },
+      identity,
+    ),
+
+    getWebComponentDefinitionReference: ideps.getWebComponentDefinitionReference,
+    getThemeBlockNames: memo(() =>
+      findAllFiles(ideps.fs, path.join(rootUri, 'blocks'), ([uri]) => uri.endsWith('.liquid')).then(
+        (uris) => uris.map((uri) => path.basename(uri, '.liquid')),
+      ),
+    ),
+  };
+}