@hubspot/project-parsing-lib 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hubspot/project-parsing-lib",
-    "version": "0.21.0",
+    "version": "0.22.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.1",
+        "@hubspot/npm-scripts": "^0.3.3",
         "@inquirer/prompts": "^7.1.0",
         "@types/node": "^24.9.0",
         "@types/npm-packlist": "7.0.3",
@@ -115,6 +115,7 @@
         "@types/semver": "^7.5.8",
         "@typescript-eslint/eslint-plugin": "8.54.0",
         "@typescript-eslint/parser": "8.54.0",
+        "@vitest/coverage-v8": "^3.2.7",
         "eslint": "^9.38.0",
         "eslint-plugin-import": "^2.31.0",
         "husky": "^9.1.7",
@@ -150,7 +151,7 @@
         "local-dev": "yarn build && cd dist && yarn link && cd .. && tsc --watch --rootDir . --outdir dist",
         "local-link": "hubspot-linking",
         "prettier:write": "prettier ./src/** --write",
-        "test": "vitest run",
+        "test": "vitest run --coverage",
         "release": "tsx ./scripts/release.ts release",
         "acceptance-test": "yarn --cwd=./acceptance-tests test"
     },

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 { 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, 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/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/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;