@platformos/platformos-graph 0.0.19 → 0.1.0

package/src/graph/test-helpers.ts

@@ -1,34 +1,27 @@
 import { memoize, path as pathUtils } from '@platformos/platformos-check-common';
-import { AbstractFileSystem } from '@platformos/platformos-common';
+import { AbstractFileSystem, uriFromPath } 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);
+    return toSourceCode(pathUtils.toUri(uri), source);
   }, identity);
 }
 
-export const fixturesRoot = pathUtils.join(URI.file(__dirname), ...'../../fixtures'.split('/'));
+export const fixturesRoot = pathUtils.join(uriFromPath(__dirname), ...'../../fixtures'.split('/'));
 export const skeleton = pathUtils.join(fixturesRoot, 'skeleton');
 
-export async function getDependencies(rootUri: string, fs: AbstractFileSystem = NodeFileSystem) {
+export function getDependencies(fs: AbstractFileSystem = NodeFileSystem) {
   const getSourceCode = makeGetSourceCode(fs);
-  const deps = {
+  return {
     fs,
     getSourceCode,
-    getWebComponentDefinitionReference: (customElementName: string) =>
-      webComponentDefs.get(customElementName),
   };
-
-  const webComponentDefs = await getWebComponentMap(rootUri, deps);
-
-  return deps;
 }
 
 // This thing is way too hard to type.

package/src/graph/traverse.spec.ts

@@ -0,0 +1,278 @@
+import { path as pathUtils } from '@platformos/platformos-check-common';
+import { describe, expect, it } from 'vitest';
+import { extractFileReferences, extractStructural } from '../index';
+import { toSourceCode } from '../toSourceCode';
+import { ModuleStructural, Reference } from '../types';
+import { fixturesRoot, getDependencies } from './test-helpers';
+
+/**
+ * `extractFileReferences` is the per-file primitive a `validate_code`-style
+ * consumer uses: parse an in-flight buffer with `toSourceCode`, then resolve its
+ * outgoing dependency edges against the on-disk project — WITHOUT building the
+ * whole app graph. The buffer is never read from disk, so these specs pass the
+ * content inline (and even use a `sourceUri` for a file that does not exist).
+ */
+const { fs } = getDependencies();
+
+/** The exact source range of `snippet` within `source`. */
+function rangeOf(source: string, snippet: string): [number, number] {
+  const start = source.indexOf(snippet);
+  if (start < 0) throw new Error(`snippet not found: ${snippet}`);
+  return [start, start + snippet.length];
+}
+
+function directRef(
+  sourceUri: string,
+  sourceRange: [number, number],
+  targetUri: string,
+  kind: Reference['kind'],
+  args?: string[],
+): Reference {
+  return {
+    source: { uri: sourceUri, range: sourceRange },
+    target: { uri: targetUri },
+    type: 'direct',
+    kind,
+    ...(args ? { args } : {}),
+  };
+}
+
+async function extract(rootUri: string, sourceUri: string, content: string) {
+  return extractFileReferences(rootUri, sourceUri, await toSourceCode(sourceUri, content), { fs });
+}
+
+describe('extractFileReferences: resolves a single buffer against the project', () => {
+  const rootUri = pathUtils.join(fixturesRoot, 'function-edges');
+  const p = (part: string) => pathUtils.join(rootUri, ...part.split('/'));
+
+  it('resolves a {% function %} edge to the canonical lib URI', async () => {
+    const sourceUri = p('app/views/pages/draft.liquid'); // not on disk — in-flight buffer
+    const content = `{% liquid
+  function items = 'queries/list'
+%}`;
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([
+      directRef(
+        sourceUri,
+        rangeOf(content, "function items = 'queries/list'"),
+        p('app/lib/queries/list.liquid'),
+        'function',
+      ),
+    ]);
+  });
+
+  it('resolves a target that does not exist on disk (path-based resolution)', async () => {
+    const sourceUri = p('app/views/pages/draft.liquid');
+    const content = `{% liquid
+  function ghost = 'queries/missing'
+%}`;
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([
+      directRef(
+        sourceUri,
+        rangeOf(content, "function ghost = 'queries/missing'"),
+        p('app/lib/queries/missing.liquid'),
+        'function',
+      ),
+    ]);
+  });
+
+  it('captures the named-argument names at a render call site', async () => {
+    const sourceUri = p('app/views/pages/draft.liquid');
+    const content = "{% render 'card', title: page.title, count: 3 %}";
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([
+      directRef(
+        sourceUri,
+        rangeOf(content, "{% render 'card', title: page.title, count: 3 %}"),
+        p('app/views/partials/card.liquid'),
+        'render',
+        ['title', 'count'],
+      ),
+    ]);
+  });
+});
+
+describe('extractFileReferences: kinds and resolution match the full graph build', () => {
+  it('tags include edges with kind "include"', async () => {
+    const rootUri = pathUtils.join(fixturesRoot, 'include-edges');
+    const p = (part: string) => pathUtils.join(rootUri, ...part.split('/'));
+    const sourceUri = p('app/views/pages/draft.liquid');
+    const content = "{% include 'shared/header' %}";
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([
+      directRef(
+        sourceUri,
+        rangeOf(content, "{% include 'shared/header' %}"),
+        p('app/views/partials/shared/header.liquid'),
+        'include',
+      ),
+    ]);
+  });
+
+  it('resolves a {% graphql %} edge to the .graphql operation file', async () => {
+    const rootUri = pathUtils.join(fixturesRoot, 'graphql-edges');
+    const p = (part: string) => pathUtils.join(rootUri, ...part.split('/'));
+    const sourceUri = p('app/views/pages/draft.liquid');
+    const content = `{% liquid
+  graphql posts = 'blog_posts/find', id: '1'
+%}`;
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([
+      directRef(
+        sourceUri,
+        rangeOf(content, "graphql posts = 'blog_posts/find', id: '1'"),
+        p('app/graphql/blog_posts/find.graphql'),
+        'graphql',
+        ['id'],
+      ),
+    ]);
+  });
+
+  it('resolves module-namespaced render + function targets in declaration order', async () => {
+    const rootUri = pathUtils.join(fixturesRoot, 'module-edges');
+    const p = (part: string) => pathUtils.join(rootUri, ...part.split('/'));
+    const sourceUri = p('app/views/pages/draft.liquid');
+    const content = `{% liquid
+  function items = 'modules/my_module/queries/get'
+%}
+{% render 'modules/my_module/card' %}`;
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([
+      directRef(
+        sourceUri,
+        rangeOf(content, "function items = 'modules/my_module/queries/get'"),
+        p('modules/my_module/public/lib/queries/get.liquid'),
+        'function',
+      ),
+      directRef(
+        sourceUri,
+        rangeOf(content, "{% render 'modules/my_module/card' %}"),
+        p('modules/my_module/public/views/partials/card.liquid'),
+        'render',
+      ),
+    ]);
+  });
+});
+
+describe('extractFileReferences: only statically resolvable edges', () => {
+  const rootUri = pathUtils.join(fixturesRoot, 'function-edges');
+  const sourceUri = pathUtils.join(rootUri, 'app/views/pages/draft.liquid');
+
+  it('skips dynamic render targets', async () => {
+    expect(await extract(rootUri, sourceUri, '{% render partial_name %}')).toEqual([]);
+  });
+
+  it('returns nothing for an unparseable buffer instead of throwing', async () => {
+    expect(await extract(rootUri, sourceUri, '{% render %}{% endif %}')).toEqual([]);
+  });
+
+  it('returns nothing for a buffer with no references', async () => {
+    expect(await extract(rootUri, sourceUri, '<h1>{{ page.title }}</h1>')).toEqual([]);
+  });
+});
+
+describe('extractFileReferences: layout-association edges (frontmatter `layout:`)', () => {
+  const rootUri = pathUtils.join(fixturesRoot, 'function-edges'); // no layouts here → default path
+  const p = (part: string) => pathUtils.join(rootUri, ...part.split('/'));
+  const sourceUri = p('app/views/pages/draft.liquid');
+
+  // The whole frontmatter block: start through the closing `---` line + newline.
+  const fmRange = (content: string): [number, number] => [
+    0,
+    content.indexOf('\n', content.indexOf('---', 3)) + 1,
+  ];
+
+  it('emits a layout edge for an explicit frontmatter layout', async () => {
+    const content = `---
+slug: draft
+layout: theme
+---
+<h1>x</h1>`;
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([
+      directRef(sourceUri, fmRange(content), p('app/views/layouts/theme.liquid'), 'layout'),
+    ]);
+  });
+
+  it('resolves a module-prefixed layout', async () => {
+    const content = `---
+layout: modules/core/admin
+---
+<h1>x</h1>`;
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([
+      directRef(
+        sourceUri,
+        fmRange(content),
+        p('modules/core/public/views/layouts/admin.liquid'),
+        'layout',
+      ),
+    ]);
+  });
+
+  it('emits no edge for an explicitly empty layout', async () => {
+    const content = `---
+slug: draft
+layout: ''
+---
+<h1>x</h1>`;
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([]);
+  });
+
+  it('emits no edge when layout is omitted (no implicit default)', async () => {
+    const content = `---
+slug: draft
+---
+<h1>x</h1>`;
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([]);
+  });
+
+  it('emits no edge for a dynamic layout value', async () => {
+    const content = `---
+layout: "{{ context.constants.LAYOUT }}"
+---
+<h1>x</h1>`;
+
+    expect(await extract(rootUri, sourceUri, content)).toEqual([]);
+  });
+});
+
+describe('extractStructural: the per-file primitive', () => {
+  const rootUri = pathUtils.join(fixturesRoot, 'structural');
+  // `rootUri` is already a URI, so joining is the whole conversion — `URI.file` on one
+  // yields `file:///file%3A///…`, a plausible-looking URI for nowhere.
+  const uriOf = (part: string) => pathUtils.join(rootUri, ...part.split('/'));
+
+  const run = async (part: string, content: string): Promise<ModuleStructural | undefined> => {
+    const uri = uriOf(part);
+    return extractStructural(await toSourceCode(uri, content), uri);
+  };
+
+  it('extracts usage + routing facts from an in-flight buffer (no graph build)', async () => {
+    const content = `---
+layout: theme
+method: post
+---
+{% render 'card' %}
+{{ 'greeting.hi' | t }}
+{{ title | upcase }}`;
+    expect(await run('app/views/pages/contact.liquid', content)).toEqual({
+      renders_used: ['card'],
+      graphql_queries_used: [],
+      filters_used: ['t', 'upcase'],
+      tags_used: ['render'],
+      translation_keys: ['greeting.hi'],
+      doc_params: [],
+      slug: 'contact',
+      layout: 'theme',
+      method: 'post',
+    });
+  });
+
+  it('returns undefined for a non-Liquid (.graphql) buffer', async () => {
+    expect(await run('app/graphql/find.graphql', 'query find { records { id } }')).toBeUndefined();
+  });
+});