js-dev-tool 1.0.18 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-dev-tool",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "bin": {
     "jstool": "tools.js"
   },
@@ -50,7 +50,7 @@
     "fflate": "^0.8.2",
     "mini-semaphore": "^1.4.4",
     "replace": "^1.2.2",
-    "rm-cstyle-cmts": "^3.3.25",
+    "rm-cstyle-cmts": "^3.3.26",
     "terser": "^5.44.1",
     "tin-args": "^0.1.1"
   }

package/regex.d.ts

@@ -7,9 +7,11 @@
 */
 /**
  * @file js-dev-scripts/regex.d.ts
+ * @desc It is recommended to add `"skipLibCheck": true` to your tsconfig.
+ * @todo publish as "annotate-regex"
  */
 declare global {
-  interface RegExp/* extends TypedRegExp<string, string>*/ {
+  interface RegExp {
     /**
      * Executes a search on a string using a regular expression pattern, and returns an array containing the results of that search.
      * @template {string} P
@@ -38,10 +40,7 @@ declare global {
      * @param {F} [flags] The flags for the regular expression.
      * @returns {RegExp & { readonly source: P; readonly flags: F }} A typed RegExp object.
      */
-    new <const P extends string, const F extends string = "">(pattern: P, flags?: F): RegExp & {
-      readonly source: P;
-      readonly flags: F;
-    };
+    new <const P extends string, const F extends string = "">(pattern: P, flags?: F): TypedRegExp<P, F>;
     /**
      * Creates a typed RegExp object with literal types for the pattern and flags.
      * @template {string} P
@@ -50,10 +49,7 @@ declare global {
      * @param {F} [flags] The flags for the regular expression.
      * @returns {RegExp & { readonly source: P; readonly flags: F }} A typed RegExp object.
      */
-    <const P extends string, const F extends string = "">(pattern: P, flags?: F): RegExp & {
-      readonly source: P;
-      readonly flags: F;
-    };
+    <const P extends string, const F extends string = "">(pattern: P, flags?: F): TypedRegExp<P, F>;
     readonly "prototype": RegExp;
   }
 }
@@ -66,7 +62,7 @@ export type Brand<Tag extends string> = {
   [k in Tag]: true;
 };
 export type TypedRegExpBrand = Brand<"__TypedRegExp">;
-export type TypedRegExp<const P extends string, const F extends string = ""> = RegExp & {
+export type TypedRegExp<P extends string, F extends string = ""> = RegExp & {
   readonly source: P;
   readonly flags: F;
 } & TypedRegExpBrand;
@@ -90,7 +86,7 @@ type FirstChar<S extends string> = S extends `${infer F}${infer _}` ? F : never;
  * without considering nesting, and unions them.
  * @template S - A string pattern.
  */
-export type ExtractGroupNames<S extends string> =
+export type ExtractGroupNames<S extends unknown> =
   S extends `${infer _Before}(?<${infer Rest}`
     ? FirstChar<Rest> extends "=" | "!"
       ? ExtractGroupNames<Rest>
@@ -125,7 +121,7 @@ export type RegExpNamedGroups<R extends RegExp> = R extends { readonly source: i
 export type __PreprocessEscapes<S extends string, Result extends string = ""> =
   S extends `\\\\${infer Rest}`
     ? __PreprocessEscapes<Rest, `${Result}__`>
-    : S extends `\\${infer Next}${infer Rest}`
+    : S extends `\\${infer EscapedChar}${infer Rest}`
       ? __PreprocessEscapes<Rest, `${Result}_!`>
       : S extends `${infer Char}${infer Rest}`
         ? __PreprocessEscapes<Rest, `${Result}${Char}`>
@@ -197,11 +193,146 @@ export type ReplaceCallbackParams<
   input: string,
   groups: RegExpNamedGroups<R>
 ];
-export type ReplacerFunctionSignature<R extends unkown> =
+export type ReplacerFunctionSignature<R extends unknown> =
   R extends (
     RegExp & { readonly source: infer T }
   ) ? R extends TypedRegExpBrand
-    ? (...args: ReplaceCallbackParams<R, T>) => string
+    ? (...args: ReplaceCallbackParams<R/* , T */>) => string
     : (match: string, ...rest: any[]) => string
   : string;
+/*! [2025/12/31 13:01:03]
+ * ## Support PCRE-style regex source (type-level)
+ *
+ * @remarks
+ * This module provides **type-level normalization** for "PCRE-ish" regex sources:
+ * you can write a readable multi-line regex with indentation and `# ...` comments,
+ * then derive a compact JavaScript `RegExp` source at compile time.
+ *
+ * Why type-level? Because it lets us:
+ * - keep the regex readable in source code (with comments and formatting)
+ * - ensure the normalized output is stable and verifiable (via type assertions)
+ *
+ * ## Supported rules
+ * - `#` starts a comment and consumes the rest of the **current line**
+ * - `\#` escapes `#` as a literal (comment is NOT started) and normalizes to `#`
+ * - whitespace characters are removed during normalization
+ * - newlines are normalized: `\r\n` and `\r` become `\n`
+ *
+ * ## Design note (ts(2589) survival)
+ * Naively scanning the entire string character-by-character (multiple passes)
+ * can hit TypeScript's instantiation depth limit (`ts(2589)`).
+ * This implementation is **line-oriented**:
+ * it strips each line, then concatenates results.
+ * That tends to scale much better for long, commented regex sources.
+ *
+ * ## Non-goals (for now)
+ * This is not a full PCRE parser. It intentionally focuses on comment + whitespace
+ * normalization for readability and DX.
+ */
+export type Whitespace =
+  | "\u{9}"
+  | "\u{A}"
+  | "\u{B}"
+  | "\u{C}"
+  | "\u{D}"
+  | "\u{20}"
+  | "\u{85}"
+  | "\u{A0}"
+  | "\u{1680}"
+  | "\u{2000}"
+  | "\u{2001}"
+  | "\u{2002}"
+  | "\u{2003}"
+  | "\u{2004}"
+  | "\u{2005}"
+  | "\u{2006}"
+  | "\u{2007}"
+  | "\u{2008}"
+  | "\u{2009}"
+  | "\u{200A}"
+  | "\u{2028}"
+  | "\u{2029}"
+  | "\u{202F}"
+  | "\u{205F}"
+  | "\u{3000}"
+  | "\u{FEFF}";
+/**
+ * Normalize newline sequences for line-based parsing.
+ * 
+ * + Align **`\r\n`** and **`\r`** to **`\n`** (makes splitting easier)
+ *
+ * @template S - Input string literal.
+ * @returns A new string literal with `\r\n` and `\r` normalized to `\n`.
+ *
+ * @example
+ * type X = NormalizeNewlines<"a\r\nb\rc\n">; // "a\nb\nc\n"
+ */
+type NormalizeNewlines<S extends string> =
+  S extends `${infer A}\r\n${infer B}` ? NormalizeNewlines<`${A}\n${B}`> :
+  S extends `${infer A}\r${infer B}` ? NormalizeNewlines<`${A}\n${B}`> :
+  S;
+/**
+ * Strip and normalize a single line of a PCRE-style regex source.
+ *
+ * @remarks
+ * Rules:
+ * - `\#` is treated as a literal `#` (the backslash is dropped)
+ * - an unescaped `#` starts a line comment and truncates the rest
+ * - all whitespace characters are removed
+ * - other escapes like `\s`, `\w`, `\/`, `\*` are preserved as-is
+ *
+ * @template S - One line of source (no `\n`).
+ * @template Acc - Accumulator for the normalized output.
+ *
+ * @example
+ * type A = StripLine<"  \\#\\w+   # comment  ">; // "#\\w+"
+ * type B = StripLine<"  abc  # comment">;        // "abc"
+ *
+ * @internal
+ *
+ * @todo
+ * - Handle `\\#` (a literal backslash + literal #) more strictly.
+ * - Do not treat `#` as a comment starter inside character classes (`[...]`).
+ */
+type StripLine<S extends string, Acc extends string = ""> =
+  S extends `\\#${infer Rest}`
+    ? StripLine<Rest, `${Acc}#`>
+    : S extends `\\${infer C}${infer Rest}`
+      ? StripLine<Rest, `${Acc}\\${C}`>
+      : S extends `#${string}`
+        ? Acc
+        : S extends `${infer C}${infer Rest}`
+          ? C extends Whitespace
+            ? StripLine<Rest, Acc>
+            : StripLine<Rest, `${Acc}${C}`>
+          : Acc;
+/**
+ * Convert a multi-line PCRE-style regex source into a compact JS `RegExp.source`.
+ *
+ * @remarks
+ * This type:
+ * 1) normalizes newlines, 2) splits by line, 3) applies {@link StripLine},
+ * then 4) concatenates the results.
+ *
+ * @template Input - A `const` string literal of the PCRE-ish source.
+ * @template Acc - Accumulator for the result.
+ * @template S - Internal normalized newline buffer (do not pass manually).
+ *
+ * @example
+ * const RE_SOURCE = `
+ * ^              # start
+ * (?:\\#\\w+)     # keep literal "#"
+ * ` as const;
+ *
+ * type Src = PCREStyleToJsRegExpSourceByLine<typeof RE_SOURCE>;
+ * // "^(:?##\\w+)" ... (depending on your actual input)
+ */
+export type PCREStyleToJsRegExpSourceByLine<
+  Input extends string,
+  Acc extends string = "",
+  S extends string = NormalizeNewlines<Input>,
+> =
+  S extends `${infer Line}\n${infer Rest}`
+    ? PCREStyleToJsRegExpSourceByLine<Input, `${Acc}${StripLine<Line>}`, Rest>
+    : `${Acc}${StripLine<S>}`;
 export as namespace XRegex;

package/scripts/publish-version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.0.18"
+  "version": "1.0.20"
 }

package/tool-lib/cjbm.js

@@ -13,21 +13,15 @@
 const fs = require("fs");
 const path = require("path");
 /**
- * Creates a typed RegExp object with literal types for the pattern and flags.
- * @template {string} P
- * @template {string} F
- * @param {P} pattern The regular expression pattern.
- * @param {F} [flags] The flags for the regular expression.
- * @returns {XRegex.TypedRegExp<P, F>} A typed RegExp object.
+ * DEVNOTE: Improved `RegExpConstructor` interface makes `createRegExp` unnecessary
+ * @date 2025/12/25 22:10:17
  */
-function createRegExp(pattern, flags) {
-  return /** @type {XRegex.TypedRegExp<P, F>} */(new RegExp(pattern, flags));
-}
-const reImportExportDetection = createRegExp(
-  `(?<!\\s*\\/\\/+.*?)(?:(?<!@)import|export)\\s*(?:(?<qcGlobal>["'])(?!https?:)(?=[.\\/]+)\
-(?:(?<globalName>(?:[.\\/]+)?[^'"]+?)(?:\\.(?<globalExt>(?:c|m)?jsx?))?)\\k<qcGlobal>|\\(\\s*(?<qcDynamic>["'])(?!https?:)(?=[.\\/]+)(?<dynamicName>(?:[.\\/]+)?[^'"]+?)\
-(?:\\.(?<dynamicExt>(?:c|m)?jsx?))?\\k<qcDynamic>\\s*\\)|(?:(?<clause>.+?|(?:\\w+\\s*,)?\\s*\\{[^}]+\\})\\s*from)\\s*(?<qcEsm>["'])(?!https?:)(?=[.\\/]+)\
-(?:(?<moduleName>(?:[.\\/]+)?[^'"]+?)(?:\\.(?<moduleExt>(?:c|m)?jsx?))?)\\k<qcEsm>)(?=\\s*;)?`, "g"
+const reImportExportDetection = new RegExp(
+  `(?:(?:^\\s*?\\/\\*+?[\\s\\S]*?\\*\\/)|(?<!\\s*\\/\\/+.*?)(?:(?<!@)import|export)\\s*\
+(?:(?<qcGlobal>["'])(?!https?:)(?=(?:\\.\\.?\\/)+)(?:(?<globalName>(?:(?:\\.\\.?\\/)+)?[^'"]+?)(?:\\.(?<globalExt>(?:c|m)?jsx?))?)\\k<qcGlobal>|\
+\\(\\s*(?<qcDynamic>["'])(?!https?:)(?=(?:\\.\\.?\\/)+)(?<dynamicName>(?:(?:\\.\\.?\\/)+)?[^'"]+?)(?:\\.(?<dynamicExt>(?:c|m)?jsx?))?\\k<qcDynamic>\\s*\\)|\
+(?:(?<clause>.+?|(?:\\w+\\s*,)?\\s*\\{[^}]+})\\s*from)\\s*(?<qcEsm>["'])(?!https?:)(?=(?:\\.\\.?\\/)+)(?:(?<moduleName>(?:(?:\\.\\.?\\/)+)?[^'"]+?)(?:\\.(?<moduleExt>(?:c|m)?jsx?))?)\\k<qcEsm>)\
+(?=\\s*;)?)`, "gm"
 );
 /**
  * @typedef {XRegex.ReplacerFunctionSignature<typeof reImportExportDetection>} TImportExportDetectRegexReplacer
@@ -49,6 +43,7 @@ function getReplacer(ext) {
   return (
     match, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _offset, _input, groups
   ) => {
+    if (/\s*?\/\*/.test(match)) return match;
     const {
       clause,
       dynamicName,