versioned-d.ts-tools 0.7.0 → 0.7.1

package/dist/dts-utilities.d.ts

@@ -13,6 +13,15 @@ export interface WhatsNewConfig {
     linkConfigs?: LinkConfig[];
     replacements?: any[];
 }
+export interface MarkdownOptions {
+    relativePath: string;
+    linkConfigs?: LinkConfig[];
+    excludedFieldNames?: string[];
+    excludedClassPatterns?: string[];
+    excludedFieldPatterns?: string[];
+    includeStaticFields?: boolean;
+    includeEnums?: boolean;
+}
 export declare const DEFAULT_LINK_CONFIGS: LinkConfig[];
 declare enum ClassType {
     Class = "Class",
@@ -54,18 +63,12 @@ export declare class APISet {
     /**
      * Generates markdown documentation for API differences.
      * By default, all classes and fields are included in the output.
-     * Exclusions must be explicitly configured via the parameters.
+     * Exclusions must be explicitly configured via the options.
      *
-     * @param relativePath - The relative path for generating links
-     * @param linkConfigs - Link configuration templates (defaults to built-in Office configs)
-     * @param excludedFieldNames - Array of field names to exclude (no defaults)
-     * @param excludedClassPatterns - Array of regex patterns for classes to exclude (no defaults)
-     * @param excludedFieldPatterns - Array of regex patterns for fields to exclude (no defaults)
-     * @param includeStaticFields - Whether to include static fields (default: true)
-     * @param includeEnums - Whether to include enums (default: true)
+     * @param options - Configuration options for markdown generation
      * @returns Markdown table string
      */
-    getAsMarkdown(relativePath: string, linkConfigs?: LinkConfig[], excludedFieldNames?: string[], excludedClassPatterns?: string[], excludedFieldPatterns?: string[], includeStaticFields?: boolean, includeEnums?: boolean): string;
+    getAsMarkdown(options: MarkdownOptions): string;
     sort(): void;
 }
 export declare function parseDTS(fileName: string, fileContents: string): APISet;

package/dist/dts-utilities.js

@@ -65,6 +65,21 @@ function buildLinkFromTemplate(template, relativePath, className, field) {
     }
     return result;
 }
