@hubspot/project-parsing-lib 0.2.0-beta.1 → 0.2.0-experimental.0

package/README.md

@@ -1,38 +1,7 @@
-# project-translation-layer
+# @hubspot/project-parsing-lib
 
-## Description
-This project is a translation layer that can be used to translate a project to its immediate representation prior to being uploaded
-to the project v2 service.
+A parsing library for converting HubSpot project directory structures to their intermediate representation (IR).
 
-## Flow Chart
+## Description
 
-```mermaid
-sequenceDiagram
-    autonumber
-    
-    actor dev as External Developer
-    participant cli as HS CLI
-    participant ppl as Project Parsing Library
-    participant pv3 as Projects v3
-    
-    dev ->> cli: Developer runs `hs project upload`
-    cli ->> cli: Loads project config
-    cli ->> ppl: CLI calls `translate` function with the values required from the project config
-    ppl ->> ppl: Walks the project directory looking for the hsmeta files
-    loop For each hsmeta file
-        ppl ->> ppl: Checks if file is valid JSON
-        ppl ->> ppl: Checks if the file is in a valid location
-        ppl ->> ppl: Generates the IR
-    end
-    ppl ->> pv3: Fetch the schemas used to validate the generated IR
-    loop For each hsmeta file
-        ppl ->> ppl: Validate the IR config block against the schema
-    end
-    alt Validation successful for all schemas
-        ppl ->> cli: Pass the IR back to the CLI
-        cli ->> cli: Zip the project contents
-        cli ->> pv3: Upload the project and the IR
-    else Validation failed for 1+ schema(s)
-        ppl ->> cli: Log the error and exit the upload
-end
-```
+This library provides functionality to parse HubSpot project structures and convert them into an intermediate representation that can be uploaded to HubSpot. It walks through project directories, locates `.hsmeta.json` files, validates them, and generates the IR needed for project uploads.

package/package.json

