results-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://dependency-cruiser.js.org/results-schema",
  "title": "dependency-cruiser output format",
  "type": "object",
  "required": ["summary", "modules"],
  "additionalProperties": false,
  "properties": {
    "summary": {
      "type": "object",
      "required": [
        "violations",
        "error",
        "warn",
        "info",
        "totalCruised",
        "optionsUsed"
      ],
      "additionalProperties": false,
      "description": "Data summarizing the found dependencies",
      "properties": {
        "violations": {
          "type": "array",
          "description": "A list of violations found in the dependencies. The dependencies themselves also contain this information, this summary is here for convenience.",
          "items": { "$ref": "#/definitions/ViolationType" }
        },
        "error": {
          "type": "number",
          "description": "the number of errors in the dependencies"
        },
        "warn": {
          "type": "number",
          "description": "the number of warnings in the dependencies"
        },
        "info": {
          "type": "number",
          "description": "the number of informational level notices in the dependencies"
        },
        "totalCruised": {
          "type": "number",
          "description": "the number of modules cruised"
        },
        "totalDependenciesCruised": {
          "type": "number",
          "description": "the number of dependencies cruised"
        },
        "ruleSetUsed": {
          "type": "object",
          "additionalProperties": false,
          "description": "rules used in the cruise",
          "properties": {
            "forbidden": {
              "type": "array",
              "description": "A list of rules that describe dependencies that are not allowed. dependency-cruiser will emit a separate error (warning/ informational) messages for each violated rule.",
              "items": {
                "$ref": "#/definitions/ForiddenRuleType"
              }
            },
            "allowed": {
              "type": "array",
              "description": "A list of rules that describe dependencies that are allowed. dependency-cruiser will emit the warning message 'not-in-allowed' for each dependency that does not at least meet one of them.",
              "items": {
                "$ref": "#/definitions/RuleType"
              }
            },
            "allowedSeverity": {
              "$ref": "#/definitions/SeverityType",
              "description": "Severity to use when a dependency is not in the 'allowed' set of rules. Defaults to 'warn'"
            }
          }
        },
        "optionsUsed": { "$ref": "#/definitions/OptionsType" }
      }
    },
    "modules": {
      "type": "array",
      "description": "A list of modules, with for each module the modules it depends upon",
      "items": {
        "type": "object",
        "required": ["source", "dependencies", "valid"],
        "additionalProperties": false,
        "properties": {
          "source": {
            "type": "string",
            "description": "The (resolved) file name of the module, e.g. 'src/main/index.js'"
          },
          "followable": {
            "type": "boolean",
            "description": "Whether or not this is a dependency that can be followed any further. This will be 'false' for for core modules, json, modules that could not be resolved to a file and modules that weren't followed because it matches the doNotFollow expression."
          },
          "matchesDoNotFollow": {
            "type": "boolean",
            "description": "'true' if the file name of this module matches the doNotFollow regular expression"
          },
          "coreModule": {
            "type": "boolean",
            "description": "Whether or not this is a node.js core module"
          },
          "couldNotResolve": {
            "type": "boolean",
            "description": "'true' if dependency-cruiser could not resolve the module name in the source code to a file name or core module. 'false' in all other cases."
          },
          "dependencyTypes": {
            "type": "array",
            "items": { "$ref": "#/definitions/DependencyType" },
            "description": "the type of inclusion - local, core, unknown (= we honestly don't know), undetermined (= we didn't bother determining it) or one of the npm dependencies defined in a package.jsom ('npm' for 'depenencies', 'npm-dev', 'npm-optional', 'npm-peer', 'npm-no-pkg' for development, optional, peer dependencies and dependencies in node_modules but not in package.json respectively)"
          },
          "license": {
            "type": "string",
            "description": "the license, if known (usually known for modules pulled from npm, not for local ones)"
          },
          "orphan": {
            "type": "boolean",
            "description": "'true' if this module does not have dependencies, and no module has it as a dependency"
          },
          "reachable": {
            "type": "array",
            "items": { "$ref": "#/definitions/ReachableType" },
            "description": "An array of objects that tell whether this module is 'reachable', and according to rule in which this reachability was defined"
          },
          "valid": {
            "type": "boolean",
            "description": "'true' if this module violated a rule; 'false' in all other cases. The violated rule will be in the 'rule' object at the same level."
          },
          "rules": {
            "type": "array",
            "items": { "$ref": "#/definitions/RuleSummaryType" },
            "description": "an array of rules violated by this module - left out if the module is valid"
          },
          "dependencies": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "module",
                "resolved",
                "coreModule",
                "dependencyTypes",
                "followable",
                "couldNotResolve",
                "moduleSystem",
                "valid",
                "dynamic"
              ],
              "additionalProperties": false,
              "properties": {
                "module": {
                  "type": "string",
                  "description": "The name of the module as it appeared in the source code, e.g. './main'"
                },
                "resolved": {
                  "type": "string",
                  "description": "The (resolved) file name of the module, e.g. 'src/main//index.js'"
                },
                "coreModule": {
                  "type": "boolean",
                  "description": "Whether or not this is a node.js core module - deprecated in favor of dependencyType === core"
                },
                "dependencyTypes": {
                  "type": "array",
                  "items": { "$ref": "#/definitions/DependencyType" },
                  "description": "the type of inclusion - local, core, unknown (= we honestly don't know), undetermined (= we didn't bother determining it) or one of the npm dependencies defined in a package.jsom ('npm' for 'depenencies', 'npm-dev', 'npm-optional', 'npm-peer', 'npm-no-pkg' for development, optional, peer dependencies and dependencies in node_modules but not in package.json respectively)"
                },
                "license": {
                  "type": "string",
                  "description": "the license, if known (usually known for modules pulled from npm, not for local ones)"
                },
                "followable": {
                  "type": "boolean",
                  "description": "Whether or not this is a dependency that can be followed any further. This will be 'false' for for core modules, json, modules that could not be resolved to a file and modules that weren't followed because it matches the doNotFollow expression."
                },
                "dynamic": {
                  "type": "boolean",
                  "description": "true if this dependency is dynamic, false in all other cases"
                },
                "matchesDoNotFollow": {
                  "type": "boolean",
                  "description": "'true' if the file name of this module matches the doNotFollow regular expression"
                },
                "couldNotResolve": {
                  "type": "boolean",
                  "description": "'true' if dependency-cruiser could not resulve the module name in the source code to a file name or core module. 'false' in all other cases."
                },
                "circular": {
                  "type": "boolean",
                  "description": "'true' if following this dependency will ultimately return to the source, false in all other cases"
                },
                "moduleSystem": { "$ref": "#/definitions/ModuleSystemType" },
                "valid": {
                  "type": "boolean",
                  "description": "'true' if this dependency violated a rule; 'false' in all other cases. The violated rule will be in the 'rule' object at the same level."
                },
                "rules": {
                  "type": "array",
                  "items": { "$ref": "#/definitions/RuleSummaryType" },
                  "description": "an array of rules violated by this dependency - left out if the dependency is valid"
                }
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "RuleType": {
      "type": "object",
      "required": ["from", "to"],
      "additionalProperties": false,
      "properties": {
        "comment": {
          "type": "string"
        },
        "from": {
          "$ref": "#/definitions/FromRestrictionType"
        },
        "to": {
          "$ref": "#/definitions/ToRestrictionType"
        }
      }
    },
    "ForiddenRuleType": {
      "type": "object",
      "required": ["from", "to"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "A short name for the rule - will appear in reporters to enable customers to quickly identify a violated rule. Try to keep them short, eslint style. E.g. 'not-to-core' for a rule forbidding dependencies on core modules, or 'not-to-unresolvable' for one that prevents dependencies on modules that probably don't exist."
        },
        "severity": { "$ref": "#/definitions/SeverityType" },
        "comment": {
          "type": "string",
          "description": "You can use this field to document why the rule is there."
        },
        "from": {
          "$ref": "#/definitions/FromRestrictionType"
        },
        "to": {
          "$ref": "#/definitions/ToRestrictionType"
        }
      }
    },
    "FromRestrictionType": {
      "type": "object",
      "description": "Criteria an end of a dependency should match to be caught by this rule. Leave it empty if you want any module to be matched.",
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "string",
          "description": "A regular expression an end of a dependency should match to be catched by this rule."
        },
        "pathNot": {
          "type": "string",
          "description": "A regular expression an end of a dependency should NOT match to be catched by this rule."
        },
        "orphan": {
          "type": "boolean",
          "description": "Whether or not to match when the module is an orphan (= has no incoming or outgoing dependencies). When this property it is part of a rule, dependency-cruiser will ignore the 'to' part."
        }
      }
    },
    "ToRestrictionType": {
      "type": "object",
      "description": "Criteria the 'to' end of a dependency should match to be caught by this rule. Leave it empty if you want any module to be matched.",
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "string",
          "description": "A regular expression an end of a dependency should match to be catched by this rule."
        },
        "pathNot": {
          "type": "string",
          "description": "A regular expression an end of a dependency should NOT match to be catched by this rule."
        },
        "couldNotResolve": {
          "type": "boolean",
          "description": "Whether or not to match modules dependency-cruiser could not resolve (and probably aren't on disk). For this one too: leave out if you don't care either way."
        },
        "circular": {
          "type": "boolean",
          "description": "Whether or not to match when following to the to will ultimately end up in the from."
        },
        "dependencyTypes": {
          "type": "array",
          "description": "Whether or not to match modules of any of these types (leaving out matches any of them)",
          "items": { "$ref": "#/definitions/DependencyType" }
        },
        "dynamic": {
          "type": "boolean",
          "description": "true if this dependency is dynamic, false in all other cases"
        },
        "moreThanOneDependencyType": {
          "type": "boolean",
          "description": "If true matches dependencies with more than one dependency type (e.g. defined in _both_ npm and npm-dev)"
        },
        "reachable": {
          "type": "boolean",
          "description": "Whether or not to match modules that aren't reachable from the from part of the rule. NOTE & TODO: should be separate rule type that ensures there's only one, and that has only path and pathNot in the to part"
        },
        "license": {
          "type": "string",
          "description": "Whether or not to match modules that were released under one of the mentioned licenses. E.g. to flag GPL-1.0, GPL-2.0 licensed modules (e.g. because your app is not compatible with the GPL) use \"GPL\""
        },
        "licenseNot": {
          "type": "string",
          "description": "Whether or not to match modules that were NOT released under one of the mentioned licenses. E.g. to flag everyting non MIT use \"MIT\" here"
        }
      }
    },
    "SeverityType": {
      "type": "string",
      "description": "How severe a violation of a rule is. The 'error' severity will make some reporters return a non-zero exit code, so if you want e.g. a build to stop when there's a rule violated: use that. The absence of the 'ignore' severity here is by design; ignored rules don't show up in the output.",
      "enum": ["error", "warn", "info"]
    },
    "RuleSummaryType": {
      "type": "object",
      "description": "If there was a rule violation (valid === false), this object contains the name of the rule and severity of violating it.",
      "required": ["name", "severity"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "The (short, eslint style) name of the violated rule. Typically something like 'no-core-punycode' or 'no-outside-deps'."
        },
        "severity": { "$ref": "#/definitions/SeverityType" }
      }
    },
    "ViolationType": {
      "type": "object",
      "required": ["from", "to", "rule"],
      "additionalProperties": false,
      "properties": {
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        },
        "additionalInformation": {
          "description": "if there's more information on the violation (e.g. the complete path in case of a circular dependency) it'll be here",
          "type": "string"
        },
        "rule": { "$ref": "#/definitions/RuleSummaryType" }
      }
    },
    "ModuleSystemType": {
      "type": "string",
      "enum": ["cjs", "amd", "es6", "tsd"]
    },
    "OutputType": {
      "type": "string",
      "enum": ["html", "dot", "err", "json"]
    },
    "DependencyType": {
      "type": "string",
      "enum": [
        "aliased",
        "core",
        "deprecated",
        "local",
        "localmodule",
        "npm",
        "npm-bundled",
        "npm-dev",
        "npm-no-pkg",
        "npm-optional",
        "npm-peer",
        "npm-unknown",
        "undetermined",
        "unknown"
      ]
    },
    "ReachableType": {
      "type": "object",
      "required": ["value", "asDefinedInRule"],
      "additionalProperties": false,
      "properties": {
        "value": {
          "type": "boolean",
          "description": "'true' if this module is reachable from any of the modules matched by the from part of a reachability-rule in 'asDefinedInRule', 'false' if not."
        },
        "asDefinedInRule": {
          "type": "string",
          "description": "The name of the rule where the reachability was defined"
        }
      }
    },
    "OptionsType": {
      "type": "object",
      "description": "the (command line) options used to generate the dependency-tree",
      "additionalProperties": false,
      "properties": {
        "args": {
          "type": "string",
          "description": "arguments passed on the command line"
        },
        "rulesFile": {
          "type": "string",
          "description": "The rules file used to validate the dependencies (if any)"
        },
        "outputTo": {
          "type": "string",
          "description": "File the output was written to ('-' for stdout)"
        },
        "doNotFollow": {
          "type": "object",
          "description": "Criteria for modules to include, but not to follow further",
          "additionalProperties": false,
          "properties": {
            "path": {
              "type": "string",
              "description": "a regular expression for modules to include, but not follow further"
            },
            "dependencyTypes": {
              "type": "array",
              "description": "an array of dependency types to include, but not follow further",
              "items": { "$ref": "#/definitions/DependencyType" }
            }
          }
        },
        "exclude": {
          "type": "object",
          "description": "Criteria for dependencies to exclude",
          "additionalProperties": false,
          "properties": {
            "path": {
              "type": "string",
              "description": "a regular expression for modules to exclude from being cruised"
            },
            "dynamic": {
              "type": "boolean",
              "description": "a boolean indicating whether or not to exclude dynamic dependencies"
            }
          }
        },
        "includeOnly": {
          "type": "string",
          "description": "a regular expression for modules to cruise; anything outside it will be skipped"
        },
        "maxDepth": {
          "type": "number",
          "description": "The maximum cruise depth specified. 0 means no maximum specified"
        },
        "moduleSystems": {
          "type": "array",
          "items": { "$ref": "#/definitions/ModuleSystemType" }
        },
        "outputType": { "$ref": "#/definitions/OutputType" },
        "prefix": {
          "type": "string"
        },
        "tsPreCompilationDeps": {
          "type": "boolean"
        },
        "combinedDependencies": {
          "type": "boolean"
        },
        "preserveSymlinks": {
          "type": "boolean"
        },
        "tsConfig": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "fileName": {
              "type": "string"
            }
          }
        },
        "webpackConfig": {
          "type": "object",
          "additionalProperties": false,
          "description": "The webpack configuration options used for the cruise",
          "properties": {
            "fileName": {
              "type": "string",
              "description": "The name of the webpack configuration file used"
            },
            "env": {
              "description": "The 'env' parameters passed",
              "oneOf": [
                {
                  "type": "object"
                },
                {
                  "type": "string"
                }
              ]
            },
            "arguments": {
              "type": "object",
              "description": "The arguments used"
            }
          }
        },
        "externalModuleResolutionStrategy": {
          "type": "string",
          "description": "What external module resolution strategy to use. Defaults to 'node_modules'",
          "enum": ["node_modules", "yarn-pnp"]
        }
      }
    }
  }
}