Valider un fichier importé contre un schéma

"""
Valider un document importé contre le schéma qu'il est censé suivre.

Niveau N0. JSON Schema est une norme publiée, et un validateur est un
programme qui l'applique : chaque échec revient avec l'endroit où il s'est
produit et la règle qu'il a enfreinte. Il n'y a rien à deviner et rien à
apprendre — un schéma est le contrat, écrit une fois, et le même document se
valide toujours de la même façon.

`jsonschema` l'applique ici, `ajv` en JavaScript. Deux choses qu'ils font tous les
deux et qui surprennent, et que ce fichier règle au lieu d'en hériter.

`format` est une annotation, pas une assertion. Les deux bibliothèques y
réagissent différemment, et les deux réactions surprennent quelqu'un :
`jsonschema` accepte « 12/01/2026 » et « 2026-02-30 » contre
`"format": "date"` sans un mot, tandis qu'`ajv` refuse purement et simplement
de compiler le schéma tant que les formats ne sont pas enregistrés. Les
enregistrer, plus bas, est ce qui met les deux d'accord — et fait refuser ces
deux dates aux deux.

Et un validateur s'arrête au premier échec tant qu'on ne lui dit pas le
contraire. Un import se vérifie une fois et se corrige une fois : toutes les
erreurs sont donc collectées, plafonnées, et le rapport dit combien ont été
laissées de côté plutôt que de faire comme s'il n'y en avait pas.

Ce qui revient, c'est un chemin et un nom de règle par échec. La formulation
du message appartient à la bibliothèque et diffère entre les deux ; le chemin
et la règle sont ce sur quoi votre code doit se brancher.
"""

from __future__ import annotations

import json

from jsonschema import Draft202012Validator, FormatChecker

# A file with one systematic mistake produces one error per record. Two hundred
# is enough to see the pattern; the count says how many more there were.
MAX_ERRORS = 200

# Compiling a schema costs far more than checking one document against it, and
# an import checks thousands against the same schema. The compiled form is kept
# here, keyed by the schema itself; the cap is what stops a caller that builds
# a new schema per record from filling memory.
_COMPILED: dict[str, object] = {}
MAX_COMPILED = 32


def validate_import(document, schema) -> dict:
    """
    Check `document` against `schema`, and return every failure.

    `errors` carries, for each one, the JSON Pointer of the value and the name
    of the rule it broke — the two things a caller can act on — plus the
    library's own message, which is for a human to read and not for code to
    match on.

    A schema that is itself invalid is reported as such rather than raised:
    on an import path, a broken contract is an incident to log, not a crash.
    """
    validator = _compiled(schema)
    if validator is None:
        return _report(False, [], 0, "this schema is not usable")
    try:
        failures = sorted(validator.iter_errors(document), key=_order)
    except Exception:  # noqa: BLE001 - a broken contract is an answer too
        return _report(False, [], 0, "this schema is not usable")
    kept = [{"path": _pointer(error.absolute_path),
             "rule": str(error.validator),
             "message": error.message}
            for error in failures[:MAX_ERRORS]]
    return _report(not failures, kept, len(failures), None)


def _compiled(schema):
    """The compiled validator for this schema, or None when it is not usable."""
    try:
        key = json.dumps(schema, sort_keys=True)
    except TypeError:
        return None
    if key not in _COMPILED:
        try:
            # The schema itself is checked first: a rule the standard does not
            # define — « objet » for « object » — would otherwise only surface
            # as an exception in the middle of a file, on the first value that
            # uses it.
            Draft202012Validator.check_schema(schema)
            _COMPILED[key] = Draft202012Validator(schema, format_checker=FormatChecker())
        except Exception:  # noqa: BLE001 - a broken contract is an answer too
            _COMPILED[key] = None
        if len(_COMPILED) > MAX_COMPILED:
            del _COMPILED[next(iter(_COMPILED))]
    return _COMPILED[key]


def _order(error):
    """
    A single order, in both languages: by place in the document, then by rule.
    An index sorts as a number, so record 10 comes after record 2 and not
    after record 1 as a string comparison would have it.
    """
    steps = [(0, step, "") if isinstance(step, int) else (1, 0, str(step))
             for step in error.absolute_path]
    return (steps, str(error.validator))


def _pointer(path) -> str:
    """The JSON Pointer of a value, which is what both libraries can produce."""
    return "".join(f"/{str(step).replace('~', '~0').replace('/', '~1')}" for step in path)


def _report(valid: bool, errors: list, total: int, reason: str | None) -> dict:
    return {"valid": valid, "errors": errors, "error_count": total,
            "truncated": total > len(errors), "reason": reason}

