CHANGE: @W-18201387@ Template changes to support scaffolding (#251)

Author: randi274

README.md

@@ -1,7 +1,11 @@
 # Salesforce Code Analyzer - Core Module
 
-The code in repository is currently for internal use only while we build the next generate Salesforce Code Analyzer.
+The code in repository is currently for internal use only while we build the next Salesforce Code Analyzer.
 
-See instead:
+See our external products:
 * [sfdx-scanner](https://github.com/forcedotcom/sfdx-scanner)
-* [sfdx-code-analyzer-vscode](https://github.com/forcedotcom/sfdx-code-analyzer-vscode)
+* [sfdx-code-analyzer-vscode](https://github.com/forcedotcom/sfdx-code-analyzer-vscode)
+
+# Adding Additional Engines
+
+If you are an internal team looking to add Engine capabilities to Salesforce Code Analyzer, refer to the [ENGINE-TEMPLATE READ.ME](/packages/ENGINE-TEMPLATE/README.md).

package-lock.json

@@ -0,0 +1,14 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Salesforce.com, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

packages/ENGINE-TEMPLATE/LICENSE

@@ -0,0 +1,52 @@
+# Adding New Engines
+
+The [code-analyzer-core](../code-analyzer-core/) package has the capability to dynamically load any and all engines that live in this monorepo, based on both available engines and JIT user configurations. If you are an internal team looking to add plugin configuration that can be leveraged through the [code-analyzer Salesforce CLI plugin](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_code-analyzer_commands_unified.htm) and [Salesforce Code Analyzer VS Code Extension](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/analyze-vscode.html), this is where you should start.
+
+
+## Start with the Scaffolding
+
+1. Copy This Template
+
+Copy this entire template folder, and rename the directory to `code-analyzer-x-engine`, where `x` will be the name of your engine. For example, the `code-analyzer-sfge-engine` has `sfge` as the engine name for the capabilities referred to as the "Salesforce Graph Engine". Engine names should be lowercased and succinct. Engine names are subject to Salesforce Code Analyzer team approval.
+
+2. Add Dependencies
+
+Add any dependencies you might need for external rule retrieval or other functionality. Important to note in the included dependencies is the code analyzer engine api, which is also published from this monorepo:
+
+```
+"@salesforce/code-analyzer-engine-api": "<MUST_MATCH_ENGINE_API_VERSION>"
+```
+
+Use the value provided in the template today, and do not try to modify it. It may include "SNAPSHOT", such as "0.21.0-SNAPSHOT" which is what indicates a new version will be available with our next release, but the value should match whatever the template uses.
+
+3. Create Your Engine
+
+Open the [engine](src/engine.ts) file. Set your engine name, which should match the name of `x` above. Follow the rest of the instructions in the file.
+
+4. Create Your Plugin (which acts as a Factory or Provider of one or more engines)
+
+Open the [plugin.ts](src/plugin.ts) file. This currently extends EnginePluginV1, managed from the Engine API. Set your available engine name, which should match the name of `x` above (thought there is the option of adding multiple engines within your plugin as well).
+
+5. Export Your Plugin
+
+Update the [index.ts](src/index.ts) to export your plugin and a `createEnginePlugin` function which returns an instance of your plugin. This will allow for dynamic JIT loading when users decide which engines they want to use to scan their projects.
+
+6. Add Configuration (Optional)
+
+With v5 of Code Analyzer, users are able to add engine-specific [configuration](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/config-custom.html). If your engine would like to have specific configuration details, add this via a `config.ts` file, and consume it in the Engine constructor.
+
+## About Rules and Violations
+
+When building out the implementation of your rules and violations, we are less prescriptive about how rules need to be stored and written, but encourage flexible solutions that are easy to maintain. Testing is also a must, and note that this monorepo requires 100% testing coverage. We recommend working with [goldfiles](test/test-data/temp-goldfile.json) for reference test data.
+
+## Messaging
+
+Any customer-facing messaging should live in the [`messages.ts`](src/messages.ts) file. Example messages are there to get started.
+
+## Request Build Support
+
+When you are ready for your engine to be available in the Code Analyzer product suite, work with the CA team to publish your engine and update the build process to include the engine in our available engines.
+
+## Release and Documentation
+
+Code Analyzer publishes new versions at the end of every month. Documentation for your engine will need to be updated at the same time, so you will need to work with Code Analyzer Documentation writer to understand the rules that your engine will be provided. Documentation will be available with the other Code Analyzer [Engines](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/engines.html).

packages/ENGINE-TEMPLATE/README.md

@@ -0,0 +1,16 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+    eslint.configs.recommended,
+    ...tseslint.configs.recommended,
+    {
+        rules: {
+            "@typescript-eslint/no-unused-vars": ["error", {
+                "argsIgnorePattern": "^_",
+                "varsIgnorePattern": "^_",
+                "caughtErrorsIgnorePattern": "^_"
+            }]
+        }
+    }
+);

packages/ENGINE-TEMPLATE/eslint.config.mjs

@@ -0,0 +1,63 @@
+{
+  "name": "@salesforce/engine-template",
+  "description": "^^ Update me: ENGINE-TEMPLATE",
+  "version": "0.1.0-SNAPSHOT",
+  "author": "The Salesforce Code Analyzer Team",
+  "license": "BSD-3-Clause",
+  "homepage": "https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/overview",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forcedotcom/code-analyzer-core.git",
+    "directory": "packages/ENGINE-TEMPLATE"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@types/node": "^20.0.0",
+    "@salesforce/code-analyzer-engine-api": "0.21.0-SNAPSHOT"
+  },
+  "devDependencies": {
+    "@eslint/js": "^8.57.1",
+    "@types/jest": "^29.5.14",
+    "eslint": "^8.57.1",
+    "jest": "^29.7.0",
+    "rimraf": "*",
+    "ts-jest": "29.2.3",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.22.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json --verbose",
+    "test": "jest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "package": "npm pack",
+    "all": "npm run build && npm run test && npm run lint && npm run package",
+    "clean": "tsc --build tsconfig.build.json --clean",
+    "postclean": "rimraf dist && rimraf coverage && rimraf ./*.tgz && rimraf vulnerabilities",
+    "scrub": "npm run clean && rimraf node_modules",
+    "showcoverage": "open ./coverage/lcov-report/index.html"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/*.test.ts"
+    ],
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/dist/"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.ts",
+      "!src/index.ts"
+    ]
+  }
+}

packages/ENGINE-TEMPLATE/package.json

@@ -0,0 +1,79 @@
+import { DescribeOptions, Engine, EngineRunResults, LogLevel, RuleDescription, RunOptions, Violation } from "@salesforce/code-analyzer-engine-api";
+import * as fsp from 'node:fs/promises';
+import path from "path";
+import { getMessage } from "./messages";
+
+// *** Change the Class Name to match your engine's name
+export class TemplateEngine extends Engine {
+    // *** Change the NAME to match your engine's name
+    static readonly NAME = "template";
+
+    // *** Consider passing in a configuration object from your engine's plugin if you want to provide user-configuration
+    constructor() {
+        super();
+    }
+
+    getName(): string {
+        return TemplateEngine.NAME;
+    }
+
+    // *** Update if you want to get your engine version any other way
+    public async getEngineVersion(): Promise<string> {
+        const pathToPackageJson: string = path.join(__dirname, '..', 'package.json');
+        const packageJson: {version: string} = JSON.parse(await fsp.readFile(pathToPackageJson, 'utf-8'));
+        return packageJson.version;
+    }
+
+    // *** Remove underscore for private naming convention if you need any of the DescribeOptions
+    async describeRules(_describeOptions: DescribeOptions): Promise<RuleDescription[]> {
+        // *** Best Practice - Use RunRulesProgressEvents to keep users informed on the scan progress
+        this.emitRunRulesProgressEvent(0);
+
+        // *** Parse out relevant file types if you engine is language-specific
+        //const relevantFiles: string[] | undefined;
+
+        // *** Get your rules!
+        const ruleDescriptions: RuleDescription[] = [];
+
+        this.emitRunRulesProgressEvent(50);
+
+        // *** Retrieval Implementation is up to you, but you'll need to map them into RuleDescription form, such as:
+        const exampleRule: RuleDescription = {
+            name: "Example Rule",
+            severityLevel: 5,
+            tags: [
+              "Recommended"
+            ],
+            description: "The description of your rule",
+            resourceUrls: []
+        };
+        ruleDescriptions.push(exampleRule);
+        
+        // *** Best Practice - Set RunRulesProgressEvents to 100 before completing
+        this.emitDescribeRulesProgressEvent(100);
+        return ruleDescriptions;
+    }
+
+    // *** ruleNames comes from a describeRules call made just before running
+    async runRules(_ruleNames: string[], _runOptions: RunOptions): Promise<EngineRunResults> {
+
+        // *** Best Practice - Use RunRulesProgressEvents to keep users informed on the scan progress
+        this.emitRunRulesProgressEvent(2);
+
+        // *** Get your violations!
+        const violations: Violation[] = [];
+
+        // *** Rule Implementation - map any violations to Violations and CodeLocations
+        // *** If Violations do not have CodeLocations they will be shown in modal form
+
+        // *** Best Practice - Use messages sparingly to keep users informed
+        // *** Ideal for failures, or an announcement
+        const one = '1'
+        this.emitLogEvent(LogLevel.Debug, getMessage('TemplateMessage2', one, '2'));
+
+        this.emitRunRulesProgressEvent(100);
+        return {
+            violations: violations
+        };
+    }
+}

packages/ENGINE-TEMPLATE/src/engine.ts

@@ -0,0 +1,11 @@
+// This file should only contain the main exports for the package
+
+// *** Change the Plugin Name to match your plugin's name
+import { TemplateEnginePlugin } from "./plugin";
+import { EnginePlugin } from "@salesforce/code-analyzer-engine-api";
+
+function createEnginePlugin(): EnginePlugin {
+    return new TemplateEnginePlugin();
+}
+
+export { createEnginePlugin, TemplateEnginePlugin }

packages/ENGINE-TEMPLATE/src/index.ts

@@ -0,0 +1,22 @@
+import {getMessageFromCatalog} from "@salesforce/code-analyzer-engine-api";
+
+const MESSAGE_CATALOG : { [key: string]: string } = {
+    TemplateMessage1:
+        `This message has one variable, '%s', in its message.`,
+
+    TemplateMessage2:
+        `This message has two variables, '%s' and %d, in its message.`,
+
+    // *** Update this for the engine name
+    UnsupportedEngineName:
+        `The TemplateEnginePlugin does not support an engine with name '%s'.`
+}
+
+/**
+ * getMessage - This is the convenience function to get a message out of the message catalog.
+ * @param msgId - The message identifier
+ * @param args - The arguments that will fill in the %s and %d markers.
+ */
+export function getMessage(msgId: string, ...args: (string | number)[]): string {
+    return getMessageFromCatalog(MESSAGE_CATALOG, msgId, ...args);
+}

packages/ENGINE-TEMPLATE/src/messages.ts

@@ -0,0 +1,36 @@
+import {
+    ConfigObject,
+    Engine,
+    EnginePluginV1,
+} from "@salesforce/code-analyzer-engine-api";
+import {getMessage} from "./messages";
+import { TemplateEngine } from "./engine";
+
+// *** Change the Class Name to match your engine's name
+export class TemplateEnginePlugin extends EnginePluginV1 {
+
+    // *** Change to match your engine's name
+    // *** If your plugin provides multiple engines, we accept that here
+    getAvailableEngineNames(): string[] {
+        return [TemplateEngine.NAME];
+    }
+
+    async createEngine(engineName: string, _resolvedConfig: ConfigObject): Promise<Engine> {
+        validateEngineName(engineName);
+        // *** Update to use _resolvedConfig, if user-configuration is desired
+        return new TemplateEngine();
+    }
+
+    // *** Methods available for use if user-configuration is desired
+    //describeEngineConfig(engineName: string): ConfigDescription;
+    //createEngineConfig(engineName: string, configValueExtractor: ConfigValueExtractor): Promise<ConfigObject>;
+
+}
+
+// *** Best Practice - validate the engine name in every public method
+// since this library is public
+function validateEngineName(engineName: string) {
+    if (engineName !== TemplateEngine.NAME) {
+        throw new Error(getMessage('UnsupportedEngineName', engineName));
+    }
+}