versioned-d.ts-tools 0.7.2 → 0.7.4

package/dist/dts-utilities.d.ts

@@ -10,6 +10,7 @@ export interface WhatsNewConfig {
     excludedFieldPatterns?: string[];
     includeStaticFields?: boolean;
     includeEnums?: boolean;
+    filterUnionAdditions?: boolean;
     linkConfigs?: LinkConfig[];
     replacements?: any[];
 }
@@ -21,6 +22,7 @@ export interface MarkdownOptions {
     excludedFieldPatterns?: string[];
     includeStaticFields?: boolean;
     includeEnums?: boolean;
+    filterUnionAdditions?: boolean;
 }
 export declare const DEFAULT_LINK_CONFIGS: LinkConfig[];
 declare enum ClassType {
@@ -57,8 +59,24 @@ export declare class APISet {
     constructor();
     addClass(clas: ClassStruct): void;
     containsClass(clas: ClassStruct): boolean;
+    /**
+     * Checks if two field declaration strings are equivalent except for additional union types.
+     * This helps filter out noise from new union options being added to existing parameters.
+     */
+    private isOnlyUnionAddition;
     containsField(clas: ClassStruct, field: FieldStruct): boolean;
-    diff(other: APISet): APISet;
+    containsFieldOrUnionAddition(clas: ClassStruct, field: FieldStruct): boolean;
+    /**
+     * Checks if a class name appears only in union type contexts and not as standalone types.
+     * Returns true if the class only appears in union expressions like "Range | RangeAreas"
+     * and doesn't appear as standalone return types or parameters.
+     */
+    /**
+     * Checks if a class with filtered fields should be excluded due to union-only changes.
+     * This is called during markdown generation after field exclusions have been applied.
+     */
+    private shouldExcludeClassForUnionFiltering;
+    diff(other: APISet, filterUnionAdditions?: boolean): APISet;
     getAsDTS(): string;
     /**
      * Generates markdown documentation for API differences.

package/dist/dts-utilities.js

@@ -165,27 +165,167 @@ class APISet {
     containsClass(clas) {
         return this.api.some(element => element.declarationString === clas.declarationString);
     }
+    /**
+     * Checks if two field declaration strings are equivalent except for additional union types.
+     * This helps filter out noise from new union options being added to existing parameters.
+     */
+    isOnlyUnionAddition(newDeclaration, oldDeclaration) {
+        // If they're identical, no difference at all
+        if (newDeclaration === oldDeclaration) {
+            return false;
+        }
+        // Quick check: if the method/field names are different, this is not a union addition
+        // Extract method/field name from the beginning of each declaration
+        const getMethodName = (decl) => {
+            const match = decl.match(/^\s*(\w+)\s*[\(:]/) || decl.match(/^\s*(\w+)\s*\??\s*:/);
+            return match ? match[1] : '';
+        };
+        const oldMethodName = getMethodName(oldDeclaration);
+        const newMethodName = getMethodName(newDeclaration);
+        // If method names are different, this is a new method, not a union addition
+        if (oldMethodName !== newMethodName || !oldMethodName) {
+            return false;
+        }
+        // More sophisticated approach: extract and compare union types from specific parameters
+        // This handles cases where union additions are in the middle of parameter lists
+        // Normalize whitespace first
+        const oldNormalized = oldDeclaration.replace(/\s+/g, ' ').trim();
+        const newNormalized = newDeclaration.replace(/\s+/g, ' ').trim();
+        // Find all union type patterns in both declarations
+        // Pattern matches: paramName: Type1 | Type2 | Type3 or paramName?: Type1 | Type2 | Type3
+        const unionPattern = /(\w+\??\s*:\s*)([^;,)]+)/g;
+        const oldUnions = new Map();
+        const newUnions = new Map();
+        let match;
+        // Extract union types from old declaration
+        unionPattern.lastIndex = 0;
+        while ((match = unionPattern.exec(oldNormalized)) !== null) {
+            const paramName = match[1].trim();
+            const unionString = match[2].trim();
+            const unionTypes = unionString.split('|').map(t => t.trim().replace(/^["']|["']$/g, ''));
+            oldUnions.set(paramName, unionTypes);
+        }
+        // Extract union types from new declaration
+        unionPattern.lastIndex = 0;
+        while ((match = unionPattern.exec(newNormalized)) !== null) {
+            const paramName = match[1].trim();
+            const unionString = match[2].trim();
+            const unionTypes = unionString.split('|').map(t => t.trim().replace(/^["']|["']$/g, ''));
+            newUnions.set(paramName, unionTypes);
+        }
+        // Check if we found any union parameters
+        if (oldUnions.size === 0 || newUnions.size === 0) {
+            return false;
+        }
+        // Check if the parameters are the same except for union additions
+        let hasUnionAddition = false;
+        for (const [paramName, oldTypes] of oldUnions) {
+            const newTypes = newUnions.get(paramName);
+            if (!newTypes) {
+                // Parameter removed, not a union addition
+                return false;
+            }
+            // Check if all old types are present in new types
+            const allOldTypesPresent = oldTypes.every(oldType => newTypes.some(newType => newType === oldType));
+            if (!allOldTypesPresent) {
+                // Types were removed or changed, not just added
+                return false;
+            }
+            // Check if new types were added
+            if (newTypes.length > oldTypes.length) {
+                hasUnionAddition = true;
+            }
+        }
+        // Check for any completely new parameters (not allowed for union addition)
+        for (const paramName of newUnions.keys()) {
+            if (!oldUnions.has(paramName)) {
+                return false;
+            }
+        }
+        return hasUnionAddition;
+    }
     containsField(clas, field) {
         const targetClass = this.api.find(element => element.declarationString === clas.declarationString);
         return targetClass ? targetClass.fields.some(thisField => thisField.declarationString === field.declarationString) : false;
     }
+    containsFieldOrUnionAddition(clas, field) {
+        const targetClass = this.api.find(element => element.declarationString === clas.declarationString);
+        if (!targetClass) {
+            return false;
+        }
+        return targetClass.fields.some(thisField => {
+            // Exact match
+            if (thisField.declarationString === field.declarationString) {
+                return true;
+            }
+            // Check if it's only a union addition
+            return this.isOnlyUnionAddition(field.declarationString, thisField.declarationString);
+        });
+    }
+    /**
+     * Checks if a class name appears only in union type contexts and not as standalone types.
+     * Returns true if the class only appears in union expressions like "Range | RangeAreas"
+     * and doesn't appear as standalone return types or parameters.
+     */
+    /**
+     * Checks if a class with filtered fields should be excluded due to union-only changes.
+     * This is called during markdown generation after field exclusions have been applied.
+     */
+    shouldExcludeClassForUnionFiltering(clas, originalFields, excludedFieldPatterns = [], excludedFieldNames = []) {
+        // If no fields in the class, don't exclude for union reasons
+        if (originalFields.length === 0) {
+            return false;
+        }
+        // First filter out excluded fields to see what would actually be displayed
+        const visibleFields = originalFields.filter(field => {
+            const isExcludedByPattern = excludedFieldPatterns.some(pattern => {
+                try {
+                    return new RegExp(pattern, 'g').test(field.declarationString);
+                }
+                catch (error) {
+                    return false;
+                }
+            });
+            const isExcludedByName = excludedFieldNames.includes(field.name);
+            return !isExcludedByPattern && !isExcludedByName;
+        });
+        // If no fields would be visible after exclusions, and all original fields contain unions,
+        // then this class likely appears only due to union additions in other classes
+        if (visibleFields.length === 0 && originalFields.every(field => field.declarationString.includes('|'))) {
+            return true;
+        }
+        return false;
+    }
     // finds the new fields and classes
-    diff(other) {
+    diff(other, filterUnionAdditions = false) {
         const diffAPI = new APISet();
         this.api.forEach((element) => {
             if (other.containsClass(element)) {
                 let classShell = null;
                 element.fields.forEach((field) => {
-                    if (!other.containsField(element, field)) {
+                    let fieldExists;
+                    if (filterUnionAdditions) {
+                        // Use union-aware field comparison when filtering is enabled
+                        fieldExists = other.containsFieldOrUnionAddition(element, field);
+                    }
+                    else {
+                        // Use exact match comparison
+                        fieldExists = other.containsField(element, field);
+                    }
+                    if (!fieldExists) {
                         if (classShell === null) {
                             classShell = element.copyWithoutFields();
-                            diffAPI.addClass(classShell);
                         }
                         classShell.fields.push(field);
                     }
                 });
+                // Only add the class to diffAPI if it has fields after filtering
+                if (classShell !== null && classShell.fields.length > 0) {
+                    diffAPI.addClass(classShell);
+                }
             }
             else {
+                // Add new classes to the diff
                 diffAPI.addClass(element);
             }
         });
@@ -242,19 +382,15 @@ class APISet {
             const isEnum = clas.type === ClassType.Enum;
             if ((finalOptions.includeEnums || !isEnum) && !isExcludedByPattern) {
                 const className = clas.getClassName();
-                // Special handling for <global> - no link
-                if (className === "<global>") {
-                    output += "|*global*|";
-                }
-                else {
-                    output += "|[" + className + "]("
-                        + buildClassLink(finalOptions.relativePath, className, finalOptions.linkConfigs) + ")|";
+                // Apply union filtering if enabled - check if this class should be filtered out BEFORE field filtering
+                if (finalOptions.filterUnionAdditions) {
+                    if (this.shouldExcludeClassForUnionFiltering(clas, clas.fields, finalOptions.excludedFieldPatterns || [], finalOptions.excludedFieldNames || [])) {
+                        // Skip this class as it only contains union-related changes
+                        return;
+                    }
                 }
-                // Ignore the following:
-                // - Fields matching excluded patterns (configurable, no defaults - all fields included unless explicitly excluded)
-                // - Excluded field names (configurable, no defaults - all field names included unless explicitly excluded)
-                // - Static fields (configurable via includeStaticFields, default: true - static fields included by default)
-                let filteredFields = clas.fields.filter((field) => {
+                // Apply field filtering after union filtering check
+                const filteredFields = clas.fields.filter((field) => {
                     // Check if field matches any excluded pattern
                     // Note: Test against field declaration string, just like the original code
                     const isExcludedByPattern = (finalOptions.excludedFieldPatterns || []).some(pattern => {
@@ -272,6 +408,19 @@ class APISet {
                         !(finalOptions.excludedFieldNames || []).includes(field.name) &&
                         (finalOptions.includeStaticFields || !isStaticField));
                 });
+                // Special handling for <global> - no link
+                if (className === "<global>") {
+                    output += "|*global*|";
+                }
+                else {
+                    output += "|[" + className + "]("
+                        + buildClassLink(finalOptions.relativePath, className, finalOptions.linkConfigs) + ")|";
+                }
+                // Ignore the following:
+                // - Fields matching excluded patterns (configurable, no defaults - all fields included unless explicitly excluded)
+                // - Excluded field names (configurable, no defaults - all field names included unless explicitly excluded)
+                // - Static fields (configurable via includeStaticFields, default: true - static fields included by default)
+                // (filteredFields already computed above)
                 let first = true;
                 if (filteredFields.length > 0) {
                     filteredFields.forEach((field) => {
@@ -311,7 +460,8 @@ class APISet {
                     });
                 }
                 else {
-                    output += "||\n";
+                    // When all fields are excluded, still show the class description
+                    output += "|" + removeAtLink(extractFirstSentenceFromComment(clas.comment)) + "|\n";
                 }
             }
         });

package/dist/version-remover.js

@@ -114,9 +114,9 @@ if (require.main === module) {
     const args = process.argv.slice(2);
     const hasHelp = args.find((x) => x === "-?" || x === "--help");
     if ((args.length !== 3 && args.length !== 4) || hasHelp) {
-        console.log("usage: node version-remover [source d.ts] [output file name] [version string] [optional config file]");
-        console.log("example: node version-remover excel.d.ts excel_1_7.d.ts \"Api set: ExcelApi 1.8\"");
-        console.log("example: node version-remover excel.d.ts excel_1_18.d.ts \"Api set: ExcelApi 1.19\" my-config.json");
+        console.log("usage: version-remover [source d.ts] [output file name] [version string] [optional config file]");
+        console.log("example: version-remover excel.d.ts excel_1_7.d.ts \"Api set: ExcelApi 1.8\"");
+        console.log("example: version-remover excel.d.ts excel_1_18.d.ts \"Api set: ExcelApi 1.19\" my-config.json");
         console.log("");
         console.log("Note: For specific API sets that require custom replacements, you may need to create");
         console.log("configuration files to handle type union cleanups and parameter removals.");

package/dist/whats-new.d.ts

@@ -12,6 +12,7 @@ export interface WhatsNewOptions {
     excludedFieldPatterns?: string[];
     includeStaticFields?: boolean;
     includeEnums?: boolean;
+    filterUnionAdditions?: boolean;
 }
 /**
  * Generates "what's new" documentation by comparing two TypeScript definition files.

package/dist/whats-new.js

@@ -40,7 +40,7 @@ const dts_utilities_1 = require("./dts-utilities");
 /**
  * Loads configuration from a JSON file
  * @param configFilePath Path to the configuration file
- * @returns Configuration object with linkConfigs, excludedFieldNames, excludedClassPatterns, excludedFieldPatterns, includeStaticFields, and includeEnums
+ * @returns Configuration object with linkConfigs, excludedFieldNames, excludedClassPatterns, excludedFieldPatterns, includeStaticFields, includeEnums, and filterUnionAdditions
  */
 function loadWhatsNewConfig(configFilePath) {
     try {
@@ -67,7 +67,8 @@ function loadWhatsNewConfig(configFilePath) {
             excludedClassPatterns: config.excludedClassPatterns,
             excludedFieldPatterns: config.excludedFieldPatterns,
             includeStaticFields: config.includeStaticFields,
-            includeEnums: config.includeEnums
+            includeEnums: config.includeEnums,
+            filterUnionAdditions: config.filterUnionAdditions
         };
     }
     catch (error) {
@@ -87,7 +88,8 @@ function generateWhatsNew(options) {
     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)) {
+    let effectiveFilterUnionAdditions = options.filterUnionAdditions;
+    if (options.configFilePath && (!options.linkConfigs || !options.excludedFieldNames || !options.excludedClassPatterns || !options.excludedFieldPatterns || options.includeStaticFields === undefined || options.includeEnums === undefined || options.filterUnionAdditions === undefined)) {
         const config = loadWhatsNewConfig(options.configFilePath);
         if (!options.linkConfigs && config.linkConfigs) {
             effectiveLinkConfigs = config.linkConfigs;
@@ -108,13 +110,16 @@ function generateWhatsNew(options) {
             // Default to true when loading from config (inclusive by default)
             effectiveIncludeEnums = config.includeEnums !== undefined ? config.includeEnums : true;
         }
+        if (options.filterUnionAdditions === undefined && config.filterUnionAdditions !== undefined) {
+            effectiveFilterUnionAdditions = config.filterUnionAdditions;
+        }
     }
     // read whole files
     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);
+    const diffAPI = previewAPI.diff(releaseAPI, effectiveFilterUnionAdditions);
     if (!fsx.existsSync(options.outputPath + ".md")) {
         fsx.createFileSync(options.outputPath + ".md");
     }
@@ -125,7 +130,8 @@ function generateWhatsNew(options) {
         excludedClassPatterns: effectiveExcludedClassPatterns,
         excludedFieldPatterns: effectiveExcludedFieldPatterns,
         includeStaticFields: effectiveIncludeStaticFields,
-        includeEnums: effectiveIncludeEnums
+        includeEnums: effectiveIncludeEnums,
+        filterUnionAdditions: effectiveFilterUnionAdditions
     }));
 }
 // CLI entry point

package/package.json

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