projen-pipelines 0.3.22 → 0.3.23

package/node_modules/@nodable/entities/src/EntityDecoder.js

@@ -5,6 +5,30 @@
 
 import { XML as DEFAULT_XML_ENTITIES } from "./entities.js"
 
+// ---------------------------------------------------------------------------
+// Entity hook action constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Action constants for `onExternalEntity` and `onInputEntity` hooks.
+ *
+ * Use these instead of raw strings to avoid typos:
+ *
+ * @example
+ * import EntityDecoder, { ENTITY_ACTION } from './EntityDecoder.js';
+ * const dec = new EntityDecoder({
+ *   onInputEntity: (name, value) => ENTITY_ACTION.BLOCK,
+ * });
+ */
+export const ENTITY_ACTION = Object.freeze({
+  /** Resolve and expand the entity normally. */
+  ALLOW: 'allow',
+  /** Silently skip this entity — it will not be registered. */
+  BLOCK: 'block',
+  /** Throw an error, aborting entity registration entirely. */
+  THROW: 'throw',
+});
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -169,6 +193,14 @@ export default class EntityDecoder {
    *   the effective action is max(onNCR, rangeMinimum).
    * @param {'remove'|'throw'} [options.ncr.nullNCR='remove']
    *   Action for U+0000 (null). 'allow' and 'leave' are clamped to 'remove' since null is never safe.
+   * @param {((name: string, value: string) => 'allow'|'block'|'throw')|null} [options.onExternalEntity=null]
+   *   Hook called when an external entity is registered via `setExternalEntities()` or
+   *   `addExternalEntity()`. Return `ENTITY_ACTION.ALLOW` to accept the entity,
+   *   `ENTITY_ACTION.BLOCK` to silently skip it, or `ENTITY_ACTION.THROW` to abort with an error.
+   * @param {((name: string, value: string) => 'allow'|'block'|'throw')|null} [options.onInputEntity=null]
+   *   Hook called when an input entity is registered via `addInputEntities()`. Return
+   *   `ENTITY_ACTION.ALLOW` to accept, `ENTITY_ACTION.BLOCK` to silently skip, or
+   *   `ENTITY_ACTION.THROW` to abort with an error.
    */
   constructor(options = {}) {
     this._limit = options.limit || {};
@@ -204,6 +236,43 @@ export default class EntityDecoder {
     this._ncrXmlVersion = ncrCfg.xmlVersion;
     this._ncrOnLevel = ncrCfg.onLevel;
     this._ncrNullLevel = ncrCfg.nullLevel;
+
+    // --- Registration hooks ---
+    /** @type {((name: string, value: string) => 'allow'|'block'|'throw')|null} */
+    this._onExternalEntity = typeof options.onExternalEntity === 'function'
+      ? options.onExternalEntity
+      : null;
+    /** @type {((name: string, value: string) => 'allow'|'block'|'throw')|null} */
+    this._onInputEntity = typeof options.onInputEntity === 'function'
+      ? options.onInputEntity
+      : null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Private: registration hook dispatch
+  // -------------------------------------------------------------------------
+
+  /**
+   * Invoke a registration hook for a single entity name/value pair.
+   * Returns true when the entity should be accepted, false when it should be
+   * silently skipped (BLOCK), and throws when the hook returns THROW.
+   *
+   * @param {((name: string, value: string) => 'allow'|'block'|'throw')|null} hook
+   * @param {string} name
+   * @param {string} value
+   * @param {string} context  — used in error messages ('external' | 'input')
+   * @returns {boolean}  true = accept, false = skip
+   */
+  _applyRegistrationHook(hook, name, value, context) {
+    if (!hook) return true; // no hook → always accept
+    const action = hook(name, value);
+    if (action === ENTITY_ACTION.BLOCK) return false;
+    if (action === ENTITY_ACTION.THROW) {
+      throw new Error(
+        `[EntityDecoder] Registration of ${context} entity "&${name};" was rejected by hook`
+      );
+    }
+    return true; // ALLOW or any unknown return value → accept
   }
 
   // -------------------------------------------------------------------------
@@ -213,6 +282,9 @@ export default class EntityDecoder {
   /**
    * Replace the full set of persistent external entities.
    * All keys are validated — throws on invalid characters.
+   * If `onExternalEntity` is set, it is called once per entry; entries that
+   * return `ENTITY_ACTION.BLOCK` are silently omitted, `ENTITY_ACTION.THROW`
+   * aborts the whole call.
    * @param {Record<string, string | { regex?: RegExp, val: string }>} map
    */
   setExternalEntities(map) {
@@ -221,18 +293,34 @@ export default class EntityDecoder {
         validateEntityName(key);
       }
     }
-    this._externalMap = mergeEntityMaps(map);
+    if (!this._onExternalEntity) {
+      this._externalMap = mergeEntityMaps(map);
+      return;
+    }
+    // Hook present — resolve values first, then filter
+    const flat = mergeEntityMaps(map);
+    const filtered = Object.create(null);
+    for (const [name, value] of Object.entries(flat)) {
+      if (this._applyRegistrationHook(this._onExternalEntity, name, value, 'external')) {
+        filtered[name] = value;
+      }
+    }
+    this._externalMap = filtered;
   }
 
   /**
    * Add a single persistent external entity.
+   * If `onExternalEntity` is set it is called before the entity is stored;
+   * `ENTITY_ACTION.BLOCK` silently skips storage, `ENTITY_ACTION.THROW` raises.
    * @param {string} key
    * @param {string} value
    */
   addExternalEntity(key, value) {
     validateEntityName(key);
     if (typeof value === 'string' && value.indexOf('&') === -1) {
-      this._externalMap[key] = value;
+      if (this._applyRegistrationHook(this._onExternalEntity, key, value, 'external')) {
+        this._externalMap[key] = value;
+      }
     }
   }
 
@@ -243,12 +331,25 @@ export default class EntityDecoder {
   /**
    * Inject DOCTYPE entities for the current document.
    * Also resets per-document expansion counters.
+   * If `onInputEntity` is set it is called once per entry; entries returning
+   * `ENTITY_ACTION.BLOCK` are silently omitted, `ENTITY_ACTION.THROW` aborts.
    * @param {Record<string, string | { regx?: RegExp, regex?: RegExp, val: string }>} map
    */
   addInputEntities(map) {
     this._totalExpansions = 0;
     this._expandedLength = 0;
-    this._inputMap = mergeEntityMaps(map);
+    if (!this._onInputEntity) {
+      this._inputMap = mergeEntityMaps(map);
+      return;
+    }
+    const flat = mergeEntityMaps(map);
+    const filtered = Object.create(null);
+    for (const [name, value] of Object.entries(flat)) {
+      if (this._applyRegistrationHook(this._onInputEntity, name, value, 'input')) {
+        filtered[name] = value;
+      }
+    }
+    this._inputMap = filtered;
   }
 
   // -------------------------------------------------------------------------
@@ -293,7 +394,7 @@ export default class EntityDecoder {
   decode(str) {
     if (typeof str !== 'string' || str.length === 0) return str;
     //TODO: check if needed
-    //if (str.indexOf('&') === -1) return str; // fast path — no entities at all
+    if (str.indexOf('&') === -1) return str; // fast path — no entities at all
 
     const original = str;
     const chunks = [];

package/node_modules/@nodable/entities/src/EntityEncoder.js

@@ -1,5 +1,7 @@
-// EntityDecoder.js
-import { trie1, trie2, trie3 } from './entityTries.js';
+// EntityEncoder.js
+import { buildTries } from './entityTries.js';
+// NOTE: no static import of ALL_ENTITIES / entities.js here — that import
+// was the actual tree-shaking leak (see constructor comment below).
 
 // Replacement strings indexed by char code — direct array access, no hashing
 const XML_UNSAFE_REPLACEMENT = new Array(128);
@@ -26,6 +28,42 @@ export default class EntityEncoder {
     this.encodeAllNamed = options.encodeAllNamed !== false;
     this.maxReplacements = options.maxReplacements || 0;
     this.replacementsCount = 0;
+
+    // Tries are only built when named-entity encoding is actually requested,
+    // and only from what the caller explicitly hands in. There is no
+    // built-in default entity set imported here — that static import was
+    // exactly what pinned the entire ALL_ENTITIES data (all categories) into
+    // every consumer's bundle regardless of what they actually used. A `||`
+    // fallback to a statically-imported default does NOT tree-shake: the
+    // import is still "used" from the bundler's point of view even if the
+    // runtime branch never executes.
+    //
+    // BREAKING CHANGE from earlier versions: `new EntityEncoder()` with no
+    // `namedEntities` and `encodeAllNamed !== false` now throws instead of
+    // silently encoding the full built-in set. Callers who want the old
+    // "encode everything" behavior must opt in explicitly:
+    //   import { ALL_ENTITIES } from '@nodable/entities';
+    //   new EntityEncoder({ namedEntities: ALL_ENTITIES });
+    if (this.encodeAllNamed) {
+      if (!options.namedEntities) {
+        throw new Error(
+          '[EntityEncoder] encodeAllNamed is true but no `namedEntities` was ' +
+          'provided. Pass a specific set (e.g. { ...COMMON_HTML, ...CURRENCY }) ' +
+          'or the full built-in set via `namedEntities: ALL_ENTITIES` imported ' +
+          'from \'@nodable/entities\'. This is required so bundlers can ' +
+          'tree-shake unused entity categories out of your build; set ' +
+          '`encodeAllNamed: false` if you don\'t need named-entity encoding at all.'
+        );
+      }
+      const tries = buildTries(options.namedEntities);
+      this.trie1 = tries.trie1;
+      this.trie2 = tries.trie2;
+      this.trie3 = tries.trie3;
+    } else {
+      this.trie1 = null;
+      this.trie2 = null;
+      this.trie3 = null;
+    }
   }
 
   encode(str) {
@@ -38,6 +76,9 @@ export default class EntityEncoder {
     // Hoist to locals — avoids `this` property lookup inside the hot loop
     const encodeXmlSafe = this.encodeXmlSafe;
     const encodeAllNamed = this.encodeAllNamed;
+    const trie1 = this.trie1;
+    const trie2 = this.trie2;
+    const trie3 = this.trie3;
 
     const len = str.length;
 
@@ -84,32 +125,34 @@ export default class EntityEncoder {
       let matchedEntity = null;
       let advance = 1;
 
-      // Try 3-char match first (longest wins)
-      const mid3 = trie3.get(c0);
-      if (mid3 !== undefined) {
-        const c1 = str.charCodeAt(i + 1);
-        const inner3 = mid3.get(c1);
-        if (inner3 !== undefined) {
-          const c2 = str.charCodeAt(i + 2);
-          const candidate = inner3.get(c2);
-          if (candidate !== undefined) { matchedEntity = candidate; advance = 3; }
+      if (encodeAllNamed) {
+        // Try 3-char match first (longest wins)
+        const mid3 = trie3.get(c0);
+        if (mid3 !== undefined) {
+          const c1 = str.charCodeAt(i + 1);
+          const inner3 = mid3.get(c1);
+          if (inner3 !== undefined) {
+            const c2 = str.charCodeAt(i + 2);
+            const candidate = inner3.get(c2);
+            if (candidate !== undefined) { matchedEntity = candidate; advance = 3; }
+          }
         }
-      }
 
-      // Try 2-char match
-      if (matchedEntity === null) {
-        const inner2 = trie2.get(c0);
-        if (inner2 !== undefined) {
-          const c1 = str.charCodeAt(i + 1);
-          const candidate = inner2.get(c1);
-          if (candidate !== undefined) { matchedEntity = candidate; advance = 2; }
+        // Try 2-char match
+        if (matchedEntity === null) {
+          const inner2 = trie2.get(c0);
+          if (inner2 !== undefined) {
+            const c1 = str.charCodeAt(i + 1);
+            const candidate = inner2.get(c1);
+            if (candidate !== undefined) { matchedEntity = candidate; advance = 2; }
+          }
         }
-      }
 
-      // Try 1-char match
-      if (matchedEntity === null && encodeAllNamed) {
-        const candidate = trie1.get(c0);
-        if (candidate !== undefined) { matchedEntity = candidate; }
+        // Try 1-char match
+        if (matchedEntity === null) {
+          const candidate = trie1.get(c0);
+          if (candidate !== undefined) { matchedEntity = candidate; }
+        }
       }
 
       if (matchedEntity !== null) {
@@ -153,18 +196,20 @@ export default class EntityEncoder {
       let matchedEntity = null;
       let advance = 1;
 
-      if (i + 1 < len) {
-        const inner2 = trie2.get(c0);
-        if (inner2 !== undefined) {
-          const c1 = str.charCodeAt(i + 1);
-          const candidate = inner2.get(c1);
-          if (candidate !== undefined) { matchedEntity = candidate; advance = 2; }
+      if (encodeAllNamed) {
+        if (i + 1 < len) {
+          const inner2 = trie2.get(c0);
+          if (inner2 !== undefined) {
+            const c1 = str.charCodeAt(i + 1);
+            const candidate = inner2.get(c1);
+            if (candidate !== undefined) { matchedEntity = candidate; advance = 2; }
+          }
         }
-      }
 
-      if (matchedEntity === null && encodeAllNamed) {
-        const candidate = trie1.get(c0);
-        if (candidate !== undefined) { matchedEntity = candidate; }
+        if (matchedEntity === null) {
+          const candidate = trie1.get(c0);
+          if (candidate !== undefined) { matchedEntity = candidate; }
+        }
       }
 
       if (matchedEntity !== null) {

package/node_modules/@nodable/entities/src/all-entities.js

@@ -0,0 +1,53 @@
+// all-entities.js
+//
+// ALL_ENTITIES lives in its OWN module, deliberately separate from
+// entities.js. An object spread like `{ ...GREEK, ...CYRILLIC, ... }` is
+// treated conservatively by bundlers (esbuild, Rollup, webpack) as a
+// potential side effect — spreading can invoke getters or Symbol.iterator —
+// so a module containing such a spread cannot be safely tree-shaken. If that
+// spread lived inside entities.js alongside the individual category exports,
+// its mere presence would pin every category into any bundle that imports
+// even one of them, regardless of whether ALL_ENTITIES itself is ever used.
+//
+// Keeping it isolated here means:
+//   - `import { COMMON_HTML } from './entities.js'` tree-shakes cleanly —
+//     no other category is dragged in.
+//   - Only consumers who explicitly `import { ALL_ENTITIES } from
+//     './all-entities.js'` (re-exported from index.js for convenience) pay
+//     for the full merged set.
+
+import {
+  BASIC_LATIN,
+  LATIN_ACCENTS,
+  LATIN_EXTENDED,
+  GREEK,
+  CYRILLIC,
+  MATH,
+  MATH_ADVANCED,
+  ARROWS,
+  SHAPES,
+  PUNCTUATION,
+  CURRENCY,
+  FRACTIONS,
+  MISC_SYMBOLS,
+} from './entities.js';
+
+/**
+ * All entities combined (if you need everything).
+ * @type {Record<string, string>}
+ */
+export const ALL_ENTITIES = {
+  ...BASIC_LATIN,
+  ...LATIN_ACCENTS,
+  ...LATIN_EXTENDED,
+  ...GREEK,
+  ...CYRILLIC,
+  ...MATH,
+  ...MATH_ADVANCED,
+  ...ARROWS,
+  ...SHAPES,
+  ...PUNCTUATION,
+  ...CURRENCY,
+  ...FRACTIONS,
+  ...MISC_SYMBOLS,
+};

package/node_modules/@nodable/entities/src/entities.js

@@ -34,7 +34,6 @@ export const BASIC_LATIN = {
   num: '#',
   dollar: '$',
   percent: '%',
-  amp: '&',
   ast: '*',
   commat: '@',
   lowbar: '_',
@@ -466,9 +465,6 @@ export const CYRILLIC = {
  */
 export const MATH = {
   plus: '+',
-  minus: '−',
-  mnplus: '∓',
-  mp: '∓',
   pm: '±',
   times: '×',
   div: '÷',
@@ -541,10 +537,6 @@ export const MATH = {
   bumpe: '≏',
   bumpeq: '≏',
   HumpEqual: '≏',
-  dotminus: '∸',
-  minusd: '∸',
-  plusdo: '∔',
-  dotplus: '∔',
   le: '≤',
   LessEqual: '≤',
   ge: '≥',
@@ -661,7 +653,6 @@ export const MATH_ADVANCED = {
   wreath: '≀',
   nsime: '≄',
   nsimeq: '≄',
-  nsimeq: '≄',
   ncong: '≇',
   simne: '≆',
   ncongdot: '⩭̸',
@@ -778,10 +769,6 @@ export const ARROWS = {
   mapsto: '↦',
   mapstodown: '↧',
   crarr: '↵',
-  nwarrow: '↖',
-  nearrow: '↗',
-  searrow: '↘',
-  swarrow: '↙',
   nleftarrow: '↚',
   nleftrightarrow: '↮',
   nrightarrow: '↛',
@@ -822,7 +809,6 @@ export const ARROWS = {
   ldrushar: '⥋',
   rdldhar: '⥩',
   lrhard: '⥭',
-  rlhar: '⇌',
   uharr: '↾',
   uharl: '↿',
   dharr: '⇂',
@@ -838,7 +824,6 @@ export const ARROWS = {
   nhArr: '⇎',
   nlarr: '↚',
   nlArr: '⇍',
-  nrarr: '↛',
   nrArr: '⇏',
   larrb: '⇤',
   LeftArrowBar: '⇤',
@@ -1000,7 +985,6 @@ export const PUNCTUATION = {
   DiacriticalDot: '˙',
   DiacriticalDoubleAcute: '˝',
   grave: '`',
-  acute: '´',
 };
 
 /**
@@ -1014,7 +998,6 @@ export const CURRENCY = {
   yen: '¥',
   euro: '€',
   dollar: '$',
-  euro: '€',
   fnof: 'ƒ',
   inr: '₹',
   af: '؋',
@@ -1114,7 +1097,6 @@ export const MISC_SYMBOLS = {
   Vdash: '⊩',
   dashv: '⊣',
   vDash: '⊨',
-  Vdash: '⊩',
   Vvdash: '⊪',
   nvdash: '⊬',
   nvDash: '⊭',
@@ -1122,26 +1104,6 @@ export const MISC_SYMBOLS = {
   nVDash: '⊯',
 };
 
-/**
- * All entities combined (if you need everything)
- * @type {Record<string, string>}
- */
-export const ALL_ENTITIES = {
-  ...BASIC_LATIN,
-  ...LATIN_ACCENTS,
-  ...LATIN_EXTENDED,
-  ...GREEK,
-  ...CYRILLIC,
-  ...MATH,
-  ...MATH_ADVANCED,
-  ...ARROWS,
-  ...SHAPES,
-  ...PUNCTUATION,
-  ...CURRENCY,
-  ...FRACTIONS,
-  ...MISC_SYMBOLS,
-};
-
 export const XML = {
   amp: "&",
   apos: "'",

package/node_modules/@nodable/entities/src/entityTries.js

@@ -1,49 +1,60 @@
 // entityTries.js
-// Builds integer-keyed tries so the decoder never allocates a string object
+// Builds integer-keyed tries so the encoder never allocates a string object
 // during lookup — every key is a plain charCode number.
 //
 // trie1: Map<code0, entity>
 // trie2: Map<code0, Map<code1, entity>>
 // trie3: Map<code0, Map<code1, Map<code2, entity>>>
+//
+// Trie construction is now a pure function, called on-demand by whoever
+// needs it (EntityEncoder, at instantiation time) instead of running
+// eagerly at module-import time against the full ALL_ENTITIES set. This
+// keeps the cost — and the entity data itself — out of any bundle/consumer
+// that never actually asks for it.
 
-import { ALL_ENTITIES } from './entities.js';
-
-// Reverse map: character sequence → "&name;"
-const CHAR_TO_ENTITY = new Map();
-for (const [name, chars] of Object.entries(ALL_ENTITIES)) {
-  CHAR_TO_ENTITY.set(chars, `&${name};`);
-}
-
-export const trie1 = new Map();   // code0          → entity string
-export const trie2 = new Map();   // code0 → Map    → entity string
-export const trie3 = new Map();   // code0 → Map → Map → entity string
+/**
+ * Build integer-keyed tries from a name → chars entity map.
+ * @param {Record<string, string>} entityMap
+ * @returns {{ trie1: Map, trie2: Map, trie3: Map }}
+ */
+export function buildTries(entityMap) {
+  const trie1 = new Map();   // code0          → entity string
+  const trie2 = new Map();   // code0 → Map    → entity string
+  const trie3 = new Map();   // code0 → Map → Map → entity string
 
-for (const [chars, entity] of CHAR_TO_ENTITY) {
-  const len = chars.length;
+  // Reverse map: character sequence → "&name;"
+  // (built inline, not kept around — only the tries need to survive)
+  for (const name in entityMap) {
+    const chars = entityMap[name];
+    const entity = `&${name};`;
+    const len = chars.length;
 
-  if (len === 1) {
-    const c0 = chars.charCodeAt(0);
-    // Keep shortest match only if no longer match already claimed this code
-    // (longer matches are inserted in the same pass so we just overwrite —
-    //  trie1 is only consulted after trie2/trie3 both miss, so no conflict)
-    trie1.set(c0, entity);
+    if (len === 1) {
+      const c0 = chars.charCodeAt(0);
+      // Keep shortest match only if no longer match already claimed this code
+      // (longer matches are inserted in the same pass so we just overwrite —
+      //  trie1 is only consulted after trie2/trie3 both miss, so no conflict)
+      trie1.set(c0, entity);
 
-  } else if (len === 2) {
-    const c0 = chars.charCodeAt(0);
-    const c1 = chars.charCodeAt(1);
-    let inner = trie2.get(c0);
-    if (inner === undefined) { inner = new Map(); trie2.set(c0, inner); }
-    inner.set(c1, entity);
+    } else if (len === 2) {
+      const c0 = chars.charCodeAt(0);
+      const c1 = chars.charCodeAt(1);
+      let inner = trie2.get(c0);
+      if (inner === undefined) { inner = new Map(); trie2.set(c0, inner); }
+      inner.set(c1, entity);
 
-  } else if (len === 3) {
-    const c0 = chars.charCodeAt(0);
-    const c1 = chars.charCodeAt(1);
-    const c2 = chars.charCodeAt(2);
-    let mid = trie3.get(c0);
-    if (mid === undefined) { mid = new Map(); trie3.set(c0, mid); }
-    let inner = mid.get(c1);
-    if (inner === undefined) { inner = new Map(); mid.set(c1, inner); }
-    inner.set(c2, entity);
+    } else if (len === 3) {
+      const c0 = chars.charCodeAt(0);
+      const c1 = chars.charCodeAt(1);
+      const c2 = chars.charCodeAt(2);
+      let mid = trie3.get(c0);
+      if (mid === undefined) { mid = new Map(); trie3.set(c0, mid); }
+      let inner = mid.get(c1);
+      if (inner === undefined) { inner = new Map(); mid.set(c1, inner); }
+      inner.set(c2, entity);
+    }
+    // HTML5 has no named entity whose character sequence is longer than 3 chars
   }
-  // HTML5 has no named entity whose character sequence is longer than 3 chars
-}
+
+  return { trie1, trie2, trie3 };
+}