@mokouliszt/mel-device 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+export type MelSeries = "iQ-R" | "iQ-F" | "MX-R" | "MX-F" | "CR800" | "CR800-R" | "CR800-D" | "CR800-Q";
+export type ValidationMode = "syntax" | "default" | "maximum" | "configured";
+export type InputMode = "exact" | "friendly";
+export type DeviceOperation = "read" | "write" | "either";
+export type DeviceAccess = "read-write" | "read-only" | "configuration-dependent" | "not-evaluated";
+
+export interface Cr800Features {
+  /** CR800-R/Q sequencer I/O unit direct control (parameter QXYREAD). */
+  qxyread?: boolean;
+  /** CPU/shared-memory extension (parameter IQMEM). */
+  iqmem?: boolean;
+  /** Sequencer device allocation (parameters DDEVVL1-DDEVVL32). */
+  ddevvl?: "disabled" | "program-external" | "status" | "mixed";
+  /** CR800-D parallel I/O unit is connected. */
+  parallelIoUnit?: boolean;
+  /** CR800-D parallel I/O interface is connected. */
+  parallelIoInterface?: boolean;
+  /** CR800-D GOT link is active. */
+  gotLink?: boolean;
+  /** CR800-D PROFIBUS option is connected. */
+  profibus?: boolean;
+  /** CR800-D CC-Link is active. */
+  ccLink?: boolean;
+  /** CR800-D CC-Link IE Field is active. */
+  ccLinkIef?: boolean;
+}
+
+export interface DeviceOptions {
+  series: MelSeries | string;
+  model?: string;
+  mode?: ValidationMode;
+  inputMode?: InputMode;
+  operation?: DeviceOperation;
+  configuredPoints?: Partial<Record<string, number>>;
+  /** Known CR800 feature states. Omitted properties are treated as unknown. */
+  cr800Features?: Cr800Features;
+}
+
+export interface ParsedDevice {
+  kind: "direct" | "unit" | "cpu-buffer" | "link";
+  prefix: string;
+  notationPrefix?: string;
+  address: number;
+  addressText: string;
+  radix: 8 | 10 | 16;
+  input: string;
+  normalized: string;
+  local: boolean;
+  digit: number | null;
+  indirect: boolean;
+  bit: number | null;
+  index: { type: "Z" | "LZ"; number: number } | null;
+  indexOrder: "index-bit" | "bit-index" | "bit" | "index" | null;
+  timerPart?: "contact" | "coil" | "current";
+  unit?: number;
+  cpu?: number;
+  network?: number;
+}
+
+export interface DeviceAnalysis {
+  valid: boolean;
+  input: unknown;
+  normalized: string | null;
+  series: MelSeries | null;
+  model: string | null;
+  mode: ValidationMode | string;
+  code: string;
+  message: string;
+  configurationDependent: boolean;
+  operation?: DeviceOperation;
+  access?: DeviceAccess;
+  /** true/false when the requested read/write is known; null when not requested or configuration-dependent. */
+  operationAllowed?: boolean | null;
+  activeAllocations?: string[];
+  possibleAllocations?: string[];
+  warnings?: string[];
+  parsed?: ParsedDevice;
+  suggestedMode?: ValidationMode;
+  source: { manual: string; pages: number[] } | null;
+}
+
+export class MelDeviceError extends Error {
+  code: string;
+  result: DeviceAnalysis;
+}
+
+export function analyzeDevice(value: unknown, options: DeviceOptions): DeviceAnalysis;
+export function isValidDevice(value: unknown, options: DeviceOptions): boolean;
+export function assertValidDevice(value: unknown, options: DeviceOptions): DeviceAnalysis;
+export function parseDevice(value: unknown, options: Pick<DeviceOptions, "series" | "inputMode">): ParsedDevice | null;
+export function normalizeDevice(value: unknown): string | null;
+export function normalizeModel(series: MelSeries | string, value?: unknown): string | null;
+export function getSupportedModels(series: MelSeries | string): string[];
+
+declare const api: {
+  MelDeviceError: typeof MelDeviceError;
+  analyzeDevice: typeof analyzeDevice;
+  assertValidDevice: typeof assertValidDevice;
+  getSupportedModels: typeof getSupportedModels;
+  isValidDevice: typeof isValidDevice;
+  normalizeDevice: typeof normalizeDevice;
+  normalizeModel: typeof normalizeModel;
+  parseDevice: typeof parseDevice;
+};
+export default api;

