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

package/src/lib/minimalArboristTree.js

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Creates a minimal tree object that satisfies npm-packlist's requirements
+ * without importing the heavy @npmcli/arborist package.
+ *
+ * @param dir - Directory containing the package
+ * @returns Minimal tree object compatible with npm-packlist
+ */
+export function createMinimalTree(dir) {
+    let pkgJson = {};
+    try {
+        const content = fs.readFileSync(path.join(dir, 'package.json'), 'utf8');
+        pkgJson = JSON.parse(content);
+    }
+    catch {
+        // Use empty package.json if not found or invalid
+        // npm-packlist handles this gracefully
+    }
+    return {
+        path: dir,
+        package: pkgJson,
+        // Set to null to skip workspace-aware filtering
+        // (we process each workspace independently)
+        workspaces: null,
+        // Set to false to skip bundled dependency handling
+        // (not needed for workspace file collection)
+        isProjectRoot: false,
+        // Empty map - only accessed when isProjectRoot is true
+        edgesOut: new Map(),
+    };
+}

package/src/lib/platformVersion.d.ts

@@ -0,0 +1,8 @@
+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;

package/src/lib/platformVersion.js

@@ -0,0 +1,74 @@
+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;
+export function isKnownPlatformVersion(platformVersion) {
+    if (!platformVersion) {
+        return false;
+    }
+    if (process.env.HUBSPOT_PROJECT_INTERNAL_TEST === 'true')
+        return true;
+    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 || typeof platformVersion !== 'string')
+        return false;
+    if (process.env.HUBSPOT_PROJECT_INTERNAL_TEST === 'true')
+        return false;
+    return !meetsMinimumPlatformVersion(platformVersion, PLATFORM_VERSIONS.v2025_2);
+}

package/src/lib/profiles.d.ts

@@ -1,5 +1,10 @@
-import { FileParseResult, HsProfileFile } from './types';
+import { FileParseResult, HsProfileFile, HSProfileVariables } from './types.js';
 export declare function getIsProfileFile(filename: string): boolean;
 export declare function getHsProfileFilename(profileName: string): string;
 export declare function getHsProfileName(profileFilename: string): string;
+export declare function getHsProfileVariables(hsProfileContents: HsProfileFile): HSProfileVariables;
+export declare function validateProfileVariables(profileVariables: HSProfileVariables, filename: string): {
+    success: boolean;
+    errors: string[];
+};
 export declare function applyHsProfileVariables(fileParseResults: FileParseResult[], hsProfileContents: HsProfileFile): FileParseResult[];

package/src/lib/profiles.js

@@ -1,56 +1,114 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getIsProfileFile = getIsProfileFile;
-exports.getHsProfileFilename = getHsProfileFilename;
-exports.getHsProfileName = getHsProfileName;
-exports.applyHsProfileVariables = applyHsProfileVariables;
-const constants_1 = require("./constants");
-const copy_1 = require("../lang/copy");
-const profileFilenameRegex = new RegExp(`^${constants_1.profileFilePrefix}\\.([^.]+)\\.json$`);
+import { PROFILE_FILE_PREFIX } from './constants.js';
+import { errorMessages } from '../lang/copy.js';
+const profileFilenameRegex = new RegExp(`^${PROFILE_FILE_PREFIX}\\.([^.]+)\\.json$`);
+// Regex to match variable placeholders like ${variableName}
 const profileInsertRegex = /\${(.*?)}/g;
-function getIsProfileFile(filename) {
+// Helper to check if string is a single variable reference (e.g., "${port}" but not "http://${port}")
+// Returns the variable key if it matches, null otherwise
+function isSingleVariableReference(str) {
+    const match = str.match(/^\${([^}]+)}$/);
+    return match ? match[1] : null;
+}
+export function getIsProfileFile(filename) {
     return profileFilenameRegex.test(filename);
 }
