canvouch 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. canvouch-0.2.1/CONTRIBUTING.md +56 -0
  2. canvouch-0.2.1/Dockerfile +45 -0
  3. canvouch-0.2.1/LICENSE +21 -0
  4. canvouch-0.2.1/MANIFEST.in +9 -0
  5. canvouch-0.2.1/PKG-INFO +313 -0
  6. canvouch-0.2.1/README.md +270 -0
  7. canvouch-0.2.1/SECURITY.md +23 -0
  8. canvouch-0.2.1/canvouch.egg-info/PKG-INFO +313 -0
  9. canvouch-0.2.1/canvouch.egg-info/SOURCES.txt +95 -0
  10. canvouch-0.2.1/canvouch.egg-info/dependency_links.txt +1 -0
  11. canvouch-0.2.1/canvouch.egg-info/entry_points.txt +3 -0
  12. canvouch-0.2.1/canvouch.egg-info/requires.txt +21 -0
  13. canvouch-0.2.1/canvouch.egg-info/top_level.txt +3 -0
  14. canvouch-0.2.1/cli/__init__.py +1 -0
  15. canvouch-0.2.1/cli/main.py +804 -0
  16. canvouch-0.2.1/config.schema.json +443 -0
  17. canvouch-0.2.1/crc_checker/__init__.py +3 -0
  18. canvouch-0.2.1/crc_checker/bit_utils.py +167 -0
  19. canvouch-0.2.1/crc_checker/config.py +854 -0
  20. canvouch-0.2.1/crc_checker/core/__init__.py +17 -0
  21. canvouch-0.2.1/crc_checker/core/models.py +103 -0
  22. canvouch-0.2.1/crc_checker/crc/__init__.py +7 -0
  23. canvouch-0.2.1/crc_checker/crc/classify.py +151 -0
  24. canvouch-0.2.1/crc_checker/crc/custom.py +36 -0
  25. canvouch-0.2.1/crc_checker/crc/engine.py +233 -0
  26. canvouch-0.2.1/crc_checker/crc/models.py +18 -0
  27. canvouch-0.2.1/crc_checker/crc/presets.py +144 -0
  28. canvouch-0.2.1/crc_checker/crc/profiles.py +152 -0
  29. canvouch-0.2.1/crc_checker/data/dataid_mappings.yaml +74 -0
  30. canvouch-0.2.1/crc_checker/data/patterns.yaml +40 -0
  31. canvouch-0.2.1/crc_checker/dataid/__init__.py +19 -0
  32. canvouch-0.2.1/crc_checker/dataid/excel.py +381 -0
  33. canvouch-0.2.1/crc_checker/dataid/mappings.py +144 -0
  34. canvouch-0.2.1/crc_checker/dataid/matching.py +71 -0
  35. canvouch-0.2.1/crc_checker/dataid/models.py +214 -0
  36. canvouch-0.2.1/crc_checker/dataid/multi.py +78 -0
  37. canvouch-0.2.1/crc_checker/dataid/parser.py +65 -0
  38. canvouch-0.2.1/crc_checker/dataid/rows.py +268 -0
  39. canvouch-0.2.1/crc_checker/dbc/__init__.py +11 -0
  40. canvouch-0.2.1/crc_checker/dbc/models.py +692 -0
  41. canvouch-0.2.1/crc_checker/dbc/parser.py +243 -0
  42. canvouch-0.2.1/crc_checker/dbc/resolver.py +288 -0
  43. canvouch-0.2.1/crc_checker/env.py +19 -0
  44. canvouch-0.2.1/crc_checker/errors.py +24 -0
  45. canvouch-0.2.1/crc_checker/file_types.py +9 -0
  46. canvouch-0.2.1/crc_checker/patterns.py +201 -0
  47. canvouch-0.2.1/crc_checker/protect/__init__.py +7 -0
  48. canvouch-0.2.1/crc_checker/protect/base.py +52 -0
  49. canvouch-0.2.1/crc_checker/protect/checksum.py +146 -0
  50. canvouch-0.2.1/crc_checker/protect/rolling_counter.py +216 -0
  51. canvouch-0.2.1/crc_checker/report/__init__.py +5 -0
  52. canvouch-0.2.1/crc_checker/report/html.py +868 -0
  53. canvouch-0.2.1/crc_checker/report/serializer.py +109 -0
  54. canvouch-0.2.1/crc_checker/report/trends.py +376 -0
  55. canvouch-0.2.1/crc_checker/trace/__init__.py +6 -0
  56. canvouch-0.2.1/crc_checker/trace/models.py +5 -0
  57. canvouch-0.2.1/crc_checker/trace/reader.py +218 -0
  58. canvouch-0.2.1/crc_checker/verify/__init__.py +6 -0
  59. canvouch-0.2.1/crc_checker/verify/cancellation.py +38 -0
  60. canvouch-0.2.1/crc_checker/verify/engine.py +164 -0
  61. canvouch-0.2.1/crc_checker/verify/models.py +147 -0
  62. canvouch-0.2.1/crc_checker/verify/runner.py +390 -0
  63. canvouch-0.2.1/docs/screenshots/report.png +0 -0
  64. canvouch-0.2.1/docs/screenshots/web-ui-result.png +0 -0
  65. canvouch-0.2.1/docs/screenshots/web-ui.png +0 -0
  66. canvouch-0.2.1/docs/supported-algorithms.md +47 -0
  67. canvouch-0.2.1/docs/web-api.md +275 -0
  68. canvouch-0.2.1/docs/zh-CN/README.md +259 -0
  69. canvouch-0.2.1/pyproject.toml +75 -0
  70. canvouch-0.2.1/setup.cfg +4 -0
  71. canvouch-0.2.1/tests/test_audit_leftovers.py +159 -0
  72. canvouch-0.2.1/tests/test_bit_utils.py +71 -0
  73. canvouch-0.2.1/tests/test_bugfix_regressions.py +964 -0
  74. canvouch-0.2.1/tests/test_cli_gating.py +309 -0
  75. canvouch-0.2.1/tests/test_config.py +113 -0
  76. canvouch-0.2.1/tests/test_config_schema.py +83 -0
  77. canvouch-0.2.1/tests/test_configuration.py +132 -0
  78. canvouch-0.2.1/tests/test_crc_classify.py +211 -0
  79. canvouch-0.2.1/tests/test_crc_engine.py +257 -0
  80. canvouch-0.2.1/tests/test_dataid.py +181 -0
  81. canvouch-0.2.1/tests/test_dbc_resolver.py +556 -0
  82. canvouch-0.2.1/tests/test_e2e_profiles.py +437 -0
  83. canvouch-0.2.1/tests/test_rc_trends.py +443 -0
  84. canvouch-0.2.1/tests/test_report_html.py +189 -0
  85. canvouch-0.2.1/tests/test_trace_reader.py +99 -0
  86. canvouch-0.2.1/tests/test_verify_engine.py +147 -0
  87. canvouch-0.2.1/tests/test_webapp.py +1190 -0
  88. canvouch-0.2.1/webapp/__init__.py +6 -0
  89. canvouch-0.2.1/webapp/catalog.py +309 -0
  90. canvouch-0.2.1/webapp/main.py +602 -0
  91. canvouch-0.2.1/webapp/paths.py +34 -0
  92. canvouch-0.2.1/webapp/schemas.py +100 -0
  93. canvouch-0.2.1/webapp/service.py +856 -0
  94. canvouch-0.2.1/webapp/static/dist/assets/index-CmxDn-IB.js +81 -0
  95. canvouch-0.2.1/webapp/static/dist/assets/index-D2k6H3kk.css +1 -0
  96. canvouch-0.2.1/webapp/static/dist/index.html +13 -0
  97. canvouch-0.2.1/webapp/version.py +114 -0
