economics.check

{
  "type": "object",
  "additionalProperties": false,
  "description": "The input of `economics.check`: nothing to narrow; the check is over the repository.\nUnknown fields are refused rather than ignored, so a caller who tries to scope the check\nto a path learns that it cannot be scoped instead of reading a partial verdict as whole.\n\n```\nuse majordomus_cli::economics::claims::EconomicsCheckInput;\nlet input: EconomicsCheckInput = serde_json::from_str(\"{}\").unwrap();\nassert_eq!(input, EconomicsCheckInput::default());\nlet narrowed = serde_json::from_str::<EconomicsCheckInput>(r#\"{\"path\":\"docs\"}\"#);\nassert!(narrowed.is_err(), \"the check is over the whole repository\");\n```",
  "title": "EconomicsCheckInput"
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "No finding."
    },
    "scanned": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "Files scanned."
    },
    "claims_checked": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "Bound claims checked."
    },
    "findings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EconomicsFinding"
      },
      "description": "Every finding."
    }
  },
  "required": [
    "ok",
    "scanned",
    "claims_checked",
    "findings"
  ],
  "description": "The answer of `economics.check`, the same over the CLI, HTTP and MCP: how much was read\nand every refusal. `ok` is true exactly when `findings` is empty. `scanned` counts the\nhand-written files read, `docs/CLAIMS.yaml` included and generated files excluded;\n`claims_checked` counts the methodology's claim bindings, whatever their status.\n\n```\nuse majordomus_cli::economics::claims::{check, EconomicsCheckReport};\nlet dir = tempfile::tempdir().unwrap();\nlet git = std::process::Command::new(\"git\")\n    .env_remove(\"GIT_DIR\").env_remove(\"GIT_WORK_TREE\").env_remove(\"GIT_INDEX_FILE\")\n    .arg(\"-C\").arg(dir.path()).args([\"init\", \"-q\"]).status().unwrap();\nassert!(git.success());\nlet report: EconomicsCheckReport = check(dir.path());\nassert!(report.ok && report.findings.is_empty(), \"an empty repository claims nothing\");\nlet json = serde_json::to_value(&report).unwrap();\nassert_eq!(json[\"claims_checked\"], 0);\nassert_eq!(serde_json::from_value::<EconomicsCheckReport>(json).unwrap(), report);\n```",
  "title": "EconomicsCheckReport",
  "$defs": {
    "EconomicsFinding": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "description": "`unsupported_quantity`, `claim_unsupported`, `claim_unbound`, `claim_duplicate`,\n`declarations_unreadable`, `claims_unreadable` or `scan_failed`."
        },
        "path": {
          "type": "string",
          "description": "Repository-relative path."
        },
        "line": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint",
          "minimum": 0,
          "description": "1-based line, when the finding is about a line."
        },
        "detail": {
          "type": "string",
          "description": "What was found, and what to do about it."
        }
      },
      "required": [
        "kind",
        "path",
        "detail"
      ],
      "description": "One thing the check refuses. `detail` names the remedy, so a finding can be acted on\nwithout reading the methodology. A finding about a claim or a file rather than a line\ncarries no `line`, and its JSON omits the key. The kinds:\n\n- `unsupported_quantity`: a number typed into hand-written prose next to the economics\n  vocabulary.\n- `claim_unsupported`: a claim binding that does not hold — the bound claim is missing\n  from `docs/CLAIMS.yaml`, or it is `guaranteed` while its metric does not stand where\n  the binding says or its evidence is not current.\n- `claim_unbound`: a `guaranteed` claim says tokens, context or cost go down and no\n  binding ties it to a metric.\n- `claim_duplicate`: one claim id appears more than once in `docs/CLAIMS.yaml`.\n- `declarations_unreadable`: the benchmark declarations cannot be read, so no binding\n  can be shown to hold.\n- `claims_unreadable`: `docs/CLAIMS.yaml` exists and cannot be read or parsed.\n- `scan_failed`: the prose could not be listed or a file in it could not be read, so\n  nothing can be said to be clean.\n\n```\nuse majordomus_cli::economics::claims::EconomicsFinding;\nlet finding = EconomicsFinding {\n    kind: \"claim_unsupported\".into(),\n    path: \"docs/CLAIMS.yaml\".into(),\n    line: None,\n    detail: \"set the claim to planned, or record the evidence\".into(),\n};\nlet json = serde_json::to_value(&finding).unwrap();\nassert!(json.get(\"line\").is_none(), \"no line, no key\");\nassert_eq!(serde_json::from_value::<EconomicsFinding>(json).unwrap(), finding);\n```"
    }
  }
}