@platformos/platformos-graph 0.0.20 → 0.1.0

package/dist/types.d.ts

@@ -1,17 +1,49 @@
 import { JSONSourceCode, LiquidSourceCode, Dependencies as CheckDependencies, UriString, Reference, ReferenceKind, Location, Range, GraphQLSourceCode, YAMLSourceCode } from '@platformos/platformos-check-common';
+import type { App, AppResolver } from '@platformos/platformos-common';
 export interface IDependencies {
     fs: CheckDependencies['fs'];
     /** Optional perf improvement if you somehow have access to pre-computed source code info */
     getSourceCode?: (uri: UriString) => Promise<FileSourceCode>;
+    /**
+     * The {@link App} whose per-type name index answers `{% render 'ui/card' %}`,
+     * `{% function … = 'commands/create' %}`, `{% graphql … = 'user/find' %}` and
+     * `layout: application` — the same object {@link IDependencies.getSourceCode} reads through
+     * when it is `appBackedGetSourceCode`.
+     *
+     * The pairing is the point: a caller that holds an App should hand it over for BOTH, so the
+     * graph reuses the lint's parses AND its index. Without it, `DocumentsLocator` falls back to a
+     * walk-only stand-in and every reference costs a `readDirectory` per candidate directory.
+     *
+     * It cannot change the ANSWER, only what it costs: `App.findOrLocate` resolves index-first and
+     * falls through to the very walk the stand-in performs. Omit it where there is genuinely no
+     * App: a build in a worker thread, a CLI, a fixture.
+     */
+    app?: App | AppResolver;
 }
-export type Dependencies = Required<IDependencies>;
+/**
+ * `IDependencies` with the optional PERFORMANCE seams resolved by
+ * `augmentDependencies` — `getSourceCode` always present, `app` still optional
+ * because "no app here" is a legitimate final state, not an unaugmented one.
+ */
+export type Dependencies = Required<Omit<IDependencies, 'app'>> & Pick<IDependencies, 'app'>;
 export type AugmentedDependencies = Dependencies;
+/** Options controlling what a build/traversal computes beyond the edge graph. */
+export interface GraphBuildOptions {
+    /**
+     * Populate each {@link LiquidModule.structural} (self-structural facts) during
+     * the build, as a by-product of the parse. OFF by default: a consumer that
+     * needs one buffer's structural facts should call `extractStructural` directly
+     * (the per-file primitive), so a full graph build — e.g. the LSP's, which never
+     * reads `structural` — does not compute a fact nothing consumes.
+     */
+    includeStructural?: boolean;
+}
 export interface AppGraph {
     rootUri: UriString;
     entryPoints: AppModule[];
     modules: Record<UriString, AppModule>;
 }
