@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.
@@ -0,0 +1,291 @@
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 * as fs from 'node:fs';
17
+ import * as path from 'node:path';
18
+ import { isAbsoluteOnAnyPlatform, toPosixRelative } from '../path-utils.js';
19
+ /**
20
+ * File name of the Salesforce ignore file, relative to the project root.
21
+ */
22
+ export const FORCEIGNORE_FILE = '.forceignore';
23
+ /**
24
+ * Comment line that heads the UTAM rules in a .forceignore file. It has no closing marker.
25
+ */
26
+ export const FORCEIGNORE_HEADER = '# Ignore UTAM';
27
+ /**
28
+ * Default markers of a project's customization region in .forceignore.
29
+ */
30
+ export const DEFAULT_FORCEIGNORE_REGION = {
31
+ start: '# -- START CUSTOMIZATION',
32
+ end: '# -- END CUSTOMIZATION',
33
+ };
34
+ /**
35
+ * Rules that keep UTAM artifacts written inside LWC bundles out of Salesforce deploys.
36
+ */
37
+ export const SIMPLY_UTAM_FORCEIGNORE_RULES = [
38
+ { pattern: '**/__utam__/**', alternatives: ['**/__utam__/', '**/__utam__', '__utam__/', '__utam__'] },
39
+ { pattern: '**/lwc/**/*.rules.json', alternatives: ['**/*.rules.json', '*.rules.json'] },
40
+ { pattern: '**/*.utam-overrides.json', alternatives: ['*.utam-overrides.json'] },
41
+ ];
42
+ const BYTE_ORDER_MARK = String.fromCharCode(0xfeff);
43
+ function splitLines(body) {
44
+ const lines = [];
45
+ let index = 0;
46
+ while (index < body.length) {
47
+ const newline = body.indexOf('\n', index);
48
+ if (newline === -1) {
49
+ lines.push({ text: body.slice(index), eol: '' });
50
+ break;
51
+ }
52
+ const raw = body.slice(index, newline);
53
+ lines.push(raw.endsWith('\r') ? { text: raw.slice(0, -1), eol: '\r\n' } : { text: raw, eol: '\n' });
54
+ index = newline + 1;
55
+ }
56
+ return lines;
57
+ }
58
+ function isActivePattern(text) {
59
+ const trimmed = text.trim();
60
+ return trimmed !== '' && !trimmed.startsWith('#') && !trimmed.startsWith('!');
61
+ }
62
+ function isBlockLine(text) {
63
+ const trimmed = text.trim();
64
+ return trimmed !== '' && !trimmed.startsWith('#');
65
+ }
66
+ function findMarker(lines, marker) {
67
+ return lines.flatMap((line, index) => (line.text.trim() === marker ? [index] : []));
68
+ }
69
+ function findBlockEnd(lines, headerIndex) {
70
+ let end = headerIndex + 1;
71
+ while (end < lines.length && isBlockLine(lines[end].text)) {
72
+ end++;
73
+ }
74
+ return end;
75
+ }
76
+ /**
77
+ * Finds the index of the region's end marker, or a warning when the region is malformed.
78
+ */
79
+ function findRegionEnd(lines, regionStart, regionEnd) {
80
+ if (!regionStart || !regionEnd) {
81
+ // An empty marker would match every blank line.
82
+ return {
83
+ warning: `A customization region marker is empty, so UTAM rules were added at the end of ${FORCEIGNORE_FILE}.`,
84
+ };
85
+ }
86
+ const starts = findMarker(lines, regionStart);
87
+ const ends = findMarker(lines, regionEnd);
88
+ if (starts.length === 0 && ends.length === 0) {
89
+ return {};
90
+ }
91
+ if (starts.length === 1 && ends.length === 1 && starts[0] < ends[0]) {
92
+ return { index: ends[0] };
93
+ }
94
+ return {
95
+ warning: `The customization region ('${regionStart}' … '${regionEnd}') is malformed, so UTAM rules were added at the end of ${FORCEIGNORE_FILE}.`,
96
+ };
97
+ }
98
+ /**
99
+ * Picks the line ending for inserted lines: the one used by the line they follow, or else the one most
100
+ * lines in the file use.
101
+ */
102
+ function pickEol(lines, insertAt) {
103
+ const previous = insertAt > 0 ? lines[insertAt - 1].eol : '';
104
+ if (previous) {
105
+ return previous;
106
+ }
107
+ const crlf = lines.filter((line) => line.eol === '\r\n').length;
108
+ const lf = lines.filter((line) => line.eol === '\n').length;
109
+ return crlf > lf ? '\r\n' : '\n';
110
+ }
111
+ function needsSeparator(lines, index) {
112
+ return index > 0 && lines[index - 1].text.trim() !== '';
113
+ }
114
+ /**
115
+ * Merges missing UTAM rules into .forceignore content without changing any existing line.
116
+ *
117
+ * Missing rules are added under the first `# Ignore UTAM` comment if one exists. Otherwise a new
118
+ * `# Ignore UTAM` block is inserted above the customization region's end marker, or appended at the
119
+ * end of the content when there is no valid region.
120
+ *
121
+ * @param content - The current .forceignore content. An empty string for a new file.
122
+ * @param options - Rules and customization region markers.
123
+ * @returns The merged content and a description of what changed.
124
+ */
125
+ export function mergeForceignore(content, options) {
126
+ const rules = options?.rules ?? SIMPLY_UTAM_FORCEIGNORE_RULES;
127
+ const regionStart = (options?.regionStart ?? DEFAULT_FORCEIGNORE_REGION.start).trim();
128
+ const regionEnd = (options?.regionEnd ?? DEFAULT_FORCEIGNORE_REGION.end).trim();
129
+ const bom = content.startsWith(BYTE_ORDER_MARK) ? BYTE_ORDER_MARK : '';
130
+ const body = content.slice(bom.length);
131
+ const lines = splitLines(body);
132
+ const active = new Set(lines.filter((line) => isActivePattern(line.text)).map((line) => line.text.trim()));
133
+ const addedPatterns = rules
134
+ .filter((rule) => ![rule.pattern, ...rule.alternatives].some((pattern) => active.has(pattern)))
135
+ .map((rule) => rule.pattern);
136
+ if (addedPatterns.length === 0) {
137
+ return { content, action: 'unchanged', addedPatterns, warnings: [] };
138
+ }
139
+ const warnings = [];
140
+ let insertAt;
141
+ let newLines;
142
+ let placement;
143
+ const headerIndex = lines.findIndex((line) => line.text.trim() === FORCEIGNORE_HEADER);
144
+ if (headerIndex === -1) {
145
+ const region = findRegionEnd(lines, regionStart, regionEnd);
146
+ if (region.warning) {
147
+ warnings.push(region.warning);
148
+ }
149
+ placement = region.index === undefined ? 'end' : 'region';
150
+ insertAt = region.index ?? lines.length;
151
+ newLines = [...(needsSeparator(lines, insertAt) ? [''] : []), FORCEIGNORE_HEADER, ...addedPatterns];
152
+ }
153
+ else {
154
+ placement = 'block';
155
+ insertAt = findBlockEnd(lines, headerIndex);
156
+ newLines = addedPatterns;
157
+ }
158
+ const eol = pickEol(lines, insertAt);
159
+ if (insertAt > 0 && lines[insertAt - 1].eol === '') {
160
+ lines[insertAt - 1].eol = eol;
161
+ }
162
+ lines.splice(insertAt, 0, ...newLines.map((text) => ({ text, eol })));
163
+ return {
164
+ content: bom + lines.map((line) => line.text + line.eol).join(''),
165
+ action: placement === 'block' ? 'appended' : 'inserted',
166
+ placement,
167
+ addedPatterns,
168
+ warnings,
169
+ };
170
+ }
171
+ /**
172
+ * Escapes the characters that .forceignore would read as wildcards in a literal path: `[`, `]` and `*`.
173
+ * A `?` is left as is: the `ignore` 5.x library that Salesforce's deploy tooling uses can't escape it,
174
+ * and unescaped it still matches the literal character.
175
+ */
176
+ function escapeIgnoreWildcards(literalPath) {
177
+ return literalPath.replace(/[[\]*]/g, '\\$&');
178
+ }
179
+ /**
180
+ * Escapes a literal path for use as a whole .forceignore line: its wildcards, plus a leading `#` (a
181
+ * comment) or `!` (a negation).
182
+ */
183
+ function escapeIgnorePattern(literalPath) {
184
+ return escapeIgnoreWildcards(literalPath).replace(/^[#!]/, '\\$&');
185
+ }
186
+ /**
187
+ * Builds .forceignore rules for UTAM test folders that sit inside a Salesforce package directory.
188
+ *
189
+ * Each rule is the folder's path relative to the project root, with forward slashes and a trailing
190
+ * slash, so it matches only that folder. Characters .forceignore treats as special are escaped, so a
191
+ * folder such as `force-app[1]` is matched literally. Folders outside every package directory are never deployed
192
+ * and get no rule, and absolute paths or paths outside the project root get no rule because a
193
+ * .forceignore pattern can't reach them.
194
+ *
195
+ * @param testDirs - Test folders, relative to the project root.
196
+ * @param packageDirectories - Package directories from sfdx-project.json, relative to the project root.
197
+ * @returns One rule per test folder that needs one, without duplicates.
198
+ */
199
+ export function resolveUtamTestIgnoreRules(testDirs, packageDirectories) {
200
+ const packages = packageDirectories.map(toPosixRelative);
201
+ const rules = [];
202
+ const seen = new Set();
203
+ for (const testDir of testDirs.map(toPosixRelative)) {
204
+ const insidePackage = packages.some((pkg) => pkg === '' || testDir === pkg || testDir.startsWith(`${pkg}/`));
205
+ const outsideProject = isAbsoluteOnAnyPlatform(testDir) || testDir === '..' || testDir.startsWith('../');
206
+ if (!testDir || outsideProject || !insidePackage || seen.has(testDir)) {
207
+ continue;
208
+ }
209
+ seen.add(testDir);
210
+ const literal = escapeIgnorePattern(testDir);
211
+ const rooted = `/${escapeIgnoreWildcards(testDir)}`;
212
+ rules.push({
213
+ pattern: `${literal}/`,
214
+ alternatives: [literal, `${literal}/**`, `${rooted}/`, rooted, `${rooted}/**`],
215
+ });
216
+ }
217
+ return rules;
218
+ }
219
+ /**
220
+ * Replaces a file's content by writing a temporary file next to it and renaming it into place, so an
221
+ * interrupted write can't leave the project's file truncated. A symlink is followed, an existing file's
222
+ * permissions are kept, and a read-only file is refused just as a plain write would refuse it.
223
+ *
224
+ * When that isn't possible (the folder doesn't allow new files, or on Windows another process briefly
225
+ * holds the file), the temporary file is removed and the file is written in place instead. An error
226
+ * from that write is thrown.
227
+ */
228
+ function writeFileSafely(filePath, content) {
229
+ const exists = fs.existsSync(filePath);
230
+ const target = exists ? fs.realpathSync(filePath) : filePath;
231
+ if (exists) {
232
+ // A rename only needs permission on the folder, so check the file itself to respect a read-only
233
+ // .forceignore the same way a plain write would.
234
+ fs.accessSync(target, fs.constants.W_OK);
235
+ }
236
+ const temp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.tmp`);
237
+ try {
238
+ fs.writeFileSync(temp, content, 'utf-8');
239
+ if (exists) {
240
+ fs.chmodSync(temp, fs.statSync(target).mode);
241
+ }
242
+ fs.renameSync(temp, target);
243
+ }
244
+ catch {
245
+ fs.rmSync(temp, { force: true });
246
+ fs.writeFileSync(target, content, 'utf-8');
247
+ }
248
+ }
249
+ /**
250
+ * Ensures a project's .forceignore covers UTAM artifacts, adding only the missing rules.
251
+ *
252
+ * Creates the file when it is missing and the project has an sfdx-project.json. Existing lines are
253
+ * never removed, rewritten, or reordered. A read or write error is reported as a 'failed' result
254
+ * rather than thrown, so a problem with a file the project owns doesn't abort the caller.
255
+ *
256
+ * @param options - Project directory, rules, region markers, and dry-run flag.
257
+ * @returns What happened to the file.
258
+ */
259
+ export function ensureForceignore(options) {
260
+ const projectDir = path.resolve(options?.projectDir ?? process.cwd());
261
+ const filePath = path.join(projectDir, FORCEIGNORE_FILE);
262
+ const exists = fs.existsSync(filePath);
263
+ if (!exists && !fs.existsSync(path.join(projectDir, 'sfdx-project.json'))) {
264
+ return { path: FORCEIGNORE_FILE, action: 'skipped', addedPatterns: [], warnings: [] };
265
+ }
266
+ let merged;
267
+ try {
268
+ merged = mergeForceignore(exists ? fs.readFileSync(filePath, 'utf-8') : '', options);
269
+ if (merged.action !== 'unchanged' && !options?.dryRun) {
270
+ writeFileSafely(filePath, merged.content);
271
+ }
272
+ }
273
+ catch (error) {
274
+ const reason = error instanceof Error ? error.message : String(error);
275
+ return {
276
+ path: FORCEIGNORE_FILE,
277
+ action: 'failed',
278
+ addedPatterns: [],
279
+ warnings: [`Could not update ${FORCEIGNORE_FILE}, so UTAM rules were not added: ${reason}`],
280
+ };
281
+ }
282
+ const action = exists || merged.action === 'unchanged' ? merged.action : 'created';
283
+ return {
284
+ path: FORCEIGNORE_FILE,
285
+ action,
286
+ placement: merged.placement,
287
+ addedPatterns: merged.addedPatterns,
288
+ warnings: merged.warnings,
289
+ };
290
+ }
291
+ //# sourceMappingURL=forceignore-manager.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"forceignore-manager.js","sourceRoot":"","sources":["../../src/forceignore/forceignore-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE5E;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAElD;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,KAAK,EAAE,0BAA0B;IACjC,GAAG,EAAE,wBAAwB;CACrB,CAAC;AAiBX;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAA+B;IACvE,EAAE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,CAAC,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE;IACrG,EAAE,OAAO,EAAE,wBAAwB,EAAE,YAAY,EAAE,CAAC,iBAAiB,EAAE,cAAc,CAAC,EAAE;IACxF,EAAE,OAAO,EAAE,0BAA0B,EAAE,YAAY,EAAE,CAAC,uBAAuB,CAAC,EAAE;CACjF,CAAC;AA2FF,MAAM,eAAe,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;AAOpD,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1C,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;YACjD,MAAM;QACR,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QACpG,KAAK,GAAG,OAAO,GAAG,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO,OAAO,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO,OAAO,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,UAAU,CAAC,KAAa,EAAE,MAAc;IAC/C,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,YAAY,CAAC,KAAa,EAAE,WAAmB;IACtD,IAAI,GAAG,GAAG,WAAW,GAAG,CAAC,CAAC;IAC1B,OAAO,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1D,GAAG,EAAE,CAAC;IACR,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,KAAa,EAAE,WAAmB,EAAE,SAAiB;IAC1E,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,EAAE,CAAC;QAC/B,gDAAgD;QAChD,OAAO;YACL,OAAO,EAAE,kFAAkF,gBAAgB,GAAG;SAC/G,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO;QACL,OAAO,EAAE,8BAA8B,WAAW,QAAQ,SAAS,2DAA2D,gBAAgB,GAAG;KAClJ,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,OAAO,CAAC,KAAa,EAAE,QAAgB;IAC9C,MAAM,QAAQ,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,CAAC,CAAC,MAAM,CAAC;IAChE,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;IAC5D,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACnC,CAAC;AAED,SAAS,cAAc,CAAC,KAAa,EAAE,KAAa;IAClD,OAAO,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,OAAiC;IACjF,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,6BAA6B,CAAC;IAC9D,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,WAAW,IAAI,0BAA0B,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IACtF,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,SAAS,IAAI,0BAA0B,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEhF,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAE/B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3G,MAAM,aAAa,GAAG,KAAK;SACxB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;SAC9F,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE/B,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACvE,CAAC;IAED,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,QAAgB,CAAC;IACrB,IAAI,QAAkB,CAAC;IACvB,IAAI,SAA+B,CAAC;IAEpC,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,kBAAkB,CAAC,CAAC;IACvF,IAAI,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;QAC5D,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QACD,SAAS,GAAG,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC1D,QAAQ,GAAG,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;QACxC,QAAQ,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,kBAAkB,EAAE,GAAG,aAAa,CAAC,CAAC;IACtG,CAAC;SAAM,CAAC;QACN,SAAS,GAAG,OAAO,CAAC;QACpB,QAAQ,GAAG,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAC5C,QAAQ,GAAG,aAAa,CAAC;IAC3B,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrC,IAAI,QAAQ,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,EAAE,EAAE,CAAC;QACnD,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;IAChC,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAEtE,OAAO;QACL,OAAO,EAAE,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACjE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU;QACvD,SAAS;QACT,aAAa;QACb,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,WAAmB;IAChD,OAAO,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,WAAmB;IAC9C,OAAO,qBAAqB,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAkB,EAAE,kBAA4B;IACzF,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACzD,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QACpD,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC;QAC7G,MAAM,cAAc,GAAG,uBAAuB,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACzG,IAAI,CAAC,OAAO,IAAI,cAAc,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACtE,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClB,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,qBAAqB,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,KAAK,CAAC,IAAI,CAAC;YACT,OAAO,EAAE,GAAG,OAAO,GAAG;YACtB,YAAY,EAAE,CAAC,OAAO,EAAE,GAAG,OAAO,KAAK,EAAE,GAAG,MAAM,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC;SAC/E,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,eAAe,CAAC,QAAgB,EAAE,OAAe;IACxD,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC7D,IAAI,MAAM,EAAE,CAAC;QACX,gGAAgG;QAChG,iDAAiD;QACjD,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAC7F,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,MAAM,EAAE,CAAC;YACX,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;QACD,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAkC;IAClE,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAEvC,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC;QAC1E,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACxF,CAAC;IAED,IAAI,MAA8B,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACrF,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YACtD,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO;YACL,IAAI,EAAE,gBAAgB;YACtB,MAAM,EAAE,QAAQ;YAChB,aAAa,EAAE,EAAE;YACjB,QAAQ,EAAE,CAAC,oBAAoB,gBAAgB,mCAAmC,MAAM,EAAE,CAAC;SAC5F,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnF,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,MAAM;QACN,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;AACJ,CAAC"}
@@ -0,0 +1 @@
1
+ export * from './forceignore-manager.js';
@@ -0,0 +1,17 @@
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
+ export * from './forceignore-manager.js';
17
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/forceignore/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,0BAA0B,CAAC"}
package/lib/index.d.ts CHANGED
@@ -3,6 +3,7 @@ export { applicationPath, lightningAppName, newRecordPath, recordPath, relatedLi
3
3
  export { LightningNavigator, goToLoginUrl, goToExperiencePage, loginAsUser, loginAsExperienceUser, goToApplication, goToCreateNewRecord, goToRecord, goToRelatedList, resolveBrowser, type FrontdoorUrlSource, type LightningNavigatorOptions, type NavigableBrowser, } from './navigator.js';
4
4
  export { formatUtamHtml, getUtamHtml, logUtamHtml, type UtamElementLike, type UtamHtml } from './utam-html.js';
5
5
  export { findLwcDirectories, discoverComponentsInPackageDir, discoverProject, type SfdxPackageDirectory, type SfdxProjectConfig, type DiscoveredLwcComponent, type DiscoveredProject, } from './discovery/index.js';
6
+ export { FORCEIGNORE_FILE, FORCEIGNORE_HEADER, DEFAULT_FORCEIGNORE_REGION, SIMPLY_UTAM_FORCEIGNORE_RULES, mergeForceignore, resolveUtamTestIgnoreRules, ensureForceignore, type ForceignoreRule, type ForceignorePlacement, type MergeForceignoreOptions, type MergeForceignoreResult, type EnsureForceignoreOptions, type ForceignoreResult, } from './forceignore/index.js';
6
7
  export { ROOT_TARGETS, convertLwcNameToHtml, getTargetsFromMeta, generateLwcRules, type GenerateRulesOptions, type RuleAction, type GenerateRulesResult, } from './rules/index.js';
7
8
  export { detectIndentation, findUtamOverridesFiles, walkElements, mergeElements, applyUtamOverrides, type ApplyOverridesOptions, type OverrideChange, type FileOverrideResult, type ApplyOverridesResult, type UtamOverrideItem, } from './overrides/index.js';
8
9
  export { findUtamJsonFiles, updateValueWithMappings, rewriteUtamNamespaces, type RewriteNamespacesOptions, type NamespaceReplacement, type FileRewriteResult, type RewriteNamespacesResult, } from './namespaces/index.js';
package/lib/index.js CHANGED
@@ -25,6 +25,7 @@ export { applicationPath, lightningAppName, newRecordPath, recordPath, relatedLi
25
25
  export { LightningNavigator, goToLoginUrl, goToExperiencePage, loginAsUser, loginAsExperienceUser, goToApplication, goToCreateNewRecord, goToRecord, goToRelatedList, resolveBrowser, } from './navigator.js';
26
26
  export { formatUtamHtml, getUtamHtml, logUtamHtml } from './utam-html.js';
27
27
  export { findLwcDirectories, discoverComponentsInPackageDir, discoverProject, } from './discovery/index.js';
28
+ export { FORCEIGNORE_FILE, FORCEIGNORE_HEADER, DEFAULT_FORCEIGNORE_REGION, SIMPLY_UTAM_FORCEIGNORE_RULES, mergeForceignore, resolveUtamTestIgnoreRules, ensureForceignore, } from './forceignore/index.js';
28
29
  export { ROOT_TARGETS, convertLwcNameToHtml, getTargetsFromMeta, generateLwcRules, } from './rules/index.js';
29
30
  export { detectIndentation, findUtamOverridesFiles, walkElements, mergeElements, applyUtamOverrides, } from './overrides/index.js';
30
31
  export { findUtamJsonFiles, updateValueWithMappings, rewriteUtamNamespaces, } from './namespaces/index.js';
package/lib/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gGAAgG;AAChG,+EAA+E;AAC/E,gGAAgG;AAChG,2CAA2C;AAC3C,EAAE;AACF,iGAAiG;AACjG,uFAAuF;AAEvF,OAAO,EACL,eAAe,EACf,YAAY,EACZ,6BAA6B,EAC7B,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAErH,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,cAAc,GAIf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC;AAE/G,OAAO,EACL,kBAAkB,EAClB,8BAA8B,EAC9B,eAAe,GAKhB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,GAIjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,kBAAkB,GAMnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,GAKtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,iCAAiC,EACjC,sBAAsB,EACtB,2BAA2B,EAC3B,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,0BAA0B,EAC1B,qBAAqB,GAQtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,qBAAqB,EACrB,iCAAiC,EACjC,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,eAAe,GAGhB,MAAM,qBAAqB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gGAAgG;AAChG,+EAA+E;AAC/E,gGAAgG;AAChG,2CAA2C;AAC3C,EAAE;AACF,iGAAiG;AACjG,uFAAuF;AAEvF,OAAO,EACL,eAAe,EACf,YAAY,EACZ,6BAA6B,EAC7B,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAErH,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,cAAc,GAIf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC;AAE/G,OAAO,EACL,kBAAkB,EAClB,8BAA8B,EAC9B,eAAe,GAKhB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,EAC1B,6BAA6B,EAC7B,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,GAOlB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,GAIjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,kBAAkB,GAMnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,GAKtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,iCAAiC,EACjC,sBAAsB,EACtB,2BAA2B,EAC3B,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,0BAA0B,EAC1B,qBAAqB,GAQtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,qBAAqB,EACrB,iCAAiC,EACjC,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,eAAe,GAGhB,MAAM,qBAAqB,CAAC"}
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Normalizes a project-relative path for use in .forceignore rules and config templates: forward
3
+ * slashes, no leading './', no trailing slash, and '' for the project root. A leading '../' is kept.
4
+ *
5
+ * @param dir - A path relative to the project root, with either separator.
6
+ * @returns The normalized path.
7
+ */
8
+ export declare function toPosixRelative(dir: string): string;
9
+ /**
10
+ * Whether a path is absolute on either platform, e.g. '/abs', 'D:\\src' or 'D:/src'. On Windows,
11
+ * path.relative returns an absolute path when the two paths are on different drives.
12
+ *
13
+ * @param dir - Any path, with either separator.
14
+ * @returns True if the path is absolute on POSIX or Windows.
15
+ */
16
+ export declare function isAbsoluteOnAnyPlatform(dir: string): boolean;
@@ -0,0 +1,42 @@
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 * as path from 'node:path';
17
+ // Internal helpers. Not exported from src/index.ts, so they aren't part of the public API.
18
+ /**
19
+ * Normalizes a project-relative path for use in .forceignore rules and config templates: forward
20
+ * slashes, no leading './', no trailing slash, and '' for the project root. A leading '../' is kept.
21
+ *
22
+ * @param dir - A path relative to the project root, with either separator.
23
+ * @returns The normalized path.
24
+ */
25
+ export function toPosixRelative(dir) {
26
+ return dir
27
+ .replace(/\\/g, '/')
28
+ .replace(/^(\.\/)+/, '')
29
+ .replace(/\/+$/, '')
30
+ .replace(/^\.$/, '');
31
+ }
32
+ /**
33
+ * Whether a path is absolute on either platform, e.g. '/abs', 'D:\\src' or 'D:/src'. On Windows,
34
+ * path.relative returns an absolute path when the two paths are on different drives.
35
+ *
36
+ * @param dir - Any path, with either separator.
37
+ * @returns True if the path is absolute on POSIX or Windows.
38
+ */
39
+ export function isAbsoluteOnAnyPlatform(dir) {
40
+ return path.posix.isAbsolute(dir) || path.win32.isAbsolute(dir);
41
+ }
42
+ //# sourceMappingURL=path-utils.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,2FAA2F;AAE3F;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,GAAG;SACP,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAClE,CAAC"}
@@ -1,3 +1,4 @@
1
+ import { type ForceignoreResult } from '../forceignore/index.js';
1
2
  /**
2
3
  * Default location of external scaffold template files.
3
4
  * Resolves to the templates directory in @simplysf/simply-utam-core whether in src or lib.
@@ -32,9 +33,22 @@ export interface ScaffoldOptions {
32
33
  */
33
34
  dryRun?: boolean;
34
35
  /**
35
- * If true, forces overwriting of existing config files.
36
+ * If true, forces overwriting of existing config files. Does not affect .forceignore, which is only
37
+ * ever added to.
36
38
  */
37
39
  force?: boolean;
40
+ /**
41
+ * If false, leaves .forceignore untouched. Defaults to true.
42
+ */
43
+ forceignore?: boolean;
44
+ /**
45
+ * Exact line that starts the .forceignore customization region. Defaults to '# -- START CUSTOMIZATION'.
46
+ */
47
+ forceignoreRegionStart?: string;
48
+ /**
49
+ * Exact line that ends the .forceignore customization region. Defaults to '# -- END CUSTOMIZATION'.
50
+ */
51
+ forceignoreRegionEnd?: string;
38
52
  }
39
53
  /**
40
54
  * Result details from executing project scaffolding.
@@ -60,6 +74,10 @@ export interface ScaffoldResult {
60
74
  * List of recommended devDependencies missing from the consumer's package.json.
61
75
  */
62
76
  missingDependencies: string[];
77
+ /**
78
+ * What happened to .forceignore. Absent when the forceignore option is false.
79
+ */
80
+ forceignore?: ForceignoreResult;
63
81
  }
64
82
  /**
65
83
  * Loads an external template file from disk, performing token replacements.
@@ -140,7 +158,8 @@ export declare function injectWireitConfiguration(packageJson: Record<string, un
140
158
  */
141
159
  export declare function checkMissingDependencies(packageJson: Record<string, unknown>, requiredDependencies?: string[]): string[];
142
160
  /**
143
- * Scaffolds standard UTAM configurations, Wireit tasks, and namespace maps in a project directory.
161
+ * Scaffolds standard UTAM configurations, Wireit tasks, and namespace maps in a project directory, and adds
162
+ * the .forceignore rules that keep UTAM artifacts out of Salesforce deploys.
144
163
  *
145
164
  * @param options - Scaffolding options.
146
165
  * @returns Results describing created, skipped, and modified files.