@simplysf/simply-utam-core 0.1.0 → 0.1.1

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/README.md CHANGED
@@ -67,26 +67,26 @@ internal.
67
67
 
68
68
  ### Org authentication & Environment
69
69
 
70
- | Export | Description |
71
- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
72
- | `TestEnvironment` | The org under test. `new TestEnvironment({ username?, env?, allowedDomains? })` throws when neither a username nor `UTAM_USERNAME` is set. |
73
- | `testEnvironment.getOrg()` | The authenticated `Org`. Authenticates on first call and shares the result; a failure is not cached. |
74
- | `testEnvironment.getConnection()` | The underlying `@salesforce/core` Connection. |
75
- | `testEnvironment.init()` | Authenticates eagerly, for a runner hook that wants auth failures reported before any test starts. Optional. |
76
- | `testEnvironment.buildFrontdoorUrl(returnUrl?)` | A one-time URL that logs a browser in and lands on `returnUrl`. |
77
- | `testEnvironment.buildExperienceFrontdoorUrl(prefix?, ret?)` | One-time single-access login URL for Experience Cloud sites. |
78
- | `testEnvironment.getOrgId()` | Dynamically queries the 15- or 18-character Salesforce Organization ID. |
79
- | `testEnvironment.getUserIdByUsername(username)` | Resolves a target username to its Salesforce User record ID. |
80
- | `testEnvironment.getNetworkIdByPrefix(prefix?)` | Resolves an Experience site prefix to its corresponding Network ID. |
81
- | `testEnvironment.buildExperienceUrl(prefix?, path?)` | Constructs a fully qualified secure Experience Cloud site URL. |
82
- | `getTestEnvironment(options?)` | Retrieves the global singleton `TestEnvironment` instance. |
83
- | `setTestEnvironment(instance)` | Overrides the global `TestEnvironment` singleton. |
84
- | `resetTestEnvironment()` | Resets and unsets the global `TestEnvironment` singleton. |
85
- | `isHostAllowed(host, instanceUrl?, allowedDomains?)` | Validates a hostname against Salesforce default patterns and custom overrides. |
86
- | `validateAndParseSecureUrl(secureUrl, siteId, validator?)` | Validates and parses a raw secure URL retrieved from SiteDetail. |
87
- | `DEFAULT_ALLOWED_HOST_PATTERNS` | Default trusted Salesforce domain RegExp matchers. |
88
- | `USERNAME_ENV` | `'UTAM_USERNAME'`. |
89
- | `TestEnvironmentOptions`, `EnvLike` | Types for the constructor options and an environment-shaped map. |
70
+ | Export | Description |
71
+ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
72
+ | `TestEnvironment` | The org under test. `new TestEnvironment({ username?, env?, allowedDomains? })` throws when neither a username nor `UTAM_USERNAME` is set. |
73
+ | `testEnvironment.getOrg()` | The authenticated `Org`. Authenticates on first call and shares the result; a failure is not cached. |
74
+ | `testEnvironment.getConnection()` | The underlying `@salesforce/core` Connection. |
75
+ | `testEnvironment.init()` | Authenticates eagerly, for a runner hook that wants auth failures reported before any test starts. Optional. |
76
+ | `testEnvironment.buildFrontdoorUrl(returnUrl?)` | A one-time URL that logs a browser in and lands on `returnUrl`. |
77
+ | `testEnvironment.buildExperienceFrontdoorUrl(prefix?, ret?)` | One-time single-access login URL for Experience Cloud sites. |
78
+ | `testEnvironment.getOrgId()` | Dynamically queries the 15- or 18-character Salesforce Organization ID. |
79
+ | `testEnvironment.getUserIdByUsername(username)` | Resolves a target username to its Salesforce User record ID. |
80
+ | `testEnvironment.getNetworkIdByPrefix(prefix?)` | Resolves an Experience site prefix to its corresponding Network ID. |
81
+ | `testEnvironment.buildExperienceUrl(prefix?, path?)` | Constructs a fully qualified secure Experience Cloud site URL. |
82
+ | `getTestEnvironment(options?)` | Retrieves the global singleton `TestEnvironment` instance. |
83
+ | `setTestEnvironment(instance)` | Overrides the global `TestEnvironment` singleton. |
84
+ | `resetTestEnvironment()` | Resets and unsets the global `TestEnvironment` singleton. |
85
+ | `isHostAllowed(host, instanceUrl?, allowedDomains?)` | Validates a hostname against Salesforce default patterns and custom overrides. |
86
+ | `validateAndParseSecureUrl(secureUrl, siteId, validator?)` | Validates and parses a raw secure URL retrieved from SiteDetail. |
87
+ | `DEFAULT_ALLOWED_HOST_PATTERNS` | Default trusted Salesforce domain RegExp matchers. |
88
+ | `USERNAME_ENV` | `'UTAM_USERNAME'`. |
89
+ | `TestEnvironmentOptions`, `EnvLike` | Types for the constructor options and an environment-shaped map. |
90
90
 
