@platformos/platformos-graph 0.0.19 → 0.0.20

package/src/cli.spec.ts

@@ -0,0 +1,265 @@
+import nodePath from 'node:path';
+import { path } from '@platformos/platformos-check-common';
+import { AbstractFileSystem, FileType } from '@platformos/platformos-common';
+import { describe, expect, it } from 'vitest';
+import { URI } from 'vscode-uri';
+import { buildSerializedFileDependencies, buildSerializedGraph, nodeFileSystem } from './cli';
+import { skeleton } from './graph/test-helpers';
+import { LiquidModuleKind, ModuleType } from './types';
+
+const skeletonPath = path.fsPath(skeleton);
+const p = (rel: string) => path.join(skeleton, ...rel.split('/'));
+const fsPathOf = (rel: string) => nodePath.join(skeletonPath, ...rel.split('/'));
+
+describe('platformos-graph CLI: buildSerializedGraph', () => {
+  it('serializes the full node and edge set for a project path', async () => {
+    const graph = await buildSerializedGraph(skeletonPath);
+
+    // Root is the project path re-expressed as a file URI.
+    expect(graph.rootUri).toBe(URI.file(skeletonPath).toString(true));
+
+    // Whole node set, sorted by URI so the assertion is order-independent.
+    expect([...graph.nodes].sort((a, b) => a.uri.localeCompare(b.uri))).toEqual([
+      {
+        uri: p('app/views/layouts/application.liquid'),
+        type: ModuleType.Liquid,
+        kind: LiquidModuleKind.Layout,
+        exists: true,
+      },
+      {
+        uri: p('app/views/pages/index.liquid'),
+        type: ModuleType.Liquid,
+        kind: LiquidModuleKind.Page,
+        exists: true,
+      },
+      {
+        uri: p('app/views/partials/child.liquid'),
+        type: ModuleType.Liquid,
+        kind: LiquidModuleKind.Partial,
+        exists: true,
+      },
+      {
+        uri: p('app/views/partials/header.liquid'),
+        type: ModuleType.Liquid,
+        kind: LiquidModuleKind.Partial,
+        exists: true,
+      },
+      {
+        uri: p('app/views/partials/parent.liquid'),
+        type: ModuleType.Liquid,
+        kind: LiquidModuleKind.Partial,
+        exists: true,
+      },
+      {
+        uri: p('assets/app.css'),
+        type: ModuleType.Asset,
+        kind: 'unused',
+        exists: true,
+      },
+      {
+        uri: p('assets/app.js'),
+        type: ModuleType.Asset,
+        kind: 'unused',
+        exists: true,
+      },
+    ]);
+
+    // Whole edge set, reduced to (source, target, type, kind) and sorted, so an
+    // extra, missing, or mis-kinded edge fails the assertion.
+    const edges = graph.edges
+      .map((edge) => ({
+        source: edge.source.uri,
+        target: edge.target.uri,
+        type: edge.type,
+        kind: edge.kind,
+      }))
+      .sort((a, b) => a.source.localeCompare(b.source) || a.target.localeCompare(b.target));
+
+    expect(edges).toEqual([
+      {
+        source: p('app/views/layouts/application.liquid'),
+        target: p('app/views/partials/header.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+      {
+        source: p('app/views/layouts/application.liquid'),
+        target: p('assets/app.css'),
+        type: 'direct',
+        kind: 'asset',
+      },
+      {
+        source: p('app/views/layouts/application.liquid'),
+        target: p('assets/app.js'),
+        type: 'direct',
+        kind: 'asset',
+      },
+      {
+        source: p('app/views/pages/index.liquid'),
+        target: p('app/views/partials/parent.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+      {
+        source: p('app/views/partials/header.liquid'),
+        target: p('app/views/partials/child.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+      {
+        source: p('app/views/partials/parent.liquid'),
+        target: p('app/views/partials/child.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+    ]);
+  });
+});
+
+describe('platformos-graph CLI: nodeFileSystem', () => {
+  it('reads a file by URI', async () => {
+    const uri = path.join(skeleton, 'assets', 'app.js');
+    expect(await nodeFileSystem.readFile(uri)).toBe(
+      '// Skeleton app bundle (asset reference target).\n',
+    );
+  });
+
+  it('stats a directory and a file', async () => {
+    expect(await nodeFileSystem.stat(path.join(skeleton, 'assets'))).toEqual({
+      type: FileType.Directory,
+      size: expect.any(Number),
+    });
+    expect(await nodeFileSystem.stat(path.join(skeleton, 'assets', 'app.css'))).toEqual({
+      type: FileType.File,
+      size: expect.any(Number),
+    });
+  });
+
+  it('lists a directory as [childUri, FileType] tuples', async () => {
+    const entries = await nodeFileSystem.readDirectory(path.join(skeleton, 'assets'));
+    expect([...entries].sort((a, b) => a[0].localeCompare(b[0]))).toEqual([
+      [path.join(skeleton, 'assets', 'app.css'), FileType.File],
+      [path.join(skeleton, 'assets', 'app.js'), FileType.File],
+    ]);
+  });
+});
+
+describe('platformos-graph CLI: buildSerializedFileDependencies', () => {
+  const edge = (ref: {
+    source: { uri: string };
+    target: { uri: string };
+    type: string;
+    kind?: string;
+  }) => ({
+    source: ref.source.uri,
+    target: ref.target.uri,
+    type: ref.type,
+    kind: ref.kind,
+  });
+
+  it('returns the outgoing and incoming edges of a single file', async () => {
+    const result = await buildSerializedFileDependencies(
+      skeletonPath,
+      fsPathOf('app/views/partials/parent.liquid'),
+    );
+
+    expect(result.uri).toBe(p('app/views/partials/parent.liquid'));
+    expect(result.dependencies.map(edge)).toEqual([
+      {
+        source: p('app/views/partials/parent.liquid'),
+        target: p('app/views/partials/child.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+    ]);
+    expect(result.references.map(edge)).toEqual([
+      {
+        source: p('app/views/pages/index.liquid'),
+        target: p('app/views/partials/parent.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+    ]);
+  });
+
+  it('returns no dependencies for a leaf partial and every incoming reference', async () => {
+    const result = await buildSerializedFileDependencies(
+      skeletonPath,
+      fsPathOf('app/views/partials/child.liquid'),
+    );
+
+    expect(result.uri).toBe(p('app/views/partials/child.liquid'));
+    expect(result.dependencies).toEqual([]);
+    expect(result.references.map(edge).sort((a, b) => a.source.localeCompare(b.source))).toEqual([
+      {
+        source: p('app/views/partials/header.liquid'),
+        target: p('app/views/partials/child.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+      {
+        source: p('app/views/partials/parent.liquid'),
+        target: p('app/views/partials/child.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+    ]);
+  });
+
+  it('resolves a relative file argument against the project root, not the cwd', async () => {
+    const result = await buildSerializedFileDependencies(
+      skeletonPath,
+      'app/views/partials/parent.liquid',
+    );
+
+    expect(result.uri).toBe(p('app/views/partials/parent.liquid'));
+    expect(result.dependencies.map(edge)).toEqual([
+      {
+        source: p('app/views/partials/parent.liquid'),
+        target: p('app/views/partials/child.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+    ]);
+  });
+
+  it('throws for a file that is not part of the app graph', async () => {
+    const missing = fsPathOf('app/views/partials/nonexistent.liquid');
+    const missingUri = path.normalize(URI.file(missing));
+    const rootUri = path.normalize(URI.file(skeletonPath));
+
+    const error = await buildSerializedFileDependencies(skeletonPath, missing).catch((e) => e);
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toBe(
+      `File is not part of the app graph: ${missingUri}\n` +
+        `It must exist and be reachable from a layout or page entry point. ` +
+        `Check the path is correct and inside the project root (${rootUri}).`,
+    );
+  });
+});
+
+describe('platformos-graph CLI: project-root validation', () => {
+  /**
+   * A filesystem where nothing exists. Injected so `findRoot` walks up from the
+   * given path entirely in memory — no real disk, no dependency on what sits
+   * above the OS temp dir — and deterministically finds no project marker.
+   */
+  const emptyFs: AbstractFileSystem = {
+    stat: () => Promise.reject(new Error('ENOENT')),
+    readFile: () => Promise.reject(new Error('ENOENT')),
+    readDirectory: () => Promise.resolve([]),
+  };
+
+  it('throws instead of emitting an empty graph for a non-platformOS directory', async () => {
+    const dir = nodePath.resolve('no-such-project', 'sub');
+    const startUri = path.normalize(URI.file(dir));
+
+    const error = await buildSerializedGraph(dir, emptyFs).catch((e) => e);
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toBe(
+      `Not a platformOS project: ${startUri}\n` +
+        `No app/, modules/, .pos, or .platformos-check.yml found at or above this path. ` +
+        `Pass the path to a platformOS app directory.`,
+    );
+  });
+});

package/src/cli.ts

@@ -0,0 +1,151 @@
+import nodePath from 'node:path';
+import fs from 'node:fs/promises';
+import { findRoot, makeFileExists, path } from '@platformos/platformos-check-common';
+import { AbstractFileSystem, FileStat, FileTuple, FileType } from '@platformos/platformos-common';
+import { URI } from 'vscode-uri';
+import { buildAppGraph } from './graph/build';
+import { serializeAppGraph } from './graph/serialize';
+import { Reference, SerializableGraph } from './types';
+
+/**
+ * A self-contained {@link AbstractFileSystem} backed by `node:fs`.
+ *
+ * The graph driver speaks file URIs, so every method converts the incoming URI
+ * to a native path with `path.fsPath` and re-emits child URIs with `path.join`
+ * (which preserves the `file://` scheme). This mirrors `NodeFileSystem` from
+ * `@platformos/platformos-check-node` exactly, but is inlined here so the CLI
+ * runs with only this package's own dependencies — `platformos-check-node` is a
+ * dev-only dependency and must not be required at runtime.
+ */
+export const nodeFileSystem: AbstractFileSystem = {
+  async readFile(uri: string): Promise<string> {
+    return fs.readFile(path.fsPath(uri), 'utf8');
+  },
+
+  async readDirectory(uri: string): Promise<FileTuple[]> {
+    const entries = await fs.readdir(path.fsPath(uri), { withFileTypes: true });
+    return entries.map((entry) => [
+      path.join(uri, entry.name),
+      entry.isDirectory() ? FileType.Directory : FileType.File,
+    ]);
+  },
+
+  async stat(uri: string): Promise<FileStat> {
+    try {
+      const stats = await fs.stat(path.fsPath(uri));
+      return {
+        type: stats.isDirectory() ? FileType.Directory : FileType.File,
+        size: stats.size,
+      };
+    } catch (e) {
+      throw new Error(`Failed to get file stat: ${e}`);
+    }
+  },
+};
+
+/**
+ * The dependency and reference edges of a single module, as produced for the
+ * CLI's single-file mode.
+ */
+export interface SerializableFileDependencies {
+  /** The resolved file URI, as keyed in the graph. */
+  uri: string;
+  /** Outgoing edges — the modules this file renders/includes/runs/queries. */
+  dependencies: Reference[];
+  /** Incoming edges — the modules that render/include/run/query this file. */
+  references: Reference[];
+}
+
+/**
+ * Resolves the given root path (absolute, or relative to `process.cwd()`) to the
+ * forward-slash-normalized `file://` URI of the enclosing platformOS project,
+ * using the same `findRoot` heuristic as the language server (an `app/`,
+ * `modules/`, `.pos`, or `.platformos-check.yml` marker at or above the path).
+ *
+ * Throws when no project is found, so a typo'd or non-platformOS directory fails
+ * loudly instead of silently producing an empty graph. Resolving via `findRoot`
+ * also lets the CLI be pointed anywhere inside a project, not just at its root.
+ *
+ * Normalization is load-bearing: the graph keys every module via `path.join` /
+ * `path.normalize` (forward slashes), so any lookup must key the same way or it
+ * silently misses on Windows, where raw URIs keep backslashes.
+ */
+async function resolveProjectRoot(root: string, fs: AbstractFileSystem): Promise<string> {
+  const absolute = nodePath.isAbsolute(root) ? root : nodePath.resolve(process.cwd(), root);
+  const startUri = path.normalize(URI.file(absolute));
+
+  const rootUri = await findRoot(startUri, makeFileExists(fs));
+  if (!rootUri) {
+    throw new Error(
+      `Not a platformOS project: ${startUri}\n` +
+        `No app/, modules/, .pos, or .platformos-check.yml found at or above this path. ` +
+        `Pass the path to a platformOS app directory.`,
+    );
+  }
+  return rootUri;
+}
+
+/**
+ * Resolves the single-file argument to a graph module key. An absolute path is
+ * taken as-is; a relative path is resolved against the project **root** (not
+ * `process.cwd()`), matching the natural "a file within this project" mental
+ * model — only files under the root can appear in the graph anyway.
+ */
+function resolveFileUri(rootUri: string, file: string): string {
+  if (nodePath.isAbsolute(file)) {
+    return path.normalize(URI.file(file));
+  }
+  return path.join(rootUri, ...file.split(/[\\/]+/).filter(Boolean));
+}
+
+/**
+ * Builds the platformOS app graph for the project rooted at `root` (a native
+ * filesystem path, absolute or relative to `process.cwd()`) and returns it in
+ * serializable JSON form.
+ *
+ * `fs` is injectable for testing; it defaults to the node-backed filesystem.
+ */
+export async function buildSerializedGraph(
+  root: string,
+  fs: AbstractFileSystem = nodeFileSystem,
+): Promise<SerializableGraph> {
+  const graph = await buildAppGraph(await resolveProjectRoot(root, fs), { fs });
+  return serializeAppGraph(graph);
+}
+
+/**
+ * Builds the full app graph for `root` and returns the dependency and reference
+ * edges of the single module at `file`.
+ *
+ * The graph is built from its real entry points (every layout and page), not
+ * seeded from `file`, so that incoming `references` are complete — the same
+ * approach the language server's `AppGraphManager` takes. A file that is not
+ * reachable from any entry point therefore has no node in the graph; rather
+ * than reporting a misleading empty edge set, this throws.
+ *
+ * `fs` is injectable for testing; it defaults to the node-backed filesystem.
+ */
+export async function buildSerializedFileDependencies(
+  root: string,
+  file: string,
+  fs: AbstractFileSystem = nodeFileSystem,
+): Promise<SerializableFileDependencies> {
+  const rootUri = await resolveProjectRoot(root, fs);
+  const fileUri = resolveFileUri(rootUri, file);
+  const graph = await buildAppGraph(rootUri, { fs });
+
+  const module = graph.modules[fileUri];
+  if (!module) {
+    throw new Error(
+      `File is not part of the app graph: ${fileUri}\n` +
+        `It must exist and be reachable from a layout or page entry point. ` +
+        `Check the path is correct and inside the project root (${rootUri}).`,
+    );
+  }
+
+  return {
+    uri: module.uri,
+    dependencies: module.dependencies,
+    references: module.references,
+  };
+}

package/src/graph/augment.ts

@@ -16,7 +16,5 @@ export function augmentDependencies(rootUri: string, ideps: IDependencies): Augm
         },
       identity,
     ),
-
-    getWebComponentDefinitionReference: ideps.getWebComponentDefinitionReference,
   };
 }

package/src/graph/build.spec.ts

@@ -11,7 +11,7 @@ describe('Module: index', () => {
   let dependencies: Dependencies;
 
   beforeAll(async () => {
-    dependencies = await getDependencies(rootUri);
+    dependencies = getDependencies();
   }, 15000);
 
   describe('Unit: buildAppGraph', { timeout: 10000 }, () => {
@@ -64,12 +64,10 @@ describe('Module: index', () => {
         assert(parentPartial.type === ModuleType.Liquid);
         assert(parentPartial.kind === LiquidModuleKind.Partial);
 
-        // outgoing links
+        // outgoing links — parent renders exactly one partial (child)
         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'), p('assets/app.js')]),
-        );
+        expect(deps.map((x) => x.target.uri)).toEqual([p('app/views/partials/child.liquid')]);
 
         // {% render 'child' %} dependency
         const parentSource = await dependencies.getSourceCode(
@@ -103,6 +101,22 @@ describe('Module: index', () => {
           ]),
         );
       });
+
+      it('tags every layout edge with its kind (asset, asset, render)', () => {
+        const layout = graph.modules[p('app/views/layouts/application.liquid')];
+        assert(layout);
+
+        // The complete, ordered edge set — not a membership probe — so an extra,
+        // missing, or mis-kinded edge fails. (Source ranges are pinned by the
+        // dedicated render-dependency test above.)
+        expect(
+          layout.dependencies.map((d) => ({ target: d.target.uri, type: d.type, kind: d.kind })),
+        ).toEqual([
+          { target: p('assets/app.js'), type: 'direct', kind: 'asset' },
+          { target: p('assets/app.css'), type: 'direct', kind: 'asset' },
+          { target: p('app/views/partials/header.liquid'), type: 'direct', kind: 'render' },
+        ]);
+      });
     });
   });
 });

package/src/graph/extract.spec.ts

@@ -0,0 +1,155 @@
+import { path as pathUtils } from '@platformos/platformos-check-common';
+import { describe, expect, it } from 'vitest';
+import { extractFileReferences } from '../index';
+import { toSourceCode } from '../toSourceCode';
+import { 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'],
+): Reference {
+  return {
+    source: { uri: sourceUri, range: sourceRange },
+    target: { uri: targetUri },
+    type: 'direct',
+    kind,
+  };
+}
+
+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',
+      ),
+    ]);
+  });
+});
+
+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',
+      ),
+    ]);
+  });
+
+  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([]);
+  });
+});

package/src/graph/module.ts

@@ -3,6 +3,7 @@ import {
   AssetModule,
   AppGraph,
   AppModule,
+  GraphQLModule,
   LiquidModule,
   LiquidModuleKind,
   ModuleType,
@@ -88,6 +89,45 @@ export function getPartialModule(appGraph: AppGraph, partial: string): LiquidMod
   });
 }
 
