A platformOS Graph is a data structure that spans Liquid, JSON, JavaScript and CSS files.

It has the following interface:

interface AppGraph {
  rootUri: UriString; // e.g. 'file:/path/to/my-app'
  entryPoints: AppModule[];
  modules: Record<UriString, AppModule>
}

An AppModule holds dependencies and references of a module. For instance,

interface LiquidModule {
  uri: UriString;
  type: 'liquid';
  kind: 'layout' | 'partial' | 'page';
  references: Reference[];
  dependencies: Reference[];
}

For a module $M$,

• a reference is a backlink to other modules that depend on $M$,
• a dependency is a dependent link on another module.

interface Reference {
  /* The file that initiated the dependency/reference */
  source: { uri: string, range?: Range };

  /* The file that it points to */
  target: { uri: string, range?: Range };

  type:
    | 'direct'   // e.g. {% render 'child' %}, {{ 'app.js' | asset_url }}, <custom-element>, etc.
    | 'indirect' // e.g. files that loosely depend on another
}

See types.md for more details and how-it-works.md for an overview of the algorithm.

Installation

npm install @platformos/platformos-graph

Usage

Through the VS Code extension

The app graph is used by the VS Code extension to power the dependencies, references and dead code features.

From the CLI

Usage:
  platformos-graph <path-to-app-directory>

Example:
  platformos-graph horizon > graph.json

As a library

See bin/platformos-graph for inspiration.

Contributing

See CONTRIBUTING.md.