Merge branch 'main' into chore/karma-tests-migration

gnbm · gnbm · commit 8da96e6daecf · 2025-10-24T11:29:48.000+01:00
diff --git a/src/compiler/types/tests/generate-prop-types.spec.ts b/src/compiler/types/tests/generate-prop-types.spec.ts
@@ -245,5 +245,31 @@ describe('generate-prop-types', () => {
 
       expect(actualTypeInfo).toEqual(expectedTypeInfo);
     });
+
+    it('escapes "*/" in default values within jsdoc', () => {
+      const stubImportTypes = stubTypesImportData();
+      const componentMeta = stubComponentCompilerMeta({
+        properties: [
+          stubComponentCompilerProperty({
+            defaultValue: "'*/*'",
+          }),
+        ],
+      });
+
+      const expectedTypeInfo: d.TypeInfo = [
+        {
+          jsdoc: "@default '*\\/*'", // Editor will evaluate this as @default '*\/*'
+          internal: false,
+          name: 'propName',
+          optional: false,
+          required: false,
+          type: 'UserCustomPropType',
+        },
+      ];
+
+      const actualTypeInfo = generatePropTypes(componentMeta, stubImportTypes);
+
+      expect(actualTypeInfo).toEqual(expectedTypeInfo);
+    });
   });
 });
diff --git a/src/utils/helpers.ts b/src/utils/helpers.ts
@@ -47,6 +47,39 @@ export const toCamelCase = (str: string) => {
  */
 export const toTitleCase = (str: string): string => str.charAt(0).toUpperCase() + str.slice(1);
 
+/**
+ * Escapes all occurrences of a specified pattern in a string.
+ * @description This function replaces all matches of a given pattern in the input text with a specified replacement string.
+ * It can handle both string and regular expression patterns and allows toggling between global and single-match replacements.
+ * @param {string} text - The input string to process.
+ * @param {RegExp | string} pattern - The pattern to search for in the input string. Can be a regular expression or a string.
+ * @param {string} replacement - The string to replace each match with.
+ * @param {boolean} [replaceAll=true] - Whether to replace all occurrences (`true`) or just the first occurrence (`false`). Defaults to `true`.
+ * @returns {string} The processed string with the replacements applied.
+ * @example
+ * @see src\utils\util.ts
+ */
+export const escapeWithPattern = (
+  text: string,
+  pattern: RegExp | string,
+  replacement: string,
+  replaceAll: boolean = true,
+): string => {
+  let regex: RegExp;
+
+  if (typeof pattern === 'string') {
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    regex = new RegExp(escaped, replaceAll ? 'g' : '');
+  } else {
+    const flags = pattern.flags;
+    const hasG = flags.includes('g');
+    const newFlags = replaceAll ? (hasG ? flags : flags + 'g') : hasG ? flags.replace(/g/g, '') : flags;
+    regex = new RegExp(pattern.source, newFlags);
+  }
+
+  return text.replace(regex, replacement);
+};
+
 /**
  * This is just a no-op, don't expect it to do anything.
  */
diff --git a/src/utils/test/helpers.spec.ts b/src/utils/test/helpers.spec.ts
@@ -1,4 +1,4 @@
-import { dashToPascalCase, isDef, mergeIntoWith, toCamelCase, toDashCase } from '../helpers';
+import { dashToPascalCase, escapeWithPattern, isDef, mergeIntoWith, toCamelCase, toDashCase } from '../helpers';
 
 describe('util helpers', () => {
   describe('dashToPascalCase', () => {
@@ -107,4 +107,63 @@ describe('util helpers', () => {
       ]);
     });
   });
+
+  describe('escapeWithPattern', () => {
+    it('replaces all occurrences of a string pattern by default', () => {
+      const text = 'foo/bar foo/bar foo/bar';
+      const pattern = '/';
+      const replacement = '\\/';
+      expect(escapeWithPattern(text, pattern, replacement)).toBe('foo\\/bar foo\\/bar foo\\/bar');
+    });
+
+    it('replaces only first occurrence if replaceAll is false', () => {
+      const text = 'foo/bar foo/bar foo/bar';
+      const pattern = '/';
+      const replacement = '\\/';
+      expect(escapeWithPattern(text, pattern, replacement, false)).toBe('foo\\/bar foo/bar foo/bar');
+    });
+
+    it('replaces all occurrences using a RegExp pattern with no g flag by default', () => {
+      const text = 'a+b+c+a+b+c';
+      const pattern = /\+/; // no 'g' flag
+      const replacement = '-';
+      expect(escapeWithPattern(text, pattern, replacement)).toBe('a-b-c-a-b-c');
+    });
+
+    it('replaces only first occurrence if replaceAll is false with RegExp', () => {
+      const text = 'a+b+c+a+b+c';
+      const pattern = /\+/;
+      const replacement = '-';
+      expect(escapeWithPattern(text, pattern, replacement, false)).toBe('a-b+c+a+b+c');
+    });
+
+    it('respects the g flag if RegExp already has it and replaceAll true', () => {
+      const text = 'x*y*z*x*y*z';
+      const pattern = /\*/g;
+      const replacement = '-';
+      expect(escapeWithPattern(text, pattern, replacement, true)).toBe('x-y-z-x-y-z');
+    });
+
+    it('removes the g flag if replaceAll is false', () => {
+      const text = 'x*y*z*x*y*z';
+      const pattern = /\*/g;
+      const replacement = '-';
+      expect(escapeWithPattern(text, pattern, replacement, false)).toBe('x-y*z*x*y*z');
+    });
+
+    it('escapes special RegExp chars in string pattern', () => {
+      const text = 'foo.*+?^${}()|[]\\bar';
+      const pattern = '.*+?^${}()|[]\\';
+      const replacement = '-ESCAPED-';
+      expect(escapeWithPattern(text, pattern, replacement)).toBe('foo-ESCAPED-bar');
+    });
+
+    it('works with empty string input', () => {
+      expect(escapeWithPattern('', 'a', 'b')).toBe('');
+    });
+
+    it('works with empty replacement', () => {
+      expect(escapeWithPattern('abcabc', 'a', '')).toBe('bcbc');
+    });
+  });
 });
