Metadata-Version: 2.4
Name: SpecGo
Version: 1.0.2
Summary: Import CAN DBC files, generate C codecs, and verify raw roundtrips.
Author-email: Ce Xu <dylanalexxc@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/specgo-dev/SpecGo
Project-URL: Repository, https://github.com/specgo-dev/SpecGo
Keywords: embedded,protocol,can,dbc,codegen,code-generation,validation,testing,property-testing,toolchain
Classifier: Development Status :: 7 - Inactive
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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 :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: cantools>=39.0
Requires-Dist: jinja2>=3.1.2
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Dynamic: license-file

# SpecGo

> Status: paused. The DBC-to-C path works, but I am not actively adding features.

SpecGo is a small CLI project I built while learning how embedded protocol
tooling can be made easier to check. The original idea was much bigger: import
different kinds of protocol documents, turn them into one IR, generate code,
and let an agent improve the result.

I did not finish that whole idea. What I did finish is a narrower pipeline for
CAN DBC files:

```text
DBC -> YAML IR -> validation -> C encode/decode -> compile gate -> roundtrip test
```

The useful part of the project is not that it generates C. It is that the
generated code is checked against the same IR with deterministic gates and
repeatable random seeds.

## What Works

- Import a CAN DBC file with `cantools`.
- Store the result as a versioned Pydantic/YAML IR.
- Check CAN IDs, DLC, signal bounds, overlap, enum values, scale, and duplicate names.
- Generate raw-value C encoders and decoders with Jinja2.
- Regenerate artifacts and compare hashes to catch nondeterministic output.
- Compile generated C with GCC, Clang, or MSVC.
- Load the compiled library with Python `ctypes` and run seeded roundtrip tests.
- Save the master seed, loop seeds, toolchain details, and failures to YAML reports.

The old PDF/text import, LLM agent, replay, wrapper generation, and differential
testing code is unfinished and not exposed by the CLI. The separate Agent, LLM,
replay, and report prototype packages are also left out of the published wheel.

## Install

SpecGo requires Python 3.11 or newer. A C compiler is also needed for the
compile gate and roundtrip test.

```bash
python -m pip install SpecGo
specgo --version
```

For local development:

```bash
git clone https://github.com/specgo-dev/SpecGo.git
cd SpecGo
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
```

## Try The Pipeline

The repository includes small, made-up DBC files under `tests/`. They do not
come from a vehicle database.

```bash
# 1. DBC -> IR
specgo ing tests/template_valid_sanitized.dbc -f

# 2. Schema and semantic validation
specgo val specgo_output/output/template_valid_sanitized.ir.yaml

# 3. Generate C and header files
specgo gen specgo_output/output/template_valid_sanitized.ir.yaml

# 4. Check file presence, deterministic output, and C compilation
specgo gate specgo_output/output/template_valid_sanitized.ir.yaml

# 5. Call the generated C functions from Python and test both directions
specgo rt \
  -i "specgo_output/output/template_valid_sanitized.ir.yaml" \
  -a specgo_output/gen \
  -n 10
```

By default, generated files go to `specgo_output/gen/` and roundtrip reports go
to `specgo_output/raw_reports/`. Pass `-m <seed>` to replay a run with a known
master seed.

Useful short commands:

| Command | Purpose |
| --- | --- |
| `specgo start` | Create project-local `.specgo` metadata |
| `specgo ing` | Import DBC into IR |
| `specgo val` | Validate IR |
| `specgo gen` | Generate C/H files |
| `specgo gate` | Check generated artifacts |
| `specgo rt` | Run seeded C roundtrip tests |
| `specgo cfg` | Read or update workspace configuration |

Run `specgo <command> --help` for all options.

## Intentional Failure Fixtures

- `tests/template_invalid_semantic_sanitized.dbc` should fail semantic validation.
- `tests/template_roundtrip_mismatch_sanitized.dbc` and
  `tests/roundtrip_mismatch_artifacts/` should fail the roundtrip test.
- `tests/template_broken_parser_demo.c` is intentionally invalid C.

These files are here to show that the gates fail when they should, not only
that the happy path passes.

## Limits

- C output uses raw integer values. Physical scale/offset conversion is not generated.
- Signals are limited to 64 bits.
- Multiplexed DBC messages are not supported as a separate code-generation model.
- Only C code generation is implemented.
- The roundtrip runner loads generated native code into the Python process.
  Only test generated or otherwise trusted C artifacts.
- This was a learning project, not a safety-certified protocol stack.

## Development Checks

```bash
python -m pytest
python -m build
python -m twine check dist/*
```

Package version metadata has one source: `specgo.__version__`. This avoids
building a wheel whose filename and runtime version disagree.

## Why I Paused It

The DBC core was a useful exercise in IR design, code generation, native
bindings, and reproducible testing. The next features would need a much larger
scope: multiplexing, physical-value semantics, replay traces, and guarded LLM
changes. I would rather leave the current boundary clear than present those
unfinished experiments as working features.

Licensed under Apache-2.0.
