@platformos/platformos-graph 0.0.20 → 0.1.0

package/src/graph/build.ts

@@ -1,30 +1,75 @@
+import { UriString } from '@platformos/platformos-check-common';
 import {
-  recursiveReadDirectory as findAllFiles,
-  isLayout,
-  isPage,
-  path,
-  UriString,
-} from '@platformos/platformos-check-common';
-import { IDependencies, AppGraph, AppModule } from '../types';
+  getFileType,
+  PlatformOSFileType,
+  SourceCodeType,
+  sourceCodeTypeOf,
+  walkAppSourceFiles,
+} from '@platformos/platformos-common';
+import { IDependencies, AppGraph, AppModule, GraphBuildOptions } from '../types';
 import { augmentDependencies } from './augment';
-import { getModule } from './module';
+import { getModule, getSchemaModule } from './module';
 import { traverseModule } from './traverse';
 
+/**
+ * Build the project dependency graph.
+ *
+ * - `entryPoints` omitted → FULL build: a single directory sweep discovers pages
+ *   + layouts (the render entry points) and standalone custom-model-type/schema
+ *   nodes, and every reachable module is materialized.
+ * - `entryPoints` provided → SCOPED build (e.g. an LSP rebuild for changed
+ *   files): built verbatim from those roots. Schema nodes are NOT auto-discovered
+ *   in this mode — schema discovery is a full-build concern.
+ *
+ * `options.includeStructural` (default off) additionally populates each
+ * `LiquidModule.structural`; see {@link GraphBuildOptions}.
+ */
 export async function buildAppGraph(
   rootUri: UriString,
   ideps: IDependencies,
   entryPoints?: UriString[],
+  options: GraphBuildOptions = {},
 ): Promise<AppGraph> {
   const deps = augmentDependencies(rootUri, ideps);
 
-  entryPoints =
-    entryPoints ??
-    (await findAllFiles(deps.fs, rootUri, ([uri]) => {
-      if (!uri.endsWith('.liquid')) return false;
-      // Layouts are entry points — they wrap all page content.
-      // Pages are also entry points — they are directly requested.
-      return isLayout(uri) || isPage(uri);
-    }));
+  // Table (schema / custom-model-type) files are platform nodes but are NOT
+  // render-reachable — nothing renders them — so they never appear via edge traversal. On
+  // a full build they are discovered as standalone leaf nodes, never entry points, so
+  // reachability/orphan semantics for the render graph are unaffected.
+  let schemaUris: UriString[] = [];
+
+  // An explicit entryPoints scope is built verbatim (e.g. a scoped LSP rebuild); the
+  // default full build (`entryPoints === undefined`) also discovers standalone Table
+  // nodes. Branching on the parameter directly lets the compiler narrow it below.
+  if (entryPoints === undefined) {
+    // ONE sweep yields both populations, partitioned by SourceCodeType below, so the
+    // tree is walked once. `walkAppSourceFiles` is anchored on APP_SOURCE_SUBTREES: the
+    // walk it replaces started at the root and skipped directories by NAME, which both
+    // dropped `app/views/pages/vendor/**` (a live site section — 137 files on one real
+    // project) and admitted `tmp/app/views/partials/x.liquid`.
+    const discovered = await walkAppSourceFiles(deps.fs, rootUri, ([uri]) => {
+      // Root-ANCHORED classification. The unanchored `getFileType(uri)` this used to call
+      // matched a known directory anywhere in the path, so
+      // `seed/post_import/app/migrations/x.liquid` classified as a Migration while being
+      // correctly absent from the lint's app.
+      const fileType = getFileType(uri, rootUri);
+
+      // A GRAPH-domain restriction, not a second answer to "what is a source file":
+      // Liquid is the only source that can reference another file, so a non-Liquid entry
+      // point would have no edges to traverse. Which extensions ARE Liquid still comes
+      // from platformos-common, never spelled here — which is also why the `.yml`/`.yaml`
+      // tests that used to partition this sweep are gone: `.yaml` is not a platformOS
+      // extension at all, so spelling it here promised coverage the platform never had.
+      if (sourceCodeTypeOf(uri) === SourceCodeType.LiquidHtml) {
+        // Layouts wrap all page content; pages are directly requested — both are entry points.
+        return fileType === PlatformOSFileType.Layout || fileType === PlatformOSFileType.Page;
+      }
+      return fileType === PlatformOSFileType.Table;
+    });
+
+    entryPoints = discovered.filter((uri) => sourceCodeTypeOf(uri) === SourceCodeType.LiquidHtml);
+    schemaUris = discovered.filter((uri) => sourceCodeTypeOf(uri) !== SourceCodeType.LiquidHtml);
+  }
 
   const graph: AppGraph = {
     entryPoints: [],
@@ -36,7 +81,13 @@ export async function buildAppGraph(
     .map((uri) => getModule(graph, uri))
     .filter((x): x is AppModule => x !== undefined);
 
-  await Promise.all(graph.entryPoints.map((entry) => traverseModule(entry, graph, deps)));
+  await Promise.all(graph.entryPoints.map((entry) => traverseModule(entry, graph, deps, options)));
+
+  if (schemaUris.length > 0) {
+    await Promise.all(
+      schemaUris.map((uri) => traverseModule(getSchemaModule(graph, uri), graph, deps, options)),
+    );
+  }
 
   return graph;
 }

package/src/graph/edge-sources.spec.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+
+import { path } from '@platformos/platformos-check-common';
+import { FileType, getFileType, PlatformOSFileType } from '@platformos/platformos-common';
+import type { AbstractFileSystem, UriString } from '@platformos/platformos-common';
+import { MockFileSystem, type MockApp } from '@platformos/platformos-check-common/dist/test';
+
+import { enumerateEdgeSources, isEdgeSource } from '../index';
+
+/**
+ * `enumerateEdgeSources` is the SINGLE canonical "what are the
+ * edge-source liquid files under a project root" primitive. The supervisor's
+ * GraphCache consumes it for BOTH the fingerprint domain and the build's entry
+ * points, so its definition must never silently drift from the file-type
+ * classifier (`getFileType` ← `FILE_TYPE_DIRS`).
+ */
+describe('Unit: enumerateEdgeSources (canonical edge-source enumeration)', () => {
+  const rootUri = path.normalize('file:/');
+  const uri = (rel: string) => path.join(rootUri, rel);
+
+  // Edge sources under every canonical location a Page/Layout/Partial can live.
+  const EDGE_SOURCES = [
+    'app/views/pages/home.liquid', // Page (modern app/ root)
+    'app/views/layouts/application.liquid', // Layout
+    'app/views/partials/card.liquid', // Partial (views/partials)
+    'app/lib/helper.liquid', // Partial (lib)
+    'marketplace_builder/views/pages/legacy.liquid', // Page (legacy root)
+    'modules/shop/public/views/partials/widget.liquid', // Partial (top-level module, public)
+    'modules/shop/private/lib/secret.liquid', // Partial (top-level module, PRIVATE access level)
+    'app/modules/blog/private/views/pages/post.liquid', // Page (nested app/modules)
+  ];
+
+  // Files that are NOT edge sources: leaves, non-liquid, and a bundled
+  // non-platformOS sibling that must never be walked.
+  const NON_EDGE_SOURCES = {
+    'app/graphql/get_posts.graphql': 'query { records { results { id } } }',
+    'app/schema/blog_post.yml': 'name: blog_post',
+    'app/assets/logo.css': 'body {}',
+    'react-app/src/components/Widget.liquid': 'noise that is never a source',
+    'README.md': '# project',
+  };
+
+  const makeFs = () => {
+    const files: MockApp = { ...NON_EDGE_SOURCES };
+    for (const rel of EDGE_SOURCES) files[rel] = '<div></div>';
+    return new MockFileSystem(files, rootUri);
+  };
+
+  const sorted = (uris: string[]) => [...uris].sort();
+
+  it('gathers exactly the edge sources across all source roots (nothing else)', async () => {
+    const fs = makeFs();
+    expect(sorted(await enumerateEdgeSources(fs, rootUri))).toEqual(sorted(EDGE_SOURCES.map(uri)));
+  });
+
+  it('the scoped walk equals a whole-tree walk filtered by the classifier (no drift)', async () => {
+    const fs = makeFs();
+    const scoped = sorted(await enumerateEdgeSources(fs, rootUri));
+    const wholeTree = sorted(
+      (await everyFileUnder(fs, rootUri)).filter((u) => isEdgeSource(u, rootUri)),
+    );
+    expect(scoped).toEqual(wholeTree);
+  });
+
+  it('isEdgeSource is exactly the Layout/Page/Partial classification', () => {
+    const EDGE_SOURCE_TYPES = [
+      PlatformOSFileType.Layout,
+      PlatformOSFileType.Page,
+      PlatformOSFileType.Partial,
+    ];
+    for (const rel of EDGE_SOURCES) {
+      const u = uri(rel);
+      expect(isEdgeSource(u, rootUri)).toBe(true);
+      expect(EDGE_SOURCE_TYPES).toContain(getFileType(u, rootUri));
+    }
+    for (const rel of Object.keys(NON_EDGE_SOURCES)) {
+      const u = uri(rel);
+      expect(isEdgeSource(u, rootUri)).toBe(false);
+      expect(EDGE_SOURCE_TYPES).not.toContain(getFileType(u, rootUri));
+    }
+  });
+
+  /**
+   * The reason the classification is anchored on the root. Unanchored, a directory
+   * named like a platformOS one ANYWHERE in the path classified: these three files
+   * are not part of the app, and counting them in the fingerprint domain made the
+   * supervisor's GraphCache rebuild on edits to files the app never reads.
+   */
+  it('does not admit a platformOS-looking path outside the app subtrees', async () => {
+    const outside = {
+      'tmp/app/views/partials/scratch.liquid': '<div></div>',
+      'seed/post_import/app/views/pages/fixture.liquid': '<div></div>',
+      'node_modules/pkg/app/lib/helper.liquid': '<div></div>',
+    };
+    for (const rel of Object.keys(outside)) expect(isEdgeSource(uri(rel), rootUri)).toBe(false);
+
+    // Control: the same three spellings ARE found when they sit at the real root, so
+    // the silence above is the anchoring, not the fixture or the walk.
+    const files: MockApp = { ...outside };
+    for (const rel of EDGE_SOURCES) files[rel] = '<div></div>';
+    const fs = new MockFileSystem(files, rootUri);
+    expect(sorted(await enumerateEdgeSources(fs, rootUri))).toEqual(sorted(EDGE_SOURCES.map(uri)));
+  });
+
+  it('never yields a non-platformOS sibling (a bundled react-app/ is skipped)', async () => {
+    const fs = makeFs();
+    const result = await enumerateEdgeSources(fs, rootUri);
+    expect(result).not.toContain(uri('react-app/src/components/Widget.liquid'));
+  });
+});
+
+/**
+ * Every file under `baseUri`, by brute-force recursion into every directory.
+ */
+async function everyFileUnder(fs: AbstractFileSystem, baseUri: UriString): Promise<UriString[]> {
+  const entries = await fs.readDirectory(baseUri).catch(() => []);
+
+  const nested = await Promise.all(
+    entries.map(async ([uri, type]) =>
+      type === FileType.Directory ? everyFileUnder(fs, uri) : [uri],
+    ),
+  );
+
+  return nested.flat();
+}

package/src/graph/edge-sources.ts

@@ -0,0 +1,49 @@
+import { type UriString } from '@platformos/platformos-check-common';
+import {
+  getFileType,
+  PlatformOSFileType,
+  walkAppSourceFiles,
+  type AbstractFileSystem,
+} from '@platformos/platformos-common';
+
+/**
+ * The canonical definition of an EDGE SOURCE: a liquid file whose own content can declare
+ * outgoing edges (a Page, Layout, or Partial). Only these files' add/remove/modify can change
+ * any file's set of dependents — `.graphql`/`.yml`/asset files are leaves.
+ *
+ * "Which files" derives entirely from the file-type classifier, so this predicate never
+ * re-encodes the classification. It is ANCHORED on `rootUri`, because a file's type IS its
+ * position relative to the project root: unanchored, `tmp/app/lib/x.liquid` is a Partial.
+ */
+export function isEdgeSource(uri: UriString, rootUri: UriString): boolean {
+  switch (getFileType(uri, rootUri)) {
+    case PlatformOSFileType.Layout:
+    case PlatformOSFileType.Page:
+    case PlatformOSFileType.Partial:
+      return true;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Enumerate every edge-source liquid file under a project root — the single canonical primitive
+ * for "which files are the graph's edge sources". Consumers never re-derive the walk or the
+ * {@link isEdgeSource} predicate.
+ *
+ * The walk is `walkAppSourceFiles`, platformos-common's anchored expansion of
+ * `APP_SOURCE_SUBTREES`, so this file names no directory at all and a bundled `react-app/` is
+ * never walked. `edge-sources.spec` pins the scoped result against a whole-tree walk filtered
+ * by {@link isEdgeSource}.
+ *
+ * NOT shared with `buildAppGraph`'s full-build discovery: the two gather DIFFERENT domains —
+ * that one takes render entry points (pages + layouts, partials being edge-reached) plus
+ * standalone schema nodes, this one takes page + layout + partial. They share the walk
+ * primitive and the classifier, which are the parts that must not drift.
+ */
+export async function enumerateEdgeSources(
+  fs: AbstractFileSystem,
+  rootUri: UriString,
+): Promise<UriString[]> {
+  return walkAppSourceFiles(fs, rootUri, ([uri]) => isEdgeSource(uri, rootUri));
+}

package/src/graph/module.spec.ts

@@ -0,0 +1,168 @@
+import { DocumentsLocator, FileType } from '@platformos/platformos-common';
+import { describe, expect, it } from 'vitest';
+import { URI } from 'vscode-uri';
+import { AppGraph, ModuleType } from '../types';
+import {
+  getAssetModule,
+  getLayoutModule,
+  getLayoutModuleByUri,
+  getModule,
+  getPageModule,
+  getPartialModuleByUri,
+} from './module';
+
+/**
+ * Node-identity invariant (code-review F10): a file must resolve to ONE module
+ * regardless of which producer creates it. Entry-point factories
+ * (getLayoutModule/getPageModule) take a URI straight from directory discovery,
+ * while edge-target factories (getLayoutModuleByUri/getPartialModuleByUri) take a
+ * DocumentsLocator-resolved URI; both normalize, so a Windows-style backslash
+ * URI from one and a forward-slash URI from the other key to the SAME cached
+ * node — never a split identity that would drop an incoming edge.
+ */
+describe('module factories: normalized node identity', () => {
+  const newGraph = (): AppGraph => ({ rootUri: 'file:///project', entryPoints: [], modules: {} });
+
+  it('dedupes an entry-point layout with the same layout resolved as an edge target', () => {
+    const graph = newGraph();
+    // As if discovered by directory traversal on Windows (backslashes)…
+    const entry = getLayoutModule(graph, 'file:///project\\app\\views\\layouts\\theme.liquid');
+    // …and as if resolved from a page's frontmatter `layout:` (forward slashes).
+    const edgeTarget = getLayoutModuleByUri(
+      graph,
+      'file:///project/app/views/layouts/theme.liquid',
+    );
+
+    expect(entry).toBe(edgeTarget); // same cached object — one node
+    expect(entry?.uri).toEqual('file:///project/app/views/layouts/theme.liquid');
+  });
+
+  it('dedupes an entry-point page regardless of separator style', () => {
+    const graph = newGraph();
+    const first = getPageModule(graph, 'file:///project\\app\\views\\pages\\index.liquid');
+    const second = getPageModule(graph, 'file:///project/app/views/pages/index.liquid');
+
+    expect(first).toBe(second);
+    expect(first.uri).toEqual('file:///project/app/views/pages/index.liquid');
+  });
+
+  it('dedupes a partial across separator styles too (regression guard for the shared contract)', () => {
+    const graph = newGraph();
+    const a = getPartialModuleByUri(graph, 'file:///project\\app\\views\\partials\\card.liquid');
+    const b = getPartialModuleByUri(graph, 'file:///project/app/views/partials/card.liquid');
+
+    expect(a).toBe(b);
+    expect(a.uri).toEqual('file:///project/app/views/partials/card.liquid');
+  });
+});
+
+/**
+ * `getModule` (the entry-point dispatcher) must key a partial by its OWN
+ * resolved URI — like it does for layouts/pages/assets — NOT by rebuilding the
+ * path from the basename. Rebuilding from the basename forced every partial into
+ * `app/views/partials/<basename>.liquid`, which mis-keyed any `lib/` or nested
+ * partial (e.g. `app/lib/can/payment_request.liquid` → the phantom
+ * `app/views/partials/payment_request.liquid`), splitting it from the same file
+ * resolved as an edge target and losing its edges in the full build.
+ */
+describe('getModule: partial entry point keys by its own URI', () => {
+  const newGraph = (): AppGraph => ({ rootUri: 'file:///project', entryPoints: [], modules: {} });
+
+  it('keys a lib partial at its own URI, not app/views/partials/<basename>', () => {
+    const graph = newGraph();
+    const uri = 'file:///project/app/lib/can/payment_request.liquid';
+    expect(getModule(graph, uri)?.uri).toEqual(uri);
+  });
+
+  it('keys a nested lib partial at its own URI', () => {
+    const graph = newGraph();
+    const uri = 'file:///project/app/lib/queries/v2/projects/find.liquid';
+    expect(getModule(graph, uri)?.uri).toEqual(uri);
+  });
+
+  it('a lib partial entry point and the same file resolved as an edge target are ONE node', () => {
+    const graph = newGraph();
+    const uri = 'file:///project/app/lib/commands/create.liquid';
+    const entry = getModule(graph, uri);
+    const edgeTarget = getPartialModuleByUri(graph, uri);
+    expect(entry).toBe(edgeTarget);
+  });
+
+  it('a flat app/views/partials partial is unaffected', () => {
+    const graph = newGraph();
+    const uri = 'file:///project/app/views/partials/card.liquid';
+    expect(getModule(graph, uri)?.uri).toEqual(uri);
+  });
+});
+
+const ROOT = 'file:///project';
+
+const emptyGraph = (): AppGraph => ({ rootUri: ROOT, entryPoints: [], modules: {} });
+
+/**
+ * Assets follow exactly the same placement rules as every other platformOS file type:
+ * `app/assets/` or `modules/<name>/{public,private}/assets/`. Resolution goes through
+ * platformos-common, so the graph cannot disagree with `DocumentsLocator` about where
+ * `{{ 'app.js' | asset_url }}` points.
+ */
+describe('asset reference resolution', () => {
+  it("resolves 'app.js' to app/assets/app.js", () => {
+    expect(getAssetModule(emptyGraph(), 'app.js')!.uri).toBe(`${ROOT}/app/assets/app.js`);
+  });
+
+  it('keeps a subdirectory instead of collapsing to a basename', () => {
+    expect(getAssetModule(emptyGraph(), 'styles/theme.css')!.uri).toBe(
+      `${ROOT}/app/assets/styles/theme.css`,
+    );
+  });
+
+  it('routes a modules/<name>/ reference into that module, not into app/assets', () => {
+    expect(getAssetModule(emptyGraph(), 'modules/admin/app.css')!.uri).toBe(
+      `${ROOT}/app/modules/admin/public/assets/app.css`,
+    );
+  });
+
+  it('ignores a reference with an extension no asset uses', () => {
+    expect(getAssetModule(emptyGraph(), 'notes.txt')).toBe(undefined);
+  });
+
+  it('agrees with DocumentsLocator for an asset that exists', async () => {
+    const assetUri = `${ROOT}/app/assets/app.js`;
+    const locator = new DocumentsLocator({
+      stat: async (uri: string) => {
+        if (uri !== assetUri) throw new Error(`ENOENT: ${uri}`);
+        return { type: FileType.File, size: 0 };
+      },
+      readFile: async () => '',
+      // Resolution reads the candidate directory's listing, not a stat per spelling.
+      readDirectory: async (uri: string) => {
+        if (uri !== `${ROOT}/app/assets`) throw new Error(`ENOENT: ${uri}`);
+        return [[assetUri, FileType.File]];
+      },
+    });
+
+    expect(getAssetModule(emptyGraph(), 'app.js')!.uri).toBe(
+      await locator.locate(URI.parse(ROOT), 'asset', 'app.js'),
+    );
+  });
+
+  it('classifies an asset URI as an asset module without reconstructing its path', () => {
+    const nested = `${ROOT}/app/assets/styles/theme.css`;
+    const moduleAsset = `${ROOT}/modules/admin/private/assets/app.css`;
+
+    expect(getModule(emptyGraph(), nested)).toMatchObject({
+      type: ModuleType.Asset,
+      uri: nested,
+    });
+    // A module ORIGINAL keeps its own path — resolving by name would have moved it to
+    // the app-overwrite slot.
+    expect(getModule(emptyGraph(), moduleAsset)).toMatchObject({
+      type: ModuleType.Asset,
+      uri: moduleAsset,
+    });
+  });
+
+  it('does not treat a root-level assets/ path as part of the app', () => {
+    expect(getModule(emptyGraph(), `${ROOT}/assets/app.js`)).toBe(undefined);
+  });
+});