@@ -0,0 +1,56 @@
1
+ # Contributing
2
+
3
+ Thanks for taking the time to improve CanVouch.
4
+
5
+ ## Setup
6
+
7
+ ```bash
8
+ pip install -r requirements.txt
9
+ pip install -e .
10
+
11
+ cd frontend
12
+ npm ci
13
+ ```
14
+
15
+ The bundled example is the only project data in the repository (it is
16
+ generated by `examples/generate_example.py`); never commit customer traces,
17
+ DBC files or DataID workbooks.
18
+
19
+ ## Local checks
20
+
21
+ Run the same gates CI runs before opening a pull request:
22
+
23
+ ```bash
24
+ pytest --tb=short --cov=crc_checker --cov=cli --cov=webapp \
25
+ --cov-report=term --cov-fail-under=80
26
+ pylint $(git ls-files '*.py') # must stay at 10.00/10
27
+
28
+ cd frontend
29
+ npm run lint
30
+ npm run format:check
31
+ npm test
32
+ npm run test:component
33
+ npm run build # also mirrors dist into webapp/static/dist
34
+ ```
35
+
36
+ `pylint` is pinned in `requirements.txt` (3.3.9) so the pre-push hook and CI
37
+ agree. CI additionally runs Python 3.11/3.12/3.13, Windows, the wheel smoke
38
+ test and the committed-`dist` freshness check.
39
+
40
+ ## Conventions
41
+
42
+ - Code comments, docstrings and CLI messages are English.
43
+ - User-facing product text is Chinese: the HTML report, the web UI and web API
44
+ error messages. The tests assert those literals byte-for-byte.
45
+ - Signal-name conventions live in `crc_checker/data/patterns.yaml`; DataID
46
+ workbook layouts live in `crc_checker/data/dataid_mappings.yaml`. Add a
47
+ configuration entry before adding code.
48
+ - New CRC algorithm: add a preset to `crc_checker/crc/presets.py`, its
49
+ validation status, and a known-answer test.
50
+
51
+ ## Pull requests
52
+
53
+ - Keep the change focused; describe the failure it fixes or the capability it
54
+ adds.
55
+ - Add or update tests for behavior changes.
56
+ - Run the local checks above (the pre-push hook runs the backend ones).
@@ -0,0 +1,45 @@
1
+ # syntax=docker/dockerfile:1
2
+ FROM python:3.14-slim AS builder
3
+
4
+ ENV PIP_NO_CACHE_DIR=1 \
5
+ PIP_DISABLE_PIP_VERSION_CHECK=1
6
+ WORKDIR /src
7
+
8
+ # Build a wheel from the checkout. The committed frontend dist is bundled into
9
+ # the wheel, so Node is not needed in the image.
10
+ COPY . .
11
+ RUN python -m pip install --upgrade pip \
12
+ && python -m pip wheel --wheel-dir /wheels ".[web,mf4]"
13
+
14
+
15
+ FROM python:3.14-slim
16
+
17
+ ENV PYTHONDONTWRITEBYTECODE=1 \
18
+ PYTHONUNBUFFERED=1 \
19
+ CANVOUCH_DATA_DIR=/data \
20
+ CANVOUCH_PROJECTS_DIR=/app/examples
21
+
22
+ ARG GIT_COMMIT=""
23
+ ENV CANVOUCH_GIT_COMMIT=${GIT_COMMIT}
24
+
25
+ WORKDIR /app
26
+
27
+ COPY --from=builder /wheels /wheels
28
+ RUN python -m pip install --no-cache-dir --no-index --find-links=/wheels \
29
+ "canvouch[web,mf4]" \
30
+ && rm -rf /wheels
31
+
32
+ # Demo project (synthetic data only) so the catalog is not empty.
33
+ COPY --from=builder /src/examples /app/examples
34
+
35
+ # Run as a non-root user; /data is the writable runtime store.
36
+ RUN useradd --create-home --uid 10001 appuser \
37
+ && mkdir -p /data \
38
+ && chown -R appuser:appuser /app /data
39
+ USER appuser
40
+
41
+ EXPOSE 8000
42
+ HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
43
+ CMD python -c "import os, urllib.request; req = urllib.request.Request('http://127.0.0.1:8000/api/limits', headers={'X-API-Token': os.environ.get('CANVOUCH_API_TOKEN', '')}); urllib.request.urlopen(req, timeout=3)" || exit 1
44
+
45
+ CMD ["uvicorn", "webapp.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]
canvouch-0.2.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CAN CRC Checker contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,9 @@
1
+ include LICENSE
2
+ include README.md
3
+ include CONTRIBUTING.md
4
+ include SECURITY.md
5
+ include Dockerfile
6
+ include config.schema.json
7
+
8
+ recursive-include crc_checker/data *.yaml
9
+ recursive-include docs *.md *.png
@@ -0,0 +1,313 @@
1
+ Metadata-Version: 2.4
2
+ Name: canvouch
3
+ Version: 0.2.1
4
+ Summary: DBC-aware CRC, rolling-counter and E2E protection verification for CAN traces
5
+ Author: CanVouch contributors
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/zhaojiale2021/canvouch
8
+ Project-URL: Repository, https://github.com/zhaojiale2021/canvouch
9
+ Project-URL: Issues, https://github.com/zhaojiale2021/canvouch/issues
10
+ Project-URL: Changelog, https://github.com/zhaojiale2021/canvouch/releases
11
+ Keywords: can,can-bus,dbc,crc,e2e,automotive,trace
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development :: Quality Assurance
20
+ Classifier: Topic :: Software Development :: Testing
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: python-can>=4.5
25
+ Requires-Dist: canmatrix>=1.1
26
+ Requires-Dist: click>=8.1
27
+ Requires-Dist: openpyxl>=3.0
28
+ Requires-Dist: xlrd>=2.0
29
+ Requires-Dist: PyYAML>=6.0
30
+ Provides-Extra: web
31
+ Requires-Dist: fastapi>=0.110; extra == "web"
32
+ Requires-Dist: uvicorn>=0.29; extra == "web"
33
+ Requires-Dist: python-multipart>=0.0.9; extra == "web"
34
+ Provides-Extra: mf4
35
+ Requires-Dist: python-can[mf4]>=4.5; extra == "mf4"
36
+ Provides-Extra: dev
37
+ Requires-Dist: pytest>=8; extra == "dev"
38
+ Requires-Dist: pytest-cov; extra == "dev"
39
+ Requires-Dist: httpx>=0.27; extra == "dev"
40
+ Requires-Dist: jsonschema>=4; extra == "dev"
41
+ Requires-Dist: pylint==4.1.3; extra == "dev"
42
+ Dynamic: license-file
43
+
44
+ <div align="center">
45
+
46
+ # CanVouch
47
+
48
+ *Every frame vouched for.*
49
+
50
+ DBC-aware CAN bus CRC / rolling-counter verification for BLF, ASC, MF4 and TRC traces.
51
+
52
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
53
+ [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
54
+ [![CI](https://github.com/zhaojiale2021/canvouch/actions/workflows/ci.yml/badge.svg)](https://github.com/zhaojiale2021/canvouch/actions/workflows/ci.yml)
55
+
56
+ [English](./README.md) | [🌍 中文](./docs/zh-CN/README.md)
57
+
58
+ </div>
59
+
60
+ ---
61
+
62
+ | Web UI | Verification result | Self-contained HTML report |
63
+ | --- | --- | --- |
64
+ | ![Web UI](docs/screenshots/web-ui.png) | ![Verification result](docs/screenshots/web-ui-result.png) | ![HTML report](docs/screenshots/report.png) |
65
+
66
+ ---
67
+
68
+ Point it at a DBC and a captured trace. It finds the checksum and rolling-counter
69
+ signals by name, computes the expected values with the configured algorithm, and
70
+ reports every mismatch with a self-contained HTML report. No vehicle-specific
71
+ code: signal-name patterns and DataID workbook layouts are configuration files.
72
+
73
+ The repository ships **only synthetic example data**.
74
+
75
+ ## 🚀 30-second start
76
+
77
+ ```bash
78
+ git clone https://github.com/zhaojiale2021/canvouch.git
79
+ cd canvouch
80
+ pip install -r requirements.txt
81
+
82
+ # Run the bundled example (CLI; no packaging step, no .exe)
83
+ python -m cli.main run -c examples/example/config.json -v
84
+
85
+ # Optional: install the `canvouch` command
86
+ pip install -e .
87
+ canvouch run -c examples/example/config.json -v
88
+ canvouch presets
89
+ canvouch inspect examples/example/dbc/network.dbc
90
+ ```
91
+
92
+ Expected output: 160 frames, 320 checks, 100 % pass.
93
+
94
+ ```bash
95
+ # Deliberately broken example → failures + RC error trends
96
+ python -m cli.main run -c examples/example/config_bad.json -v
97
+ ```
98
+
99
+ Table output lists failures only by default; add `--show-all` to print every
100
+ verdict. Use it as a gate: `--fail-on-failure` exits 1 on any failed check, and
101
+ `--min-pass-rate 99.5` exits 1 below the threshold (both also work on
102
+ `canvouch verify`; the pre-rename `crc-check` command still works as an alias).
103
+
104
+ ```bash
105
+ canvouch run -c examples/example/config.json --fail-on-failure
106
+ ```
107
+
108
+ MF4/MDF traces need python-can's optional reader; `requirements.txt` already
109
+ installs it. For a bare `pip install -e .`, add it with
110
+ `pip install "python-can[mf4]"` (or `pip install -e ".[mf4]"`).
111
+
112
+ ### Docker
113
+
114
+ ```bash
115
+ docker build -t canvouch .
116
+ docker run --rm -p 8000:8000 canvouch
117
+ ```
118
+
119
+ The image bundles the synthetic example project and serves the web UI on port
120
+ 8000. Pushing a `v*` tag runs `release.yml`, which verifies the tag against
121
+ `crc_checker.__version__`, runs the test suite, and publishes the wheel to PyPI
122
+ and the image to GHCR (the PyPI trusted publisher must be configured once in
123
+ the repository settings).
124
+
125
+ ## 🌐 Web version
126
+
127
+ ```bash
128
+ ./run_web.sh 8000 # Windows: run_web.bat 8000
129
+ # http://127.0.0.1:8000
130
+ ```
131
+
132
+ Two ways to run: pick a **project id**, or switch to **manual mode** and upload
133
+ DBC file(s) + a trace (plus an optional DataID file), then fill in the config
134
+ options (algorithm, range, DataID layout, filters) on the page. A project's
135
+ bundled sample traces are one click away — no download-then-upload detour.
136
+ The browser only sends project ids or uploaded files; paths stay server-side.
137
+ Set `CANVOUCH_API_TOKEN` to require `X-API-Token` (or `Authorization: Bearer`)
138
+ on every `/api/*` call; the value is entered in the UI's version dialog and kept
139
+ in the browser's localStorage. Upload caps: 200 MB per file and 400 MB per
140
+ request by default (`CANVOUCH_MAX_UPLOAD_MB` / `CANVOUCH_MAX_REQUEST_MB`).
141
+ Projects are scanned from `projects/` (or `examples/` when `projects/` does not
142
+ exist; override with `CANVOUCH_PROJECTS_DIR`). The Vue frontend is committed
143
+ as `frontend/dist`, so a deployment machine needs no Node. The launcher binds to
144
+ `127.0.0.1` by default; set `CANVOUCH_WEB_HOST` or pass a host argument to opt into
145
+ LAN binding. The web server has no authentication, so network exposure should be
146
+ behind an authenticated reverse proxy or equivalent access controls. See
147
+ [docs/web-api.md](docs/web-api.md).
148
+
149
+ Server environment variables use the `CANVOUCH_` prefix (`CANVOUCH_DATA_DIR`, `CANVOUCH_PROJECTS_DIR`, `CANVOUCH_API_TOKEN`, `CANVOUCH_MAX_UPLOAD_MB`, `CANVOUCH_MAX_REQUEST_MB`); the pre-rename `CRC_CHECKER_*` / `CRC_WEB_*` names are still accepted as fallbacks.
150
+
151
+ ## 🌟 What you get
152
+
153
+ | When you need… | What it does |
154
+ | --- | --- |
155
+ | **Find protection signals automatically** | Prefix (`Checksum_*`, `CRC_*`) and suffix (`*_CRC`, `*_Counter`) naming, indexed E2E instances, sensor bus markers, block-counter exclusion — all driven by YAML regexes |
156
+ | **Verify E2E profiles** | Profile 5 (CRC16/CCITT, DataID append, byte swap) and Profile 1/1A (CRC8/SAE-J1850-ZERO, DataID prepend, 4-bit counter) |
157
+ | **Non-CRC checksums** | SUM8, SUM8/XOR-FF, XOR8/SEED, selected per message from DBC comments |
158
+ | **Many trace formats** | BLF, ASC, MF4, TRC, CSV/LOG via python-can (MF4 via the `python-can[mf4]` extra) |
159
+ | **Big traces** | Streaming verification, cached CRC engines, decimated RC trend charts, report size guard |
160
+ | **CI gating** | `--fail-on-failure` / `--min-pass-rate`; the frame cap is never silent |
161
+ | **DataID tables** | `.xlsx`, legacy `.xls` and preprocessed JSON; named column layouts from YAML |
162
+ | **Reproducible results** | CLI and web share one runner (`crc_checker/verify/runner.py`) |
163
+
164
+ ## 🧮 Supported algorithms
165
+
166
+ Verified with real data means the algorithm reproduced expected values on
167
+ captured CAN traces during development. Everything else is implemented and
168
+ unit-tested against known-answer vectors, but **not verified with real data** —
169
+ `canvouch presets` prints the same status.
170
+
171
+ | Preset | Use | Status |
172
+ | --- | --- | --- |
173
+ | `CRC16/CCITT` | AUTOSAR E2E Profile 5 | ✅ verified with real data |
174
+ | `CRC8/SAE-J1850-ZERO` | AUTOSAR E2E Profile 1 / 1A | ✅ verified with real data |
175
+ | `CRC8/SAE-J1850` | DBC-comment checksums | ✅ verified with real data |
176
+ | `SUM8/XOR-FF` | sum of bytes `& 0xFF`, then `XOR 0xFF` | ✅ verified with real data |
177
+ | `XOR8/SEED` | byte-wise XOR with a constant seed | ✅ verified with real data |
178
+ | `SUM8` | plain additive sum `& 0xFF` | ✅ verified (wider variants unverified) |
179
+ | `CRC8/AUTOSAR`, `CRC8/H2F`, `CRC16/ARC`, `CRC16/MODBUS`, `CRC32/AUTOSAR`, `CRC32/ETHERNET`, `XOR8` | — | ⚠️ not verified with real data |
180
+
181
+ Details and promotion checklist: [docs/supported-algorithms.md](docs/supported-algorithms.md).
182
+
183
+ ## 🧩 Extending without code changes
184
+
185
+ **New signal naming** — add a regex to
186
+ [`crc_checker/data/patterns.yaml`](crc_checker/data/patterns.yaml):
187
+
188
+ ```yaml
189
+ checksum:
190
+ prefix: ['(?i)^(checksum|check_sum|crc|e2e_crc)']
191
+ suffix: ['(?i)(_crc|_checksum|_chks)([0-9_]*)$']
192
+ rolling_counter:
193
+ prefix: ['(?i)^(rolling.?counter|rc_|alive.?counter)']
194
+ suffix: ['(?i)(_counter|_cntr|_msgcntr)([0-9_]*)$']
195
+ exclude: ['(?i)block_?counter']
196
+ ```
197
+
198
+ Or point `signals.patterns_file` at your own YAML, or use
199
+ `signals.checksum_patterns` / `signals.rc_patterns` inline.
200
+
201
+ **New DataID workbook layout** — add a named mapping to
202
+ [`crc_checker/data/dataid_mappings.yaml`](crc_checker/data/dataid_mappings.yaml),
203
+ then select it with `dataid.mapping`. Use `dataid.mapping_file` for a separate
204
+ file. Built-in names: `hi_lo_two_cols`, `single_16bit`, `generic_abc`,
205
+ `simple_8bit`, `description_regex`.
206
+
207
+ **New project** — put `config.json` (+ DBC / DataID / trace) under `projects/`.
208
+
209
+ ### Generate a project config with an AI assistant
210
+
211
+ Copy this prompt and attach or provide the DBC, trace, and optional DataID files:
212
+
213
+ ```text
214
+ Create a CanVouch project configuration for my CAN data.
215
+
216
+ Please:
217
+ 1. Identify the DBC file(s), trace file(s), and optional DataID Excel/JSON input.
218
+ 2. Inspect the DBC protection signals and suggest a CRC preset, range, and DataID layout.
219
+ 3. Produce `config.json` with paths, algorithm settings, frame filters, and HTML output.
220
+ 4. Keep every input path relative to the generated config file.
221
+ 5. Add comments explaining assumptions that need checking.
222
+ 6. Validate the final JSON and report the exact `canvouch run -c <config> -v` command.
223
+ ```
224
+
225
+ ## ⚙️ Configuration
226
+
227
+ A run is a JSON file (`canvouch gen-config` writes an annotated example). The
228
+ main sections:
229
+
230
+ | Section | Field | Description |
231
+ | --- | --- | --- |
232
+ | top level | `dbc` / `dbcs` | One DBC path, or a list of files/directories |
233
+ | | `dbc_merge` | Merge several DBCs into one map instead of selecting per trace channel |
234
+ | `crc` | `preset` | Preset name, or `custom` for inline parameters |
235
+ | | `byte_swap` | Swap computed CRC bytes (Profile 5) |
236
+ | | `auto_classify` | Pick the algorithm per message from DBC comments |
237
+ | | `profile_by_width` | 2-byte CRC → Profile 5, 1-byte → Profile 1 |
238
+ | | `profiles` | Per-profile overrides (algorithm, DataID layout, range, counter max) |
239
+ | | `range_overrides` / `skip` | Per-message range / unverified signals |
240
+ | `range` | `mode` | `exclude_crc` / `full_payload` / `custom_range` |
241
+ | | `start_byte` / `end_byte` | Range for `custom_range` (`-1` = end of payload) |
242
+ | `dataid` | `json` / `xlsx` | Preprocessed JSON (fast) or Excel workbook |
243
+ | | `mapping` / `mapping_file` | DataID column layout |
244
+ | | `position` / `byte_order` / `default` | `prepend`/`append`, `lo_hi`/`hi_lo`, fallback DataID |
245
+ | `signals` | `patterns_file` | Custom signal-name YAML |
246
+ | | `checksum_pattern(s)` / `rc_pattern(s)` | Regex overrides |
247
+ | `filter` | `frame_ids` / `max_frames` | CAN ID filter; frame cap (`0` = unlimited, default 6000) |
248
+ | `rc` | `max_valid` | Max valid counter value (default `2^bits - 1`) |
249
+ | `output` | `format` / `file` / `only_failures` | `table` or `html`, path, failures-only view |
250
+ | | `max_report_sections` | Frame-section cap (default 30 000, 0 = unlimited) |
251
+
252
+ Full schema: `crc_checker/config.py` (`CONFIG_SCHEMA_DOC`). Editors can use
253
+ [`config.schema.json`](config.schema.json) for completion and validation
254
+ (`"$schema": "./config.schema.json"` in your config file).
255
+
256
+ ## 📁 Repository layout
257
+
258
+ ```
259
+ crc_checker/ Core package
260
+ crc/ CRC engine, presets, E2E profiles, comment classifier
261
+ dbc/ DBC parser + signal resolver
262
+ dataid/ DataID Excel/JSON parser
263
+ trace/ Trace reader (BLF/ASC/MF4/TRC/CSV)
264
+ protect/ CRC and rolling-counter verifiers
265
+ verify/ Verification orchestration (shared by CLI and web)
266
+ report/ Self-contained HTML report + RC trend charts
267
+ data/ Shipped pattern and DataID-mapping defaults
268
+ cli/ Click CLI (python -m cli.main)
269
+ webapp/ FastAPI backend
270
+ frontend/ Vue 3 + Element Plus (dist committed)
271
+ examples/ Synthetic example project + generator
272
+ tests/ pytest suite
273
+ ```
274
+
275
+ ## 🧪 Development
276
+
277
+ ```bash
278
+ pytest --tb=short --cov=crc_checker --cov=cli --cov=webapp \
279
+ --cov-report=term --cov-fail-under=80 # CI backend test command
280
+ pylint $(git ls-files '*.py') # must stay 10.00/10
281
+ cd frontend && npm run lint # eslint
282
+ cd frontend && npm run format:check # prettier
283
+ cd frontend && npm test # node --test (pure logic)
284
+ cd frontend && npm run test:component # vitest (@vue/test-utils)
285
+ cd frontend && npm ci && npm run build # rebuild committed dist
286
+ python examples/generate_example.py # regenerate the example
287
+ ```
288
+
289
+ CI runs pylint and coverage-gated pytest on Python 3.11, 3.12 and 3.13, plus a
290
+ Windows pytest job and frontend lint/tests/build freshness checks. The pre-push
291
+ hook runs pylint and the same 80%-coverage backend pytest command using Python
292
+ 3.11 when `uv` is installed; otherwise it uses the active Python environment.
293
+ It does not replace the full CI matrix or frontend checks.
294
+
295
+ ## 🤝 Contributing
296
+
297
+ Issues and pull requests are welcome. Before opening a PR, run the development
298
+ checks above; CI additionally covers the Python matrix, Windows, frontend
299
+ checks, and committed-`dist` freshness.
300
+
301
+ ## 📄 License
302
+
303
+ MIT. See [LICENSE](./LICENSE).
304
+
305
+ ---
306
+
307
+ <div align="center">
308
+
309
+ **DBC in, trace in, verdicts out — no customer-specific code paths.**
310
+
311
+ [⭐ Star us on GitHub](https://github.com/zhaojiale2021/canvouch) · [🐛 Report Issues](https://github.com/zhaojiale2021/canvouch/issues)
312
+
313
+ </div>