csv-surgeon

CSV Surgeon — profile a CSV and find the rows that will break something.

profile   per-column type, null rate, cardinality, min/max, sample values
issues    ragged rows, duplicate headers, mixed types, whitespace-padded keys
dupes     duplicate records, by whole row or by chosen key columns
slice     head/tail/filter rows without loading the file into a spreadsheet

Pure stdlib csv, no pandas, no network, no credentials.

WHY IT LEADS WITH NULL RATE AND CARDINALITY

Those two numbers explain most CSV surprises. A column that is 40% empty will break a join you thought was safe. A column with cardinality 1 is a constant someone forgot to remove. A column with cardinality == row count is an id, and joining on anything else is probably a mistake. None of that is visible by looking at the first ten rows, which is what everyone does.

WHY RAGGED ROWS GET THEIR OWN CHECK

A row with the wrong number of fields is the single most common CSV defect, and most tools silently pad or truncate it. The data then looks fine and is wrong. This reports the row number so you can go and look at it.

WHY WHITESPACE IN HEADERS IS A FINDING

"name" and "name " are different keys in every downstream consumer, and the difference is invisible in every viewer. It produces bugs that read as impossible.

Parameters

The typed contract this capability answers to (JSON Schema — the deterministic layer):

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "profile",
        "issues",
        "dupes",
        "slice"
      ],
      "description": "What to do."
    },
    "path": {
      "type": "string",
      "description": "Path to the .csv file."
    },
    "keys": {
      "type": "string",
      "description": "For dupes: comma-separated column names to match on. Default: the whole row."
    },
    "limit": {
      "type": "integer",
      "description": "For slice: how many rows. Default 10."
    }
  },
  "required": [
    "action",
    "path"
  ]
}