@platformos/platformos-graph 0.0.20 → 0.2.0

package/src/graph/module.ts

@@ -1,4 +1,5 @@
-import { isLayout, isPage, isPartial, path, UriString } from '@platformos/platformos-check-common';
+import { path, UriString } from '@platformos/platformos-check-common';
+import { getFileType, nameToPaths, PlatformOSFileType } from '@platformos/platformos-common';
 import {
   AssetModule,
   AppGraph,
@@ -7,6 +8,7 @@ import {
   LiquidModule,
   LiquidModuleKind,
   ModuleType,
+  SchemaModule,
   SUPPORTED_ASSET_IMAGE_EXTENSIONS,
 } from '../types';
 import { extname } from '../utils';
@@ -33,57 +35,103 @@ export function getModule(appGraph: AppGraph, uri: UriString): AppModule | undef
     return cache.get(uri)!;
   }
 
-  const relativePath = path.relative(uri, appGraph.rootUri);
-
-  switch (true) {
-    case isLayout(uri):
+  // One anchored classification, not four unanchored ones: a file's type is its
+  // position relative to the project root, and the graph has that root.
+  switch (getFileType(uri, appGraph.rootUri)) {
+    case PlatformOSFileType.Layout:
       return getLayoutModule(appGraph, uri);
 
-    case isPage(uri):
+    case PlatformOSFileType.Page:
       return getPageModule(appGraph, uri);
 
-    case isPartial(uri):
-      return getPartialModule(appGraph, path.basename(uri, '.liquid'));
+    case PlatformOSFileType.Partial:
+      // The URI is already resolved, so it is used as-is. Reducing it to a
+      // `basename` and rebuilding a path from that loses any subdirectory and any
+      // module prefix — `app/views/partials/ui/card.liquid` came back as
+      // `app/views/partials/card.liquid`, a node for a file that need not exist,
+      // and `app/lib/can/x.liquid` was split from the same file resolved as an
+      // edge target (which comes through getPartialModuleByUri).
+      return getPartialModuleByUri(appGraph, uri);
 
-    case relativePath.startsWith('assets') || relativePath.startsWith('modules'):
-      return getAssetModule(appGraph, path.basename(uri));
+    case PlatformOSFileType.Asset:
+      return getAssetModuleByUri(appGraph, uri);
   }
 }
 
