fix: sfProject types matches schemas repo

.github/workflows/perf.yml

@@ -19,8 +19,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with:
-          cache: yarn
       - uses: salesforcecli/github-workflows/.github/actions/yarnInstallWithRetries@main
         with:
           ignore-scripts: true

MIGRATING_V7-V8.md

@@ -0,0 +1,15 @@
+# Migrating `@salesforce/core` from v7 to v8
+
+v8 uses the types from `@salesforce/schemas`, for SfProject/SfProjectJson.
+
+The schemas types are more accurate about the PackageDir type (what `sfdx-project.json` packageDirectories is an array of). It is a union type of
+
+1. simply `path`, with an optional default property
+1. 1, along with the `package` property and lots of optional properties used for packaging.
+
+To support differentiating between the two structures, 2 type guards are now importable:
+
+1. isPackagingDirectory
+1. isNamedPackagingDirectory
+
+`PackageDir` and `PackageDirDependency` are no longer re-exported. If you need them, import them from `@salesforce/schemas`

package.json

@@ -53,9 +53,9 @@
   ],
   "dependencies": {
     "@jsforce/jsforce-node": "^3.2.0",
-    "@salesforce/kit": "^3.1.2",
+    "@salesforce/kit": "^3.1.6",
     "@salesforce/schemas": "^1.9.0",
-    "@salesforce/ts-types": "^2.0.9",
+    "@salesforce/ts-types": "^2.0.10",
     "ajv": "^8.15.0",
     "change-case": "^4.1.2",
     "fast-levenshtein": "^3.0.0",
@@ -64,16 +64,16 @@
     "js2xmlparser": "^4.0.1",
     "jsonwebtoken": "9.0.2",
     "jszip": "3.10.1",
-    "pino": "^8.21.0",
+    "pino": "^9.2.0",
     "pino-abstract-transport": "^1.2.0",
-    "pino-pretty": "^10.3.1",
+    "pino-pretty": "^11.2.1",
     "proper-lockfile": "^4.1.2",
     "semver": "^7.6.2",
     "ts-retry-promise": "^0.8.1"
   },
   "devDependencies": {
-    "@salesforce/dev-scripts": "^8.5.0",
-    "@salesforce/ts-sinon": "^1.4.19",
+    "@salesforce/dev-scripts": "^10.1.1",
+    "@salesforce/ts-sinon": "^1.4.22",
     "@types/benchmark": "^2.1.5",
     "@types/chai-string": "^1.4.5",
     "@types/fast-levenshtein": "^0.0.4",

src/index.ts

@@ -75,7 +75,7 @@ export {
 
 export { OrgConfigProperties, ORG_CONFIG_ALLOWED_PROPERTIES } from './org/orgConfigProperties';
 
-export { PackageDir, NamedPackageDir, PackageDirDependency, SfProject, SfProjectJson } from './sfProject';
+export { NamedPackageDir, SfProject, SfProjectJson } from './sfProject';
 
 export { SchemaValidator } from './schema/validator';
 

src/org/scratchOrgInfoGenerator.ts

@@ -7,7 +7,7 @@
 import { promises as fs } from 'node:fs';
 import { parseJson } from '@salesforce/kit';
 import { ensureString } from '@salesforce/ts-types';
-import { SfProjectJson } from '../sfProject';
+import { SfProjectJson, isPackagingDirectory } from '../sfProject';
 import { WebOAuthServer } from '../webOAuthServer';
 import { Messages } from '../messages';
 import { SfError } from '../sfError';
@@ -90,6 +90,7 @@ export const getAncestorIds = async (
     throw new SfError(messages.getMessage('Package2AncestorsIdsKeyNotSupportedError'), 'DeprecationError');
   }
   const packagesWithAncestors = (await projectJson.getPackageDirectories())
+    .filter(isPackagingDirectory)
     // check that the package has any ancestor types (id or version)
     .filter((packageDir) => packageDir.ancestorId ?? packageDir.ancestorVersion);
   if (packagesWithAncestors.length === 0) {

src/sfProject.ts

@@ -8,6 +8,7 @@ import { basename, dirname, isAbsolute, normalize, resolve, sep } from 'node:pat
 import * as fs from 'node:fs';
 import { defaults, env } from '@salesforce/kit';
 import { Dictionary, ensure, JsonMap, Nullable, Optional } from '@salesforce/ts-types';
+import { PackageDir, ProjectJson as ProjectJsonSchema, PackagePackageDir } from '@salesforce/schemas';
 import { SfdcUrl } from './util/sfdcUrl';
 import { ConfigAggregator } from './config/configAggregator';
 import { ConfigFile } from './config/configFile';
@@ -18,45 +19,12 @@ import { resolveProjectPath, resolveProjectPathSync, SFDX_PROJECT_JSON } from '.
 
 import { SfError } from './sfError';
 import { Messages } from './messages';
-import { findUpperCaseKeys } from './util/findUppercaseKeys';
+import { ensureNoUppercaseKeys } from './util/findUppercaseKeys';
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/core', 'config');
 
-const coreMessages = Messages.loadMessages('@salesforce/core', 'core');
-
-export type PackageDirDependency = {
-  [k: string]: unknown;
-  package: string;
-  versionNumber?: string;
-};
-
-export type PackageDir = {
-  ancestorId?: string;
-  ancestorVersion?: string;
-  default?: boolean;
-  definitionFile?: string;
-  dependencies?: PackageDirDependency[];
-  includeProfileUserLicenses?: boolean;
-  package?: string;
-  packageMetadataAccess?: {
-    permissionSets: string | string[];
-    permissionSetLicenses: string | string[];
-  };
-  path: string;
-  postInstallScript?: string;
-  postInstallUrl?: string;
-  releaseNotesUrl?: string;
-  scopeProfiles?: boolean;
-  uninstallScript?: string;
-  versionDescription?: string;
-  versionName?: string;
-  versionNumber?: string;
-  unpackagedMetadata?: { path: string };
-  seedMetadata?: { path: string };
-};
-
-export type NamedPackageDir = PackageDir & {
+type NamedDirAdditions = {
   /**
    * The [normalized](https://nodejs.org/api/path.html#path_path_normalize_path) path used as the package name.
    */
@@ -67,16 +35,10 @@ export type NamedPackageDir = PackageDir & {
   fullPath: string;
 };
 
-export type ProjectJson = ConfigContents & {
-  packageDirectories: PackageDir[];
-  namespace?: string;
-  sourceApiVersion?: string;
-  sfdcLoginUrl?: string;
-  signupTargetLoginUrl?: string;
-  oauthLocalPort?: number;
-  plugins?: { [k: string]: unknown };
-  packageAliases?: { [k: string]: string };
-};
+export type NamedPackagingDir = PackagePackageDir & NamedDirAdditions;
+export type NamedPackageDir = PackageDir & NamedDirAdditions;
+
+export type ProjectJson = ConfigContents & ProjectJsonSchema;
 
 /**
  * The sfdx-project.json config object. This file determines if a folder is a valid sfdx project.
@@ -96,6 +58,7 @@ export type ProjectJson = ConfigContents & {
  * **See** [force:project:create](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_create_new.htm)
  */
 export class SfProjectJson extends ConfigFile<ConfigFile.Options, ProjectJson> {
+  /** json properties that are uppercase, or allow uppercase keys inside them */
   public static BLOCKLIST = ['packageAliases'];
 
   public static getFileName(): string {
@@ -337,19 +300,9 @@ export class SfProjectJson extends ConfigFile<ConfigFile.Options, ProjectJson> {
    *
    * @param packageDir
    */
-  public addPackageDirectory(packageDir: NamedPackageDir): void {
-    // there is no notion of uniqueness in package directory entries
-    // so an attempt of matching an existing entry is a bit convoluted
-    // an entry w/o a package or id is considered a directory entry for which a package has yet to be created
-    // so first attempt is to find a matching dir entry that where path is the same and id and package are not present
-    // if that fails, then find a matching dir entry package is present and is same as the new entry
-    const dirIndex = this.getContents().packageDirectories.findIndex((pd) => {
-      const withId = pd as NamedPackageDir & { id: string };
-      return (
-        (withId.path === packageDir.path && !withId.id && !withId.package) ||
-        (!!packageDir.package && packageDir.package === withId.package)
-      );
-    });
+  public addPackageDirectory(packageDir: PackageDir): void {
+    const dirIndex = this.getContents().packageDirectories.findIndex(findPackageDir(packageDir));
+
     // merge new package dir with existing entry, if present
     const packageDirEntry: PackageDir = Object.assign(
       {},
@@ -367,17 +320,14 @@ export class SfProjectJson extends ConfigFile<ConfigFile.Options, ProjectJson> {
     this.set('packageDirectories', modifiedPackagesDirs);
   }
 
+  // keep it because testSetup stubs it!
   // eslint-disable-next-line class-methods-use-this
   private doesPackageExist(packagePath: string): boolean {
     return fs.existsSync(packagePath);
   }
 
   private validateKeys(): void {
-    // Verify that the configObject does not have upper case keys; throw if it does.  Must be heads down camel case.
-    const upperCaseKey = findUpperCaseKeys(this.toObject(), SfProjectJson.BLOCKLIST);
-    if (upperCaseKey) {
-      throw coreMessages.createError('invalidJsonCasing', [upperCaseKey, this.getPath()]);
-    }
+    ensureNoUppercaseKeys(this.getPath())(SfProjectJson.BLOCKLIST)(this.toObject());
   }
 }
 
@@ -600,7 +550,8 @@ export class SfProject {
    */
   public getPackageNameFromPath(path: string): Optional<string> {
     const packageDir = this.getPackageFromPath(path);
-    return packageDir ? packageDir.package ?? packageDir.path : undefined;
+    if (!packageDir) return undefined;
+    return isNamedPackagingDirectory(packageDir) ? packageDir.package : packageDir.path;
   }
 
   /**
@@ -762,3 +713,26 @@ export class SfProject {
       .map(([key]) => key);
   }
 }
+
+/** differentiate between the Base PackageDir (path, maybe default) and the Packaging version (package and maybe a LOT of other fields) by whether is has the `package` property */
+export const isPackagingDirectory = (packageDir: PackageDir): packageDir is PackagePackageDir =>
+  isPackagingDir(packageDir);
+
+/** differentiate between the Base PackageDir (path, maybe default) and the Packaging version (package and maybe a LOT of other fields) by whether is has the `package` property */
+export const isNamedPackagingDirectory = (packageDir: NamedPackageDir): packageDir is NamedPackagingDir =>
+  isPackagingDir(packageDir);
+
+const isPackagingDir = (packageDir: PackageDir | NamedPackageDir): boolean =>
+  'package' in packageDir && typeof packageDir.package === 'string';
+/**
+ * there is no notion of uniqueness in package directory entries
+ * so an attempt of matching an existing entry is a bit convoluted
+ */
+const findPackageDir =
+  (target: PackageDir) =>
+  (potentialMatch: PackageDir): boolean =>
+    // an entry w/o a package or id is considered a directory entry for which a package has yet to be created
+    //  find a matching dir entry that where path is the same and id and package are not present
+    (potentialMatch.path === target.path && !('id' in potentialMatch) && !isPackagingDirectory(potentialMatch)) ||
+    // if that fails, then find a matching dir entry package is present and is same as the new entry
+    (isPackagingDirectory(target) && isPackagingDirectory(potentialMatch) && target.package === potentialMatch.package);

src/util/findUppercaseKeys.ts

@@ -5,21 +5,25 @@
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-import { JsonMap, Optional, isJsonMap, asJsonMap, AnyJson } from '@salesforce/ts-types';
-import { findKey } from '@salesforce/kit';
+import { strictEqual } from 'node:assert/strict';
+import { JsonMap, isJsonMap } from '@salesforce/ts-types';
+import { Messages } from '../messages';
 
-export const findUpperCaseKeys = (data?: JsonMap, sectionBlocklist: string[] = []): Optional<string> => {
-  let key: Optional<string>;
-  findKey(data, (val: AnyJson, k: string) => {
-    if (/^[A-Z]/.test(k)) {
-      key = k;
-    } else if (isJsonMap(val)) {
-      if (sectionBlocklist.includes(k)) {
-        return key;
-      }
-      key = findUpperCaseKeys(asJsonMap(val));
-    }
-    return key;
-  });
-  return key;
-};
+Messages.importMessagesDirectory(__dirname);
+const coreMessages = Messages.loadMessages('@salesforce/core', 'core');
+
+/** will throw on any upperCase unless they are present in the allowList.  Recursively searches the object, returning valid keys */
+export const ensureNoUppercaseKeys =
+  (path: string) =>
+  (allowList: string[] = []) =>
+  (data: JsonMap): string[] => {
+    const keys = getKeys(data, allowList);
+    const upperCaseKeys = keys.filter((key) => /^[A-Z]/.test(key)).join(', ');
+    strictEqual(upperCaseKeys.length, 0, coreMessages.getMessage('invalidJsonCasing', [upperCaseKeys, path]));
+    return keys;
+  };
+
+const getKeys = (data: JsonMap, allowList: string[]): string[] =>
+  Object.entries(data)
+    .filter(([k]) => !allowList.includes(k))
+    .flatMap(([key, value]) => (isJsonMap(value) ? [key, ...getKeys(value, allowList)] : [key]));