@salesforce/metadata-core-sdk 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.txt +27 -0
- package/README.md +219 -0
- package/dist/index.d.ts +38 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +22 -0
- package/dist/index.js.map +1 -0
- package/dist/sdk/abstractions/core/IPlatformContext.d.ts +45 -0
- package/dist/sdk/abstractions/core/IPlatformContext.d.ts.map +1 -0
- package/dist/sdk/abstractions/core/IPlatformContext.js +8 -0
- package/dist/sdk/abstractions/core/IPlatformContext.js.map +1 -0
- package/dist/sdk/abstractions/core/index.d.ts +8 -0
- package/dist/sdk/abstractions/core/index.d.ts.map +1 -0
- package/dist/sdk/abstractions/core/index.js +8 -0
- package/dist/sdk/abstractions/core/index.js.map +1 -0
- package/dist/sdk/abstractions/index.d.ts +17 -0
- package/dist/sdk/abstractions/index.d.ts.map +1 -0
- package/dist/sdk/abstractions/index.js +20 -0
- package/dist/sdk/abstractions/index.js.map +1 -0
- package/dist/sdk/abstractions/services/IFileSystem.d.ts +114 -0
- package/dist/sdk/abstractions/services/IFileSystem.d.ts.map +1 -0
- package/dist/sdk/abstractions/services/IFileSystem.js +8 -0
- package/dist/sdk/abstractions/services/IFileSystem.js.map +1 -0
- package/dist/sdk/abstractions/services/ILogger.d.ts +63 -0
- package/dist/sdk/abstractions/services/ILogger.d.ts.map +1 -0
- package/dist/sdk/abstractions/services/ILogger.js +18 -0
- package/dist/sdk/abstractions/services/ILogger.js.map +1 -0
- package/dist/sdk/abstractions/services/ITelemetry.d.ts +159 -0
- package/dist/sdk/abstractions/services/ITelemetry.d.ts.map +1 -0
- package/dist/sdk/abstractions/services/ITelemetry.js +97 -0
- package/dist/sdk/abstractions/services/ITelemetry.js.map +1 -0
- package/dist/sdk/abstractions/services/index.d.ts +10 -0
- package/dist/sdk/abstractions/services/index.d.ts.map +1 -0
- package/dist/sdk/abstractions/services/index.js +10 -0
- package/dist/sdk/abstractions/services/index.js.map +1 -0
- package/dist/sdk/abstractions/types/FileMetadata.d.ts +15 -0
- package/dist/sdk/abstractions/types/FileMetadata.d.ts.map +1 -0
- package/dist/sdk/abstractions/types/FileMetadata.js +8 -0
- package/dist/sdk/abstractions/types/FileMetadata.js.map +1 -0
- package/dist/sdk/abstractions/types/Result.d.ts +15 -0
- package/dist/sdk/abstractions/types/Result.d.ts.map +1 -0
- package/dist/sdk/abstractions/types/Result.js +8 -0
- package/dist/sdk/abstractions/types/Result.js.map +1 -0
- package/dist/sdk/abstractions/types/index.d.ts +9 -0
- package/dist/sdk/abstractions/types/index.d.ts.map +1 -0
- package/dist/sdk/abstractions/types/index.js +9 -0
- package/dist/sdk/abstractions/types/index.js.map +1 -0
- package/dist/sdk/constants.d.ts +35 -0
- package/dist/sdk/constants.d.ts.map +1 -0
- package/dist/sdk/constants.js +35 -0
- package/dist/sdk/constants.js.map +1 -0
- package/dist/sdk/contracts/core/IMetadataParser.d.ts +49 -0
- package/dist/sdk/contracts/core/IMetadataParser.d.ts.map +1 -0
- package/dist/sdk/contracts/core/IMetadataParser.js +8 -0
- package/dist/sdk/contracts/core/IMetadataParser.js.map +1 -0
- package/dist/sdk/contracts/core/IVisualizationPlugin.d.ts +65 -0
- package/dist/sdk/contracts/core/IVisualizationPlugin.d.ts.map +1 -0
- package/dist/sdk/contracts/core/IVisualizationPlugin.js +8 -0
- package/dist/sdk/contracts/core/IVisualizationPlugin.js.map +1 -0
- package/dist/sdk/contracts/core/index.d.ts +9 -0
- package/dist/sdk/contracts/core/index.d.ts.map +1 -0
- package/dist/sdk/contracts/core/index.js +9 -0
- package/dist/sdk/contracts/core/index.js.map +1 -0
- package/dist/sdk/contracts/index.d.ts +9 -0
- package/dist/sdk/contracts/index.d.ts.map +1 -0
- package/dist/sdk/contracts/index.js +9 -0
- package/dist/sdk/contracts/index.js.map +1 -0
- package/dist/sdk/contracts/types/MetadataPluginInfo.d.ts +56 -0
- package/dist/sdk/contracts/types/MetadataPluginInfo.d.ts.map +1 -0
- package/dist/sdk/contracts/types/MetadataPluginInfo.js +8 -0
- package/dist/sdk/contracts/types/MetadataPluginInfo.js.map +1 -0
- package/dist/sdk/contracts/types/PluginConfig.d.ts +16 -0
- package/dist/sdk/contracts/types/PluginConfig.d.ts.map +1 -0
- package/dist/sdk/contracts/types/PluginConfig.js +8 -0
- package/dist/sdk/contracts/types/PluginConfig.js.map +1 -0
- package/dist/sdk/contracts/types/PluginContext.d.ts +22 -0
- package/dist/sdk/contracts/types/PluginContext.d.ts.map +1 -0
- package/dist/sdk/contracts/types/PluginContext.js +8 -0
- package/dist/sdk/contracts/types/PluginContext.js.map +1 -0
- package/dist/sdk/contracts/types/PluginError.d.ts +50 -0
- package/dist/sdk/contracts/types/PluginError.d.ts.map +1 -0
- package/dist/sdk/contracts/types/PluginError.js +31 -0
- package/dist/sdk/contracts/types/PluginError.js.map +1 -0
- package/dist/sdk/contracts/types/ValidationResult.d.ts +15 -0
- package/dist/sdk/contracts/types/ValidationResult.d.ts.map +1 -0
- package/dist/sdk/contracts/types/ValidationResult.js +8 -0
- package/dist/sdk/contracts/types/ValidationResult.js.map +1 -0
- package/dist/sdk/contracts/types/VersionInfo.d.ts +24 -0
- package/dist/sdk/contracts/types/VersionInfo.d.ts.map +1 -0
- package/dist/sdk/contracts/types/VersionInfo.js +8 -0
- package/dist/sdk/contracts/types/VersionInfo.js.map +1 -0
- package/dist/sdk/contracts/types/index.d.ts +13 -0
- package/dist/sdk/contracts/types/index.d.ts.map +1 -0
- package/dist/sdk/contracts/types/index.js +13 -0
- package/dist/sdk/contracts/types/index.js.map +1 -0
- package/dist/sdk/design-system/index.d.ts +11 -0
- package/dist/sdk/design-system/index.d.ts.map +1 -0
- package/dist/sdk/design-system/index.js +12 -0
- package/dist/sdk/design-system/index.js.map +1 -0
- package/dist/sdk/design-system/tokens/colors.d.ts +122 -0
- package/dist/sdk/design-system/tokens/colors.d.ts.map +1 -0
- package/dist/sdk/design-system/tokens/colors.js +142 -0
- package/dist/sdk/design-system/tokens/colors.js.map +1 -0
- package/dist/sdk/design-system/tokens/spacing.d.ts +24 -0
- package/dist/sdk/design-system/tokens/spacing.d.ts.map +1 -0
- package/dist/sdk/design-system/tokens/spacing.js +24 -0
- package/dist/sdk/design-system/tokens/spacing.js.map +1 -0
- package/dist/sdk/design-system/tokens/typography.d.ts +31 -0
- package/dist/sdk/design-system/tokens/typography.d.ts.map +1 -0
- package/dist/sdk/design-system/tokens/typography.js +31 -0
- package/dist/sdk/design-system/tokens/typography.js.map +1 -0
- package/dist/sdk/design-system/utils.d.ts +66 -0
- package/dist/sdk/design-system/utils.d.ts.map +1 -0
- package/dist/sdk/design-system/utils.js +116 -0
- package/dist/sdk/design-system/utils.js.map +1 -0
- package/dist/sdk/design-system/vscode-design-system.css +623 -0
- package/dist/sdk/utils/errors/ErrorBoundary.d.ts +35 -0
- package/dist/sdk/utils/errors/ErrorBoundary.d.ts.map +1 -0
- package/dist/sdk/utils/errors/ErrorBoundary.js +65 -0
- package/dist/sdk/utils/errors/ErrorBoundary.js.map +1 -0
- package/dist/sdk/utils/errors/ErrorBuilder.d.ts +107 -0
- package/dist/sdk/utils/errors/ErrorBuilder.d.ts.map +1 -0
- package/dist/sdk/utils/errors/ErrorBuilder.js +163 -0
- package/dist/sdk/utils/errors/ErrorBuilder.js.map +1 -0
- package/dist/sdk/utils/errors/setupHandlers.d.ts +12 -0
- package/dist/sdk/utils/errors/setupHandlers.d.ts.map +1 -0
- package/dist/sdk/utils/errors/setupHandlers.js +42 -0
- package/dist/sdk/utils/errors/setupHandlers.js.map +1 -0
- package/dist/sdk/utils/logger.d.ts +41 -0
- package/dist/sdk/utils/logger.d.ts.map +1 -0
- package/dist/sdk/utils/logger.js +54 -0
- package/dist/sdk/utils/logger.js.map +1 -0
- package/dist/sdk/utils/test-helpers/architecture-test-utils.d.ts +146 -0
- package/dist/sdk/utils/test-helpers/architecture-test-utils.d.ts.map +1 -0
- package/dist/sdk/utils/test-helpers/architecture-test-utils.js +286 -0
- package/dist/sdk/utils/test-helpers/architecture-test-utils.js.map +1 -0
- package/dist/sdk/utils/test-helpers/index.d.ts +8 -0
- package/dist/sdk/utils/test-helpers/index.d.ts.map +1 -0
- package/dist/sdk/utils/test-helpers/index.js +8 -0
- package/dist/sdk/utils/test-helpers/index.js.map +1 -0
- package/dist/sdk/utils/xmlParser.d.ts +38 -0
- package/dist/sdk/utils/xmlParser.d.ts.map +1 -0
- package/dist/sdk/utils/xmlParser.js +79 -0
- package/dist/sdk/utils/xmlParser.js.map +1 -0
- package/dist/sdk/webviewMessageTypes.d.ts +24 -0
- package/dist/sdk/webviewMessageTypes.d.ts.map +1 -0
- package/dist/sdk/webviewMessageTypes.js +23 -0
- package/dist/sdk/webviewMessageTypes.js.map +1 -0
- package/package.json +80 -0
- package/src/sdk/utils/test-helpers/architecture-test-utils.ts +365 -0
- package/src/sdk/utils/test-helpers/index.ts +20 -0
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright (c) 2025, Salesforce, Inc.
|
|
3
|
+
* All rights reserved.
|
|
4
|
+
* Licensed under the BSD 3-Clause license.
|
|
5
|
+
* For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
|
|
6
|
+
**/
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Architecture test helpers for enforcing import and dependency boundaries.
|
|
10
|
+
*
|
|
11
|
+
* Used by architecture.test.ts to:
|
|
12
|
+
* - Scan source files under a package root
|
|
13
|
+
* - Detect banned package imports (static, require, dynamic import)
|
|
14
|
+
* - Detect banned string patterns in lines (e.g. relative cross-plugin paths)
|
|
15
|
+
* - Apply glob-style exclude patterns and explicit file exclusions
|
|
16
|
+
* - Report violations with file, line, and suggested fix
|
|
17
|
+
*
|
|
18
|
+
* Glob patterns supported: ** (any path), * (one segment), {a,b} (alternatives).
|
|
19
|
+
* Paths are normalized to forward slashes before matching.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
import * as fs from 'fs';
|
|
23
|
+
import * as path from 'path';
|
|
24
|
+
import { glob } from 'glob';
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Configuration for a single architecture rule (one "suite" in the test).
|
|
28
|
+
*/
|
|
29
|
+
export interface SuiteConfig {
|
|
30
|
+
/** Human-readable description shown in violation messages */
|
|
31
|
+
description: string;
|
|
32
|
+
/** Package names that must not appear in import/require (e.g. 'fs', '@salesforce/foo') */
|
|
33
|
+
bannedPackages?: string[];
|
|
34
|
+
/** String patterns that must not appear in a line (e.g. '../object' for cross-plugin imports) */
|
|
35
|
+
bannedPatterns?: string[];
|
|
36
|
+
/** Glob patterns for paths to skip entirely (e.g. patterns for __tests__ or scripts dirs) */
|
|
37
|
+
excludePatterns: string[];
|
|
38
|
+
/** Exact path substrings for files to skip (temporary allowlist; prefer fixing the code) */
|
|
39
|
+
excludeFiles: string[];
|
|
40
|
+
/** Optional message shown after the violation list (e.g. how to fix) */
|
|
41
|
+
errorMessage?: string;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Full architecture config: a map of suite name -> SuiteConfig.
|
|
46
|
+
* Each suite is run independently and reported separately.
|
|
47
|
+
*/
|
|
48
|
+
export interface ArchitectureConfig {
|
|
49
|
+
suites: Record<string, SuiteConfig>;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* A single violation: one line in one file that broke a rule.
|
|
54
|
+
*/
|
|
55
|
+
export interface Violation {
|
|
56
|
+
/** Path relative to package root */
|
|
57
|
+
file: string;
|
|
58
|
+
/** 1-based line number */
|
|
59
|
+
line: number;
|
|
60
|
+
/** Trimmed line content */
|
|
61
|
+
content: string;
|
|
62
|
+
/** Set when violation is from bannedPackages */
|
|
63
|
+
package?: string;
|
|
64
|
+
/** Set when violation is from bannedPatterns */
|
|
65
|
+
pattern?: string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Placeholder for ** in glob (non-control char so ESLint no-control-regex is satisfied) */
|
|
69
|
+
const GLOBSTAR_PLACEHOLDER = '\u200B';
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Converts a glob-style pattern into a regex string for matching file paths.
|
|
73
|
+
*
|
|
74
|
+
* Supported syntax:
|
|
75
|
+
* - ** = match zero or more path segments (any characters including /)
|
|
76
|
+
* - * = match one path segment (any characters except /)
|
|
77
|
+
* - {a,b} = match one of the comma-separated options (e.g. {ts,js} for .ts or .js)
|
|
78
|
+
*
|
|
79
|
+
* Order of replacement matters: ** is stashed first so that * doesn't consume it;
|
|
80
|
+
* then . is escaped; then the placeholder is turned into .* last so that dot isn't escaped.
|
|
81
|
+
*
|
|
82
|
+
* @param pattern - Glob pattern (e.g. double-asterisk slash __tests__ for test dirs, or *.test.{ts,js})
|
|
83
|
+
* @returns Regex source string; caller wraps in start/end anchors for full path match
|
|
84
|
+
*/
|
|
85
|
+
function globToRegex(pattern: string): string {
|
|
86
|
+
return pattern
|
|
87
|
+
.replace(/\\/g, '/') // normalize backslashes to forward slashes (Windows)
|
|
88
|
+
.replace(/\*\*/g, GLOBSTAR_PLACEHOLDER) // stash ** so next step doesn't turn it into [^/]*
|
|
89
|
+
.replace(/\*/g, '[^/]*') // * = one path segment (no slashes)
|
|
90
|
+
.replace(/\{([^}]+)\}/g, (_, group) => {
|
|
91
|
+
// {ts,js} -> (ts|js); escape dots in each option
|
|
92
|
+
const options = group.split(',').map((s: string) => s.trim());
|
|
93
|
+
return `(${options.map((o: string) => o.replace(/\./g, '\\.')).join('|')})`;
|
|
94
|
+
})
|
|
95
|
+
.replace(/\./g, '\\.') // escape literal dots (e.g. .test .ts)
|
|
96
|
+
.replace(new RegExp(GLOBSTAR_PLACEHOLDER, 'g'), '.*'); // ** = any characters including /
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Returns true if the file path matches the glob pattern (full path match).
|
|
101
|
+
*
|
|
102
|
+
* The path is normalized to forward slashes. The pattern is converted via globToRegex
|
|
103
|
+
* and anchored at both ends (^...$), so the entire path must match.
|
|
104
|
+
*
|
|
105
|
+
* @param filePath - Path to check (relative or absolute; backslashes normalized)
|
|
106
|
+
* @param pattern - Glob pattern (e.g. pattern for __tests__ dir or one segment wildcard)
|
|
107
|
+
* @returns true if the path matches, false otherwise (or if regex construction fails)
|
|
108
|
+
*/
|
|
109
|
+
export function matchPattern(filePath: string, pattern: string): boolean {
|
|
110
|
+
const normalizedPath = filePath.replace(/\\/g, '/');
|
|
111
|
+
const regexStr = globToRegex(pattern);
|
|
112
|
+
try {
|
|
113
|
+
const regex = new RegExp(`^${regexStr}$`);
|
|
114
|
+
return regex.test(normalizedPath);
|
|
115
|
+
} catch {
|
|
116
|
+
return false;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Returns true if the file should be excluded from architecture checks.
|
|
122
|
+
*
|
|
123
|
+
* A file is excluded if:
|
|
124
|
+
* 1. Its path matches any of the glob patterns in excludePatterns, or
|
|
125
|
+
* 2. Its path includes any of the strings in excludeFiles (substring match).
|
|
126
|
+
*
|
|
127
|
+
* Use excludePatterns for broad rules (e.g. all __tests__); use excludeFiles for
|
|
128
|
+
* a temporary allowlist of specific files until they are refactored.
|
|
129
|
+
*
|
|
130
|
+
* @param relativePath - File path relative to package root
|
|
131
|
+
* @param excludePatterns - Glob patterns (e.g. patterns that match __tests__ or scripts dirs)
|
|
132
|
+
* @param excludeFiles - Path substrings (e.g. 'core/PluginManager.ts')
|
|
133
|
+
*/
|
|
134
|
+
export function isExcluded(
|
|
135
|
+
relativePath: string,
|
|
136
|
+
excludePatterns: string[],
|
|
137
|
+
excludeFiles: string[]
|
|
138
|
+
): boolean {
|
|
139
|
+
const normalizedPath = relativePath.replace(/\\/g, '/');
|
|
140
|
+
for (const pattern of excludePatterns) {
|
|
141
|
+
if (matchPattern(normalizedPath, pattern)) {
|
|
142
|
+
return true;
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
return excludeFiles.some((exclusion) => normalizedPath.includes(exclusion.replace(/\\/g, '/')));
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Detects if a line contains an import/require of one of the banned packages.
|
|
150
|
+
*
|
|
151
|
+
* Checks for (with single or double quotes):
|
|
152
|
+
* - ES static: import ... from 'pkg'
|
|
153
|
+
* - CommonJS: require('pkg')
|
|
154
|
+
* - Dynamic: import('pkg') or import('pkg' + ...)
|
|
155
|
+
*
|
|
156
|
+
* Does not parse the AST; uses string inclusion, so avoid banning substrings
|
|
157
|
+
* that could appear in comments or unrelated strings.
|
|
158
|
+
*
|
|
159
|
+
* @param line - One line of source code (will be trimmed)
|
|
160
|
+
* @param bannedPackages - Package names to forbid (e.g. ['fs', 'node:fs'])
|
|
161
|
+
* @returns The matched package name, or null if none
|
|
162
|
+
*/
|
|
163
|
+
export function checkForBannedImport(line: string, bannedPackages: string[]): string | null {
|
|
164
|
+
const trimmedLine = line.trim();
|
|
165
|
+
|
|
166
|
+
for (const pkg of bannedPackages) {
|
|
167
|
+
const singleQuoted = `'${pkg}'`;
|
|
168
|
+
const doubleQuoted = `"${pkg}"`;
|
|
169
|
+
|
|
170
|
+
if (trimmedLine.includes(singleQuoted) || trimmedLine.includes(doubleQuoted)) {
|
|
171
|
+
if (
|
|
172
|
+
trimmedLine.includes(`from ${singleQuoted}`) ||
|
|
173
|
+
trimmedLine.includes(`from ${doubleQuoted}`) ||
|
|
174
|
+
trimmedLine.includes(`require(${singleQuoted})`) ||
|
|
175
|
+
trimmedLine.includes(`require(${doubleQuoted})`) ||
|
|
176
|
+
trimmedLine.includes(`import(${singleQuoted})`) ||
|
|
177
|
+
trimmedLine.includes(`import(${doubleQuoted})`) ||
|
|
178
|
+
trimmedLine.includes(`import(${singleQuoted}.`) ||
|
|
179
|
+
trimmedLine.includes(`import(${doubleQuoted}.`)
|
|
180
|
+
) {
|
|
181
|
+
return pkg;
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
return null;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* Detects if a line contains a banned substring pattern (e.g. relative path to another plugin).
|
|
191
|
+
*
|
|
192
|
+
* The pattern is converted to a regex: . and * are escaped, ** becomes .*.
|
|
193
|
+
* So bannedPatterns like '../object' will match lines containing that substring.
|
|
194
|
+
* Used for rules that are not package names (e.g. no cross-plugin relative imports).
|
|
195
|
+
*
|
|
196
|
+
* @param line - One line of source code (will be trimmed)
|
|
197
|
+
* @param bannedPatterns - Literal patterns to forbid (e.g. ['../object', '../flow'])
|
|
198
|
+
* @returns The matched pattern, or null if none
|
|
199
|
+
*/
|
|
200
|
+
export function checkForBannedPattern(line: string, bannedPatterns: string[]): string | null {
|
|
201
|
+
const trimmedLine = line.trim();
|
|
202
|
+
for (const pattern of bannedPatterns) {
|
|
203
|
+
const regex = patternToRegex(pattern);
|
|
204
|
+
if (regex && regex.test(trimmedLine)) {
|
|
205
|
+
return pattern;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
return null;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* Converts a simple pattern string into a RegExp for line matching.
|
|
213
|
+
*
|
|
214
|
+
* Used by checkForBannedPattern. Escapes dot and star for regex; double-asterisk becomes .*
|
|
215
|
+
* so we can match substrings in a line (e.g. relative path in an import). The pattern
|
|
216
|
+
* [^'"]* means "any character except quote" for import path segments.
|
|
217
|
+
*
|
|
218
|
+
* @param pattern - Literal pattern (e.g. '../object')
|
|
219
|
+
* @returns RegExp or null if construction fails
|
|
220
|
+
*/
|
|
221
|
+
function patternToRegex(pattern: string): RegExp | null {
|
|
222
|
+
try {
|
|
223
|
+
const escaped = pattern
|
|
224
|
+
.replace(/\./g, '\\.') // literal dot
|
|
225
|
+
.replace(/\*\*/g, '.*') // ** = any chars
|
|
226
|
+
.replace(/\*/g, '[^\'"]*'); // * = any chars except single/double quote (for import paths)
|
|
227
|
+
return new RegExp(escaped);
|
|
228
|
+
} catch {
|
|
229
|
+
return null;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* Finds all TypeScript/JavaScript source files under packageRoot.
|
|
235
|
+
*
|
|
236
|
+
* Includes .ts, .js, .tsx, .jsx. Excludes node_modules, dist, out, and build.
|
|
237
|
+
* Returns absolute file paths. Used as the input for validateSuite.
|
|
238
|
+
*
|
|
239
|
+
* @param packageRoot - Directory to scan (e.g. path to src)
|
|
240
|
+
* @returns Absolute paths of matching files
|
|
241
|
+
*/
|
|
242
|
+
export async function scanSourceFiles(packageRoot: string): Promise<string[]> {
|
|
243
|
+
const files = await glob('**/*.{ts,js,tsx,jsx}', {
|
|
244
|
+
cwd: packageRoot,
|
|
245
|
+
ignore: ['**/node_modules/**', '**/dist/**', '**/out/**', '**/build/**'],
|
|
246
|
+
absolute: true,
|
|
247
|
+
});
|
|
248
|
+
return files;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* Runs one suite against the given file list: applies exclusions, then checks
|
|
253
|
+
* each non-excluded file for banned imports and banned patterns.
|
|
254
|
+
*
|
|
255
|
+
* Files in suite.excludePatterns or suite.excludeFiles are skipped. For each
|
|
256
|
+
* remaining file, every line is checked against bannedPackages (if set) and
|
|
257
|
+
* bannedPatterns (if set). Each hit is recorded as a Violation.
|
|
258
|
+
*
|
|
259
|
+
* @param packageRoot - Root used to compute relative paths in violations
|
|
260
|
+
* @param sourceFiles - Absolute paths (e.g. from scanSourceFiles)
|
|
261
|
+
* @param suiteName - Name of the suite (for reference)
|
|
262
|
+
* @param suite - Rule config (banned lists, exclusions)
|
|
263
|
+
* @returns List of violations for this suite
|
|
264
|
+
*/
|
|
265
|
+
export function validateSuite(
|
|
266
|
+
packageRoot: string,
|
|
267
|
+
sourceFiles: string[],
|
|
268
|
+
suiteName: string,
|
|
269
|
+
suite: SuiteConfig
|
|
270
|
+
): Violation[] {
|
|
271
|
+
const violations: Violation[] = [];
|
|
272
|
+
|
|
273
|
+
for (const file of sourceFiles) {
|
|
274
|
+
const relativePath = path.relative(packageRoot, file);
|
|
275
|
+
if (isExcluded(relativePath, suite.excludePatterns, suite.excludeFiles)) {
|
|
276
|
+
continue;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
const content = fs.readFileSync(file, 'utf-8');
|
|
280
|
+
const lines = content.split('\n');
|
|
281
|
+
|
|
282
|
+
lines.forEach((line, index) => {
|
|
283
|
+
if (suite.bannedPackages?.length) {
|
|
284
|
+
const bannedPackage = checkForBannedImport(line, suite.bannedPackages);
|
|
285
|
+
if (bannedPackage) {
|
|
286
|
+
violations.push({
|
|
287
|
+
file: relativePath,
|
|
288
|
+
line: index + 1,
|
|
289
|
+
content: line.trim(),
|
|
290
|
+
package: bannedPackage,
|
|
291
|
+
});
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
if (suite.bannedPatterns?.length) {
|
|
295
|
+
const bannedPattern = checkForBannedPattern(line, suite.bannedPatterns);
|
|
296
|
+
if (bannedPattern) {
|
|
297
|
+
violations.push({
|
|
298
|
+
file: relativePath,
|
|
299
|
+
line: index + 1,
|
|
300
|
+
content: line.trim(),
|
|
301
|
+
pattern: bannedPattern,
|
|
302
|
+
});
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
});
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
return violations;
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/**
|
|
312
|
+
* Runs all suites in config: scans packageRoot once, then runs each suite
|
|
313
|
+
* and collects violations per suite name.
|
|
314
|
+
*
|
|
315
|
+
* @param packageRoot - Root directory to scan and relativize paths from
|
|
316
|
+
* @param config - Full architecture config (map of suite name -> SuiteConfig)
|
|
317
|
+
* @returns Map of suite name -> list of violations (empty array if none)
|
|
318
|
+
*/
|
|
319
|
+
export async function validateArchitecture(
|
|
320
|
+
packageRoot: string,
|
|
321
|
+
config: ArchitectureConfig
|
|
322
|
+
): Promise<Record<string, Violation[]>> {
|
|
323
|
+
const sourceFiles = await scanSourceFiles(packageRoot);
|
|
324
|
+
const results: Record<string, Violation[]> = {};
|
|
325
|
+
|
|
326
|
+
for (const [suiteName, suite] of Object.entries(config.suites)) {
|
|
327
|
+
results[suiteName] = validateSuite(packageRoot, sourceFiles, suiteName, suite);
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
return results;
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
/**
|
|
334
|
+
* Formats a list of violations into a single string suitable for throwing
|
|
335
|
+
* as an Error message or logging. Includes suite description, file:line,
|
|
336
|
+
* line content, and package/pattern that was violated; appends suite.errorMessage
|
|
337
|
+
* and a hint about excludeFiles.
|
|
338
|
+
*
|
|
339
|
+
* @param suiteName - Name of the suite that failed
|
|
340
|
+
* @param suite - Suite config (description, errorMessage)
|
|
341
|
+
* @param violations - List of violations from validateSuite
|
|
342
|
+
* @returns Multi-line string (no trailing newline)
|
|
343
|
+
*/
|
|
344
|
+
export function reportViolations(
|
|
345
|
+
suiteName: string,
|
|
346
|
+
suite: SuiteConfig,
|
|
347
|
+
violations: Violation[]
|
|
348
|
+
): string {
|
|
349
|
+
const lines = [
|
|
350
|
+
`\nArchitecture Violation: ${suite.description}`,
|
|
351
|
+
'',
|
|
352
|
+
`Found ${violations.length} violation(s) in suite '${suiteName}':`,
|
|
353
|
+
'',
|
|
354
|
+
...violations.map((v) => {
|
|
355
|
+
const detail = v.package ? `Package: ${v.package}` : `Pattern: ${v.pattern}`;
|
|
356
|
+
return ` ${v.file}:${v.line}\n ${v.content}\n ${detail}`;
|
|
357
|
+
}),
|
|
358
|
+
'',
|
|
359
|
+
];
|
|
360
|
+
if (suite.errorMessage) {
|
|
361
|
+
lines.push(`${suite.errorMessage}`);
|
|
362
|
+
}
|
|
363
|
+
lines.push(' Add file to excludeFiles in architecture config if this is temporary.');
|
|
364
|
+
return lines.join('\n');
|
|
365
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright (c) 2025, Salesforce, Inc.
|
|
3
|
+
* All rights reserved.
|
|
4
|
+
* Licensed under the BSD 3-Clause license.
|
|
5
|
+
* For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
|
|
6
|
+
**/
|
|
7
|
+
|
|
8
|
+
export {
|
|
9
|
+
type ArchitectureConfig,
|
|
10
|
+
type SuiteConfig,
|
|
11
|
+
type Violation,
|
|
12
|
+
checkForBannedImport,
|
|
13
|
+
checkForBannedPattern,
|
|
14
|
+
isExcluded,
|
|
15
|
+
matchPattern,
|
|
16
|
+
reportViolations,
|
|
17
|
+
scanSourceFiles,
|
|
18
|
+
validateArchitecture,
|
|
19
|
+
validateSuite,
|
|
20
|
+
} from './architecture-test-utils';
|