@salesforce/metadata-plugins 1.0.0

package/dist/shared/utils/vizDependentPathsHelper.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+import { type IFileSystem } from '@salesforce/metadata-core-sdk';
+/**
+ * Helper for resolving visualization-dependent file paths.
+ *
+ * Requires IFileSystem at construction time only; all file and path operations
+ * use the injected fileSystem (no direct Node fs/path).
+ */
+export declare class VizDependentPathsHelper {
+    private readonly fileSystem;
+    /**
+     * @param fileSystem Platform file system (e.g. from IPlatformContext.fileSystem). Required only at construction.
+     */
+    constructor(fileSystem: IFileSystem);
+    /**
+     * Check if a filename matches a pattern.
+     *
+     * Supports simple wildcard patterns:
+     * - `*.ext` matches files ending with `.ext`
+     * - `prefix.*` matches files starting with `prefix.`
+     * - `exact` matches exact filename
+     */
+    private matchesPattern;
+    /**
+     * Find files matching a pattern in a sibling directory.
+     *
+     * When visualizing a parent file, finds all related files in a sibling directory
+     * (e.g., object file -> fields/*.field-meta.xml). Always includes the main file in the result.
+     *
+     * @param filePath - Path to the main file
+     * @param siblingDirName - Name of the sibling directory (e.g. 'fields', 'classes')
+     * @param siblingFilePattern - File pattern (e.g. '*.field-meta.xml')
+     * @returns Array of absolute file paths (always includes the main file)
+     */
+    findFilesInSiblingDirectory(filePath: string, siblingDirName: string, siblingFilePattern: string): Promise<string[]>;
+    /**
+     * Find parent file matching a pattern by searching up the directory hierarchy.
+     *
+     * When a child file changes, finds the parent file that should be re-visualized
+     * (e.g. field file -> object file). Searches up until a match, root, or max levels.
+     *
+     * @param filePath - Path to the child file
+     * @param parentPattern - Pattern to match parent file (e.g. '*.object-meta.xml')
+     * @returns Absolute path to parent file, or null if not found
+     */
+    findParentFile(filePath: string, parentPattern: string): Promise<string | null>;
+}
+//# sourceMappingURL=vizDependentPathsHelper.d.ts.map

package/dist/shared/utils/vizDependentPathsHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vizDependentPathsHelper.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/vizDependentPathsHelper.ts"],"names":[],"mappings":"AAAA;;;;;IAKI;AAEJ,OAAO,EAAE,KAAK,WAAW,EAA+B,MAAM,+BAA+B,CAAC;AAM9F;;;;;GAKG;AACH,qBAAa,uBAAuB;IAItB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAHvC;;OAEG;gBAC0B,UAAU,EAAE,WAAW;IASpD;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;;OAUG;IACG,2BAA2B,CAC/B,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,MAAM,EAAE,CAAC;IAuBpB;;;;;;;;;OASG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAiCtF"}

package/dist/shared/utils/vizDependentPathsHelper.js

