# Port provenance and compatibility

This package is a TypeScript port and Apache-2.0 derived work of
[`rspeer/python-ftfy`](https://github.com/rspeer/python-ftfy), created by Robyn
Speer. The pinned source-of-truth commit is recorded in [UPSTREAM.md](../UPSTREAM.md).

## API mapping

The port deliberately retains upstream's snake_case names. Python named tuples
returned by the explanation and byte-guessing APIs become JavaScript arrays
with matching named properties, so both styles work:

```ts
const [text, explanation] = fix_and_explain(input);
const sameText = fix_and_explain(input).text;
```

Python `bytes` values become `Uint8Array`. Python iterables used by `fix_file`
become JavaScript `Iterable<string | Uint8Array>`. Encoding errors are exposed
as `UnicodeDecodeError` and `UnicodeEncodeError` from `ftfy-js/bad-codecs`.

## Reference data

JavaScript lacks standard equivalents for several facilities used upstream.
The repository therefore generates and ships exact tables from the pinned
Python environment for:

- supported single-byte and sloppy encodings;
- HTML5 named entities plus upstream's uppercase variants;
- Unicode character names and general categories; and
- `wcwidth` zero-width and wide-character ranges.

The generator is `scripts/generate-reference-data.py`. Generated sources name
their provenance and are checked into the package so consumers do not need
Python.

## Tests

The test suite ports every upstream unit-test module and copies all upstream
JSON test corpora. It verifies both expected successes and upstream's declared
known failures. Every passing corpus example is also tested after adding an
extra layer of UTF-8-decoded-as-Latin-1 mojibake, and every explanation plan is
replayed with `apply_plan`.

The project does not publish to npm automatically. `npm run check` ends with an
npm dry run so the maintainer can inspect and publish the package manually.

Maintainers with the pinned upstream checkout can additionally run a
deterministic Python-vs-TypeScript differential sweep:

```sh
PYTHON_FTFY_ROOT=/path/to/python-ftfy npm run test:differential
```