versioned-d.ts-tools 0.5.0 → 0.7.0

package/README.md

@@ -105,33 +105,76 @@ 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. This is useful when different Office applications have different URL patterns.
+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"
-    },
-    {
-      "name": "Standard Office Applications", 
-      "pathPattern": ".*",
-      "description": "Standard URL pattern for Excel, Word, PowerPoint, Outlook"
+      "globalFunctionTemplate": "/{basePath}#officescript-officescript-{fieldName}-function(1)",
+      "classTemplate": "/{basePath}/officescript.{className}",
+      "classMemberTemplate": "/{basePath}/officescript.{className}#officescript-officescript-{className}-{fieldName}{suffix}"
     }
   ]
 }
 ```
 
-When a configuration file is provided, the tool will use the appropriate URL pattern based on the relative path. For example:
+**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')
+- `{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)
 
-- Office Scripts APIs will use the Office Scripts-specific URL format
-- Other Office applications will use the standard URL format
+When a configuration file is provided, the tool will use the appropriate URL template based on the pattern matching. The first matching `pathPattern` (regex) wins.
 
 See `example-link-config.json` for a complete example.
 

package/dist/dts-utilities.d.ts

@@ -1,6 +1,17 @@
 export interface LinkConfig {
     pathPattern: string;
-    buildLink: (relativePath: string, className: string, field: FieldStruct) => string;
+    globalFunctionTemplate: string;
+    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 {
@@ -40,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

@@ -36,47 +36,48 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.APISet = exports.DEFAULT_LINK_CONFIGS = void 0;
 exports.parseDTS = parseDTS;
 const ts = __importStar(require("typescript"));
-// Default link builder for Office Scripts
-function buildOfficeScriptsLink(relativePath, className, field) {
-    if (className === "<global>") {
-        const basePath = relativePath.substring(0, relativePath.lastIndexOf("."));
-        return "/" + basePath + "#officescript-officescript-" + field.name.toLowerCase() + "-function(1)";
+// Available placeholders:
+// {basePath} - relativePath without the trailing dot
+// {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
+// Default link builder using templates
+function buildLinkFromTemplate(template, relativePath, className, field) {
+    const basePath = relativePath.substring(0, relativePath.lastIndexOf("."));
+    const hostName = relativePath.includes("/api/")
+        ? relativePath.substring(relativePath.indexOf("/api/") + 5, relativePath.lastIndexOf("/"))
+        : "";
+    const fileName = relativePath.substring(relativePath.lastIndexOf("/") + 1, relativePath.lastIndexOf("."));
+    let result = template
+        .replace(/{basePath}/g, basePath)
+        .replace(/{hostName}/g, hostName)
+        .replace(/{fileName}/g, fileName);
+    if (className && className !== "<global>") {
+        result = result.replace(/{className}/g, className.toLowerCase());
     }
-    else {
+    if (field) {
         const suffix = (field.type === FieldType.Method || field.type === FieldType.Function) ? "-member(1)" : "-member";
-        const url = "/" + relativePath + className.toLowerCase();
-        const anchor = "officescript-officescript-" + className.toLowerCase() + "-" + field.name.toLowerCase() + suffix;
-        return url + "#" + anchor;
-    }
-}
-// Default link builder for standard Office applications
-function buildStandardLink(relativePath, className, field) {
-    if (className === "<global>") {
-        const hostName = relativePath.substring(relativePath.indexOf("/api/") + 5, relativePath.lastIndexOf("/"));
-        const fileName = relativePath.substring(relativePath.lastIndexOf("/") + 1, relativePath.lastIndexOf("."));
-        const basePath = relativePath.substring(0, relativePath.lastIndexOf("."));
-        const anchorPrefix = hostName + "-" + fileName + "-";
-        return "/" + basePath + "#" + anchorPrefix + field.name.toLowerCase() + "-function(1)";
-    }
-    else {
-        const hostName = relativePath.substring(relativePath.indexOf("/api/") + 5, relativePath.lastIndexOf("/"));
-        const fileName = relativePath.substring(relativePath.lastIndexOf("/") + 1, relativePath.lastIndexOf("."));
-        const suffix = (field.type === FieldType.Method || field.type === FieldType.Function) ? "-member(1)" : "-member";
-        const url = "/" + relativePath + className.toLowerCase();
-        const anchorPrefix = hostName + "-" + fileName + "-";
-        const anchor = anchorPrefix + className.toLowerCase() + "-" + field.name.toLowerCase() + suffix;
-        return url + "#" + anchor;
+        result = result
+            .replace(/{fieldName}/g, field.name.toLowerCase())
+            .replace(/{suffix}/g, suffix);
     }
+    return result;
 }
 // Default configurations for known Office applications
 exports.DEFAULT_LINK_CONFIGS = [
     {
         pathPattern: "office-scripts",
-        buildLink: buildOfficeScriptsLink
+        globalFunctionTemplate: "/{basePath}#officescript-officescript-{fieldName}-function(1)",
+        classTemplate: "/{basePath}/officescript.{className}",
+        classMemberTemplate: "/{basePath}/officescript.{className}#officescript-officescript-{className}-{fieldName}{suffix}"
     },
     {
         pathPattern: ".*", // matches any path as fallback
-        buildLink: buildStandardLink
+        globalFunctionTemplate: "/{basePath}#{hostName}-{fileName}-{fieldName}-function(1)",
+        classTemplate: "/{basePath}.{className}",
+        classMemberTemplate: "/{basePath}.{className}#{hostName}-{fileName}-{className}-{fieldName}{suffix}"
     }
 ];
 // capturing these because of eccentricities with the compiler ordering
@@ -199,42 +200,69 @@ 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>") {
                     output += "|*global*|";
                 }
                 else {
-                    output += "|[" + className + "](/"
-                        + relativePath + className.toLowerCase() + ")|";
+                    output += "|[" + className + "]("
+                        + 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) {
@@ -320,11 +348,21 @@ function removeAtLink(commentText) {
     commentText = commentText.replace(/{@link ([^}]*?) \| (http.*?)}/gm, "[$1]($2)");
     return commentText;
 }
+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
+    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
-    // Use the configuration's link builder
-    return config.buildLink(relativePath, className, field);
+    // 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);
+    }
+    else {
+        return buildLinkFromTemplate(config.classMemberTemplate, relativePath, className, field);
+    }
 }
 function parseDTS(fileName, fileContents) {
     // Reset global state for new parse

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,36 +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);
-        // Convert the config to LinkConfig objects with actual functions
-        return config.linkConfigs.map((item) => ({
-            pathPattern: new RegExp(item.pathPattern),
-            buildLink: item.pathPattern === "office-scripts"
-                ? (namespace, className) => className === "*global*"
-                    ? `/javascript/api/office-scripts/officescript/officescript#officescript-officescript-${namespace.toLowerCase()}-function(1)`
-                    : `/javascript/api/office-scripts/officescript/officescript.${className.toLowerCase()}#officescript-officescript-${className.toLowerCase()}-${namespace.toLowerCase()}-member(1)`
-                : (namespace, className) => className === "*global*"
-                    ? `/javascript/api/${namespace}/${namespace}#${namespace}-${namespace}-${namespace.toLowerCase()}-function(1)`
-                    : `/javascript/api/${namespace}/${namespace}.${className.toLowerCase()}#${namespace}-${namespace}-${className.toLowerCase()}-${namespace.toLowerCase()}-member(1)`
-        }));
+        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();
@@ -78,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.5.0",
+  "version": "0.7.0",
   "description": "Tools for managing versioned TypeScript definition files",
   "main": "dist/index.js",
   "bin": {