check-modules-rule-registry.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Check Modules Rule Registry",
  "type": "object",
  "description": "Schema describing the rule registry consumed by the check-modules implementation.",
  "additionalProperties": false,
  "properties": {
    "schemaVersion": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Semantic version of the registry format (e.g. 1.0.0)."
    },
    "generatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO timestamp capturing when the registry file was generated."
    },
    "rules": {
      "type": "array",
      "description": "Collection of rule definitions applied by the check-modules stage.",
      "items": {
        "$ref": "#/$defs/rule"
      },
      "minItems": 1,
      "uniqueItems": true
    }
  },
  "required": ["schemaVersion", "rules"],
  "$defs": {
    "rule": {
      "type": "object",
      "title": "Rule",
      "description": "Declarative definition of a lint rule that produces issues for a module.",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]*$",
          "description": "Stable, kebab-case identifier (e.g. text-deprecated-new-buffer)."
        },
        "label": {
          "type": "string",
          "description": "Short human-readable name for the rule."
        },
        "category": {
          "type": "string",
          "enum": [
            "Deprecated",
            "Recommendation",
            "Typo",
            "Outdated",
            "Security",
            "Performance"
          ],
          "description": "High-level grouping shown alongside findings."
        },
        "severity": {
          "type": "string",
          "enum": ["info", "low", "medium", "high", "critical"],
          "description": "Relative priority used for ordering and alerting."
        },
        "autofixable": {
          "type": "boolean",
          "default": false,
          "description": "Indicates whether the issue can be auto-fixed by tooling."
        },
        "message": {
          "type": "string",
          "description": "Issue message presented to module maintainers."
        },
        "fixSuggestion": {
          "type": "string",
          "description": "Optional short hint or command describing how to resolve the issue."
        },
        "docsUrl": {
          "type": "string",
          "format": "uri",
          "description": "Optional reference link with extra context."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true,
          "description": "Arbitrary labels for grouping/filtering in the UI (e.g. ci, coding-style)."
        },
        "appliesTo": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "enum": [
              "general",
              "package-json",
              "package-lock",
              "readme",
              "filesystem",
              "external"
            ]
          },
          "uniqueItems": true,
          "description": "Which artifacts the rule inspects."
        },
        "detection": {
          "$ref": "#/$defs/detection",
          "description": "Declarative definition of how the rule identifies findings."
        },
        "metadata": {
          "type": "object",
          "description": "Free-form key/value pairs for pipeline-internal use (e.g. owner, rollout notes).",
          "additionalProperties": true
        }
      },
      "required": [
        "id",
        "label",
        "category",
        "severity",
        "message",
        "appliesTo",
        "detection"
      ]
    },
    "detection": {
      "type": "object",
      "title": "Detection",
      "description": "Strategy the stage uses to discover rule violations.",
      "additionalProperties": false,
      "properties": {
        "type": {
          "type": "string",
          "enum": ["text-match", "regex", "filesystem", "external"],
          "description": "Detector engine leveraged by the rule."
        },
        "caseSensitive": {
          "type": "boolean",
          "default": false,
          "description": "Indicates whether pattern matching is case-sensitive."
        },
        "allowPartialMatch": {
          "type": "boolean",
          "default": true,
          "description": "If false, matches must align to whole tokens (implementation-defined)."
        },
        "patterns": {
          "type": "array",
          "description": "List of patterns evaluated by the detector (required for text-match and regex).",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "pattern": {
                "type": "string",
                "description": "Substring or regular expression depending on detection.type."
              },
              "flags": {
                "type": "string",
                "pattern": "^[gimsuy]*$",
                "description": "Valid ECMAScript regex flags (only for regex detectors)."
              },
              "targetFiles": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "uniqueItems": true,
                "description": "Glob-like hints to narrow the search scope (e.g. README.md)."
              }
            },
            "required": ["pattern"]
          },
          "minItems": 1
        },
        "script": {
          "type": "string",
          "description": "Identifier of an external helper invoked for filesystem/external detections."
        }
      },
      "required": ["type"],
      "allOf": [
        {
          "if": {
            "properties": { "type": { "enum": ["text-match", "regex"] } },
            "required": ["type"]
          },
          "then": {
            "required": ["patterns"]
          }
        },
        {
          "if": {
            "properties": { "type": { "enum": ["filesystem", "external"] } },
            "required": ["type"]
          },
          "then": {
            "required": ["script"]
          }
        }
      ]
    }
  }
}