-export type AppModule = LiquidModule | AssetModule | GraphQLModule;
+export type AppModule = LiquidModule | AssetModule | GraphQLModule | SchemaModule;
 export type FileSourceCode = LiquidSourceCode | JSONSourceCode | GraphQLSourceCode | YAMLSourceCode | AssetSourceCode;
 export interface SerializableGraph {
     rootUri: UriString;
@@ -20,8 +52,46 @@ export interface SerializableGraph {
 }
 export type SerializableEdge = Reference;
 export type SerializableNode = Pick<AppModule, 'uri' | 'type' | 'kind' | 'exists'>;
+/**
+ * A Liquid file's own structural declarations — a by-product of the parse the
+ * graph already does, so consumers need not re-parse the file.
+ *
+ * The usage arrays are ALWAYS present (sorted, de-duplicated): an empty array
+ * means "the file uses none", since the whole AST is analyzed — never "not
+ * extracted". The routing facts (`slug`/`layout`/`method`) are optional: an
+ * absent one means "not applicable / not declared" (e.g. a partial has no slug).
+ * `doc_params` lands in a later phase and will appear here when it does.
+ */
+export interface ModuleStructural {
+    /** Partial names rendered via `{% render %}` / `{% include %}` (the literal target names). */
+    renders_used: string[];
+    /** Operation names invoked via `{% graphql %}` (the literal target names). */
+    graphql_queries_used: string[];
+    /** Liquid filter names used anywhere in the file. */
+    filters_used: string[];
+    /** Liquid tag names used anywhere in the file. */
+    tags_used: string[];
+    /** Translation keys referenced via the `t` / `translate` filter. */
+    translation_keys: string[];
+    /** `@param` names declared in the file's `{% doc %}` block. */
+    doc_params: string[];
+    /**
+     * Effective URL slug: the frontmatter `slug` override if declared, else
+     * derived from the page's path. Present for page files only.
+     */
+    slug?: string;
+    /** Declared wrapper layout (frontmatter `layout`), when declared. */
+    layout?: string;
+    /** Declared HTTP method (frontmatter `method`), when declared. */
+    method?: string;
+}
 export interface LiquidModule extends IAppModule<ModuleType.Liquid> {
     kind: LiquidModuleKind;
+    /**
+     * The file's own structural declarations, populated during a full
+     * `buildAppGraph`. Absent when the file declares none of the surfaced facts.
+     */
+    structural?: ModuleStructural;
 }
 export interface AssetModule extends IAppModule<ModuleType.Asset> {
     kind: 'unused';
@@ -33,6 +103,34 @@ export interface AssetModule extends IAppModule<ModuleType.Asset> {
  */
 export interface GraphQLModule extends IAppModule<ModuleType.GraphQL> {
     kind: 'graphql';
+    /**
+     * The platformOS model tables this operation targets (from its `table`
+     * filters / `record_create` inputs) — every distinct table in document order.
+     * Populated during `buildAppGraph` traversal; always present (empty = the
+     * operation declares no table, or was never resolved on disk).
+     */
+    tables: string[];
+}
+/**
+ * A custom model type / schema file (`custom_model_types`/`model_schemas`/
+ * `schema` dirs — `PlatformOSFileType.Table`). A platform primitive,
+ * modeled as a neutral graph node. A leaf node — schema files have no outgoing
+ * platformOS dependencies — and not render-reachable, so it is discovered and
+ * added explicitly during a full `buildAppGraph` (never an entry point).
+ *
+ * NOTE (ADR 004): this is a neutral platform fact. The commands/queries
+ * convention and resource/CRUD completeness that build ON schemas are NOT
+ * modeled here — they live in the convention overlay.
+ */
+export interface SchemaModule extends IAppModule<ModuleType.Schema> {
+    kind: 'schema';
+    /**
+     * The model table name (the schema's top-level `name:`), when declared. A
+     * schema declares exactly one, so this is a single value (unlike a GraphQL
+     * op's {@link GraphQLModule.tables}) that a consumer can join against. Absent
+     * when the file declares no `name:` or could not be parsed.
+     */
+    table?: string;
 }
 export interface IAppModule<T extends ModuleType> {
     /** Used as a discriminant in the AppModule union */
@@ -61,7 +159,8 @@ export interface IAppModule<T extends ModuleType> {
 export declare const enum ModuleType {
     Liquid = "Liquid",
     Asset = "Asset",
-    GraphQL = "GraphQL"
+    GraphQL = "GraphQL",
+    Schema = "Schema"
 }
 export declare const enum LiquidModuleKind {
     /** app/views/layouts/*.liquid files */

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAkHa,QAAA,gCAAgC,GAAG;IAC9C,KAAK;IACL,MAAM;IACN,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;CACN,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAqNa,QAAA,gCAAgC,GAAG;IAC9C,KAAK;IACL,MAAM;IACN,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;CACN,CAAC"}

package/dist/utils/index.d.ts

@@ -1,7 +1,7 @@
 import { UriString } from '@platformos/platformos-check-common';
 import { AbstractFileSystem } from '@platformos/platformos-common';
 export declare function unique<T>(array: T[]): T[];
-export declare function assertNever(module: never): void;
+export declare function assertNever(module: never): never;
 export declare const identity: <T>(x: T) => T;
 export declare function isString(x: unknown): x is string;
 export declare function extname(uri: UriString): string;

package/fixtures/asset-edges/app/assets/logo.css

@@ -0,0 +1 @@
+body { color: red; }

package/fixtures/asset-edges/app/assets/site/app.js

@@ -0,0 +1 @@
+console.log("app");

package/fixtures/asset-edges/app/views/pages/index.liquid

@@ -0,0 +1,3 @@
+<script src="{{ 'site/app.js' | asset_url }}" defer></script>
+<link rel="stylesheet" href="{{ 'logo.css' | asset_url }}">
+<link rel="icon" href="{{ 'images/missing.png' | asset_url }}">

package/fixtures/graphql-table/app/graphql/with_table.graphql

@@ -0,0 +1,5 @@
+query {
+  records(per_page: 1, filter: { table: { value: "blog_post" } }) {
+    results { id }
+  }
+}

package/fixtures/graphql-table/app/graphql/without_table.graphql

@@ -0,0 +1,3 @@
+query {
+  current_user { id email }
+}

package/fixtures/graphql-table/app/views/pages/index.liquid

@@ -0,0 +1,4 @@
+{% liquid
+  graphql posts = 'with_table'
+  graphql me = 'without_table'
+%}

package/fixtures/layout-edges/app/views/layouts/theme.liquid

@@ -0,0 +1,4 @@
+<!DOCTYPE html>
+<html>
+  <body>{{ content_for_layout }}</body>
+</html>

package/fixtures/layout-edges/app/views/pages/broken.liquid

@@ -0,0 +1,5 @@
+---
+slug: broken
+layout: ghost
+---
+<h1>broken</h1>

package/fixtures/layout-edges/app/views/pages/index.liquid

@@ -0,0 +1,5 @@
+---
+slug: index
+layout: theme
+---
+<h1>home</h1>

package/fixtures/schema-nodes/app/schema/blog_post.yml

@@ -0,0 +1,6 @@
+name: blog_post
+properties:
+  - name: title
+    type: string
+  - name: body
+    type: text

package/fixtures/schema-nodes/app/schema/no_name.yml

@@ -0,0 +1,3 @@
+properties:
+  - name: anon
+    type: string

package/fixtures/schema-nodes/app/views/pages/index.liquid

@@ -0,0 +1 @@
+<h1>home</h1>

package/fixtures/structural/app/views/pages/about.liquid

@@ -0,0 +1 @@
+<h1>about</h1>

package/fixtures/structural/app/views/pages/blog/show.liquid

@@ -0,0 +1,4 @@
+---
+slug: blog/custom
+---
+<h1>show</h1>

package/fixtures/structural/app/views/pages/index.liquid

@@ -0,0 +1,6 @@
+---
+layout: application
+method: get
+---
+{% render 'card' %}
+{% render 'documented' %}

package/fixtures/structural/app/views/pages/rich.liquid

@@ -0,0 +1,8 @@
+---
+layout: application
+---
+{% assign x = 'a' %}
+{% if x %}{{ x | upcase }}{% endif %}
+{% render 'card' %}
+{% graphql res = 'blog/find' %}
+{{ 'greeting.hello' | t }}

package/fixtures/structural/app/views/partials/card.liquid

@@ -0,0 +1 @@
+<div class="card">{{ title }}</div>

package/fixtures/structural/app/views/partials/documented.liquid

@@ -0,0 +1,5 @@
+{% doc %}
+  @param title [String] The card title.
+  @param count [Number] How many.
+{% enddoc %}
+<div>{{ title }}</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformos/platformos-graph",
-  "version": "0.0.20",
+  "version": "0.1.0",
   "description": "platformOS App Graph as a data structure",
   "author": "platformOS",
   "homepage": "https://github.com/Platform-OS/platformos-tools/tree/master/packages/platformos-graph#readme",
@@ -29,13 +29,15 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@platformos/liquid-html-parser": "^0.0.18",
-    "@platformos/platformos-check-common": "0.0.20",
-    "@platformos/platformos-common": "0.0.18",
+    "@platformos/liquid-html-parser": "^0.1.0",
+    "@platformos/platformos-check-common": "1.0.0",
+    "@platformos/platformos-common": "0.1.0",
     "acorn": "^8.16.0",
+    "js-yaml": "^4.1.1",
     "vscode-uri": "^3.1.0"
   },
   "devDependencies": {
-    "@platformos/platformos-check-node": "0.0.20"
+    "@platformos/platformos-check-node": "1.0.0",
+    "@types/js-yaml": "^4.0.9"
   }
 }

package/src/cli.spec.ts

@@ -1,8 +1,7 @@
 import nodePath from 'node:path';
 import { path } from '@platformos/platformos-check-common';
-import { AbstractFileSystem, FileType } from '@platformos/platformos-common';
+import { AbstractFileSystem, FileType, uriFromPath } from '@platformos/platformos-common';
 import { describe, expect, it } from 'vitest';
-import { URI } from 'vscode-uri';
 import { buildSerializedFileDependencies, buildSerializedGraph, nodeFileSystem } from './cli';
 import { skeleton } from './graph/test-helpers';
 import { LiquidModuleKind, ModuleType } from './types';
@@ -16,10 +15,23 @@ describe('platformos-graph CLI: buildSerializedGraph', () => {
     const graph = await buildSerializedGraph(skeletonPath);
 
     // Root is the project path re-expressed as a file URI.
-    expect(graph.rootUri).toBe(URI.file(skeletonPath).toString(true));
+    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,
@@ -50,18 +62,6 @@ describe('platformos-graph CLI: buildSerializedGraph', () => {
         kind: LiquidModuleKind.Partial,
         exists: true,
       },
-      {
-        uri: p('assets/app.css'),
-        type: ModuleType.Asset,
-        kind: 'unused',
-        exists: true,
-      },
-      {
-        uri: p('assets/app.js'),
-        type: ModuleType.Asset,
-        kind: 'unused',
-        exists: true,
-      },
     ]);
 
     // Whole edge set, reduced to (source, target, type, kind) and sorted, so an
@@ -78,21 +78,27 @@ describe('platformos-graph CLI: buildSerializedGraph', () => {
     expect(edges).toEqual([
       {
         source: p('app/views/layouts/application.liquid'),
-        target: p('app/views/partials/header.liquid'),
+        target: p('app/assets/app.css'),
         type: 'direct',
-        kind: 'render',
+        kind: 'asset',
       },
       {
         source: p('app/views/layouts/application.liquid'),
-        target: p('assets/app.css'),
+        target: p('app/assets/app.js'),
         type: 'direct',
         kind: 'asset',
       },
       {
         source: p('app/views/layouts/application.liquid'),
-        target: p('assets/app.js'),
+        target: p('app/views/partials/header.liquid'),
         type: 'direct',
-        kind: 'asset',
+        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'),
@@ -118,28 +124,28 @@ describe('platformos-graph CLI: buildSerializedGraph', () => {
 
 describe('platformos-graph CLI: nodeFileSystem', () => {
   it('reads a file by URI', async () => {
-    const uri = path.join(skeleton, 'assets', 'app.js');
+    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, 'assets'))).toEqual({
+    expect(await nodeFileSystem.stat(path.join(skeleton, 'app', 'assets'))).toEqual({
       type: FileType.Directory,
       size: expect.any(Number),
     });
-    expect(await nodeFileSystem.stat(path.join(skeleton, 'assets', 'app.css'))).toEqual({
+    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, 'assets'));
+    const entries = await nodeFileSystem.readDirectory(path.join(skeleton, 'app', 'assets'));
     expect([...entries].sort((a, b) => a[0].localeCompare(b[0]))).toEqual([
-      [path.join(skeleton, 'assets', 'app.css'), FileType.File],
-      [path.join(skeleton, 'assets', 'app.js'), FileType.File],
+      [path.join(skeleton, 'app', 'assets', 'app.css'), FileType.File],
+      [path.join(skeleton, 'app', 'assets', 'app.js'), FileType.File],
     ]);
   });
 });
@@ -225,8 +231,8 @@ describe('platformos-graph CLI: buildSerializedFileDependencies', () => {
 
   it('throws for a file that is not part of the app graph', async () => {
     const missing = fsPathOf('app/views/partials/nonexistent.liquid');
-    const missingUri = path.normalize(URI.file(missing));
-    const rootUri = path.normalize(URI.file(skeletonPath));
+    const missingUri = uriFromPath(missing);
+    const rootUri = uriFromPath(skeletonPath);
 
     const error = await buildSerializedFileDependencies(skeletonPath, missing).catch((e) => e);
     expect(error).toBeInstanceOf(Error);
@@ -252,14 +258,14 @@ describe('platformos-graph CLI: project-root validation', () => {
 
   it('throws instead of emitting an empty graph for a non-platformOS directory', async () => {
     const dir = nodePath.resolve('no-such-project', 'sub');
-    const startUri = path.normalize(URI.file(dir));
+    const 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/, modules/, .pos, or .platformos-check.yml found at or above this path. ` +
-        `Pass the path to a platformOS app directory.`,
+        `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

@@ -1,8 +1,18 @@
 import nodePath from 'node:path';
 import fs from 'node:fs/promises';
-import { findRoot, makeFileExists, path } from '@platformos/platformos-check-common';
-import { AbstractFileSystem, FileStat, FileTuple, FileType } from '@platformos/platformos-common';
-import { URI } from 'vscode-uri';
+import {
+  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';
@@ -25,7 +35,7 @@ export const nodeFileSystem: AbstractFileSystem = {
   async readDirectory(uri: string): Promise<FileTuple[]> {
     const entries = await fs.readdir(path.fsPath(uri), { withFileTypes: true });
     return entries.map((entry) => [
-      path.join(uri, entry.name),
+      path.childUri(uri, entry.name),
       entry.isDirectory() ? FileType.Directory : FileType.File,
     ]);
   },
@@ -59,8 +69,9 @@ export interface SerializableFileDependencies {
 /**
  * Resolves the given root path (absolute, or relative to `process.cwd()`) to the
  * forward-slash-normalized `file://` URI of the enclosing platformOS project,
- * using the same `findRoot` heuristic as the language server (an `app/`,
- * `modules/`, `.pos`, or `.platformos-check.yml` marker at or above the path).
+ * 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`
@@ -70,16 +81,21 @@ export interface SerializableFileDependencies {
  * `path.normalize` (forward slashes), so any lookup must key the same way or it
  * silently misses on Windows, where raw URIs keep backslashes.
  */
-async function resolveProjectRoot(root: string, fs: AbstractFileSystem): Promise<string> {
+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 startUri = path.normalize(URI.file(absolute));
 
-  const rootUri = await findRoot(startUri, makeFileExists(fs));
+  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: ${startUri}\n` +
-        `No app/, modules/, .pos, or .platformos-check.yml found at or above this path. ` +
-        `Pass the path to a platformOS app directory.`,
+      `Not a platformOS project: ${given}\n` +
+        `No ${markers} found ` +
+        `at or above this path. Pass the path to a platformOS app directory.`,
     );
   }
   return rootUri;
@@ -93,7 +109,7 @@ async function resolveProjectRoot(root: string, fs: AbstractFileSystem): Promise
  */
 function resolveFileUri(rootUri: string, file: string): string {
   if (nodePath.isAbsolute(file)) {
-    return path.normalize(URI.file(file));
+    return uriFromPath(file);
   }
   return path.join(rootUri, ...file.split(/[\\/]+/).filter(Boolean));
 }
@@ -109,7 +125,7 @@ export async function buildSerializedGraph(
   root: string,
   fs: AbstractFileSystem = nodeFileSystem,
 ): Promise<SerializableGraph> {
-  const graph = await buildAppGraph(await resolveProjectRoot(root, fs), { fs });
+  const graph = await buildAppGraph(await resolveGraphRoot(root, fs), { fs });
   return serializeAppGraph(graph);
 }
 
@@ -130,7 +146,7 @@ export async function buildSerializedFileDependencies(
   file: string,
   fs: AbstractFileSystem = nodeFileSystem,
 ): Promise<SerializableFileDependencies> {
-  const rootUri = await resolveProjectRoot(root, fs);
+  const rootUri = await resolveGraphRoot(root, fs);
   const fileUri = resolveFileUri(rootUri, file);
   const graph = await buildAppGraph(rootUri, { fs });
 

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 ??