feat: Design and implement a plugin API for third-party custom rules

[Nanle-code]

Overview

ChainProof's rule set is currently hardcoded in the core package. There is no mechanism for teams to ship custom detection rules specific to their protocol, internal coding standards, or proprietary vulnerability patterns. A first-class plugin API would transform ChainProof from a static tool into an extensible platform.

Use Cases

• A DeFi protocol wants to enforce that all price feeds must use their approved oracle wrapper
• A team wants to detect usage of deprecated internal library functions
• An auditing firm wants to bundle proprietary detection logic without upstreaming it
• A researcher wants to prototype and test a new rule before contributing it to core

Proposed Plugin API

// packages/core/src/types.ts — new types
export interface ChainProofPlugin {
  name: string;
  version: string;
  rules: PluginRule[];
}

export interface PluginRule {
  id: string;           // e.g. "MYTEAM-001"
  title: string;
  severity: Severity;
  description: string;
  detect: (ast: ASTNode, source: string, filePath: string) => Finding[];
}

Loading Mechanisms

1. Config file — .chainproofrc.json accepts a plugins array of npm package names or local paths:

{
  "plugins": [
    "@myteam/chainproof-rules",
    "./local-rules/my-custom-rule.js"
  ]
}

2. Programmatic API — scan() accepts a plugins array in ScanConfig
3. VS Code setting — chainproof.plugins array of paths/packages

Plugin Resolution

• npm packages resolved relative to process.cwd()
• Local paths resolved relative to config file location
• Plugin loading errors are non-fatal (warn + continue)
• Sandbox consideration: plugins run in the same process (document security implications)

Acceptance Criteria

• ChainProofPlugin and PluginRule types exported from @chainproof/core
• Plugin loading in scanner.ts before rule execution
• Config file plugins field supported in .chainproofrc.json
• ScanConfig.plugins?: ChainProofPlugin[] field added
• VS Code extension reads chainproof.plugins setting
• CLI --plugin <path> flag added
• Plugin authoring documentation in README
• Example plugin package in examples/plugins/
• Plugin load errors are non-fatal with clear warning messages