91
91
  ### Navigation
92
92
 
@@ -103,7 +103,7 @@ internal.
103
103
  | `navigator.loginAsExperienceUser(username, sitePrefix, pageName)` | Impersonate a user and switch network to an Experience Cloud site. |
104
104
  | `goToLoginUrl`, `goToExperiencePage`, `loginAsUser` | Standalone functional wrappers for navigation methods. |
105
105
  | `goToApplication`, `goToCreateNewRecord`, `goToRecord` | Standalone functional wrappers for record and app navigation. |
106
- | `goToRelatedList`, `resolveBrowser` | Standalone helper to open related list and resolve browser instance. |
106
+ | `goToRelatedList`, `resolveBrowser` | Standalone helper to open related list and resolve browser instance. |
107
107
  | `applicationPath`, `newRecordPath`, `recordPath`, `relatedListPath` | The Lightning paths the methods above open, for a caller building its own URLs. |
108
108
  | `lightningAppName(app)` | The namespacing rule: `MyApp` becomes `c__MyApp`, a namespaced name is unchanged. |
109
109
  | `NavigableBrowser`, `FrontdoorUrlSource`, `LightningNavigatorOptions` | Structural types: anything with `navigateTo(url)`, anything with `buildFrontdoorUrl(returnUrl?)`. |
@@ -119,70 +119,83 @@ internal.
119
119
 
120
120
  ### Discovery
121
121
 
122
- | Export | Description |
123
- | ------------------------------------------------- | ------------------------------------------------------------------------------------- |
124
- | `discoverProject(rootDir?)` | Discovers `sfdx-project.json`, package directories, namespaces, and LWC components. |
125
- | `findLwcDirectories(dirPath)` | Recursively locates directories named `lwc`. |
126
- | `discoverComponentsInPackageDir(pkgDir, rootDir)` | Finds all LWC components and metadata inside a given package directory. |
122
+ | Export | Description |
123
+ | ------------------------------------------------- | ----------------------------------------------------------------------------------- |
124
+ | `discoverProject(rootDir?)` | Discovers `sfdx-project.json`, package directories, namespaces, and LWC components. |
125
+ | `findLwcDirectories(dirPath)` | Recursively locates directories named `lwc`. |
126
+ | `discoverComponentsInPackageDir(pkgDir, rootDir)` | Finds all LWC components and metadata inside a given package directory. |
127
+
128
+ ### `.forceignore` Management
129
+
130
+ | Export | Description |
131
+ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
132
+ | `ensureForceignore(options?)` | Adds missing UTAM rules to a project's `.forceignore`, creating it when `sfdx-project.json` exists. |
133
+ | `mergeForceignore(content, options?)` | Pure merge of missing rules into `.forceignore` content; never changes an existing line. |
134
+ | `resolveUtamTestIgnoreRules(testDirs, packageDirs)` | Rules for UTAM test folders that sit inside a package directory, relative to the project root. |
135
+ | `SIMPLY_UTAM_FORCEIGNORE_RULES` | The rules for UTAM artifacts in LWC bundles, with the existing patterns accepted as covering each. |
136
+ | `FORCEIGNORE_HEADER`, `FORCEIGNORE_FILE` | The `# Ignore UTAM` comment that heads our rules, and the `.forceignore` file name. |
137
+ | `DEFAULT_FORCEIGNORE_REGION` | Default `# -- START CUSTOMIZATION` / `# -- END CUSTOMIZATION` region markers. |
138
+ | `ForceignoreRule`, `ForceignoreResult`, `ForceignorePlacement` | Types: a rule, what happened to the file, and where rules were written. |
139
+ | `MergeForceignoreOptions`, `MergeForceignoreResult`, `EnsureForceignoreOptions` | Option and result types for the functions above. |
127
140
 
