versioned-d.ts-tools 0.5.0 → 0.6.0

package/README.md

@@ -107,7 +107,7 @@ This generates a markdown file (e.g., `excel_whats_new.md`) containing a table s
 
 #### 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.
+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:**
 
@@ -117,21 +117,37 @@ You can provide an optional JSON configuration file to customize how URLs are ge
     {
       "name": "Office Scripts",
       "pathPattern": "office-scripts",
-      "description": "Special URL pattern for 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"
+      "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}"
     }
   ]
 }
 ```
 
-When a configuration file is provided, the tool will use the appropriate URL pattern based on the relative path. For example:
+**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
 
-- Office Scripts APIs will use the Office Scripts-specific URL format
-- Other Office applications will use the standard URL format
+**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.
 

package/dist/dts-utilities.d.ts

@@ -1,6 +1,8 @@
 export interface LinkConfig {
     pathPattern: string;
-    buildLink: (relativePath: string, className: string, field: FieldStruct) => string;
+    globalFunctionTemplate: string;
+    classTemplate: string;
+    classMemberTemplate: string;
 }
 export declare const DEFAULT_LINK_CONFIGS: LinkConfig[];
 declare enum ClassType {

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 {
-        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("."));
+    if (field) {
         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
@@ -217,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.
@@ -320,11 +321,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.js

@@ -46,17 +46,18 @@ 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)`
-        }));
+        // 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.`);

package/package.json

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