Contrôler un numéro d’identification d’entreprise

"""
Contrôler un numéro d'identification d'entreprise française, hors ligne et
exactement.

Niveau N0. Un SIREN fait neuf chiffres, un SIRET quatorze, et le dernier
chiffre de chacun se calcule à partir des précédents. Le contrôler est de
l'arithmétique : la réponse est exacte, elle est la même à chaque fois, et
elle ne coûte rien.

Cette arithmétique n'est pas ce qu'on écrit. Une bibliothèque de numéros
normalisés la porte — `python-stdnum` ici, `stdnum-js` en JavaScript — et
avec elle l'exception qu'une clé de Luhn écrite à la main rate : tous les
établissements de La Poste partagent le SIREN 356000000, et leurs SIRET ne
satisfont pas Luhn. La règle que l'INSEE donne pour eux est que la somme
simple des quatorze chiffres soit un multiple de cinq. 35600000009075,
l'établissement de Rennes, échoue à Luhn et est valide.

Ce que la clé prouve est étroit, et le rapport dit laquelle a été appliquée
pour que l'appelant puisse le savoir. Un numéro peut être bien formé et
n'appartenir à personne : 000000000 passe. Savoir si l'entreprise existe, et
si elle est encore en activité, est une consultation du répertoire Sirene,
pas un calcul plus difficile.
"""

from __future__ import annotations

from stdnum.fr import siren, siret

# The separators people paste around these numbers: the ordinary space, the
# non-breaking ones a spreadsheet inserts, the full stop, the hyphens. Anything
# else surviving the clean-up is refused rather than quietly dropped, which is
# what turns a mistyped number into a different valid one.
SEPARATORS = " .  -‐‑–"

# Nine digits, or fourteen. Sixty-four characters leaves room for every
# separator anyone has pasted and refuses a pasted paragraph.
MAX_CHARACTERS = 64

VALIDATORS = {"SIREN": (9, siren.is_valid), "SIRET": (14, siret.is_valid)}
BY_LENGTH = {9: "SIREN", 14: "SIRET"}


def check_company_number(raw, *, expected: str | None = None) -> dict:
    """
    Say whether `raw` carries a well-formed SIREN or SIRET.

    `expected` is the kind the caller is asking for, "SIREN" or "SIRET". Left
    out, the length decides — the only reading there is, since the two lengths
    do not overlap — and `kind` in the report says which one was checked.

    Nothing here raises on bad input: a validator that throws in a request path
    leaves the form with no answer to show. Every refusal comes back as
    `valid: False` with a `reason` in plain words.
    """
    if not isinstance(raw, str):
        return _report(False, None, "", f"a company number is text, not {type(raw).__name__}")
    if len(raw) > MAX_CHARACTERS:
        return _report(False, None, "", f"longer than {MAX_CHARACTERS} characters")

    compact = "".join(character for character in raw if character not in SEPARATORS)
    # `str.isdigit` is true of Arabic-Indic and other decimal digits, which the
    # checksum cannot be computed on; ASCII is what the register uses.
    if not compact or not compact.isascii() or not compact.isdigit():
        return _report(False, None, compact, "not digits and separators only")

    kind = expected or BY_LENGTH.get(len(compact))
    if kind not in VALIDATORS:
        return _report(False, None, compact, f"{len(compact)} digits: expected nine or fourteen")

    length, is_valid = VALIDATORS[kind]
    if len(compact) != length:
        return _report(False, kind, compact, f"{kind} is {length} digits, got {len(compact)}")
    if not is_valid(compact):
        return _report(False, kind, compact, f"the check digit of this {kind} does not match")
    return _report(True, kind, compact, None)


def _report(valid: bool, kind: str | None, compact: str, reason: str | None) -> dict:
    return {"valid": valid, "kind": kind, "compact": compact, "reason": reason}

