@hubspot/project-parsing-lib 0.2.2-experimental.3 → 0.3.0-experimental.0

package/README.md

@@ -1,5 +1,10 @@
 # @hubspot/project-parsing-lib
 
+[![npm version](https://img.shields.io/npm/v/@hubspot/project-parsing-lib)](https://www.npmjs.com/package/@hubspot/project-parsing-lib)
+[![npm downloads](https://img.shields.io/npm/dm/@hubspot/project-parsing-lib)](https://www.npmjs.com/package/@hubspot/project-parsing-lib)
+[![npm license](https://img.shields.io/npm/l/@hubspot/project-parsing-lib)](https://www.npmjs.com/package/@hubspot/project-parsing-lib)
+[![node version](https://img.shields.io/node/v/@hubspot/project-parsing-lib)](https://www.npmjs.com/package/@hubspot/project-parsing-lib)
+
 A parsing library for converting HubSpot project directory structures to their intermediate representation (IR).
 
 ## Description

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hubspot/project-parsing-lib",
-    "version": "0.2.2-experimental.3",
+    "version": "0.3.0-experimental.0",
     "description": "Parsing library for converting projects directory structures to their intermediate representation",
     "license": "Apache-2.0",
     "type": "module",
@@ -107,7 +107,7 @@
         }
     },
     "devDependencies": {
-        "@hubspot/npm-scripts": "0.3.0",
+        "@hubspot/npm-scripts": "0.3.1",
         "@inquirer/prompts": "^7.1.0",
         "@types/node": "^24.9.0",
         "@types/npm-packlist": "7.0.3",
@@ -123,10 +123,10 @@
         "semver": "^7.6.3",
         "tsx": "^4.20.5",
         "typescript": "^5.6.2",
-        "vitest": "^2.1.9"
+        "vitest": "^3.2.7"
     },
     "dependencies": {
-        "@hubspot/local-dev-lib": "^5.9.0",
+        "@hubspot/local-dev-lib": "5.10.1",
         "@npmcli/map-workspaces": "4.0.2",
         "ajv": "8.18.0",
         "ajv-formats": "3.0.1",
@@ -134,12 +134,14 @@
         "npm-packlist": "8.0.1"
     },
     "resolutions": {
-        "ajv-formats/ajv": "8.18.0"
+        "ajv-formats/ajv": "8.18.0",
+        "vite": "^6.0.0"
     },
     "overrides": {
         "ajv-formats": {
             "ajv": "8.18.0"
-        }
+        },
+        "vite": "^6.0.0"
     },
     "scripts": {
         "build": "tsx ./scripts/build.ts",

package/src/exports/projects.d.ts

@@ -1,4 +1,5 @@
-export { getProjectMetadata } from '../lib/project.js';
-export { projectContainsHsMetaFiles } from '../lib/files.js';
+export { getProjectMetadata, parseProjectConfig, validateProjectConfig, ProjectConfigValidationError, } from '../lib/project.js';
 export type { ProjectMetadata } from '../lib/project.js';
-export { LATEST_SUPPORTED_PLATFORM_VERSION, isSupportedPlatformVersion, isLegacyProject, supportsComponentPermissions, } from '../lib/platformVersion.js';
+export { projectContainsHsMetaFiles } from '../lib/files.js';
+export type { ProjectConfig } from '../lib/types.js';
+export { LATEST_SUPPORTED_PLATFORM_VERSION, isKnownPlatformVersion, isLegacyProject, meetsMinimumPlatformVersion, } from '../lib/platformVersion.js';

package/src/exports/projects.js

@@ -1,3 +1,3 @@
-export { getProjectMetadata } from '../lib/project.js';
+export { getProjectMetadata, parseProjectConfig, validateProjectConfig, ProjectConfigValidationError, } from '../lib/project.js';
 export { projectContainsHsMetaFiles } from '../lib/files.js';
-export { LATEST_SUPPORTED_PLATFORM_VERSION, isSupportedPlatformVersion, isLegacyProject, supportsComponentPermissions, } from '../lib/platformVersion.js';
+export { LATEST_SUPPORTED_PLATFORM_VERSION, isKnownPlatformVersion, isLegacyProject, meetsMinimumPlatformVersion, } from '../lib/platformVersion.js';

package/src/lang/copy.d.ts

@@ -37,6 +37,14 @@ export declare const errorMessages: {
         unexpectedToplevelFields: (unexpectedFields: string) => string;
         wrongDirectoryForComponent: (directory: string, componentType: string, componentMetadata: ComponentMetadata, correctDir: string) => string;
     };
+    projectConfig: {
+        couldNotRead: (projectDir: string) => string;
+        invalidJson: string;
+        mustBeJsonObject: string;
+        missingRequiredFields: (fields: string[]) => string;
+        srcDirOutsideProject: string;
+        srcDirNotFound: (srcDir: string) => string;
+    };
     migrateThemes: {
         rootReactThemeNotSupported: string;
     };

package/src/lang/copy.js

@@ -1,4 +1,4 @@
-import { APP_FUNCTIONS_KEY, APP_KEY, Components, PACKAGE_JSON, } from '../lib/constants.js';
+import { APP_FUNCTIONS_KEY, APP_KEY, Components, HS_PROJECT_JSON_FILENAME, PACKAGE_JSON, } from '../lib/constants.js';
 import { mapToUserFacingType } from '../lib/transform.js';
 export const errorMessages = {
     api: {
@@ -38,6 +38,14 @@ export const errorMessages = {
         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`,
     },
+    projectConfig: {
+        couldNotRead: (projectDir) => `Could not read ${HS_PROJECT_JSON_FILENAME} in ${projectDir}`,
+        invalidJson: `Failed to parse ${HS_PROJECT_JSON_FILENAME}: invalid JSON`,
+        mustBeJsonObject: `${HS_PROJECT_JSON_FILENAME} must be a JSON object`,
+        missingRequiredFields: (fields) => `${HS_PROJECT_JSON_FILENAME} is missing required field(s): ${fields.join(', ')}`,
+        srcDirOutsideProject: `"srcDir" in ${HS_PROJECT_JSON_FILENAME} must be within the project directory`,
+        srcDirNotFound: (srcDir) => `The "srcDir" specified in ${HS_PROJECT_JSON_FILENAME} does not exist: ${srcDir}`,
+    },
     migrateThemes: {
         rootReactThemeNotSupported: 'Migrating themes that live at the root of the project src directory is not supported. Please move the theme to a subdirectory.',
     },

package/src/lib/constants.d.ts

@@ -1,11 +1,13 @@
+export declare const DEPRECATED_PLATFORM_VERSIONS: {
+    readonly v2025_1: "2025.1";
+};
 export declare const PLATFORM_VERSIONS: {
-    v2023_2: string;
-    v2025_1: string;
-    v2025_2: string;
-    v2026_03_BETA: string;
-    v2026_03: string;
-    v2026_09_BETA: string;
-    UNSTABLE: string;
+    readonly v2023_2: "2023.2";
+    readonly v2025_2: "2025.2";
+    readonly v2026_03_BETA: "2026.03-beta";
+    readonly v2026_03: "2026.03";
+    readonly v2026_09_BETA: "2026.09-beta";
+    readonly UNSTABLE: "unstable";
 };
 import { ComponentMeta as ComponentsTopLevel } from './types.js';
 export declare const APP_KEY = "app";
@@ -29,7 +31,7 @@ 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 ACTIONS_KEY = "action";
+export declare const ACTIONS_KEY = "crm-bulk-action";
 export declare const APP_FUNCTIONS_PACKAGE_KEY = "serverless-package";
 export declare const AUTO_GENERATED_COMPONENT_TYPES: string[];
 export interface ComponentMetadata {

package/src/lib/constants.js

@@ -1,7 +1,10 @@
-// Project Platform Versions
+// Previously supported Project Platform Versions
+export const DEPRECATED_PLATFORM_VERSIONS = {
+    v2025_1: '2025.1',
+};
+// Supported Project Platform Versions
 export const PLATFORM_VERSIONS = {
     v2023_2: '2023.2',
-    v2025_1: '2025.1',
     v2025_2: '2025.2',
     v2026_03_BETA: '2026.03-beta',
     v2026_03: '2026.03',
@@ -33,7 +36,7 @@ export const VIDEO_CONFERENCING_KEY = 'video-conferencing';
 export const WEBHOOKS_KEY = 'webhooks';
 export const WEBHOOKS_JOURNAL_KEY = 'webhooks-journal';
 export const WORKFLOW_ACTIONS_KEY = 'workflow-action';
-export const ACTIONS_KEY = 'action';
+export const ACTIONS_KEY = 'crm-bulk-action';
 // Auto-generated component types
 export const APP_FUNCTIONS_PACKAGE_KEY = 'serverless-package';
 export const AUTO_GENERATED_COMPONENT_TYPES = [APP_FUNCTIONS_PACKAGE_KEY];

package/src/lib/platformVersion.d.ts

@@ -1,4 +1,8 @@
-export declare const LATEST_SUPPORTED_PLATFORM_VERSION: string;
-export declare function isSupportedPlatformVersion(platformVersion?: string | null): boolean;
+export declare const LATEST_SUPPORTED_PLATFORM_VERSION: "2026.03";
+export declare function isKnownPlatformVersion(platformVersion?: string | null): boolean;
+/**
+ * Returns true if platformVersion meets or exceeds minimumVersion.
+ * Versions that do not match the expected format are treated as newer than all known versions.
+ */
+export declare function meetsMinimumPlatformVersion(platformVersion: string, minimumVersion: string): boolean;
 export declare function isLegacyProject(platformVersion?: string | null): boolean;
-export declare function supportsComponentPermissions(platformVersion: string): boolean;

package/src/lib/platformVersion.js

@@ -1,30 +1,74 @@
-import { PLATFORM_VERSIONS } from './constants.js';
+import { PLATFORM_VERSIONS, DEPRECATED_PLATFORM_VERSIONS, } from './constants.js';
 // Used for logging suggestions to users whenever we encouter an unknown version
 export const LATEST_SUPPORTED_PLATFORM_VERSION = PLATFORM_VERSIONS.v2026_03;
-// We are unable to reliably interact versions of projects that are not officially supported by this library
-export function isSupportedPlatformVersion(platformVersion) {
-    if (!platformVersion || typeof platformVersion !== 'string') {
+export function isKnownPlatformVersion(platformVersion) {
+    if (!platformVersion) {
         return false;
     }
     if (process.env.HUBSPOT_PROJECT_INTERNAL_TEST === 'true')
         return true;
-    const supportedPlatformVersions = Object.values(PLATFORM_VERSIONS);
-    return supportedPlatformVersions.includes(platformVersion);
+    const knownVersions = [
+        ...Object.values(PLATFORM_VERSIONS),
+        ...Object.values(DEPRECATED_PLATFORM_VERSIONS),
+    ];
+    return knownVersions.includes(platformVersion);
+}
+function parseVersion(version) {
+    if (version === PLATFORM_VERSIONS.UNSTABLE)
+        return { type: PLATFORM_VERSIONS.UNSTABLE };
+    const match = version.match(/^(\d{4})\.(\d{1,2})(-beta)?$/);
+    if (!match)
+        return { type: 'unknown' };
+    return {
+        type: 'dated',
+        year: parseInt(match[1], 10),
+        month: parseInt(match[2], 10),
+        beta: !!match[3],
+    };
+}
+function compareVersions(a, b) {
+    if (b.type === 'unknown') {
+        throw new Error(`platformVersion: thresholdVersion could not be parsed as a known version format`);
+    }
+    // "Unstable" is always the most recent version
+    if (a.type === PLATFORM_VERSIONS.UNSTABLE &&
+        b.type === PLATFORM_VERSIONS.UNSTABLE) {
+        return 0;
+    }
+    if (a.type === PLATFORM_VERSIONS.UNSTABLE)
+        return 1;
+    if (b.type === PLATFORM_VERSIONS.UNSTABLE)
+        return -1;
+    if (a.type !== 'dated') {
+        throw new Error(`platformVersion: thresholdVersion could not be parsed as a known version format`);
+    }
+    if (a.year !== b.year)
+        return a.year - b.year;
+    if (a.month !== b.month)
+        return a.month - b.month;
+    // Look for beta tags if all else is equal
+    if (a.beta === b.beta)
+        return 0;
+    return a.beta ? -1 : 1;
+}
+/**
+ * Returns true if platformVersion meets or exceeds minimumVersion.
+ * Versions that do not match the expected format are treated as newer than all known versions.
+ */
+export function meetsMinimumPlatformVersion(platformVersion, minimumVersion) {
+    const parsedMinimum = parseVersion(minimumVersion);
+    if (parsedMinimum.type === 'unknown') {
+        throw new Error(`platformVersion: minimumVersion could not be parsed as a known version format`);
+    }
+    const parsed = parseVersion(platformVersion);
+    if (parsed.type === 'unknown')
+        return true;
+    return compareVersions(parsed, parsedMinimum) >= 0;
 }
 export function isLegacyProject(platformVersion) {
-    if (!platformVersion)
+    if (!platformVersion || typeof platformVersion !== 'string')
         return false;
     if (process.env.HUBSPOT_PROJECT_INTERNAL_TEST === 'true')
         return false;
-    return [PLATFORM_VERSIONS.v2023_2, PLATFORM_VERSIONS.v2025_1].includes(platformVersion);
-}
-const PRE_PERMISSIONS_VERSIONS = new Set([
-    PLATFORM_VERSIONS.v2023_2,
-    PLATFORM_VERSIONS.v2025_1,
-    PLATFORM_VERSIONS.v2025_2,
-    PLATFORM_VERSIONS.v2026_03_BETA,
-    PLATFORM_VERSIONS.v2026_03,
-]);
-export function supportsComponentPermissions(platformVersion) {
-    return !PRE_PERMISSIONS_VERSIONS.has(platformVersion);
+    return !meetsMinimumPlatformVersion(platformVersion, PLATFORM_VERSIONS.v2025_2);
 }

package/src/lib/profiles.js

@@ -95,15 +95,18 @@ export function applyHsProfileVariables(fileParseResults, hsProfileContents) {
     const profileVariables = getHsProfileVariables(hsProfileContents);
     return fileParseResults.map(fileParseResult => {
         const { content, file } = fileParseResult;
-        // Only process files that have content with a config section
-        if (!content?.config) {
+        if (!content) {
             return fileParseResult;
         }
-        const configWithVariablesReplaced = replaceVariablesInValue(content.config, file, profileVariables);
+        const uidWithVariablesReplaced = interpolate(file, content.uid, profileVariables);
+        const configWithVariablesReplaced = content.config
+            ? replaceVariablesInValue(content.config, file, profileVariables)
+            : content.config;
         return {
             ...fileParseResult,
             content: {
                 ...content,
+                uid: uidWithVariablesReplaced,
                 config: configWithVariablesReplaced,
             },
         };

package/src/lib/project.d.ts

@@ -1,3 +1,9 @@
+import { ProjectConfig } from './types.js';
+export declare class ProjectConfigValidationError extends Error {
+    constructor(message: string);
+}
+export declare function parseProjectConfig(projectDir: string): ProjectConfig;
+export declare function validateProjectConfig(config: unknown, projectDir: string): asserts config is ProjectConfig;
 export interface ComponentMetadata {
     count: number;
     maxCount: number;

package/src/lib/project.js

@@ -1,7 +1,58 @@
-import { Components } from './constants.js';
+import { Components, HS_PROJECT_JSON_FILENAME } from './constants.js';
 import { locateHsMetaFiles } from './files.js';
+import { errorMessages } from '../lang/copy.js';
 import path from 'path';
 import fs from 'fs';
+export class ProjectConfigValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProjectConfigValidationError';
+    }
+}
+export function parseProjectConfig(projectDir) {
+    const configPath = path.join(projectDir, HS_PROJECT_JSON_FILENAME);
+    let rawConfig;
+    try {
+        rawConfig = fs.readFileSync(configPath, 'utf-8');
+    }
+    catch {
+        throw new ProjectConfigValidationError(errorMessages.projectConfig.couldNotRead(projectDir));
+    }
+    let config;
+    try {
+        config = JSON.parse(rawConfig);
+    }
+    catch {
+        throw new ProjectConfigValidationError(errorMessages.projectConfig.invalidJson);
+    }
+    validateProjectConfig(config, projectDir);
+    return config;
+}
+export function validateProjectConfig(config, projectDir) {
+    if (!config || typeof config !== 'object') {
+        throw new ProjectConfigValidationError(errorMessages.projectConfig.mustBeJsonObject);
+    }
+    const c = config;
+    const missingFields = [];
+    if (!c['name'])
+        missingFields.push('name');
+    if (!c['srcDir'])
+        missingFields.push('srcDir');
+    if (!c['platformVersion'])
+        missingFields.push('platformVersion');
+    if (missingFields.length > 0) {
+        throw new ProjectConfigValidationError(errorMessages.projectConfig.missingRequiredFields(missingFields));
+    }
+    const srcDirResolved = path.resolve(projectDir, c['srcDir']);
+    const projectDirNormalized = path.resolve(projectDir);
+    if (srcDirResolved !== projectDirNormalized &&
+        !srcDirResolved.startsWith(projectDirNormalized + path.sep)) {
+        throw new ProjectConfigValidationError(errorMessages.projectConfig.srcDirOutsideProject);
+    }
+    if (!fs.existsSync(srcDirResolved)) {
+        throw new ProjectConfigValidationError(errorMessages.projectConfig.srcDirNotFound(c['srcDir']));
+    }
+}
 export async function getProjectMetadata(projectSrcDir) {
     const hsMetaFiles = [];
     const components = {};

package/src/lib/translate.js

@@ -3,14 +3,14 @@ import { validateIntermediateRepresentation } from './validation.js';
 import { getIntermediateRepresentation, getParsingErrors, transform, } from './transform.js';
 import { errorMessages } from '../lang/copy.js';
 import { getLocalDevProfileData, getLocalDevProjectNodes, getRemovedNodesAndNodesWithErrors, } from './localDev.js';
-import { isSupportedPlatformVersion } from './platformVersion.js';
+import { isKnownPlatformVersion } from './platformVersion.js';
 const defaultOptions = {
     skipValidation: false,
 };
 export async function translate(translationContext, translationOptions = defaultOptions) {
     const { skipValidation, profile } = translationOptions;
     if (!skipValidation &&
-        !isSupportedPlatformVersion(translationContext.platformVersion)) {
+        !isKnownPlatformVersion(translationContext.platformVersion)) {
         throw new Error(errorMessages.project.unsupportedPlatformVersion(translationContext.platformVersion));
     }
     const { results: metafileContents, skippedFiles } = await loadHsMetaFiles(translationContext);
@@ -32,7 +32,7 @@ export async function translate(translationContext, translationOptions = default
 export async function translateForLocalDev(translationContext, translationOptions) {
     const { skipValidation, profile, projectNodesAtLastUpload } = translationOptions || {};
     if (!skipValidation &&
-        !isSupportedPlatformVersion(translationContext.platformVersion)) {
+        !isKnownPlatformVersion(translationContext.platformVersion)) {
         throw new Error(errorMessages.project.unsupportedPlatformVersion(translationContext.platformVersion));
     }
     const { results: metafileContents, skippedFiles } = await loadHsMetaFiles(translationContext);

package/src/lib/types.d.ts

@@ -72,6 +72,12 @@ export type Transformation = {
 export type CompiledError = {
     errors: string[];
 };
+export interface ProjectConfig {
+    name: string;
+    srcDir: string;
+    platformVersion: string;
+    [key: string]: unknown;
+}
 export interface TranslationContext {
     projectSourceDir: string;
     platformVersion: string;

package/src/lib/validation.js

@@ -2,10 +2,10 @@ import { getIntermediateRepresentationSchema } from './schemas.js';
 import { Ajv2020, } from 'ajv/dist/2020.js';
 import { compileError, TranslationError } from './errors.js';
 import { errorMessages } from '../lang/copy.js';
-import { AUTO_GENERATED_COMPONENT_TYPES, Components } from './constants.js';
+import { AUTO_GENERATED_COMPONENT_TYPES, Components, PLATFORM_VERSIONS, } from './constants.js';
 import path from 'path';
 import { findTransformationByUid, mapToUserFacingType } from './transform.js';
-import { supportsComponentPermissions } from './platformVersion.js';
+import { meetsMinimumPlatformVersion } from './platformVersion.js';
 import { validateUid } from './uid.js';
 // ajv-formats does not play nicely with ESM and TS
 import addFormatsModule from 'ajv-formats';
@@ -49,7 +49,7 @@ function validateIntermediateRepresentationNode(schema, transformation, irNode,
         shouldSkipValidation = true;
     }
     if (irNode.permissions &&
-        !supportsComponentPermissions(translationContext.platformVersion)) {
+        !meetsMinimumPlatformVersion(translationContext.platformVersion, PLATFORM_VERSIONS.v2026_09_BETA)) {
         transformation.fileParseResult.errors.push(errorMessages.validation.permissionsNotSupported(translationContext.platformVersion));
     }
     if (!schema[irNode.componentType]) {