mapcan 0.23.2__tar.gz → 0.23.3__tar.gz

{mapcan-0.23.2 → mapcan-0.23.3}/.gitignore

@@ -41,3 +41,7 @@ canmap_tasks.md
 
 # UI mockups
 examples_ui/
+
+# Browser tests of the web editor
+web/test-results/
+web/playwright-report/

{mapcan-0.23.2 → mapcan-0.23.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mapcan
-Version: 0.23.2
+Version: 0.23.3
 Summary: A YAML map of CAN signals as the single source of truth: validation, Excel/PDF/Markdown/HTML, DBC, C/Python code
 Project-URL: Homepage, https://github.com/ordu1453/mapcan
 Project-URL: Documentation, https://github.com/ordu1453/mapcan/blob/main/docs/format.md
@@ -125,6 +125,9 @@ mapcan build vehicle.yaml -o build/         # PDF, Excel, HTML, DBC, C and Pytho
 mapcan app vehicle.yaml                     # edit it on the bit layout
 ```
 
+The app, the web editor (**File → Import DBC…**) and the VS Code extension (**mapcan: Import DBC…**)
+import a DBC too.
+
 You keep your tools: the DBC exported back works in CANalyzer, SavvyCAN, PCAN-View and Wireshark.
 
 ## Why not just a DBC file?

{mapcan-0.23.2 → mapcan-0.23.3}/README.md

@@ -53,6 +53,9 @@ mapcan build vehicle.yaml -o build/         # PDF, Excel, HTML, DBC, C and Pytho
 mapcan app vehicle.yaml                     # edit it on the bit layout
 ```
 
+The app, the web editor (**File → Import DBC…**) and the VS Code extension (**mapcan: Import DBC…**)
+import a DBC too.
+
 You keep your tools: the DBC exported back works in CANalyzer, SavvyCAN, PCAN-View and Wireshark.
 
 ## Why not just a DBC file?

{mapcan-0.23.2 → mapcan-0.23.3}/docs/ci-example.md

@@ -45,6 +45,48 @@ jobs:
 merge. `mapcan fmt --check` fails when the keys of the map are not in the canonical order, so that maps
 edited by different people and editors stay easy to review; `mapcan fmt my-map.yaml` fixes it.
 
+## Breaking changes in pull requests
+
+A map describes devices already in the field: moving a signal, changing its scale or reassigning an
+ID breaks them, while a new signal in free bits does not. `mapcan diff --fail-on breaking` tells the
+two apart (see [cli.md](cli.md#comparing-versions)), so a pull request that breaks the map fails
+unless it says so on purpose: here with the label `breaking`, or by raising the major version of
+`document.version`.
+
+```yaml
+name: mapcan-compat
+on:
+  pull_request:
+    paths: ["my-map.yaml"]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+jobs:
+  compat:
+    runs-on: ubuntu-latest
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'breaking') }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+      - run: uv tool install "mapcan==X.Y.Z"
+      - name: Compare with the base branch
+        shell: bash   # with pipefail, so that tee keeps the exit code of mapcan diff
+        run: |
+          git show "origin/${{ github.base_ref }}:my-map.yaml" > base.yaml
+          old=$(yq '.document.version' base.yaml | cut -d. -f1)
+          new=$(yq '.document.version' my-map.yaml | cut -d. -f1)
+          if [ "$new" != "$old" ]; then
+            echo "major version raised ($old → $new): breaking changes allowed"
+            mapcan diff base.yaml my-map.yaml --lang en
+          else
+            mapcan diff base.yaml my-map.yaml --lang en --format md --fail-on breaking | tee -a "$GITHUB_STEP_SUMMARY"
+          fi
+```
+
+`git show` gives only the main file: a map split into included files needs the base branch checked
+out next to it (`git worktree add ../base origin/main`) and `mapcan diff ../base/my-map.yaml my-map.yaml`.
+
 ## GitLab CI
 
 `.gitlab-ci.yml`, using the published Docker image:

{mapcan-0.23.2 → mapcan-0.23.3}/docs/cli.md

@@ -16,7 +16,7 @@ mapcan export eds  FILE [-o DIR] [--bus NAME]
 mapcan gen c       FILE [-o DIR] [--prefix my_] [--bus NAME]
 mapcan gen py      FILE [-o DIR] [--bus NAME]
 mapcan build       FILE [-o DIR] [--formats xlsx,pdf,md,html,dbc,eds,c,py] [--pdf-template NAME]
-mapcan diff        OLD NEW [--format text|md|json]
+mapcan diff        OLD NEW [--format text|md|json] [--fail-on breaking|any]
 mapcan import dbc  FILE.dbc [-o FILE.yaml] [--title TEXT] [--lang en] [--force]
 mapcan migrate     FILE… [--check]      # former field names → current ones
 mapcan fmt         FILE… [--check]      # keys in one order, comments and layout kept
@@ -188,6 +188,23 @@ becomes a `can` bus with explicit IDs. Value names become identifiers (`Not avai
 `NOT_AVAILABLE`, the original text goes to the description), and whatever DBC cannot express is
 reported as a warning.
 
+## Comparing versions
+
+`mapcan diff OLD NEW` lists what changed between two versions of a map and marks the changes that
+break devices built against the old one (`[breaking]` in text, **breaking:** in Markdown, a
+`breaking` field per change in JSON):
+
+| Breaking | Compatible |
+|---|---|
+| a bus, frame, signal, flag or value removed | anything added: buses, devices, frames, signals in free bits, values |
+| a frame's ID, CANopen function, PGN, priority, length or IDE changed; a device's node ID or address | timing, transmission mode, sender and receivers |
+| a signal moved or resized; its byte order, representation, encoding, factor or offset changed | titles, descriptions, units of display, initial values |
+| a value renamed or renumbered; a flag moved; the multiplexer or a multiplexer value changed | limits widened or removed |
+| a limit narrowed or added | |
+
+`--fail-on breaking` exits with code 1 when a breaking change is found, `--fail-on any` on any change;
+[ci-example.md](ci-example.md#breaking-changes-in-pull-requests) uses it to check pull requests.
+
 ## CI
 
 [ci-example.md](ci-example.md) shows a pipeline for map repositories: when the YAML changes, the map

{mapcan-0.23.2 → mapcan-0.23.3}/docs/web.md

@@ -47,6 +47,10 @@ Save as… / Close map** all work in the browser. The file dialog can browse any
 accepts a typed path and lists recent files. If the current map has unsaved changes, the editor
 offers to save them before switching.
 
+**File → Import DBC…** (also on the start screen) turns a DBC file into a map, as
+`mapcan import dbc` does: the map is written next to the DBC with its name (the editor asks before
+overwriting) and opens; whatever the DBC cannot express is listed once it is open.
+
 The start screen also lists the bundled examples: pick one, choose where to save a copy, and it
 opens. The mapcan version is shown in the top bar next to the title and on the start screen.
 **File → Report an issue** (and the link on the start screen) opens a new GitHub issue with the
@@ -177,7 +181,7 @@ available at `http://127.0.0.1:8765/api/docs`.
 | GET | `/api/update` | Newer version on GitHub Releases: `{current, latest, newer, url, installer}` (`mapcan app` and local `serve` only) |
 | POST | `/api/instance/activate` | `{token, path}`: a second launch hands the file to the running instance (the token is in `~/.mapcan/instance.json`) |
 | GET | `/api/fs/list?dir=` | Folders and YAML files for the file dialog |
-| POST | `/api/file/open`, `/api/file/new`, `/api/file/example`, `/api/file/save_as`, `/api/file/close` | File operations; `409 unsaved` means there are unsaved changes (pass `force: true` to proceed) |
+| POST | `/api/file/open`, `/api/file/new`, `/api/file/example`, `/api/file/import_dbc`, `/api/file/save_as`, `/api/file/close` | File operations; `409 unsaved` means there are unsaved changes (pass `force: true` to proceed) |
 | GET | `/api/state` | Text, data, computed layout and diagnostics |
 | POST | `/api/ops` | `{"ops": [...]}`: apply operations atomically |
 | POST | `/api/device_file` | `{"bus": ["buses", 0], "device": {...}, "file": "devices/node.yaml"}`: a new device in a new file, added to `include` |

{mapcan-0.23.2 → mapcan-0.23.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapcan"
-version = "0.23.2"
+version = "0.23.3"
 description = "A YAML map of CAN signals as the single source of truth: validation, Excel/PDF/Markdown/HTML, DBC, C/Python code"
 # readme: built from README.md with absolute links for PyPI (see fancy-pypi-readme below)
 dynamic = ["readme"]

{mapcan-0.23.2 → mapcan-0.23.3}/src/mapcan/__init__.py

@@ -1,6 +1,6 @@
 """mapcan: a YAML signal map as the single source of truth."""
 
-__version__ = "0.23.2"
+__version__ = "0.23.3"
 
 from .loader import load, loads  # noqa: E402
 from .model import MapCan  # noqa: E402

{mapcan-0.23.2 → mapcan-0.23.3}/src/mapcan/cli.py

@@ -208,12 +208,20 @@ class DiffFormat(str, Enum):
     json = "json"
 
 
+class FailOn(str, Enum):
+    breaking = "breaking"
+    any = "any"
+
+
 @app.command(help=_("Compare two versions of a map (frames, signals, values) and print a changelog."))
 def diff(
     old: Path = typer.Argument(..., exists=True, dir_okay=False, help=_("Old version of the map.")),
     new: Path = typer.Argument(..., exists=True, dir_okay=False, help=_("New version of the map.")),
     fmt: DiffFormat = typer.Option(DiffFormat.text, "--format", help="text | md | json"),
     lang: Optional[str] = LangOpt,
+    fail_on: Optional[FailOn] = typer.Option(
+        None, "--fail-on",
+        help=_("Exit code 1 on breaking changes (breaking) or on any change (any).")),
 ) -> None:
     from .diff import diff_maps, render_diff
     from .loader import load
@@ -228,6 +236,12 @@ def diff(
         maps.append(res.map)
     d = diff_maps(maps[0], maps[1], lang)
     typer.echo(render_diff(d, fmt.value, lang or maps[1].lang))
+    if fail_on is FailOn.breaking and d.breaking:
+        typer.secho(_("breaking changes: {count}", count=len(d.breaking)), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    if fail_on is FailOn.any and not d.empty:
+        typer.secho(_("changes: {count}", count=len(d.changes)), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
 
 
 @app.command(help=_("Rewrite the former names of fields (deprecated-key) to the current ones, keeping comments and "

{mapcan-0.23.2 → mapcan-0.23.3}/src/mapcan/diff.py

@@ -27,6 +27,7 @@ class Change:
     field: str = ""          # changed field
     old: Any = None
     new: Any = None
+    breaking: bool = False   # devices built against the old version misread the bus (see is_breaking)
 
 
 @dataclass
@@ -39,6 +40,10 @@ class MapDiff:
     def empty(self) -> bool:
         return not self.changes
 
+    @property
+    def breaking(self) -> list[Change]:
+        return [c for c in self.changes if c.breaking]
+
     def to_dict(self) -> dict:
         return {"old_version": self.old_version, "new_version": self.new_version,
                 "changes": [asdict(c) for c in self.changes]}
@@ -56,6 +61,45 @@ SIGNAL_FIELDS = ("start_bit", "bit_length", "byte_order", "representation", "enc
                  "min", "max", "initial", "source", "invalid_raw", "multiplexer", "mux", "description")
 FLAG_FIELDS = ("bit", "bit_length", "description")
 
+# Fields whose change makes a device built against the old version send or read the bus differently
+BREAKING_FIELDS = {
+    "device": {"node_id", "address"},
+    "frame": {"can_id", "canopen", "length", "extended", "pgn", "priority"},
+    "signal": {"start_bit", "bit_length", "byte_order", "representation", "encoding", "factor", "offset",
+               "multiplexer", "mux"},
+    "flag": {"bit", "bit_length"},
+    "value": {"name"},
+}
+
+
+def _narrowed(fld: str, old: Any, new: Any) -> bool:
+    """A limit (min or max) admits fewer values than before; a limit set where there was none does too."""
+    if new is None:
+        return False
+    if old is None:
+        return True
+    try:
+        return new > old if fld == "min" else new < old
+    except TypeError:
+        return True
+
+
+def is_breaking(c: Change) -> bool:
+    """The change breaks devices built against the old version of the map.
+
+    Removing a bus, frame, signal, flag or value breaks them; so do moving or rescaling a signal, changing the
+    identifier or length of a frame, renaming or renumbering a value and narrowing a limit. Additions, texts,
+    units of display, timing and widened limits do not. A removed device is not breaking by itself: its frames
+    are listed as removed.
+    """
+    if c.kind == "added":
+        return False
+    if c.kind == "removed":
+        return c.scope != "device"
+    if c.scope == "signal" and c.field in ("min", "max"):
+        return _narrowed(c.field, c.old, c.new)
+    return c.field in BREAKING_FIELDS.get(c.scope, ())
+
 
 def _invalid_text(s: Signal) -> str | None:
     """invalid_raw as one comparable text: "not_available 0xFF; error 0xFE00..0xFEFF"."""
@@ -104,6 +148,8 @@ def diff_maps(old: MapCan, new: MapCan, lang: str | None = None) -> MapDiff:
                 d.changes.append(_frame_change("added", name, f))
             continue
         _diff_bus(d, ob[name], nb[name], langs)
+    for c in d.changes:
+        c.breaking = is_breaking(c)
     return d
 
 
@@ -254,14 +300,14 @@ _T = {
         "bus": "шина", "device": "устройство", "frame": "кадр", "signal": "сигнал",
         "flag": "флаг", "value": "значение", "bits": "биты", "byte": "байт",
         "added_n": "добавлено", "removed_n": "удалено", "changed_n": "изменено",
-        "none": "Изменений нет.",
+        "none": "Изменений нет.", "breaking": "несовместимо",
     },
     "en": {
         "added": "added", "removed": "removed", "changed": "changed",
         "bus": "bus", "device": "device", "frame": "frame", "signal": "signal",
         "flag": "flag", "value": "value", "bits": "bits", "byte": "byte",
         "added_n": "added", "removed_n": "removed", "changed_n": "changed",
-        "none": "No changes.",
+        "none": "No changes.", "breaking": "breaking",
     },
 }
 
@@ -375,9 +421,13 @@ def release_message(version: str, changes: list[str]) -> str:
 def render_diff(diff: MapDiff, fmt: str = "text", lang: str = "ru") -> str:
     if fmt == "json":
         return diff.to_json()
+    T = _T.get(lang, _T["ru"])
     lines = changelog_lines(diff, lang)
     if not lines:
-        return _T.get(lang, _T["ru"])["none"]
+        return T["none"]
+    # changelog_lines gives one line per change, in the same order
+    mark = f"**{T['breaking']}:** " if fmt == "md" else f"[{T['breaking']}] "
+    lines = [mark + line if c.breaking else line for c, line in zip(diff.changes, lines, strict=True)]
     if fmt == "md":
         head = f"## {diff.old_version} → {diff.new_version}\n\n"
         return head + "\n".join(f"- {line}" for line in lines)

{mapcan-0.23.2 → mapcan-0.23.3}/src/mapcan/launcher.py

@@ -179,13 +179,13 @@ def _webview():
 class DialogApi:
     """Methods for the window's JS (window.pywebview.api): the system open and save file dialogs."""
 
-    FILE_TYPES = ("YAML (*.yaml;*.yml)", "All files (*.*)")
+    FILE_TYPES = {"yaml": ("YAML (*.yaml;*.yml)", "All files (*.*)"), "dbc": ("DBC (*.dbc)", "All files (*.*)")}
 
     def __init__(self, get_window):
         self._get_window = get_window   # with "_": pywebview does not expose the attribute to JS
 
-    def pick_file(self, mode: str, directory: str = "", filename: str = "") -> str | None:
-        """``mode``: "open" or "save". Returns the chosen path or None (cancelled)."""
+    def pick_file(self, mode: str, directory: str = "", filename: str = "", types: str = "yaml") -> str | None:
+        """``mode``: "open" or "save"; ``types``: a key of FILE_TYPES. Returns the chosen path or None (cancelled)."""
         import webview
 
         win = self._get_window()
@@ -193,7 +193,7 @@ class DialogApi:
             return None
         kind = webview.FileDialog.SAVE if mode == "save" else webview.FileDialog.OPEN
         result = win.create_file_dialog(kind, directory=directory or "", save_filename=filename or "",
-                                        file_types=self.FILE_TYPES)
+                                        file_types=self.FILE_TYPES.get(types, self.FILE_TYPES["yaml"]))
         if not result:
             return None
         return result if isinstance(result, str) else result[0]

{mapcan-0.23.2 → mapcan-0.23.3}/src/mapcan/locale/ru.py

@@ -21,6 +21,10 @@ RU: dict[str, str] = {
         "Редактор в отдельном окне (pywebview); повторный запуск открывает файл в уже запущенном окне.",
     "Compare two versions of a map (frames, signals, values) and print a changelog.":
         "Сравнить две версии карты (кадры, сигналы, значения) и вывести changelog.",
+    "Exit code 1 on breaking changes (breaking) or on any change (any).":
+        "Код возврата 1 при несовместимых изменениях (breaking) или при любых (any).",
+    "breaking changes: {count}": "несовместимых изменений: {count}",
+    "changes: {count}": "изменений: {count}",
     "List validation rules.": "Список правил проверки.",
     "Print the format's JSON Schema (for IDE hints).": "Вывести JSON Schema формата (для подсказок в IDE).",
     "List PDF templates or copy a built-in template to customize the layout.":
@@ -623,6 +627,7 @@ RU: dict[str, str] = {
     "{fmt} export error: {error}": "ошибка экспорта {fmt}: {error}",
     "the file is not UTF-8 encoded": "файл не в UTF-8",
     "could not read {name}: {error}": "не удалось прочитать {name}: {error}",
+    "could not import {name}: {error}": "не удалось импортировать {name}: {error}",
     "could not create {path}: {error}": "не удалось создать {path}: {error}",
     "could not save {path}: {error}": "не удалось сохранить {path}: {error}",
     "could not save the logo: {error}": "не удалось сохранить логотип: {error}",

{mapcan-0.23.2 → mapcan-0.23.3}/src/mapcan/lsp/server.py

@@ -404,6 +404,26 @@ def new_map_command(ls: MapcanServer, *args) -> dict:
         return {"error": str(e)}
 
 
+@server.command("mapcan.lsp.importDbc")
+@server.thread()
+def import_dbc_command(ls: MapcanServer, *args) -> dict:
+    """Argument: {path, title, language}: a DBC file. Response: {text, warnings} (the YAML of the map and what the
+    import could not bring over) or {error}."""
+    from ..i18n import normalize_language
+    from ..importers.dbc import import_dbc
+
+    params = _arg(args)
+    path = Path(str(params.get("path") or ""))
+    if not path.is_file():
+        return {"error": _("file not found: {path}", path=path)}
+    try:
+        text, warnings = import_dbc(path, params.get("title") or None,
+                                    normalize_language(str(params.get("language") or "en")) or "en")
+    except Exception as e:  # noqa: BLE001 — cantools raises many kinds of errors on a broken DBC
+        return {"error": _("could not import {name}: {error}", name=path.name, error=e)}
+    return {"text": text, "warnings": warnings}
+
+
 @server.command("mapcan.lsp.example")
 def example_command(ls: MapcanServer, *args) -> dict:
     """Argument: {name, mapFile}: an example and the file name of its copy. Response: {text, includes: {path

{mapcan-0.23.2 → mapcan-0.23.3}/src/mapcan/web/app.py

@@ -120,6 +120,14 @@ class ExampleBody(BaseModel):
     overwrite: bool = False
 
 
+class ImportBody(BaseModel):
+    source: str                   # the DBC file
+    path: str = ""                # the new map; next to the DBC, with its name, by default
+    language: str = "en"          # document language of the new map
+    force: bool = False
+    overwrite: bool = False
+
+
 class SaveAsBody(BaseModel):
     path: str
     overwrite: bool = False
@@ -314,8 +322,12 @@ class Workspace:
         }
 
 
-def list_dir(d: Path) -> dict:
-    """Contents of a folder for the file dialog: subfolders and YAML files."""
+FILE_KINDS = {"yaml": (".yaml", ".yml"), "dbc": (".dbc",)}
+
+
+def list_dir(d: Path, kind: str = "yaml") -> dict:
+    """Contents of a folder for the file dialog: subfolders and the files of ``kind`` (FILE_KINDS)."""
+    suffixes = FILE_KINDS.get(kind, FILE_KINDS["yaml"])
     if not d.is_dir():
         raise AppError(404, "not-found", _("folder not found: {path}", path=d))
     try:
@@ -328,7 +340,7 @@ def list_dir(d: Path) -> dict:
             continue
         try:
             is_dir = it.is_dir()
-            if not is_dir and it.suffix.lower() not in (".yaml", ".yml"):
+            if not is_dir and it.suffix.lower() not in suffixes:
                 continue
             st = it.stat()
         except OSError:
@@ -680,8 +692,8 @@ def create_app(session: EditorSession | None = None, poll_interval: float = 1.0,
         return path
 
     @app.get("/api/fs/list")
-    async def fs_list(dir: str = "") -> dict:
-        return list_dir(wsp.resolve(dir) if dir else wsp.cwd)
+    async def fs_list(dir: str = "", kind: str = "yaml") -> dict:
+        return list_dir(wsp.resolve(dir) if dir else wsp.cwd, kind)
 
     @app.post("/api/file/open")
     async def file_open(body: OpenBody) -> dict:
@@ -738,6 +750,27 @@ def create_app(session: EditorSession | None = None, poll_interval: float = 1.0,
         return await create_file(body.path, body.force, body.overwrite, lambda _path: example_text(body.name),
                                  included)
 
+    @app.post("/api/file/import_dbc")
+    async def file_import_dbc(body: ImportBody) -> dict:
+        from ..importers.dbc import import_dbc
+
+        source = wsp.resolve(body.source)
+        if not source.is_file():
+            raise AppError(404, "not-found", _("file not found: {path}", path=source))
+        warnings: list[str] = []
+
+        def make_text(path: Path) -> str:
+            try:
+                text, found = import_dbc(source, path.stem, normalize_language(body.language) or "en")
+            except Exception as e:  # noqa: BLE001 — cantools raises many kinds of errors on a broken DBC
+                raise AppError(400, "import", _("could not import {name}: {error}", name=source.name, error=e)) from e
+            warnings.extend(found)
+            return text
+
+        result = await create_file(body.path or str(source.with_suffix(".yaml")), body.force, body.overwrite,
+                                   make_text)
+        return {**result, "warnings": warnings}
+
     @app.post("/api/file/save_as")
     async def file_save_as(body: SaveAsBody) -> dict:
         writable()