// standard-deduction-vs-itemized.cjs -- METHOD DECK (X063).
// Per the Founder rule via W001/PQ021, the standard deduction amount is a value that changes
// every year, so it is now a typed input (standard_deduction) with companion
// standard_deduction_source and standard_deduction_date inputs, instead of a table keyed by
// filing_status baked into run(). filing_status is kept only to word the question and answer
// naturally; the actual comparison uses whatever standard_deduction the visitor supplies.
module.exports = {
  slug: "standard-deduction-vs-itemized",
  title: "Standard deduction vs. itemized, at a stated deduction amount",
  deck_category: "tax",
  description: "Compares a stated, cited standard deduction amount against a given itemized deduction total and reports which is larger.",
  inputs: [
    { name: "filing_status", type: "string", required: true, description: "Filing status, used only to word the question and answer", enum: ["single", "married_filing_jointly", "head_of_household"] },
    { name: "itemized_total", type: "number", unit: "currency units", required: true, description: "Sum of all itemized deductions", min: 0 },
    { name: "standard_deduction", type: "number", unit: "currency units", required: true, description: "The standard deduction amount for this filing status and tax year; the visitor may enter a newer year's published figure.", min: 0 },
    { name: "standard_deduction_source", type: "string", required: true, description: "Citation for the standard_deduction figure (for example the IRS revenue procedure); change it together with standard_deduction when using a newer year." },
    { name: "standard_deduction_date", type: "string", unit: "ISO date", required: true, description: "The date the cited standard_deduction figure was retrieved or published." }
  ],
  outputs: [
    { name: "standard_deduction", unit: "currency units", description: "The stated standard deduction for this filing status" },
    { name: "larger_amount", unit: "currency units", description: "The larger of the standard deduction and the itemized total" },
    { name: "which_is_larger", description: "Either 'standard' or 'itemized'" }
  ],
  steps: [
    "The visitor supplies standard_deduction for their filing status, plus standard_deduction_source and standard_deduction_date, the citation for that figure; this method never looks up a table itself.",
    "Compare standard_deduction to itemized_total.",
    "which_is_larger = 'itemized' if itemized_total > standard_deduction, otherwise 'standard'.",
    "larger_amount = the greater of the two values, rounded to 2 decimals (money to cents)."
  ],
  constants: [
    { name: "standard_deduction_single_2026", value: 16100, unit: "currency units", source: 0 },
    { name: "standard_deduction_mfj_2026", value: 32200, unit: "currency units", source: 0 },
    { name: "standard_deduction_hoh_2026", value: 24150, unit: "currency units", source: 0 }
  ],
  sources: [
    { kind: "url", value: "https://www.irs.gov/pub/irs-drop/rp-25-32.pdf", title: "Rev. Proc. 2025-32, Section 4.14 (2026 Standard Deduction)", publisher: "Internal Revenue Service", retrieved_utc: "2026-09-30T19:31:29Z", note: "Official 2026 tax year standard deduction amounts: $32,200 MFJ, $24,150 HoH, $16,100 single/MFS; documented source of the standard_deduction_source/standard_deduction_date default values prefilled below by filing status." }
  ],
  disclaimer: "General comparison only, using a stated, cited standard deduction. Not tax advice. Itemized deduction eligibility rules (SALT cap, mortgage interest limits, etc.) are not evaluated here. Consult a licensed tax professional or the IRS for your actual return.",
  questionText(inputs) {
    const statusText = { single: "single", married_filing_jointly: "married filing jointly", head_of_household: "head of household" }[inputs.filing_status];
    return `For a ${statusText} filer with $${inputs.itemized_total} of itemized deductions and a standard deduction of $${inputs.standard_deduction} (${inputs.standard_deduction_source}, dated ${inputs.standard_deduction_date}), is the standard deduction or itemizing larger, and by how much?`;
  },
  run(inputs) {
    const { filing_status, itemized_total, standard_deduction, standard_deduction_source, standard_deduction_date } = inputs;
    if (!["single", "married_filing_jointly", "head_of_household"].includes(filing_status)) throw new Error("filing_status must be one of: single, married_filing_jointly, head_of_household");
    if (typeof itemized_total !== "number" || itemized_total < 0) throw new Error("itemized_total must be a non-negative number");
    if (typeof standard_deduction !== "number" || standard_deduction < 0) throw new Error("standard_deduction must be a non-negative number");
    if (typeof standard_deduction_source !== "string" || !standard_deduction_source.trim()) throw new Error("standard_deduction_source must be a non-empty string");
    if (typeof standard_deduction_date !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(standard_deduction_date)) throw new Error("standard_deduction_date must be a string in YYYY-MM-DD format");
    const which_is_larger = itemized_total > standard_deduction ? "itemized" : "standard";
    const larger_amount = Math.round(Math.max(standard_deduction, itemized_total) * 100) / 100;
    const fmt = (n) => n.toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
    return {
      answer: `${which_is_larger === "itemized" ? "Itemizing" : "The standard deduction"} is larger at $${fmt(larger_amount)}`,
      values: { standard_deduction, larger_amount, which_is_larger }
    };
  },
  examples: [
    {
      name: "worked example",
      inputs: { filing_status: "single", itemized_total: 20000, standard_deduction: 16100, standard_deduction_source: "IRS Rev. Proc. 2025-32, Section 4.14", standard_deduction_date: "2026-09-30" },
      expected: { answer: "Itemizing is larger at $20,000.00" },
      check: "hand computation: 2026 single standard deduction is 16100; 20000 > 16100, so itemized wins at 20000.00"
    },
    {
      name: "test vector: standard deduction wins",
      inputs: { filing_status: "married_filing_jointly", itemized_total: 18000, standard_deduction: 32200, standard_deduction_source: "IRS Rev. Proc. 2025-32, Section 4.14", standard_deduction_date: "2026-09-30" },
      expected: { answer: "The standard deduction is larger at $32,200.00" },
      check: "hand computation: 2026 MFJ standard deduction is 32200; 18000 < 32200, so the standard deduction wins at 32200.00"
    }
  ]
};