@platformos/platformos-graph 0.0.19 → 0.1.0

package/src/cli.spec.ts

@@ -0,0 +1,271 @@
+import nodePath from 'node:path';
+import { path } from '@platformos/platformos-check-common';
+import { AbstractFileSystem, FileType, uriFromPath } from '@platformos/platformos-common';
+import { describe, expect, it } from 'vitest';
+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(uriFromPath(skeletonPath));
+
+    // Whole node set, sorted by URI so the assertion is order-independent.
+    // (`app/assets/*` sorts ahead of `app/views/*`.)
+    expect([...graph.nodes].sort((a, b) => a.uri.localeCompare(b.uri))).toEqual([
+      {
+        uri: p('app/assets/app.css'),
+        type: ModuleType.Asset,
+        kind: 'unused',
+        exists: true,
+      },
+      {
+        uri: p('app/assets/app.js'),
+        type: ModuleType.Asset,
+        kind: 'unused',
+        exists: true,
+      },
+      {
+        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,
+      },
+    ]);
+
+    // 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/assets/app.css'),
+        type: 'direct',
+        kind: 'asset',
+      },
+      {
+        source: p('app/views/layouts/application.liquid'),
+        target: p('app/assets/app.js'),
+        type: 'direct',
+        kind: 'asset',
+      },
+      {
+        source: p('app/views/layouts/application.liquid'),
+        target: p('app/views/partials/header.liquid'),
+        type: 'direct',
+        kind: 'render',
+      },
+      {
+        source: p('app/views/pages/index.liquid'),
+        target: p('app/views/layouts/application.liquid'),
+        type: 'direct',
+        kind: 'layout',
+      },
+      {
+        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, 'app', '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, 'app', 'assets'))).toEqual({
+      type: FileType.Directory,
+      size: expect.any(Number),
+    });
+    expect(await nodeFileSystem.stat(path.join(skeleton, 'app', '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, 'app', 'assets'));
+    expect([...entries].sort((a, b) => a[0].localeCompare(b[0]))).toEqual([
+      [path.join(skeleton, 'app', 'assets', 'app.css'), FileType.File],
+      [path.join(skeleton, 'app', '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 = uriFromPath(missing);
+    const rootUri = uriFromPath(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 = uriFromPath(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/, marketplace_builder/, 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,167 @@
+import nodePath from 'node:path';
+import fs from 'node:fs/promises';
+import {
+  makeFileExists,
+  path,
+  PROJECT_ROOT_MARKERS,
+  resolveProjectRoot,
+} from '@platformos/platformos-check-common';
+import {
+  AbstractFileSystem,
+  FileStat,
+  FileTuple,
+  FileType,
+  uriFromPath,
+} from '@platformos/platformos-common';
+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.childUri(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/` — or its
+ * legacy `marketplace_builder/` sibling — `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 resolveGraphRoot(root: string, fs: AbstractFileSystem): Promise<string> {
+  // Only the cwd-relative step stays here: `process.cwd()` is node-specific, and the resolution
+  // itself lives in platformos-check-common so the linter shares it rather than owning a copy.
+  const absolute = nodePath.isAbsolute(root) ? root : nodePath.resolve(process.cwd(), root);
+
+  const { given, root: rootUri } = await resolveProjectRoot(absolute, makeFileExists(fs));
+  if (!rootUri) {
+    // The marker list is derived rather than restated, so it cannot drift from what findRoot
+    // actually looks for. The wording is unchanged from when it was hand-written — this is a
+    // refactor, and the existing message assertion is what proves it stayed one.
+    const markers = PROJECT_ROOT_MARKERS.join(', ').replace(/, ([^,]*)$/, ', or $1');
+    throw new Error(
+      `Not a platformOS project: ${given}\n` +
+        `No ${markers} 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 uriFromPath(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 resolveGraphRoot(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 resolveGraphRoot(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

@@ -7,6 +7,10 @@ export function augmentDependencies(rootUri: string, ideps: IDependencies): Augm
   return {
     fs: ideps.fs,
 
+    // Passed through as given. There is nothing to default: an absent app means the
+    // caller has none, and `DocumentsLocator` already owns what to do then.
+    app: ideps.app,
+
     // parse at most once
     getSourceCode: memoize(
       ideps.getSourceCode ??
@@ -16,7 +20,5 @@ export function augmentDependencies(rootUri: string, ideps: IDependencies): Augm
         },
       identity,
     ),
-
-    getWebComponentDefinitionReference: ideps.getWebComponentDefinitionReference,
   };
 }