Graph

The Graph tool build’s on oneRepo’s powerful Workspace Graph by adding a Workspace & Workspace file validator and a Graph visualizer.

Configuration

The one graph verify command comes with some basic schema for validating package.json files and no configuration is required.

However, you can enhance this by providing custom schema to match to workspaces and their files:

export default {
  validation: {
    schema: './path/to/graph-schema.js',
  },
};

Commands

`one graph`

Run core Graph commands

one graph <command>

`one graph show`

Show this repository’s Workspace Graph using an online visualizer or output Graph representations to various formats.

one graph show [options...]

This command can generate representations of your Workspace Graph for use in debugging, verifying, and documentation. By default, a URL will be given to visualize your Graph online.

Pass --open to auto-open your default browser with the URL or use one of the --format options to print out various other representations.

Option	Type	Description
`--affected`	`boolean`	Select all affected Workspaces. If no other inputs are chosen, this will default to `true`.
`--all, -a`	`boolean`	Run across all Workspaces
`--format, -f`	`"mermaid"`, `"plain"`, `"json"`	Output format for inspecting the Workspace Graph.
`--open`	`boolean`	Auto-open the browser for the online visualizer.
`--staged`	`boolean`	Use files on the git stage to calculate affected files or Workspaces. When unset or `--no-staged`, changes will be calculated from the entire branch, since its fork point.
`--workspaces, -w`	`array`	List of Workspace names to run against

Advanced options

Option	Type	Description
`--from-ref`	`string`	Git ref to start looking for affected files or Workspaces
`--through-ref`	`string`	Git ref to start looking for affected files or Workspaces
`--url`	`string`, default: `"https://onerepo.tools/visualize/"`	Override the URL used to visualize the Graph. The Graph data will be attached the the `g` query parameter as a JSON string of the DAG, compressed using zLib deflate.

Print a URL to the online visualizer for the current affected Workspace Graph.

one graph show

Open the online visualizer for your full Workspace Graph.

one graph show --all --open

Generate a Mermaid graph to a file, isolating just the given <workspaces...> and those that are dependent on it.

one graph show --format=mermaid -w <workspaces...> > ./out.mermaid

`one graph verify`

Verify the integrity of the repo’s dependency Graph and files in each Workspace.

one graph verify

This command will first validate dependencies across Workspace Graph trees using the given --mode as well as Workspace configuration file integrity using the repo’s defined JSON schema validators.

Dependencies across Workspaces can be validated using one of the various modes:

off: No validation will occur. Everything goes.
loose: Reused third-party dependencies will be required to have semantic version overlap across unique branches of the Graph.
strict: Versions of all dependencies across each discrete Workspace dependency tree must be strictly equal.

Option	Type	Description
`--mode`	`"strict"`, `"loose"`, `"off"`, default: `"loose"`	Dependency overlap validation method.

Advanced options

Option	Type	Description
`--custom-schema`	`string`	Path to a custom JSON schema definition

Verifying configurations

The one graph verify command in oneRepo has support for validating most configuration files in workspaces, including JSON, CJSON, YAML, and static JavaScript/TypeScript configurations.

Schema validation uses AJV with support for JSON schemas draft-2019-09 and draft-07. It also supports ajv-errors for better and more actionable error messaging.

Examples

JSON validation

export default {
  'modules/*': {
    'package.json': {
      type: 'object',
      properties: {
        // Ensure package names start with your organizations scope:
        name: {
          type: 'string',
          pattern: '^@scope\\/',
          // ajv-errors addition
          errorMessage: {
            pattern: 'Modules must be scoped for the organization, "@scope/<name>"',
          },
        },
      },
      required: ['name'],
    },
  },
  'apps/*': {
    'tsconfig.json': {
      type: 'object',
      properties: {
        // Ensure your tsconfig.json extends your standard config
        extends: { type: 'string', enum: ['@scope/tsconfig/base.json'] },
      },
    },
  },
};

JS/TS config validation

Note that if the configuration is the default export, like in the case of jest.config.js files, you will need set the export name property or properties to validate. To validate the default export use the property name default.

import type { GraphSchemaValidators } from 'onerepo';

export default {
  '**/*': {
    'jest.config.js': {
      type: 'object',
      properties: {
        default: {
          type: 'object',
          properties: {
            displayName: { type: 'string' },
            clearMocks: { type: 'boolean', const: true },
            resetMocks: { type: 'boolean', const: true },
          },
          required: ['displayname', 'clearMocks', 'resetMocks'],
        }
      },
      required: ['default']
    },
  },
} satisfies GraphSchemaValidators;

Functional schema

There are cases where more information about a workspace is needed for the schema to be complete. For this, the schema may also be a function that accepts two arguments, workspace and graph:

import type { graph, GraphSchemaValidators } from 'onerepo';

export default {
  '**': {
    'package.json': (workspace: graph.Workspace, graph: graph.Graph) => ({
      type: 'object',
      properties: {
        repository: {
          type: 'object',
          properties: {
            directory: {
              type: 'string',
              const: graph.root.relative(workspace.location),
            },
          },
          required: ['directory'],
        },
      },
      required: ['repository'],
    }),
  },
} satisfies GraphSchemaValidators;

Base schema

oneRepo provides a base schema with some defaults for private & public package.json files. If the provided schema are not to your liking, you can override with the location glob '**':

module.export = {
  '**': {
    'package.json': {
      /* ... */
    },
  },
};

Schema extensions

Required files

To mark a file as required, the JSON schema validation has been extended to include a key $required at the top level of each file schema. Setting this key to true will result in errors if a matched workspace does not include this file:

import type { graph, GraphSchemaValidators } from 'onerepo';

export default {
  '**': {
    'package.json': {
      type: 'object',
      $required: true,
    },
  },
} satisfies GraphSchemaValidators;