/**
 * Valider un document importé contre le schéma qu'il est censé suivre.
 *
 * Niveau N0. JSON Schema est une norme publiée, et un validateur est un
 * programme qui l'applique : chaque échec revient avec l'endroit où il s'est
 * produit et la règle qu'il a enfreinte. Il n'y a rien à deviner et rien à
 * apprendre — un schéma est le contrat, écrit une fois, et le même document se
 * valide toujours de la même façon.
 *
 * `ajv` l'applique ici, `jsonschema` en Python. Deux choses qu'ils font tous les
 * deux et qui surprennent, et que ce fichier règle au lieu d'en hériter.
 *
 * `format` est une annotation, pas une assertion. Les deux bibliothèques y
 * réagissent différemment, et les deux réactions surprennent quelqu'un :
 * `jsonschema` accepte « 12/01/2026 » et « 2026-02-30 » contre
 * `"format": "date"` sans un mot, tandis qu'`ajv` refuse purement et simplement
 * de compiler le schéma tant que les formats ne sont pas enregistrés. Les
 * enregistrer, plus bas, est ce qui met les deux d'accord — et fait refuser ces
 * deux dates aux deux.
 *
 * Et un validateur s'arrête au premier échec tant qu'on ne lui dit pas le
 * contraire. Un import se vérifie une fois et se corrige une fois : toutes les
 * erreurs sont donc collectées, plafonnées, et le rapport dit combien ont été
 * laissées de côté plutôt que de faire comme s'il n'y en avait pas.
 *
 * Ce qui revient, c'est un chemin et un nom de règle par échec. La formulation
 * du message appartient à la bibliothèque et diffère entre les deux ; le chemin
 * et la règle sont ce sur quoi votre code doit se brancher.
 */

// `ajv` still defaults to draft-07; the 2020-12 dialect, the current one, is
// a separate entry point. Importing the default one instead refuses every
// schema that declares 2020-12, which is the shape the standard now publishes.
import AjvModule from 'ajv/dist/2020.js';
import addFormatsModule from 'ajv-formats';

// Both packages are published as CommonJS and carry their class on `default`.
const Ajv = AjvModule.default ?? AjvModule;
const addFormats = addFormatsModule.default ?? addFormatsModule;

// A file with one systematic mistake produces one error per record. Two
// hundred is enough to see the pattern; the count says how many more there were.
export const MAX_ERRORS = 200;

// Compiling a schema costs far more than checking one document against it, and
// an import checks thousands against the same schema. The compiled form is
// kept here, keyed by the schema itself; the cap is what stops a caller that
// builds a new schema per record from filling memory.
const COMPILED = new Map();
export const MAX_COMPILED = 32;

/** The compiled validator for this schema, or null when it is not usable. */
function compiled(schema) {
  let key;
  try {
    key = JSON.stringify(schema) ?? 'undefined';
  } catch {
    return null;
  }
  if (!COMPILED.has(key)) {
    let validate = null;
    try {
      // The schema itself is checked first: a rule the standard does not
      // define — « objet » for « object » — would otherwise only surface as an
      // exception in the middle of a file, on the first value that uses it.
      const ajv = new Ajv({ allErrors: true, strictSchema: false });
      addFormats(ajv);
      validate = ajv.compile(schema);
    } catch {
      validate = null;
    }
    COMPILED.set(key, validate);
    if (COMPILED.size > MAX_COMPILED) COMPILED.delete(COMPILED.keys().next().value);
  }
  return COMPILED.get(key);
}

/**
 * Check `document` against `schema`, and return every failure.
 *
 * `errors` carries, for each one, the JSON Pointer of the value and the name
 * of the rule it broke — the two things a caller can act on — plus the
 * library's own message, which is for a human to read and not for code to
 * match on.
 *
 * A schema that is itself invalid is reported as such rather than thrown: on
 * an import path, a broken contract is an incident to log, not a crash.
 *
 * @param {unknown} document
 * @param {object} schema
 */
export function validateImport(document, schema) {
  const validate = compiled(schema);
  if (!validate) return report(false, [], 0, 'this schema is not usable');

  validate(document);
  const failures = [...(validate.errors ?? [])].sort(order);
  const kept = failures.slice(0, MAX_ERRORS).map((error) => ({
    path: error.instancePath,
    rule: error.keyword,
    message: error.message,
  }));
  return report(failures.length === 0, kept, failures.length, null);
}

/**
 * A single order, in both languages: by place in the document, then by rule.
 * An index sorts as a number, so record 10 comes after record 2 and not after
 * record 1 as a string comparison would have it.
 */
function order(a, b) {
  const steps = (error) => error.instancePath.split('/').slice(1)
    .map((step) => step.replace(/~1/g, '/').replace(/~0/g, '~'))
    .map((step) => (/^\d+$/.test(step) ? [0, Number(step), ''] : [1, 0, step]));
  const left = steps(a);
  const right = steps(b);
  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
    if (i >= left.length) return -1;
    if (i >= right.length) return 1;
    for (let k = 0; k < 3; k += 1) {
      if (left[i][k] < right[i][k]) return -1;
      if (left[i][k] > right[i][k]) return 1;
    }
  }
  return a.keyword < b.keyword ? -1 : a.keyword > b.keyword ? 1 : 0;
}

const report = (valid, errors, total, reason) => ({
  valid, errors, error_count: total, truncated: total > errors.length, reason,
});