128
141
  ### Rules Generation
129
142
 
130
- | Export | Description |
131
- | -------------------------------------------- | ------------------------------------------------------------------------------------- |
132
- | `generateLwcRules(options?)` | Scans LWC components and generates or updates `<component>.rules.json` files. |
133
- | `convertLwcNameToHtml(componentName, ns?)` | Converts component name to kebab-case HTML tag with namespace prefix. |
134
- | `getTargetsFromMeta(xmlContent)` | Extracts targets from `<targets>` in a `*.js-meta.xml` file. |
135
- | `ROOT_TARGETS` | Target page names that designate an LWC as a root component. |
143
+ | Export | Description |
144
+ | ------------------------------------------ | ----------------------------------------------------------------------------- |
145
+ | `generateLwcRules(options?)` | Scans LWC components and generates or updates `<component>.rules.json` files. |
146
+ | `convertLwcNameToHtml(componentName, ns?)` | Converts component name to kebab-case HTML tag with namespace prefix. |
147
+ | `getTargetsFromMeta(xmlContent)` | Extracts targets from `<targets>` in a `*.js-meta.xml` file. |
148
+ | `ROOT_TARGETS` | Target page names that designate an LWC as a root component. |
136
149
 
137
150
  ### Overrides Merger
138
151
 
139
- | Export | Description |
140
- | -------------------------------------------- | ------------------------------------------------------------------------------------- |
141
- | `applyUtamOverrides(options?)` | Deep merges `*.utam-overrides.json` definitions into generated `*.utam.json` files. |
142
- | `findUtamOverridesFiles(dirPath)` | Locates all `*.utam-overrides.json` files in a directory tree. |
143
- | `detectIndentation(content)` | Detects indentation formatting of a JSON file (2 spaces, 4 spaces, or tabs). |
144
- | `mergeElements(target, source)` | Deep merges override properties into a target AST node. |
145
- | `walkElements(node, callback)` | Traverses AST nodes across root elements, nested elements, and shadow DOM roots. |
152
+ | Export | Description |
153
+ | --------------------------------- | ----------------------------------------------------------------------------------- |
154
+ | `applyUtamOverrides(options?)` | Deep merges `*.utam-overrides.json` definitions into generated `*.utam.json` files. |
155
+ | `findUtamOverridesFiles(dirPath)` | Locates all `*.utam-overrides.json` files in a directory tree. |
156
+ | `detectIndentation(content)` | Detects indentation formatting of a JSON file (2 spaces, 4 spaces, or tabs). |
157
+ | `mergeElements(target, source)` | Deep merges override properties into a target AST node. |
158
+ | `walkElements(node, callback)` | Traverses AST nodes across root elements, nested elements, and shadow DOM roots. |
146
159
 
147
160
  ### Namespace Rewriting
148
161
 