/**
 * Contrôler un numéro d'identification d'entreprise française, hors ligne et
 * exactement.
 *
 * Niveau N0. Un SIREN fait neuf chiffres, un SIRET quatorze, et le dernier
 * chiffre de chacun se calcule à partir des précédents. Le contrôler est de
 * l'arithmétique : la réponse est exacte, elle est la même à chaque fois, et
 * elle ne coûte rien.
 *
 * Cette arithmétique n'est pas ce qu'on écrit. Une bibliothèque de numéros
 * normalisés la porte — `stdnum-js` ici, `python-stdnum` en Python — et avec
 * elle l'exception qu'une clé de Luhn écrite à la main rate : tous les
 * établissements de La Poste partagent le SIREN 356000000, et leurs SIRET ne
 * satisfont pas Luhn. La règle que l'INSEE donne pour eux est que la somme
 * simple des quatorze chiffres soit un multiple de cinq. 35600000009075,
 * l'établissement de Rennes, échoue à Luhn et est valide.
 *
 * Ce que la clé prouve est étroit, et le rapport dit laquelle a été appliquée
 * pour que l'appelant puisse le savoir. Un numéro peut être bien formé et
 * n'appartenir à personne : 000000000 passe. Savoir si l'entreprise existe, et
 * si elle est encore en activité, est une consultation du répertoire Sirene,
 * pas un calcul plus difficile.
 */

import { stdnum } from 'stdnum';

const { siren, siret } = stdnum.FR;

// The separators people paste around these numbers: the ordinary space, the
// non-breaking ones a spreadsheet inserts, the full stop, the hyphens.
// Anything else surviving the clean-up is refused rather than quietly dropped,
// which is what turns a mistyped number into a different valid one.
export const SEPARATORS = ' .  -‐‑–';

// Nine digits, or fourteen. Sixty-four characters leaves room for every
// separator anyone has pasted and refuses a pasted paragraph.
export const MAX_CHARACTERS = 64;

const VALIDATORS = {
  SIREN: [9, (value) => siren.validate(value).isValid],
  SIRET: [14, (value) => siret.validate(value).isValid],
};
const BY_LENGTH = { 9: 'SIREN', 14: 'SIRET' };

/**
 * Say whether `raw` carries a well-formed SIREN or SIRET.
 *
 * `expected` is the kind the caller is asking for, 'SIREN' or 'SIRET'. Left
 * out, the length decides — the only reading there is, since the two lengths
 * do not overlap — and `kind` in the report says which one was checked.
 *
 * Nothing here throws on bad input: a validator that throws in a request path
 * leaves the form with no answer to show. Every refusal comes back as
 * `valid: false` with a `reason` in plain words.
 *
 * @param {string} raw
 * @param {{expected?: 'SIREN'|'SIRET'}} [options]
 */
export function checkCompanyNumber(raw, { expected } = {}) {
  if (typeof raw !== 'string') {
    return report(false, null, '', `a company number is text, not ${kindOf(raw)}`);
  }
  if (raw.length > MAX_CHARACTERS) {
    return report(false, null, '', `longer than ${MAX_CHARACTERS} characters`);
  }

  const compact = [...raw].filter((character) => !SEPARATORS.includes(character)).join('');
  // Only ASCII digits: the checksum cannot be computed on Arabic-Indic or
  // other decimal digits, and the register uses ASCII.
  if (!/^[0-9]+$/.test(compact)) {
    return report(false, null, compact, 'not digits and separators only');
  }

  const kind = expected ?? BY_LENGTH[compact.length];
  if (!(kind in VALIDATORS)) {
    return report(false, null, compact, `${compact.length} digits: expected nine or fourteen`);
  }

  const [length, isValid] = VALIDATORS[kind];
  if (compact.length !== length) {
    return report(false, kind, compact, `${kind} is ${length} digits, got ${compact.length}`);
  }
  if (!isValid(compact)) {
    return report(false, kind, compact, `the check digit of this ${kind} does not match`);
  }
  return report(true, kind, compact, null);
}

const kindOf = (value) => (value === null ? 'null' : typeof value);

const report = (valid, kind, compact, reason) => ({ valid, kind, compact, reason });