Description
Diff Guardian ships with 26 built-in classification rules (R01–R26) covering parameter removal, return type changes, visibility downgrades, etc. However, teams often have project-specific contracts that the built-in rules cannot express — for example, "every exported function must have a JSDoc @public tag" or "enum values must never be reordered." Adding support for user-defined custom rules in dg.config.json would let teams extend Diff Guardian without forking the codebase.
Steps to Reproduce
- Open
dg.config.json
- There is no
rules or customRules field to define additional classification logic
- A team that wants to flag "JSDoc tag removed" or "decorator removed" as breaking has no way to do so
Expected Behavior
dg.config.json should accept a customRules array:
{
"customRules": [
{
"id": "CUSTOM-01",
"name": "JSDoc @public tag removed",
"severity": "breaking",
"match": {
"type": "function",
"property": "jsdocTags",
"condition": "removed",
"value": "public"
}
}
]
}
- Custom rules should be evaluated after built-in rules
- Custom rule violations should appear in the terminal report and PR comment with a
[CUSTOM-01] prefix
npx dg rules should list both built-in and custom rules
Implementation Hints
Config Schema (src/config/):
- Extend the config type with
customRules?: CustomRule[]
- Define the
CustomRule interface with id, name, severity, and match conditions
Classifier Engine (src/classifier/):
- After running built-in rules, iterate over
customRules and evaluate each match condition against the diff
- Map the
match.condition to an AST diff predicate (e.g., removed checks if the property existed in base but not head)
Reporter (src/reporters/):
- Prefix custom rule IDs in the output so they are visually distinct from built-in rules
Affected Files
src/config/schema.ts
src/classifier/engine.ts
src/reporters/terminalReporter.ts
src/reporters/githubReporter.ts
dg.config.json (schema update)
Labels
type:feature, level:advanced
Description
Diff Guardian ships with 26 built-in classification rules (R01–R26) covering parameter removal, return type changes, visibility downgrades, etc. However, teams often have project-specific contracts that the built-in rules cannot express — for example, "every exported function must have a JSDoc @public tag" or "enum values must never be reordered." Adding support for user-defined custom rules in
dg.config.jsonwould let teams extend Diff Guardian without forking the codebase.Steps to Reproduce
dg.config.jsonrulesorcustomRulesfield to define additional classification logicExpected Behavior
dg.config.jsonshould accept acustomRulesarray:{ "customRules": [ { "id": "CUSTOM-01", "name": "JSDoc @public tag removed", "severity": "breaking", "match": { "type": "function", "property": "jsdocTags", "condition": "removed", "value": "public" } } ] }[CUSTOM-01]prefixnpx dg rulesshould list both built-in and custom rulesImplementation Hints
Config Schema (
src/config/):customRules?: CustomRule[]CustomRuleinterface withid,name,severity, andmatchconditionsClassifier Engine (
src/classifier/):customRulesand evaluate each match condition against the diffmatch.conditionto an AST diff predicate (e.g.,removedchecks if the property existed in base but not head)Reporter (
src/reporters/):Affected Files
src/config/schema.tssrc/classifier/engine.tssrc/reporters/terminalReporter.tssrc/reporters/githubReporter.tsdg.config.json(schema update)Labels
type:feature,level:advanced