versioned-d.ts-tools 0.4.2 → 0.6.0

package/README.md

@@ -90,16 +90,66 @@ You can provide an optional JSON configuration file to specify additional text r
 Compares two TypeScript definition files and generates a markdown report of the differences.
 
 ```bash
-whats-new [new d.ts] [old d.ts] [output file name (minus extension)] [relative path]
+whats-new [new d.ts] [old d.ts] [output file name (minus extension)] [relative path] [config file (optional)]
 ```
 
-**Example:**
+**Examples:**
 
 ```bash
+# Basic usage
 whats-new excel_1_9.d.ts excel_1_8.d.ts excel_whats_new javascript/api/excel/excel.
+
+# With configuration file for custom link patterns
+whats-new office-scripts.d.ts office-scripts-old.d.ts office-scripts-whats-new javascript/api/office-scripts/ my-link-config.json
 ```
 
-This generates a `excel_whats_new.md` file containing a markdown table showing what's new between the two versions.
+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
+
+You can provide an optional JSON configuration file to customize how URLs are generated for different API types using flexible templates with placeholders.
+
+**Configuration file format:**
+
+```json
+{
+  "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}"
+    }
+  ]
+}
+```
+
+**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)
+
+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.
 
 ## Programmatic Usage
 

package/dist/dts-utilities.d.ts

@@ -1,3 +1,10 @@
+export interface LinkConfig {
+    pathPattern: string;
+    globalFunctionTemplate: string;
+    classTemplate: string;
+    classMemberTemplate: string;
+}
+export declare const DEFAULT_LINK_CONFIGS: LinkConfig[];
 declare enum ClassType {
     Class = "Class",
     Interface = "Interface",
@@ -35,7 +42,7 @@ export declare class APISet {
     containsField(clas: ClassStruct, field: FieldStruct): boolean;
     diff(other: APISet): APISet;
     getAsDTS(): string;
-    getAsMarkdown(relativePath: string): string;
+    getAsMarkdown(relativePath: string, linkConfigs?: LinkConfig[]): string;
     sort(): void;
 }
 export declare function parseDTS(fileName: string, fileContents: string): APISet;

package/dist/dts-utilities.js

@@ -33,9 +33,53 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APISet = void 0;
+exports.APISet = exports.DEFAULT_LINK_CONFIGS = void 0;
 exports.parseDTS = parseDTS;
 const ts = __importStar(require("typescript"));
+// 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());
+    }
+    if (field) {
+        const suffix = (field.type === FieldType.Method || field.type === FieldType.Function) ? "-member(1)" : "-member";
+        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",
+        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
+        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
 let topClass = null;
 let lastItem = null;
@@ -156,7 +200,7 @@ class APISet {
         });
         return output.join("\n");
     }
-    getAsMarkdown(relativePath) {
+    getAsMarkdown(relativePath, linkConfigs = exports.DEFAULT_LINK_CONFIGS) {
         this.sort();
         // table header
         let output = "| Class | Fields | Description |\n|:---|:---|:---|\n";
@@ -174,8 +218,8 @@ class APISet {
                     output += "|*global*|";
                 }
                 else {
-                    output += "|[" + className + "](/"
-                        + relativePath + className.toLowerCase() + ")|";
+                    output += "|[" + className + "]("
+                        + buildClassLink(relativePath, className, linkConfigs) + ")|";
                 }
                 // Ignore the following:
                 // - String literal overloads.
@@ -226,7 +270,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) + ")|";
+                            + buildFieldLink(relativePath, className, field, linkConfigs) + ")|";
                         tableLine += removeAtLink(extractFirstSentenceFromComment(field.comment));
                         output += tableLine + "|\n";
                     });
@@ -277,20 +321,21 @@ function removeAtLink(commentText) {
     commentText = commentText.replace(/{@link ([^}]*?) \| (http.*?)}/gm, "[$1]($2)");
     return commentText;
 }
-function buildFieldLink(relativePath, className, field) {
-    // Special handling for global functions - use a different link format
-    if (className === "<global>") {
-        let hostName = relativePath.substring(relativePath.indexOf("/api/") + 5, relativePath.lastIndexOf("/"));
-        let fileName = relativePath.substring(relativePath.lastIndexOf("/") + 1, relativePath.lastIndexOf("."));
-        let anchorPrefix = hostName + "-" + fileName + "-";
-        return "/" + relativePath.substring(0, relativePath.lastIndexOf(".")) + "#" + anchorPrefix + field.name.toLowerCase() + "-function(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
+    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 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);
     }
