plugin-schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ExternalPluginDef",
  "description": "A declarative plugin definition loaded from a standalone file or inline config.\n\nExternal plugins provide the same static pattern capabilities as built-in\nplugins (entry points, always-used files, used exports, tooling dependencies),\nbut are defined in standalone files or inline in the fallow config rather than\ncompiled Rust code.\n\nThey cannot do AST-based config parsing (`resolve_config()`), but cover the\nvast majority of framework integration use cases.\n\nSupports JSONC, JSON, and TOML formats. All use camelCase field names.\n\n```json\n{\n  \"$schema\": \"https://raw.githubusercontent.com/fallow-rs/fallow/main/plugin-schema.json\",\n  \"name\": \"my-framework\",\n  \"enablers\": [\"my-framework\", \"@my-framework/core\"],\n  \"entryPoints\": [\"src/routes/**/*.{ts,tsx}\"],\n  \"configPatterns\": [\"my-framework.config.{ts,js}\"],\n  \"alwaysUsed\": [\"src/setup.ts\"],\n  \"toolingDependencies\": [\"my-framework-cli\"],\n  \"usedExports\": [\n    { \"pattern\": \"src/routes/**/*.{ts,tsx}\", \"exports\": [\"default\", \"loader\", \"action\"] }\n  ]\n}\n```",
  "type": "object",
  "properties": {
    "name": {
      "description": "Unique name for this plugin.",
      "type": "string"
    },
    "detection": {
      "description": "Rich detection logic (dependency checks, file existence, boolean combinators).\nTakes priority over `enablers` when set.",
      "anyOf": [
        {
          "$ref": "#/$defs/PluginDetection"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "enablers": {
      "description": "Package names that activate this plugin when found in package.json.\nSupports exact matches and prefix patterns (ending with `/`).\nOnly used when `detection` is not set.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": []
    },
    "entryPoints": {
      "description": "Glob patterns for entry point files.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": []
    },
    "entryPointRole": {
      "description": "Coverage role for `entryPoints`.\n\nDefaults to `support`. Set to `runtime` for application entry points\nor `test` for test framework entry points.",
      "$ref": "#/$defs/EntryPointRole",
      "default": "support"
    },
    "configPatterns": {
      "description": "Glob patterns for config files (marked as always-used when active).",
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": []
    },
    "alwaysUsed": {
      "description": "Files that are always considered \"used\" when this plugin is active.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": []
    },
    "toolingDependencies": {
      "description": "Dependencies that are tooling (used via CLI/config, not source imports).\nThese should not be flagged as unused devDependencies.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": []
    },
    "usedExports": {
      "description": "Exports that are always considered used for matching file patterns.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/ExternalUsedExport"
      },
      "default": []
    },
    "usedClassMembers": {
      "description": "Class member method/property rules the framework invokes at runtime.\nSupports plain member names for global suppression and scoped objects\nwith `extends` / `implements` constraints when the method name is too\ncommon to suppress across the whole workspace.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/UsedClassMemberRule"
      },
      "default": []
    }
  },
  "required": [
    "name"
  ],
  "$defs": {
    "PluginDetection": {
      "description": "How to detect if a plugin should be activated.\n\nWhen set on an `ExternalPluginDef`, this takes priority over `enablers`.\nSupports dependency checks, file existence checks, and boolean combinators.",
      "oneOf": [
        {
          "description": "Plugin detected if this package is in dependencies.",
          "type": "object",
          "properties": {
            "package": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "const": "dependency"
            }
          },
          "required": [
            "type",
            "package"
          ]
        },
        {
          "description": "Plugin detected if this file pattern matches.",
          "type": "object",
          "properties": {
            "pattern": {
              "type": "string"
            },
            "type": {
              "type": "string",
              "const": "fileExists"
            }
          },
          "required": [
            "type",
            "pattern"
          ]
        },
        {
          "description": "All conditions must be true.",
          "type": "object",
          "properties": {
            "conditions": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/PluginDetection"
              }
            },
            "type": {
              "type": "string",
              "const": "all"
            }
          },
          "required": [
            "type",
            "conditions"
          ]
        },
        {
          "description": "Any condition must be true.",
          "type": "object",
          "properties": {
            "conditions": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/PluginDetection"
              }
            },
            "type": {
              "type": "string",
              "const": "any"
            }
          },
          "required": [
            "type",
            "conditions"
          ]
        }
      ]
    },
    "EntryPointRole": {
      "description": "How a plugin's discovered entry points contribute to coverage reachability.",
      "oneOf": [
        {
          "description": "Runtime/application roots that should count toward runtime reachability.",
          "type": "string",
          "const": "runtime"
        },
        {
          "description": "Test roots that should count toward test reachability.",
          "type": "string",
          "const": "test"
        },
        {
          "description": "Support/setup/config roots that should keep files alive but not count as runtime/test.",
          "type": "string",
          "const": "support"
        }
      ]
    },
    "ExternalUsedExport": {
      "description": "Exports considered used for files matching a pattern.",
      "type": "object",
      "properties": {
        "pattern": {
          "description": "Glob pattern for files.",
          "type": "string"
        },
        "exports": {
          "description": "Export names always considered used.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "pattern",
        "exports"
      ]
    },
    "UsedClassMemberRule": {
      "description": "A `usedClassMembers` entry from config or an external plugin.\n\nSupports either a plain member name (`\"agInit\"`) or a scoped rule that\nonly applies when a class matches specific `extends` / `implements`\nheritage clauses.",
      "anyOf": [
        {
          "description": "Globally suppress this class member name for all classes.",
          "type": "string"
        },
        {
          "description": "Suppress these class member names only for matching classes.",
          "$ref": "#/$defs/ScopedUsedClassMemberRule"
        }
      ]
    },
    "ScopedUsedClassMemberRule": {
      "description": "A heritage-constrained `usedClassMembers` rule.",
      "type": "object",
      "properties": {
        "extends": {
          "description": "Only apply when the class extends this parent class name.",
          "type": [
            "string",
            "null"
          ]
        },
        "implements": {
          "description": "Only apply when the class implements this interface name.",
          "type": [
            "string",
            "null"
          ]
        },
        "members": {
          "description": "Member names that should be treated as framework-used.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false,
      "required": [
        "members"
      ]
    }
  }
}