moult 0.1.0

data/schema/deadcode.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/moult-rb/moult-rb/blob/main/schema/deadcode.schema.json",
+  "title": "Moult dead-code report",
+  "description": "Typed output contract for `moult deadcode`. One of Moult's two protected APIs. Every finding is a confidence-graded candidate carrying its reasons; nothing here asserts that code is certainly dead.",
+  "type": "object",
+  "required": ["schema_version", "tool", "analysis", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "description": "Bumped only on a breaking change to this shape. v2 adds the runtime block (analysis.coverage provenance and a per-finding runtime field).",
+      "type": "integer",
+      "const": 2
+    },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string"},
+        "version": {"type": "string"}
+      }
+    },
+    "analysis": {
+      "type": "object",
+      "required": ["root", "git_ref", "generated_at", "coverage", "index"],
+      "additionalProperties": false,
+      "properties": {
+        "root": {"type": "string"},
+        "git_ref": {"type": ["string", "null"]},
+        "generated_at": {"type": ["string", "null"], "format": "date-time"},
+        "coverage": {
+          "description": "Provenance of merged runtime coverage (--coverage). Null when none was merged.",
+          "$ref": "common.schema.json#/$defs/coverage_source"
+        },
+        "index": {
+          "type": "object",
+          "required": ["backend", "backend_version", "resolved", "rails", "diagnostics"],
+          "additionalProperties": false,
+          "properties": {
+            "backend": {"type": "string"},
+            "backend_version": {"type": ["string", "null"]},
+            "resolved": {"type": "boolean"},
+            "rails": {"description": "Whether Rails entrypoint awareness was applied.", "type": "boolean"},
+            "diagnostics": {"type": "array", "items": {"type": "string"}}
+          }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/finding"}
+    }
+  },
+  "$defs": {
+    "reason": {
+      "description": "One auditable contribution to a finding's confidence.",
+      "type": "object",
+      "required": ["rule", "delta", "detail"],
+      "additionalProperties": false,
+      "properties": {
+        "rule": {"type": "string"},
+        "delta": {"description": "Signed adjustment this rule applied.", "type": "number"},
+        "detail": {"type": "string"}
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": ["symbol_id", "kind", "name", "span", "confidence", "category", "runtime", "reasons"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol_id": {
+          "description": "Stable join key shared with the hotspots contract: \"<path>:<start_line>:<fqname>\".",
+          "type": "string"
+        },
+        "kind": {
+          "description": "What sort of definition this candidate is.",
+          "type": "string",
+          "enum": ["method", "constant"]
+        },
+        "name": {
+          "description": "Fully-qualified lexical name (Class#method or Class.method).",
+          "type": "string"
+        },
+        "span": {"$ref": "common.schema.json#/$defs/span"},
+        "confidence": {
+          "description": "Likelihood the candidate is actually dead, in [0, 1]. Never an assertion of certain death.",
+          "$ref": "common.schema.json#/$defs/unit_interval"
+        },
+        "category": {
+          "description": "Always \"dead_code\" in this contract.",
+          "type": "string"
+        },
+        "runtime": {
+          "description": "Runtime coverage classification merged from --coverage; null when no coverage was supplied. A runtime_cold/runtime_hot entry in reasons records its effect on the confidence.",
+          "$ref": "common.schema.json#/$defs/runtime"
+        },
+        "reasons": {
+          "description": "The factors that raised or lowered the confidence, in application order.",
+          "type": "array",
+          "items": {"$ref": "#/$defs/reason"}
+        }
+      }
+    }
+  }
+}

