rowcanary 1.0.0__tar.gz

rowcanary-1.0.0/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{md,yml,yaml}]
+indent_size = 2

rowcanary-1.0.0/.gitattributes

@@ -0,0 +1,6 @@
+* text=auto eol=lf
+*.csv -text -whitespace
+*.tsv -text -whitespace
+*.jsonl -text -whitespace
+*.xlsx -text
+*.png -text

rowcanary-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+jobs:
+  build:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: '3.10'
+      - name: Build and validate distributions
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+          python tools/check_package.py dist
+      - name: Smoke test installed wheel outside checkout
+        run: |
+          python -m venv /tmp/rowcanary-publish
+          /tmp/rowcanary-publish/bin/python -m pip install dist/*.whl
+          cd /tmp
+          /tmp/rowcanary-publish/bin/rowcanary --version
+          /tmp/rowcanary-publish/bin/rowcanary demo
+          /tmp/rowcanary-publish/bin/rowcanary make publish-probe.csv
+          /tmp/rowcanary-publish/bin/rowcanary check publish-probe.csv
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/rowcanary/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: distributions
+          path: dist
+      - name: Publish with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1

rowcanary-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,72 @@
+name: Checks
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-15-intel, windows-latest]
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install '.[test]'
+      - name: Run tests
+        run: python -m unittest discover -s tests -v
+      - name: Smoke test
+        run: |
+          python -m rowcanary demo
+          python -m rowcanary make probe.csv
+          python -m rowcanary check probe.csv
+          rowcanary --version
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: '3.10'
+      - name: Install development tools
+        run: python -m pip install '.[dev]'
+      - name: Static analysis
+        run: |
+          python -m ruff check .
+          python -m ruff format --check rowcanary tests tools
+      - name: Build and validate distributions
+        run: |
+          python -m build
+          python -m twine check dist/*
+          python tools/check_package.py dist
+      - name: Test installed wheel outside the checkout
+        run: |
+          python -m venv /tmp/rowcanary-wheel
+          /tmp/rowcanary-wheel/bin/python -m pip install dist/*.whl
+          cd /tmp
+          /tmp/rowcanary-wheel/bin/python -m rowcanary demo
+          /tmp/rowcanary-wheel/bin/rowcanary make probe.csv
+          /tmp/rowcanary-wheel/bin/rowcanary check probe.csv
+          /tmp/rowcanary-wheel/bin/python -c "import json; from pathlib import Path; from importlib.resources import files; from rowcanary import Config, check_file, write_probes; c=Config(probe_set='extended'); write_probes(Path('api.json'), **c.make_options()); assert check_file(Path('api.json'), **c.check_options()).ok; json.loads(files('rowcanary').joinpath('config.schema.json').read_bytes())"
+
+  assets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: '3.14'
+      - name: Install asset verification tools
+        run: python -m pip install -r tools/requirements-assets.txt
+      - name: Validate vectors and PNG exports
+        run: python tools/check_assets.py

rowcanary-1.0.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+.venv-*/
+.local/
+.ruff_cache/
+venv/
+*.egg-info/
+build/
+dist/
+.coverage
+.serena/
+.DS_Store
+rowcanary-probe.csv
+.trail/cache/
+.trail/graph.db
+.trail/state.json
+Thumbs.db
+.playwright-cli/
+output/playwright/

