@createiq/htmldiff 1.0.1 → 1.0.2

package/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

package/.gitlab-ci.yml

@@ -1,15 +1,17 @@
 stages:
   - test
   - deploy
+  - generate_artifacts
 
 default:
   interruptible: true
 
 "Run unit tests":
   stage: test
-  image: ${CI_REGISTRY}/infra/baseimages/node:22-alpine
+  image: ${ACR_HOSTNAME}/infra/baseimages/node:22-alpine
+  before_script:
+    - npm ci --prefer-offline --no-audit
   script:
-    - npm i
     - VITEST_MAX_THREADS=4 npm run test:ci -- --coverage
   allow_failure: false
   needs: []
@@ -26,12 +28,14 @@ default:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_TRIGGERED != "true"
     - if: $CI_COMMIT_BRANCH == "prod" && $CI_PIPELINE_TRIGGERED != "true"
+  tags: ["kluster:aks-ciqi-eun"]
 
 "Lint":
   stage: test
-  image: ${CI_REGISTRY}/infra/baseimages/node:22-alpine
+  image: ${ACR_HOSTNAME}/infra/baseimages/node:22-alpine
+  before_script:
+    - npm ci --prefer-offline --no-audit
   script:
-    - npm i
     - npm run lint
     - npm run format
   allow_failure: false
@@ -40,32 +44,101 @@ default:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_TRIGGERED != "true"
     - if: $CI_COMMIT_BRANCH == "prod" && $CI_PIPELINE_TRIGGERED != "true"
+  tags: ["kluster:aks-ciqi-eun"]
 
+# TODO this runs on gke01-london for firewall reasons to be able to talk to registry.npmjs.org
 "Publish to npm - dry-run":
   stage: deploy
   image: ${CI_REGISTRY}/infra/baseimages/node:22-alpine
+  before_script:
+    - npm ci --prefer-offline --no-audit
   script:
-    - npm i
     - npm run build
     # Use the default registry for publishing
     - npm --verbose config --global delete registry
-    - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt HTTPS_PROXY=$PROJENV_HTTPS_PROXY NO_PROXY=$PROJENV_NO_PROXY npm publish --access public --dry-run
+    - npm publish --access public --dry-run
   allow_failure: false
   # No needs, only run if the test stage passes
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_TRIGGERED != "true"
+  tags: ["kluster:gke01-london"]
 
+# TODO this runs on gke01-london for firewall reasons to be able to talk to registry.npmjs.org
 "Publish to npm":
   stage: deploy
   image: ${CI_REGISTRY}/infra/baseimages/node:22-alpine
+  before_script:
+    - npm ci --prefer-offline --no-audit
   script:
-    - npm i
     - npm run build
     # Use the default registry for publishing
     - npm --verbose config --global delete registry
-    - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt HTTPS_PROXY=$PROJENV_HTTPS_PROXY NO_PROXY=$PROJENV_NO_PROXY npm publish --access public
+    - npm publish --access public
   allow_failure: false
   # No needs, only run if the test stage passes
   rules:
-    - if: $CI_COMMIT_BRANCH == "prod" && $CI_PIPELINE_TRIGGERED != "true"
+    - if: $CI_COMMIT_BRANCH == "prod" && $CI_PIPELINE_TRIGGERED != "true"
+  tags: ["kluster:gke01-london"]
+
+.generate_sbom: &generate_sbom
+  stage: generate_artifacts
+  image: ${ACR_HOSTNAME}/infra/baseimages/node:22-alpine
+  before_script:
+    - npm ci --prefer-offline --no-audit
+  script:
+    - mkdir -p cyclonedx
+    - npm exec -- @cyclonedx/cyclonedx-npm --package-lock-only --omit dev --spec-version 1.6 --mc-type library --output-file cyclonedx/bom_${CI_COMMIT_SHORT_SHA}.json --validate
+  artifacts:
+    name: "sbom_htmldiff_$CI_COMMIT_SHORT_SHA"
+    paths:
+      - cyclonedx/*
+    expire_in: 1 month
+  tags: ["kluster:aks-ciqi-eun"]
+
+.push_sbom_deptrack: &push_sbom_deptrack
+  stage: generate_artifacts
+  variables:
+    DTRACK_SERVER: https://dependencytrack.stag.a.nakhoda.ai
+    DTRACK_API_KEY: odt_DKxpr0Sx_TmAc11wSPPl1YphFxEuiwDPb1VmSRY7d
+    DTRACK_PROJECT: 2f456575-183e-4985-99f6-ad8767b86476
+  script:
+    - |-
+      cat <<EOF >payload.json
+      {
+        "project": "${DTRACK_PROJECT}",
+        "bom": "$(base64 --wrap=0 cyclonedx/bom_${CI_COMMIT_SHORT_SHA}.json)"
+      }
+      EOF
+    # Upload using a limited permission API key that can only upload SBOMs
+    - |
+      curl --fail-with-body -X "PUT" "${DTRACK_SERVER}/api/v1/bom" \
+           -H 'Content-Type: application/json' \
+           -H "X-API-Key: ${DTRACK_API_KEY}" \
+           -d @payload.json
+  tags: ["kluster:aks-ciqi-eun"]
+
+"Generate SBOM":
+  <<: *generate_sbom
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_TRIGGERED != "true"
+
+"Push SBOM to Dependency-Track":
+  <<: *push_sbom_deptrack
+  needs:
+    - "Generate SBOM"
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_TRIGGERED != "true"
+
+# Don't need this on every build but useful for testing changes to the above
+#"MR: Generate SBOM":
+#  <<: *generate_sbom
+#  rules:
+#    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+#
+#"MR: Push SBOM to Dependency-Track":
+#  <<: *push_sbom_deptrack
+#  needs:
+#    - "MR: Generate SBOM"
+#  rules:
+#    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

package/.husky/pre-commit

@@ -0,0 +1 @@
+npm exec -- lint-staged

package/README.md

@@ -1,5 +1,140 @@
-## Project Description
+## @createiq/htmldiff
 
-A library for comparing two HTML files/snippets and highlighting the differences using simple HTML.
+A library for comparing two HTML snippets and highlighting the differences using simple HTML.
 
-This HTML Diff implementation is a TypeScript port of the C# port found [here](https://github.com/Rohland/htmldiff.net), which is a port of the ruby implementation found [here](https://github.com/myobie/htmldiff).
+This HTML Diff implementation is a TypeScript port of the C# port found [here](https://github.com/Rohland/htmldiff.net),
+which is a port of the ruby implementation found [here](https://github.com/myobie/htmldiff).
+
+## Installation
+
+`npm install @createiq/htmldiff`
+
+## Usage
+
+This is intended to be a drop-in replacement for the `htmldiff` npm library (https://github.com/dfoverdx/htmldiff-js),
+and intentionally mirrors the structure and classes of the [HtmlDiff.NET](https://github.com/Rohland/htmldiff.net)
+library that was initially ported, hence usage differing slightly from many JavaScript-ecosystem libraries.
+
+```ts
+import HtmlDiff from '@createiq/htmldiff'
+
+const oldHtml = `<p>Some <em>old</em> html here</p>`
+const newHtml = `<p>Some <b>new</b> html goes here</p>`
+
+const diffHtml = HtmlDiff.execute(oldHtml, newHtml)
+
+// Output: <p>Some <ins class='mod em'><del class='diffmod'>old</del></ins><b><ins class='mod b'><ins class='diffmod'>new</ins></ins></b> html <ins class='diffins'>goes </ins>here</p>
+```
+
+### Configuring the diff output
+
+There are a couple of options that can be set directly on the `HtmlDiff` instance, `HtmlDiff.execute` will always create
+a new instance and use defaults, but for custom output you can use `new HtmlDiff(oldHtml, newHtml)` and set the options
+directly:
+
+```ts
+import HtmlDiff from '@createiq/htmldiff'
+
+const oldHtml = `<p>Some <em>old</em> html here</p>`
+const newHtml = `<p>Some <b>new</b> html goes here</p>`
+
+const diff = new HtmlDiff(oldHtml, newHtml)
+diff.repeatingWordsAccuracy = 0.5
+diff.ignoreWhitespaceDifferences = true
+diff.orphanMatchThreshold = 0.2
+
+const diffHtml = diff.build()
+```
+
+## API
+
+### HtmlDiff.execute(oldHtml, newHtml)
+
+Returns a HTML diff from `oldHtml` to `newHtml` with the default options. This is exactly the same as calling
+`new HtmlDiff(oldHtml, newHtml).build()`
+
+### new HtmlDiff(oldHtml, newHtml)
+
+Returns an HtmlDiff instance.
+
+#### addBlockExpression(expression: RegExp)
+
+Uses `expression` to group text together so that any change detected within the group is treated as a single block, for
+example to keep dates together.
+
+This **MUST** have the global flag (`/g`) enabled on the RegExp and must not overlap with other block expressions.
+
+Example:
+
+```ts
+const oldHtml = 'This is a date 1 Jan 2016 that will change'
+const newHtml = 'This is a date 22 Feb 2017 that did change'
+
+const diff = new HtmlDiff(oldHtml, newHtml)
+diff.addBlockExpression(/\d{1,2}\s*(Jan|Feb)\s*\d{4}/g)
+
+const diffHtml = diff.build()
+
+// Output: This is a date<del class='diffmod'> 1 Jan 2016</del><ins class='diffmod'> 22 Feb 2017</ins> that <del class='diffmod'>will</del><ins class='diffmod'>did</ins> change
+```
+
+#### .repeatingWordsAccuracy <sup>get/set</sup>
+
+Type: `number`\
+Default: `1.0`
+
+Defines how to compare repeating words. Valid values are from 0 to 1. This value allows to exclude some words from
+comparison that eventually reduces the total time of the diff algorithm.
+
+- `0` means that all words are excluded so the diff will not find any matching words at all.
+- `1` (default value) means that all words participate in comparison so this is the most accurate case.
+- `0.5` means that any word that occurs more than 50% times may be excluded from comparison. This doesn't
+  mean that such words will definitely be excluded but only gives a permission to exclude them if necessary.
+
+#### .ignoreWhitespaceDifferences <sup>get/set</sup>
+
+Type: `boolean`\
+Default: `false`
+
+If true all whitespaces are considered as equal
+
+#### .orphanMatchThreshold <sup>get/set</sup>
+
+Type: `number`\
+Default: `0.0`
+
+If some match is too small and located far from its neighbors then it is considered as orphan and removed. For example:
+
+```
+aaaaa bb ccccccccc dddddd ee
+11111 bb 222222222 dddddd ee
+```
+
+will find two matches `bb` and `dddddd ee` but the first will be considered as orphan and ignored, as result it will
+consider texts `aaaaa bb ccccccccc` and `11111 bb 222222222` as single replacement:
+
+```html
+<del>aaaaa bb ccccccccc</del><ins>11111 bb 222222222</ins> dddddd ee
+```
+
+This property defines relative size of the match to be considered as orphan, from 0 to 1.
+
+- `1` means that all matches will be considered as orphans.
+- `0` (default) means that no match will be considered as orphan.
+- `0.2` means that if match length is less than 20% of distance between its neighbors it is considered as orphan.
+
+#### build()
+
+Returns the diff from an HtmlDiff instance.
+
+## Contributing
+
+The library uses [Biome](https://biomejs.dev/) for linting and formatting, and [Vitest](https://vitest.dev/) for unit
+tests and benchmarking. It's worth ensuring that you have appropriate plugins for your development environment,
+particularly for Biome to avoid having to fix formatting issues late.
+
+### Releasing
+
+Merge requests to the `main` branch should be reviewed by the team as normal but will not release a new version of the
+library to npm. This happens when merge requests are made to the `prod` branch, this should be an MR directly from
+`main` to `prod` and **MUST** include a bump to the version in package.json satisfying semver.

package/biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json",
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
   "formatter": {
     "enabled": true,
     "formatWithErrors": false,
@@ -9,13 +9,25 @@
     "lineWidth": 120,
     "attributePosition": "auto"
   },
-  "organizeImports": { "enabled": true },
+  "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "linter": {
     "enabled": true,
     "rules": {
       "recommended": true,
       "suspicious": {
         "noConfusingVoidType": "off"
+      },
+      "style": {
+        "noParameterAssign": "error",
+        "useAsConstAssertion": "error",
+        "useDefaultParameterLast": "error",
+        "useEnumInitializers": "error",
+        "useSelfClosingElements": "error",
+        "useSingleVarDeclarator": "error",
+        "noUnusedTemplateLiteral": "error",
+        "useNumberNamespace": "error",
+        "noInferrableTypes": "error",
+        "noUselessElse": "error"
       }
     }
   },

package/dist/HtmlDiff.cjs

@@ -68,7 +68,7 @@ var closingTagTexRegex = /^\s*<\/[^>]+>\s*$/;
 var tagWordRegex = /<[^\s>]+/;
 var whitespaceRegex = /^(\s|&nbsp;)+$/;
 var wordRegex = /[\w#@]+/;
-var tagRegex = /<\/?(?<name>[^\s\/>]+)[^>]*>/;
+var tagRegex = /<\/?(?<name>[^\s/>]+)[^>]*>/;
 var SpecialCaseWordTags = ["<img"];
 function isTag(item) {
   if (SpecialCaseWordTags.some((re) => item?.startsWith(re))) {
@@ -168,10 +168,10 @@ var MatchFinder = class _MatchFinder {
       if (key === null) {
         continue;
       }
-      this.wordIndices = {
-        ...this.wordIndices,
-        [key]: [...this.wordIndices[key] ?? [], i]
-      };
+      if (!this.wordIndices[key]) {
+        this.wordIndices[key] = [];
+      }
+      this.wordIndices[key].push(i);
     }
   }
   static putNewWord(block, word, blockSize) {
@@ -194,7 +194,12 @@ var MatchFinder = class _MatchFinder {
   findMatch() {
     this.indexNewWords();
     this.removeRepeatingWords();
-    if (Object.keys(this.wordIndices).length === 0) {
+    let hasIndices = false;
+    for (const _key in this.wordIndices) {
+      hasIndices = true;
+      break;
+    }
+    if (!hasIndices) {
       return null;
     }
     let bestMatchInOld = this.startInOld;
@@ -209,7 +214,7 @@ var MatchFinder = class _MatchFinder {
         continue;
       }
       const newMatchLengthAt = /* @__PURE__ */ new Map();
