scjson 0.3.5 → 0.4.0

package/dist/comment_promotion.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Local tag names that own a ``help_text`` field on the model side.
+ * Mirrors ``APPLIES_TO_TAGS`` in ``py/scjson/comment_promotion.py``.
+ */
+export const APPLIES_TO_TAGS: Set<string>;
+/**
+ * Tags whose textual content is opaque target-language source. Comments
+ * inside these elements remain content and MUST NOT be promoted (CONV-F
+ * rule 5).
+ */
+export const SOURCE_BODY_TAGS: Set<string>;
+export namespace TAG_TO_ATTR {
+    let _if: string;
+    export { _if as if };
+    export let raise: string;
+    let _else: string;
+    export { _else as else };
+}
+/**
+ * Fields in the JS model that hold a *singleton* object rather than an
+ * array of objects under XML elements named ``transition``.
+ *
+ * Used by ``resolveAddress`` so a singleton field can still satisfy an
+ * address segment ``["transition", 0]`` even though it is not wrapped in
+ * a JS array.
+ */
+export const SINGLETON_TRANSITION_PARENTS: Set<string>;
+/**
+ * Return the JS model attribute name for an XML local tag.
+ *
+ * @param {string} tag - XML local tag name.
+ * @returns {string} Attribute name on the JS model object.
+ */
+export function modelAttrForTag(tag: string): string;
+/**
+ * Canonical key for a tuple-address. Used as a Map key so two addresses
+ * with the same shape collide.
+ *
+ * @param {Array<[string, number]>} address - Tuple address.
+ * @returns {string} JSON serialization of the address.
+ */
+export function addressKey(address: Array<[string, number]>): string;
+/**
+ * Repair raw XML comment body text per CONV-F §294-299.
+ *
+ * Strips a common leading indentation margin from multi-line block comments
+ * and trims leading/trailing blank lines. Does NOT paragraph-wrap or
+ * coalesce. Single-line comments are stripped only of edge whitespace.
+ *
+ * @param {string} raw - Comment body text without the ``<!--`` / ``-->``
+ *     delimiters.
+ * @returns {string} Repaired text suitable for storage in ``help_text``.
+ */
+export function repairCommentText(raw: string): string;
+/**
+ * Return a body string safe to wrap in ``<!-- ... -->``.
+ *
+ * Per CONV-F §340-344: the forbidden sequence ``--`` is replaced with
+ * ``- -`` and a body ending in ``-`` gets one trailing space appended.
+ *
+ * @param {string} text - Repaired help_text entry.
+ * @returns {string} Comment-safe body.
+ */
+export function emitSafeCommentText(text: string): string;
+/**
+ * Extract help_text promotion metadata from an SCXML string.
+ *
+ * @param {string} xmlStr - Raw SCXML string.
+ * @returns {{cleanedXml: string, addressMap: Map<string, string[]>, addressMapJson: Array<{address: Array<[string,number]>, comments: string[]}>}}
+ *     The comment-free XML serialization and the address map.
+ *     ``addressMapJson`` provides a stable JSON-friendly projection for
+ *     downstream callers or cross-language fixture comparison.
+ *     On parse failure returns the original string and an empty map.
+ */
+export function extractHelpTextFromXml(xmlStr: string): {
+    cleanedXml: string;
+    addressMap: Map<string, string[]>;
+    addressMapJson: Array<{
+        address: Array<[string, number]>;
+        comments: string[];
+    }>;
+};
+/**
+ * Append each address's comment list to the corresponding model element's
+ * ``help_text`` array.
+ *
+ * Comments are appended to any existing ``help_text`` entries per CONV-F
+ * rule 7.
+ *
+ * @param {object} model - Root SCJSON object.
+ * @param {Map<string, string[]>} addressMap - Map produced by
+ *     ``extractHelpTextFromXml``.
+ */
+export function attachHelpTextToModel(model: object, addressMap: Map<string, string[]>): void;
+/**
+ * Re-emit ``xmlStr`` with each model element's ``help_text`` entries as
+ * leading XML comments.
+ *
+ * @param {string} xmlStr - Comment-free SCXML produced by the existing
+ *     ``jsonToXml`` pipeline.
+ * @param {object} model - The SCJSON model whose ``help_text`` lists drive
+ *     injection.
+ * @returns {string} SCXML with leading comments inserted.
+ */
+export function injectHelpTextCommentsIntoXml(xmlStr: string, model: object): string;