@simplysf/simply-utam-core 0.0.0 → 0.1.0

package/LICENSE.txt

@@ -0,0 +1,206 @@
+Apache License Version 2.0
+
+Copyright (c) 2026, SimplySF.
+All rights reserved.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -2,12 +2,13 @@
 
 [![NPM](https://img.shields.io/npm/v/@simplysf/simply-utam-core?label=@simplysf/simply-utam-core)](https://npmjs.com/@simplysf/simply-utam-core) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://raw.githubusercontent.com/SimplySF/simply-utam/main/LICENSE.txt)
 
-Org authentication, Lightning navigation, and debugging helpers for
+Org authentication, Lightning navigation, UTAM compilation helpers, AST transformations, and debugging helpers for
 [UTAM](https://utam.dev/) UI tests against Salesforce, built by [SimplySF](https://github.com/SimplySF).
 
 It logs the test browser in to an org you have already authorized with the Salesforce CLI — no
 passwords in the test project — and opens Lightning pages directly, so a test starts on the page it
-is about instead of clicking its way there.
+is about instead of clicking its way there. It also provides zero-config build transformations for LWC root rules,
+AST overrides, namespace mapping, and offline Cucumber step scaffolding.
 
 ## Install
 
@@ -64,16 +65,28 @@ browser history, WebDriver logs, or a screenshot of the address bar. The org is
 Everything below is exported from the package root and is semver-covered. Anything not listed is
 internal.
 
-### Org authentication
-
-| Export                                          | Description                                                                                                               |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `TestEnvironment`                               | The org under test. `new TestEnvironment({ username?, env? })` throws when neither a username nor `UTAM_USERNAME` is set. |
-| `testEnvironment.getOrg()`                      | The authenticated `Org`. Authenticates on first call and shares the result; a failure is not cached.                      |
-| `testEnvironment.init()`                        | Authenticates eagerly, for a runner hook that wants auth failures reported before any test starts. Optional.              |
-| `testEnvironment.buildFrontdoorUrl(returnUrl?)` | A one-time URL that logs a browser in and lands on `returnUrl`.                                                           |
-| `USERNAME_ENV`                                  | `'UTAM_USERNAME'`.                                                                                                        |
-| `TestEnvironmentOptions`, `EnvLike`             | Types for the constructor options and an environment-shaped map.                                                          |
+### Org authentication & Environment
+
+| Export                                                        | Description                                                                                                               |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `TestEnvironment`                                             | The org under test. `new TestEnvironment({ username?, env?, allowedDomains? })` throws when neither a username nor `UTAM_USERNAME` is set. |
+| `testEnvironment.getOrg()`                                    | The authenticated `Org`. Authenticates on first call and shares the result; a failure is not cached.                      |
+| `testEnvironment.getConnection()`                             | The underlying `@salesforce/core` Connection.                                                                            |
+| `testEnvironment.init()`                                      | Authenticates eagerly, for a runner hook that wants auth failures reported before any test starts. Optional.              |
+| `testEnvironment.buildFrontdoorUrl(returnUrl?)`               | A one-time URL that logs a browser in and lands on `returnUrl`.                                                           |
+| `testEnvironment.buildExperienceFrontdoorUrl(prefix?, ret?)`  | One-time single-access login URL for Experience Cloud sites.                                                              |
+| `testEnvironment.getOrgId()`                                  | Dynamically queries the 15- or 18-character Salesforce Organization ID.                                                   |
+| `testEnvironment.getUserIdByUsername(username)`               | Resolves a target username to its Salesforce User record ID.                                                             |
+| `testEnvironment.getNetworkIdByPrefix(prefix?)`               | Resolves an Experience site prefix to its corresponding Network ID.                                                      |
+| `testEnvironment.buildExperienceUrl(prefix?, path?)`          | Constructs a fully qualified secure Experience Cloud site URL.                                                            |
+| `getTestEnvironment(options?)`                                | Retrieves the global singleton `TestEnvironment` instance.                                                                |
+| `setTestEnvironment(instance)`                                | Overrides the global `TestEnvironment` singleton.                                                                         |
+| `resetTestEnvironment()`                                      | Resets and unsets the global `TestEnvironment` singleton.                                                                 |
+| `isHostAllowed(host, instanceUrl?, allowedDomains?)`          | Validates a hostname against Salesforce default patterns and custom overrides.                                           |
+| `validateAndParseSecureUrl(secureUrl, siteId, validator?)`    | Validates and parses a raw secure URL retrieved from SiteDetail.                                                          |
+| `DEFAULT_ALLOWED_HOST_PATTERNS`                               | Default trusted Salesforce domain RegExp matchers.                                                                        |
+| `USERNAME_ENV`                                                | `'UTAM_USERNAME'`.                                                                                                        |
+| `TestEnvironmentOptions`, `EnvLike`                           | Types for the constructor options and an environment-shaped map.                                                          |
 
 ### Navigation
 
@@ -85,6 +98,12 @@ internal.
 | `navigator.goToCreateNewRecord(app, objectApiName)`                   | An object's new-record form.                                                                      |
 | `navigator.goToRecord(app, recordId)`                                 | A record's detail page.                                                                           |
 | `navigator.goToRelatedList(app, recordId, relatedListName)`           | One of a record's related lists.                                                                  |
+| `navigator.goToExperiencePage(sitePrefix, pageName)`                  | Log in and navigate directly to an Experience Cloud community page.                               |
+| `navigator.loginAsUser(username, returnUrl?)`                         | Impersonate a user via admin session and redirect to target page.                                 |
+| `navigator.loginAsExperienceUser(username, sitePrefix, pageName)`     | Impersonate a user and switch network to an Experience Cloud site.                                |
+| `goToLoginUrl`, `goToExperiencePage`, `loginAsUser`                   | Standalone functional wrappers for navigation methods.                                            |
+| `goToApplication`, `goToCreateNewRecord`, `goToRecord`                | Standalone functional wrappers for record and app navigation.                                     |
+| `goToRelatedList`, `resolveBrowser`                                   | Standalone helper to open related list and resolve browser instance.                             |
 | `applicationPath`, `newRecordPath`, `recordPath`, `relatedListPath`   | The Lightning paths the methods above open, for a caller building its own URLs.                   |
 | `lightningAppName(app)`                                               | The namespacing rule: `MyApp` becomes `c__MyApp`, a namespaced name is unchanged.                 |
 | `NavigableBrowser`, `FrontdoorUrlSource`, `LightningNavigatorOptions` | Structural types: anything with `navigateTo(url)`, anything with `buildFrontdoorUrl(returnUrl?)`. |
@@ -98,6 +117,73 @@ internal.
 | `formatUtamHtml(utamHtml)`      | The colored block `logUtamHtml` writes.                                               |
 | `UtamElementLike`, `UtamHtml`   | Types: any UTAM page object or element, and what it resolved to.                      |
 
+### Discovery
+
+| Export                                            | Description                                                                           |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `discoverProject(rootDir?)`                       | Discovers `sfdx-project.json`, package directories, namespaces, and LWC components.   |
+| `findLwcDirectories(dirPath)`                     | Recursively locates directories named `lwc`.                                          |
+| `discoverComponentsInPackageDir(pkgDir, rootDir)` | Finds all LWC components and metadata inside a given package directory.               |
+
+### Rules Generation
+
+| Export                                       | Description                                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `generateLwcRules(options?)`                 | Scans LWC components and generates or updates `<component>.rules.json` files.         |
+| `convertLwcNameToHtml(componentName, ns?)`   | Converts component name to kebab-case HTML tag with namespace prefix.                 |
+| `getTargetsFromMeta(xmlContent)`             | Extracts targets from `<targets>` in a `*.js-meta.xml` file.                          |
+| `ROOT_TARGETS`                               | Target page names that designate an LWC as a root component.                          |
+
+### Overrides Merger
+
+| Export                                       | Description                                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `applyUtamOverrides(options?)`               | Deep merges `*.utam-overrides.json` definitions into generated `*.utam.json` files.   |
+| `findUtamOverridesFiles(dirPath)`            | Locates all `*.utam-overrides.json` files in a directory tree.                        |
+| `detectIndentation(content)`                 | Detects indentation formatting of a JSON file (2 spaces, 4 spaces, or tabs).          |
+| `mergeElements(target, source)`              | Deep merges override properties into a target AST node.                               |
+| `walkElements(node, callback)`               | Traverses AST nodes across root elements, nested elements, and shadow DOM roots.      |
+
+### Namespace Rewriting
+
+| Export                                       | Description                                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `rewriteUtamNamespaces(options?)`            | Rewrites namespace prefixes across `*.utam.json` files according to mapping config.   |
+| `findUtamJsonFiles(dirPath)`                 | Locates all `*.utam.json` schema files in a directory tree.                           |
+| `updateValueWithMappings(value, map, list)`  | Replaces namespace prefixes in AST values based on longest-match sorting.             |
+
+### Step Scaffolding Engine
+
+| Export                                       | Description                                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `generateCucumberSteps(options?)`            | Scans Gherkin features, compiles existing step expressions, and scaffolds skeletons.  |
+| `parseGherkinDocument(content)`              | Parses Gherkin source text into an AST document representation.                       |
+| `extractStepsFromGherkin(content, path?)`    | Extracts all scenario and background steps, normalizing And/But keywords.             |
+| `extractStepExpressionsFromContent(content)` | Statically extracts registered step expressions from definition code.                 |
+| `compileStepExpressions(raw, registry?)`     | Compiles string and RegExp expressions using `@cucumber/cucumber-expressions`.        |
+| `matchStepAgainstExpressions(stepText, list)`| Matches a feature step text against compiled expressions.                             |
+| `generateStepSnippet(step, registry?)`       | Generates an idiomatic async step snippet with Cucumber expressions.                  |
+| `formatParameterNames(names, table?, doc?)`  | Formats parameter names to eliminate collisions and add dataTable/docString.          |
+| `formatCode(code)`                           | Formats generated TypeScript / JavaScript code using Prettier.                        |
+| `resolveGlobs(patterns, rootDir)`            | Resolves one or more glob patterns or file paths.                                     |
+
+### Project Scaffolding
+
+| Export                                       | Description                                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `scaffoldProject(options?)`                  | Scaffolds configuration files, template files, and injects Wireit tasks into package. |
+| `injectWireitConfiguration(packageJson, dir)`| Injects standard UTAM Wireit scripts and tasks non-destructively into package.json.   |
+| `checkMissingDependencies(pkg, required?)`   | Detects missing recommended devDependencies.                                          |
+| `loadTemplate(name, dir?, tokens?)`          | Loads an external scaffold template, performing `{{token}}` replacements.             |
+| `generateGeneratorConfig(sourceDir, appName)`| Generates parsed `generator.config.json` content.                                     |
+| `generateUtamConfig(templatesDir?)`          | Generates parsed `utam.config.json` content.                                          |
+| `generateWdioConfig(sourceDir, dir?)`        | Generates formatted `wdio.conf.mjs` content.                                          |
+| `generateNamespaceMap(appName, dir?)`        | Generates parsed `namespace-map.json` content.                                        |
+| `generateHelloFeature(dir?)`                 | Generates formatted `hello.feature` starter smoke test content.                       |
+| `generateHelloSteps(dir?)`                   | Generates formatted `hello.steps.mjs` starter step definition content.                |
+| `DEFAULT_TEMPLATES_DIR`                      | Path to starter config templates directory.                                           |
+| `DEFAULT_REQUIRED_DEV_DEPENDENCIES`          | List of standard recommended UTAM devDependencies.                                    |
+
 WebdriverIO and UTAM are not dependencies: the browser and UTAM objects are typed structurally, so
 the package works with whichever versions your test project already uses.
 

package/lib/discovery/index.d.ts

@@ -0,0 +1 @@
+export * from './project-discovery.js';

package/lib/discovery/index.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './project-discovery.js';
+//# sourceMappingURL=index.js.map

package/lib/discovery/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,wBAAwB,CAAC"}

package/lib/discovery/project-discovery.d.ts

@@ -0,0 +1,55 @@
+export interface SfdxPackageDirectory {
+    [key: string]: unknown;
+    default?: boolean;
+    package?: string;
+    path: string;
+    versionName?: string;
+    versionNumber?: string;
+}
+export interface SfdxProjectConfig {
+    [key: string]: unknown;
+    namespace?: string;
+    packageDirectories: SfdxPackageDirectory[];
+    sfdcLoginUrl?: string;
+    sourceApiVersion?: string;
+}
+export interface DiscoveredLwcComponent {
+    name: string;
+    directory: string;
+    packageDirectory: string;
+    metaFile: string | null;
+    hasMetaFile: boolean;
+}
+export interface DiscoveredProject {
+    rootDir: string;
+    sfdxProjectFile: string | null;
+    packageJsonFile: string | null;
+    packageName: string | null;
+    namespace: string | null;
+    packageDirectories: string[];
+    defaultPackageDirectory: string | null;
+    lwcComponents: DiscoveredLwcComponent[];
+}
+/**
+ * Recursively locates all folders named 'lwc' inside the specified directory.
+ *
+ * @param dirPath - Directory path to search within.
+ * @returns Array of absolute paths to discovered 'lwc' directories.
+ */
+export declare function findLwcDirectories(dirPath: string): string[];
+/**
+ * Discovers LWC components within the given package directory.
+ *
+ * @param packageDirPath - Path of the package directory.
+ * @param rootDir - Root directory of the project.
+ * @returns Array of discovered LWC components with metadata.
+ */
+export declare function discoverComponentsInPackageDir(packageDirPath: string, rootDir: string): DiscoveredLwcComponent[];
+/**
+ * Inspects a Salesforce project workspace and extracts configuration, package directories,
+ * packaging namespace, and discovered LWC components.
+ *
+ * @param rootDir - Root workspace directory to discover.
+ * @returns Discovered project configuration and LWC components.
+ */
+export declare function discoverProject(rootDir?: string): DiscoveredProject;

package/lib/discovery/project-discovery.js

@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Recursively locates all folders named 'lwc' inside the specified directory.
+ *
+ * @param dirPath - Directory path to search within.
+ * @returns Array of absolute paths to discovered 'lwc' directories.
+ */
+export function findLwcDirectories(dirPath) {
+    let lwcDirs = [];
+    try {
+        if (!fs.existsSync(dirPath)) {
+            return [];
+        }
+        const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'lwc') {
+                    lwcDirs.push(fullPath);
+                }
+                else if (entry.name !== 'node_modules' &&
+                    entry.name !== '.git' &&
+                    entry.name !== 'dist' &&
+                    entry.name !== 'lib' &&
+                    entry.name !== '.wireit' &&
+                    entry.name !== '.sfdx' &&
+                    entry.name !== '.sf') {
+                    lwcDirs = lwcDirs.concat(findLwcDirectories(fullPath));
+                }
+            }
+        }
+    }
+    catch {
+        // Gracefully handle permission or read errors
+    }
+    return lwcDirs;
+}
+/**
+ * Discovers LWC components within the given package directory.
+ *
+ * @param packageDirPath - Path of the package directory.
+ * @param rootDir - Root directory of the project.
+ * @returns Array of discovered LWC components with metadata.
+ */
+export function discoverComponentsInPackageDir(packageDirPath, rootDir) {
+    const components = [];
+    const absolutePkgDir = path.isAbsolute(packageDirPath) ? packageDirPath : path.resolve(rootDir, packageDirPath);
+    if (!fs.existsSync(absolutePkgDir)) {
+        return components;
+    }
+    const lwcDirs = findLwcDirectories(absolutePkgDir);
+    for (const lwcDir of lwcDirs) {
+        try {
+            const entries = fs.readdirSync(lwcDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const componentName = entry.name;
+                    if (componentName.startsWith('.') || componentName === '__tests__') {
+                        continue;
+                    }
+                    const componentDir = path.join(lwcDir, componentName);
+                    const metaFilePath = path.join(componentDir, `${componentName}.js-meta.xml`);
+                    const hasMetaFile = fs.existsSync(metaFilePath);
+                    components.push({
+                        name: componentName,
+                        directory: componentDir,
+                        packageDirectory: packageDirPath,
+                        metaFile: hasMetaFile ? metaFilePath : null,
+                        hasMetaFile,
+                    });
+                }
+            }
+        }
+        catch {
+            // Gracefully handle directory read errors
+        }
+    }
+    return components;
+}
+function parseSfdxProject(resolvedRoot) {
+    let sfdxProjectFile = null;
+    let namespace = null;
+    const packageDirectories = [];
+    let defaultPackageDirectory = null;
+    const candidate = path.join(resolvedRoot, 'sfdx-project.json');
+    if (fs.existsSync(candidate)) {
+        sfdxProjectFile = candidate;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
+            if (typeof parsed.namespace === 'string' && parsed.namespace.trim()) {
+                namespace = parsed.namespace.trim();
+            }
+            if (Array.isArray(parsed.packageDirectories)) {
+                for (const pkgDir of parsed.packageDirectories) {
+                    if (typeof pkgDir?.path === 'string') {
+                        packageDirectories.push(pkgDir.path);
+                        if (pkgDir.default === true && !defaultPackageDirectory) {
+                            defaultPackageDirectory = pkgDir.path;
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Continue with empty defaults on JSON read error
+        }
+    }
+    if (packageDirectories.length === 0) {
+        for (const fallback of ['force-app', 'sfdx-source', 'src']) {
+            if (fs.existsSync(path.join(resolvedRoot, fallback))) {
+                packageDirectories.push(fallback);
+            }
+        }
+    }
+    if (!defaultPackageDirectory && packageDirectories.length > 0) {
+        defaultPackageDirectory = packageDirectories[0];
+    }
+    return { sfdxProjectFile, namespace, packageDirectories, defaultPackageDirectory };
+}
+function parsePackageJson(resolvedRoot) {
+    let packageJsonFile = null;
+    let packageName = null;
+    const candidate = path.join(resolvedRoot, 'package.json');
+    if (fs.existsSync(candidate)) {
+        packageJsonFile = candidate;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
+            if (typeof parsed['name'] === 'string') {
+                packageName = parsed['name'];
+            }
+        }
+        catch {
+            // Continue with null on parse error
+        }
+    }
+    return { packageJsonFile, packageName };
+}
+/**
+ * Inspects a Salesforce project workspace and extracts configuration, package directories,
+ * packaging namespace, and discovered LWC components.
+ *
+ * @param rootDir - Root workspace directory to discover.
+ * @returns Discovered project configuration and LWC components.
+ */
+export function discoverProject(rootDir = process.cwd()) {
+    const resolvedRoot = path.resolve(rootDir);
+    const sfdx = parseSfdxProject(resolvedRoot);
+    const pkg = parsePackageJson(resolvedRoot);
+    const lwcComponents = [];
+    for (const pkgDir of sfdx.packageDirectories) {
+        lwcComponents.push(...discoverComponentsInPackageDir(pkgDir, resolvedRoot));
+    }
+    return {
+        rootDir: resolvedRoot,
+        sfdxProjectFile: sfdx.sfdxProjectFile,
+        packageJsonFile: pkg.packageJsonFile,
+        packageName: pkg.packageName,
+        namespace: sfdx.namespace,
+        packageDirectories: sfdx.packageDirectories,
+        defaultPackageDirectory: sfdx.defaultPackageDirectory,
+        lwcComponents,
+    };
+}
+//# sourceMappingURL=project-discovery.js.map

package/lib/discovery/project-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-discovery.js","sourceRoot":"","sources":["../../src/discovery/project-discovery.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -1,4 +1,10 @@
-export { TestEnvironment, USERNAME_ENV, type EnvLike, type TestEnvironmentOptions } from './test-environment.js';
+export { TestEnvironment, USERNAME_ENV, DEFAULT_ALLOWED_HOST_PATTERNS, isHostAllowed, validateAndParseSecureUrl, getTestEnvironment, setTestEnvironment, resetTestEnvironment, type EnvLike, type TestEnvironmentOptions, } from './test-environment.js';
 export { applicationPath, lightningAppName, newRecordPath, recordPath, relatedListPath } from './lightning-paths.js';
-export { LightningNavigator, type FrontdoorUrlSource, type LightningNavigatorOptions, type NavigableBrowser, } from './navigator.js';
+export { LightningNavigator, goToLoginUrl, goToExperiencePage, loginAsUser, loginAsExperienceUser, goToApplication, goToCreateNewRecord, goToRecord, goToRelatedList, resolveBrowser, type FrontdoorUrlSource, type LightningNavigatorOptions, type NavigableBrowser, } from './navigator.js';
 export { formatUtamHtml, getUtamHtml, logUtamHtml, type UtamElementLike, type UtamHtml } from './utam-html.js';
+export { findLwcDirectories, discoverComponentsInPackageDir, discoverProject, type SfdxPackageDirectory, type SfdxProjectConfig, type DiscoveredLwcComponent, type DiscoveredProject, } from './discovery/index.js';
+export { ROOT_TARGETS, convertLwcNameToHtml, getTargetsFromMeta, generateLwcRules, type GenerateRulesOptions, type RuleAction, type GenerateRulesResult, } from './rules/index.js';
+export { detectIndentation, findUtamOverridesFiles, walkElements, mergeElements, applyUtamOverrides, type ApplyOverridesOptions, type OverrideChange, type FileOverrideResult, type ApplyOverridesResult, type UtamOverrideItem, } from './overrides/index.js';
+export { findUtamJsonFiles, updateValueWithMappings, rewriteUtamNamespaces, type RewriteNamespacesOptions, type NamespaceReplacement, type FileRewriteResult, type RewriteNamespacesResult, } from './namespaces/index.js';
+export { parseGherkinDocument, extractStepsFromGherkin, normalizeExpression, extractStepExpressionsFromContent, compileStepExpressions, matchStepAgainstExpressions, formatParameterNames, generateStepSnippet, formatCode, resolveGlobs, resolveDefaultTargetOutput, generateCucumberSteps, type StepSemanticKeyword, type ParsedGherkinStep, type RawExtractedExpression, type CompiledStepExpression, type GeneratedStepSnippet, type GenerateStepsOptions, type GenerateStepsResult, } from './steps/index.js';
+export { DEFAULT_TEMPLATES_DIR, DEFAULT_REQUIRED_DEV_DEPENDENCIES, loadTemplate, generateGeneratorConfig, generateUtamConfig, generateWdioConfig, generateNamespaceMap, generateHelloFeature, generateHelloSteps, injectWireitConfiguration, checkMissingDependencies, scaffoldProject, type ScaffoldOptions, type ScaffoldResult, } from './scaffold/index.js';