-      if (!Object.keys(this.wordIndices).includes(index)) {
+      if (!this.wordIndices[index]) {
         matchLengthAt = newMatchLengthAt;
         continue;
       }
@@ -471,7 +476,7 @@ var BlockFinder = class {
       const from = match.index;
       const to = match.index + match[0].length;
       result.addBlock(from, to);
-    } catch (e) {
+    } catch {
       throw new ArgumentError(
         `One or more block expressions result in a text sequence that overlaps. Current expression: ${exp}`
       );
@@ -503,6 +508,20 @@ var HtmlDiff = class _HtmlDiff {
     "</s>",
     "</span>"
   ];
+  static SpecialCaseClosingTagsSet = /* @__PURE__ */ new Set([
+    "</strong>",
+    "</em>",
+    "</b>",
+    "</i>",
+    "</big>",
+    "</small>",
+    "</u>",
+    "</sub>",
+    "</sup>",
+    "</strike>",
+    "</s>",
+    "</span>"
+  ]);
   static SpecialCaseOpeningTagRegex = /<((strong)|(b)|(i)|(em)|(big)|(small)|(u)|(sub)|(sup)|(strike)|(s)|(span))[>\s]+/i;
   content = [];
   newText;
@@ -612,15 +631,15 @@ var HtmlDiff = class _HtmlDiff {
     this.processInsertOperation(operation, "diffmod");
   }
   processInsertOperation(operation, cssClass) {
-    const text = this.newWords.filter((_, pos) => pos >= operation.startInNew && pos < operation.endInNew);
+    const text = this.newWords.slice(operation.startInNew, operation.endInNew);
     this.insertTag(_HtmlDiff.InsTag, cssClass, text);
   }
   processDeleteOperation(operation, cssClass) {
-    const text = this.oldWords.filter((_, pos) => pos >= operation.startInOld && pos < operation.endInOld);
+    const text = this.oldWords.slice(operation.startInOld, operation.endInOld);
     this.insertTag(_HtmlDiff.DelTag, cssClass, text);
   }
   processEqualOperation(operation) {
-    const result = this.newWords.filter((_, pos) => pos >= operation.startInNew && pos < operation.endInNew);
+    const result = this.newWords.slice(operation.startInNew, operation.endInNew);
     this.content.push(result.join(""));
   }
   /**
@@ -663,7 +682,13 @@ var HtmlDiff = class _HtmlDiff {
       let specialCaseTagInjection = "";
       let specialCaseTagInjectionIsBefore = false;
       if (_HtmlDiff.SpecialCaseOpeningTagRegex.test(words[0])) {
-        const styledTagNames = words.filter((word) => Utils_default.isTag(word)).map((style) => Utils_default.getTagName(style)).join(" ");
+        const tagNames = /* @__PURE__ */ new Set();
+        for (const word of words) {
+          if (Utils_default.isTag(word)) {
+            tagNames.add(Utils_default.getTagName(word));
+          }
+        }
+        const styledTagNames = Array.from(tagNames).join(" ");
         this.specialTagDiffStack.push(words[0]);
         specialCaseTagInjection = `<ins class='mod ${styledTagNames}'>`;
         if (tag === _HtmlDiff.DelTag) {
@@ -672,7 +697,7 @@ var HtmlDiff = class _HtmlDiff {
             words.shift();
           }
         }
-      } else if (_HtmlDiff.SpecialCaseClosingTags.includes(words[0].toLowerCase())) {
+      } else if (_HtmlDiff.SpecialCaseClosingTagsSet.has(words[0].toLowerCase())) {
         const openingTag = this.specialTagDiffStack.length === 0 ? null : this.specialTagDiffStack.pop();
         const openingAndClosingTagsMatch = !!openingTag && Utils_default.getTagName(openingTag) === Utils_default.getTagName(words[indexLastTagInFirstTagBlock]);
         if (!!openingTag && openingAndClosingTagsMatch) {
@@ -683,7 +708,7 @@ var HtmlDiff = class _HtmlDiff {
         }
         if (tag === _HtmlDiff.DelTag) {
           words.shift();
-          while (words.length > 0 && _HtmlDiff.SpecialCaseClosingTags.includes(words[0].toLowerCase())) {
+          while (words.length > 0 && _HtmlDiff.SpecialCaseClosingTagsSet.has(words[0].toLowerCase())) {
             words.shift();
           }
         }
@@ -714,13 +739,13 @@ var HtmlDiff = class _HtmlDiff {
       }
     }
     if (indexOfFirstTag !== null) {
-      const items2 = words.filter((s, pos) => pos >= 0 && pos < indexOfFirstTag);
+      const items2 = words.slice(0, indexOfFirstTag);
       if (indexOfFirstTag > 0) {
         words.splice(0, indexOfFirstTag);
       }
       return items2;
     }
-    const items = words.filter((s, pos) => pos >= 0 && pos <= words.length);
+    const items = words.slice(0);
     words.splice(0, words.length);
     return items;
   }
@@ -769,9 +794,18 @@ var HtmlDiff = class _HtmlDiff {
         curr = next;
         continue;
       }
-      const oldDistanceInChars = this.oldWords.slice(prev.endInOld, next.startInOld).reduce((acc, word) => acc + word.length, 0);
-      const newDistanceInChars = this.newWords.slice(prev.endInNew, next.startInNew).reduce((acc, word) => acc + word.length, 0);
-      const currMatchLengthInChars = this.newWords.slice(curr.startInNew, curr.endInNew).reduce((acc, word) => acc + word.length, 0);
+      let oldDistanceInChars = 0;
+      for (let i = prev.endInOld; i < next.startInOld; i++) {
+        oldDistanceInChars += this.oldWords[i].length;
+      }
+      let newDistanceInChars = 0;
+      for (let i = prev.endInNew; i < next.startInNew; i++) {
+        newDistanceInChars += this.newWords[i].length;
+      }
+      let currMatchLengthInChars = 0;
+      for (let i = curr.startInNew; i < curr.endInNew; i++) {
+        currMatchLengthInChars += this.newWords[i].length;
+      }
       if (currMatchLengthInChars > Math.max(oldDistanceInChars, newDistanceInChars) * this.orphanMatchThreshold) {
         yield curr;
       }