@hubspot/project-parsing-lib 0.19.2 → 0.20.0-beta.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.19.2",
+    "version": "0.20.0-beta.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",

package/src/exports/projects.d.ts

@@ -1,4 +1,4 @@
 export { getProjectMetadata } from '../lib/project.js';
 export { projectContainsHsMetaFiles } from '../lib/files.js';
 export type { ProjectMetadata } from '../lib/project.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/exports/projects.js

@@ -1,3 +1,3 @@
 export { getProjectMetadata } 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/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";

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',

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/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/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]) {