149
- | Export | Description |
150
- | -------------------------------------------- | ------------------------------------------------------------------------------------- |
151
- | `rewriteUtamNamespaces(options?)` | Rewrites namespace prefixes across `*.utam.json` files according to mapping config. |
152
- | `findUtamJsonFiles(dirPath)` | Locates all `*.utam.json` schema files in a directory tree. |
153
- | `updateValueWithMappings(value, map, list)` | Replaces namespace prefixes in AST values based on longest-match sorting. |
162
+ | Export | Description |
163
+ | ------------------------------------------- | ----------------------------------------------------------------------------------- |
164
+ | `rewriteUtamNamespaces(options?)` | Rewrites namespace prefixes across `*.utam.json` files according to mapping config. |
165
+ | `findUtamJsonFiles(dirPath)` | Locates all `*.utam.json` schema files in a directory tree. |
166
+ | `updateValueWithMappings(value, map, list)` | Replaces namespace prefixes in AST values based on longest-match sorting. |
154
167
 
155
168
  ### Step Scaffolding Engine
156
169
 
157
- | Export | Description |
158
- | -------------------------------------------- | ------------------------------------------------------------------------------------- |
159
- | `generateCucumberSteps(options?)` | Scans Gherkin features, compiles existing step expressions, and scaffolds skeletons. |
160
- | `parseGherkinDocument(content)` | Parses Gherkin source text into an AST document representation. |
161
- | `extractStepsFromGherkin(content, path?)` | Extracts all scenario and background steps, normalizing And/But keywords. |
162
- | `extractStepExpressionsFromContent(content)` | Statically extracts registered step expressions from definition code. |
163
- | `compileStepExpressions(raw, registry?)` | Compiles string and RegExp expressions using `@cucumber/cucumber-expressions`. |
164
- | `matchStepAgainstExpressions(stepText, list)`| Matches a feature step text against compiled expressions. |
165
- | `generateStepSnippet(step, registry?)` | Generates an idiomatic async step snippet with Cucumber expressions. |
166
- | `formatParameterNames(names, table?, doc?)` | Formats parameter names to eliminate collisions and add dataTable/docString. |
167
- | `formatCode(code)` | Formats generated TypeScript / JavaScript code using Prettier. |
168
- | `resolveGlobs(patterns, rootDir)` | Resolves one or more glob patterns or file paths. |
170
+ | Export | Description |
171
+ | --------------------------------------------- | ------------------------------------------------------------------------------------ |
172
+ | `generateCucumberSteps(options?)` | Scans Gherkin features, compiles existing step expressions, and scaffolds skeletons. |
173
+ | `parseGherkinDocument(content)` | Parses Gherkin source text into an AST document representation. |
174
+ | `extractStepsFromGherkin(content, path?)` | Extracts all scenario and background steps, normalizing And/But keywords. |
175
+ | `extractStepExpressionsFromContent(content)` | Statically extracts registered step expressions from definition code. |
176
+ | `compileStepExpressions(raw, registry?)` | Compiles string and RegExp expressions using `@cucumber/cucumber-expressions`. |
177
+ | `matchStepAgainstExpressions(stepText, list)` | Matches a feature step text against compiled expressions. |
178
+ | `generateStepSnippet(step, registry?)` | Generates an idiomatic async step snippet with Cucumber expressions. |
179
+ | `formatParameterNames(names, table?, doc?)` | Formats parameter names to eliminate collisions and add dataTable/docString. |
180
+ | `formatCode(code)` | Formats generated TypeScript / JavaScript code using Prettier. |
181
+ | `resolveGlobs(patterns, rootDir)` | Resolves one or more glob patterns or file paths. |
169
182
 
170
183
  ### Project Scaffolding
171
184
 