rowcanary-1.0.0/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+## [1.0.0] - 2026-11-03
+
+- Publish the frozen, backward-compatible CLI, five-format comparison engine,
+  diagnostics/reports, local browser interface and Python/configuration API.
+- Complete the sequential roadmap, final regression and packaging review;
+  retain bounded inputs, exact values/types and documented application limits.
+- Provide verified wheel, sdist, source ZIP and SHA-256 checksums on GitHub.
+  No PyPI publication is included.
+
+## [0.9.0] - 2026-11-03
+
+- Freeze the 1.0 feature/API surface after focused independent security and
+  compatibility review of the new configuration, CLI and browser changes.
+- Update security boundaries for all formats, local HTTP and configuration.
+- Verify the installed public API and configuration schema outside the checkout
+  in hosted packaging CI, in addition to existing local wheel/sdist gates.
+- Retain known application limitations and the unchanged runtime dependencies.
+
+## [0.8.0] - 2026-11-03
+
+- Add a complete first-run guide, spreadsheet guidance and troubleshooting.
+- Clear stale browser reports after input/mode changes; lock fields while busy
+  and announce errors assertively. Retain keyboard focus and both themes.
+- Include actual desktop/mobile screenshots and verify browser generation,
+  PASS/FAIL, report downloads, labels, skip-link focus and reduced motion.
+
+## [0.7.0] - 2026-11-03
+
+- Stabilize public Python imports and add immutable, validated Config/load_config.
+- Support bounded UTF-8 JSON configuration for make/check/batch, relative custom
+  paths, explicit CLI precedence and --no-strict-order. Preserve prior defaults.
+- Package configuration schema 1.0 and Python, batch and pinned Actions examples.
+- Reject unknown/duplicate keys, invalid option types, encodings and oversized JSON.
+
+## [0.6.0] - 2026-11-03
+
+- Add 13 deterministic synthetic compatibility fixtures with independent
+  expected issue IDs/codes, explicit provenance and SHA-256 manifests.
+- Cover five formats, UTF BOM profiles, semicolon CSV, changed/reordered rows
+  and native JSON scalar coercions; verify byte-identical corpus rebuilds.
+- Record native Microsoft Excel 16.0 build 20527 (32-bit) OpenText/CSVUTF8
+  observations: text-column import preserved 33/35 controls, automatic inference
+  20/35. Retain raw CSV outputs and exact settings; neither profile fully passed.
+- Add an isolated, macro-disabled Excel automation script and an evidence matrix
+  that separates parser fixtures, native observations and untested applications.
+- Use fixed ZIP platform metadata and stored XLSX members so generated bytes do
+  not vary with host zlib versions. Files are larger; existing output limits apply.
+
+## [0.5.0] - 2026-11-03
+
+- Stream CSV, TSV and JSONL through bounded, context-managed readers, preserving
+  exact CR/LF/CRLF and enforcing byte limits even after stale size checks.
+- Compare streamed records once without consuming JSONL rows during column
+  inference; close input handles after success and failure.
+- Bound diagnostic counts/text and JSON numeric fields; reject duplicate XLSX
+  archive members and multiple objects per JSONL line.
+- Avoid reserving the entire byte limit for small buffered reads.
+- Bound the local server backlog, test concurrent isolation and hostile framing,
+  and render only the first 200 UI items while retaining complete downloads.
+- Add reproducible synthetic time/Python-allocation benchmarks; document that
+  JSON arrays/XLSX remain buffered and measurements do not represent process RSS.
+
+## [0.4.0] - 2026-11-03
+
+- Add `rowcanary serve` with a browser interface bound only to `127.0.0.1`.
+- Generate/download controls and upload/check exports in all five formats,
+  including custom controls, exact types and strict-order comparison.
+- Download versioned JSON and escaped standalone HTML reports.
+- Include labeled keyboard-accessible controls, responsive light/dark themes,
+  the existing canary identity and no external resources or runtime dependencies.
+- Enforce exact Host/Origin and per-session token checks, fixed static routes,
+  request/upload limits, temporary files and no-store/security headers.
+
+## [0.3.0] - 2026-11-03
+
+- Add evidence-based classifications, severity, scalar types, observations,
+  tentative possible causes and practical guidance without changing issue codes.
+- Observe reordered rows without failing by default; add opt-in `--strict-order`.
+- Add deterministic, escaped standalone HTML and JSON exports with exclusive
+  creation through `check --report` and `batch --report`.
+- Check multiple files with `batch`, retaining every result; operational errors
+  take exit-code precedence over integrity differences.
+- Package report JSON Schema 1.0 and validate real single and batch reports.
+- Keep schema validation a test dependency; runtime dependencies are unchanged.
+
+## [0.2.0] - 2026-11-02
+
+- Generate and audit CSV, TSV, JSON, JSONL and single-sheet XLSX files.
+- Add explicit format/encoding options, conservative content detection and
+  UTF-16/32 BOM decoding without normalizing in-cell line breaks.
+- Add deterministic extended/category probe sets and validated custom scalar
+  controls, preserving the original default probe IDs and CLI commands.
+- Preserve JSON/XLSX scalar types; refuse lossy XLSX integer/text generation.
+- Store XLSX strings as literal text and reject returned formulas without
+  executing them. Bound ZIP expansion and validate malformed workbooks.
+- Write deterministic OpenXML/ZIP metadata and preserve embedded CR/LF/CRLF
+  across platforms without passing generated data through text-mode writers.
+
+## [0.1.1] - 2026-11-02
+
+- Enforce the documented string-field safety bound in JSON, including nested
+  extra data, so JSON cannot bypass the bound applied to CSV fields.
+- Reject invalid API column names before reading a file, with an actionable error.
+- Add regression coverage for both validation failures. Preserve all existing
+  CLI commands, default probes and exact CR/LF comparisons.
+
+## [0.1.0] - 2026-11-02
+
+- Generate 24 deterministic, realistic edge-case CSV controls.
+- Compare round-tripped CSV or JSON by stable probe IDs, regardless of row order.
+- Detect dropped, duplicate, added, and changed control records.
+- Print human-readable or JSON reports with appropriate exit codes.
+- Include an isolated demonstration, automated tests and CI configuration.
+- Preserve in-cell CR/LF/CRLF exactly and report blank CSV records.
+- Support explicit CSV delimiters without automatic data normalization.
+- Reject duplicate JSON keys and nonstandard constants; retain numeric token
+  precision for diagnostics without accepting numbers as strings.
+- Bound reads to 32 MiB, exported records to 100,000 and CSV fields to 128 Ki
+  characters; refuse existing output symlinks, including dangling links.
+- Escape untrusted terminal text and support restricted output encodings.
+- Return structured JSON errors for `check --json` input and I/O failures.
+- Clarify spreadsheet formula risks and the limits of a passing result.
+- Reconstruct the original bird/table logo as self-contained SVG paths, with
+  PNG exports and a 1280 × 640 social preview.
+- Include package inspection, asset verification and regression tests.