@@ -1,44 +1,86 @@
 {
     "name": "@hubspot/project-parsing-lib",
-    "version": "0.2.0-beta.1",
+    "version": "0.2.0-experimental.0",
     "description": "Parsing library for converting projects directory structures to their intermediate representation",
     "license": "Apache-2.0",
-    "main": "src/index.js",
+    "type": "module",
+    "exports": {
+        "./constants": {
+            "import": "./src/exports/constants.js",
+            "types": "./src/exports/constants.d.ts"
+        },
+        "./migrate": {
+            "import": "./src/exports/migrate.js",
+            "types": "./src/exports/migrate.d.ts"
+        },
+        "./profiles": {
+            "import": "./src/exports/profiles.js",
+            "types": "./src/exports/profiles.d.ts"
+        },
+        "./projects": {
+            "import": "./src/exports/projects.js",
+            "types": "./src/exports/projects.d.ts"
+        },
+        "./schema": {
+            "import": "./src/exports/schema.js",
+            "types": "./src/exports/schema.d.ts"
+        },
+        "./themes": {
+            "import": "./src/exports/themes.js",
+            "types": "./src/exports/themes.d.ts"
+        },
+        "./transform": {
+            "import": "./src/exports/transform.js",
+            "types": "./src/exports/transform.d.ts"
+        },
+        "./translate": {
+            "import": "./src/exports/translate.js",
+            "types": "./src/exports/translate.d.ts"
+        },
+        "./uid": {
+            "import": "./src/exports/uid.js",
+            "types": "./src/exports/uid.d.ts"
+        },
+        "./workspaces": {
+            "import": "./src/exports/workspaces.js",
+            "types": "./src/exports/workspaces.d.ts"
+        }
+    },
     "devDependencies": {
-        "@hubspot/local-dev-lib": "^3.1.0",
+        "@hubspot/npm-scripts": "0.0.6",
         "@inquirer/prompts": "^7.1.0",
-        "@types/jest": "^29.5.14",
+        "@types/node": "^24.9.0",
+        "@types/npm-packlist": "7.0.3",
         "@types/semver": "^7.5.8",
-        "@typescript-eslint/eslint-plugin": "^8.11.0",
-        "@typescript-eslint/parser": "^8.11.0",
-        "eslint": "^8.56.0",
+        "@typescript-eslint/eslint-plugin": "8.54.0",
+        "@typescript-eslint/parser": "8.54.0",
+        "eslint": "^9.38.0",
         "eslint-plugin-import": "^2.31.0",
         "husky": "^9.1.7",
-        "jest": "^29.5.0",
         "lint-staged": "^10.5.4",
-        "prettier": "^1.19.1",
+        "prettier": "^3.3.0",
         "semver": "^7.6.3",
-        "ts-jest": "^29.2.5",
-        "ts-node": "^10.9.2",
-        "typescript": "^5.6.2"
+        "tsx": "^4.20.5",
+        "typescript": "^5.6.2",
+        "vitest": "^2.1.9"
     },
     "dependencies": {
-        "ajv": "8.17.1",
-        "ajv-formats": "3.0.1"
-    },
-    "peerDependencies": {
-        "@hubspot/local-dev-lib": "^3.1.0"
+        "@hubspot/local-dev-lib": "4.0.4",
+        "ajv": "8.18.0",
+        "ajv-formats": "3.0.1",
+        "glob": "13.0.0",
+        "npm-packlist": "8.0.1"
     },
     "scripts": {
-        "build": "ts-node ./scripts/build.ts",
+        "build": "tsx ./scripts/build.ts",
         "lint": "echo 'Linting is disabled for Blazar'",
         "lint:local": "eslint --max-warnings=0 . && prettier ./src/** --check",
         "local-dev": "yarn build && cd dist && yarn link && cd .. && tsc --watch --rootDir . --outdir dist",
+        "local-link": "hubspot-linking",
         "prettier:write": "prettier ./src/** --write",
-        "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ./node_modules/.bin/jest",
-        "release": "yarn ts-node ./scripts/release.ts release",
-        "acceptance-test": "yarn --cwd=./acceptance-tests test",
-        "update-north-star": "git submodule update --remote --merge"
+        "test": "vitest run",
+        "release": "tsx ./scripts/release.ts release",
+        "acceptance-test": "yarn --cwd=./acceptance-tests test"
     },
     "engines": {
         "node": ">=18"

package/src/exports/constants.d.ts

@@ -0,0 +1 @@
+export * from '../lib/constants.js';

package/src/exports/constants.js

@@ -0,0 +1 @@
+export * from '../lib/constants.js';

package/src/exports/migrate.d.ts

@@ -0,0 +1 @@
+export { migrate } from '../lib/migrate.js';

package/src/exports/migrate.js

@@ -0,0 +1 @@
+export { migrate } from '../lib/migrate.js';

package/src/exports/profiles.d.ts

@@ -0,0 +1,3 @@
+export { getAllHsProfiles, loadHsProfileFile } from '../lib/files.js';
+export { getHsProfileFilename, validateProfileVariables, } from '../lib/profiles.js';
+export type { HsProfileFile, HSProfileVariables } from '../lib/types.js';

package/src/exports/profiles.js

@@ -0,0 +1,2 @@
+export { getAllHsProfiles, loadHsProfileFile } from '../lib/files.js';
+export { getHsProfileFilename, validateProfileVariables, } from '../lib/profiles.js';

package/src/exports/projects.d.ts

@@ -0,0 +1,3 @@
+export { getProjectMetadata } from '../lib/project.js';
+export { projectContainsHsMetaFiles } from '../lib/files.js';
+export type { ProjectMetadata } from '../lib/project.js';

package/src/exports/projects.js

@@ -0,0 +1,2 @@
+export { getProjectMetadata } from '../lib/project.js';
+export { projectContainsHsMetaFiles } from '../lib/files.js';

package/src/exports/schema.d.ts

@@ -0,0 +1,2 @@
+export { getIntermediateRepresentationSchema } from '../lib/schemas.js';
+export type { AnySchema } from 'ajv';

package/src/exports/schema.js

@@ -0,0 +1 @@
+export { getIntermediateRepresentationSchema } from '../lib/schemas.js';

package/src/exports/themes.d.ts

@@ -0,0 +1,2 @@
+export { migrateThemes, getProjectThemeDetails } from '../lib/migrateThemes.js';
+export type { ThemeDetails, ReactThemeDetails, ProjectThemeDetails, } from '../lib/migrateThemes.js';

package/src/exports/themes.js

@@ -0,0 +1 @@
+export { migrateThemes, getProjectThemeDetails } from '../lib/migrateThemes.js';

package/src/exports/transform.d.ts

@@ -0,0 +1,2 @@
+export { mapToUserFriendlyName, mapToUserFacingType, mapToInternalType, } from '../lib/transform.js';
+export type { Dependencies } from '../lib/types.js';

package/src/exports/transform.js

@@ -0,0 +1 @@
+export { mapToUserFriendlyName, mapToUserFacingType, mapToInternalType, } from '../lib/transform.js';

package/src/exports/translate.d.ts

@@ -0,0 +1,3 @@
+export { translate, translateForLocalDev } from '../lib/translate.js';
+export { isTranslationError, type TranslationError } from '../lib/errors.js';
+export type { IntermediateRepresentation, IntermediateRepresentationLocalDev, IntermediateRepresentationNodeLocalDev, IntermediateRepresentationNode, TranslationContext, TranslationOptions, TranslationOptionsLocalDev, } from '../lib/types.js';

package/src/exports/translate.js

@@ -0,0 +1,2 @@
+export { translate, translateForLocalDev } from '../lib/translate.js';
+export { isTranslationError } from '../lib/errors.js';

package/src/exports/uid.d.ts

@@ -0,0 +1 @@
+export { validateUid, coerceToValidUid } from '../lib/uid.js';

package/src/exports/uid.js

@@ -0,0 +1 @@
+export { validateUid, coerceToValidUid } from '../lib/uid.js';

package/src/exports/workspaces.d.ts

@@ -0,0 +1,2 @@
+export { findAndParsePackageJsonFiles, resolveWorkspaceDirectories, collectWorkspaceDirectories, collectFileDependencies, getPackableFiles, WorkspaceResolutionError, FileDependencyResolutionError, } from '../lib/workspaces.js';
+export type { ParsedPackageJson, WorkspaceMapping, FileDependencyMapping, } from '../lib/workspaces.js';

package/src/exports/workspaces.js

@@ -0,0 +1 @@
+export { findAndParsePackageJsonFiles, resolveWorkspaceDirectories, collectWorkspaceDirectories, collectFileDependencies, getPackableFiles, WorkspaceResolutionError, FileDependencyResolutionError, } from '../lib/workspaces.js';

package/src/lang/copy.d.ts

@@ -1,10 +1,12 @@
-import { ComponentMetadata } from '../lib/constants';
+import { ComponentMetadata } from '../lib/constants.js';
 export declare const errorMessages: {
     api: {
         failedToFetchSchemas: string;
+        failedToFetchSchemas403: string;
         accountIdIsRequiredToFetchSchemas: string;
     };
     project: {
+        mustHaveAppComponent: (componentType: string) => string;
         noHsMetaFiles: string;
         failedToTranslateProject: string;
         duplicateUid: (uid: string, files: string[]) => string;
@@ -30,8 +32,12 @@ export declare const errorMessages: {
         unsupportedType: (type: string) => string;
         errorWithField: (field: string, error: string | undefined) => string;
         invalidJson: string;
+        unexpectedToplevelFields: (unexpectedFields: string) => string;
         wrongDirectoryForComponent: (directory: string, componentType: string, componentMetadata: ComponentMetadata, correctDir: string) => string;
     };
+    migrateThemes: {
+        rootReactThemeNotSupported: string;
+    };
 };
 export declare function getInvalidJsonError(): string;
 export declare function getMissingTypeError(): string;

package/src/lang/copy.js

@@ -1,26 +1,18 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.logMessages = exports.errorMessages = void 0;
-exports.getInvalidJsonError = getInvalidJsonError;
-exports.getMissingTypeError = getMissingTypeError;
-exports.getMissingConfigError = getMissingConfigError;
-exports.getMissingAccountIdError = getMissingAccountIdError;
-exports.getMissingRequiredFieldError = getMissingRequiredFieldError;
-exports.getFailedToFetchSchemasError = getFailedToFetchSchemasError;
-exports.getUnsupportedTypeError = getUnsupportedTypeError;
-const constants_1 = require("../lib/constants");
-const transform_1 = require("../lib/transform");
-exports.errorMessages = {
+import { APP_FUNCTIONS_KEY, APP_KEY, Components, PACKAGE_JSON, } from '../lib/constants.js';
+import { mapToUserFacingType } from '../lib/transform.js';
+export const errorMessages = {
     api: {
-        failedToFetchSchemas: 'Failed to fetch schemas',
-        accountIdIsRequiredToFetchSchemas: 'Account id is required to fetch schemas',
+        failedToFetchSchemas: 'Failed to fetch component schemas',
+        failedToFetchSchemas403: 'Failed to fetch component schemas. Please verify that your personal access key provides access to developer projects.',
+        accountIdIsRequiredToFetchSchemas: 'Account id is required to fetch component schemas',
     },
     project: {
+        mustHaveAppComponent: (componentType) => `This '${componentType}' component must be a child of the '${APP_KEY}' component. No *-hsmeta.json files were found with type '${APP_KEY}'`,
         noHsMetaFiles: 'No *-hsmeta.json files found in the current directory. Please make sure you are inside the correct project directory.',
         failedToTranslateProject: 'Project validation failed',
         duplicateUid: (uid, files) => `Duplicate uid '${uid}' found in:\n- ${files.join('\n- ')}`,
         duplicateComponent: (componentType) => `Only one ${componentType} component is allowed`,
-        noPackageJsonForServerless: (appFunctionsPackageFile) => `${appFunctionsPackageFile} does not exist. ${constants_1.Components[constants_1.AppFunctionsKey].userFriendlyName} requires a ${constants_1.packageJson} file to exist in this location`,
+        noPackageJsonForServerless: (appFunctionsPackageFile) => `${appFunctionsPackageFile} does not exist. ${Components[APP_FUNCTIONS_KEY].userFriendlyName} requires a ${PACKAGE_JSON} file to exist in this location`,
         fileContentMissingFor: (file) => `File content is missing for ${file}`,
     },
     profile: {
@@ -38,34 +30,38 @@ exports.errorMessages = {
         uidTooLong: `'uid' must be 64 characters or less`,
         missingType: `Missing required field: 'type'`,
         missingConfig: `Missing required field: 'config'`,
-        unsupportedType: (type) => `Unsupported type: ${(0, transform_1.mapToUserFacingType)(type)}`,
-        errorWithField: (field, error) => `Error with ${field}: ${error || 'Unknown error'}`,
+        unsupportedType: (type) => `Unsupported type: ${mapToUserFacingType(type)}`,
+        errorWithField: (field, error) => `${field}: ${error || 'Unknown error'}`,
         invalidJson: 'Invalid JSON',
+        unexpectedToplevelFields: (unexpectedFields) => `Unexpected top-level properties found: ${unexpectedFields}`,
         wrongDirectoryForComponent: (directory, componentType, componentMetadata, correctDir) => `The directory '${directory}' is incorrect for type '${componentType}'. ${componentMetadata.userFriendlyName} ${componentMetadata.userFriendlyTypePlural} should only be placed in the '${correctDir}' directory`,
     },
+    migrateThemes: {
+        rootReactThemeNotSupported: 'Migrating themes that live at the root of the project src directory is not supported. Please move the theme to a subdirectory.',
+    },
 };
-function getInvalidJsonError() {
-    return exports.errorMessages.validation.invalidJson;
+export function getInvalidJsonError() {
+    return errorMessages.validation.invalidJson;
 }
-function getMissingTypeError() {
-    return exports.errorMessages.validation.missingType;
+export function getMissingTypeError() {
+    return errorMessages.validation.missingType;
 }
-function getMissingConfigError() {
-    return exports.errorMessages.validation.missingConfig;
+export function getMissingConfigError() {
+    return errorMessages.validation.missingConfig;
 }
-function getMissingAccountIdError() {
-    return exports.errorMessages.api.accountIdIsRequiredToFetchSchemas;
+export function getMissingAccountIdError() {
+    return errorMessages.api.accountIdIsRequiredToFetchSchemas;
 }
-function getMissingRequiredFieldError(field) {
-    return exports.errorMessages.validation.missingRequiredField(field);
+export function getMissingRequiredFieldError(field) {
+    return errorMessages.validation.missingRequiredField(field);
 }
-function getFailedToFetchSchemasError() {
-    return exports.errorMessages.api.failedToFetchSchemas;
+export function getFailedToFetchSchemasError() {
+    return errorMessages.api.failedToFetchSchemas;
 }
-function getUnsupportedTypeError(type) {
-    return exports.errorMessages.validation.unsupportedType(type);
+export function getUnsupportedTypeError(type) {
+    return errorMessages.validation.unsupportedType(type);
 }
-exports.logMessages = {
+export const logMessages = {
     files: {
         skippingPath: (path) => `Skipping ${path} as it is not in a valid directory`,
     },

package/src/lib/constants.d.ts

@@ -1,19 +1,26 @@
-export declare const AppKey = "app";
-export declare const ThemeKey = "theme";
-export declare const AppFunctionsKey = "app-function";
-export declare const AppObjectKey = "app-object";
-export declare const AppObjectAssociationKey = "app-object-association";
-export declare const CallingKey = "calling";
-export declare const CardsKey = "card";
-export declare const SettingsKey = "settings";
-export declare const MarketingEventsKey = "marketing-event";
-export declare const MediaBridgeKey = "media-bridge";
-export declare const TimelineEventsKey = "timeline-event";
-export declare const VideoConferencingKey = "video-conferencing";
-export declare const WebhooksKey = "webhooks";
-export declare const WorkflowActionsKey = "workflow-action";
-export declare const AppFunctionsPackageKey = "serverless-package";
-export declare const AutoGeneratedComponentTypes: string[];
+import { Components as ComponentsTopLevel } from './types.js';
+export declare const APP_KEY = "app";
+export declare const THEME_KEY = "theme";
+export declare const CMS_ASSETS_KEY = "cms-assets";
+export declare const APP_EVENTS_KEY = "app-event";
+export declare const APP_FUNCTIONS_KEY = "app-function";
+export declare const PAGES_KEY = "page";
+export declare const APP_OBJECT_KEY = "app-object";
+export declare const APP_OBJECT_ASSOCIATION_KEY = "app-object-association";
+export declare const CALLING_KEY = "calling";
+export declare const CARDS_KEY = "card";
+export declare const SCIM_KEY = "scim";
+export declare const MARKETING_EVENTS_KEY = "marketing-event";
+export declare const MCP_REGISTRY_KEY = "mcp-registry";
+export declare const MEDIA_BRIDGE_KEY = "media-bridge";
+export declare const SETTINGS_KEY = "settings";
+export declare const TELEMETRY_KEY = "telemetry";
+export declare const VIDEO_CONFERENCING_KEY = "video-conferencing";
+export declare const WEBHOOKS_KEY = "webhooks";
+export declare const WEBHOOKS_JOURNAL_KEY = "webhooks-journal";
+export declare const WORKFLOW_ACTIONS_KEY = "workflow-action";
+export declare const APP_FUNCTIONS_PACKAGE_KEY = "serverless-package";
+export declare const AUTO_GENERATED_COMPONENT_TYPES: string[];
 export interface ComponentMetadata {
     dir: string;
     isToplevel: boolean;
@@ -24,18 +31,27 @@ export interface ComponentMetadata {
     singularComponent?: boolean;
 }
 export declare const Components: Record<string, ComponentMetadata>;
-export declare const userFacingToInternalType: Record<string, string>;
-export declare const internalTypeToUserFacing: Record<string, string>;
-export declare const metafileExtension = "-hsmeta.json";
-export declare const profileFilePrefix = "hsprofile";
-export declare const hsProjectJsonFilename = "hsproject.json";
-export declare const packageJson = "package.json";
-export declare const packageLockJson = "package-lock.json";
-export declare const allowedAppSubComponentsDirs: string[];
-export declare const allowedThemeSubComponentsDirs: string[];
-export declare const ProjectStructure: {
+export declare const USER_FACING_TO_INTERNAL_TYPE: Record<string, string>;
+export declare const INTERNAL_TYPE_TO_USER_FACING: Record<string, string>;
+export declare const METAFILE_EXTENSION = "-hsmeta.json";
+export declare const PROFILE_FILE_PREFIX = "hsprofile";
+export declare const HS_PROJECT_JSON_FILENAME = "hsproject.json";
+export declare const PACKAGE_JSON = "package.json";
+export declare const PACKAGE_LOCK_JSON = "package-lock.json";
+export declare const ALLOWED_APP_SUB_COMPONENTS_DIRS: string[];
+export declare const ALLOWED_THEME_SUB_COMPONENTS_DIRS: string[];
+export declare const ALLOWED_CMS_ASSET_SUB_COMPONENT_DIRS: string[];
+export declare const PROJECT_STRUCTURE: {
     readonly app: string[];
     readonly theme: string[];
+    readonly "cms-assets": string[];
 };
-export declare const allowedComponentDirectories: string[];
-export declare const allowedSubComponentDirectories: string[];
+export declare const ALLOWED_COMPONENT_DIRECTORIES: string[];
+export declare const ALLOWED_SUB_COMPONENT_DIRECTORIES: string[];
+export declare const PROFILE_VARIABLE_TYPES: {
+    readonly PROFILE_INT: "PROFILE_INT";
+    readonly PROFILE_LONG: "PROFILE_LONG";
+    readonly PROFILE_STRING: "PROFILE_STRING";
+    readonly PROFILE_BOOLEAN: "PROFILE_BOOLEAN";
+};
+export declare const ALLOWED_TOP_LEVEL_FIELDS: Set<keyof ComponentsTopLevel>;