milsymbol-sidc 0.3.0 → 0.4.0

package/README.md

@@ -1,5 +1,6 @@
 # milsymbol-sidc
 
+[![CI](https://github.com/psylsph/milsymbol-sidc/actions/workflows/ci.yml/badge.svg)](https://github.com/psylsph/milsymbol-sidc/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/milsymbol-sidc.svg)](https://www.npmjs.com/package/milsymbol-sidc)
 [![npm downloads](https://img.shields.io/npm/dm/milsymbol-sidc.svg)](https://www.npmjs.com/package/milsymbol-sidc)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -35,8 +36,8 @@ new ms.Symbol(sidc).asSVG(); // friendly land unit icon
 
 > **Coverage:** complete structural encoding for positions 1–20 of the numeric
 > SIDC. Positions 8–10 have named universal codes; positions 11–20 accept
-> validated raw entity and modifier codes. Symbol-set-specific entity and
-> modifier catalogs remain future work.
+> validated raw entity and modifier codes. A membership-only code catalog ships
+> behind the `milsymbol-sidc/catalogs` subpath; semantic names remain future work.
 
 ## Installation
 
@@ -142,6 +143,7 @@ Present. This remains the default for backward compatibility; configure
 | ------ | ---- | ------- | ----------- |
 | `strict` | `boolean` | `false` | Throw on invalid field combinations during `toString()` instead of warning. Invalid values always throw immediately regardless of this flag. |
 | `standard` | `Standard` | Not configured (2525E behavior) | Select a standard family. `App6` defaults the version to APP-6 E (`"14"`); `MilStd2525` defaults it to MIL-STD-2525E (`"13"`). Explicit configuration also checks that later version choices belong to the selected family. |
+| `onWarning` | `(problem: SidcProblem) => void` | `console.warn` | Receive non-fatal problems instead of writing to the console. `strict: true` still throws instead of reporting. |
 
 ### Methods
 
@@ -161,6 +163,14 @@ All setters validate their argument and return a new immutable `Sidc`.
 | `modifier1(v)` | Positions 17–18 | Any two-digit string; symbol-set-specific catalogs are not included |
 | `modifier2(v)` | Positions 19–20 | Any two-digit string; symbol-set-specific catalogs are not included |
 | `toString()` | — | Validates combinations and renders the 20-character SIDC |
+| `problems()` | — | Structured list of non-fatal problems; never throws |
+| `isValid()` | — | `true` when `problems()` is empty |
+| `with(fields)` | — | Applies a partial field record immutably; validates like the setters |
+| `clone()` | — | Copies the fields into an independent builder |
+| `equals(other)` | — | Compares encoded fields, ignoring `strict` and `standard` |
+| `toObject()` / `toJSON()` | — | Plain, serializable snapshot of every encoded field |
+| `Sidc.parse(s, options?)` | — | Parses a 20-character numeric SIDC; throws when invalid |
+| `Sidc.tryParse(s, options?)` | — | Parses a SIDC or returns `undefined` |
 
 ### Enum reference
 
@@ -390,6 +400,72 @@ try {
 Error classes: `SidcError` (base) → `SidcValidationError`,
 `SidcCombinationError`.
 
+### Reading and reporting problems
+
+`console.warn` is only the default. Inspect problems without side effects with
+`problems()` and `isValid()`, or route them anywhere with `onWarning`:
+
+```ts
+import { Sidc, SymbolSet, Status } from "milsymbol-sidc";
+
+const sidc = new Sidc()
+  .symbolSet(SymbolSet.ControlMeasure)
+  .status(Status.Destroyed);
+
+sidc.problems();
+// [{ code: "condition-status-control-measure", message: "…" }]
+sidc.isValid(); // false
+
+new Sidc({ onWarning: (problem) => log.warn(problem.code) })
+  .symbolSet(SymbolSet.ControlMeasure)
+  .status(Status.Destroyed)
+  .toString(); // no console output; onWarning is called once
+```
+
+Every problem carries a stable `code` and the exact legacy warning `message`.
+`problems()` never throws, even for builders created with `{ strict: true }`;
+`toString()` still throws `SidcCombinationError` in strict mode.
+
+## Parsing a SIDC
+
+`Sidc.parse()` turns a 20-character numeric SIDC back into a builder so you can
+validate, edit, and re-render existing codes. `Sidc.tryParse()` returns
+`undefined` instead of throwing.
+
+```ts
+import { Sidc } from "milsymbol-sidc";
+
+const sidc = Sidc.parse("14031002161234560109");
+sidc.toObject().entity; // "123456"
+
+sidc.with({ modifier1: "02" }).toString(); // "14031002161234560209"
+Sidc.tryParse("not-a-sidc"); // undefined
+```
+
+Round-tripping is guaranteed: `Sidc.parse(s).toString() === s` for any string
+this library produces. Only the 20-character numeric form is supported today;
+letter-based SIDCs and the 21–30 character extension are not.
+
+## Catalogs (optional)
+
+The `milsymbol-sidc/catalogs` subpath exposes a membership catalog generated from
+milsymbol's numeric symbol data: which entity and modifier codes milsymbol
+registers for each symbol set. It is a separate entry point, so the core builder
+stays data-free unless you import it.
+
+```ts
+import { entityCodes, isKnownEntityCode } from "milsymbol-sidc/catalogs";
+
+isKnownEntityCode("10", "121100"); // true — a registered land-unit entity
+isKnownEntityCode("10", "999999"); // false
+entityCodes("10").length; // number of registered land-unit codes
+```
+
+The catalog is **membership only**: it carries no semantic names and is never
+consulted by `toString()`, so raw entity and modifier values still encode
+without recognition warnings. Regenerate it with `npm run generate:catalogs`;
+the milsymbol version it was derived from is exported as `CATALOG_SOURCE`.
+
 ## Using with milsymbol
 
 milsymbol routes any SIDC whose first two characters are digits to its numeric
@@ -524,10 +600,16 @@ new Sidc({ standard: Standard.App6, strict: true })
 
 ```bash
 npm install
-npm test     # compiles with tsc, then runs node --test against dist/
+npm test                  # compiles with tsc, then runs node --test against dist/
 npm run build
+npm run lint              # eslint
+npm run format:check      # prettier
+npm run generate:catalogs # regenerate src/catalogs.generated.ts from milsymbol
 ```
 
+CI runs the test suite on Node 18/20/22/24, plus lint, formatting, markdownlint,
+coverage, and a check that the generated catalog is current.
+
 Test coverage includes per-field offset encoding for every enum member,
 defaults, immutability, setter validation errors, extended-field offsets,
 all combination rules in both warn and strict modes, raw-code escape hatches,
@@ -535,10 +617,8 @@ and error class hierarchy.
 
 ## Roadmap
 
-- Symbol-set-specific named entity and modifier catalogs with semantic
-  validation.
+- Semantic entity and modifier names, layered on the membership catalog.
 - Official positions 21–30 / Set C extension data.
-- Parsing/decoding SIDC strings back into structured fields.
 
 ## License
 

package/dist/src/catalog.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Optional membership catalogs derived from milsymbol's numeric symbol data.
+ *
+ * Import from the `milsymbol-sidc/catalogs` subpath. This module is deliberately
+ * **not** part of the main entry point, so bundlers that only use the builder
+ * never include the catalog data.
+ *
+ * These catalogs answer "which codes does milsymbol register for this symbol
+ * set?". They intentionally carry no semantic names, and they are never
+ * consulted by `Sidc.toString()` - raw entity and modifier values continue to
+ * encode without recognition warnings.
+ *
+ * ```ts
+ * import { isKnownEntityCode } from "milsymbol-sidc/catalogs";
+ *
+ * isKnownEntityCode("10", "121100"); // true for land units
+ * isKnownEntityCode("10", "999999"); // false
+ * ```
+ */
+import { CATALOG_SOURCE } from "./catalogs.generated.js";
+export { CATALOG_SOURCE };
+export type CatalogSource = typeof CATALOG_SOURCE;
+/** Every symbol set the catalog covers, sorted ascending. */
+export declare function catalogSymbolSets(): readonly string[];
+/** `true` when any catalog data exists for the symbol set. */
+export declare function hasCatalog(symbolSet: string): boolean;
+/** Six-digit entity codes milsymbol registers for a symbol set. */
+export declare function entityCodes(symbolSet: string): readonly string[];
+/** `true` when the entity code is registered for the symbol set. */
+export declare function isKnownEntityCode(symbolSet: string, entity: string): boolean;
+/** Two-digit modifier 1 codes milsymbol registers for a symbol set. */
+export declare function modifier1Codes(symbolSet: string): readonly string[];
+/** `true` when modifier 1 is registered for the symbol set. */
+export declare function isKnownModifier1Code(symbolSet: string, modifier: string): boolean;
+/** Two-digit modifier 2 codes milsymbol registers for a symbol set. */
+export declare function modifier2Codes(symbolSet: string): readonly string[];
+/** `true` when modifier 2 is registered for the symbol set. */
+export declare function isKnownModifier2Code(symbolSet: string, modifier: string): boolean;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/src/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,cAAc,EAIf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,MAAM,MAAM,aAAa,GAAG,OAAO,cAAc,CAAC;AAiBlD,6DAA6D;AAC7D,wBAAgB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAErD;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEhE;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAE5E;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEnE;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAET;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEnE;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAET"}

package/dist/src/catalog.js

@@ -0,0 +1,63 @@
+/**
+ * Optional membership catalogs derived from milsymbol's numeric symbol data.
+ *
+ * Import from the `milsymbol-sidc/catalogs` subpath. This module is deliberately
+ * **not** part of the main entry point, so bundlers that only use the builder
+ * never include the catalog data.
+ *
+ * These catalogs answer "which codes does milsymbol register for this symbol
+ * set?". They intentionally carry no semantic names, and they are never
+ * consulted by `Sidc.toString()` - raw entity and modifier values continue to
+ * encode without recognition warnings.
+ *
+ * ```ts
+ * import { isKnownEntityCode } from "milsymbol-sidc/catalogs";
+ *
+ * isKnownEntityCode("10", "121100"); // true for land units
+ * isKnownEntityCode("10", "999999"); // false
+ * ```
+ */
+import { CATALOG_SOURCE, ENTITY_CODES, MODIFIER_1_CODES, MODIFIER_2_CODES, } from "./catalogs.generated.js";
+export { CATALOG_SOURCE };
+const EMPTY = Object.freeze([]);
+const SYMBOL_SETS = new Set([
+    ...Object.keys(ENTITY_CODES),
+    ...Object.keys(MODIFIER_1_CODES),
+    ...Object.keys(MODIFIER_2_CODES),
+]);
+function codesFor(table, symbolSet) {
+    return table[symbolSet] ?? EMPTY;
+}
+/** Every symbol set the catalog covers, sorted ascending. */
+export function catalogSymbolSets() {
+    return Object.freeze([...SYMBOL_SETS].sort());
+}
+/** `true` when any catalog data exists for the symbol set. */
+export function hasCatalog(symbolSet) {
+    return SYMBOL_SETS.has(symbolSet);
+}
+/** Six-digit entity codes milsymbol registers for a symbol set. */
+export function entityCodes(symbolSet) {
+    return codesFor(ENTITY_CODES, symbolSet);
+}
+/** `true` when the entity code is registered for the symbol set. */
+export function isKnownEntityCode(symbolSet, entity) {
+    return entityCodes(symbolSet).includes(entity);
+}
+/** Two-digit modifier 1 codes milsymbol registers for a symbol set. */
+export function modifier1Codes(symbolSet) {
+    return codesFor(MODIFIER_1_CODES, symbolSet);
+}
+/** `true` when modifier 1 is registered for the symbol set. */
+export function isKnownModifier1Code(symbolSet, modifier) {
+    return modifier1Codes(symbolSet).includes(modifier);
+}
+/** Two-digit modifier 2 codes milsymbol registers for a symbol set. */
+export function modifier2Codes(symbolSet) {
+    return codesFor(MODIFIER_2_CODES, symbolSet);
+}
+/** `true` when modifier 2 is registered for the symbol set. */
+export function isKnownModifier2Code(symbolSet, modifier) {
+    return modifier2Codes(symbolSet).includes(modifier);
+}
+//# sourceMappingURL=catalog.js.map

package/dist/src/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,CAAC;AAG1B,MAAM,KAAK,GAAsB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAEnD,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC;IAC/C,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC;IAC5B,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC;IAChC,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC;CACjC,CAAC,CAAC;AAEH,SAAS,QAAQ,CACf,KAAkD,EAClD,SAAiB;IAEjB,OAAO,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC;AACnC,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,SAAiB;IAC1C,OAAO,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,OAAO,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AAC3C,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,MAAc;IACjE,OAAO,WAAW,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACjD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;AAC/C,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,QAAgB;IAEhB,OAAO,cAAc,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;AAC/C,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,QAAgB;IAEhB,OAAO,cAAc,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACtD,CAAC"}

package/dist/src/catalogs.generated.d.ts

@@ -0,0 +1,20 @@
+/**
+ * GENERATED FILE - do not edit by hand.
+ *
+ * Membership catalog derived from milsymbol 3.0.4 (MIT),
+ * Copyright (c) 2017 Måns Beckman - https://www.spatialillusions.com
+ *
+ * Regenerate with `npm run generate:catalogs`.
+ */
+/** Package and version the catalog was generated from. */
+export declare const CATALOG_SOURCE: {
+    readonly name: "milsymbol";
+    readonly version: "3.0.4";
+};
+/** Six-digit entity codes milsymbol registers, keyed by symbol set. */
+export declare const ENTITY_CODES: Readonly<Record<string, readonly string[]>>;
+/** Two-digit modifier 1 codes milsymbol registers, keyed by symbol set. */
+export declare const MODIFIER_1_CODES: Readonly<Record<string, readonly string[]>>;
+/** Two-digit modifier 2 codes milsymbol registers, keyed by symbol set. */
+export declare const MODIFIER_2_CODES: Readonly<Record<string, readonly string[]>>;
+//# sourceMappingURL=catalogs.generated.d.ts.map

package/dist/src/catalogs.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogs.generated.d.ts","sourceRoot":"","sources":["../../src/catalogs.generated.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CA0sCjE,CAAC;AAEL,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CA0uBrE,CAAC;AAEL,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CA4PrE,CAAC"}