rowcanary-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Use an issue to describe a reproducible data-change case, including Python/OS
+versions and the exact commands used. Include synthetic input and observed
+output. Do not share customer records, credentials or unredacted private paths.
+Read [SECURITY.md](SECURITY.md) before reporting a vulnerability.
+
+For code changes:
+
+1. Install development tools: `python -m pip install -e ".[dev]"`.
+2. Add a focused regression test that fails before the fix.
+3. Preserve exact strings and JSON types. Do not hide data changes through
+   trimming, newline replacement, Unicode normalization or numeric coercion.
+4. Prefer the Python standard library and small changes at the responsible
+   layer. Keep Python 3.10 compatibility.
+5. Run `python -m unittest discover -s tests -v` and `python -m ruff check .`.
+6. For a release, also run `python -m build`, `python -m twine check dist/*` and
+   `python tools/check_package.py dist` in a directory containing one current
+   wheel and one current source distribution.
+
+CLI exit statuses are part of the interface: 0 for matching controls or
+successful generation/demo, 1 for integrity differences, 2 for invalid input or
+I/O/usage errors. `check --json` operational errors produce an `error` object;
+argument parsing errors remain stderr usage diagnostics.
+
+Tests must never evaluate spreadsheet formulas. Use only synthetic fixtures
+and temporary directories; verify that generation cannot overwrite an existing
+path. See [asset instructions](assets/README.md) before changing artwork.

rowcanary-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RowCanary contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rowcanary-1.0.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md LICENSE CHANGELOG.md CONTRIBUTING.md SECURITY.md
+include .editorconfig .gitignore .gitattributes
+recursive-include .github/workflows *.yml
+recursive-include assets *.svg *.png *.md *.txt
+recursive-include docs *.md *.png
+recursive-include examples *.csv *.tsv *.json *.jsonl *.xlsx *.md *.py *.yml
+recursive-include rowcanary/static *.html *.css *.js *.svg
+recursive-include tests *.py
+recursive-include tools *.py *.ps1 *.txt
+global-exclude *.py[cod] .DS_Store
+prune .trail
+prune .local
+prune .venv