diff --git a/src/utils/test/util.spec.ts b/src/utils/test/util.spec.ts
@@ -1,6 +1,7 @@
 import { mockBuildCtx, mockValidatedConfig } from '@stencil/core/testing';
 import * as util from '@utils';
 
+import { getTextDocs } from '@utils';
 import type * as d from '../../declarations';
 import { stubDiagnostic } from '../../dev-server/test/Diagnostic.stub';
 
@@ -298,4 +299,72 @@ interface Foo extends Components.Foo, HTMLStencilElement {`);
       expect(util.isJsFile(fileName)).toEqual(true);
     });
   });
+
+  describe('getTextDocs', () => {
+    let docs: d.CompilerJsDoc;
+
+    beforeEach(() => {
+      docs = {
+        tags: [],
+        text: '',
+      };
+    });
+    it('returns empty string for null or undefined', () => {
+      expect(getTextDocs(null)).toBe('');
+      expect(getTextDocs(undefined)).toBe('');
+    });
+
+    it('returns only main text if no tags', () => {
+      docs = {
+        text: 'Some doc text.',
+        tags: [],
+      };
+      expect(getTextDocs(docs)).toBe('Some doc text.');
+    });
+
+    it('replaces line breaks in main text with spaces', () => {
+      docs = {
+        text: 'Line 1\nLine 2\r\nLine 3',
+        tags: [],
+      };
+      expect(getTextDocs(docs)).toBe('Line 1 Line 2 Line 3');
+    });
+
+    it('filters out internal tags and escapes "*/" in text and tags', () => {
+      docs = {
+        text: 'This text ends with */ sequence.',
+        tags: [
+          { name: 'internal', text: 'should be removed' },
+          { name: 'default', text: "'*/*'" },
+          { name: 'deprecated', text: 'Use something else' },
+        ],
+      };
+
+      const result = getTextDocs(docs);
+
+      // Should replace "*/" with "*\/" (single backslash)
+      expect(result).toContain('This text ends with *\\/ sequence.');
+
+      // @internal tag filtered out
+      expect(result).not.toContain('@internal');
+
+      // @default and @deprecated tags included and escaped
+      expect(result).toContain("@default '*\\/*'");
+      expect(result).toContain('@deprecated Use something else');
+
+      // Main text and tags separated by new lines
+      const lines = result.split('\n');
+      expect(lines[0]).toBe('This text ends with *\\/ sequence.');
+      expect(lines).toContain("@default '*\\/*'");
+      expect(lines).toContain('@deprecated Use something else');
+    });
+
+    it('trims the result', () => {
+      docs = {
+        text: '  Some text with spaces  ',
+        tags: [],
+      };
+      expect(getTextDocs(docs)).toBe('Some text with spaces');
+    });
+  });
 });
diff --git a/src/utils/util.ts b/src/utils/util.ts
@@ -1,5 +1,5 @@
 import type * as d from '../declarations';
-import { dashToPascalCase, isString, toDashCase } from './helpers';
+import { dashToPascalCase, escapeWithPattern, isString, toDashCase } from './helpers';
 import { buildError } from './message-utils';
 
 /**
@@ -8,6 +8,8 @@ import { buildError } from './message-utils';
  */
 const SUPPRESSED_JSDOC_TAGS: ReadonlyArray<string> = ['virtualProp', 'slot', 'part', 'internal'];
 
+const LINE_BREAK_REGEX: Readonly<RegExp> = /\r?\n|\r/g;
+
 /**
  * Create a stylistically-appropriate JS variable name from a filename
  *
@@ -111,16 +113,21 @@ export const generatePreamble = (config: d.ValidatedConfig): string => {
   return preambleComment.join('\n');
 };
 
-const lineBreakRegex = /\r?\n|\r/g;
 export function getTextDocs(docs: d.CompilerJsDoc | undefined | null) {
   if (docs == null) {
     return '';
   }
-  return `${docs.text.replace(lineBreakRegex, ' ')}
-${docs.tags
-  .filter((tag) => tag.name !== 'internal')
-  .map((tag) => `@${tag.name} ${(tag.text || '').replace(lineBreakRegex, ' ')}`)
-  .join('\n')}`.trim();
+
+  const mainText = escapeWithPattern(docs.text.replace(LINE_BREAK_REGEX, ' '), /\*\//, '*\\/', true);
+
+  const tags = docs.tags
+    .filter((tag) => tag.name !== 'internal')
+    .map((tag) => {
+      const tagText = escapeWithPattern((tag.text || '').replace(LINE_BREAK_REGEX, ' '), /\*\//, '*\\/', true);
+      return `@${tag.name} ${tagText}`;
+    });
+
+  return [mainText, ...tags].join('\n').trim();
 }
 
 /**
@@ -163,10 +170,10 @@ function formatDocBlock(docs: d.CompilerJsDoc, indentation: number = 0): string
  */
 function getDocBlockLines(docs: d.CompilerJsDoc): string[] {
   return [
-    ...docs.text.split(lineBreakRegex),
+    ...docs.text.split(LINE_BREAK_REGEX),
     ...docs.tags
       .filter((tag) => !SUPPRESSED_JSDOC_TAGS.includes(tag.name))
-      .map((tag) => `@${tag.name} ${tag.text || ''}`.split(lineBreakRegex)),
+      .map((tag) => `@${tag.name} ${tag.text || ''}`.split(LINE_BREAK_REGEX)),
   ]
     .flat()
     .filter(Boolean);