data/schema/duplication.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/moult-rb/moult-rb/blob/main/schema/duplication.schema.json",
+  "title": "Moult duplication report",
+  "description": "Typed output contract for `moult duplication`. One of Moult's two protected APIs. Every finding is a confidence-graded clone group carrying its reasons; nothing here asserts that duplication is certainly removable.",
+  "type": "object",
+  "required": ["schema_version", "tool", "analysis", "summary", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "description": "Bumped only on a breaking change to this shape.",
+      "type": "integer",
+      "const": 1
+    },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string"},
+        "version": {"type": "string"}
+      }
+    },
+    "analysis": {
+      "type": "object",
+      "required": ["root", "git_ref", "generated_at", "detector"],
+      "additionalProperties": false,
+      "properties": {
+        "root": {"type": "string"},
+        "git_ref": {"type": ["string", "null"]},
+        "generated_at": {"type": ["string", "null"], "format": "date-time"},
+        "detector": {
+          "type": "object",
+          "required": ["backend", "backend_version", "min_mass", "fuzzy"],
+          "additionalProperties": false,
+          "properties": {
+            "backend": {"description": "Clone-detection backend, e.g. \"flay\".", "type": "string"},
+            "backend_version": {"type": ["string", "null"]},
+            "min_mass": {"description": "Mass threshold below which fragments were ignored.", "type": "integer", "minimum": 0},
+            "fuzzy": {"description": "Whether near-matches (not just structural-equivalents) were included.", "type": "boolean"}
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["sets", "occurrences", "total_mass"],
+      "additionalProperties": false,
+      "properties": {
+        "sets": {"description": "Number of clone groups.", "type": "integer", "minimum": 0},
+        "occurrences": {"description": "Total sites across all groups.", "type": "integer", "minimum": 0},
+        "total_mass": {"type": "integer", "minimum": 0}
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/finding"}
+    }
+  },
+  "$defs": {
+    "reason": {
+      "description": "One auditable contribution to a finding's confidence.",
+      "type": "object",
+      "required": ["rule", "delta", "detail"],
+      "additionalProperties": false,
+      "properties": {
+        "rule": {"type": "string"},
+        "delta": {"description": "Signed adjustment this rule applied.", "type": "number"},
+        "detail": {"type": "string"}
+      }
+    },
+    "occurrence": {
+      "description": "One site of a clone group.",
+      "type": "object",
+      "required": ["symbol_id", "path", "line", "fuzzy"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol_id": {
+          "description": "Best-effort enclosing-method join key (\"<path>:<start_line>:<fqname>\"), shared with the hotspots/deadcode contracts. Null when the fragment is not inside a known method (top-level code, or a duplicated whole class).",
+          "type": ["string", "null"]
+        },
+        "path": {"type": "string"},
+        "line": {"description": "Clone start line (flay reports line granularity).", "type": "integer", "minimum": 1},
+        "fuzzy": {"description": "True only for a near-match site surfaced in fuzzy mode.", "type": "boolean"}
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": ["category", "confidence", "kind", "node_type", "mass", "reasons", "occurrences"],
+      "additionalProperties": false,
+      "properties": {
+        "category": {
+          "description": "Always \"duplication\" in this contract.",
+          "type": "string"
+        },
+        "confidence": {
+          "description": "Likelihood this is genuine, consolidatable duplication, in [0, 1]. Never an assertion of certainty.",
+          "$ref": "common.schema.json#/$defs/unit_interval"
+        },
+        "kind": {
+          "description": "identical=byte-for-byte match; similar=same structure, differing names/literals.",
+          "type": "string",
+          "enum": ["identical", "similar"]
+        },
+        "node_type": {
+          "description": "The duplicated AST node's type (flay sexp type, e.g. \"defn\", \"call\", \"class\").",
+          "type": "string"
+        },
+        "mass": {
+          "description": "flay's structural mass of the duplicated node.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "reasons": {
+          "description": "The factors that raised or lowered the confidence, in application order.",
+          "type": "array",
+          "items": {"$ref": "#/$defs/reason"}
+        },
+        "occurrences": {
+          "description": "The sites of this clone group; a group has at least two.",
+          "type": "array",
+          "minItems": 2,
+          "items": {"$ref": "#/$defs/occurrence"}
+        }
+      }
+    }
+  }
+}

data/schema/flags.schema.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/moult-rb/moult-rb/blob/main/schema/flags.schema.json",
+  "title": "Moult feature-flags report",
+  "description": "Typed output contract for `moult flags`. One of Moult's two protected APIs. Each finding is one feature-flag key found by a static Prism scan of the OpenFeature client surface (provider-agnostic). Without --provider a flag reference is a recorded fact: confidence is null and the value_type/reference_count/default_values classification carries the signal (schema_version 1). With --provider a LOCAL provider snapshot (e.g. a flagd flag-definition export) is joined on the literal flag_key and each finding additionally carries a confidence-graded staleness candidate (status + confidence + reasons) and the report an analysis.provider provenance block (schema_version 2). The bump is additive: without a snapshot the output is byte-for-byte identical to v1. The snapshot is evidence (archived / fully rolled out / absent), never proof - nothing here asserts a flag is certainly stale, dead, or unused.",
+  "type": "object",
+  "required": ["schema_version", "tool", "analysis", "summary", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "description": "1 without a provider snapshot (usage only); 2 when --provider merges staleness candidates. The two share one additive shape: the v2-only blocks (analysis.provider, per-finding staleness, summary.by_staleness_status) are absent at v1.",
+      "type": "integer",
+      "enum": [1, 2]
+    },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string"},
+        "version": {"type": "string"}
+      }
+    },
+    "analysis": {
+      "type": "object",
+      "required": ["root", "git_ref", "generated_at", "scanner"],
+      "additionalProperties": false,
+      "properties": {
+        "root": {"type": "string"},
+        "git_ref": {"type": ["string", "null"]},
+        "generated_at": {"type": ["string", "null"], "format": "date-time"},
+        "provider": {
+          "description": "Provenance of a merged provider snapshot (--provider). Present only at schema_version 2; absent (the whole key omitted) without a snapshot.",
+          "$ref": "common.schema.json#/$defs/provider_source"
+        },
+        "scanner": {
+          "description": "Provenance of the static scan. This slice ingests no external tool output; it scans a client surface (the swap point for a future SDK/standard).",
+          "type": "object",
+          "required": ["target", "sdk_gem", "client_builder"],
+          "additionalProperties": false,
+          "properties": {
+            "target": {"description": "The flag standard scanned, e.g. \"openfeature\".", "type": "string"},
+            "sdk_gem": {"description": "The SDK gem whose call shape is detected (never a runtime dependency).", "type": "string"},
+            "client_builder": {"description": "The client constructor recognised, e.g. \"OpenFeature::SDK.build_client\".", "type": "string"}
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["flags", "references", "dynamic_references", "by_value_type"],
+      "additionalProperties": false,
+      "properties": {
+        "flags": {"description": "Number of distinct literal flag keys catalogued.", "type": "integer", "minimum": 0},
+        "references": {"description": "Total catalogued reference sites across all flags.", "type": "integer", "minimum": 0},
+        "dynamic_references": {"description": "Flag-evaluation calls whose key was not a literal (counted, not catalogued; a static scan cannot resolve the key).", "type": "integer", "minimum": 0},
+        "by_value_type": {"description": "Reference count keyed by value_type.", "type": "object", "additionalProperties": {"type": "integer", "minimum": 0}},
+        "by_staleness_status": {"description": "Flag count keyed by staleness status. Present only at schema_version 2 (--provider).", "type": "object", "additionalProperties": {"type": "integer", "minimum": 0}}
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/finding"}
+    }
+  },
+  "$defs": {
+    "reason": {
+      "description": "One auditable note behind a finding's classification.",
+      "type": "object",
+      "required": ["rule", "detail"],
+      "additionalProperties": false,
+      "properties": {
+        "rule": {"type": "string"},
+        "detail": {"type": "string"}
+      }
+    },
+    "occurrence": {
+      "description": "One reference site of a flag.",
+      "type": "object",
+      "required": ["symbol_id", "path", "line", "method"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol_id": {
+          "description": "Best-effort enclosing-method join key (\"<path>:<start_line>:<fqname>\"), shared with the other contracts. Null for a top-level reference (outside any method).",
+          "type": ["string", "null"]
+        },
+        "path": {"description": "Root-relative referencing file path; the health files[] join key.", "type": "string"},
+        "line": {"description": "Call-site line (1-based).", "type": "integer", "minimum": 1},
+        "method": {"description": "The OpenFeature fetch method used at the site, e.g. \"fetch_boolean_value\" or \"fetch_string_details\". A plain string: the contract does not enumerate SDK method names.", "type": "string"}
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": ["category", "confidence", "flag_key", "value_type", "reference_count", "default_values", "reasons", "occurrences"],
+      "additionalProperties": false,
+      "properties": {
+        "category": {
+          "description": "Always \"feature_flag\" in this contract.",
+          "type": "string",
+          "const": "feature_flag"
+        },
+        "confidence": {
+          "description": "Null at schema_version 1 (a flag reference is a recorded fact, not a probabilistic candidate). At schema_version 2 it carries the staleness candidate's confidence (== staleness.confidence): the reserved per-finding confidence slot's first real use in this contract. Still a confidence in [0, 1], never a certainty.",
+          "$ref": "common.schema.json#/$defs/confidence"
+        },
+        "flag_key": {"description": "The literal flag key passed as flag_key:.", "type": "string"},
+        "value_type": {
+          "description": "The flag's value type, read from the fetch_<type>_* method. integer/float collapse to number; unknown means the flag was referenced with more than one type. A classification of recorded usage, never an assertion the flag is wrong.",
+          "type": "string",
+          "enum": ["boolean", "string", "number", "object", "unknown"]
+        },
+        "reference_count": {"description": "Number of catalogued reference sites (equals occurrences length).", "type": "integer", "minimum": 1},
+        "default_values": {
+          "description": "Distinct literal default values observed across the sites (string-rendered, sorted). Empty when no default was a literal.",
+          "type": "array",
+          "items": {"type": "string"}
+        },
+        "reasons": {
+          "description": "The notes behind the classification.",
+          "type": "array",
+          "items": {"$ref": "#/$defs/reason"}
+        },
+        "occurrences": {
+          "description": "The reference sites of this flag; at least one.",
+          "type": "array",
+          "minItems": 1,
+          "items": {"$ref": "#/$defs/occurrence"}
+        },
+        "staleness": {
+          "description": "A confidence-graded staleness candidate from the joined provider snapshot. Present only at schema_version 2 (--provider); the whole key is omitted without a snapshot. Evidence, never a claim of certain death.",
+          "$ref": "#/$defs/staleness"
+        }
+      }
+    },
+    "staleness": {
+      "description": "The staleness judgement for a flag, joined from the provider snapshot on flag_key. status records the observed lifecycle (archived/disabled/rolled_out/active) or absent (referenced in code, unknown to the provider); confidence grades how strong a removal candidate it is; reasons audit the call. active carries confidence 0.0 (not a removal candidate). Nothing here asserts certain death.",
+      "type": "object",
+      "required": ["status", "confidence", "reasons"],
+      "additionalProperties": false,
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["archived", "absent", "disabled", "rolled_out", "active"]
+        },
+        "confidence": {
+          "description": "Removal-candidate strength in [0, 1]. A confidence, never a certainty.",
+          "$ref": "common.schema.json#/$defs/unit_interval"
+        },
+        "reasons": {
+          "description": "The notes behind the staleness judgement.",
+          "type": "array",
+          "items": {"$ref": "#/$defs/reason"}
+        }
+      }
+    }
+  }
+}