-function getHsProfileFilename(profileName) {
-    return `${constants_1.profileFilePrefix}.${profileName}.json`;
+export function getHsProfileFilename(profileName) {
+    return `${PROFILE_FILE_PREFIX}.${profileName}.json`;
 }
-function getHsProfileName(profileFilename) {
+export function getHsProfileName(profileFilename) {
     const match = profileFilename.match(profileFilenameRegex);
     return match ? match[1] : '';
 }
-function interpolate(file, template, profileVariables) {
-    return template.replace(profileInsertRegex, (__match, key) => {
-        const profileVariableType = typeof profileVariables[key];
-        if (profileVariableType === 'undefined') {
-            throw new Error(copy_1.errorMessages.profile.missingValue(key, file));
+export function getHsProfileVariables(hsProfileContents) {
+    const profileVariablesAreValid = hsProfileContents?.variables &&
+        typeof hsProfileContents.variables === 'object' &&
+        !Array.isArray(hsProfileContents.variables);
+    return profileVariablesAreValid ? hsProfileContents.variables : {};
+}
+export function validateProfileVariables(profileVariables, filename) {
+    const errors = [];
+    for (const [variableKey, variableValue] of Object.entries(profileVariables)) {
+        try {
+            const variableType = typeof variableValue;
+            validateProfileVariable(variableType, variableKey, filename);
         }
-        if (!['string', 'number', 'boolean'].includes(profileVariableType)) {
-            throw new Error(copy_1.errorMessages.profile.invalidValue(key));
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            errors.push(errorMessage);
         }
-        return String(profileVariables[key]);
+    }
+    return {
+        success: errors.length === 0,
+        errors,
+    };
+}
+function validateProfileVariable(variableType, variableKey, filename) {
+    const allowedTypes = ['string', 'number', 'boolean'];
+    if (variableType === 'undefined') {
+        throw new Error(errorMessages.profile.missingValue(variableKey, filename));
+    }
+    if (!allowedTypes.includes(variableType)) {
+        throw new Error(errorMessages.profile.invalidValue(variableKey));
+    }
+}
+function interpolate(file, template, profileVariables) {
+    return template.replace(profileInsertRegex, (_fullMatch, variableKey) => {
+        const variableValue = profileVariables[variableKey];
+        const variableType = typeof variableValue;
+        validateProfileVariable(variableType, variableKey, file);
+        return String(variableValue);
     });
 }
-function applyHsProfileVariables(fileParseResults, hsProfileContents) {
-    const profileVariables = hsProfileContents?.variables &&
-        typeof hsProfileContents.variables === 'object' &&
-        !Array.isArray(hsProfileContents.variables)
-        ? hsProfileContents.variables
-        : {};
+function replaceVariablesInValue(value, file, profileVariables) {
+    // Handle string values with variable substitution
+    if (typeof value === 'string') {
+        // If the entire value is a single variable (e.g., "${port}"),
+        // return the typed value to preserve number/boolean types
+        const variableKey = isSingleVariableReference(value);
+        if (variableKey) {
+            const variableValue = profileVariables[variableKey];
+            const variableType = typeof variableValue;
+            validateProfileVariable(variableType, variableKey, file);
+            return variableValue;
+        }
+        // Otherwise, perform string interpolation (no-op if no variables found)
+        // For strings with multiple variables (e.g., "http://${host}:${port}"),
+        // this converts all values to strings
+        return interpolate(file, value, profileVariables);
+    }
+    // Recursively handle arrays
+    if (Array.isArray(value)) {
+        return value.map(item => replaceVariablesInValue(item, file, profileVariables));
+    }
+    // Recursively handle objects
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = replaceVariablesInValue(val, file, profileVariables);
+        }
+        return result;
+    }
+    // Return primitive values as-is
+    return value;
+}
+export function applyHsProfileVariables(fileParseResults, hsProfileContents) {
+    const profileVariables = getHsProfileVariables(hsProfileContents);
     return fileParseResults.map(fileParseResult => {
         const { content, file } = fileParseResult;
-        if (content && content.config) {
-            let interpolatedConfig = content.config;
-            interpolatedConfig = JSON.parse(interpolate(file, JSON.stringify(content.config), profileVariables));
-            if (interpolatedConfig) {
-                return {
-                    ...fileParseResult,
-                    content: {
-                        ...content,
-                        config: interpolatedConfig,
-                    },
-                };
-            }
+        if (!content) {
+            return fileParseResult;
         }
-        return fileParseResult;
+        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,28 +1,84 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getProjectMetadata = getProjectMetadata;
-const constants_1 = require("./constants");
-const files_1 = require("./files");
-const path_1 = __importDefault(require("path"));
-async function getProjectMetadata(projectSrcDir) {
+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 = {};
-    const metafiles = await (0, files_1.locateHsMetaFiles)(projectSrcDir, { silent: true });
-    Object.keys(constants_1.Components).forEach(componentType => {
-        const { parentComponent, singularComponent, dir } = constants_1.Components[componentType];
-        const componentPath = path_1.default.join(projectSrcDir, parentComponent ? path_1.default.join(parentComponent, dir) : dir);
+    let metafiles = [];
+    if (fs.existsSync(projectSrcDir)) {
+        ({ metaFiles: metafiles } = await locateHsMetaFiles(projectSrcDir));
+    }
+    const seenComponentPaths = new Map();
+    Object.keys(Components).forEach(componentType => {
+        const { parentComponent, singularComponent, dir } = Components[componentType];
+        const componentPath = path.join(projectSrcDir, parentComponent ? path.join(parentComponent, dir) : dir);
+        if (seenComponentPaths.has(componentPath)) {
+            components[componentType] = seenComponentPaths.get(componentPath);
+            return;
+        }
         const metaFilesByType = metafiles
-            .filter(metafile => path_1.default.parse(metafile.file).dir === componentPath)
+            .filter(metafile => path.parse(metafile.file).dir === componentPath)
             .map(metaFile => metaFile.file);
-        hsMetaFiles.push(...metaFilesByType);
-        components[componentType] = {
+        const metadata = {
             hsMetaFiles: metaFilesByType,
             count: metaFilesByType.length,
             maxCount: singularComponent ? 1 : Infinity,
         };
+        hsMetaFiles.push(...metaFilesByType);
+        seenComponentPaths.set(componentPath, metadata);
+        components[componentType] = metadata;
     });
     return {
         hsMetaFiles,

package/src/lib/schemas.d.ts

@@ -1,3 +1,3 @@
-import { AnySchema } from 'ajv/dist/2020';
-import { TranslationContext } from './types';
+import type { AnySchema } from 'ajv';
+import { TranslationContext } from './types.js';
 export declare function getIntermediateRepresentationSchema(translationContext: TranslationContext): Promise<Record<string, AnySchema>>;

package/src/lib/schemas.js

@@ -1,24 +1,24 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getIntermediateRepresentationSchema = getIntermediateRepresentationSchema;
-const http_1 = require("@hubspot/local-dev-lib/http");
-const index_1 = require("@hubspot/local-dev-lib/errors/index");
-const copy_1 = require("../lang/copy");
-async function getIntermediateRepresentationSchema(translationContext) {
+import { http } from '@hubspot/local-dev-lib/http';
+import { isHubSpotHttpError, isSpecifiedError, } from '@hubspot/local-dev-lib/errors/index';
+import { errorMessages } from '../lang/copy.js';
+export async function getIntermediateRepresentationSchema(translationContext) {
     if (!translationContext.accountId) {
-        throw new Error(copy_1.errorMessages.api.accountIdIsRequiredToFetchSchemas);
+        throw new Error(errorMessages.api.accountIdIsRequiredToFetchSchemas);
     }
     try {
         const { accountId, platformVersion } = translationContext;
-        const { data } = await http_1.http.get(accountId, {
+        const { data } = await http.get(accountId, {
             url: `project-components-external/project-schemas/v3/${platformVersion}`,
         });
         return data;
     }
     catch (e) {
-        if ((0, index_1.isHubSpotHttpError)(e)) {
+        if (isSpecifiedError(e, { statusCode: 403 })) {
+            throw new Error(errorMessages.api.failedToFetchSchemas403, { cause: e });
+        }
+        if (isHubSpotHttpError(e)) {
             throw e;
         }
-        throw new Error(copy_1.errorMessages.api.failedToFetchSchemas, { cause: e });
+        throw new Error(errorMessages.api.failedToFetchSchemas, { cause: e });
     }
 }

package/src/lib/transform.d.ts

@@ -1,9 +1,11 @@
-import { Dependencies, FileParseResult, HsProfileFile, IntermediateRepresentation, Transformation, TranslationContext } from './types';
+import { Dependencies, FileParseResult, HsProfileFile, IntermediateRepresentation, Transformation, TranslationContext } from './types.js';
 export declare function mapToInternalType(type: string): string;
 export declare function mapToUserFacingType(type: string): string;
 export declare function mapToUserFriendlyName(internalType: string): string;
+export declare function findTransformationByUid(transformations: Transformation[], uid: string): Transformation | undefined;
 export declare function transform(fileParseResults: FileParseResult[], translationContext: TranslationContext, hsProfileContents?: HsProfileFile): Transformation[];
-export declare function getIntermediateRepresentation(transformations: Transformation[], skipValidation: boolean | undefined): IntermediateRepresentation;
+export declare function getIntermediateRepresentation(transformations: Transformation[], hsProfileContents?: HsProfileFile, skipValidation?: boolean): IntermediateRepresentation;
+export declare function getParsingErrors(transformations: Transformation[]): FileParseResult[];
 export declare function generateServerlessPackageComponent(appFunctionsDirectory: string, translationContext: TranslationContext, componentDeps: Dependencies): {
     uid: string;
     transformation: Transformation;