package/dist/index.js

@@ -0,0 +1,14 @@
+import api from "./index.cjs";
+
+export const {
+  MelDeviceError,
+  analyzeDevice,
+  assertValidDevice,
+  getSupportedModels,
+  isValidDevice,
+  normalizeDevice,
+  normalizeModel,
+  parseDevice
+} = api;
+
+export default api;

package/docs/manual-evidence.md

@@ -0,0 +1,136 @@
+# Manual evidence
+
+このファイルは、実装時に使用したPDFと判定値の対応を示します。ページ番号はPDFビューアの通しページではなく、マニュアル本文の印刷ページです。
+
+## 使用マニュアル
+
+| シリーズ | マニュアル | 文書番号・版 | 主な参照ページ |
+| --- | --- | --- | --- |
+| iQ-R | MELSEC iQ-R シーケンサCPUユニットユーザーズマニュアル | SH-082487-J | 65（機種別デフォルト点数）、408（デバイス一覧）、409-410（点数設定・最大使用範囲）、435-436（インデックス修飾） |
+| iQ-F | MELSEC iQ-F FX5ユーザーズマニュアル（応用編） | JY997D54301AF | 57（デバイス一覧）、69-70（インデックス）、76（割込みポインタ）、89（機種別使用範囲） |
+| MX-R | MELSEC MXコントローラ MX-Rモデルユーザーズマニュアル | SH-082640-D | 350（デバイス一覧・デフォルト点数）、351-352（点数設定・最大使用範囲）、380-381（インデックス修飾） |
+| MX-F | MELSEC MXコントローラ MX-Fモデルユーザーズマニュアル | SH-082633-E | 277（性能・デフォルト点数）、416（デバイス一覧）、417-418（点数設定・最大使用範囲） |
+| CR800 | CR800シリーズコントローラ 機能と操作の詳細解説 | BFP-A3477-AB | 5-489～5-491（CPUバッファ対応）、6-618～6-619（シーケンサリンク）、6-654（対応デバイス一覧）、6-655～6-657（デバイス割付） |
+
+## 基数
+
+| シリーズ | 8進 | 16進 | 10進 |
+| --- | --- | --- | --- |
+| iQ-F | X, Y | B, SB, W, SW | その他の通常デバイス |
+| iQ-R / MX-R / MX-F | - | X, Y, B, SB, W, SW, FX, FY | その他の通常デバイス |
+
+この差により、iQ-Fの `X1777` は有効候補ですが `X1780` は構文エラーです。一方、iQ-R/MXのX/Yは16進です。
+
+## iQ-F 機種別使用範囲
+
+本文89ページの表をそのまま上限へ変換しています。
+
+| 記号 | FX5S / FX5U / FX5UC | FX5UJ |
+| --- | ---: | ---: |
+| X, Y | 0-1777（8進） | 0-1777（8進） |
+| M | 0-32767 | 0-7679 |
+| B, SB | 0-7FFF（16進） | 0-7FF（16進） |
+| F | 0-32767 | 0-127 |
+| S | 0-4095 | 0-4095 |
+| T | 0-1023 | 0-511 |
+| ST | 0-1023 | 0-15 |
+| C | 0-1023 | 0-255 |
+| LC | 0-1023 | 0-63 |
+| D | 0-7999 | 0-7999 |
+| L | 0-32767 | 0-7679 |
+| R / ER | 0-32767 | 0-32767 |
+| W / SW | 0-7FFF（16進） | 0-3FF（16進） |
+
+FX5Sは本文57ページの注記により `U\G` 非対応です。ERはSDメモリカード上のデバイスであり、FX5Sで使用する場合は本文の別記載どおりSDメモリカードユニットが必要なので、詳細判定は設定依存になります。
+
+## iQ-R デフォルト差
+
+本文65ページおよび408-409ページに基づき、R00/R01/R02とそれ以外を分離しています。
+
+| 記号 | R00/R01/R02 | R04以上・ENCPU |
+| --- | ---: | ---: |
+| X, Y | 8K点 | 12K点 |
+| M | 8K点 | 12K点 |
+| T | 2K点 | 1K点 |
+| LT | 0点 | 1K点 |
+| C | 1K点 | 512点 |
+| LC | 0点 | 512点 |
+| D | 12K点 | 18K点 |
+| BL | 128点 | 320点 |
+
+B=8K、F=2K、SB=2K、V=2K、W=8K、SW=2K、L=8Kは共通です。S/ST/LST/R/ZR/TRのデフォルトは0点なので、`default` では無効、`maximum` または実際の `configuredPoints` を必要とします。
+
+本文410ページの最大値は「R120CPU + 16MB拡張SRAMカセット」条件であり、ほかの型名にそのまま保証できません。そのため `maximum` の成功結果でも `configurationDependent: true` を返します。
+
+## MX-R / MX-F
+
+デフォルトの主な点数は両シリーズで M=64K、B=32K、F=2K、SB=2K、V=2K、T=1K、LT=4K、C/LC=512、D=64K、W=32K、SW=2K、L=8Kです。ST/LST/R/ZRはデフォルト0点です。MX-RのSM/SDは4496点、Iは1024点です。MX-FのSM/SDは10000点、Iは256点です。MX-RのPはMXR300がデフォルト8192点／最大16384点、MXR500がデフォルト16384点／最大32768点です。
+
+最大使用範囲は次のとおりです。
+
+| 記号 | MX-R | MX-F |
+| --- | ---: | ---: |
+| M | 0-167747583 | 0-67084287 |
+| B / SB | 0-9FF9FFF（16進） | 0-3FF9FFF（16進） |
+| T / ST / C | 0-9319295 | 0-3726879 |
+| LT / LST | 0-2621055 | 0-1048191 |
+| LC | 0-4933727 | 0-1973055 |
+| D | 0-10484223 | 0-4192767 |
+| W / SW | 0-9FF9FF（16進） | 0-3FF9FF（16進） |
+
+両マニュアルとも、実際の最大値はグローバルラベル使用量で変化すると注記しています。
+
+## 修飾表記
+
+iQ-R本文436ページ、MX-R本文381ページ、MX-Fの同等節では、次の例が明示されています。
+
+- `K4M100Z2`
+- `D10Z2.0`
+- `D10.8Z2`
+- `@D10Z2`
+- `@D10.8`
+- `@D10Z2.8`
+- `@D10.8Z2`
+
+iQ-F本文69ページではZによる全デバイスのインデックス修飾、LZによる `U\G` の修飾が示されています。
+
+## 意図的な保守性
+
+- P/I/BL/TR等、マニュアルの一覧には存在しても通常の連続番号上限を十分に確定できない表記は、`syntax` では解析できますが、範囲モードでは根拠のない上限を推測しません。
+- リンクダイレクトとユニットアクセスは、コントローラが扱える最大値だけでは装着ユニット／ネットワーク上の実在性を保証できないため、成功時も設定依存です。
+- 特殊リレー・特殊レジスタは番号が範囲内でも、全番号に機能が割り当てられているとは限りません。本パッケージは「表記と領域の範囲」を判定し、個別のSM/SD用途までは判定しません。
+- `maximum` は「その型名の無条件保証」ではなく、マニュアルに記載されたシリーズ側の変更可能上限です。厳密な実機判定には `configured` を使用してください。
+
+## MELFA CR800-R/D/Q
+
+取扱説明書の本文6.8.1には、GOTまたはSLMP対応機器からアクセスできるデバイス範囲は固定で、変更できないと明記されています。このためCR800では設定点数による拡張を認めません。
+
+| モデル | X/Y（16進） | M（10進） | D（10進） | SM/SD（10進） | CPUメモリ（10進） |
+| --- | --- | --- | --- | --- | --- |
+| CR800-R | `0-FFF` | `0-18431` | `0-5119` | `0-4095` | `U3En\G0-524287`, `U3En\HG0-12287` |
+| CR800-D | `0-1FFF` | 非対応 | `0-5119` | `0-4095` | `U3E0/U3E1\HG0-2047` |
+| CR800-Q | `0-FFF` | `0-18431` | `0-5119` | `0-2047` | `U3En\G10000-24335` |
+
+表6-11～6-13により、MはDタイプで指定不可、CPUバッファのHGはQタイプで指定不可です。5.2.1および6.2.2ではロボットCPU No.1～3を`U3E1`～`U3E3`としてアクセスする対応が明記されているため、R/Qタイプのnは0～3として扱います。Dタイプは表6-12にn=0,1と明記されています。
+
+### デバイス割付とR/W属性
+
+表6-14～6-16の注記に従い、機能が無効または未割付の範囲はR/W、機能が有効な範囲は表の属性で判定します。`cr800Features`が省略された機能は不明扱いです。
+
+| モデル | 常時読出し専用 | 機能有効時に読出し専用 |
+| --- | --- | --- |
+| CR800-R | `X384-X38B`, `U3E1-U3E3\HG0-HG511` | QXYREAD: `X/Y0-FFF`; IQMEM: `U3E1-U3E3\HG512-HG1023`; DDEVVL状態変数: `D4096-D5119` |
+| CR800-D | `X320-X327`, `X384-X38B`, `U3E1\HG0-HG511` | パラレルI/O/GOT/PROFIBUS/CC-Link系の表6-15記載範囲; IQMEM: `U3E1\HG512-HG1023`; DDEVVL状態変数: `D4096-D5119` |
+| CR800-Q | `X384-X38B`, `U3E1-U3E3\G10000-G10511` | QXYREAD: `X/Y0-FFF`; DDEVVL状態変数: `D4096-D5119` |
+
+`U3E0`側のシーケンサリンク／拡張領域はR/Wです。DDEVVLはプログラム外部変数ならR/W、状態変数ならRです。
+
+### CR800-Q表6-16の不整合
+
+表6-16の共有メモリ拡張機能には`U3En\G512-G1023 (n=1,2,3)`と印刷されています。しかし、次の記載と両立しません。
+
+- 表6-13: CR800-Qの固定範囲は`U3En\G10000-G24335`
+- 表5-3／5-4: CR800-QはRタイプのHGアドレスに10000を加えたGアドレスで対応
+- 6.2.2／表6-4: `U3En\G10000-G10511`をロボットCPU No.nの領域として使用
+
+このため`U3En\G512-G1023`は有効範囲へ追加しません。該当入力には`MANUAL_RANGE_CONFLICT`を返します。IQMEMの意図された読み出し側アドレスと考えられる`U3En\G10512-G11023`は固定範囲としては有効ですが、表記不整合が解消できないため、IQMEM有効時でもR属性を断定せず`configuration-dependent`とします。これはマニュアル間の矛盾を隠して推測値を確定しないための意図的な保守性です。

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@mokouliszt/mel-device",
+  "version": "0.3.0",
+  "description": "Model-aware Mitsubishi MELSEC and MELFA device notation validator.",
+  "license": "MIT",
+  "author": "mokouliszt",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.ja.md",
+    "LICENSE",
+    "docs/manual-evidence.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "npm run build && node --test",
+    "prepack": "npm test"
+  },
+  "keywords": [
+    "mitsubishi",
+    "melsec",
+    "plc",
+    "device",
+    "iq-r",
+    "iq-f",
+    "mx-r",
+    "mx-f",
+    "cr800",
+    "melfa"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mokouliszt/mel-device.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mokouliszt/mel-device/issues"
+  },
+  "homepage": "https://github.com/mokouliszt/mel-device#readme"
+}