versioned-d.ts-tools 0.6.0 → 0.7.0

package/README.md

@@ -105,44 +105,71 @@ whats-new office-scripts.d.ts office-scripts-old.d.ts office-scripts-whats-new j
 
 This generates a markdown file (e.g., `excel_whats_new.md`) containing a table showing what's new between the two versions.
 
-#### Link Configuration File
+#### Configuration File
 
-You can provide an optional JSON configuration file to customize how URLs are generated for different API types using flexible templates with placeholders.
+You can provide an optional JSON configuration file to customize the output by excluding specific fields, classes, and controlling what types of declarations are included.
 
 **Configuration file format:**
 
 ```json
 {
+  "excludedFieldNames": [
+    "load", "set", "toJSON", "context", "track", "untrack"
+  ],
+  "excludedClassPatterns": [
+    "LoadOptions$", "Data$"
+  ],
+  "excludedFieldPatterns": [
+    "\\w+\\??:\\s*\".*\""
+  ],
+  "includeStaticFields": false,
+  "includeEnums": false,
   "linkConfigs": [
     {
-      "name": "Office Scripts",
       "pathPattern": "office-scripts",
-      "description": "Special URL pattern for Office Scripts",
       "globalFunctionTemplate": "/{basePath}#officescript-officescript-{fieldName}-function(1)",
       "classTemplate": "/{basePath}/officescript.{className}",
       "classMemberTemplate": "/{basePath}/officescript.{className}#officescript-officescript-{className}-{fieldName}{suffix}"
-    },
-    {
-      "name": "Standard Office Applications", 
-      "pathPattern": ".*",
-      "description": "Standard URL pattern for Excel, Word, PowerPoint, Outlook",
-      "globalFunctionTemplate": "/{basePath}#{hostName}-{fileName}-{fieldName}-function(1)",
-      "classTemplate": "/{basePath}.{className}",
-      "classMemberTemplate": "/{basePath}.{className}#{hostName}-{fileName}-{className}-{fieldName}{suffix}"
     }
   ]
 }
 ```
 
