{
  "$schema": "../cases.schema.json",
  "format": 1,
  "domain": "passport",
  "title": {
    "en": "Passport",
    "pt-BR": "Passaporte"
  },
  "functions": [
    {
      "id": "passport.format",
      "level": "extended",
      "summary": "Formats a Brazilian passport number for display.",
      "description": "Formats a passport number: upper-cased, without symbols, capped at 8 characters (the same operation as `passport.parse`).\n\n- Pending decision (findings §1b, §2 #8): the reference (JS) upper-cases lowercase and masked input. Erlang and Python accept only the strict uppercase form.\n- It is an alias of `passport.parse`: it does not check the number, so a partial value (`AB12`) is formatted as it is.\n- A value that is not a string (for example a number) returns an empty string: a number is never a passport number, since the series is two letters.",
      "params": [
        {
          "name": "passport",
          "type": "string"
        }
      ],
      "returns": "string",
      "cases": [
        {
          "id": "passport.format#[\"AB123456\"]",
          "args": [
            "AB123456"
          ],
          "expect": {
            "returns": "AB123456"
          }
        },
        {
          "id": "passport.format#lowercase",
          "args": [
            "acd12736"
          ],
          "expect": {
            "returns": "ACD12736"
          }
        },
        {
          "id": "passport.format#strips-symbols",
          "args": [
            "AB-123.456"
          ],
          "expect": {
            "returns": "AB123456"
          }
        },
        {
          "id": "passport.format#partial",
          "args": [
            "AB12"
          ],
          "expect": {
            "returns": "AB12"
          }
        },
        {
          "id": "passport.format#empty",
          "args": [
            ""
          ],
          "expect": {
            "returns": ""
          },
          "note": "some libs return null/None for input they cannot format; the reference returns an empty string (asserted by its tests)"
        },
        {
          "id": "passport.format#caps-length",
          "args": [
            "AB123456789"
          ],
          "expect": {
            "returns": "AB123456"
          },
          "note": "reference truncates to 8 characters; asserted by the reference (JS) unit tests"
        },
        {
          "id": "passport.format#[\"A\"]",
          "args": [
            "A"
          ],
          "expect": {
            "returns": "A"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport is valid"
        },
        {
          "id": "passport.format#[\"AB\"]",
          "args": [
            "AB"
          ],
          "expect": {
            "returns": "AB"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport is valid"
        },
        {
          "id": "passport.format#[\"AB1\"]",
          "args": [
            "AB1"
          ],
          "expect": {
            "returns": "AB1"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport is valid"
        },
        {
          "id": "passport.format#[\"AB123\"]",
          "args": [
            "AB123"
          ],
          "expect": {
            "returns": "AB123"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport is valid"
        },
        {
          "id": "passport.format#[\"AB1234\"]",
          "args": [
            "AB1234"
          ],
          "expect": {
            "returns": "AB1234"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport is valid"
        },
        {
          "id": "passport.format#[\"AB12345\"]",
          "args": [
            "AB12345"
          ],
          "expect": {
            "returns": "AB12345"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport is valid"
        },
        {
          "id": "passport.format#[\"a\"]",
          "args": [
            "a"
          ],
          "expect": {
            "returns": "A"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport has lowercase letters"
        },
        {
          "id": "passport.format#[\"ac\"]",
          "args": [
            "ac"
          ],
          "expect": {
            "returns": "AC"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport has lowercase letters"
        },
        {
          "id": "passport.format#[\"acd\"]",
          "args": [
            "acd"
          ],
          "expect": {
            "returns": "ACD"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport has lowercase letters"
        },
        {
          "id": "passport.format#[\"acd1\"]",
          "args": [
            "acd1"
          ],
          "expect": {
            "returns": "ACD1"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport has lowercase letters"
        },
        {
          "id": "passport.format#[\"acd12\"]",
          "args": [
            "acd12"
          ],
          "expect": {
            "returns": "ACD12"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport has lowercase letters"
        },
        {
          "id": "passport.format#[\"acd127\"]",
          "args": [
            "acd127"
          ],
          "expect": {
            "returns": "ACD127"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport has lowercase letters"
        },
        {
          "id": "passport.format#[\"acd1273\"]",
          "args": [
            "acd1273"
          ],
          "expect": {
            "returns": "ACD1273"
          },
          "note": "JavaScript's own test: should return the formatted passport when passport has lowercase letters"
        }
      ]
    },
    {
      "id": "passport.generate",
      "level": "extended",
      "summary": "Generates a random valid Brazilian passport number.",
      "description": "Generates a random valid passport number: 2 uppercase letters followed by 6 digits.",
      "params": [],
      "returns": "string",
      "cases": [
        {
          "id": "passport.generate#generated-is-valid",
          "args": [],
          "expect": {
            "satisfies": "passport.isValid"
          },
          "repeat": 5,
          "note": "every generated value must pass the lib's own validator"
        }
      ]
    },
    {
      "id": "passport.isValid",
      "level": "extended",
      "summary": "Checks whether a Brazilian passport number is valid: 2 letters followed by 6 digits.",
      "description": "Validates a Brazilian passport number: 2 letters followed by 6 digits, after removing non-alphanumeric characters.\n\n- There is no check digit, so a well-formed number is not necessarily a real passport.\n- A numeric value is never valid, since it cannot start with the two letters.\n- Pending decision (findings §1b, §2 #8): the reference (JS) is case-insensitive and ignores symbols (`ab123456`, `AB-123.456` are valid). Erlang and Python accept only the strict uppercase form.\n- The layout's only official source is the Polícia Federal FAQ (\"duas letras ... e por seis dígitos subsequentes\", example CS265436). Neither Decreto 5.978/2006 nor IN 173-DG/PF/2020 defines the number, and the FAQ forbids no letter, so none is rejected.",
      "params": [
        {
          "name": "passport",
          "type": "string | number"
        }
      ],
      "returns": "boolean",
      "cases": [
        {
          "id": "passport.isValid#[\"AA111111\"]",
          "args": [
            "AA111111"
          ],
          "expect": {
            "returns": true
          }
        },
        {
          "id": "passport.isValid#[\"CL125167\"]",
          "args": [
            "CL125167"
          ],
          "expect": {
            "returns": true
          }
        },
        {
          "id": "passport.isValid#lowercase",
          "args": [
            "ab123456"
          ],
          "expect": {
            "returns": true
          },
          "note": "case-insensitive in the reference (see the description); asserted by the reference (JS) unit tests"
        },
        {
          "id": "passport.isValid#masked",
          "args": [
            "AB-123456"
          ],
          "expect": {
            "returns": true
          }
        },
        {
          "id": "passport.isValid#dotted",
          "args": [
            "AB.123.456"
          ],
          "expect": {
            "returns": true
          }
        },
        {
          "id": "passport.isValid#[\"1\"]",
          "args": [
            "1"
          ],
          "expect": {
            "returns": false
          }
        },
        {
          "id": "passport.isValid#[\"1112223334-\"]",
          "args": [
            "1112223334-"
          ],
          "expect": {
            "returns": false
          }
        },
        {
          "id": "passport.isValid#number",
          "args": [
            1
          ],
          "expect": {
            "returns": false
          },
          "note": "a number is accepted but never valid (see the description)"
        },
        {
          "id": "passport.isValid#[\"CS265436\"]",
          "args": [
            "CS265436"
          ],
          "expect": {
            "returns": true
          },
          "note": "the example of the Polícia Federal FAQ"
        },
        {
          "id": "passport.isValid#[\"DC-221345extra\"]",
          "args": [
            "DC-221345extra"
          ],
          "expect": {
            "returns": false
          },
          "note": "JavaScript docs example: trailing letters make the sanitized value longer than 2 letters and 6 digits"
        },
        {
          "id": "passport.isValid#[\"AB-123.456\"]",
          "args": [
            "AB-123.456"
          ],
          "expect": {
            "returns": true
          },
          "note": "JavaScript docs example (symbols are ignored)"
        },
        {
          "id": "passport.isValid#[\"12345678\"]",
          "args": [
            "12345678"
          ],
          "expect": {
            "returns": false
          },
          "note": "JavaScript docs example"
        }
      ]
    },
    {
      "id": "passport.parse",
      "level": "extended",
      "summary": "Removes non-alphanumeric characters from a passport number, converts it to uppercase and caps it at 8 characters.",
      "description": "Removes every non-alphanumeric character from a passport number, upper-cases it and caps it at 8 characters.\n\n- A value that is not a string (for example a number) returns an empty string.",
      "params": [
        {
          "name": "passport",
          "type": "string"
        }
      ],
      "returns": "string",
      "cases": [
        {
          "id": "passport.parse#[\"Ab123456\"]",
          "args": [
            "Ab123456"
          ],
          "expect": {
            "returns": "AB123456"
          }
        },
        {
          "id": "passport.parse#spaces",
          "args": [
            " AB 123 456 "
          ],
          "expect": {
            "returns": "AB123456"
          }
        },
        {
          "id": "passport.parse#hyphens",
          "args": [
            "-AB1-23-4-56-"
          ],
          "expect": {
            "returns": "AB123456"
          }
        },
        {
          "id": "passport.parse#caps-length",
          "args": [
            "AB123456789"
          ],
          "expect": {
            "returns": "AB123456"
          }
        },
        {
          "id": "passport.parse#empty",
          "args": [
            ""
          ],
          "expect": {
            "returns": ""
          }
        },
        {
          "id": "passport.parse#[\".AB.1.23.456.\"]",
          "args": [
            ".AB.1.23.456."
          ],
          "expect": {
            "returns": "AB123456"
          },
          "note": "JavaScript's own test: should return the string without symbols when there are dots"
        },
        {
          "id": "passport.parse#[\".A B.1.2-3.45 -. 6.\"]",
          "args": [
            ".A B.1.2-3.45 -. 6."
          ],
          "expect": {
            "returns": "AB123456"
          },
          "note": "JavaScript's own test: should return the string without symbols when there are multiple symbols"
        },
        {
          "id": "passport.parse#[\"AB-123.456\"]",
          "args": [
            "AB-123.456"
          ],
          "expect": {
            "returns": "AB123456"
          },
          "note": "JavaScript docs example"
        }
      ]
    }
  ]
}