@mokouliszt/mel-device 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mokouliszt
+
+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.

package/README.ja.md

@@ -0,0 +1,216 @@
+# @mokouliszt/mel-device
+
+[English](README.md)
+
+三菱電機 MELSEC / MXコントローラ および MELFAロボットコントローラのデバイス表記を、シリーズとCPU／コントローラ型名を含めて検証する、依存ライブラリなしのnpmパッケージです。
+
+対応シリーズは iQ-R、iQ-F、MX-R、MX-F、CR800-R/D/Qです。ES Modules と CommonJS の両方から利用できます。
+
+## インストール
+
+```bash
+npm install @mokouliszt/mel-device
+```
+
+## 基本的な使い方
+
+```js
+import { isValidDevice, analyzeDevice } from "@mokouliszt/mel-device";
+
+isValidDevice("X0", {
+  series: "iQ-R",
+  model: "R00"
+}); // true（R00CPU に正規化）
+
+isValidDevice("D0.A", {
+  series: "iQ-F",
+  model: "FX5S"
+}); // true
+
+analyzeDevice("D12288", {
+  series: "iQ-R",
+  model: "R00",
+  mode: "default"
+});
+// {
+//   valid: false,
+//   code: "REQUIRES_CONFIGURATION",
+//   suggestedMode: "maximum",
+//   ...
+// }
+
+isValidDevice("U3E0\\G524287", {
+  series: "CR800-R"
+}); // true（modelはseriesから推論）
+```
+
+`analyzeDevice` は、単なる `true` / `false` ではなく、正規化後の型名、解釈したデバイス、失敗理由、参照マニュアルとページ、実機設定への依存有無を返します。入力欄のバリデーションにはこちらを推奨します。
+
+`model`を省略できるのは、`series`に`CR800-R`、`CR800-D`、`CR800-Q`のいずれかを直接指定した場合だけです。その他のシリーズでは従来どおり型名を指定してください。
+
+## 判定モード
+
+PLCのM/D等はCPUパラメータで点数を変更できるため、型名だけで実機上の有効範囲を断定できない場合があります。本パッケージは、この違いをモードで明示します。
+
+| `mode` | 用途 | 動作 |
+| --- | --- | --- |
+| `default` | 安全側の通常判定（既定） | マニュアル記載のデフォルト点数で判定。iQ-Fは添付マニュアルにデフォルト点数表がないため、機種別「使用範囲」で判定し `configurationDependent: true` を返します。 |
+| `maximum` | 設計・設定画面 | マニュアル記載の変更可能上限で判定。メモリ、ラベル使用量、拡張SRAM等で実際の上限が下がる場合があります。 |
+| `configured` | 実機プロジェクトの厳密判定 | `configuredPoints` に渡した実際の点数で判定。可変デバイスの点数が未指定なら `MISSING_CONFIGURATION`。 |
+| `syntax` | エディタ入力途中・構文チェック | 型名が対応するデバイス文法のみを確認し、点数範囲を無視。 |
+
+CR800-R/D/Qのデバイス範囲はマニュアル上固定されているため、`default`、`maximum`、`configured`はいずれも同じ固定範囲を使用します。
+
+```js
+isValidDevice("D99", {
+  series: "MX-F",
+  model: "MXF100",
+  mode: "configured",
+  configuredPoints: { D: 100 }
+}); // true
+
+isValidDevice("D100", {
+  series: "MX-F",
+  model: "MXF100",
+  mode: "configured",
+  configuredPoints: { D: 100 }
+}); // false（100点はD0〜D99）
+```
+
+## 入力モード
+
+`inputMode: "exact"` が既定です。大文字、半角、マニュアルどおりの `\` を要求します。
+
+UIで人が入力する場合は `friendly` が便利です。前後空白、小文字、全角英数字、`¥` / `￥` を正規化します。
+
+```js
+analyzeDevice("  u1￥g0  ", {
+  series: "iQ-F",
+  model: "FX5U",
+  inputMode: "friendly"
+}).normalized; // "U1\\G0"
+```
+
+## 対応する主な表記
+
+- 直接デバイス: `X0`, `DX0`, `DY0`, `M0`, `D0`, `W0`, `SM400`
+- ワードデバイスのビット指定: `D0.A`
+- タイマ／カウンタの接点・コイル・現在値: `TS0`, `TC0`, `TN0`, `LCS0` など
+- ユニットアクセス: `U1\G0`
+- CPUバッファメモリアクセス: `U3E0\G0`
+- リンクダイレクト: `J1\X0`, `J1\W0`
+- 桁指定: `K4M100`
+- 間接指定: `@D10`, `@D10.8`
+- インデックス修飾: `D10Z2.0`, `D10.8Z2`, `D0LZ0`
+- ローカルデバイス: `#M0`（対応シリーズ／デバイスのみ）
+
+## MELFA CR800
+
+推奨表記は、親シリーズとコントローラ種別を分ける方法です。
+
+```js
+analyzeDevice("U3E1\\HG100", {
+  series: "CR800",
+  model: "CR800-D",
+  operation: "write"
+});
+// valid: true（デバイス表記としては有効）
+// access: "read-only"
+// operationAllowed: false（この領域は常時有効のシーケンサリンク入力）
+```
+
+`series: "CR800-R"`、`"CR800-D"`、`"CR800-Q"`の省略形も使用でき、この場合は`model`を省略できます。モデルには`R`、`D`、`Q`も指定できます。
+
+| モデル | 対応デバイスと固定範囲 |
+| --- | --- |
+| CR800-R | `X0-XFFF`, `Y0-YFFF`, `M0-M18431`, `D0-D5119`, `SM0-SM4095`, `SD0-SD4095`, `U3E0-U3E3\G0-G524287`, `U3E0-U3E3\HG0-HG12287` |
+| CR800-D | `X0-X1FFF`, `Y0-Y1FFF`, `D0-D5119`, `SM0-SM4095`, `SD0-SD4095`, `U3E0/U3E1\HG0-HG2047` |
+| CR800-Q | `X0-XFFF`, `Y0-YFFF`, `M0-M18431`, `D0-D5119`, `SM0-SM2047`, `SD0-SD2047`, `U3E0-U3E3\G10000-G24335` |
+
+### 読書き属性の判定
+
+取扱説明書の表6-14～6-16では、固定範囲内でも機能の割付中は読出し専用となり、書込みが無視される領域があります。`isValidDevice`は「デバイス表記と固定範囲」を判定し、`analyzeDevice`はそれとは別に次を返します。
+
+- `access`: `read-write` / `read-only` / `configuration-dependent`
+- `operationAllowed`: `operation: "read" | "write"`に対する`true` / `false`。構成不明時は`null`
+- `activeAllocations`, `possibleAllocations`, `warnings`: 判定根拠となった割付
+
+実機設定が分かる場合は`cr800Features`を渡せます。省略した項目は「不明」として安全側に`configuration-dependent`を返します。
+
+```js
+analyzeDevice("U3E1\\HG600", {
+  series: "CR800-D",
+  operation: "write",
+  cr800Features: { iqmem: false }
+}).operationAllowed; // true（拡張機能無効時は自由に読書き可能）
+
+analyzeDevice("U3E1\\HG600", {
+  series: "CR800-D",
+  operation: "write",
+  cr800Features: { iqmem: true }
+}).operationAllowed; // false
+```
+
+指定可能な設定は次のとおりです。
+
+| `cr800Features` | 対象 | 意味 |
+| --- | --- | --- |
+| `qxyread` | R/Q | シーケンサ入出力ユニット直接制御 |
+| `iqmem` | R/D/Q | CPUバッファ／共有メモリ拡張 |
+| `ddevvl` | R/D/Q | `"disabled"`, `"program-external"`, `"status"`, `"mixed"` |
+| `parallelIoUnit`, `parallelIoInterface`, `gotLink` | D | パラレルI/O、GOTリンク |
+| `profibus`, `ccLink`, `ccLinkIef` | D | 各ネットワーク機能 |
+
+常時有効の例として、CR800-Dの`U3E1\HG0-HG511`、CR800-Rの`U3E1-U3E3\HG0-HG511`、CR800-Qの`U3E1-U3E3\G10000-G10511`は外部機器から読出し専用です。ハンド入力`X384-X38B`も読出し専用です。一方、機能が無効または未割付の領域は、マニュアル注記どおり自由に読書きできます。
+
+CR800-Qの表6-16にある`U3En\G512-G1023`は、表6-13の固定範囲`G10000-G24335`および5.2.1／6.2.2の対応表と矛盾します。本パッケージは誤った有効判定を避けるため、この表記を`MANUAL_RANGE_CONFLICT`として無効にし、`G10512-G11023`側のIQMEM読書き属性も断定せず`configuration-dependent`とします。
+
+表6-11～6-13に記載されていないビット指定、桁指定、間接指定、インデックス修飾、ローカル指定は、CR800では保守的に無効と判定します。
+
+定数（`K100`, `HFF`, 実数・文字列）は「デバイス」ではないため判定対象外です。ラベル、構造体メンバ、SLMPのバイナリデバイスコードも対象外です。
+
+## API
+
+### `isValidDevice(value, options): boolean`
+
+簡潔な真偽値判定です。
+
+### `analyzeDevice(value, options): DeviceAnalysis`
+
+詳細判定です。主要な返却値は `valid`, `code`, `message`, `normalized`, `parsed`, `configurationDependent`, `source` です。
+
+### `assertValidDevice(value, options): DeviceAnalysis`
+
+無効時に `MelDeviceError` を投げます。
+
+### `parseDevice(value, options): ParsedDevice | null`
+
+構文を分解します。シリーズ／機種の範囲判定は行いません。
+
+### `normalizeDevice(value): string | null`
+
+人間向け表記を正規化します。
+
+### `normalizeModel(series, model): string | null`
+
+`R00` → `R00CPU`、iQ-Fの具体的な型名 → `FX5U` のように、検証用の型名へ正規化します。
+
+### `getSupportedModels(series): string[]`
+
+マニュアルの対象機種一覧を返します。
+
+## 対象機種
+
+- iQ-R: R00CPU、R01CPU、R02CPU、R04/R08/R16/R32/R120 CPUおよびENCPU
+- iQ-F: FX5S、FX5UJ、FX5U、FX5UC（具体的なI/O型名もファミリへ正規化）
+- MX-R: MXR300-16/-32/-64、MXR500-128/-256
+- MX-F: MXF100系のマニュアル対象10機種（`MXF100` をファミリ別名として受付）
+- MELFA CR800: CR800-R、CR800-D、CR800-Q
+
+## 資料
+
+判定表は、同梱の [manual-evidence.md](docs/manual-evidence.md) にマニュアル番号・版・ページ単位で整理しています。
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,216 @@
+# @mokouliszt/mel-device
+
+[日本語](README.ja.md)
+
+A dependency-free npm package for validating Mitsubishi Electric MELSEC/MX controller and MELFA robot controller device notation against a specified series and CPU/controller model.
+
+Supported series are iQ-R, iQ-F, MX-R, MX-F, and CR800-R/D/Q. The package supports both ES Modules and CommonJS.
+
+## Installation
+
+```bash
+npm install @mokouliszt/mel-device
+```
+
+## Basic usage
+
+```js
+import { isValidDevice, analyzeDevice } from "@mokouliszt/mel-device";
+
+isValidDevice("X0", {
+  series: "iQ-R",
+  model: "R00"
+}); // true (normalized to R00CPU)
+
+isValidDevice("D0.A", {
+  series: "iQ-F",
+  model: "FX5S"
+}); // true
+
+analyzeDevice("D12288", {
+  series: "iQ-R",
+  model: "R00",
+  mode: "default"
+});
+// {
+//   valid: false,
+//   code: "REQUIRES_CONFIGURATION",
+//   suggestedMode: "maximum",
+//   ...
+// }
+
+isValidDevice("U3E0\\G524287", {
+  series: "CR800-R"
+}); // true (model inferred from series)
+```
+
+Instead of returning only `true` or `false`, `analyzeDevice` reports the normalized model, parsed device, reason for failure, referenced manual and page, and whether the result depends on the actual hardware configuration. It is the recommended API for validating user input.
+
+The `model` option may be omitted only when `series` is set directly to `CR800-R`, `CR800-D`, or `CR800-Q`. A model must still be specified for all other series.
+
+## Validation modes
+
+The number of available points for PLC devices such as M and D can be changed in the CPU parameters, so the valid range on actual hardware cannot always be determined from the model alone. This package makes that distinction explicit through validation modes.
+
+| `mode` | Use case | Behavior |
+| --- | --- | --- |
+| `default` | Conservative general-purpose validation (default) | Validates against the default point counts stated in the manuals. Because the referenced iQ-F manuals do not include a default point-count table, iQ-F devices are checked against the model-specific usage range and return `configurationDependent: true`. |
+| `maximum` | Design and configuration screens | Validates against the maximum configurable limits stated in the manuals. Actual limits may be lower depending on memory, label usage, expansion SRAM, and other factors. |
+| `configured` | Exact validation for an actual project | Validates against the actual point counts supplied in `configuredPoints`. Returns `MISSING_CONFIGURATION` if the point count for a configurable device is omitted. |
+| `syntax` | In-progress editor input and syntax checking | Checks only whether the model supports the device syntax and ignores point-count ranges. |
+
+The device ranges for CR800-R/D/Q are fixed in the manuals, so `default`, `maximum`, and `configured` all use the same fixed ranges.
+
+```js
+isValidDevice("D99", {
+  series: "MX-F",
+  model: "MXF100",
+  mode: "configured",
+  configuredPoints: { D: 100 }
+}); // true
+
+isValidDevice("D100", {
+  series: "MX-F",
+  model: "MXF100",
+  mode: "configured",
+  configuredPoints: { D: 100 }
+}); // false (100 points cover D0 through D99)
+```
+
+## Input modes
+
+`inputMode: "exact"` is the default. It requires uppercase, half-width characters, and the `\` separator used in the manuals.
+
+For user-entered UI input, `friendly` is convenient. It normalizes leading and trailing whitespace, lowercase characters, full-width alphanumeric characters, and `¥` / `￥`.
+
+```js
+analyzeDevice("  u1￥g0  ", {
+  series: "iQ-F",
+  model: "FX5U",
+  inputMode: "friendly"
+}).normalized; // "U1\\G0"
+```
+
+## Main supported notation
+
+- Direct devices: `X0`, `DX0`, `DY0`, `M0`, `D0`, `W0`, `SM400`
+- Bit specification for word devices: `D0.A`
+- Timer/counter contacts, coils, and current values: `TS0`, `TC0`, `TN0`, `LCS0`, etc.
+- Module access: `U1\G0`
+- CPU buffer memory access: `U3E0\G0`
+- Link direct devices: `J1\X0`, `J1\W0`
+- Digit specification: `K4M100`
+- Indirect specification: `@D10`, `@D10.8`
+- Index modification: `D10Z2.0`, `D10.8Z2`, `D0LZ0`
+- Local devices: `#M0` (supported series/devices only)
+
+## MELFA CR800
+
+The recommended notation separates the parent series from the controller type.
+
+```js
+analyzeDevice("U3E1\\HG100", {
+  series: "CR800",
+  model: "CR800-D",
+  operation: "write"
+});
+// valid: true (valid as device notation)
+// access: "read-only"
+// operationAllowed: false (this area is an always-enabled sequencer link input)
+```
+
+The shorthand series values `"CR800-R"`, `"CR800-D"`, and `"CR800-Q"` are also accepted; `model` may be omitted in that form. The model may also be specified as `R`, `D`, or `Q`.
+
+| Model | Supported devices and fixed ranges |
+| --- | --- |
+| CR800-R | `X0-XFFF`, `Y0-YFFF`, `M0-M18431`, `D0-D5119`, `SM0-SM4095`, `SD0-SD4095`, `U3E0-U3E3\G0-G524287`, `U3E0-U3E3\HG0-HG12287` |
+| CR800-D | `X0-X1FFF`, `Y0-Y1FFF`, `D0-D5119`, `SM0-SM4095`, `SD0-SD4095`, `U3E0/U3E1\HG0-HG2047` |
+| CR800-Q | `X0-XFFF`, `Y0-YFFF`, `M0-M18431`, `D0-D5119`, `SM0-SM2047`, `SD0-SD2047`, `U3E0-U3E3\G10000-G24335` |
+
+### Read/write attribute validation
+
+Tables 6-14 through 6-16 of the instruction manual identify areas that become read-only while particular functions are assigned, even when the addresses remain within the fixed device ranges. Writes to these areas are ignored. `isValidDevice` validates the device notation and fixed range, while `analyzeDevice` separately returns the following fields:
+
+- `access`: `read-write` / `read-only` / `configuration-dependent`
+- `operationAllowed`: `true` or `false` for `operation: "read" | "write"`; `null` when the configuration is unknown
+- `activeAllocations`, `possibleAllocations`, `warnings`: allocations used as the basis for the result
+
+If the actual hardware configuration is known, pass it through `cr800Features`. Omitted properties are treated as unknown and conservatively return `configuration-dependent`.
+
+```js
+analyzeDevice("U3E1\\HG600", {
+  series: "CR800-D",
+  operation: "write",
+  cr800Features: { iqmem: false }
+}).operationAllowed; // true (freely readable/writable when the expansion is disabled)
+
+analyzeDevice("U3E1\\HG600", {
+  series: "CR800-D",
+  operation: "write",
+  cr800Features: { iqmem: true }
+}).operationAllowed; // false
+```
+
+The following settings are supported:
+
+| `cr800Features` | Applies to | Meaning |
+| --- | --- | --- |
+| `qxyread` | R/Q | Direct control of sequencer I/O units |
+| `iqmem` | R/D/Q | CPU buffer/shared-memory expansion |
+| `ddevvl` | R/D/Q | `"disabled"`, `"program-external"`, `"status"`, `"mixed"` |
+| `parallelIoUnit`, `parallelIoInterface`, `gotLink` | D | Parallel I/O and GOT link |
+| `profibus`, `ccLink`, `ccLinkIef` | D | Network functions |
+
+Examples of always-enabled areas include `U3E1\HG0-HG511` on CR800-D, `U3E1-U3E3\HG0-HG511` on CR800-R, and `U3E1-U3E3\G10000-G10511` on CR800-Q. These areas are read-only from external devices. Hand inputs `X384-X38B` are also read-only. In contrast, areas for disabled or unassigned functions may be freely read and written as described in the manual notes.
+
+The `U3En\G512-G1023` range in Table 6-16 for CR800-Q conflicts with the fixed `G10000-G24335` range in Table 6-13 and with the correspondence tables in Sections 5.2.1 and 6.2.2. To avoid false-positive validation, this package treats that notation as invalid with `MANUAL_RANGE_CONFLICT`. It also does not make a definitive claim about the IQMEM read/write attributes of the `G10512-G11023` range, instead reporting them as `configuration-dependent`.
+
+Bit specifications, digit specifications, indirect specifications, index modifications, and local specifications that are not listed in Tables 6-11 through 6-13 are conservatively treated as invalid for CR800.
+
+Constants (`K100`, `HFF`, real numbers, and strings) are outside the validation scope because they are not devices. Labels, structure members, and SLMP binary device codes are also outside the scope.
+
+## API
+
+### `isValidDevice(value, options): boolean`
+
+Returns a simple Boolean validation result.
+
+### `analyzeDevice(value, options): DeviceAnalysis`
+
+Returns a detailed validation result. The main fields are `valid`, `code`, `message`, `normalized`, `parsed`, `configurationDependent`, and `source`.
+
+### `assertValidDevice(value, options): DeviceAnalysis`
+
+Throws `MelDeviceError` when the device is invalid.
+
+### `parseDevice(value, options): ParsedDevice | null`
+
+Parses the notation into its components. It does not validate ranges for a series or model.
+
+### `normalizeDevice(value): string | null`
+
+Normalizes human-entered notation.
+
+### `normalizeModel(series, model): string | null`
+
+Normalizes a model name for validation, such as `R00` → `R00CPU` or a specific iQ-F model name → `FX5U`.
+
+### `getSupportedModels(series): string[]`
+
+Returns the list of models covered by the manuals.
+
+## Supported models
+
+- iQ-R: R00CPU, R01CPU, R02CPU, R04/R08/R16/R32/R120 CPUs, and ENCPUs
+- iQ-F: FX5S, FX5UJ, FX5U, and FX5UC (specific I/O model names are normalized to their families)
+- MX-R: MXR300-16/-32/-64 and MXR500-128/-256
+- MX-F: the 10 models covered by the MXF100-series manual (`MXF100` is accepted as a family alias)
+- MELFA CR800: CR800-R, CR800-D, and CR800-Q
+
+## References
+
+The validation tables and their supporting manual numbers, editions, and page references are documented in the bundled [manual-evidence.md](docs/manual-evidence.md).
+
+## License
+
+MIT