-    // Build the standard link anchor format based on host.
-    let hostName = relativePath.substring(relativePath.indexOf("/api/") + 5, relativePath.lastIndexOf("/"));
-    let fileName = relativePath.substring(relativePath.lastIndexOf("/") + 1, relativePath.lastIndexOf("."));
-    let anchorPrefix = hostName + "-" + fileName + "-";
-    let fieldLink = "/" + relativePath + className.toLowerCase() + "#" + anchorPrefix + className.toLowerCase() + "-" + field.name.toLowerCase() + ((field.type === FieldType.Method || field.type === FieldType.Function) ? "-member(1)" : "-member");
-    return fieldLink;
 }
 function parseDTS(fileName, fileContents) {
     // Reset global state for new parse

package/dist/whats-new.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export declare function generateWhatsNew(newDtsPath: string, oldDtsPath: string, outputPath: string, relativePath: string): void;
+import { LinkConfig } from './dts-utilities';
+export declare function generateWhatsNew(newDtsPath: string, oldDtsPath: string, outputPath: string, relativePath: string, linkConfigs?: LinkConfig[], configFilePath?: string): void;

package/dist/whats-new.js

@@ -37,7 +37,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateWhatsNew = generateWhatsNew;
 const fsx = __importStar(require("fs-extra"));
 const dts_utilities_1 = require("./dts-utilities");
-function generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath) {
+/**
+ * Loads link configuration from a JSON file
+ * @param configFilePath Path to the configuration file
+ * @returns Array of LinkConfig objects
+ */
+function loadLinkConfig(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
+            };
+        });
+    }
+    catch (error) {
+        console.warn(`Could not load config file ${configFilePath}: ${error}. Using default configuration.`);
+        return [];
+    }
+}
+function generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath, linkConfigs, configFilePath) {
+    // Load configuration from file if provided
+    let effectiveLinkConfigs = linkConfigs;
+    if (configFilePath && !linkConfigs) {
+        effectiveLinkConfigs = loadLinkConfig(configFilePath);
+    }
     // read whole files
     let wholeRelease = fsx.readFileSync(oldDtsPath).toString();
     let wholePreview = fsx.readFileSync(newDtsPath).toString();
@@ -47,22 +79,27 @@ function generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath) {
     if (!fsx.existsSync(outputPath + ".md")) {
         fsx.createFileSync(outputPath + ".md");
     }
-    fsx.writeFileSync(outputPath + ".md", diffAPI.getAsMarkdown(relativePath));
+    fsx.writeFileSync(outputPath + ".md", diffAPI.getAsMarkdown(relativePath, effectiveLinkConfigs));
 }
 // CLI entry point
 if (require.main === module) {
-    if (process.argv.length !== 6 || process.argv.find((x) => { return x === "-?"; })) {
-        console.log("usage: whats-new [new d.ts] [old d.ts] [output file name (minus extension)] [relative path]");
+    if (process.argv.length < 6 || process.argv.length > 7 || process.argv.find((x) => { return x === "-?"; })) {
+        console.log("usage: whats-new [new d.ts] [old d.ts] [output file name (minus extension)] [relative path] [config file (optional)]");
         console.log("example: whats-new excel_1_9.d.ts excel_1_8.d.ts excel_whats_new javascript/api/excel/excel.");
+        console.log("example with config: whats-new excel_1_9.d.ts excel_1_8.d.ts excel_whats_new javascript/api/excel/excel. my-config.json");
         process.exit(0);
     }
     const newDtsPath = process.argv[2];
     const oldDtsPath = process.argv[3];
     const outputPath = process.argv[4];
     const relativePath = process.argv[5];
+    const configFilePath = process.argv.length === 7 ? process.argv[6] : undefined;
     console.log(`What's New between ${newDtsPath} and ${oldDtsPath}?`);
+    if (configFilePath) {
+        console.log(`Using configuration file: ${configFilePath}`);
+    }
     tryCatch(async () => {
-        generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath);
+        generateWhatsNew(newDtsPath, oldDtsPath, outputPath, relativePath, undefined, configFilePath);
     });
 }
 async function tryCatch(call) {

package/package.json

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