Jerry
102 lines
3.8 KiB
Markdown
102 lines
3.8 KiB
Markdown
# Translator Backend Contract
|
|
|
|
This contract defines the package structure and dependency boundaries for every
|
|
SimpleCAD translator backend.
|
|
|
|
## Backend Naming
|
|
|
|
Backend packages live under `simplecadapi.translator` and use the name
|
|
`<backend>_translator`, where `<backend>` is a stable lowercase backend ID.
|
|
|
|
Examples:
|
|
|
|
- `freecad_translator`
|
|
- `openscad_translator`
|
|
- `onshape_translator`
|
|
|
|
Backends are exported explicitly from `simplecadapi.translator`. Importing a
|
|
backend package must not require the target CAD runtime to be installed.
|
|
|
|
## Required Files
|
|
|
|
Every backend package contains:
|
|
|
|
| File | Responsibility |
|
|
| --- | --- |
|
|
| `__init__.py` | Defines the complete public backend surface through `__all__`. |
|
|
| `api.py` | Contains public convenience functions and user-facing error boundaries. |
|
|
| `translator.py` | Contains the `<Backend>Translator` implementation. |
|
|
| `capabilities.py` | Declares backend targets and support for every canonical operation. |
|
|
|
|
The translator class must inherit `BaseTranslator`. `capabilities.py` exports
|
|
`BACKEND_NAME`, `CAPABILITIES`, and `OP_SUPPORT`. The operation support map must
|
|
contain exactly the canonical operation set. Unsupported operations require a
|
|
non-empty reason.
|
|
|
|
## Conditional Files
|
|
|
|
Use these standard names when the corresponding responsibility exists:
|
|
|
|
| File or directory | Responsibility |
|
|
| --- | --- |
|
|
| `exporter.py` | File output, external process or remote API execution, and output validation. |
|
|
| `context.py` | State owned by one translation invocation. |
|
|
| `analysis.py` | Backend-specific graph analysis and lowering decisions. |
|
|
| `codegen.py` | Pure target-code formatting and literal helpers. |
|
|
| `emitters/` | Canonical operation emitters and their single registry. |
|
|
| `runtime/` | Source fragments embedded into an artifact for execution in the target runtime. |
|
|
|
|
An `emitters/registry.py` file is the only operation-to-emitter mapping. Runtime
|
|
fragments must remain valid Python source, must not execute target APIs when the
|
|
SimpleCAD package is imported, and must be assembled in one declared order.
|
|
|
|
## Translation And Export
|
|
|
|
Translation is an in-memory operation. It consumes canonical model JSON or an
|
|
already imported canonical payload and returns a `TranslationArtifact`.
|
|
|
|
Export is an effectful operation. It may write files, invoke an executable, or
|
|
call a remote API. Those effects belong in `exporter.py`, not in the translator
|
|
or emitters.
|
|
|
|
Public naming follows these forms:
|
|
|
|
- `translate_model_json_to_<artifact>` for in-memory conversion.
|
|
- `export_model_json_to_<format>` for file or external-runtime output.
|
|
|
|
Existing public names may remain as compatibility aliases.
|
|
|
|
## Dependencies
|
|
|
|
The allowed dependency direction is:
|
|
|
|
```text
|
|
backend/__init__.py -> api.py, translator.py, capabilities.py
|
|
api.py -> translator.py, exporter.py
|
|
translator.py -> context.py, analysis.py, emitters/, runtime/
|
|
emitters/ -> context and pure code-generation helpers
|
|
exporter.py -> shared types/errors and external execution
|
|
```
|
|
|
|
The following reverse dependencies are prohibited:
|
|
|
|
- Translator or emitters importing `api.py`.
|
|
- Translator importing `exporter.py`.
|
|
- Emitters importing the public translator class.
|
|
- Runtime fragments importing the backend package.
|
|
- Capabilities importing translator implementation modules.
|
|
|
|
## Compatibility
|
|
|
|
The generated artifact and its persisted target metadata are treated as a
|
|
compatibility boundary. Pure module moves must not rename generated runtime
|
|
helpers, registries, target object properties, or public import paths. Behavior
|
|
fixes are made separately from structural migrations.
|
|
|
|
## Verification
|
|
|
|
The shared backend contract test verifies required files, public exports,
|
|
translator inheritance, backend naming, and canonical operation coverage.
|
|
Backend tests additionally verify generated artifact syntax and, where the
|
|
target runtime is available, real exported files.
|