@@ -0,0 +1,108 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+import { ErrorBuilder, ErrorCategory } from '@salesforce/metadata-core-sdk';
+const MAX_PARENT_LEVELS = 5;
+/**
+ * Helper for resolving visualization-dependent file paths.
+ *
+ * Requires IFileSystem at construction time only; all file and path operations
+ * use the injected fileSystem (no direct Node fs/path).
+ */
+export class VizDependentPathsHelper {
+    /**
+     * @param fileSystem Platform file system (e.g. from IPlatformContext.fileSystem). Required only at construction.
+     */
+    constructor(fileSystem) {
+        this.fileSystem = fileSystem;
+        if (!fileSystem) {
+            throw ErrorBuilder.create()
+                .category(ErrorCategory.Configuration)
+                .message('fileSystem is required')
+                .build();
+        }
+    }
+    /**
+     * Check if a filename matches a pattern.
+     *
+     * Supports simple wildcard patterns:
+     * - `*.ext` matches files ending with `.ext`
+     * - `prefix.*` matches files starting with `prefix.`
+     * - `exact` matches exact filename
+     */
+    matchesPattern(filename, pattern) {
+        if (pattern.startsWith('*')) {
+            return filename.endsWith(pattern.slice(1));
+        }
+        if (pattern.endsWith('*')) {
+            return filename.startsWith(pattern.slice(0, -1));
+        }
+        return filename === pattern || filename.endsWith(pattern);
+    }
+    /**
+     * Find files matching a pattern in a sibling directory.
+     *
+     * When visualizing a parent file, finds all related files in a sibling directory
+     * (e.g., object file -> fields/*.field-meta.xml). Always includes the main file in the result.
+     *
+     * @param filePath - Path to the main file
+     * @param siblingDirName - Name of the sibling directory (e.g. 'fields', 'classes')
+     * @param siblingFilePattern - File pattern (e.g. '*.field-meta.xml')
+     * @returns Array of absolute file paths (always includes the main file)
+     */
+    async findFilesInSiblingDirectory(filePath, siblingDirName, siblingFilePattern) {
+        const mainDir = this.fileSystem.dirname(filePath);
+        const siblingDir = this.fileSystem.join(mainDir, siblingDirName);
+        const dirExists = await this.fileSystem.exists(siblingDir);
+        if (!dirExists) {
+            return [filePath];
+        }
+        const result = await this.fileSystem.readDirectory(siblingDir);
+        if (!result.success || !result.data) {
+            return [filePath];
+        }
+        const files = result.data
+            .filter((entry) => entry.isFile && this.matchesPattern(entry.name, siblingFilePattern))
+            .map((entry) => this.fileSystem.join(siblingDir, entry.name));
+        return [...files, filePath];
+    }
+    /**
+     * Find parent file matching a pattern by searching up the directory hierarchy.
+     *
+     * When a child file changes, finds the parent file that should be re-visualized
+     * (e.g. field file -> object file). Searches up until a match, root, or max levels.
+     *
+     * @param filePath - Path to the child file
+     * @param parentPattern - Pattern to match parent file (e.g. '*.object-meta.xml')
+     * @returns Absolute path to parent file, or null if not found
+     */
+    async findParentFile(filePath, parentPattern) {
+        const parsed = this.fileSystem.parse(filePath);
+        let currentDir = this.fileSystem.dirname(filePath);
+        const rootPath = parsed.root;
+        let levelsSearched = 0;
+        while (levelsSearched < MAX_PARENT_LEVELS) {
+            const parentDir = this.fileSystem.dirname(currentDir);
+            if (currentDir === rootPath || currentDir === parentDir) {
+                break;
+            }
+            const dirExists = await this.fileSystem.exists(currentDir);
+            if (!dirExists) {
+                break;
+            }
+            const result = await this.fileSystem.readDirectory(currentDir);
+            if (result.success && result.data) {
+                const match = result.data.find((entry) => entry.isFile && this.matchesPattern(entry.name, parentPattern));
+                if (match) {
+                    return this.fileSystem.join(currentDir, match.name);
+                }
+            }
+            currentDir = parentDir;
+            levelsSearched++;
+        }
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@salesforce/metadata-plugins",
+  "version": "1.0.0",
+  "description": "Visualizer implementations for Salesforce metadata",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "npm": ">=7.0.0",
+    "node": ">=18.0.0",
+    "vscode": "^1.86.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && npm run build:react-apps",
+    "build:react-apps": "node scripts/build-react-apps.js",
+    "watch": "tsc -p tsconfig.json --watch",
+    "clean": "rm -rf dist && node scripts/cleanup-vscode-platform.js",
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "test:architecture": "jest src/__tests__/architecture.test.ts",
+    "test:unit": "jest --coverage --testPathPattern=__tests__",
+    "test:flexipage": "jest src/plugins/flexipage",
+    "vs:platform": "node scripts/vscode-platform.js",
+    "vs:dev": "node scripts/vscode-platform.js dev",
+    "vs:e2e": "node scripts/vscode-platform.js e2e",
+    "vs:e2e:compile": "node scripts/vscode-platform.js e2e-compile",
+    "vs:sync": "node scripts/vscode-platform.js sync",
+    "vs:sync-plugin": "node scripts/vscode-platform.js sync-plugin",
+    "watch:react": "node scripts/watch-react-apps.js",
+    "vs:clean": "node scripts/vscode-platform.js clean",
+    "bundle-size": "node scripts/bundle-size.js",
+    "prepare": "husky || true",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "salesforce",
+    "metadata",
+    "visualizer",
+    "plugins",
+    "implementations"
+  ],
+  "author": "salesforce",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forcedotcom/salesforce-metadata-visualizer-support"
+  },
+  "homepage": "https://github.com/forcedotcom/salesforce-metadata-visualizer-support#readme",
+  "bugs": {
+    "url": "https://github.com/forcedotcom/salesforce-metadata-visualizer-support/issues"
+  },
+  "peerDependencies": {
+    "@salesforce/metadata-core-sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.6.0",
+    "@commitlint/config-conventional": "^19.6.0",
+    "@dagrejs/dagre": "^2.0.4",
+    "@eslint/js": "^9.15.0",
+    "@salesforce/metadata-core-sdk": "^1.0.0",
+    "@salesforce/salesforcedx-vscode-test-tools": "^1.2.5",
+    "@tony.ganchev/eslint-plugin-header": "^3.1.6",
+    "@types/chai": "^4.3.11",
+    "@types/dagre": "^0.7.54",
+    "@types/jest": "^29.5.14",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^18.19.68",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@types/vscode": "^1.104.0",
+    "@types/xml2js": "^0.4.14",
+    "@vitejs/plugin-react": "^4.2.0",
+    "@xyflow/react": "^12.10.1",
+    "chai": "^4.3.7",
+    "chokidar": "^3.6.0",
+    "concurrently": "^9.2.1",
+    "eslint": "^9.15.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jest": "^28.9.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "glob": "^11.0.0",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "lint-staged": "^16.2.5",
+    "prettier": "^3.4.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.15.0",
+    "vite": "^5.0.0",
+    "vscode-extension-tester": "^8.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "overrides": {
+    "glob": "^11.0.0",
+    "test-exclude": ">=7.0.0"
+  }
+}