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

package/src/lib/files.js

@@ -1,66 +1,59 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadHsProfileFile = loadHsProfileFile;
-exports.getAllHsProfiles = getAllHsProfiles;
-exports.loadHsMetaFiles = loadHsMetaFiles;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const fs_2 = require("@hubspot/local-dev-lib/fs");
-const constants_1 = require("./constants");
-const copy_1 = require("../lang/copy");
-const logger_1 = require("@hubspot/local-dev-lib/logger");
-const profiles_1 = require("./profiles");
-function loadHsProfileFile(projectSourceDir, profile) {
+import fs from 'fs';
+import path from 'path';
+import { walk } from '@hubspot/local-dev-lib/fs';
+import { ALLOWED_COMPONENT_DIRECTORIES, ALLOWED_SUB_COMPONENT_DIRECTORIES, METAFILE_EXTENSION, ALLOWED_TOP_LEVEL_FIELDS, } from './constants.js';
+import { errorMessages, logMessages } from '../lang/copy.js';
+import { logger } from '@hubspot/local-dev-lib/logger';
+import { getHsProfileFilename, getHsProfileName, getIsProfileFile, } from './profiles.js';
+export function loadHsProfileFile(projectSourceDir, profile) {
     if (!profile) {
-        throw new Error(copy_1.errorMessages.profile.noProfileSpecified);
+        throw new Error(errorMessages.profile.noProfileSpecified);
     }
-    const profileFile = (0, profiles_1.getHsProfileFilename)(profile);
-    const profileFilepath = path_1.default.join(projectSourceDir, profileFile);
+    const profileFile = getHsProfileFilename(profile);
+    const profileFilepath = path.join(projectSourceDir, profileFile);
     let hsProfile;
     try {
-        hsProfile = JSON.parse(fs_1.default.readFileSync(profileFilepath, 'utf8'));
+        hsProfile = JSON.parse(fs.readFileSync(profileFilepath, 'utf8'));
     }
     catch (_e) {
-        throw new Error(copy_1.errorMessages.profile.failedToLoadHsProfile(profileFile));
+        throw new Error(errorMessages.profile.failedToLoadHsProfile(profileFile));
     }
     return hsProfile;
 }
-function getAllHsProfiles(projectSourceDir) {
+export function getAllHsProfiles(projectSourceDir) {
     return new Promise((resolve, _reject) => {
-        fs_1.default.readdir(projectSourceDir, { recursive: false, withFileTypes: true }, (err, files) => {
+        fs.readdir(projectSourceDir, { recursive: false, withFileTypes: true }, (err, files) => {
             if (err) {
                 return resolve([]);
             }
             return resolve(files
-                .filter(file => file.isFile() && (0, profiles_1.getIsProfileFile)(file.name))
-                .map(file => (0, profiles_1.getHsProfileName)(file.name)));
+                .filter(file => file.isFile() && getIsProfileFile(file.name))
+                .map(file => getHsProfileName(file.name)));
         });
     });
 }
-async function loadHsMetaFiles(translationContext) {
-    const metaFiles = await locateHsMetaFiles(translationContext);
+export async function loadHsMetaFiles(translationContext) {
+    const metaFiles = await locateHsMetaFiles(translationContext.projectSourceDir);
     return parseHsMetaFiles(metaFiles, translationContext);
 }
-async function locateHsMetaFiles(translationContext) {
-    const { projectSourceDir } = translationContext;
-    return (await (0, fs_2.walk)(projectSourceDir, ['node_modules'])).reduce((metaFiles, file) => {
-        if (!file.endsWith(constants_1.metafileExtension)) {
+export async function locateHsMetaFiles(projectSourceDir, options = { silent: false }) {
+    return (await walk(projectSourceDir, ['node_modules'])).reduce((metaFiles, file) => {
+        if (!file.endsWith(METAFILE_EXTENSION)) {
             return metaFiles;
         }
-        const pathRelativeToProjectSrcDir = path_1.default.relative(projectSourceDir, file);
-        const { dir: metaFileDir } = path_1.default.parse(pathRelativeToProjectSrcDir);
-        const parentDirectory = metaFileDir.split(path_1.default.sep)[0];
-        if (constants_1.allowedComponentDirectories.includes(metaFileDir)) {
+        const pathRelativeToProjectSrcDir = path.relative(projectSourceDir, file);
+        const { dir: metaFileDir } = path.parse(pathRelativeToProjectSrcDir);
+        const parentDirectory = metaFileDir.split(path.sep)[0];
+        if (ALLOWED_COMPONENT_DIRECTORIES.includes(metaFileDir)) {
             metaFiles.push({ file });
         }
-        else if (constants_1.allowedSubComponentDirectories.includes(metaFileDir)) {
+        else if (ALLOWED_SUB_COMPONENT_DIRECTORIES.includes(metaFileDir)) {
             metaFiles.push({ file, parentDirectory });
         }
         else {
-            logger_1.logger.warn(copy_1.logMessages.files.skippingPath(pathRelativeToProjectSrcDir));
+            if (!options.silent) {
+                logger.warn(logMessages.files.skippingPath(pathRelativeToProjectSrcDir));
+            }
         }
         return metaFiles;
     }, []);
@@ -75,7 +68,7 @@ function loadFile(metaFileLocation, translationContext) {
     const { projectSourceDir } = translationContext;
     return new Promise(async (resolve) => {
         const { file, parentDirectory } = metaFileLocation;
-        fs_1.default.readFile(file, 'utf-8', (err, content) => {
+        fs.readFile(file, 'utf-8', (err, content) => {
             if (err) {
                 return resolve({
                     file,
@@ -83,7 +76,7 @@ function loadFile(metaFileLocation, translationContext) {
                 });
             }
             resolve({
-                file: path_1.default.relative(projectSourceDir, file),
+                file: path.relative(projectSourceDir, file),
                 content,
                 parentDirectory,
                 errors: [],
@@ -101,7 +94,25 @@ function parseFile(fileLoadResult) {
         parsedFileContents = JSON.parse(fileLoadResult.content);
     }
     catch (_e) {
-        fileLoadResult.errors?.push(copy_1.errorMessages.validation.invalidJson);
+        fileLoadResult.errors?.push(errorMessages.validation.invalidJson);
+    }
+    // Validate top-level fields (only uid, type, and config are expected)
+    if (parsedFileContents &&
+        typeof parsedFileContents === 'object' &&
+        !Array.isArray(parsedFileContents)) {
+        const actualFields = Object.keys(parsedFileContents);
+        const unexpectedFields = actualFields.filter(field => !ALLOWED_TOP_LEVEL_FIELDS.has(field));
+        if (unexpectedFields.length > 0) {
+            const unexpectedFieldsList = unexpectedFields.join(', ');
+            fileLoadResult.errors?.push(errorMessages.validation.unexpectedToplevelFields(unexpectedFieldsList));
+        }
     }
     return { ...fileLoadResult, content: parsedFileContents };
 }
+export async function projectContainsHsMetaFiles(projectSourceDir) {
+    const hsMetaFiles = (await walk(projectSourceDir, ['node_modules'])).filter(file => file.endsWith(METAFILE_EXTENSION));
+    return hsMetaFiles.length > 0;
+}
+export function convertPathToPosixPath(filepath) {
+    return filepath.replaceAll(path.win32.sep, path.posix.sep);
+}

package/src/lib/localDev.d.ts

@@ -0,0 +1,4 @@
+import { BEProfileVariables, HSProfileVariables, IntermediateRepresentationNode, IntermediateRepresentationNodeLocalDev, FileParseResult } from './types.js';
+export declare function getLocalDevProjectNodes(intermediateNodesIndexedByUid: Record<string, IntermediateRepresentationNode>, projectSourceDir: string, projectNodesAtLastUpload?: Record<string, IntermediateRepresentationNodeLocalDev>): Record<string, IntermediateRepresentationNodeLocalDev>;
+export declare function getRemovedNodesAndNodesWithErrors(intermediateNodesIndexedByUid: Record<string, IntermediateRepresentationNode>, projectNodesAtLastUpload: Record<string, IntermediateRepresentationNodeLocalDev>, parsingErrors: FileParseResult[]): Record<string, IntermediateRepresentationNodeLocalDev>;
+export declare function getLocalDevProfileData(profileVariables?: BEProfileVariables): HSProfileVariables;

package/src/lib/localDev.js

@@ -0,0 +1,72 @@
+import path from 'path';
+import { isDeepEqual } from '@hubspot/local-dev-lib/isDeepEqual';
+export function getLocalDevProjectNodes(intermediateNodesIndexedByUid, projectSourceDir, projectNodesAtLastUpload) {
+    const localDevProjectNodes = {};
+    Object.entries(intermediateNodesIndexedByUid).forEach(([uid, node]) => {
+        const component = intermediateNodesIndexedByUid[uid];
+        const componentConfigPath = path.join(projectSourceDir, component.metaFilePath);
+        let configUpdatedSinceLastUpload = false;
+        if (projectNodesAtLastUpload) {
+            const componentAtLastUpload = projectNodesAtLastUpload[uid];
+            if (componentAtLastUpload) {
+                configUpdatedSinceLastUpload = !isDeepEqual(component.config, componentAtLastUpload.config);
+            }
+            else {
+                // Component is net new
+                configUpdatedSinceLastUpload = true;
+            }
+        }
+        localDevProjectNodes[uid] = {
+            ...node,
+            localDev: {
+                componentRoot: path.dirname(componentConfigPath),
+                componentConfigPath,
+                configUpdatedSinceLastUpload,
+                removed: false,
+                parsingErrors: [],
+            },
+        };
+    });
+    return localDevProjectNodes;
+}
+export function getRemovedNodesAndNodesWithErrors(intermediateNodesIndexedByUid, projectNodesAtLastUpload, parsingErrors) {
+    const nodesWithErrors = {};
+    Object.entries(projectNodesAtLastUpload).forEach(([uid, node]) => {
+        // Node is still in the project
+        if (intermediateNodesIndexedByUid[uid]) {
+            return;
+            // Node has parsing errors but was not removed
+        }
+        const errorForNode = parsingErrors.find(error => error.file === node.metaFilePath);
+        if (errorForNode) {
+            nodesWithErrors[uid] = {
+                ...node,
+                localDev: {
+                    ...node.localDev,
+                    parsingErrors: errorForNode.errors,
+                },
+            };
+            //  Node was removed since the last upload
+        }
+        else {
+            nodesWithErrors[uid] = {
+                ...node,
+                localDev: {
+                    ...node.localDev,
+                    removed: true,
+                },
+            };
+        }
+    });
+    return nodesWithErrors;
+}
+export function getLocalDevProfileData(profileVariables) {
+    if (!profileVariables) {
+        return {};
+    }
+    const localDevProfileData = {};
+    Object.entries(profileVariables).forEach(([key, value]) => {
+        localDevProfileData[key] = value.value;
+    });
+    return localDevProfileData;
+}

package/src/lib/migrate.d.ts

@@ -1 +1,2 @@
+export declare const OUTPUT_IR_FILE = "FULL_IR.json";
 export declare function migrate(inputDir: string, outputDir: string): Promise<void>;

package/src/lib/migrate.js

@@ -1,35 +1,30 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.migrate = migrate;
-const fs_1 = require("@hubspot/local-dev-lib/fs");
-const path_1 = __importDefault(require("path"));
-const fs_2 = __importDefault(require("fs"));
-const transform_1 = require("./transform");
-const constants_1 = require("./constants");
-const index_1 = require("../index");
+import { walk } from '@hubspot/local-dev-lib/fs';
+import path from 'path';
+import fs from 'fs';
+import { mapToUserFacingType } from './transform.js';
+import { METAFILE_EXTENSION, Components, HS_PROJECT_JSON_FILENAME, APP_FUNCTIONS_PACKAGE_KEY, APP_FUNCTIONS_KEY, } from './constants.js';
+import { translate } from './translate.js';
+import { loadJsonFile } from './utils.js';
 const IR_FILENAME = 'ir.json';
 const filesDirectory = 'files';
-const OUTPUT_IR_FILE = 'FULL_IR.json';
-async function migrate(inputDir, outputDir) {
-    if (!fs_2.default.existsSync(inputDir)) {
+export const OUTPUT_IR_FILE = 'FULL_IR.json';
+export async function migrate(inputDir, outputDir) {
+    if (!fs.existsSync(inputDir)) {
         throw new Error(`Input directory ${inputDir} does not exist`);
     }
-    const hsProjectJsonPath = path_1.default.join(inputDir, constants_1.hsProjectJsonFilename);
-    if (!fs_2.default.existsSync(hsProjectJsonPath)) {
-        throw new Error(`${constants_1.hsProjectJsonFilename} file does not exist in ${inputDir}`);
+    const hsProjectJsonPath = path.join(inputDir, HS_PROJECT_JSON_FILENAME);
+    if (!fs.existsSync(hsProjectJsonPath)) {
+        throw new Error(`${HS_PROJECT_JSON_FILENAME} file does not exist in ${inputDir}`);
     }
     let hsProjectJson;
     try {
         hsProjectJson = loadJsonFile(hsProjectJsonPath);
     }
     catch (e) {
-        throw new Error(`Error parsing ${constants_1.hsProjectJsonFilename}: ${e}`);
+        throw new Error(`Error parsing ${HS_PROJECT_JSON_FILENAME}: ${e}`);
     }
-    const files = await (0, fs_1.walk)(inputDir);
-    const sourceCodeOutputDir = path_1.default.join(outputDir, 'src');
+    const files = await walk(inputDir);
+    const sourceCodeOutputDir = path.join(outputDir, 'src');
     // Create the output directory if it doesn't exist
     ensureDirExists(sourceCodeOutputDir);
     files.forEach((filename) => {
@@ -37,63 +32,66 @@ async function migrate(inputDir, outputDir) {
         if (!isIRFile(filename)) {
             return;
         }
-        const irDirName = path_1.default.dirname(filename);
+        const irDirName = path.dirname(filename);
         const IR = loadJsonFile(filename);
         const { metaFilePath } = IR;
-        const projectConfig = convertIRToProjectConfig(IR);
-        const fullOutputPath = path_1.default.join(sourceCodeOutputDir, getTargetDirectoryFromComponentType(projectConfig.type));
+        const component = convertIRToProjectConfig(IR);
+        const fullOutputPath = path.join(sourceCodeOutputDir, getTargetDirectoryFromComponentType(component.type));
         // Ensure the output directory exists
-        const currentFilesDirectory = path_1.default.join(irDirName, filesDirectory);
+        const currentFilesDirectory = path.join(irDirName, filesDirectory);
         ensureDirExists(currentFilesDirectory);
-        fs_2.default.cpSync(currentFilesDirectory, fullOutputPath, {
+        fs.cpSync(currentFilesDirectory, fullOutputPath, {
             recursive: true,
         });
+        // In the current component is a APP_FUNCTIONS_PACKAGE we don't want to write a hsmeta.json file
+        // since it is an auto generate component
+        if (component.type === APP_FUNCTIONS_PACKAGE_KEY) {
+            return;
+        }
         // Use the metaFilePath if provided, otherwise use the project UID
-        const hsmetaFilePath = path_1.default.join(fullOutputPath, metaFilePath
-            ? path_1.default.basename(metaFilePath)
-            : `${projectConfig.uid}${constants_1.metafileExtension}`);
+        const hsmetaFilePath = path.join(fullOutputPath, metaFilePath
+            ? path.basename(metaFilePath)
+            : `${component.uid}${METAFILE_EXTENSION}`);
         // Write the hsmeta file to the output directory
-        fs_2.default.writeFileSync(hsmetaFilePath, JSON.stringify(projectConfig, null, 2));
+        fs.writeFileSync(hsmetaFilePath, JSON.stringify(component, null, 2));
     });
-    const IR = await (0, index_1.translate)({
+    const IR = await translate({
         projectSourceDir: sourceCodeOutputDir,
         platformVersion: hsProjectJson.platformVersion,
     }, { skipValidation: true });
     // Write the IR file to the output directory
-    fs_2.default.writeFileSync(path_1.default.join(outputDir, OUTPUT_IR_FILE), JSON.stringify(IR, null, 2));
+    fs.writeFileSync(path.join(outputDir, OUTPUT_IR_FILE), JSON.stringify(IR, null, 2));
 }
 function ensureDirExists(dir) {
-    if (!fs_2.default.existsSync(dir)) {
-        fs_2.default.mkdirSync(dir, { recursive: true });
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
     }
 }
 function isIRFile(filename) {
-    const { base } = path_1.default.parse(filename);
+    const { base } = path.parse(filename);
     return base.toLowerCase() === IR_FILENAME;
 }
-function loadJsonFile(filename) {
-    return JSON.parse(fs_2.default.readFileSync(filename, {
-        encoding: 'utf-8',
-    }));
-}
 function convertIRToProjectConfig(IR) {
     const { config, uid, componentType } = IR;
     return {
         config,
         uid,
-        type: (0, transform_1.mapToUserFacingType)(componentType),
+        type: mapToUserFacingType(componentType),
         // We are assuming no dependencies for now since this will be a freshly migrated
         // project and the current supported components don't have non-hierarchical dependencies
         dependencies: undefined,
     };
 }
 function getTargetDirectoryFromComponentType(componentType) {
-    const component = constants_1.Components[componentType];
+    let component = Components[componentType];
+    if (componentType === APP_FUNCTIONS_PACKAGE_KEY) {
+        component = Components[APP_FUNCTIONS_KEY];
+    }
     if (!component) {
-        throw Error('Unsupported component type');
+        throw Error(`Unsupported component type: "${componentType}"`);
     }
     const parentDirectory = component.parentComponent
-        ? constants_1.Components[component.parentComponent].dir
+        ? Components[component.parentComponent].dir
         : '';
-    return path_1.default.join(parentDirectory, component.dir);
+    return path.join(parentDirectory, component.dir);
 }

package/src/lib/migrateThemes.d.ts

@@ -0,0 +1,25 @@
+export type ThemeDetails = {
+    configFilepath: string;
+    themePath: string;
+    themeConfig: {
+        secret_names?: string[];
+    };
+};
+export type ReactThemeDetails = {
+    configFilepath: string;
+    themePath: string;
+    themeConfig: {
+        secretNames?: string[];
+    };
+};
+export type ProjectThemeDetails = {
+    legacyThemeDetails: ThemeDetails[];
+    legacyReactThemeDetails: ReactThemeDetails[];
+};
+export declare function getProjectThemeDetails(projectSourceDir: string): Promise<ProjectThemeDetails>;
+export declare function migrateThemes(projectDir: string, projectSourceDir: string): Promise<{
+    legacyThemeDetails: ThemeDetails[];
+    legacyReactThemeDetails: ReactThemeDetails[];
+    migrated: boolean;
+    failureReason?: string;
+}>;

package/src/lib/migrateThemes.js

@@ -0,0 +1,120 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { promisify } from 'util';
+import { walk } from '@hubspot/local-dev-lib/fs';
+import { THEME_KEY, CMS_ASSETS_KEY, METAFILE_EXTENSION } from './constants.js';
+import { loadJsonFile } from './utils.js';
+import { errorMessages } from '../lang/copy.js';
+const mkdtempAsync = promisify(fs.mkdtemp);
+const LEGACY_THEME_CONFIG = 'theme.json';
+const LEGACY_REACT_THEME_CONFIG = 'cms-assets.json';
+export async function getProjectThemeDetails(projectSourceDir) {
+    const files = await walk(projectSourceDir, ['node_modules']);
+    const legacyThemeDetails = [];
+    const legacyReactThemeDetails = [];
+    files.forEach((filename) => {
+        const isLegacyThemeConfig = filename.endsWith(LEGACY_THEME_CONFIG);
+        const isLegacyReactThemeConfig = filename.endsWith(LEGACY_REACT_THEME_CONFIG);
+        if (isLegacyThemeConfig || isLegacyReactThemeConfig) {
+            const parsedConfig = loadJsonFile(filename);
+            const themeDetails = {
+                configFilepath: filename,
+                themePath: path.dirname(filename),
+                themeConfig: parsedConfig,
+            };
+            if (isLegacyThemeConfig) {
+                legacyThemeDetails.push(themeDetails);
+            }
+            else {
+                legacyReactThemeDetails.push(themeDetails);
+            }
+        }
+    });
+    return {
+        legacyThemeDetails,
+        legacyReactThemeDetails,
+    };
+}
+function buildNewTheme(componentKey, migratedProjectTempDir, themeDetails) {
+    const themeName = path.basename(themeDetails.themePath);
+    const componentDir = path.join(migratedProjectTempDir, componentKey);
+    const newThemeDir = path.join(componentDir, themeName);
+    fs.cpSync(themeDetails.themePath, newThemeDir, {
+        recursive: true,
+    });
+    const newThemeConfig = {
+        uid: themeName,
+        type: componentKey,
+        config: {
+            themePath: themeName,
+            secretNames: [],
+        },
+    };
+    // Remove secrets from the legacy theme config if they exist & move them to the new theme config
+    let updatedLegacyThemeConfig;
+    if ('secret_names' in themeDetails.themeConfig) {
+        const { secret_names, ...configWithoutSecrets } = themeDetails.themeConfig;
+        if (secret_names) {
+            newThemeConfig.config.secretNames = secret_names;
+            updatedLegacyThemeConfig = configWithoutSecrets;
+        }
+    }
+    else if ('secretNames' in themeDetails.themeConfig) {
+        const { secretNames, ...configWithoutSecrets } = themeDetails.themeConfig;
+        if (secretNames) {
+            newThemeConfig.config.secretNames = secretNames;
+            updatedLegacyThemeConfig = configWithoutSecrets;
+        }
+    }
+    if (updatedLegacyThemeConfig) {
+        const newLegacyConfigFilepath = path.join(newThemeDir, path.basename(themeDetails.configFilepath));
+        fs.writeFileSync(newLegacyConfigFilepath, JSON.stringify(updatedLegacyThemeConfig, null, 2));
+    }
+    fs.writeFileSync(path.join(componentDir, `${themeName}${METAFILE_EXTENSION}`), JSON.stringify(newThemeConfig, null, 2));
+}
+export async function migrateThemes(projectDir, projectSourceDir) {
+    const { legacyThemeDetails, legacyReactThemeDetails } = await getProjectThemeDetails(projectSourceDir);
+    // Migrate the project to a temporary directory to avoid file conflicts in the original project
+    const migratedProjectTempDir = await mkdtempAsync(path.join(os.tmpdir(), 'hubspot-migrated-project-'));
+    let isRootReactThemeProject = false;
+    legacyReactThemeDetails.forEach(themeDetails => {
+        isRootReactThemeProject = themeDetails.themePath === projectSourceDir;
+        if (!isRootReactThemeProject) {
+            buildNewTheme(CMS_ASSETS_KEY, migratedProjectTempDir, themeDetails);
+        }
+    });
+    // Do not support migrating themes that live at the root of the project src directory
+    if (isRootReactThemeProject) {
+        return {
+            legacyThemeDetails,
+            legacyReactThemeDetails,
+            migrated: false,
+            failureReason: errorMessages.migrateThemes.rootReactThemeNotSupported,
+        };
+    }
+    legacyThemeDetails.forEach(themeDetails => {
+        buildNewTheme(THEME_KEY, migratedProjectTempDir, themeDetails);
+    });
+    // Copy the rest of the project files to the temp directory
+    fs.cpSync(projectSourceDir, migratedProjectTempDir, {
+        recursive: true,
+        filter: src => {
+            return (!legacyThemeDetails.some(file => src.includes(file.themePath)) &&
+                !legacyReactThemeDetails.some(file => src.includes(file.themePath)));
+        },
+    });
+    // Archive the legacy theme files
+    const archiveDest = path.join(projectDir, 'archive');
+    fs.renameSync(projectSourceDir, archiveDest);
+    // Copy the new theme config files to the project source directory
+    fs.cpSync(migratedProjectTempDir, projectSourceDir, {
+        recursive: true,
+    });
+    fs.rmSync(migratedProjectTempDir, { recursive: true });
+    return {
+        legacyThemeDetails,
+        legacyReactThemeDetails,
+        migrated: true,
+    };
+}

package/src/lib/minimalArboristTree.d.ts

@@ -0,0 +1,118 @@
+/**
+ * MINIMAL ARBORIST TREE
+ *
+ * This module provides a lightweight alternative to @npmcli/arborist for use
+ * with npm-packlist. Instead of importing the full arborist package (~3.4MB
+ * with 35+ transitive dependencies), we create a minimal tree object that
+ * satisfies npm-packlist's runtime requirements.
+ *
+ * WHY THIS EXISTS:
+ * - @npmcli/arborist adds ~3.4MB to the bundle
+ * - npm-packlist only uses a small subset of the Arborist Node interface
+ * - For our use case (determining packable files in workspace directories),
+ *   we don't need the full dependency resolution capabilities of arborist
+ *
+ * CONTEXT: HUBSPOT DEVELOPER PROJECTS UPLOAD FLOW
+ *
+ * This library is used to collect files from npm workspace packages for upload
+ * to HubSpot's build system. Important constraints:
+ *
+ * - node_modules/ directories are EXCLUDED from uploads
+ * - The build system runs `npm install` to fetch dependencies
+ * - Source files, package.json, and config files are included
+ *
+ * This means bundleDependencies (which includes files from node_modules/) would
+ * not work even if we used full arborist, because node_modules/ is excluded
+ * from the upload archive. Developers with private registry packages should use
+ * file: dependencies instead, which ARE supported.
+ *
+ * HOW NPM-PACKLIST USES THE TREE (as of npm-packlist@8.0.1):
+ *
+ *   tree.path              - Directory path (REQUIRED)
+ *   tree.package           - Parsed package.json content (REQUIRED)
+ *     .files               - Files array for inclusion
+ *     .main                - Main entry point (always included)
+ *     .bin                 - Binary files (always included)
+ *     .browser             - Browser field (always included)
+ *     .bundleDependencies  - Only used when isProjectRoot=true
+ *     .dependencies        - Only used when isProjectRoot=true
+ *     .optionalDependencies - Only used when isProjectRoot=true
+ *   tree.workspaces        - Map of workspace paths (OPTIONAL, guarded by if-check)
+ *   tree.isProjectRoot     - Boolean for bundled deps handling (OPTIONAL)
+ *   tree.edgesOut          - Dependency edges (only accessed when isProjectRoot=true)
+ *
+ * KNOWN LIMITATIONS:
+ *
+ * 1. BUNDLED DEPENDENCIES NOT SUPPORTED
+ *    We set isProjectRoot=false, which skips bundled dependency handling.
+ *    If a workspace package has "bundleDependencies" in package.json, those
+ *    files will NOT be included in the packlist result.
+ *
+ *    NOTE: This would not work anyway because bundleDependencies includes files
+ *    from node_modules/, and node_modules/ is excluded from project uploads.
+ *    Even with full arborist, bundled dependencies would be filtered out.
+ *    Developers needing to include private/local packages should use file:
+ *    dependencies instead (e.g., "my-pkg": "file:../my-pkg").
+ *
+ * 2. WORKSPACE-AWARE FILTERING DISABLED
+ *    We set workspaces=null, so npm-packlist won't exclude workspace
+ *    directories. This is fine for our use case since we process each
+ *    workspace independently.
+ *
+ * 3. VERSION COUPLING
+ *    This minimal interface is based on npm-packlist@8.0.1. Future versions
+ *    may access additional properties, causing runtime errors. If packlist
+ *    behavior changes unexpectedly, check for new property accesses:
+ *
+ *      grep -E "this\.tree\." node_modules/npm-packlist/lib/index.js
+ *
+ * DEBUGGING:
+ *
+ * If getPackableFiles() returns unexpected results:
+ *
+ * 1. Check if npm-packlist version changed (package.json)
+ * 2. Compare tree property accesses (grep command above)
+ * 3. Test with full arborist to isolate the issue:
+ *
+ *      import Arborist from '@npmcli/arborist';
+ *      const arb = new Arborist({ path: dir });
+ *      const tree = await arb.loadActual();
+ *      const files = await packlist(tree);
+ *
+ * 4. If full arborist works but minimal tree doesn't, add the missing
+ *    properties to MinimalArboristTree interface and createMinimalTree()
+ */
+/**
+ * Minimal subset of package.json fields used by npm-packlist
+ */
+interface PackageJsonForPacklist {
+    name?: string;
+    files?: string[];
+    main?: string;
+    bin?: string | Record<string, string>;
+    browser?: string | Record<string, string>;
+    bundleDependencies?: string[];
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+}
+/**
+ * Minimal tree interface that satisfies npm-packlist's runtime requirements.
+ * This is NOT the full Arborist Node interface - only the properties that
+ * npm-packlist actually accesses at runtime.
+ */
+export interface MinimalArboristTree {
+    path: string;
+    package: PackageJsonForPacklist;
+    workspaces: null;
+    isProjectRoot: false;
+    edgesOut: Map<string, unknown>;
+}
+/**
+ * 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 declare function createMinimalTree(dir: string): MinimalArboristTree;
+export {};

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(),
+    };
+}