ScopeDoctorGroup

A "group" is a set of operations that should be preformed as part of solving a problem. For example, there may be a group to install and configure Node, or other language.

A Group is defined by one or more "actions". Taking a look at an example

apiVersion: scope.github.com/v1alpha
kind: ScopeDoctorGroup
metadata:
  name: node
spec:
  include: by-default
  description: Check node is ready.
  needs:
    - python
    - brew
  actions:
    - description: Node Version
      name: node-version
      check:
        paths:
          - '.npmrc'
        commands:
          - ./scripts/check-node-version.sh
      fix:
        commands:
          - ./scripts/fix-node-version.sh
        helpText: Running into errors reach out in #foo-help
        helpUrl: https://go.example.com/get-help
      required: false
    - description: Install packages
      name: yarn
      check:
        paths:
          - 'package.json'
          - '**/package.json'
          - yarn.lock
          - '**/yarn.lock'
      fix:
        commands:
          - yarn install

In the example above, there are two actions, the first ensures that node is operational.

Actions

An action is a discrete step, they run in order defined. The action should be atomic, and target a single resolution.

Notice an action can provide both paths and commands, if either of them indicate that the fix should run, it will run. In the event there are no defined check, the fix will always run.

paths indicate a fix should run when:

1. No files match any of the path globs, or
2. Any of the matching files contents have changed

Fix

When the checks determine that something isn't correct, a fix is the way to automate the resolution. When provided, scope will run them in order.

Commands

A command can either be relative, or use the PATH. To target a script relative to the group it must start with ., and giving a relative path to the group file.

Schema

Viewer

