@platformos/platformos-graph 0.0.2

package/src/graph/build.spec.ts

@@ -0,0 +1,248 @@
+import { path as pathUtils, SourceCodeType } from '@platformos/platformos-check-common';
+import { assert, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { buildThemeGraph } from '../index';
+import { Dependencies, JsonModuleKind, LiquidModuleKind, ModuleType, ThemeGraph } from '../types';
+import { getDependencies, skeleton } from './test-helpers';
+
+describe('Module: index', () => {
+  const rootUri = skeleton;
+  const p = (part: string) => pathUtils.join(rootUri, ...part.split('/'));
+  const loc = (part: string) => expect.objectContaining({ uri: p(part) });
+  let dependencies: Dependencies;
+
+  beforeAll(async () => {
+    dependencies = await getDependencies(rootUri);
+  }, 15000);
+
+  describe('Unit: buildThemeGraph', { timeout: 10000 }, () => {
+    it('build a graph of the theme', { timeout: 10000 }, async () => {
+      const graph = await buildThemeGraph(rootUri, dependencies);
+      expect(graph).toBeDefined();
+    });
+
+    describe('with a valid theme graph', () => {
+      let graph: ThemeGraph;
+
+      beforeEach(async () => {
+        graph = await buildThemeGraph(rootUri, dependencies);
+      });
+
+      it('have a root URI', () => {
+        expect(graph.rootUri).toBeDefined();
+        expect(graph.rootUri).toBe(rootUri);
+      });
+
+      // We're using sections as entry points because the section rendering API can render
+      // any section without it needing a preset or default value in its schema.
+      it('infers entry points from the templates folder and section files', () => {
+        expect(graph.entryPoints).toHaveLength(3);
+        expect(graph.entryPoints.map((x) => x.uri)).toEqual(
+          expect.arrayContaining([
+            p('templates/index.json'),
+            p('sections/custom-section.liquid'),
+            p('sections/header.liquid'),
+          ]),
+        );
+      });
+
+      it("finds layout/theme.liquid's dependencies and references", () => {
+        const themeLayout = graph.modules[p('layout/theme.liquid')];
+        assert(themeLayout);
+
+        // outgoing links
+        const deps = themeLayout.dependencies;
+        assert(deps.map((x) => x.source.uri).every((x) => x === p('layout/theme.liquid')));
+        expect(deps.map((x) => x.target.uri)).toEqual(
+          expect.arrayContaining([
+            p('sections/header-group.json'),
+            p('assets/theme.js'),
+            p('assets/theme.css'),
+          ]),
+        );
+
+        // ingoing links
+        const refs = themeLayout.references;
+        expect(refs).toHaveLength(1);
+        assert(refs.map((x) => x.target.uri).every((x) => x === p('layout/theme.liquid')));
+        expect(refs.map((x) => x.source.uri)).toEqual(
+          expect.arrayContaining([p('templates/index.json')]),
+        );
+      });
+
+      it("finds templates/index.json's dependencies and references", () => {
+        const indexTemplate = graph.modules[p('templates/index.json')];
+        assert(indexTemplate);
+        assert(indexTemplate.type === ModuleType.Json);
+        assert(indexTemplate.kind === JsonModuleKind.Template);
+
+        // outgoing links
+        const deps = indexTemplate.dependencies;
+        assert(deps.map((x) => x.source.uri).every((x) => x === p('templates/index.json')));
+        expect(deps.map((x) => x.target.uri)).toEqual(
+          expect.arrayContaining([
+            p('layout/theme.liquid'),
+            p('sections/custom-section.liquid'),
+            p('blocks/group.liquid'),
+            p('blocks/text.liquid'),
+          ]),
+        );
+
+        // ingoing links
+        const refs = indexTemplate.references;
+        expect(refs).toHaveLength(0);
+      });
+
+      it("finds sections/custom-section's dependencies and references", () => {
+        const customSection = graph.modules[p('sections/custom-section.liquid')];
+        assert(customSection);
+        assert(customSection.type === ModuleType.Liquid);
+        assert(customSection.kind === LiquidModuleKind.Section);
+
+        // outgoing links
+        const deps = customSection.dependencies;
+        assert(deps.map((x) => x.source.uri).every((x) => x === customSection.uri));
+        expect(deps.map((x) => x.target.uri)).toEqual(
+          expect.arrayContaining([
+            p('blocks/group.liquid'),
+            p('blocks/text.liquid'),
+            p('blocks/_private.liquid'),
+          ]),
+        );
+
+        // ingoing links
+        const refs = customSection.references;
+        assert(refs.map((x) => x.target.uri).every((x) => x === customSection.uri));
+        expect(refs.map((x) => x.source.uri)).toEqual(
+          expect.arrayContaining([p('templates/index.json'), p('sections/header-group.json')]),
+        );
+        expect(refs).toHaveLength(2);
+      });
+
+      it("finds blocks/group's dependencies and references", () => {
+        const groupBlock = graph.modules[p('blocks/group.liquid')];
+        assert(groupBlock);
+        assert(groupBlock.type === ModuleType.Liquid);
+        assert(groupBlock.kind === LiquidModuleKind.Block);
+
+        const deps = groupBlock.dependencies;
+        assert(deps.map((x) => x.source.uri).every((x) => x === groupBlock.uri));
+        expect(deps).toEqual(
+          expect.arrayContaining([
+            {
+              source: loc('blocks/group.liquid'),
+              target: loc('app/views/partials/parent.liquid'),
+              type: 'direct',
+            }, // direct dep in partial
+            {
+              source: loc('blocks/group.liquid'),
+              target: loc('blocks/text.liquid'),
+              type: 'indirect',
+            }, // indirect because of @theme
+            {
+              source: loc('blocks/group.liquid'),
+              target: loc('blocks/text.liquid'),
+              type: 'preset',
+            }, // direct dep in preset
+          ]),
+        );
+
+        const refs = groupBlock.references;
+        assert(refs.map((x) => x.target.uri).every((x) => x === groupBlock.uri));
+        expect(refs.map((x) => x.source.uri)).toEqual(
+          expect.arrayContaining([
+            p('templates/index.json'),
+            p('sections/custom-section.liquid'), // @theme ref
+            p('sections/header-group.json'), // custom-section > group
+            p('blocks/group.liquid'), // @theme ref
+          ]),
+        );
+
+        expect(refs).toContainEqual(
+          // Expecting the `@theme` reference in the custom-section schema to be indirect
+          expect.objectContaining({
+            type: 'indirect',
+            source: {
+              uri: p('sections/custom-section.liquid'),
+              range: [expect.any(Number), expect.any(Number)],
+            },
+          }),
+        );
+      });
+
+      it("finds the app/views/partials/parent's dependencies and references", async () => {
+        const parentPartial = graph.modules[p('app/views/partials/parent.liquid')];
+        assert(parentPartial);
+        assert(parentPartial.type === ModuleType.Liquid);
+        assert(parentPartial.kind === LiquidModuleKind.Partial);
+
+        // outgoing links
+        const deps = parentPartial.dependencies;
+        assert(deps.map((x) => x.source.uri).every((x) => x === parentPartial.uri));
+        expect(deps.map((x) => x.target.uri)).toEqual(
+          expect.arrayContaining([
+            p('app/views/partials/child.liquid'), // {% render 'child' %}
+            p('assets/theme.js'), // <parent-element>
+          ]),
+        );
+
+        // ingoing links
+        const refs = parentPartial.references;
+        assert(refs.map((x) => x.target.uri).every((x) => x === parentPartial.uri));
+        expect(refs.map((x) => x.source.uri)).toEqual(
+          expect.arrayContaining([
+            p('blocks/group.liquid'), // {% render 'parent' %}
+          ]),
+        );
+
+        // {% render 'child', children: children %} dependency
+        const parentSource = await dependencies.getSourceCode(
+          p('app/views/partials/parent.liquid'),
+        );
+        assert(parentSource);
+        assert(parentSource.type === SourceCodeType.LiquidHtml);
+        expect(parentPartial.dependencies.map((x) => x.source)).toContainEqual(
+          expect.objectContaining({
+            uri: p('app/views/partials/parent.liquid'),
+            range: [
+              parentSource.source.indexOf('{% render "child"'),
+              parentSource.source.indexOf('{% render "child"') +
+                '{% render "child", children: children %}'.length,
+            ],
+          }),
+        );
+
+        // <parent-element> dependency
+        expect(parentPartial.dependencies.map((x) => x.source)).toContainEqual(
+          expect.objectContaining({
+            uri: p('app/views/partials/parent.liquid'),
+            range: [
+              parentSource.source.indexOf('<parent-element'),
+              parentSource.source.indexOf('<parent-element') + '<parent-element'.length,
+            ],
+          }),
+        );
+      });
+
+      it("finds the blocks/_static's dependencies and references", () => {
+        const staticBlock = graph.modules[p('blocks/_static.liquid')];
+        assert(staticBlock);
+        assert(staticBlock.type === ModuleType.Liquid);
+        assert(staticBlock.kind === LiquidModuleKind.Block);
+
+        // outgoing links
+        const deps = staticBlock.dependencies;
+        expect(deps).toEqual([]);
+
+        // ingoing links
+        const refs = staticBlock.references;
+        assert(refs.map((x) => x.target.uri).every((x) => x === staticBlock.uri));
+        expect(refs.map((x) => x.source.uri)).toEqual(
+          expect.arrayContaining([
+            p('sections/header-group.json'),
+            p('blocks/render-static.liquid'),
+          ]),
+        );
+      });
+    });
+  });
+});

package/src/graph/build.ts

@@ -0,0 +1,45 @@
+import {
+  recursiveReadDirectory as findAllFiles,
+  path,
+  UriString,
+} from '@platformos/platformos-check-common';
+import { IDependencies, ThemeGraph, ThemeModule } from '../types';
+import { augmentDependencies } from './augment';
+import { getModule } from './module';
+import { traverseModule } from './traverse';
+
+export async function buildThemeGraph(
+  rootUri: UriString,
+  ideps: IDependencies,
+  entryPoints?: UriString[],
+): Promise<ThemeGraph> {
+  const deps = augmentDependencies(rootUri, ideps);
+
+  entryPoints =
+    entryPoints ??
+    (await findAllFiles(deps.fs, rootUri, ([uri]) => {
+      // Templates are entry points in the theme graph.
+      const isTemplateFile = uri.startsWith(path.join(rootUri, 'templates'));
+
+      // Since any section file can be rendered directly by the Section Rendering API,
+      // we consider all section files as entry points.
+      const isSectionFile =
+        uri.startsWith(path.join(rootUri, 'sections')) && uri.endsWith('.liquid');
+
+      return isTemplateFile || isSectionFile;
+    }));
+
+  const graph: ThemeGraph = {
+    entryPoints: [],
+    modules: {},
+    rootUri,
+  };
+
+  graph.entryPoints = entryPoints
+    .map((uri) => getModule(graph, uri))
+    .filter((x): x is ThemeModule => x !== undefined);
+
+  await Promise.all(graph.entryPoints.map((entry) => traverseModule(entry, graph, deps)));
+
+  return graph;
+}

package/src/graph/module.ts

@@ -0,0 +1,212 @@
+import { path, UriString } from '@platformos/platformos-check-common';
+import {
+  CssModule,
+  ImageModule,
+  JavaScriptModule,
+  JsonModule,
+  JsonModuleKind,
+  LiquidModule,
+  LiquidModuleKind,
+  ModuleType,
+  SUPPORTED_ASSET_IMAGE_EXTENSIONS,
+  SvgModule,
+  ThemeGraph,
+  ThemeModule,
+} from '../types';
+import { extname } from '../utils';
+
+/**
+ * We're using a ModuleCache to prevent race conditions with traverse.
+ *
+ * e.g. if we have two modules that depend on the same 'assets/foo.js' file and
+ * that they somehow depend on it before it gets traversed (and thus added to the
+ * graphs' modules record), we want to avoid creating two different module objects
+ * that represent the same file.
+ *
+ * We're using a WeakMap<ThemeGraph> to cache modules so that if the theme graph
+ * gets garbage collected, the module cache will also be garbage collected.
+ *
+ * This allows us to have a module cache without changing the API of the
+ * ThemeGraph (no need for a `visited` property on modules, etc.)
+ */
+const ModuleCache: WeakMap<ThemeGraph, Map<string, ThemeModule>> = new WeakMap();
+
+export function getModule(themeGraph: ThemeGraph, uri: UriString): ThemeModule | undefined {
+  const cache = getCache(themeGraph);
+  if (cache.has(uri)) {
+    return cache.get(uri)!;
+  }
+
+  const relativePath = path.relative(uri, themeGraph.rootUri);
+
+  switch (true) {
+    case relativePath.startsWith('assets'): {
+      return getAssetModule(themeGraph, path.basename(uri));
+    }
+
+    case relativePath.startsWith('blocks'): {
+      return getThemeBlockModule(themeGraph, path.basename(uri, '.liquid'));
+    }
+
+    case relativePath.startsWith('layout'): {
+      return getLayoutModule(themeGraph, path.basename(uri, '.liquid'));
+    }
+
+    case relativePath.startsWith('sections'): {
+      if (relativePath.endsWith('.json')) {
+        return getSectionGroupModule(themeGraph, path.basename(uri, '.json'));
+      }
+      return getSectionModule(themeGraph, path.basename(uri, '.liquid'));
+    }
+
+    case relativePath.includes('/views/partials') || relativePath.includes('/lib/'): {
+      return getPartialModule(themeGraph, path.basename(uri, '.liquid'));
+    }
+
+    case relativePath.startsWith('snippets'): {
+      return getPartialModule(themeGraph, path.basename(uri, '.liquid'));
+    }
+
+    case relativePath.startsWith('templates'): {
+      return getTemplateModule(themeGraph, uri);
+    }
+  }
+}
+
+export function getTemplateModule(themeGraph: ThemeGraph, uri: UriString): ThemeModule {
+  const extension = extname(uri);
+  switch (extension) {
+    case 'json': {
+      return module(themeGraph, {
+        type: ModuleType.Json,
+        kind: JsonModuleKind.Template,
+        dependencies: [],
+        references: [],
+        uri: uri,
+      });
+    }
+
+    case 'liquid': {
+      return module(themeGraph, {
+        type: ModuleType.Liquid,
+        kind: LiquidModuleKind.Template,
+        dependencies: [],
+        references: [],
+        uri: uri,
+      });
+    }
+
+    default: {
+      throw new Error(`Unknown template type for ${uri}`);
+    }
+  }
+}
+
+export function getThemeBlockModule(themeGraph: ThemeGraph, blockType: string): LiquidModule {
+  const uri = path.join(themeGraph.rootUri, 'blocks', `${blockType}.liquid`);
+  return module(themeGraph, {
+    type: ModuleType.Liquid,
+    kind: LiquidModuleKind.Block,
+    dependencies: [],
+    references: [],
+    uri,
+  });
+}
+
+export function getSectionModule(themeGraph: ThemeGraph, sectionType: string): LiquidModule {
+  const uri = path.join(themeGraph.rootUri, 'sections', `${sectionType}.liquid`);
+  return module(themeGraph, {
+    type: ModuleType.Liquid,
+    kind: LiquidModuleKind.Section,
+    dependencies: [],
+    references: [],
+    uri,
+  });
+}
+
+export function getSectionGroupModule(
+  themeGraph: ThemeGraph,
+  sectionGroupType: string,
+): JsonModule {
+  const uri = path.join(themeGraph.rootUri, 'sections', `${sectionGroupType}.json`);
+  return module(themeGraph, {
+    type: ModuleType.Json,
+    kind: JsonModuleKind.SectionGroup,
+    dependencies: [],
+    references: [],
+    uri,
+  });
+}
+
+export function getAssetModule(
+  themeGraph: ThemeGraph,
+  asset: string,
+): JavaScriptModule | CssModule | SvgModule | ImageModule | undefined {
+  const extension = extname(asset);
+
+  let type: ModuleType | undefined = undefined;
+
+  if (SUPPORTED_ASSET_IMAGE_EXTENSIONS.includes(extension)) {
+    type = ModuleType.Image;
+  } else if (extension === 'js') {
+    type = ModuleType.JavaScript;
+  } else if (extension === 'css') {
+    type = ModuleType.Css;
+  } else if (extension === 'svg') {
+    type = ModuleType.Svg;
+  }
+
+  if (!type) {
+    return undefined;
+  }
+
+  return module(themeGraph, {
+    type,
+    kind: 'unused',
+    dependencies: [],
+    references: [],
+    uri: path.join(themeGraph.rootUri, 'assets', asset),
+  });
+}
+
+export function getPartialModule(themeGraph: ThemeGraph, partial: string): LiquidModule {
+  const uri = path.join(themeGraph.rootUri, 'app/views/partials', `${partial}.liquid`);
+  return module(themeGraph, {
+    type: ModuleType.Liquid,
+    kind: LiquidModuleKind.Partial,
+    uri: uri,
+    dependencies: [],
+    references: [],
+  });
+}
+
+export function getLayoutModule(
+  themeGraph: ThemeGraph,
+  layoutName: string | false | undefined = 'theme',
+): LiquidModule | undefined {
+  if (layoutName === false) return undefined;
+  if (layoutName === undefined) layoutName = 'theme';
+  const uri = path.join(themeGraph.rootUri, 'layout', `${layoutName}.liquid`);
+  return module(themeGraph, {
+    type: ModuleType.Liquid,
+    kind: LiquidModuleKind.Layout,
+    uri: uri,
+    dependencies: [],
+    references: [],
+  });
+}
+
+function getCache(themeGraph: ThemeGraph): Map<string, ThemeModule> {
+  if (!ModuleCache.has(themeGraph)) {
+    ModuleCache.set(themeGraph, new Map());
+  }
+  return ModuleCache.get(themeGraph)!;
+}
+
+function module<T extends ThemeModule>(themeGraph: ThemeGraph, mod: T): T {
+  const cache = getCache(themeGraph);
+  if (!cache.has(mod.uri)) {
+    cache.set(mod.uri, mod);
+  }
+  return cache.get(mod.uri)! as T;
+}

package/src/graph/serialize.spec.ts

@@ -0,0 +1,62 @@
+import { path as pathUtils } from '@platformos/platformos-check-common';
+import { describe, expect, it } from 'vitest';
+import { ThemeGraph } from '../types';
+import { getSectionModule, getPartialModule, getTemplateModule } from './module';
+import { serializeThemeGraph } from './serialize';
+import { bind } from './traverse';
+
+describe('Unit: serializeThemeGraph', () => {
+  it('serialize the graph', () => {
+    const rootUri = 'file:///theme';
+    const p = (part: string) => pathUtils.join(rootUri, part);
+    const graph: ThemeGraph = {
+      entryPoints: [],
+      modules: {},
+      rootUri,
+    };
+
+    const template = getTemplateModule(graph, p('templates/index.json'));
+    const customSection = getSectionModule(graph, 'custom-section');
+    const parentPartial = getPartialModule(graph, 'parent');
+    const childPartial = getPartialModule(graph, 'child');
+    bind(template, customSection, { sourceRange: [0, 5] });
+    bind(customSection, parentPartial, { sourceRange: [10, 15] });
+    bind(parentPartial, childPartial, { sourceRange: [20, 25] });
+
+    const section2 = getSectionModule(graph, 'section2');
+    bind(template, section2, { sourceRange: [20, 25] });
+
+    graph.entryPoints = [template];
+    [template, customSection, section2, parentPartial, childPartial].forEach((module) => {
+      graph.modules[module.uri] = module;
+    });
+
+    const { nodes, edges } = serializeThemeGraph(graph);
+    expect(nodes).toHaveLength(5);
+    expect(edges).toHaveLength(4);
+    expect(edges).toEqual(
+      expect.arrayContaining([
+        {
+          source: { uri: 'file:///theme/templates/index.json', range: [0, 5] },
+          target: { uri: 'file:///theme/sections/custom-section.liquid' },
+          type: 'direct',
+        },
+        {
+          source: { uri: 'file:///theme/sections/custom-section.liquid', range: [10, 15] },
+          target: { uri: 'file:///theme/app/views/partials/parent.liquid' },
+          type: 'direct',
+        },
+        {
+          source: { uri: 'file:///theme/app/views/partials/parent.liquid', range: [20, 25] },
+          target: { uri: 'file:///theme/app/views/partials/child.liquid' },
+          type: 'direct',
+        },
+        {
+          source: { uri: 'file:///theme/templates/index.json', range: [20, 25] },
+          target: { uri: 'file:///theme/sections/section2.liquid' },
+          type: 'direct',
+        },
+      ]),
+    );
+  });
+});

package/src/graph/serialize.ts

@@ -0,0 +1,20 @@
+import { SerializableEdge, SerializableGraph, SerializableNode, ThemeGraph } from '../types';
+
+export function serializeThemeGraph(graph: ThemeGraph): SerializableGraph {
+  const nodes: SerializableNode[] = Object.values(graph.modules).map((module) => ({
+    uri: module.uri,
+    type: module.type,
+    kind: module.kind,
+    ...('exists' in module ? { exists: module.exists } : {}),
+  }));
+
+  const edges: SerializableEdge[] = Object.values(graph.modules).flatMap(
+    (module) => module.dependencies,
+  );
+
+  return {
+    rootUri: graph.rootUri,
+    nodes,
+    edges,
+  };
+}

package/src/graph/test-helpers.ts

@@ -0,0 +1,57 @@
+import {
+  LiquidSourceCode,
+  memoize,
+  path as pathUtils,
+  SectionSchema,
+  ThemeBlockSchema,
+  toSchema,
+} from '@platformos/platformos-check-common';
+import { AbstractFileSystem } from '@platformos/platformos-common';
+import { NodeFileSystem } from '@platformos/platformos-check-node';
+import { vi } from 'vitest';
+import { URI } from 'vscode-uri';
+import { getWebComponentMap } from '../getWebComponentMap';
+import { toSourceCode } from '../toSourceCode';
+import { identity } from '../utils';
+
+export function makeGetSourceCode(fs: AbstractFileSystem) {
+  return memoize(async function getSourceCode(uri: string) {
+    const source = await fs.readFile(uri);
+    return toSourceCode(URI.file(uri).toString(), source);
+  }, identity);
+}
+
+export const fixturesRoot = pathUtils.join(URI.file(__dirname), ...'../../fixtures'.split('/'));
+export const skeleton = pathUtils.join(fixturesRoot, 'skeleton');
+
+export async function getDependencies(rootUri: string, fs: AbstractFileSystem = NodeFileSystem) {
+  const getSourceCode = makeGetSourceCode(fs);
+  const deps = {
+    fs,
+    getSectionSchema: memoize(async (name: string) => {
+      const uri = pathUtils.join(skeleton, 'sections', `${name}.liquid`);
+      const sourceCode = (await getSourceCode(uri)) as LiquidSourceCode;
+      return (await toSchema('theme', uri, sourceCode, async () => true)) as SectionSchema;
+    }, identity),
+    getBlockSchema: memoize(async (name: string) => {
+      const uri = pathUtils.join(skeleton, 'blocks', `${name}.liquid`);
+      const sourceCode = (await getSourceCode(uri)) as LiquidSourceCode;
+      return (await toSchema('theme', uri, sourceCode, async () => true)) as ThemeBlockSchema;
+    }, identity),
+    getSourceCode,
+    getWebComponentDefinitionReference: (customElementName: string) =>
+      webComponentDefs.get(customElementName),
+  };
+
+  const webComponentDefs = await getWebComponentMap(rootUri, deps);
+
+  return deps;
+}
+
+// This thing is way too hard to type.
+export function mockImpl(obj: any, method: any, callback: any) {
+  const original = obj[method].bind(obj);
+  return vi.spyOn(obj, method).mockImplementation(function () {
+    return callback(original, ...arguments);
+  });
+}