+**Configuration Options:**
+
+- **`excludedFieldNames`** - Array of exact field names to exclude from output
+- **`excludedClassPatterns`** - Array of regex patterns for class names to exclude
+- **`excludedFieldPatterns`** - Array of regex patterns for field declarations to exclude
+- **`includeStaticFields`** - Boolean to include/exclude static fields (default: true)
+- **`includeEnums`** - Boolean to include/exclude enum declarations (default: true when loading from config, false for backward compatibility when called directly)
+- **`linkConfigs`** - Array of custom URL generation templates (see Link Configuration section below)
+
+**Enum Configurability:**
+
+The `includeEnums` option provides fine-grained control over enum inclusion:
+
+- **Default behavior**: When calling the API directly, enums are excluded by default (`includeEnums: false`) for backward compatibility
+- **Config file behavior**: When loading from a config file, enums are included by default (`includeEnums: true`) unless explicitly set to false
+- **Explicit control**: Set `"includeEnums": true` to include enums, or `"includeEnums": false` to exclude them
+
+This dual-default approach ensures existing integrations continue working while enabling new functionality when explicitly configured.
+
+#### Link Configuration
+
+The `linkConfigs` section allows you to customize how URLs are generated for different API types using flexible templates with placeholders.
+```
+
 **Available Template Placeholders:**
+
 - `{basePath}` - relativePath without the trailing dot (e.g., 'javascript/api/excel/excel')
-- `{hostName}` - extracted host name (e.g., 'excel', 'office-scripts') 
+- `{hostName}` - extracted host name (e.g., 'excel', 'office-scripts')
 - `{fileName}` - extracted file name (e.g., 'excel', 'officescript')
 - `{className}` - class name in lowercase
 - `{fieldName}` - field/method name in lowercase
 - `{suffix}` - '-member(1)' for methods/functions, '-member' for properties
 
 **Template Types:**
+
 - `globalFunctionTemplate` - For namespace-level functions (global functions)
 - `classTemplate` - For class/interface URLs in the first column
 - `classMemberTemplate` - For class members (methods, properties, events)

package/dist/dts-utilities.d.ts

@@ -4,6 +4,15 @@ export interface LinkConfig {
     classTemplate: string;
     classMemberTemplate: string;
 }
+export interface WhatsNewConfig {
+    excludedFieldNames?: string[];
+    excludedClassPatterns?: string[];
+    excludedFieldPatterns?: string[];
+    includeStaticFields?: boolean;
+    includeEnums?: boolean;
+    linkConfigs?: LinkConfig[];
+    replacements?: any[];
+}
 export declare const DEFAULT_LINK_CONFIGS: LinkConfig[];
 declare enum ClassType {
     Class = "Class",
@@ -42,7 +51,21 @@ export declare class APISet {
     containsField(clas: ClassStruct, field: FieldStruct): boolean;
     diff(other: APISet): APISet;
     getAsDTS(): string;
-    getAsMarkdown(relativePath: string, linkConfigs?: LinkConfig[]): string;
+    /**
+     * 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.
+     *
+     * @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)
+     * @returns Markdown table string
+     */
+    getAsMarkdown(relativePath: string, linkConfigs?: LinkConfig[], excludedFieldNames?: string[], excludedClassPatterns?: string[], excludedFieldPatterns?: string[], includeStaticFields?: boolean, includeEnums?: boolean): string;
     sort(): void;
 }
 export declare function parseDTS(fileName: string, fileContents: string): APISet;

package/dist/dts-utilities.js

@@ -200,18 +200,40 @@ class APISet {
         });
         return output.join("\n");
     }
-    getAsMarkdown(relativePath, linkConfigs = exports.DEFAULT_LINK_CONFIGS) {
+    /**
+     * 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.
+     *
+     * @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)
+     * @returns Markdown table string
+     */
+    getAsMarkdown(relativePath, linkConfigs = exports.DEFAULT_LINK_CONFIGS, excludedFieldNames = [], excludedClassPatterns = [], excludedFieldPatterns = [], includeStaticFields = true, includeEnums = false) {
         this.sort();
         // table header
         let output = "| Class | Fields | Description |\n|:---|:---|:---|\n";
         this.api.forEach((clas) => {
             // Ignore the following:
-            // - Enums.
-            // - LoadOptions interfaces
-            // - *Data classes for set/load methods
-            if (clas.type !== ClassType.Enum &&
-                !clas.getClassName().endsWith("LoadOptions") &&
-                !clas.getClassName().endsWith("Data")) {
+            // - 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 isEnum = clas.type === ClassType.Enum;
+            if ((includeEnums || !isEnum) && !isExcludedByPattern) {
                 const className = clas.getClassName();
                 // Special handling for <global> - no link
                 if (className === "<global>") {
@@ -222,20 +244,25 @@ class APISet {
                         + buildClassLink(relativePath, className, linkConfigs) + ")|";
                 }
                 // Ignore the following:
-                // - String literal overloads.
-                // - `load`, `set`, `track`, `untrack`, and `toJSON` methods
-                // - The `context` property.
-                // - Static fields.
+                // - 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) => {
-                    let isLiteral = field.declarationString.search(/([a-zA-Z]+)(\??:)([\n]?([ |]*\"[\w]*\"[|,\n]*)+?)([ ]*[\),])/g) >= 0;
-                    return (!isLiteral &&
-                        field.name !== "load" &&
-                        field.name !== "set" &&
-                        field.name !== "toJSON" &&
-                        field.name !== "context" &&
-                        field.name !== "track" &&
-                        field.name !== "untrack" &&
-                        !field.declarationString.includes("static "));
+                    // Check if field matches any excluded pattern
+                    const isExcludedByPattern = excludedFieldPatterns.some(pattern => {
+                        try {
+                            return new RegExp(pattern, 'g').test(field.declarationString);
+                        }
+                        catch (error) {
+                            console.warn(`Invalid field regex pattern "${pattern}": ${error.message}`);
+                            return false;
+                        }
+                    });
+                    // Check if field is static and should be excluded
+                    const isStaticField = field.declarationString.includes("static ");
+                    return (!isExcludedByPattern &&
+                        !excludedFieldNames.includes(field.name) &&
+                        (includeStaticFields || !isStaticField));
                 });
                 let first = true;
                 if (filteredFields.length > 0) {

package/dist/whats-new.d.ts

@@ -1,3 +1,3 @@
 #!/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): void;
+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;

package/dist/whats-new.js

@@ -38,37 +38,72 @@ exports.generateWhatsNew = generateWhatsNew;
 const fsx = __importStar(require("fs-extra"));
 const dts_utilities_1 = require("./dts-utilities");
 /**
- * Loads link configuration from a JSON file
+ * Loads configuration from a JSON file
  * @param configFilePath Path to the configuration file
- * @returns Array of LinkConfig objects
+ * @returns Configuration object with linkConfigs, excludedFieldNames, excludedClassPatterns, excludedFieldPatterns, includeStaticFields, and includeEnums
  */
-function loadLinkConfig(configFilePath) {
+function loadWhatsNewConfig(configFilePath) {
     try {
         const configContent = fsx.readFileSync(configFilePath, 'utf8');
         const config = JSON.parse(configContent);
-        // Validate that the config has the required template properties
-        return config.linkConfigs.map((item) => {
-            if (!item.globalFunctionTemplate || !item.classTemplate || !item.classMemberTemplate) {
-                throw new Error(`Configuration item missing required template properties: ${JSON.stringify(item)}`);
-            }
-            return {
-                pathPattern: item.pathPattern,
-                globalFunctionTemplate: item.globalFunctionTemplate,
-                classTemplate: item.classTemplate,
-                classMemberTemplate: item.classMemberTemplate
-            };
-        });
+        let linkConfigs = undefined;
+        // Handle linkConfigs if present
+        if (config.linkConfigs) {
+            linkConfigs = config.linkConfigs.map((item) => {
+                if (!item.globalFunctionTemplate || !item.classTemplate || !item.classMemberTemplate) {
+                    throw new Error(`Configuration item missing required template properties: ${JSON.stringify(item)}`);
+                }
+                return {
+                    pathPattern: item.pathPattern,
+                    globalFunctionTemplate: item.globalFunctionTemplate,
+                    classTemplate: item.classTemplate,
+                    classMemberTemplate: item.classMemberTemplate
+                };
+            });
+        }
+        return {
+            linkConfigs,
+            excludedFieldNames: config.excludedFieldNames,
+            excludedClassPatterns: config.excludedClassPatterns,
+            excludedFieldPatterns: config.excludedFieldPatterns,
+            includeStaticFields: config.includeStaticFields,
+            includeEnums: config.includeEnums
+        };
     }
     catch (error) {
         console.warn(`Could not load config file ${configFilePath}: ${error}. Using default configuration.`);
-        return [];
+        return {};
     }
 }
-function generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath, linkConfigs, configFilePath) {
+function generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath, linkConfigs, configFilePath, excludedFieldNames, excludedClassPatterns, excludedFieldPatterns, includeStaticFields, includeEnums) {
     // Load configuration from file if provided
     let effectiveLinkConfigs = linkConfigs;
-    if (configFilePath && !linkConfigs) {
-        effectiveLinkConfigs = loadLinkConfig(configFilePath);
+    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) {
+            effectiveLinkConfigs = config.linkConfigs;
+        }
+        if (!excludedFieldNames && config.excludedFieldNames) {
+            effectiveExcludedFieldNames = config.excludedFieldNames;
+        }
+        if (!excludedClassPatterns && config.excludedClassPatterns) {
+            effectiveExcludedClassPatterns = config.excludedClassPatterns;
+        }
+        if (!excludedFieldPatterns && config.excludedFieldPatterns) {
+            effectiveExcludedFieldPatterns = config.excludedFieldPatterns;
+        }
+        if (includeStaticFields === undefined && config.includeStaticFields !== undefined) {
+            effectiveIncludeStaticFields = config.includeStaticFields;
+        }
+        if (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();
@@ -79,7 +114,7 @@ function generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath, link
     if (!fsx.existsSync(outputPath + ".md")) {
         fsx.createFileSync(outputPath + ".md");
     }
-    fsx.writeFileSync(outputPath + ".md", diffAPI.getAsMarkdown(relativePath, effectiveLinkConfigs));
+    fsx.writeFileSync(outputPath + ".md", diffAPI.getAsMarkdown(relativePath, effectiveLinkConfigs, effectiveExcludedFieldNames, effectiveExcludedClassPatterns, effectiveExcludedFieldPatterns, effectiveIncludeStaticFields, effectiveIncludeEnums));
 }
 // CLI entry point
 if (require.main === module) {

package/package.json

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