rowcanary-1.0.0/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: rowcanary
+Version: 1.0.0
+Summary: Detect silent data corruption in CSV import/export workflows with control samples
+Author: RowCanary contributors
+License-Expression: MIT
+Project-URL: Source, https://github.com/spockplayer2-alt/rowcanary
+Project-URL: Issues, https://github.com/spockplayer2-alt/rowcanary/issues
+Project-URL: Changelog, https://github.com/spockplayer2-alt/rowcanary/blob/main/CHANGELOG.md
+Keywords: csv,import,export,data-integrity,testing,cli
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openpyxl<4,>=3.1.5
+Requires-Dist: defusedxml<1,>=0.7.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Requires-Dist: jsonschema<5,>=4.23; extra == "dev"
+Provides-Extra: test
+Requires-Dist: jsonschema<5,>=4.23; extra == "test"
+Dynamic: license-file
+
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <img src="assets/logo.svg" width="156" height="132" alt="RowCanary: a canary shaped like a data table">
+  </picture>
+  <h1>RowCanary</h1>
+  <p><strong>Detect silent data changes during import/export workflows.</strong></p>
+  <p>Local Python CLI and browser UI · CSV, TSV, JSON, JSONL and XLSX · MIT</p>
+</div>
+
+An import can succeed while changing the data. A spreadsheet might turn
+`00012345` into `12345`, an importer might interpret `5E12` as a number, or an
+export might trim spaces that matter.
+
+RowCanary creates 24 known control values. Pass them through the same workflow
+as your data, export the result, and check which values survived. It reports
+exact differences without trimming, numeric conversion or Unicode normalization.
+
+## Demonstration
+
+Run this from the source directory or after installation:
+
+```console
+$ python -m rowcanary demo
+DEMO: three sample values were intentionally modified.
+FAIL  21/24 test values preserved
+  [changed] zeroes: Leading zeroes may have been removed
+    expected: '00012345'
+    actual:   '12345'
+  [changed] scientific: Identifier may have been read as scientific notation
+    expected: '5E12'
+    actual:   '5000000000000'
+  [changed] formula: Formula-like text was evaluated or rewritten
+    expected: '=1+1'
+    actual:   '2'
+  Scope: only the provided control samples, not an entire real dataset.
+Use 'rowcanary make probe.csv' to test a real import/export process.
+```
+
+The demo deliberately alters three values in a temporary directory. It exits
+successfully when the demonstration runs; this is not an observed result from
+Excel, Google Sheets, a CRM or another third-party application.
+
+## Installation
+
+Requires **Python 3.10 or newer**. Install from [PyPI](https://pypi.org/project/rowcanary/):
+
+```bash
+pip install rowcanary
+rowcanary --version
+```
+
+The version output is `rowcanary 1.0.0`. Use a virtual environment if your Python
+installation requires one. If the console script is not on your `PATH`, use
+`python -m rowcanary` with the Python interpreter that installed the package.
+You can also run the module directly from the extracted source directory.
+
+## Quick start
+
+For the local browser interface, run `rowcanary serve --open`. It binds only to
+`127.0.0.1`, uses no external resources and provides generation, upload/check,
+light/dark themes and JSON/HTML downloads. Stop it with Ctrl+C. See the
+[local UI guide](docs/web-ui.md) for privacy, limits and port options.
+
+```bash
+python -m rowcanary make probe.csv
+python -m rowcanary check probe.csv
+```
+
+The second command checks the unmodified control file:
+
+```text
+PASS  24/24 test values preserved
+  No changes detected in the test values.
+  Scope: only the provided control samples, not an entire real dataset.
+```
+
+`make` refuses to overwrite an existing path. Choose a new filename for each
+probe. The default filename, when omitted, is `rowcanary-probe.csv`.
+
+**Spreadsheet safety:** the probes deliberately include strings beginning with
+`=`, `+` and `-`, including `=1+1`. Spreadsheet software may evaluate them.
+CSV quoting does not prevent formula evaluation. Use isolated test data and
+inspect import settings before opening a probe. RowCanary itself never evaluates
+formulas or executes input values. It does not sanitize arbitrary CSV files.
+
+## Real-world usage
+
+1. Generate a probe with `rowcanary make probe.csv`.
+2. Import it into an isolated test area of the application being assessed.
+3. Export those same records through the workflow you want to test.
+4. Run `rowcanary check exported.csv`.
+
+Keep `_rowcanary_id` and `_rowcanary_value` in the export. Records can be
+reordered and additional named columns are allowed. The file should contain
+only the probe records: other records are reported as unexpected.
+
+If the application renames the columns:
+
+```bash
+rowcanary check exported.csv --id-column probe_id --value-column probe_value
+```
+
+For a semicolon-delimited workflow, explicitly choose the same delimiter for
+generation and checking:
+
+```bash
+rowcanary make probe-semicolon.csv --delimiter ";"
+rowcanary check exported.csv --delimiter ";"
+```
+
+There is no delimiter detection. A delimiter must be one UTF-8 character; tab
+and pipe are also supported. Newline, carriage return, NUL and double quote
+cannot be delimiters.
+
+For JSON exports, use an array of objects with the same column names. Probe
+values and IDs must remain **strings**; a JSON number, boolean or null is a
+change, even if it looks similar when printed.
+See [the complete JSON example](examples/clean.json).
+
+```bash
+rowcanary check exported.json --json
+rowcanary check export.txt --format json --json
+```
+
+`--format` chooses the input parser; `--json` chooses the output report.
+Without `--format`, a supported extension selects the parser; recognizable
+content is used for files with unknown extensions.
+`--delimiter` applies only to CSV.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | All controls match, or `make` / `demo` completed |
+| `1` | The export was read, but integrity differences were found |
+| `2` | Invalid input, command usage or an I/O error |
+
+Normal JSON reports contain `schema_version`, `ok`, `passed`, `total`, `input`,
+`issues` and non-failing `observations`.
+For input or I/O errors, `check --json` writes `{"error": "..."}` to stdout and
+exits 2. Argument-parsing errors use the usual stderr usage message. Human
+reports escape terminal control characters and characters the output encoding
+cannot represent. JSON escapes preserve the original Unicode values.
+
+## Supported formats
+
+| Operation | Format |
+| --- | --- |
+| Generate / check | CSV, TSV, JSON array of objects, JSONL, XLSX |
+| Input encoding | UTF-8, UTF-16/32 with BOM; explicit `--encoding` for legacy text |
+| Report | Human-readable text, versioned JSON or standalone HTML |
+
+See [reports and batch checks](docs/reporting.md) for diagnostic fields, the
+packaged JSON Schema, `--strict-order`, exclusive `--report` exports and batch
+exit-code precedence.
+
+The [compatibility matrix](docs/compatibility.md) separates deterministic parser
+fixtures from actual Excel observations and unverified application workflows.
+
+CSV quoting, embedded delimiters, escaped double quotes and embedded line
+breaks are parsed. Line breaks **inside values** are compared exactly, including
+the difference between LF, CR and CRLF. Record terminators may vary.
+
+Use `--format` when the extension/content is ambiguous. XLSX uses one worksheet
+and stores generated strings as literal text; returned formulas are refused
+without evaluation. CSV/TSV can still be interpreted as formulas by external
+spreadsheet applications. See [formats and custom probes](docs/formats.md) and
+[the format and resource limits](docs/limitations.md).
+
+## What it detects
+
+The controls cover leading zeros, large integers, scientific notation, decimal
+formatting, signed values, an international phone number, date/time-like text,
+boolean/null-like strings, empty strings, spaces, tabs, newlines, punctuation,
+Unicode, emoji and formula-like text.
+
+It also reports missing, duplicated and unexpected records, non-text IDs and
+missing required fields. A valid export with no records reports 24 missing
+controls. Blank CSV records are reported rather than discarded. Duplicate CSV
+headers, extra CSV fields, duplicate JSON object keys and nonstandard JSON
+constants such as `NaN` are rejected as invalid input.
+
+The preserved-value count measures matching known controls; extra or duplicate
+rows can therefore produce a failing report showing `24/24`. Always use the
+exit code or JSON `ok` field to decide whether the check passed.
+
+## Limitations
+
+A pass applies to **these controls in this specific workflow**. It does not
+prove that an entire real dataset is intact, that formulas never ran, or that
+an application is secure. A formula-like string being changed does not establish
+why it changed. Intentional normalization is reported as a difference.
+
+The application must support export or read-back and preserve the two probe
+columns. A rejected import is inconclusive; its schema may legitimately reject
+some controls. RowCanary has no application integrations and does not inspect
+an importer's internal storage. See [limitations](docs/limitations.md) and
+[security guidance](SECURITY.md).
+
+## How it works
+
+`make` writes the deterministic controls defined in `rowcanary/core.py`.
+`check` reads the bounded UTF-8 export, matches records by their stable IDs and
+compares each value as an exact string. Input order is irrelevant. JSON numeric
+tokens retain their original spelling for diagnostics and remain numbers for
+comparison; they are never silently converted into strings. The CLI wraps
+these checks with text/JSON reports and exit codes.
+
+All processing stays local. There are no network calls, accounts or telemetry.
+XLSX support uses openpyxl and defusedxml.
+
+## Development
+
+From the source directory:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+python -m ruff check .
+python -m build
+python -m twine check dist/*
+python tools/check_package.py dist
+```
+
+The tests use the standard library. GitHub Actions is configured for Ubuntu,
+Windows and macOS on Python 3.10–3.14, plus package and static checks. The
+[verification report](docs/verification.md) distinguishes executed checks from
+pending hosted CI and third-party application tests.
+
+The existing flat `rowcanary/` package is retained. `tests/` contains regression
+tests, `examples/` contains clean and deliberately altered fixtures, and
+`assets/` contains genuine vector masters and their PNG exports. See
+[asset provenance and regeneration](assets/README.md).
+
+## Contributing
+
+Reproducible data-change cases and focused improvements are welcome. Read
+[CONTRIBUTING.md](CONTRIBUTING.md). Use synthetic data in reports and never
+include customer records or credentials. Report security issues through the
+process in [SECURITY.md](SECURITY.md).
+
+## License
+
+RowCanary is distributed under the [MIT license](LICENSE). The social preview
+uses outlined Noto Sans glyphs; its [font license](assets/FONT-LICENSE.txt) is
+included.
+
+Reusable JSON options, Python API and batch/Actions examples: [integration guide](docs/integrations.md).
+
+Start here: [first control check and troubleshooting](docs/quickstart.md).