172
- | Export | Description |
173
- | -------------------------------------------- | ------------------------------------------------------------------------------------- |
174
- | `scaffoldProject(options?)` | Scaffolds configuration files, template files, and injects Wireit tasks into package. |
175
- | `injectWireitConfiguration(packageJson, dir)`| Injects standard UTAM Wireit scripts and tasks non-destructively into package.json. |
176
- | `checkMissingDependencies(pkg, required?)` | Detects missing recommended devDependencies. |
177
- | `loadTemplate(name, dir?, tokens?)` | Loads an external scaffold template, performing `{{token}}` replacements. |
178
- | `generateGeneratorConfig(sourceDir, appName)`| Generates parsed `generator.config.json` content. |
179
- | `generateUtamConfig(templatesDir?)` | Generates parsed `utam.config.json` content. |
180
- | `generateWdioConfig(sourceDir, dir?)` | Generates formatted `wdio.conf.mjs` content. |
181
- | `generateNamespaceMap(appName, dir?)` | Generates parsed `namespace-map.json` content. |
182
- | `generateHelloFeature(dir?)` | Generates formatted `hello.feature` starter smoke test content. |
183
- | `generateHelloSteps(dir?)` | Generates formatted `hello.steps.mjs` starter step definition content. |
184
- | `DEFAULT_TEMPLATES_DIR` | Path to starter config templates directory. |
185
- | `DEFAULT_REQUIRED_DEV_DEPENDENCIES` | List of standard recommended UTAM devDependencies. |
185
+ | Export | Description |
186
+ | --------------------------------------------- | -------------------------------------------------------------------------------------- |
187
+ | `scaffoldProject(options?)` | Scaffolds configuration files, template files, Wireit tasks, and `.forceignore` rules. |
188
+ | `injectWireitConfiguration(packageJson, dir)` | Injects standard UTAM Wireit scripts and tasks non-destructively into package.json. |
189
+ | `checkMissingDependencies(pkg, required?)` | Detects missing recommended devDependencies. |
190
+ | `loadTemplate(name, dir?, tokens?)` | Loads an external scaffold template, performing `{{token}}` replacements. |
191
+ | `generateGeneratorConfig(sourceDir, appName)` | Generates parsed `generator.config.json` content. |
192
+ | `generateUtamConfig(templatesDir?)` | Generates parsed `utam.config.json` content. |
193
+ | `generateWdioConfig(sourceDir, dir?)` | Generates formatted `wdio.conf.mjs` content. |
194
+ | `generateNamespaceMap(appName, dir?)` | Generates parsed `namespace-map.json` content. |
195
+ | `generateHelloFeature(dir?)` | Generates formatted `hello.feature` starter smoke test content. |
196
+ | `generateHelloSteps(dir?)` | Generates formatted `hello.steps.mjs` starter step definition content. |
197
+ | `DEFAULT_TEMPLATES_DIR` | Path to starter config templates directory. |
198
+ | `DEFAULT_REQUIRED_DEV_DEPENDENCIES` | List of standard recommended UTAM devDependencies. |
186
199
 
187
200
  WebdriverIO and UTAM are not dependencies: the browser and UTAM objects are typed structurally, so
188
201
  the package works with whichever versions your test project already uses.
@@ -15,6 +15,7 @@
15
15
  */
16
16
  import fs from 'node:fs';
17
17
  import path from 'node:path';
