@platformos/platformos-graph 0.0.19 → 0.1.0

package/dist/types.d.ts

@@ -1,39 +1,137 @@
-import { JSONSourceCode, LiquidSourceCode, Dependencies as CheckDependencies, UriString, Reference, Location, Range, GraphQLSourceCode, YAMLSourceCode } from '@platformos/platformos-check-common';
+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>;
-    /** A way to link <custom-element> to its window.customElements.define statement */
-    getWebComponentDefinitionReference: (customElementName: string) => {
-        assetName: string;
-        range: Range;
-    } | undefined;
+    /**
+     * 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;
+export type AppModule = LiquidModule | AssetModule | GraphQLModule | SchemaModule;
 export type FileSourceCode = LiquidSourceCode | JSONSourceCode | GraphQLSourceCode | YAMLSourceCode | AssetSourceCode;
 export interface SerializableGraph {
     rootUri: UriString;
     nodes: SerializableNode[];
     edges: SerializableEdge[];
 }
-export interface SerializableEdge {
-    source: Location;
-    target: Location;
-}
+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';
 }
+/**
+ * A `.graphql` operation file (referenced by `{% graphql op = 'name' %}`).
+ * A leaf node — GraphQL documents have no outgoing platformOS dependencies —
+ * so it is not traversed, only existence-checked (like {@link AssetModule}).
+ */
+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 */
     type: T;
@@ -60,7 +158,9 @@ export interface IAppModule<T extends ModuleType> {
 }
 export declare const enum ModuleType {
     Liquid = "Liquid",
-    Asset = "Asset"
+    Asset = "Asset",
+    GraphQL = "GraphQL",
+    Schema = "Schema"
 }
 export declare const enum LiquidModuleKind {
     /** app/views/layouts/*.liquid files */
@@ -77,11 +177,5 @@ export interface AssetSourceCode {
     source: string;
     ast: any | Error;
 }
-export { Reference, Range, Location };
+export { Reference, ReferenceKind, Range, Location };
 export type Void = void | Void[];
-export type WebComponentMap = Map<WebComponentName, WebComponentDefinition>;
-export type WebComponentName = string;
-export type WebComponentDefinition = {
-    assetName: string;
-    range: [number, number];
-};

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AA6Ga,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/background-edges/app/views/pages/broken.liquid

@@ -0,0 +1,3 @@
+{% liquid
+  background job_id = 'jobs/missing'
+%}

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

@@ -0,0 +1,3 @@
+{% liquid
+  background job_id = 'jobs/notify', data: 'x'
+%}

package/fixtures/background-edges/app/views/partials/jobs/notify.liquid

@@ -0,0 +1,3 @@
+{% liquid
+  log "queued"
+%}

package/fixtures/function-edges/app/lib/queries/list.liquid

@@ -0,0 +1,3 @@
+{% liquid
+  return true
+%}

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

@@ -0,0 +1,3 @@
+{% liquid
+  function ghost = 'queries/missing'
+%}

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

@@ -0,0 +1,3 @@
+{% liquid
+  function items = 'queries/list'
+%}

package/fixtures/graphql-edges/app/graphql/blog_posts/find.graphql

@@ -0,0 +1,10 @@
+query find($id: ID!) {
+  records(
+    per_page: 1
+    filter: { id: { value: $id }, table: { value: "blog_post" } }
+  ) {
+    results {
+      id
+    }
+  }
+}

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

@@ -0,0 +1,3 @@
+{% liquid
+  graphql ghost = 'blog_posts/missing'
+%}

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

@@ -0,0 +1,3 @@
+{% liquid
+  graphql posts = 'blog_posts/find', id: '1'
+%}

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/include-edges/app/views/pages/index.liquid

@@ -0,0 +1 @@
+{% include 'shared/header' %}

package/fixtures/include-edges/app/views/partials/shared/header.liquid

@@ -0,0 +1 @@
+<header>site</header>

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/module-edges/app/views/pages/index.liquid

@@ -0,0 +1,4 @@
+{% liquid
+  function items = 'modules/my_module/queries/get'
+%}
+{% render 'modules/my_module/card' %}

package/fixtures/module-edges/modules/my_module/public/lib/queries/get.liquid

@@ -0,0 +1,3 @@
+{% liquid
+  return true
+%}

package/fixtures/module-edges/modules/my_module/public/views/partials/card.liquid

@@ -0,0 +1 @@
+<article>card</article>

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/skeleton/app/assets/app.js

@@ -0,0 +1 @@
+// Skeleton app bundle (asset reference target).

package/fixtures/skeleton/app/views/partials/child.liquid

@@ -1,9 +1,7 @@
 {% doc %}
-  Child fixture that depends on the child-element custom element
+  Child partial.
 
   @param {string} children
 {% enddoc %}
 
-<child-element>
-  {{ children }}
-</child-element>
+{{ children }}

package/fixtures/skeleton/app/views/partials/parent.liquid

@@ -1,9 +1,7 @@
 {% doc %}
-  Parent partial that renders the children and depends on the parent-element custom element
+  Parent partial that renders the child partial.
 
   @param {string} children
 {% enddoc %}
 
-<parent-element>
-  {% render "child", children: children %}
-</parent-element>
+{% render "child", children: children %}

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.19",
+  "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.17",
-    "@platformos/platformos-check-common": "0.0.19",
+    "@platformos/liquid-html-parser": "^0.1.0",
+    "@platformos/platformos-check-common": "1.0.0",
+    "@platformos/platformos-common": "0.1.0",
     "acorn": "^8.16.0",
-    "acorn-walk": "^8.3.5",
+    "js-yaml": "^4.1.1",
     "vscode-uri": "^3.1.0"
   },
   "devDependencies": {
-    "@platformos/platformos-check-node": "0.0.19"
+    "@platformos/platformos-check-node": "1.0.0",
+    "@types/js-yaml": "^4.0.9"
   }
 }