Loading ....

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "title": "V1AlphaDoctorGroup",
  "description": "Resource used to define a `ScopeDoctorGroup`.",
  "type": "object",
  "required": [
    "apiVersion",
    "kind",
    "metadata",
    "spec"
  ],
  "properties": {
    "apiVersion": {
      "description": "API version of the resource",
      "$ref": "#/definitions/V1AlphaApiVersion"
    },
    "kind": {
      "description": "The type of resource.",
      "$ref": "#/definitions/DoctorGroupKind"
    },
    "metadata": {
      "description": "Standard set of options including name, description for the resource. Together `kind` and `metadata.name` are required to be unique. If there are duplicate, the resources \"closest\" to the execution dir will take precedence.",
      "$ref": "#/definitions/ModelMetadata"
    },
    "spec": {
      "description": "Options for the resource.",
      "$ref": "#/definitions/DoctorGroupSpec"
    }
  },
  "additionalProperties": false,
  "definitions": {
    "DoctorCheckSpec": {
      "description": "What needs to be checked before the action will run. `paths` will be checked first, then `commands`. If a `path` matches no files or the matching files have changed, the `command` will run.",
      "type": "object",
      "properties": {
        "commands": {
          "description": "A list of commands to execute to check the environment.",
          "default": null,
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "nullable": true
        },
        "paths": {
          "description": "A list of globs to check for changes. When the glob matches a new file, or the contents of the file change, the check will require a fix.\n\nRelative paths are relative to the scope config directory containing the config file.\n\nShared configs can use the template string `{{ working_dir }}` to access the working directory.",
          "default": null,
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "nullable": true
        }
      },
      "additionalProperties": false
    },
    "DoctorFixSpec": {
      "description": "Definition for fixing the environment.",
      "type": "object",
      "properties": {
        "commands": {
          "description": "List of commands to run to fix the env.",
          "default": [],
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "helpText": {
          "description": "Text to display when no command is provided / fails to fix the env.",
          "default": null,
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "helpUrl": {
          "description": "Link to documentation to fix the issue.",
          "default": null,
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        }
      },
      "additionalProperties": false
    },
    "DoctorGroupActionSpec": {
      "description": "An action is a single step used to check in a group. This is most commonly used to build a series of tasks for a system, like `ruby`, `python`, and databases.",
      "type": "object",
      "required": [
        "check"
      ],
      "properties": {
        "check": {
          "description": "The `check` run before `fix` (if provided). A check is used to determine if the fix needs to be executed, or fail the action if no fix is provided. If a fix is specified, the check will re-execute to ensure that the fix applied correctly.",
          "$ref": "#/definitions/DoctorCheckSpec"
        },
        "description": {
          "description": "A description of this specific action, used for information to the users.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "fix": {
          "description": "A fix defines how to fix the issue that a `check` is validating. When provided, will only run when the `check` \"fails\".",
          "anyOf": [
            {
              "$ref": "#/definitions/DoctorFixSpec"
            },
            {
              "type": "null"
            }
          ],
          "nullable": true
        },
        "name": {
          "description": "Name of the \"action\". When not provided, it will be the index of the action within the group. This is used when reporting status to the users.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "required": {
          "description": "If false, the action is allowed to fail and let other actions in the group execute. Defaults to `true`.",
          "default": true,
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "DoctorGroupKind": {
      "type": "string",
      "enum": [
        "ScopeDoctorGroup"
      ]
    },
    "DoctorGroupSpec": {
      "description": "Often used to describe how to fix a \"system\", like `ruby`, `python`, or databases. Able to depend on other \"system\".",
      "type": "object",
      "required": [
        "actions"
      ],
      "properties": {
        "actions": {
          "description": "A series of steps to check and fix for the group.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/DoctorGroupActionSpec"
          }
        },
        "include": {
          "description": "Change how a group is handled when building the dependency task graph. When set to `when-required`, the group will be ignored unless it's required by another dependency.",
          "default": "by-default",
          "$ref": "#/definitions/DoctorInclude"
        },
        "needs": {
          "description": "A list of `ScopeDoctorGroup` that are required for this group to execute. If not all finish successfully, this group will not execute.",
          "default": [],
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "reportExtraDetails": {
          "description": "defines additional data that needs to be pulled from the system when reporting a bug. `reportExtraDetails` is a map of `string:string`, the value is a command that should be run. When a report is built, the commands will be run and automatically included in the report.",
          "default": {},
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "DoctorInclude": {
      "description": "Configure how a groups will be used when determining the task graph.",
      "oneOf": [
        {
          "description": "Default option, the group will be included by default when determining which groups should run.",
          "type": "string",
          "enum": [
            "by-default"
          ]
        },
        {
          "description": "Useful for shared configuration. The group will not run unless another group depends on it.",
          "type": "string",
          "enum": [
            "when-required"
          ]
        }
      ]
    },
    "KnownErrorKind": {
      "type": "string",
      "enum": [
        "ScopeKnownError"
      ]
    },
    "KnownErrorSpec": {
      "description": "Definition of the known error",
      "type": "object",
      "required": [
        "help",
        "pattern"
      ],
      "properties": {
        "help": {
          "description": "Text that the user can use to fix the issue",
          "type": "string"
        },
        "pattern": {
          "description": "A Regex used to determine if the line is an error.",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "ModelMetadata": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "annotations": {
          "description": "Annotations attach arbitrary non-identifying metadata to objects.",
          "default": {
            "scope.github.com/bin-path": null,
            "scope.github.com/file-dir": null,
            "scope.github.com/file-path": null,
            "working_dir": null
          },
          "$ref": "#/definitions/ModelMetadataAnnotations"
        },
        "description": {
          "description": "Description of this resource, used when listing resources and helpful to inform users why the resource exists.",
          "default": "Description not provided",
          "type": "string"
        },
        "labels": {
          "description": "Key/value pairs, allows resources to be easily filtered from the CLI.",
          "default": {},
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "name": {
          "description": "Name of the resource, needs to be unique across `kinds`. When two resources share a name, the one \"closest\" to the current working directory will take precedence.",
          "type": "string"
        }
      }
    },
    "ModelMetadataAnnotations": {
      "type": "object",
      "properties": {
        "scope.github.com/bin-path": {
          "description": "When running commands, additional paths that should be paced at the _beginning_ of the `PATH`.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "working_dir": {
          "description": "The current working directory of the scope command, generated automatically.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        }
      }
    },
    "ReportDestinationGithubIssueSpec": {
      "description": "How to load the report to GitHub Issue",
      "type": "object",
      "required": [
        "owner",
        "repo"
      ],
      "properties": {
        "owner": {
          "description": "`owner` of the repository for the issue",
          "type": "string"
        },
        "repo": {
          "description": "`repo` the name of the repo for the issue",
          "type": "string"
        },
        "tags": {
          "description": "A list of tags to be added to the issue",
          "default": [],
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "ReportDestinationLocalSpec": {
      "description": "Create a report that is only local",
      "type": "object",
      "required": [
        "directory"
      ],
      "properties": {
        "directory": {
          "description": "Directory to put the report into",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "ReportDestinationRustyPasteSpec": {
      "description": "How to upload a report to RustyPaste",
      "type": "object",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "description": "URL of RustyPaste",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "ReportDestinationSpec": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "rustyPaste"
          ],
          "properties": {
            "rustyPaste": {
              "$ref": "#/definitions/ReportDestinationRustyPasteSpec"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "githubIssue"
          ],
          "properties": {
            "githubIssue": {
              "$ref": "#/definitions/ReportDestinationGithubIssueSpec"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "local"
          ],
          "properties": {
            "local": {
              "$ref": "#/definitions/ReportDestinationLocalSpec"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "ReportDestinationTemplates": {
      "type": "object",
      "properties": {
        "analyze": {
          "description": "Template to use when generating a bug without with analyze or intercept A Jinja2 style template, to be included. The text should be in Markdown format. Scope injects `command` as the command that was run.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "doctor": {
          "description": "Template to use when generating a bug report with `scope doctor` A Jinja2 style template, to be included. The text should be in Markdown format. Scope injects `command` as the command that was run.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "title": {
          "description": "Title to use when creating the issue. This is a Jinja2 style template. `entrypoint` is provided as a variable, which is the scope command run.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        }
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "ReportLocationKind": {
      "type": "string",
      "enum": [
        "ScopeReportLocation"
      ]
    },
    "ReportLocationSpec": {
      "description": "Define where to upload the report to",
      "type": "object",
      "required": [
        "destination"
      ],
      "properties": {
        "additionalData": {
          "description": "defines additional data that needs to be pulled from the system when reporting a bug. `additionalData` is a map of `string:string`, the value is a command that should be run. When a report is built, the commands will be run and automatically included in the report.",
          "default": {},
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "destination": {
          "description": "Destination the report should be uploaded to",
          "$ref": "#/definitions/ReportDestinationSpec"
        },
        "templates": {
          "description": "Templates to use when uploading a report",
          "default": {
            "analyze": null,
            "doctor": null,
            "title": null
          },
          "$ref": "#/definitions/ReportDestinationTemplates"
        }
      },
      "additionalProperties": false
    },
    "V1AlphaApiVersion": {
      "description": "Version of the Scope API",
      "oneOf": [
        {
          "description": "Current latest version of the resources.",
          "type": "string",
          "enum": [
            "scope.github.com/v1alpha"
          ]
        }
      ]
    },
    "V1AlphaDoctorGroup": {
      "description": "Resource used to define a `ScopeDoctorGroup`.",
      "type": "object",
      "required": [
        "apiVersion",
        "kind",
        "metadata",
        "spec"
      ],
      "properties": {
        "apiVersion": {
          "description": "API version of the resource",
          "$ref": "#/definitions/V1AlphaApiVersion"
        },
        "kind": {
          "description": "The type of resource.",
          "$ref": "#/definitions/DoctorGroupKind"
        },
        "metadata": {
          "description": "Standard set of options including name, description for the resource. Together `kind` and `metadata.name` are required to be unique. If there are duplicate, the resources \"closest\" to the execution dir will take precedence.",
          "$ref": "#/definitions/ModelMetadata"
        },
        "spec": {
          "description": "Options for the resource.",
          "$ref": "#/definitions/DoctorGroupSpec"
        }
      },
      "additionalProperties": false
    },
    "V1AlphaKnownError": {
      "description": "Resource used to define a `ScopeKnownError`. A known error is a specific error that a user may run into.",
      "type": "object",
      "required": [
        "apiVersion",
        "kind",
        "metadata",
        "spec"
      ],
      "properties": {
        "apiVersion": {
          "description": "API version of the resource",
          "$ref": "#/definitions/V1AlphaApiVersion"
        },
        "kind": {
          "description": "The type of resource.",
          "$ref": "#/definitions/KnownErrorKind"
        },
        "metadata": {
          "description": "Standard set of options including name, description for the resource. Together `kind` and `metadata.name` are required to be unique. If there are duplicate, the resources \"closest\" to the execution dir will take precedence.",
          "$ref": "#/definitions/ModelMetadata"
        },
        "spec": {
          "description": "Options for the resource.",
          "$ref": "#/definitions/KnownErrorSpec"
        }
      },
      "additionalProperties": false
    },
    "V1AlphaReportLocation": {
      "description": "A `ScopeReportLocation` tells where to upload a report to.",
      "type": "object",
      "required": [
        "apiVersion",
        "kind",
        "metadata",
        "spec"
      ],
      "properties": {
        "apiVersion": {
          "description": "API version of the resource",
          "$ref": "#/definitions/V1AlphaApiVersion"
        },
        "kind": {
          "description": "The type of resource.",
          "$ref": "#/definitions/ReportLocationKind"
        },
        "metadata": {
          "description": "Standard set of options including name, description for the resource. Together `kind` and `metadata.name` are required to be unique. If there are duplicate, the resources \"closest\" to the execution dir will take precedence.",
          "$ref": "#/definitions/ModelMetadata"
        },
        "spec": {
          "description": "Options for the resource.",
          "$ref": "#/definitions/ReportLocationSpec"
        }
      },
      "additionalProperties": false
    }
  }
}