versioned-d.ts-tools 0.4.2 → 0.5.0

package/README.md

@@ -90,16 +90,50 @@ 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 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. This is useful when different Office applications have different URL patterns.
+
+**Configuration file format:**
+
+```json
+{
+  "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"
+    }
+  ]
+}
 ```
 
-This generates a `excel_whats_new.md` file containing a markdown table showing what's new between the two versions.
+When a configuration file is provided, the tool will use the appropriate URL pattern based on the relative path. For example:
+
+- Office Scripts APIs will use the Office Scripts-specific URL format
+- Other Office applications will use the standard URL format
+
+See `example-link-config.json` for a complete example.
 
 ## Programmatic Usage
 

package/dist/dts-utilities.d.ts

@@ -1,3 +1,8 @@
+export interface LinkConfig {
+    pathPattern: string;
+    buildLink: (relativePath: string, className: string, field: FieldStruct) => string;
+}
+export declare const DEFAULT_LINK_CONFIGS: LinkConfig[];
 declare enum ClassType {
     Class = "Class",
     Interface = "Interface",
@@ -35,7 +40,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,52 @@ 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"));
+// 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)";
+    }
+    else {
+        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;
+    }
+}
+// Default configurations for known Office applications
+exports.DEFAULT_LINK_CONFIGS = [
+    {
+        pathPattern: "office-scripts",
+        buildLink: buildOfficeScriptsLink
+    },
+    {
+        pathPattern: ".*", // matches any path as fallback
+        buildLink: buildStandardLink
+    }
+];
 // capturing these because of eccentricities with the compiler ordering
 let topClass = null;
 let lastItem = null;
@@ -156,7 +199,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";
@@ -226,7 +269,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 +320,11 @@ 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)";
-    }
-    // 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 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);
 }
 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,38 @@ 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);
+        // 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)`
+        }));
+    }
+    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 +78,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.5.0",
   "description": "Tools for managing versioned TypeScript definition files",
   "main": "dist/index.js",
   "bin": {