-export function getAssetModule(appGraph: AppGraph, asset: string): AssetModule | undefined {
-  const extension = extname(asset);
-
-  const SUPPORTED_ASSET_EXTENSIONS = [
-    ...SUPPORTED_ASSET_IMAGE_EXTENSIONS,
-    'js',
-    'css',
-    'svg',
-    'pdf',
-    'woff',
-    'woff2',
-    'ttf',
-    'eot',
-  ];
-
-  if (!SUPPORTED_ASSET_EXTENSIONS.includes(extension)) {
-    return undefined;
-  }
+/**
+ * Create (or fetch the cached) asset module for an already-resolved URI.
+ *
+ * Preferred over {@link getAssetModule} whenever the file is known, for the same
+ * reason as {@link getPartialModuleByUri}: it does not reconstruct a path from a
+ * name, so a nested or module asset keeps the location it actually has.
+ *
+ * Gated on {@link isSupportedAsset} HERE rather than at each call site, so a new
+ * caller cannot forget the gate and mint an Asset node for a value that is not an
+ * asset file.
+ */
+export function getAssetModuleByUri(appGraph: AppGraph, uri: string): AssetModule | undefined {
+  if (!isSupportedAsset(uri)) return undefined;
 
   return module(appGraph, {
     type: ModuleType.Asset,
     kind: 'unused',
+    // Normalize to forward slashes — see getPartialModuleByUri.
+    uri: path.normalize(uri),
     dependencies: [],
     references: [],
-    uri: path.join(appGraph.rootUri, 'assets', asset),
   });
 }
 
-export function getPartialModule(appGraph: AppGraph, partial: string): LiquidModule {
-  const uri = path.join(appGraph.rootUri, 'app/views/partials', `${partial}.liquid`);
+/** File extensions the graph treats as assets (the `asset_url` edge gate). */
+const SUPPORTED_ASSET_EXTENSIONS = [
+  ...SUPPORTED_ASSET_IMAGE_EXTENSIONS,
+  'js',
+  'css',
+  'svg',
+  'pdf',
+  'woff',
+  'woff2',
+  'ttf',
+  'eot',
+];
+
+/**
+ * Whether `nameOrUri` refers to a supported asset file (by extension).
+ *
+ * The single gate for admitting an asset, whether the subject is a reference (the
+ * string inside `{{ 'app.js' | asset_url }}`) or a resolved URI. It preserves the
+ * graph's historical behavior of ignoring an `asset_url`-family filter applied to
+ * a value that is not an asset file. Exported so the traversal can skip the
+ * filesystem probe for a non-asset value BEFORE resolving it; the module
+ * factories gate on it again, so neither layer depends on the other remembering.
+ */
+export function isSupportedAsset(nameOrUri: string): boolean {
+  return SUPPORTED_ASSET_EXTENSIONS.includes(extname(nameOrUri));
+}
+
+/**
+ * Create (or fetch the cached) asset module for an asset REFERENCE — the string
+ * inside `{{ 'app.js' | asset_url }}`, which may carry a `modules/<name>/` prefix.
+ *
+ * Assets live under the same roots as every other file type: `app/assets/` or
+ * `modules/<name>/{public,private}/assets/`. Those come from platformos-common, so the
+ * graph resolves a reference to the same place the linter and the platform do.
+ *
+ * The FIRST candidate is used as the canonical location: this is sync and has no
+ * filesystem, so it cannot tell which candidate exists. Prefer
+ * {@link getAssetModuleByUri} — the traversal resolves through `DocumentsLocator`,
+ * which can.
+ */
+export function getAssetModule(appGraph: AppGraph, asset: string): AssetModule | undefined {
+  if (!isSupportedAsset(asset)) return undefined;
+
+  const [canonical] = nameToPaths(PlatformOSFileType.Asset, asset);
+  if (!canonical) return undefined;
+
   return module(appGraph, {
-    type: ModuleType.Liquid,
-    kind: LiquidModuleKind.Partial,
-    uri: uri,
+    type: ModuleType.Asset,
+    kind: 'unused',
+    uri: path.join(appGraph.rootUri, canonical),
     dependencies: [],
     references: [],
   });
@@ -91,21 +139,24 @@ 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.
+ * full URI — used for `{% render %}` / `{% include %}` / `{% function %}` /
+ * `{% background %}` targets whose URI is resolved canonically by
+ * `DocumentsLocator` (which handles lib paths, module prefixes, and extensions).
+ * It keys the node by that URI verbatim (normalized), never reconstructing a path
+ * from a name: partials have two search roots (`views/partials`, `lib`) and two
+ * extensions, so a name-derived path is a guess, and guessing split a `lib/`
+ * partial into two nodes. 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.
+    // (getAssetModule builds its URI 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: [],
@@ -125,6 +176,24 @@ export function getGraphQLModuleByUri(appGraph: AppGraph, uri: string): GraphQLM
     uri: path.normalize(uri),
     dependencies: [],
     references: [],
+    // Always present (empty = no table declared); populated during traversal.
+    tables: [],
+  });
+}
+
+/**
+ * Create (or fetch the cached) Schema module for an already-resolved
+ * `custom_model_type`/schema URI — discovered during a full `buildAppGraph`.
+ * A leaf node; its `table` (the model `name:`) is populated during traversal.
+ */
+export function getSchemaModule(appGraph: AppGraph, uri: string): SchemaModule {
+  return module(appGraph, {
+    type: ModuleType.Schema,
+    kind: 'schema',
+    // Normalize to forward slashes — see getPartialModuleByUri.
+    uri: path.normalize(uri),
+    dependencies: [],
+    references: [],
   });
 }
 