18
+ import { parseSfdxProject } from './sfdx-project.js';
18
19
  /**
19
20
  * Recursively locates all folders named 'lwc' inside the specified directory.
20
21
  *
@@ -93,46 +94,6 @@ export function discoverComponentsInPackageDir(packageDirPath, rootDir) {
93
94
  }
94
95
  return components;
95
96
  }
96
- function parseSfdxProject(resolvedRoot) {
97
- let sfdxProjectFile = null;
98
- let namespace = null;
99
- const packageDirectories = [];
100
- let defaultPackageDirectory = null;
101
- const candidate = path.join(resolvedRoot, 'sfdx-project.json');
102
- if (fs.existsSync(candidate)) {
103
- sfdxProjectFile = candidate;
104
- try {
105
- const parsed = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
106
- if (typeof parsed.namespace === 'string' && parsed.namespace.trim()) {
107
- namespace = parsed.namespace.trim();
108
- }
109
- if (Array.isArray(parsed.packageDirectories)) {
110
- for (const pkgDir of parsed.packageDirectories) {
111
- if (typeof pkgDir?.path === 'string') {
112
- packageDirectories.push(pkgDir.path);
113
- if (pkgDir.default === true && !defaultPackageDirectory) {
114
- defaultPackageDirectory = pkgDir.path;
115
- }
116
- }
117
- }
118
- }
119
- }
120
- catch {
121
- // Continue with empty defaults on JSON read error
122
- }
123
- }
124
- if (packageDirectories.length === 0) {
125
- for (const fallback of ['force-app', 'sfdx-source', 'src']) {
126
- if (fs.existsSync(path.join(resolvedRoot, fallback))) {
127
- packageDirectories.push(fallback);
128
- }
129
- }
130
- }
131
- if (!defaultPackageDirectory && packageDirectories.length > 0) {
132
- defaultPackageDirectory = packageDirectories[0];
133
- }
134
- return { sfdxProjectFile, namespace, packageDirectories, defaultPackageDirectory };
135
- }
136
97
  function parsePackageJson(resolvedRoot) {
137
98
  let packageJsonFile = null;
138
99
  let packageName = null;
@@ -1 +1 @@
1
- {"version":3,"file":"project-discovery.js","sourceRoot":"","sources":["../../src/discovery/project-discovery.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"project-discovery.js","sourceRoot":"","sources":["../../src/discovery/project-discovery.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,14 @@
1
+ export interface SfdxProjectDetails {
2
+ sfdxProjectFile: string | null;
3
+ namespace: string | null;
4
+ packageDirectories: string[];
5
+ defaultPackageDirectory: string | null;
6
+ }
7
+ /**
8
+ * Reads sfdx-project.json without scanning any source folders. Internal: not re-exported from the
9
+ * discovery barrel, so it isn't part of the public API.
10
+ *
11
+ * @param resolvedRoot - Absolute project root.
12
+ * @returns The sfdx-project.json path, namespace, and package directories.
13
+ */
14
+ export declare function parseSfdxProject(resolvedRoot: string): SfdxProjectDetails;
@@ -0,0 +1,65 @@
1
+ /*
2
+ * Copyright (c) 2026, SimplySF.
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ */
16
+ import fs from 'node:fs';
17
+ import path from 'node:path';
18
+ /**
19
+ * Reads sfdx-project.json without scanning any source folders. Internal: not re-exported from the
20
+ * discovery barrel, so it isn't part of the public API.
21
+ *
22
+ * @param resolvedRoot - Absolute project root.
23
+ * @returns The sfdx-project.json path, namespace, and package directories.
24
+ */
25
+ export function parseSfdxProject(resolvedRoot) {
26
+ let sfdxProjectFile = null;
27
+ let namespace = null;
28
+ const packageDirectories = [];
29
+ let defaultPackageDirectory = null;
30
+ const candidate = path.join(resolvedRoot, 'sfdx-project.json');
31
+ if (fs.existsSync(candidate)) {
32
+ sfdxProjectFile = candidate;
33
+ try {
34
+ const parsed = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
35
+ if (typeof parsed.namespace === 'string' && parsed.namespace.trim()) {
36
+ namespace = parsed.namespace.trim();
37
+ }
38
+ if (Array.isArray(parsed.packageDirectories)) {
39
+ for (const pkgDir of parsed.packageDirectories) {
40
+ if (typeof pkgDir?.path === 'string') {
41
+ packageDirectories.push(pkgDir.path);
42
+ if (pkgDir.default === true && !defaultPackageDirectory) {
43
+ defaultPackageDirectory = pkgDir.path;
44
+ }
45
+ }
46
+ }
47
+ }
48
+ }
49
+ catch {
50
+ // Continue with empty defaults on JSON read error
51
+ }
52
+ }
53
+ if (packageDirectories.length === 0) {
54
+ for (const fallback of ['force-app', 'sfdx-source', 'src']) {
55
+ if (fs.existsSync(path.join(resolvedRoot, fallback))) {
56
+ packageDirectories.push(fallback);
57
+ }
58
+ }
59
+ }
60
+ if (!defaultPackageDirectory && packageDirectories.length > 0) {
61
+ defaultPackageDirectory = packageDirectories[0];
62
+ }
63
+ return { sfdxProjectFile, namespace, packageDirectories, defaultPackageDirectory };
64
+ }
65
+ //# sourceMappingURL=sfdx-project.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sfdx-project.js","sourceRoot":"","sources":["../../src/discovery/sfdx-project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAU7B;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,YAAoB;IACnD,IAAI,eAAe,GAAkB,IAAI,CAAC;IAC1C,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,MAAM,kBAAkB,GAAa,EAAE,CAAC;IACxC,IAAI,uBAAuB,GAAkB,IAAI,CAAC;IAElD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;IAC/D,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7B,eAAe,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAsB,CAAC;YACpF,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;gBACpE,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YACtC,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,EAAE,CAAC;gBAC7C,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,kBAAkB,EAAE,CAAC;oBAC/C,IAAI,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;wBACrC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;wBACrC,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,uBAAuB,EAAE,CAAC;4BACxD,uBAAuB,GAAG,MAAM,CAAC,IAAI,CAAC;wBACxC,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,kDAAkD;QACpD,CAAC;IACH,CAAC;IAED,IAAI,kBAAkB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,KAAK,MAAM,QAAQ,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC;YAC3D,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;gBACrD,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC,uBAAuB,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,uBAAuB,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,CAAC;AACrF,CAAC"}
@@ -0,0 +1,145 @@
1
+ /**
2
+ * File name of the Salesforce ignore file, relative to the project root.
3
+ */
4
+ export declare const FORCEIGNORE_FILE = ".forceignore";
5
+ /**
6
+ * Comment line that heads the UTAM rules in a .forceignore file. It has no closing marker.
7
+ */
8
+ export declare const FORCEIGNORE_HEADER = "# Ignore UTAM";
9
+ /**
10
+ * Default markers of a project's customization region in .forceignore.
11
+ */
12
+ export declare const DEFAULT_FORCEIGNORE_REGION: {
13
+ readonly start: "# -- START CUSTOMIZATION";
14
+ readonly end: "# -- END CUSTOMIZATION";
15
+ };
16
+ /**
17
+ * A required .forceignore rule, and the existing patterns accepted as already covering it.
18
+ */
19
+ export interface ForceignoreRule {
20
+ /**
21
+ * The pattern written when the rule is missing.
22
+ */
23
+ pattern: string;
24
+ /**
25
+ * Other patterns that, when present as an active line, count as covering the rule.
26
+ */
27
+ alternatives: string[];
28
+ }
29
+ /**
30
+ * Rules that keep UTAM artifacts written inside LWC bundles out of Salesforce deploys.
31
+ */
32
+ export declare const SIMPLY_UTAM_FORCEIGNORE_RULES: readonly ForceignoreRule[];
33
+ /**
34
+ * Options for merging UTAM rules into .forceignore content.
35
+ */
36
+ export interface MergeForceignoreOptions {
37
+ /**
38
+ * Rules that must be present. Defaults to SIMPLY_UTAM_FORCEIGNORE_RULES.
39
+ */
40
+ rules?: readonly ForceignoreRule[];
41
+ /**
42
+ * Exact line that starts the customization region. Defaults to DEFAULT_FORCEIGNORE_REGION.start.
43
+ */
44
+ regionStart?: string;
45
+ /**
46
+ * Exact line that ends the customization region. Defaults to DEFAULT_FORCEIGNORE_REGION.end.
47
+ */
48
+ regionEnd?: string;
49
+ }
50
+ /**
51
+ * Where missing rules were written: an existing `# Ignore UTAM` block, the customization region, or
52
+ * the end of the file.
53
+ */
54
+ export type ForceignorePlacement = 'block' | 'region' | 'end';
55
+ /**
56
+ * Outcome of merging UTAM rules into .forceignore content.
57
+ */
58
+ export interface MergeForceignoreResult {
59
+ /**
60
+ * The resulting content. Equal to the input when action is 'unchanged'.
61
+ */
62
+ content: string;
63
+ /**
64
+ * 'appended' added rules to an existing block, 'inserted' added a new block, and 'unchanged' found
65
+ * every rule already covered.
66
+ */
67
+ action: 'appended' | 'inserted' | 'unchanged';
68
+ /**
69
+ * Where missing rules were written, when any were.
70
+ */
71
+ placement?: ForceignorePlacement;
72
+ /**
73
+ * Patterns that were added, in rule order.
74
+ */
75
+ addedPatterns: string[];
76
+ /**
77
+ * Non-fatal problems, such as a malformed customization region.
78
+ */
79
+ warnings: string[];
80
+ }
81
+ /**
82
+ * Options for ensuring a project's .forceignore covers UTAM artifacts.
83
+ */
84
+ export interface EnsureForceignoreOptions extends MergeForceignoreOptions {
85
+ /**
86
+ * Root directory of the consumer project. Defaults to current working directory.
87
+ */
88
+ projectDir?: string;
89
+ /**
90
+ * If true, computes the result without writing to disk.
91
+ */
92
+ dryRun?: boolean;
93
+ }
94
+ /**
95
+ * Outcome of ensuring a project's .forceignore covers UTAM artifacts.
96
+ */
97
+ export interface ForceignoreResult extends Omit<MergeForceignoreResult, 'content' | 'action'> {
98
+ /**
99
+ * Path of the .forceignore file, relative to the project root.
100
+ */
101
+ path: string;
102
+ /**
103
+ * What happened to the file. 'created' wrote a new file, 'skipped' means there is no .forceignore
104
+ * and no sfdx-project.json, and 'failed' means the file could not be read or written (the reason is
105
+ * in warnings).
106
+ */
107
+ action: 'created' | 'appended' | 'inserted' | 'unchanged' | 'skipped' | 'failed';
108
+ }
109
+ /**
110
+ * Merges missing UTAM rules into .forceignore content without changing any existing line.
111
+ *
112
+ * Missing rules are added under the first `# Ignore UTAM` comment if one exists. Otherwise a new
113
+ * `# Ignore UTAM` block is inserted above the customization region's end marker, or appended at the
114
+ * end of the content when there is no valid region.
115
+ *
116
+ * @param content - The current .forceignore content. An empty string for a new file.
117
+ * @param options - Rules and customization region markers.
118
+ * @returns The merged content and a description of what changed.
119
+ */
120
+ export declare function mergeForceignore(content: string, options?: MergeForceignoreOptions): MergeForceignoreResult;
121
+ /**
122
+ * Builds .forceignore rules for UTAM test folders that sit inside a Salesforce package directory.
123
+ *
124
+ * Each rule is the folder's path relative to the project root, with forward slashes and a trailing
125
+ * slash, so it matches only that folder. Characters .forceignore treats as special are escaped, so a
126
+ * folder such as `force-app[1]` is matched literally. Folders outside every package directory are never deployed
127
+ * and get no rule, and absolute paths or paths outside the project root get no rule because a
128
+ * .forceignore pattern can't reach them.
129
+ *
130
+ * @param testDirs - Test folders, relative to the project root.
131
+ * @param packageDirectories - Package directories from sfdx-project.json, relative to the project root.
132
+ * @returns One rule per test folder that needs one, without duplicates.
133
+ */
134
+ export declare function resolveUtamTestIgnoreRules(testDirs: string[], packageDirectories: string[]): ForceignoreRule[];
135
+ /**
136
+ * Ensures a project's .forceignore covers UTAM artifacts, adding only the missing rules.
137
+ *
138
+ * Creates the file when it is missing and the project has an sfdx-project.json. Existing lines are
139
+ * never removed, rewritten, or reordered. A read or write error is reported as a 'failed' result
140
+ * rather than thrown, so a problem with a file the project owns doesn't abort the caller.
141
+ *
142
+ * @param options - Project directory, rules, region markers, and dry-run flag.
143
+ * @returns What happened to the file.
144
+ */
145
+ export declare function ensureForceignore(options?: EnsureForceignoreOptions): ForceignoreResult;