+// Helper functions for pattern matching optimization
+function compilePatterns(patterns) {
+    if (!patterns || patterns.length === 0) {
+        return [];
+    }
+    return patterns.map(pattern => {
+        try {
+            return new RegExp(pattern);
+        }
+        catch (error) {
+            console.warn(`Invalid regex pattern "${pattern}": ${error.message}`);
+            return null;
+        }
+    }).filter(Boolean);
+}
 // Default configurations for known Office applications
 exports.DEFAULT_LINK_CONFIGS = [
     {
@@ -80,10 +95,26 @@ exports.DEFAULT_LINK_CONFIGS = [
         classMemberTemplate: "/{basePath}.{className}#{hostName}-{fileName}-{className}-{fieldName}{suffix}"
     }
 ];
-// capturing these because of eccentricities with the compiler ordering
-let topClass = null;
-let lastItem = null;
-let globalFunctionsClass = null;
+// Parsing context to encapsulate state during DTS parsing
+class ParsingContext {
+    constructor() {
+        this.topClass = null;
+        this.lastItem = null;
+        this.globalFunctionsClass = null;
+    }
+    reset() {
+        this.topClass = null;
+        this.lastItem = null;
+        this.globalFunctionsClass = null;
+    }
+    ensureGlobalFunctionsClass(allClasses) {
+        if (this.globalFunctionsClass === null) {
+            this.globalFunctionsClass = new ClassStruct("<global>", "", ClassType.Interface);
+            allClasses.addClass(this.globalFunctionsClass);
+        }
+        return this.globalFunctionsClass;
+    }
+}
 var ClassType;
 (function (ClassType) {
     ClassType["Class"] = "Class";
@@ -138,26 +169,11 @@ class APISet {
         this.api.push(clas);
     }
     containsClass(clas) {
-        let found = false;
-        this.api.forEach((element) => {
-            if (element.declarationString === clas.declarationString) {
-                found = true;
-            }
-        });
-        return found;
+        return this.api.some(element => element.declarationString === clas.declarationString);
     }
     containsField(clas, field) {
-        let found = false;
-        this.api.forEach((element) => {
-            if (element.declarationString === clas.declarationString) {
-                element.fields.forEach((thisField) => {
-                    if (thisField.declarationString === field.declarationString) {
-                        found = true;
-                    }
-                });
-            }
-        });
-        return found;
+        const targetClass = this.api.find(element => element.declarationString === clas.declarationString);
+        return targetClass ? targetClass.fields.some(thisField => thisField.declarationString === field.declarationString) : false;
     }
     // finds the new fields and classes
     diff(other) {
@@ -203,19 +219,24 @@ class APISet {
     /**
      * Generates markdown documentation for API differences.
      * By default, all classes and fields are included in the output.
-     * Exclusions must be explicitly configured via the parameters.
+     * Exclusions must be explicitly configured via the options.
      *
-     * @param relativePath - The relative path for generating links
-     * @param linkConfigs - Link configuration templates (defaults to built-in Office configs)
-     * @param excludedFieldNames - Array of field names to exclude (no defaults)
-     * @param excludedClassPatterns - Array of regex patterns for classes to exclude (no defaults)
-     * @param excludedFieldPatterns - Array of regex patterns for fields to exclude (no defaults)
-     * @param includeStaticFields - Whether to include static fields (default: true)
-     * @param includeEnums - Whether to include enums (default: true)
+     * @param options - Configuration options for markdown generation
      * @returns Markdown table string
      */
-    getAsMarkdown(relativePath, linkConfigs = exports.DEFAULT_LINK_CONFIGS, excludedFieldNames = [], excludedClassPatterns = [], excludedFieldPatterns = [], includeStaticFields = true, includeEnums = false) {
+    getAsMarkdown(options) {
+        const finalOptions = {
+            linkConfigs: exports.DEFAULT_LINK_CONFIGS,
+            excludedFieldNames: [],
+            excludedClassPatterns: [],
+            excludedFieldPatterns: [],
+            includeStaticFields: true,
+            includeEnums: false,
+            ...options // Spread user options to override defaults
+        };
         this.sort();
+        // Pre-compile regex patterns for better performance (class patterns only)
+        const compiledClassPatterns = compilePatterns(finalOptions.excludedClassPatterns);
         // table header
         let output = "| Class | Fields | Description |\n|:---|:---|:---|\n";
         this.api.forEach((clas) => {
@@ -223,17 +244,9 @@ class APISet {
             // - Enums (configurable via includeEnums, default: true - enums included by default).
             // - Classes matching excluded patterns (configurable, no defaults - all classes included unless explicitly excluded)
             const className = clas.getClassName();
-            const isExcludedByPattern = excludedClassPatterns.some(pattern => {
-                try {
-                    return new RegExp(pattern).test(className);
-                }
-                catch (error) {
-                    console.warn(`Invalid regex pattern "${pattern}": ${error.message}`);
-                    return false;
-                }
-            });
+            const isExcludedByPattern = compiledClassPatterns.some(regex => regex.test(className));
             const isEnum = clas.type === ClassType.Enum;
-            if ((includeEnums || !isEnum) && !isExcludedByPattern) {
+            if ((finalOptions.includeEnums || !isEnum) && !isExcludedByPattern) {
                 const className = clas.getClassName();
                 // Special handling for <global> - no link
                 if (className === "<global>") {
@@ -241,7 +254,7 @@ class APISet {
                 }
                 else {
                     output += "|[" + className + "]("
-                        + buildClassLink(relativePath, className, linkConfigs) + ")|";
+                        + buildClassLink(finalOptions.relativePath, className, finalOptions.linkConfigs) + ")|";
                 }
                 // Ignore the following:
                 // - Fields matching excluded patterns (configurable, no defaults - all fields included unless explicitly excluded)
@@ -249,7 +262,8 @@ class APISet {
                 // - Static fields (configurable via includeStaticFields, default: true - static fields included by default)
                 let filteredFields = clas.fields.filter((field) => {
                     // Check if field matches any excluded pattern
-                    const isExcludedByPattern = excludedFieldPatterns.some(pattern => {
+                    // Note: Test against field declaration string, just like the original code
+                    const isExcludedByPattern = (finalOptions.excludedFieldPatterns || []).some(pattern => {
                         try {
                             return new RegExp(pattern, 'g').test(field.declarationString);
                         }
@@ -261,8 +275,8 @@ class APISet {
                     // Check if field is static and should be excluded
                     const isStaticField = field.declarationString.includes("static ");
                     return (!isExcludedByPattern &&
-                        !excludedFieldNames.includes(field.name) &&
-                        (includeStaticFields || !isStaticField));
+                        !(finalOptions.excludedFieldNames || []).includes(field.name) &&
+                        (finalOptions.includeStaticFields || !isStaticField));
                 });
                 let first = true;
                 if (filteredFields.length > 0) {
@@ -297,7 +311,7 @@ class APISet {
                         newItemText = newItemText.replace(/[\s][\s]+/g, " ").replace(/\( /g, "(").replace(/ \)/g, ")").replace(/,\)/g, ")").replace(/([\w]\??: )\\\| /g, "$1"); // dprint formatting quirks
                         newItemText = newItemText.replace(/\<any\>/g, "");
                         let tableLine = "[" + newItemText + "]("
-                            + buildFieldLink(relativePath, className, field, linkConfigs) + ")|";
+                            + buildFieldLink(finalOptions.relativePath, className, field, finalOptions.linkConfigs) + ")|";
                         tableLine += removeAtLink(extractFirstSentenceFromComment(field.comment));
                         output += tableLine + "|\n";
                     });
@@ -344,18 +358,33 @@ function extractFirstSentenceFromComment(commentText) {
 function removeAtLink(commentText) {
     // Replace links with the format "{@link Foo}" with "Foo".
     commentText = commentText.replace(/{@link ([^|]*?)}/gm, "$1");
-    // Replace links with the format "{@link Foo | URL}" with "[Foo](URL)".
-    commentText = commentText.replace(/{@link ([^}]*?) \| (http.*?)}/gm, "[$1]($2)");
+    // Replace links with the format "{@link URL | text}" with just the text part.
+    commentText = commentText.replace(/{@link ([^}]*?) \| ([^}]*?)}/gm, "$2");
     return commentText;
 }
+// Cache for compiled link config patterns to avoid recompilation
+const linkConfigCache = new Map();
+function getCompiledLinkConfigs(linkConfigs) {
+    if (!linkConfigCache.has(linkConfigs)) {
+        const compiled = linkConfigs.map(config => ({
+            config,
+            regex: new RegExp(config.pathPattern)
+        }));
+        linkConfigCache.set(linkConfigs, compiled);
+    }
+    return linkConfigCache.get(linkConfigs);
+}
+function findMatchingLinkConfig(relativePath, linkConfigs = exports.DEFAULT_LINK_CONFIGS) {
+    const compiledConfigs = getCompiledLinkConfigs(linkConfigs);
+    const matchingConfig = compiledConfigs.find(({ regex }) => regex.test(relativePath));
+    return matchingConfig ? matchingConfig.config : exports.DEFAULT_LINK_CONFIGS[exports.DEFAULT_LINK_CONFIGS.length - 1];
+}
 function buildClassLink(relativePath, className, linkConfigs = exports.DEFAULT_LINK_CONFIGS) {
-    // Find the first matching configuration
-    const config = linkConfigs.find(config => new RegExp(config.pathPattern).test(relativePath)) || exports.DEFAULT_LINK_CONFIGS[exports.DEFAULT_LINK_CONFIGS.length - 1]; // fallback to last config
+    const config = findMatchingLinkConfig(relativePath, linkConfigs);
     return buildLinkFromTemplate(config.classTemplate, relativePath, className);
 }
 function buildFieldLink(relativePath, className, field, linkConfigs = exports.DEFAULT_LINK_CONFIGS) {
-    // Find the first matching configuration
-    const config = linkConfigs.find(config => new RegExp(config.pathPattern).test(relativePath)) || exports.DEFAULT_LINK_CONFIGS[exports.DEFAULT_LINK_CONFIGS.length - 1]; // fallback to last config
+    const config = findMatchingLinkConfig(relativePath, linkConfigs);
     // Use appropriate template based on whether it's a global function or class member
     if (className.trim() === "<global>") {
         return buildLinkFromTemplate(config.globalFunctionTemplate, relativePath, className, field);
@@ -365,43 +394,42 @@ function buildFieldLink(relativePath, className, field, linkConfigs = exports.DE
     }
 }
 function parseDTS(fileName, fileContents) {
-    // Reset global state for new parse
-    topClass = null;
-    lastItem = null;
-    globalFunctionsClass = null;
+    // Create parsing context to encapsulate state
+    const context = new ParsingContext();
+    context.reset();
     const node = ts.createSourceFile(fileName, fileContents, ts.ScriptTarget.ES2015, true);
     const allClasses = new APISet();
-    parseDTSInternal(node, allClasses);
+    parseDTSInternal(node, allClasses, context);
     return allClasses;
 }
-function parseDTSInternal(node, allClasses) {
+function parseDTSInternal(node, allClasses, context) {
     switch (node.kind) {
         case ts.SyntaxKind.InterfaceDeclaration:
-            parseDTSTopLevelItem(node, allClasses, ClassType.Interface);
+            parseDTSTopLevelItem(node, allClasses, ClassType.Interface, context);
             break;
         case ts.SyntaxKind.ClassDeclaration:
-            parseDTSTopLevelItem(node, allClasses, ClassType.Class);
+            parseDTSTopLevelItem(node, allClasses, ClassType.Class, context);
             break;
         case ts.SyntaxKind.EnumDeclaration:
-            parseDTSTopLevelItem(node, allClasses, ClassType.Enum);
+            parseDTSTopLevelItem(node, allClasses, ClassType.Enum, context);
             break;
         case ts.SyntaxKind.FunctionDeclaration:
-            parseDTSGlobalFunctionItem(node, allClasses);
+            parseDTSGlobalFunctionItem(node, allClasses, context);
             break;
         case ts.SyntaxKind.PropertySignature:
-            parseDTSFieldItem(node, FieldType.Property);
+            parseDTSFieldItem(node, FieldType.Property, context);
             break;
         case ts.SyntaxKind.PropertyDeclaration:
-            parseDTSFieldItem(node, FieldType.Property);
+            parseDTSFieldItem(node, FieldType.Property, context);
             break;
         case ts.SyntaxKind.EnumMember:
-            parseDTSFieldItem(node, FieldType.Enum);
+            parseDTSFieldItem(node, FieldType.Enum, context);
             break;
         case ts.SyntaxKind.MethodSignature:
-            parseDTSFieldItem(node, FieldType.Method);
+            parseDTSFieldItem(node, FieldType.Method, context);
             break;
         case ts.SyntaxKind.MethodDeclaration:
-            parseDTSFieldItem(node, FieldType.Method);
+            parseDTSFieldItem(node, FieldType.Method, context);
             break;
         case ts.SyntaxKind.TypeLiteral:
             return;
@@ -409,39 +437,36 @@ function parseDTSInternal(node, allClasses) {
             // the compiler parses comments after the class/field, therefore this connects to the previous item
             if (node.getText().indexOf("/**") >= 0 &&
                 node.getText().indexOf("*/") >= 0 &&
-                lastItem !== null &&
-                lastItem.comment === "") {
+                context.lastItem !== null &&
+                context.lastItem.comment === "") {
                 // clean up spacing as best we can for the diffed d.ts
-                lastItem.comment = node.getText().replace(/    \*/g, "*");
-                if (lastItem.comment.indexOf("@eventproperty") >= 0) {
+                context.lastItem.comment = node.getText().replace(/    \*/g, "*");
+                if (context.lastItem.comment.indexOf("@eventproperty") >= 0) {
                     // events are indistinguishable from properties aside from this tag
-                    lastItem.type = FieldType.Event;
+                    context.lastItem.type = FieldType.Event;
                 }
             }
     }
     node.getChildren().forEach((element) => {
-        parseDTSInternal(element, allClasses);
+        parseDTSInternal(element, allClasses, context);
     });
 }
-function parseDTSTopLevelItem(node, allClasses, type) {
-    topClass = new ClassStruct("export " + type.toLowerCase() + " " + node.name.text, "", type);
-    allClasses.addClass(topClass);
-    lastItem = topClass;
+function parseDTSTopLevelItem(node, allClasses, type, context) {
+    context.topClass = new ClassStruct("export " + type.toLowerCase() + " " + node.name.text, "", type);
+    allClasses.addClass(context.topClass);
+    context.lastItem = context.topClass;
 }
-function parseDTSFieldItem(node, type) {
+function parseDTSFieldItem(node, type, context) {
     const newField = new FieldStruct(node.getText(), "", type, node.name.getText());
-    topClass.fields.push(newField);
-    lastItem = newField;
+    context.topClass.fields.push(newField);
+    context.lastItem = newField;
 }
-function parseDTSGlobalFunctionItem(node, allClasses) {
+function parseDTSGlobalFunctionItem(node, allClasses, context) {
     // Create a "<global>" class to hold top-level functions if it doesn't exist
-    if (globalFunctionsClass === null) {
-        globalFunctionsClass = new ClassStruct("<global>", "", ClassType.Interface);
-        allClasses.addClass(globalFunctionsClass);
-    }
+    const globalClass = context.ensureGlobalFunctionsClass(allClasses);
     const functionName = node.name ? node.name.getText() : "anonymous";
     const newFunction = new FieldStruct(node.getText(), "", FieldType.Function, functionName);
-    globalFunctionsClass.fields.push(newFunction);
-    lastItem = newFunction;
+    globalClass.fields.push(newFunction);
+    context.lastItem = newFunction;
 }
 //# sourceMappingURL=dts-utilities.js.map

package/dist/whats-new.d.ts

@@ -1,3 +1,20 @@
 #!/usr/bin/env node
 import { LinkConfig } from './dts-utilities';
-export declare function generateWhatsNew(newDtsPath: string, oldDtsPath: string, outputPath: string, relativePath: string, linkConfigs?: LinkConfig[], configFilePath?: string, excludedFieldNames?: string[], excludedClassPatterns?: string[], excludedFieldPatterns?: string[], includeStaticFields?: boolean, includeEnums?: boolean): void;
+export interface WhatsNewOptions {
+    newDtsPath: string;
+    oldDtsPath: string;
+    outputPath: string;
+    relativePath: string;
+    linkConfigs?: LinkConfig[];
+    configFilePath?: string;
+    excludedFieldNames?: string[];
+    excludedClassPatterns?: string[];
+    excludedFieldPatterns?: string[];
+    includeStaticFields?: boolean;
+    includeEnums?: boolean;
+}
+/**
+ * Generates "what's new" documentation by comparing two TypeScript definition files.
+ * @param options - Configuration options for the generation
+ */
+export declare function generateWhatsNew(options: WhatsNewOptions): void;

package/dist/whats-new.js

@@ -75,46 +75,58 @@ function loadWhatsNewConfig(configFilePath) {
         return {};
     }
 }
-function generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath, linkConfigs, configFilePath, excludedFieldNames, excludedClassPatterns, excludedFieldPatterns, includeStaticFields, includeEnums) {
+/**
+ * Generates "what's new" documentation by comparing two TypeScript definition files.
+ * @param options - Configuration options for the generation
+ */
+function generateWhatsNew(options) {
     // Load configuration from file if provided
-    let effectiveLinkConfigs = linkConfigs;
-    let effectiveExcludedFieldNames = excludedFieldNames;
-    let effectiveExcludedClassPatterns = excludedClassPatterns;
-    let effectiveExcludedFieldPatterns = excludedFieldPatterns;
-    let effectiveIncludeStaticFields = includeStaticFields;
-    let effectiveIncludeEnums = includeEnums;
-    if (configFilePath && (!linkConfigs || !excludedFieldNames || !excludedClassPatterns || !excludedFieldPatterns || includeStaticFields === undefined || includeEnums === undefined)) {
-        const config = loadWhatsNewConfig(configFilePath);
-        if (!linkConfigs && config.linkConfigs) {
+    let effectiveLinkConfigs = options.linkConfigs;
+    let effectiveExcludedFieldNames = options.excludedFieldNames;
+    let effectiveExcludedClassPatterns = options.excludedClassPatterns;
+    let effectiveExcludedFieldPatterns = options.excludedFieldPatterns;
+    let effectiveIncludeStaticFields = options.includeStaticFields;
+    let effectiveIncludeEnums = options.includeEnums;
+    if (options.configFilePath && (!options.linkConfigs || !options.excludedFieldNames || !options.excludedClassPatterns || !options.excludedFieldPatterns || options.includeStaticFields === undefined || options.includeEnums === undefined)) {
+        const config = loadWhatsNewConfig(options.configFilePath);
+        if (!options.linkConfigs && config.linkConfigs) {
             effectiveLinkConfigs = config.linkConfigs;
         }
-        if (!excludedFieldNames && config.excludedFieldNames) {
+        if (!options.excludedFieldNames && config.excludedFieldNames) {
             effectiveExcludedFieldNames = config.excludedFieldNames;
         }
-        if (!excludedClassPatterns && config.excludedClassPatterns) {
+        if (!options.excludedClassPatterns && config.excludedClassPatterns) {
             effectiveExcludedClassPatterns = config.excludedClassPatterns;
         }
-        if (!excludedFieldPatterns && config.excludedFieldPatterns) {
+        if (!options.excludedFieldPatterns && config.excludedFieldPatterns) {
             effectiveExcludedFieldPatterns = config.excludedFieldPatterns;
         }
-        if (includeStaticFields === undefined && config.includeStaticFields !== undefined) {
+        if (options.includeStaticFields === undefined && config.includeStaticFields !== undefined) {
             effectiveIncludeStaticFields = config.includeStaticFields;
         }
-        if (includeEnums === undefined) {
+        if (options.includeEnums === undefined) {
             // Default to true when loading from config (inclusive by default)
             effectiveIncludeEnums = config.includeEnums !== undefined ? config.includeEnums : true;
         }
     }
     // read whole files
-    let wholeRelease = fsx.readFileSync(oldDtsPath).toString();
-    let wholePreview = fsx.readFileSync(newDtsPath).toString();
+    let wholeRelease = fsx.readFileSync(options.oldDtsPath).toString();
+    let wholePreview = fsx.readFileSync(options.newDtsPath).toString();
     const releaseAPI = (0, dts_utilities_1.parseDTS)("release", wholeRelease);
     const previewAPI = (0, dts_utilities_1.parseDTS)("preview", wholePreview);
     const diffAPI = previewAPI.diff(releaseAPI);
-    if (!fsx.existsSync(outputPath + ".md")) {
-        fsx.createFileSync(outputPath + ".md");
+    if (!fsx.existsSync(options.outputPath + ".md")) {
+        fsx.createFileSync(options.outputPath + ".md");
     }
-    fsx.writeFileSync(outputPath + ".md", diffAPI.getAsMarkdown(relativePath, effectiveLinkConfigs, effectiveExcludedFieldNames, effectiveExcludedClassPatterns, effectiveExcludedFieldPatterns, effectiveIncludeStaticFields, effectiveIncludeEnums));
+    fsx.writeFileSync(options.outputPath + ".md", diffAPI.getAsMarkdown({
+        relativePath: options.relativePath,
+        linkConfigs: effectiveLinkConfigs,
+        excludedFieldNames: effectiveExcludedFieldNames,
+        excludedClassPatterns: effectiveExcludedClassPatterns,
+        excludedFieldPatterns: effectiveExcludedFieldPatterns,
+        includeStaticFields: effectiveIncludeStaticFields,
+        includeEnums: effectiveIncludeEnums
+    }));
 }
 // CLI entry point
 if (require.main === module) {
@@ -134,7 +146,13 @@ if (require.main === module) {
         console.log(`Using configuration file: ${configFilePath}`);
     }
     tryCatch(async () => {
-        generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath, undefined, configFilePath);
+        generateWhatsNew({
+            newDtsPath,
+            oldDtsPath,
+            outputPath,
+            relativePath,
+            configFilePath
+        });
     });
 }
 async function tryCatch(call) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "versioned-d.ts-tools",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Tools for managing versioned TypeScript definition files",
   "main": "dist/index.js",
   "bin": {