data/schema/gate.schema.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/moult-rb/moult-rb/blob/main/schema/gate.schema.json",
+  "title": "Moult PR risk gate report",
+  "description": "Typed output contract for `moult gate`, the diff-aware PR risk gate. This is the ONLY Moult contract that renders a verdict: it consumes the confidence-graded / classified SIGNALS the other analyses emit (none of which carry pass/fail), scopes them to the changed lines/files (Clean as You Code), and applies an explicit, recorded policy. The verdict is an auditable application of that policy over confidence-graded candidates -- never a claim that code is certainly wrong or dead. No signal contract carries a verdict; it lives only here.",
+  "type": "object",
+  "required": ["schema_version", "tool", "analysis", "policy", "verdict", "reasons", "summary", "rules"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "description": "Bumped only on a breaking change to this shape.",
+      "type": "integer",
+      "const": 1
+    },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string"},
+        "version": {"type": "string"}
+      }
+    },
+    "analysis": {
+      "type": "object",
+      "required": ["root", "git_ref", "generated_at", "base_ref", "merge_base", "scope", "components"],
+      "additionalProperties": false,
+      "properties": {
+        "root": {"type": "string"},
+        "git_ref": {"type": ["string", "null"]},
+        "generated_at": {"type": ["string", "null"], "format": "date-time"},
+        "base_ref": {
+          "description": "The requested base ref the diff is taken against (e.g. \"origin/main\"). Null under scope \"all\".",
+          "type": ["string", "null"]
+        },
+        "merge_base": {
+          "description": "The resolved merge-base sha between base_ref and HEAD -- the \"new code\" boundary. Null under scope \"all\".",
+          "type": ["string", "null"]
+        },
+        "scope": {
+          "description": "\"diff\" gates only findings intersecting the changed lines/files; \"all\" gates the whole codebase.",
+          "type": "string",
+          "enum": ["diff", "all"]
+        },
+        "components": {
+          "description": "Provenance: which signal analyses the gate composed, and which were skipped (errored or not applicable). Mirrors the health composer discipline.",
+          "type": "array",
+          "items": {"$ref": "#/$defs/component"}
+        }
+      }
+    },
+    "policy": {
+      "description": "Every threshold that was applied, recorded in full so the verdict is reproducible and auditable.",
+      "type": "object",
+      "required": ["source", "dead_code_max_confidence", "boundary_max_severity", "complexity_ceiling", "duplication_max_mass", "exclude_paths"],
+      "additionalProperties": false,
+      "properties": {
+        "source": {"description": "\"default\" or the config file the overrides came from.", "type": "string"},
+        "dead_code_max_confidence": {"$ref": "common.schema.json#/$defs/unit_interval"},
+        "boundary_max_severity": {"type": "string", "enum": ["low", "medium", "high"]},
+        "complexity_ceiling": {"type": "number", "minimum": 0},
+        "duplication_max_mass": {"type": "number", "minimum": 0},
+        "exclude_paths": {
+          "description": "Root-relative path prefixes dropped from gating (e.g. test/spec). The gate judges production code; override to [] to gate everything.",
+          "type": "array",
+          "items": {"type": "string"}
+        }
+      }
+    },
+    "verdict": {
+      "description": "The single top-level outcome. The only pass/fail in any Moult contract.",
+      "type": "string",
+      "enum": ["pass", "fail"]
+    },
+    "reasons": {
+      "description": "Why the verdict came out the way it did.",
+      "type": "array",
+      "items": {"$ref": "#/$defs/reason"}
+    },
+    "summary": {
+      "type": "object",
+      "required": ["rules", "evaluated", "failed", "findings"],
+      "additionalProperties": false,
+      "properties": {
+        "rules": {"description": "Total policy rules.", "type": "integer", "minimum": 0},
+        "evaluated": {"description": "Rules whose backing analysis ran.", "type": "integer", "minimum": 0},
+        "failed": {"description": "Evaluated rules that the changes violated.", "type": "integer", "minimum": 0},
+        "findings": {"description": "Total contributing findings across failed rules.", "type": "integer", "minimum": 0}
+      }
+    },
+    "rules": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/rule"}
+    }
+  },
+  "$defs": {
+    "reason": {
+      "description": "One auditable note behind the verdict or a rule outcome.",
+      "type": "object",
+      "required": ["rule", "detail"],
+      "additionalProperties": false,
+      "properties": {
+        "rule": {"type": "string"},
+        "detail": {"type": "string"}
+      }
+    },
+    "component": {
+      "type": "object",
+      "required": ["name", "present", "diagnostic"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string"},
+        "present": {"description": "Whether this analysis contributed observations.", "type": "boolean"},
+        "diagnostic": {"description": "Why it was skipped, when absent; null when present.", "type": ["string", "null"]}
+      }
+    },
+    "contribution": {
+      "description": "One finding that contributed to a rule outcome. Stays a confidence-graded / classified candidate: `value` is the observed signal, never an assertion of certainty.",
+      "type": "object",
+      "required": ["category", "path", "symbol_id", "line", "value"],
+      "additionalProperties": false,
+      "properties": {
+        "category": {"$ref": "common.schema.json#/$defs/category"},
+        "path": {"description": "Root-relative file path.", "type": "string"},
+        "symbol_id": {
+          "description": "Method-level join key (\"<path>:<start_line>:<fqname>\"), shared with the other contracts. Null where the finding is file-keyed (boundaries) or outside any method.",
+          "type": ["string", "null"]
+        },
+        "line": {"description": "1-based line of the finding, when known; null for file-keyed findings.", "type": ["integer", "null"], "minimum": 1},
+        "value": {
+          "description": "The observed signal that tripped the rule (a confidence, an ABC score, a clone mass, or a severity). A graded/classified value, never a certainty.",
+          "type": ["number", "string", "null"]
+        }
+      }
+    },
+    "rule": {
+      "description": "One policy rule's outcome over the scoped changes.",
+      "type": "object",
+      "required": ["rule", "evaluated", "observed", "threshold", "passed", "reasons", "findings"],
+      "additionalProperties": false,
+      "properties": {
+        "rule": {
+          "type": "string",
+          "enum": ["no_new_dead_code", "no_new_high_severity_boundary", "new_code_complexity_ceiling", "new_code_duplication_ceiling"]
+        },
+        "evaluated": {"description": "False when the backing analysis didn't run; such a rule never fails the gate.", "type": "boolean"},
+        "observed": {
+          "description": "The worst observed value among scoped findings for this rule (max confidence/ABC/mass, or highest severity). Null when not evaluated or nothing was observed.",
+          "type": ["number", "string", "null"]
+        },
+        "threshold": {"description": "The applied threshold, rendered as a comparison (e.g. \"< 0.8\", \"<= medium\").", "type": "string"},
+        "passed": {"description": "Whether the changes satisfied the rule. Null when not evaluated.", "type": ["boolean", "null"]},
+        "reasons": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/reason"}
+        },
+        "findings": {
+          "description": "The contributing findings (empty when the rule passed or was skipped).",
+          "type": "array",
+          "items": {"$ref": "#/$defs/contribution"}
+        }
+      }
+    }
+  }
+}