@@ -136,7 +205,30 @@ export function getLayoutModule(
   return module(appGraph, {
     type: ModuleType.Liquid,
     kind: LiquidModuleKind.Layout,
-    uri: layoutUri,
+    // Normalize so a layout discovered as an entry point keys identically to the
+    // same file resolved as a frontmatter `layout:` edge target (which comes
+    // through getLayoutModuleByUri, also normalized) — one node, never a split
+    // identity. See getPartialModuleByUri for why DocumentsLocator/fs URIs must
+    // be normalized.
+    uri: path.normalize(layoutUri),
+    dependencies: [],
+    references: [],
+  });
+}
+
+/**
+ * Create (or fetch the cached) Layout module for an already-resolved layout URI
+ * — used for the frontmatter `layout:` association edge, whose target is
+ * resolved by `DocumentsLocator` (`'layout'` type: `app/views/layouts`, module
+ * prefixes, `.html.liquid`/`.liquid`). Distinct from {@link getLayoutModule} only
+ * in that the latter accepts the `string | false | undefined` a frontmatter read
+ * yields; both normalize, so both key the same node.
+ */
+export function getLayoutModuleByUri(appGraph: AppGraph, uri: string): LiquidModule {
+  return module(appGraph, {
+    type: ModuleType.Liquid,
+    kind: LiquidModuleKind.Layout,
+    uri: path.normalize(uri),
     dependencies: [],
     references: [],
   });
@@ -146,7 +238,9 @@ export function getPageModule(appGraph: AppGraph, pageUri: string): LiquidModule
   return module(appGraph, {
     type: ModuleType.Liquid,
     kind: LiquidModuleKind.Page,
-    uri: pageUri,
+    // Normalize for the same node-identity reason as getLayoutModule / the other
+    // factories (see getPartialModuleByUri).
+    uri: path.normalize(pageUri),
     dependencies: [],
     references: [],
   });

package/src/graph/query.spec.ts

@@ -0,0 +1,260 @@
+import { path as pathUtils } from '@platformos/platformos-check-common';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { buildAppGraph } from '../index';
+import { AppGraph } from '../types';
+import {
+  dependenciesOf,
+  dependentsOf,
+  exists,
+  isEntryPoint,
+  isOrphan,
+  missingDependencies,
+  missingTargets,
+  nearestModules,
+  orphans,
+  reachableFrom,
+} from './query';
+import {
+  getGraphQLModuleByUri,
+  getLayoutModule,
+  getPageModule,
+  getPartialModuleByUri,
+  getSchemaModule,
+} from './module';
+import { bind } from './traverse';
+import { getDependencies, skeleton } from './test-helpers';
+
+const targets = (refs: { target: { uri: string } }[]) =>
+  refs.map((r) => r.target.uri).sort((a, b) => a.localeCompare(b));
+const sources = (refs: { source: { uri: string } }[]) =>
+  refs.map((r) => r.source.uri).sort((a, b) => a.localeCompare(b));
+
+describe('Graph queries: over the built skeleton app graph', () => {
+  const p = (part: string) => pathUtils.join(skeleton, ...part.split('/'));
+  let graph: AppGraph;
+
+  beforeAll(async () => {
+    graph = await buildAppGraph(skeleton, getDependencies());
+  }, 15000);
+
+  it('dependenciesOf returns a file’s outgoing targets', () => {
+    expect(targets(dependenciesOf(graph, p('app/views/pages/index.liquid')))).toEqual([
+      p('app/views/layouts/application.liquid'),
+      p('app/views/partials/parent.liquid'),
+    ]);
+  });
+
+  it('dependency edges are call sites carrying kind + named-argument names', () => {
+    // index.liquid: `layout: application` (no args) + `{% render "parent", children: "hello" %}`.
+    const edges = dependenciesOf(graph, p('app/views/pages/index.liquid'))
+      .map((ref) => ({ kind: ref.kind, target: ref.target.uri, args: ref.args }))
+      .sort((a, b) => a.target.localeCompare(b.target));
+
+    expect(edges).toEqual([
+      { kind: 'layout', target: p('app/views/layouts/application.liquid'), args: undefined },
+      { kind: 'render', target: p('app/views/partials/parent.liquid'), args: ['children'] },
+    ]);
+  });
+
+  it('dependentsOf returns every caller of a file', () => {
+    expect(sources(dependentsOf(graph, p('app/views/partials/child.liquid')))).toEqual([
+      p('app/views/partials/header.liquid'),
+      p('app/views/partials/parent.liquid'),
+    ]);
+    expect(sources(dependentsOf(graph, p('app/views/layouts/application.liquid')))).toEqual([
+      p('app/views/pages/index.liquid'),
+    ]);
+  });
+
+  it('dependenciesOf / dependentsOf return [] for a URI absent from the graph', () => {
+    expect(dependenciesOf(graph, p('app/views/partials/nope.liquid'))).toEqual([]);
+    expect(dependentsOf(graph, p('app/views/partials/nope.liquid'))).toEqual([]);
+  });
+
+  it('reachableFrom returns the transitive outgoing closure', () => {
+    // Sorted by URI — `app/assets/*` sorts ahead of `app/views/*`.
+    expect(reachableFrom(graph, p('app/views/pages/index.liquid'))).toEqual([
+      p('app/assets/app.css'),
+      p('app/assets/app.js'),
+      p('app/views/layouts/application.liquid'),
+      p('app/views/partials/child.liquid'),
+      p('app/views/partials/header.liquid'),
+      p('app/views/partials/parent.liquid'),
+    ]);
+  });
+
+  it('exists reflects on-disk presence', () => {
+    expect(exists(graph, p('app/views/partials/child.liquid'))).toBe(true);
+    expect(exists(graph, p('app/views/partials/nope.liquid'))).toBe(false);
+  });
+
+  it('isEntryPoint distinguishes pages/layouts from partials', () => {
+    expect(isEntryPoint(graph, p('app/views/pages/index.liquid'))).toBe(true);
+    expect(isEntryPoint(graph, p('app/views/layouts/application.liquid'))).toBe(true);
+    expect(isEntryPoint(graph, p('app/views/partials/child.liquid'))).toBe(false);
+  });
+
+  it('a fully-wired skeleton has no orphans and no missing targets', () => {
+    expect(orphans(graph)).toEqual([]);
+    expect(missingTargets(graph)).toEqual([]);
+  });
+});
+
+describe('Graph queries: orphan and missing-target detection (hermetic graph)', () => {
+  const rootUri = 'file:///app';
+  const p = (part: string) => pathUtils.join(rootUri, ...part.split('/'));
+
+  // page (entry) ─render→ used (exists)
+  //                └─render→ missing (exists:false)
+  // orphan (exists, referenced by nothing, not an entry point)
+  // schema (exists, referenced by nothing, not an entry point — but NOT an orphan)
+  let graph: AppGraph;
+  let pageUri: string;
+  let usedUri: string;
+  let orphanUri: string;
+  let missingUri: string;
+  let schemaUri: string;
+
+  beforeAll(() => {
+    graph = { rootUri, entryPoints: [], modules: {} };
+    const page = getPageModule(graph, p('app/views/pages/index.liquid'));
+    const used = getPartialModuleByUri(graph, p('app/views/partials/used.liquid'));
+    const orphan = getPartialModuleByUri(graph, p('app/views/partials/orphan.liquid'));
+    const missing = getPartialModuleByUri(graph, p('app/views/partials/missing.liquid'));
+    const schema = getSchemaModule(graph, p('app/schema/blog_post.yml'));
+
+    page.exists = true;
+    used.exists = true;
+    orphan.exists = true;
+    missing.exists = false;
+    schema.exists = true;
+
+    bind(page, used, { sourceRange: [0, 10], kind: 'render' });
+    bind(page, missing, { sourceRange: [11, 21], kind: 'render' });
+
+    graph.entryPoints = [page];
+    for (const module of [page, used, orphan, missing, schema]) graph.modules[module.uri] = module;
+
+    pageUri = page.uri;
+    usedUri = used.uri;
+    orphanUri = orphan.uri;
+    missingUri = missing.uri;
+    schemaUri = schema.uri;
+  });
+
+  it('flags an unreferenced, non-entry-point file as an orphan', () => {
+    expect(isOrphan(graph, orphanUri)).toBe(true);
+  });
+
+  it('does not flag referenced files, entry points, or missing targets as orphans', () => {
+    expect(isOrphan(graph, usedUri)).toBe(false); // referenced by the page
+    expect(isOrphan(graph, pageUri)).toBe(false); // entry point
+    expect(isOrphan(graph, missingUri)).toBe(false); // missing, not orphan
+  });
+
+  it('never flags a schema node as an orphan (referenced by table name, not edges)', () => {
+    // Without the guard this would be a false positive: schema exists, is not an
+    // entry point, and has zero incoming edges.
+    expect(isOrphan(graph, schemaUri)).toBe(false);
+  });
+
+  it('orphans() lists exactly the orphan modules (excludes the schema)', () => {
+    expect(orphans(graph).map((m) => m.uri)).toEqual([orphanUri]);
+  });
+
+  it('missingDependencies returns a file’s edges to non-existent targets', () => {
+    expect(missingDependencies(graph, pageUri)).toEqual([
+      {
+        source: { uri: pageUri, range: [11, 21] },
+        target: { uri: missingUri },
+        type: 'direct',
+        kind: 'render',
+      },
+    ]);
+  });
+
+  it('missingTargets lists every unresolved edge in the graph', () => {
+    expect(missingTargets(graph)).toEqual([
+      {
+        source: { uri: pageUri, range: [11, 21] },
+        target: { uri: missingUri },
+        type: 'direct',
+        kind: 'render',
+      },
+    ]);
+  });
+});
+
+describe('Graph queries: nearest-name candidates (did-you-mean)', () => {
+  const rootUri = 'file:///app';
+  const p = (part: string) => pathUtils.join(rootUri, ...part.split('/'));
+
+  // Partials: header, footer, sidebar (exist). A layout ALSO named "header"
+  // (exists) — same name, different category. A graphql op blog/find (exists).
+  // Typo targets: partial "headr" and graphql "blog/fnd" (both exists:false).
+  let graph: AppGraph;
+  let headerUri: string;
+  let footerUri: string;
+  let sidebarUri: string;
+  let headrUri: string;
+  let graphqlFindUri: string;
+  let graphqlTypoUri: string;
+
+  beforeAll(() => {
+    graph = { rootUri, entryPoints: [], modules: {} };
+    const page = getPageModule(graph, p('app/views/pages/index.liquid'));
+    const header = getPartialModuleByUri(graph, p('app/views/partials/header.liquid'));
+    const footer = getPartialModuleByUri(graph, p('app/views/partials/footer.liquid'));
+    const sidebar = getPartialModuleByUri(graph, p('app/views/partials/sidebar.liquid'));
+    const headerLayout = getLayoutModule(graph, p('app/views/layouts/header.liquid'))!;
+    const find = getGraphQLModuleByUri(graph, p('app/graphql/blog/find.graphql'));
+    const headr = getPartialModuleByUri(graph, p('app/views/partials/headr.liquid'));
+    const graphqlTypo = getGraphQLModuleByUri(graph, p('app/graphql/blog/fnd.graphql'));
+
+    for (const m of [page, header, footer, sidebar, headerLayout, find]) m.exists = true;
+    headr.exists = false;
+    graphqlTypo.exists = false;
+
+    graph.entryPoints = [page];
+    for (const m of [page, header, footer, sidebar, headerLayout, find, headr, graphqlTypo]) {
+      graph.modules[m.uri] = m;
+    }
+
+    headerUri = header.uri;
+    footerUri = footer.uri;
+    sidebarUri = sidebar.uri;
+    headrUri = headr.uri;
+    graphqlFindUri = find.uri;
+    graphqlTypoUri = graphqlTypo.uri;
+  });
+
+  it('ranks the closest same-category name first', () => {
+    expect(nearestModules(graph, headrUri, { limit: 1 }).map((m) => m.uri)).toEqual([headerUri]);
+  });
+
+  it('only considers existing modules of the same category (excludes self, layouts, graphql, missing)', () => {
+    // The layout "header" shares the name but is a different kind; the graphql
+    // op, the page, the typo itself, and missing modules are all out.
+    const uris = nearestModules(graph, headrUri, { limit: 10 })
+      .map((m) => m.uri)
+      .sort((a, b) => a.localeCompare(b));
+    expect(uris).toEqual([footerUri, headerUri, sidebarUri]);
+  });
+
+  it('honours maxDistance', () => {
+    // Only "header" is within edit distance 1 of "headr".
+    expect(nearestModules(graph, headrUri, { maxDistance: 1 }).map((m) => m.uri)).toEqual([
+      headerUri,
+    ]);
+  });
+
+  it('suggests graphql operations for a missing graphql target', () => {
+    expect(nearestModules(graph, graphqlTypoUri, { limit: 1 }).map((m) => m.uri)).toEqual([
+      graphqlFindUri,
+    ]);
+  });
+
+  it('returns [] for a URI absent from the graph', () => {
+    expect(nearestModules(graph, p('app/views/partials/unknown.liquid'))).toEqual([]);
+  });
+});

package/src/graph/query.ts

@@ -0,0 +1,154 @@
+import { levenshtein, path, UriString } from '@platformos/platformos-check-common';
+import { AppGraph, AppModule, ModuleType, Reference } from '../types';
+
+/**
+ * Project-structure queries over a BUILT {@link AppGraph}.
+ *
+ * Every function here is PURE and synchronous: it only reads the in-memory
+ * graph produced by `buildAppGraph`. All I/O (disk traversal, parsing,
+ * resolution) stays in `buildAppGraph`; this layer never touches the filesystem.
+ *
+ * These resurrect the old in-supervisor `ProjectFactGraph` / `ProjectMap`
+ * capabilities as the graph package's own API, so consumers (the MCP supervisor,
+ * the LSP) read project facts without re-deriving any graph logic.
+ *
+ * Note on graph scope: `buildAppGraph` only materializes modules reachable from
+ * its entry points. Whole-project queries like {@link orphans} are therefore
+ * only as complete as the graph they are given — to detect unreferenced files,
+ * build the graph with every file as an entry point.
+ */
+
+/** The outgoing dependency edges of `uri` (what it renders/includes/runs/queries/wraps). */
+export function dependenciesOf(graph: AppGraph, uri: UriString): Reference[] {
+  return graph.modules[uri]?.dependencies ?? [];
+}
+
+/** The incoming reference edges to `uri` (who renders/includes/runs/queries/wraps it). */
+export function dependentsOf(graph: AppGraph, uri: UriString): Reference[] {
+  return graph.modules[uri]?.references ?? [];
+}
+
+/**
+ * Whether `uri` is a module in the graph that resolves to a file on disk.
+ * Returns `false` for a URI absent from the graph or a known-missing target.
+ */
+export function exists(graph: AppGraph, uri: UriString): boolean {
+  return graph.modules[uri]?.exists ?? false;
+}
+
+/** Whether `uri` is one of the graph's entry points (a page or layout root). */
+export function isEntryPoint(graph: AppGraph, uri: UriString): boolean {
+  return graph.entryPoints.some((entry) => entry.uri === uri);
+}
+
+/**
+ * Whether `uri` is an orphan: an existing, non-entry-point module that nothing
+ * references. Entry points (pages, layouts) are roots reachable independently of
+ * render edges, so they are never orphans; known-missing targets are "missing"
+ * (see {@link missingDependencies}), not orphans.
+ */
+export function isOrphan(graph: AppGraph, uri: UriString): boolean {
+  const module = graph.modules[uri];
+  if (!module || module.exists === false) return false;
+  if (isEntryPoint(graph, uri)) return false;
+  // Schema nodes are referenced by model table name (from graphql/commands), not
+  // by file edges, so they are NEVER edge-referenced — "no incoming references"
+  // is meaningless for them. Excluding them keeps orphan = render dead-code.
+  if (module.type === ModuleType.Schema) return false;
+  return module.references.length === 0;
+}
+
+/** Every orphan module in the graph (see {@link isOrphan}), sorted by URI. */
+export function orphans(graph: AppGraph): AppModule[] {
+  return Object.values(graph.modules)
+    .filter((module) => isOrphan(graph, module.uri))
+    .sort((a, b) => a.uri.localeCompare(b.uri));
+}
+
+/**
+ * Every module URI transitively reachable from `uri` by following outgoing
+ * dependency edges, sorted. Excludes `uri` itself unless a cycle leads back to
+ * it. Modules absent from the graph contribute nothing.
+ */
+export function reachableFrom(graph: AppGraph, uri: UriString): UriString[] {
+  const seen = new Set<UriString>();
+  const queue: UriString[] = dependenciesOf(graph, uri).map((dep) => dep.target.uri);
+
+  while (queue.length > 0) {
+    const next = queue.shift()!;
+    if (seen.has(next)) continue;
+    seen.add(next);
+    for (const dep of dependenciesOf(graph, next)) queue.push(dep.target.uri);
+  }
+
+  return [...seen].sort((a, b) => a.localeCompare(b));
+}
+
+/** The outgoing edges of `uri` whose target does not exist on disk. */
+export function missingDependencies(graph: AppGraph, uri: UriString): Reference[] {
+  return dependenciesOf(graph, uri).filter((ref) => !exists(graph, ref.target.uri));
+}
+
+/**
+ * Every edge in the graph that points at a non-existent target — the project's
+ * unresolved references. Sorted by (source URI, target URI) for stable output.
+ */
+export function missingTargets(graph: AppGraph): Reference[] {
+  return Object.values(graph.modules)
+    .flatMap((module) => module.dependencies)
+    .filter((ref) => !exists(graph, ref.target.uri))
+    .sort(
+      (a, b) =>
+        a.source.uri.localeCompare(b.source.uri) || a.target.uri.localeCompare(b.target.uri),
+    );
+}
+
+export interface NearestModulesOptions {
+  /** Maximum number of candidates to return, closest first. Default 3. */
+  limit?: number;
+  /** Maximum edit distance to include. Default: no cap (consumer decides relevance). */
+  maxDistance?: number;
+}
+
+/**
+ * The existing modules whose names are closest to `uri` — the "did you mean?"
+ * candidate set for a typo'd or missing reference.
+ *
+ * Candidates are restricted to the SAME category as `uri` (same module `type`,
+ * and for Liquid the same `kind`), so a missing `{% render %}` only suggests
+ * partials, a missing `{% graphql %}` only graphql operations, etc. Ranked by
+ * Levenshtein distance over the project-relative path (reusing check-common's
+ * `levenshtein` + `path.relative` — never re-implemented), closest first, ties
+ * broken by URI. `uri` itself and known-missing modules are excluded.
+ *
+ * Pure over the graph: candidates come only from modules present in it, so build
+ * with every file as an entry point for a complete candidate pool (see header).
+ */
+export function nearestModules(
+  graph: AppGraph,
+  uri: UriString,
+  options: NearestModulesOptions = {},
+): AppModule[] {
+  const { limit = 3, maxDistance = Infinity } = options;
+  const target = graph.modules[uri];
+  if (!target) return [];
+
+  const targetPath = path.relative(uri, graph.rootUri);
+
+  return Object.values(graph.modules)
+    .filter(
+      (module) =>
+        module.uri !== uri &&
+        module.exists !== false &&
+        module.type === target.type &&
+        module.kind === target.kind,
+    )
+    .map((module) => ({
+      module,
+      distance: levenshtein(path.relative(module.uri, graph.rootUri), targetPath),
+    }))
+    .filter((candidate) => candidate.distance <= maxDistance)
+    .sort((a, b) => a.distance - b.distance || a.module.uri.localeCompare(b.module.uri))
+    .slice(0, limit)
+    .map((candidate) => candidate.module);
+}