+/**
+ * Create (or fetch the cached) Liquid Partial module for an ALREADY-RESOLVED
+ * full URI — used for `{% function %}` / `{% include %}` targets whose URI is
+ * resolved canonically by `DocumentsLocator` (which handles lib paths, module
+ * prefixes, and extensions). Unlike {@link getPartialModule}, it does not
+ * reconstruct the path from a name. Commands/queries/lib helpers are all
+ * `Partial` kind, consistent with check-common's file-type classification.
+ */
+export function getPartialModuleByUri(appGraph: AppGraph, uri: string): LiquidModule {
+  return module(appGraph, {
+    type: ModuleType.Liquid,
+    kind: LiquidModuleKind.Partial,
+    // Normalize to forward slashes so module keys match the rest of the graph
+    // (getPartialModule/getAssetModule build URIs via path.join, which
+    // normalizes). DocumentsLocator returns `Utils.joinPath(...).toString()`
+    // unnormalized, which on Windows keeps backslashes and breaks key/edge
+    // matching against the normalized URIs everywhere else.
+    uri: path.normalize(uri),
+    dependencies: [],
+    references: [],
+  });
+}
+
+/**
+ * Create (or fetch the cached) GraphQL module for an already-resolved
+ * `.graphql` URI — used for `{% graphql op = 'name' %}` targets resolved by
+ * `DocumentsLocator`. A leaf node (no outgoing edges).
+ */
+export function getGraphQLModuleByUri(appGraph: AppGraph, uri: string): GraphQLModule {
+  return module(appGraph, {
+    type: ModuleType.GraphQL,
+    kind: 'graphql',
+    // Normalize to forward slashes — see getPartialModuleByUri.
+    uri: path.normalize(uri),
+    dependencies: [],
+    references: [],
+  });
+}
+
 export function getLayoutModule(
   appGraph: AppGraph,
   layoutUri: string | false | undefined,