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"
    },
    "manifestEntries": {
      "description": "Entry points DERIVED from framework manifest files.\n\nUnlike `entryPoints` (static globs), each rule finds manifest files by a\nrecursive glob, parses them, and seeds sibling entries resolved relative\nto each manifest's directory, gated on the manifest's own fields. Seeded\nentries use this plugin's `entryPointRole`.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/ManifestEntryRule"
      },
      "default": []
    },
    "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"
        }
      ]
    },
    "ManifestEntryRule": {
      "description": "A rule that seeds entry points DERIVED from framework manifest files.\n\nFor every file matching `manifests` (a recursive glob) that passes the\nmanifest-level `when` gate, each rule in `entries` is resolved relative to\nthe manifest's directory (with `${dotted.field}` interpolation) into an entry\npoint. Seeded entries use the owning plugin's `entryPointRole`.\n\n```jsonc\n{\n  \"manifests\": \"**/kibana.jsonc\",\n  \"when\": { \"type\": \"plugin\" },\n  \"entries\": [\n    { \"path\": \"public/index.{ts,tsx}\", \"when\": { \"plugin.browser\": true } },\n    { \"path\": \"server/index.{ts,tsx}\", \"when\": { \"plugin.server\": true } },\n    { \"path\": \"${plugin.extraPublicDirs}/index.{ts,tsx}\" }\n  ]\n}\n```",
      "type": "object",
      "properties": {
        "manifests": {
          "description": "Recursive glob selecting the manifest files to read (e.g. `**/kibana.jsonc`).",
          "type": "string"
        },
        "format": {
          "description": "Manifest format. Defaults to `jsonc` (which also parses plain JSON).",
          "$ref": "#/$defs/ManifestFormat",
          "default": "jsonc"
        },
        "when": {
          "description": "Manifest-level gate: a map of dotted field path to an expected scalar\nvalue. ALL entries must match by STRICT EQUALITY for the manifest to be\nprocessed. An empty map matches every manifest.",
          "type": "object",
          "additionalProperties": true,
          "default": {}
        },
        "entries": {
          "description": "Entry rules seeded per matching manifest.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/ManifestSeedRule"
          }
        }
      },
      "required": [
        "manifests",
        "entries"
      ]
    },
    "ManifestFormat": {
      "description": "Format of the manifest files a [`ManifestEntryRule`] reads.\n\n`jsonc` (the default) also parses plain JSON, so it is the tolerant choice.",
      "oneOf": [
        {
          "description": "JSONC (comments + trailing commas). Also accepts plain JSON.",
          "type": "string",
          "const": "jsonc"
        },
        {
          "description": "Strict JSON.",
          "type": "string",
          "const": "json"
        }
      ]
    },
    "ManifestSeedRule": {
      "description": "A single entry seeded by a [`ManifestEntryRule`], resolved relative to the\nmanifest's directory.",
      "type": "object",
      "properties": {
        "path": {
          "description": "Entry glob relative to the manifest directory. May contain\n`${dotted.field}` interpolation that fans out over string / array\nmanifest field values (a missing or empty field seeds nothing). The glob\nmust encode its own extension (e.g. `public/index.{ts,tsx}`); glob entry\npatterns are matched literally against discovered files without\nsource-extension probing.",
          "type": "string"
        },
        "when": {
          "description": "Per-entry gate (strict equality), evaluated against the same manifest.\nAn empty map always passes.",
          "type": "object",
          "additionalProperties": true,
          "default": {}
        }
      },
      "required": [
        "path"
      ]
    },
    "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 or glob pattern (`\"agInit\"`,\n`\"enter*\"`) or a scoped rule that only applies when a class matches\nspecific `extends` / `implements` heritage clauses.",
      "anyOf": [
        {
          "description": "Globally suppress this class member name or glob pattern 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 or glob patterns that should be treated as framework-used.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false,
      "required": [
        "members"
      ]
    }
  }
}