@platformos/platformos-graph 0.0.20 → 0.2.0

package/src/graph/serialize.spec.ts

@@ -1,7 +1,7 @@
 import { path as pathUtils } from '@platformos/platformos-check-common';
 import { describe, expect, it } from 'vitest';
 import { AppGraph } from '../types';
-import { getLayoutModule, getPartialModule } from './module';
+import { getLayoutModule, getPartialModuleByUri } from './module';
 import { serializeAppGraph } from './serialize';
 import { bind } from './traverse';
 
@@ -16,9 +16,9 @@ describe('Unit: serializeAppGraph', () => {
     };
 
     const layout = getLayoutModule(graph, p('app/views/layouts/application.liquid'))!;
-    const headerPartial = getPartialModule(graph, 'header');
-    const parentPartial = getPartialModule(graph, 'parent');
-    const childPartial = getPartialModule(graph, 'child');
+    const headerPartial = getPartialModuleByUri(graph, p('app/views/partials/header.liquid'));
+    const parentPartial = getPartialModuleByUri(graph, p('app/views/partials/parent.liquid'));
+    const childPartial = getPartialModuleByUri(graph, p('app/views/partials/child.liquid'));
 
     bind(layout, headerPartial, { sourceRange: [0, 5] });
     bind(layout, parentPartial, { sourceRange: [10, 15] });

package/src/graph/test-helpers.ts

@@ -1,5 +1,5 @@
 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';
@@ -9,11 +9,11 @@ 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 function getDependencies(fs: AbstractFileSystem = NodeFileSystem) {

package/src/graph/{extract.spec.ts → traverse.spec.ts}

@@ -1,8 +1,8 @@
 import { path as pathUtils } from '@platformos/platformos-check-common';
 import { describe, expect, it } from 'vitest';
-import { extractFileReferences } from '../index';
+import { extractFileReferences, extractStructural } from '../index';
 import { toSourceCode } from '../toSourceCode';
-import { Reference } from '../types';
+import { ModuleStructural, Reference } from '../types';
 import { fixturesRoot, getDependencies } from './test-helpers';
 
 /**
@@ -26,12 +26,14 @@ function directRef(
   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 } : {}),
   };
 }
 
@@ -74,6 +76,21 @@ describe('extractFileReferences: resolves a single buffer against the project',
       ),
     ]);
   });
+
+  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', () => {
@@ -107,6 +124,7 @@ describe('extractFileReferences: kinds and resolution match the full graph build
         rangeOf(content, "graphql posts = 'blog_posts/find', id: '1'"),
         p('app/graphql/blog_posts/find.graphql'),
         'graphql',
+        ['id'],
       ),
     ]);
   });
@@ -153,3 +171,108 @@ describe('extractFileReferences: only statically resolvable edges', () => {
     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();
+  });
+});

package/src/graph/traverse.ts

@@ -1,13 +1,31 @@
-import { NamedTags, NodeTypes } from '@platformos/liquid-html-parser';
-import { SourceCodeType, UriString, visit, Visitor } from '@platformos/platformos-check-common';
-import { DocumentsLocator } from '@platformos/platformos-common';
+import yaml from 'js-yaml';
+import { LiquidNamedArgument, NamedTags, NodeTypes } from '@platformos/liquid-html-parser';
+import {
+  isTranslationKeyUsage,
+  SourceCodeType,
+  UriString,
+  visit,
+  Visitor,
+} from '@platformos/platformos-check-common';
+import {
+  containsLiquid,
+  DocumentsLocator,
+  effectivePageSlug,
+  extractGraphqlTables,
+  extractRelativePagePath,
+  extractSchemaTable,
+  isGraphqlDocument,
+  PLATFORM_YAML_LOAD_OPTIONS,
+} from '@platformos/platformos-common';
 import { URI } from 'vscode-uri';
 import {
   AugmentedDependencies,
   AppGraph,
   AppModule,
   FileSourceCode,
+  GraphBuildOptions,
   LiquidModule,
+  ModuleStructural,
   ModuleType,
   Range,
   Reference,
@@ -15,22 +33,31 @@ import {
   Void,
 } from '../types';
 import { assertNever, exists, isString, unique } from '../utils';
-import { getAssetModule, getGraphQLModuleByUri, getPartialModuleByUri } from './module';
+import {
+  getAssetModuleByUri,
+  getGraphQLModuleByUri,
+  getLayoutModuleByUri,
+  getPartialModuleByUri,
+  isSupportedAsset,
+} from './module';
 
-/** A resolved outgoing reference: the target graph node + its call-site range + kind. */
-interface ResolvedReference {
+/** A resolved outgoing reference: the target graph node + its call-site range + kind (+ named-arg names). */
+export interface ResolvedReference {
   target: AppModule;
   sourceRange: Range;
   kind: ReferenceKind;
+  /** Names of the named arguments at the call site, in source order; omitted when none. */
+  args?: string[];
 }
 
-/** The dependency surface the reference resolver needs: just a filesystem (for DocumentsLocator). */
-type ResolverDependencies = Pick<AugmentedDependencies, 'fs'>;
+/** The dependency surface the reference resolver needs: what `DocumentsLocator` takes. */
+type ResolverDependencies = Pick<AugmentedDependencies, 'fs' | 'app'>;
 
 export async function traverseModule(
   module: AppModule,
   appGraph: AppGraph,
   deps: AugmentedDependencies,
+  options: GraphBuildOptions = {},
 ): Promise<Void> {
   // If the module is already traversed, skip it
   if (appGraph.modules[module.uri]) {
@@ -51,7 +78,7 @@ export async function traverseModule(
 
   switch (module.type) {
     case ModuleType.Liquid: {
-      return traverseLiquidModule(module, appGraph, deps);
+      return traverseLiquidModule(module, appGraph, deps, options);
     }
 
     case ModuleType.Asset: {
@@ -59,7 +86,21 @@ export async function traverseModule(
     }
 
     case ModuleType.GraphQL: {
-      return; // Leaf node — GraphQL documents have no platformOS dependencies
+      // Leaf node — GraphQL documents have no platformOS dependencies. We do read the
+      // file once to record the model tables it targets (a neutral platform fact),
+      // from the parse the source code already carries: when the graph reads through
+      // an `App` that is the SAME parse the lint used, not a second one.
+      const sourceCode = await deps.getSourceCode(module.uri);
+      module.tables = isGraphqlDocument(sourceCode.ast) ? extractGraphqlTables(sourceCode.ast) : [];
+      return;
+    }
+
+    case ModuleType.Schema: {
+      // Leaf node — a custom model type / schema file. Read the source once to
+      // record its model table name (the YAML `name:`), a neutral platform fact.
+      const sourceCode = await deps.getSourceCode(module.uri);
+      module.table = extractSchemaTable(sourceCode.source);
+      return;
     }
 
     default: {
@@ -72,19 +113,29 @@ async function traverseLiquidModule(
   module: LiquidModule,
   appGraph: AppGraph,
   deps: AugmentedDependencies,
+  options: GraphBuildOptions,
 ) {
   const sourceCode = await deps.getSourceCode(module.uri);
+
+  // Surface the file's own structural declarations as a by-product of the parse
+  // — only when the caller opted in (see GraphBuildOptions). Absent
+  // otherwise, and when the file could not be parsed.
+  if (options.includeStructural) {
+    module.structural = await extractStructural(sourceCode, module.uri);
+  }
+
   const references = await resolveLiquidReferences(appGraph, sourceCode, deps);
 
   for (const reference of references) {
     bind(module, reference.target, {
       sourceRange: reference.sourceRange,
       kind: reference.kind,
+      args: reference.args,
     });
   }
 
   const modules = unique(references.map((ref) => ref.target));
-  const promises = modules.map((mod) => traverseModule(mod, appGraph, deps));
+  const promises = modules.map((mod) => traverseModule(mod, appGraph, deps, options));
 
   return Promise.all(promises);
 }
@@ -102,33 +153,53 @@ async function traverseLiquidModule(
  * match the rest of the graph on every platform. Unparseable input yields no
  * references rather than throwing.
  */
-async function resolveLiquidReferences(
+export async function resolveLiquidReferences(
   appGraph: AppGraph,
   sourceCode: FileSourceCode,
   deps: ResolverDependencies,
 ): Promise<ResolvedReference[]> {
   if (sourceCode.ast instanceof Error) return []; // can't visit what you can't parse
 
-  // Canonical target resolution (lib paths, module prefixes, extensions) is
-  // owned by check-common's DocumentsLocator — never re-derived here.
-  const documentsLocator = new DocumentsLocator(deps.fs);
+  // Canonical target resolution (lib paths, module prefixes, extensions) is owned by
+  // platformos-common's DocumentsLocator — never re-derived here.
+  //
+  // `deps.app` is the caller's App, so a name is answered by the index it already holds
+  // (O(1), no I/O) and only an index MISS walks candidate directories. Without one the
+  // locator builds a walk-only stand-in and every reference lists a directory per
+  // candidate path — same answers, thousands of extra listings on a project the language
+  // server had already indexed. See `IDependencies.app`.
+  const documentsLocator = new DocumentsLocator(deps.fs, deps.app);
   const rootUri = URI.parse(appGraph.rootUri);
 
   const visitor: Visitor<SourceCodeType.LiquidHtml, ResolvedReference> = {
     // {{ 'app.js' | asset_url }}
-    // {{ 'image.png' | asset_img_url }}
-    // {{ 'icon.svg' | inline_asset_content }}
+    //
+    // `asset_url` is the ONLY filter that names an asset. `asset_img_url` and
+    // `inline_asset_content` stood beside it here and are Shopify's, inherited with the fork:
+    // neither is in `filters.json`, so no platformOS template can call one, and the four sample
+    // projects contain zero uses against 1142 of `asset_url`. A dead name in an edge rule is not
+    // harmless — it is a claim about the platform that the next reader has no reason to doubt.
     LiquidFilter: async (node, ancestors) => {
-      if (['asset_url', 'asset_img_url', 'inline_asset_content'].includes(node.name)) {
+      if (node.name === 'asset_url') {
         const parentNode = ancestors[ancestors.length - 1]!;
         if (parentNode.type !== NodeTypes.LiquidVariable) return;
         if (parentNode.expression.type !== NodeTypes.String) return;
         if (parentNode.filters[0] !== node) return;
         const asset = parentNode.expression.value;
-        const assetModule = getAssetModule(appGraph, asset);
-        if (!assetModule) return;
+        // Skip a non-asset value before paying for the filesystem probe below.
+        // Not the only gate: `getAssetModuleByUri` applies the same predicate, so
+        // neither layer relies on the other remembering.
+        if (!isSupportedAsset(asset)) return;
+        // Resolve through DocumentsLocator (`'asset'`: app/assets, module
+        // public/assets) — not a hard-coded base — so the target matches the
+        // real on-disk location, with the canonical `app/assets/<name>` as the
+        // fallback for an unresolved asset.
+        const uri = await documentsLocator.locateOrDefault(rootUri, 'asset', asset);
+        if (!uri) return;
+        const target = getAssetModuleByUri(appGraph, uri);
+        if (!target) return; // resolution changed the extension — no asset node
         return {
-          target: assetModule,
+          target,
           sourceRange: [parentNode.position.start, parentNode.position.end],
           kind: 'asset',
         };
@@ -155,6 +226,7 @@ async function resolveLiquidReferences(
         target: getPartialModuleByUri(appGraph, uri),
         sourceRange: [tag.position.start, tag.position.end],
         kind: isInclude ? 'include' : 'render',
+        args: argNames(node.args),
       };
     },
 
@@ -169,6 +241,7 @@ async function resolveLiquidReferences(
         target: getPartialModuleByUri(appGraph, uri),
         sourceRange: [tag.position.start, tag.position.end],
         kind: 'function',
+        args: argNames(node.args),
       };
     },
 
@@ -187,6 +260,7 @@ async function resolveLiquidReferences(
         target: getPartialModuleByUri(appGraph, uri),
         sourceRange: [tag.position.start, tag.position.end],
         kind: 'background',
+        args: argNames(node.args),
       };
     },
 
@@ -202,6 +276,31 @@ async function resolveLiquidReferences(
         target: getGraphQLModuleByUri(appGraph, uri),
         sourceRange: [tag.position.start, tag.position.end],
         kind: 'graphql',
+        args: argNames(node.args),
+      };
+    },
+
+    // Frontmatter `layout: name` → page/email → its wrapper layout.
+    // Resolved through DocumentsLocator (`'layout'`: app/views/layouts, module
+    // prefixes, `.html.liquid`/`.liquid`). Only an EXPLICIT, static, non-empty
+    // string layout produces an edge:
+    //  - `layout: ''`        → explicitly no layout (no edge)
+    //  - layout omitted      → no edge (we never synthesize the implicit default)
+    //  - dynamic `{{ ... }}` → no edge (not statically resolvable)
+    //  - non-string value    → no edge
+    // The source range is the whole frontmatter block (tag-level granularity,
+    // like the other edges).
+    YAMLFrontmatter: async (node) => {
+      const data = loadFrontmatter(node.body);
+      if (!data) return; // malformed/empty frontmatter — nothing to resolve
+      const layout = data.layout;
+      if (typeof layout !== 'string' || layout === '' || containsLiquid(layout)) return;
+      const uri = await documentsLocator.locateOrDefault(rootUri, 'layout', layout);
+      if (!uri) return;
+      return {
+        target: getLayoutModuleByUri(appGraph, uri),
+        sourceRange: [node.position.start, node.position.end],
+        kind: 'layout',
       };
     },
   };
@@ -210,26 +309,19 @@ async function resolveLiquidReferences(
 }
 
 /**
- * Extract one Liquid file's outgoing dependency references, resolved against the
- * project at `rootUri`, WITHOUT building the whole app graph.
+ * Extract one Liquid file's outgoing dependency references, resolved against the project at
+ * `rootUri`, WITHOUT building the whole app graph.
  *
- * This is the per-file primitive for consumers that hold a single (possibly
- * in-flight, not-yet-on-disk) buffer — e.g. a `validate_code`-style tool that
- * parses the buffer with {@link toSourceCode} and wants the file's resolved
- * `render`/`include`/`function`/`background`/`graphql`/asset edges with their
- * canonical target URIs and {@link ReferenceKind}. Resolution uses the same
- * `DocumentsLocator`-backed logic as the full graph build, so a target's URI is
- * identical to the key it would have as a graph node.
+ * The per-file primitive for consumers holding a single (possibly in-flight, not-yet-on-disk)
+ * buffer. Resolution uses the same `DocumentsLocator`-backed logic as the full graph build, so
+ * a target's URI is identical to the key it would have as a graph node.
  *
  * Notes for consumers:
- * - Targets are returned whether or not they exist on disk (resolution is
- *   path-based). To distinguish missing targets, `stat` `target.uri` via the
- *   same `fs`; unresolved/missing partials are also surfaced by the linter's
- *   `MissingPartial` check, so prefer that for diagnostics.
+ * - Targets are returned whether or not they exist on disk (resolution is path-based). To
+ *   distinguish missing targets, `stat` `target.uri` via the same `fs`.
  * - Only statically resolvable references are returned; dynamic targets
  *   (`{% render some_var %}`) and inline forms are skipped.
- * - `sourceCode` is parsed by the caller (from the buffer, not disk); only `fs`
- *   is touched here, for target resolution.
+ * - `sourceCode` is parsed by the caller; nothing but target resolution happens here.
  */
 export async function extractFileReferences(
   rootUri: UriString,
@@ -245,8 +337,9 @@ export async function extractFileReferences(
   return references.map((reference) => ({
     source: { uri: sourceUri, range: reference.sourceRange },
     target: { uri: reference.target.uri },
-    type: 'direct',
+    type: 'direct' as const,
     kind: reference.kind,
+    ...argsField(reference.args),
   }));
 }
 
@@ -262,6 +355,151 @@ function isStringLiteral<T extends { type: NodeTypes }>(
   return !isString(node) && node.type === NodeTypes.String;
 }
 
+/**
+ * Parse a YAML block (frontmatter body or a schema file) into an object, or
+ * `undefined` for unparseable / non-object YAML. The single `js-yaml` entry
+ * point shared by the layout-edge resolver, schema-table extraction, and
+ * self-structural extraction — so there is one frontmatter/YAML parse path.
+ */
+function loadFrontmatter(body: string): Record<string, unknown> | undefined {
+  let data: unknown;
+  try {
+    // A duplicated key must not cost this file its edges — see
+    // PLATFORM_YAML_LOAD_OPTIONS. js-yaml's default throws, and the `catch` below
+    // then reports the file as having no frontmatter and no schema at all, which is
+    // how one repeated key silently removes a layout or partial from the graph.
+    data = yaml.load(body, PLATFORM_YAML_LOAD_OPTIONS);
+  } catch {
+    return undefined;
+  }
+  return typeof data === 'object' && data !== null ? (data as Record<string, unknown>) : undefined;
+}
+
+/**
+ * Extract a Liquid file's own structural declarations from an already-parsed source — the
+ * per-file primitive, sibling to {@link extractFileReferences}. Reuses the shared `js-yaml`
+ * frontmatter parse, platformos-common's slug helpers, and check-common's liquid-doc and
+ * translation detection — never a second parser.
+ *
+ * Usage facts come from one walk of the parsed AST and are always present (sorted,
+ * de-duplicated); `doc_params` is in source order. Routing facts come from frontmatter: `slug`
+ * is the frontmatter override else the path-derived slug, for page files only, and
+ * `layout`/`method` when declared.
+ *
+ * Returns `undefined` for a non-Liquid source or one that could not be parsed.
+ */
+export async function extractStructural(
+  sourceCode: FileSourceCode,
+  uri: UriString,
+): Promise<ModuleStructural | undefined> {
+  // Only a parsed Liquid AST has the structure this analyzes; a `.graphql`/`.yml`
+  // buffer (or an unparseable one) yields no structural facts.
+  if (sourceCode.type !== SourceCodeType.LiquidHtml || sourceCode.ast instanceof Error) {
+    return undefined;
+  }
+
+  const renders = new Set<string>();
+  const graphqlQueries = new Set<string>();
+  const filters = new Set<string>();
+  const tags = new Set<string>();
+  const translationKeys = new Set<string>();
+  // `{% doc %}` @param names, in source (signature) order — not sorted/de-duped.
+  const docParams: string[] = [];
+
+  // A single walk of the already-parsed AST collects every usage fact — no
+  // second traversal (the doc `@param` names are read from the parser-produced
+  // `LiquidDocParamNode`s in this same pass, as `extractDocDefinition` would).
+  await visit<SourceCodeType.LiquidHtml, void>(sourceCode.ast, {
+    RenderMarkup: async (node) => {
+      if (isStringLiteral(node.partial)) renders.add(node.partial.value);
+    },
+    GraphQLMarkup: async (node) => {
+      if (isStringLiteral(node.graphql)) graphqlQueries.add(node.graphql.value);
+    },
+    LiquidFilter: async (node) => {
+      filters.add(node.name);
+    },
+    LiquidTag: async (node) => {
+      if (typeof node.name === 'string') tags.add(node.name);
+    },
+    // A translation-key usage is a string literal piped through `t`/`translate`,
+    // e.g. `{{ 'greeting.hello' | t }}` — detected via check-common's shared
+    // `isTranslationKeyUsage` so it cannot drift from the translation check.
+    LiquidVariable: async (node) => {
+      if (isTranslationKeyUsage(node)) translationKeys.add(node.expression.value);
+    },
+    LiquidDocParamNode: async (node) => {
+      docParams.push(node.paramName.value);
+    },
+  });
+
+  const frontmatter = loadFrontmatterOf(sourceCode);
+  const layout = typeof frontmatter?.layout === 'string' ? frontmatter.layout : undefined;
+  const method = typeof frontmatter?.method === 'string' ? frontmatter.method : undefined;
+  const slug = effectiveSlug(uri, frontmatter);
+
+  const sorted = (set: Set<string>) => [...set].sort((a, b) => a.localeCompare(b));
+
+  return {
+    renders_used: sorted(renders),
+    graphql_queries_used: sorted(graphqlQueries),
+    filters_used: sorted(filters),
+    tags_used: sorted(tags),
+    translation_keys: sorted(translationKeys),
+    doc_params: docParams,
+    ...(slug !== undefined ? { slug } : {}),
+    ...(layout !== undefined ? { layout } : {}),
+    ...(method !== undefined ? { method } : {}),
+  };
+}
+
+/** The parsed frontmatter object of a Liquid file, if it has parseable frontmatter. */
+function loadFrontmatterOf(sourceCode: FileSourceCode): Record<string, unknown> | undefined {
+  if (sourceCode.type !== SourceCodeType.LiquidHtml) return undefined;
+  const ast = sourceCode.ast;
+  if (ast instanceof Error || ast.type !== NodeTypes.Document) return undefined;
+  const node = ast.children.find((child) => child.type === NodeTypes.YAMLFrontmatter);
+  return node?.type === NodeTypes.YAMLFrontmatter ? loadFrontmatter(node.body) : undefined;
+}
+
+/**
+ * The effective URL slug for `uri`, delegating to `effectivePageSlug` — the
+ * single slug-derivation shared with `RouteTable`, so the graph's routing fact
+ * can never drift from the platform's actual routing (override-wins, coerced to
+ * a string; else path-derived using the effective format). Returns `undefined`
+ * for a non-page file unless it declares an explicit `slug` override.
+ */
+function effectiveSlug(
+  uri: UriString,
+  frontmatter: Record<string, unknown> | undefined,
+): string | undefined {
+  const relativePath = extractRelativePagePath(uri);
+  if (relativePath !== null) return effectivePageSlug(relativePath, frontmatter);
+  // Non-page file: only an explicit `slug` override is meaningful.
+  const slug = frontmatter?.slug;
+  return slug !== undefined && slug !== null ? String(slug) : undefined;
+}
+
+/**
+ * The names of a call site's named arguments, in source order, or `undefined`
+ * when there are none (so an argument-less edge carries no `args` field). Values
+ * are intentionally not captured — names are what cross-checking against a
+ * partial's `@param` signature needs. Every `LiquidNamedArgument` has a string
+ * `name` by construction, so no per-element guard is required.
+ */
+function argNames(args: LiquidNamedArgument[]): string[] | undefined {
+  return args.length > 0 ? args.map((arg) => arg.name) : undefined;
+}
+
+/**
+ * The spreadable `args` field for an edge: present only for a non-empty
+ * argument-name list, absent otherwise. The single place the "omit when none"
+ * rule lives, so {@link bind} and {@link extractFileReferences} cannot diverge.
+ */
+function argsField(args: string[] | undefined): { args?: string[] } {
+  return args && args.length > 0 ? { args } : {};
+}
+
 /**
  * The bind method is the method that links two modules together.
  *
@@ -276,10 +514,12 @@ export function bind(
     sourceRange,
     type = 'direct', // the type of dependency, can be 'direct' or 'indirect'
     kind, // the semantic Liquid construct that created the edge
+    args, // names of the named arguments at the call site (omitted when none)
   }: {
     sourceRange?: Range; // a range in the source module that references the child
     type?: Reference['type']; // the type of dependency
     kind?: ReferenceKind; // render | include | function | background | graphql | asset | layout
+    args?: string[]; // named-argument names at the call site
   } = {},
 ): void {
   const dependency: Reference = {
@@ -287,6 +527,7 @@ export function bind(
     target: { uri: target.uri },
     type: type,
     kind: kind,
+    ...argsField(args),
   };
 
   source.dependencies.push(dependency);