@hubspot/project-parsing-lib 0.16.0-beta.0 → 0.17.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hubspot/project-parsing-lib",
-    "version": "0.16.0-beta.0",
+    "version": "0.17.0-beta.0",
     "description": "Parsing library for converting projects directory structures to their intermediate representation",
     "license": "Apache-2.0",
     "type": "module",
@@ -111,6 +111,7 @@
         "@inquirer/prompts": "^7.1.0",
         "@types/node": "^24.9.0",
         "@types/npm-packlist": "7.0.3",
+        "@types/npmcli__map-workspaces": "3.0.4",
         "@types/semver": "^7.5.8",
         "@typescript-eslint/eslint-plugin": "8.54.0",
         "@typescript-eslint/parser": "8.54.0",
@@ -126,11 +127,15 @@
     },
     "dependencies": {
         "@hubspot/local-dev-lib": "4.0.4",
+        "@npmcli/map-workspaces": "4.0.2",
         "ajv": "8.18.0",
         "ajv-formats": "3.0.1",
         "glob": "13.0.0",
         "npm-packlist": "8.0.1"
     },
+    "resolutions": {
+        "ajv-formats/ajv": "8.18.0"
+    },
     "scripts": {
         "build": "tsx ./scripts/build.ts",
         "lint": "echo 'Linting is disabled for Blazar'",

package/src/exports/workspaces.d.ts

@@ -1,2 +1,2 @@
-export { findAndParsePackageJsonFiles, resolveWorkspaceDirectories, collectWorkspaceDirectories, collectFileDependencies, getPackableFiles, WorkspaceResolutionError, FileDependencyResolutionError, } from '../lib/workspaces.js';
-export type { ParsedPackageJson, WorkspaceMapping, FileDependencyMapping, } from '../lib/workspaces.js';
+export { findAndParsePackageJsonFiles, resolveWorkspaceDirectories, collectWorkspaceDirectories, collectFileDependencies, validateWorkspaceProtocolDependencies, parseLocalSpec, getPackableFiles, WorkspaceResolutionError, FileDependencyResolutionError, OrphanWorkspaceProtocolError, } from '../lib/workspaces.js';
+export type { ParsedPackageJson, WorkspaceMapping, FileDependencyMapping, FileDependencyKind, LocalDependencyProtocol, } from '../lib/workspaces.js';

package/src/exports/workspaces.js

@@ -1 +1 @@
-export { findAndParsePackageJsonFiles, resolveWorkspaceDirectories, collectWorkspaceDirectories, collectFileDependencies, getPackableFiles, WorkspaceResolutionError, FileDependencyResolutionError, } from '../lib/workspaces.js';
+export { findAndParsePackageJsonFiles, resolveWorkspaceDirectories, collectWorkspaceDirectories, collectFileDependencies, validateWorkspaceProtocolDependencies, parseLocalSpec, getPackableFiles, WorkspaceResolutionError, FileDependencyResolutionError, OrphanWorkspaceProtocolError, } from '../lib/workspaces.js';

package/src/lang/copy.d.ts

@@ -51,4 +51,7 @@ export declare const logMessages: {
     files: {
         skippingPath: (path: string) => string;
     };
+    workspaces: {
+        cannotAccessDirectory: (dir: string, e: unknown) => string;
+    };
 };

package/src/lang/copy.js

@@ -66,4 +66,7 @@ export const logMessages = {
     files: {
         skippingPath: (path) => `Skipping ${path} as it is not in a valid directory`,
     },
+    workspaces: {
+        cannotAccessDirectory: (dir, e) => `Cannot access directory ${dir}: ${e}`,
+    },
 };

package/src/lib/platformVersion.js

@@ -6,11 +6,15 @@ export function isSupportedPlatformVersion(platformVersion) {
     if (!platformVersion || typeof platformVersion !== 'string') {
         return false;
     }
+    if (process.env.HUBSPOT_PROJECT_INTERNAL_TEST === 'true')
+        return true;
     const supportedPlatformVersions = Object.values(PLATFORM_VERSIONS);
     return supportedPlatformVersions.includes(platformVersion);
 }
 export function isLegacyProject(platformVersion) {
     if (!platformVersion)
         return false;
+    if (process.env.HUBSPOT_PROJECT_INTERNAL_TEST === 'true')
+        return false;
     return [PLATFORM_VERSIONS.v2023_2, PLATFORM_VERSIONS.v2025_1].includes(platformVersion);
 }

package/src/lib/workspaces.d.ts

@@ -15,6 +15,17 @@ export declare class FileDependencyResolutionError extends Error {
     sourcePackageJson: string;
     constructor(packageName: string, dependencyPath: string, sourcePackageJson: string, cause?: Error);
 }
+/**
+ * Error thrown when a `workspace:` protocol dependency does not match any known
+ * workspace member. npm itself does not support the `workspace:` protocol —
+ * only pnpm and yarn berry do — so the install fails with a confusing message
+ * server-side. Surface a clearer error up front.
+ */
+export declare class OrphanWorkspaceProtocolError extends Error {
+    packageName: string;
+    sourcePackageJson: string;
+    constructor(packageName: string, sourcePackageJson: string);
+}
 interface PackageJson {
     name?: string;
     workspaces?: string[] | {
@@ -32,18 +43,40 @@ export interface WorkspaceMapping {
     workspaceDir: string;
     sourcePackageJsonPath: string;
 }
+export type FileDependencyKind = 'directory' | 'tarball';
+export type LocalDependencyProtocol = 'file' | 'link';
 export interface FileDependencyMapping {
     packageName: string;
     localPath: string;
     sourcePackageJsonPath: string;
+    kind: FileDependencyKind;
+    protocol: LocalDependencyProtocol;
 }
+/**
+ * Parses a `file:` or `link:` dependency spec into its protocol and raw path.
+ * Handles all npm-supported shapes:
+ *   - file:./relative/path
+ *   - file:relative/path (no leading slash/dot)
+ *   - file:/absolute/path
+ *   - file://./relative — npm-style file URL with relative path
+ *   - file:///absolute — file URL with absolute path
+ *   - link:./relative/path (symlink semantics for directories only)
+ */
+export declare function parseLocalSpec(spec: string): {
+    protocol: LocalDependencyProtocol;
+    rawPath: string;
+} | null;
 /**
  * Finds and parses all package.json files in a directory.
  * This is the single entry point for discovering package.json files and parsing their contents.
  */
 export declare function findAndParsePackageJsonFiles(srcDir: string): Promise<ParsedPackageJson[]>;
 /**
- * Resolves workspace glob patterns to actual directories
+ * Resolves workspace glob patterns to actual directories.
+ *
+ * Uses @npmcli/map-workspaces (npm's reference impl) so that negation patterns
+ * like `["packages/*", "!packages/excluded"]` are honored — a hand-rolled
+ * per-pattern glob() silently accepted negations without actually excluding.
  */
 export declare function resolveWorkspaceDirectories(baseDir: string, workspaceGlobs: string[]): Promise<string[]>;
 /**
@@ -53,10 +86,22 @@ export declare function resolveWorkspaceDirectories(baseDir: string, workspaceGl
  */
 export declare function collectWorkspaceDirectories(parsedPackageJsons: ParsedPackageJson[]): Promise<WorkspaceMapping[]>;
 /**
- * Collects all file: dependencies that need to be uploaded.
- * Returns mappings that track the package name, resolved path, and source package.json.
+ * Collects all `file:` and `link:` dependencies that need to be uploaded.
+ * Returns mappings that track the package name, resolved path, source
+ * package.json, kind (directory vs tarball) and protocol (file vs link).
  */
 export declare function collectFileDependencies(parsedPackageJsons: ParsedPackageJson[]): Promise<FileDependencyMapping[]>;
+/**
+ * Validates that every `workspace:` protocol dependency in the parsed package
+ * trees matches a known workspace member. Throws OrphanWorkspaceProtocolError
+ * for the first orphan found.
+ *
+ * npm itself does not implement the `workspace:` protocol; only pnpm and yarn
+ * berry do. If a project uses `workspace:*` without a matching member declared
+ * under `workspaces`, the install fails server-side with a confusing message —
+ * fail fast with a clearer one.
+ */
+export declare function validateWorkspaceProtocolDependencies(parsedPackageJsons: ParsedPackageJson[], workspaceMappings: WorkspaceMapping[]): void;
 /**
  * Returns the set of files that npm would include when publishing a package.
  * Uses npm-packlist which respects the "files" field in package.json,

package/src/lib/workspaces.js

@@ -2,11 +2,13 @@ import fs from 'fs';
 import fsPromises from 'fs/promises';
 import path from 'path';
 import os from 'os';
-import { glob } from 'glob';
+import { fileURLToPath } from 'node:url';
+import mapWorkspaces from '@npmcli/map-workspaces';
 import packlist from 'npm-packlist';
 import { logger } from '@hubspot/local-dev-lib/logger';
 import { walk } from '@hubspot/local-dev-lib/fs';
 import { createMinimalTree } from './minimalArboristTree.js';
+import { logMessages } from '../lang/copy.js';
 /**
  * Error thrown when a workspace directory cannot be resolved
  */
@@ -41,6 +43,28 @@ export class FileDependencyResolutionError extends Error {
         }
     }
 }
+/**
+ * Error thrown when a `workspace:` protocol dependency does not match any known
+ * workspace member. npm itself does not support the `workspace:` protocol —
+ * only pnpm and yarn berry do — so the install fails with a confusing message
+ * server-side. Surface a clearer error up front.
+ */
+export class OrphanWorkspaceProtocolError extends Error {
+    packageName;
+    sourcePackageJson;
+    constructor(packageName, sourcePackageJson) {
+        super(`Found \`workspace:\` protocol dependency "${packageName}" in ${sourcePackageJson} but no workspace member is named "${packageName}". ` +
+            `The \`workspace:\` protocol requires a matching workspace member declared under "workspaces" in a parent package.json. ` +
+            `If you're migrating from pnpm or yarn berry, replace with \`file:./<relative-path>\` or \`link:./<relative-path>\`, or add the package under "workspaces".`);
+        this.packageName = packageName;
+        this.sourcePackageJson = sourcePackageJson;
+        this.name = 'OrphanWorkspaceProtocolError';
+    }
+}
+function hasTarballExtension(p) {
+    const { ext, name } = path.parse(p.toLowerCase());
+    return (ext === '.tgz' || ext === '.tar' || (ext === '.gz' && name.endsWith('.tar')));
+}
 /**
  * Expands tilde (~) in paths to the user's home directory
  */
@@ -49,6 +73,33 @@ function expandTildePath(filePath) {
         ? path.join(os.homedir(), filePath.slice(1))
         : filePath;
 }
+/**
+ * Parses a `file:` or `link:` dependency spec into its protocol and raw path.
+ * Handles all npm-supported shapes:
+ *   - file:./relative/path
+ *   - file:relative/path (no leading slash/dot)
+ *   - file:/absolute/path
+ *   - file://./relative — npm-style file URL with relative path
+ *   - file:///absolute — file URL with absolute path
+ *   - link:./relative/path (symlink semantics for directories only)
+ */
+export function parseLocalSpec(spec) {
+    const match = /^(file|link):(.*)$/.exec(spec);
+    if (!match) {
+        return null;
+    }
+    const protocol = match[1];
+    let rawPath = match[2];
+    if (rawPath.startsWith('//')) {
+        try {
+            rawPath = fileURLToPath(`file:${rawPath}`);
+        }
+        catch {
+            return { protocol, rawPath };
+        }
+    }
+    return { protocol, rawPath };
+}
 /**
  * Finds and parses all package.json files in a directory.
  * This is the single entry point for discovering package.json files and parsing their contents.
@@ -82,56 +133,58 @@ function extractWorkspaceGlobs(packageJson) {
     if (!workspaces) {
         return [];
     }
-    // Handle array format: "workspaces": ["packages/*"]
     if (Array.isArray(workspaces)) {
         return workspaces;
     }
-    // Handle object format: "workspaces": {"packages": ["packages/*"]}
     if (workspaces.packages && Array.isArray(workspaces.packages)) {
         return workspaces.packages;
     }
     return [];
 }
 /**
- * Resolves workspace glob patterns to actual directories
+ * Resolves workspace glob patterns to actual directories.
+ *
+ * Uses @npmcli/map-workspaces (npm's reference impl) so that negation patterns
+ * like `["packages/*", "!packages/excluded"]` are honored — a hand-rolled
+ * per-pattern glob() silently accepted negations without actually excluding.
  */
 export async function resolveWorkspaceDirectories(baseDir, workspaceGlobs) {
-    const resolvedDirs = new Set();
-    for (const pattern of workspaceGlobs) {
-        const expandedPattern = expandTildePath(pattern);
-        const absolutePattern = path.resolve(baseDir, expandedPattern);
+    if (workspaceGlobs.length === 0) {
+        return [];
+    }
+    const expandedGlobs = workspaceGlobs.map(expandTildePath);
+    let workspaceMap;
+    try {
+        workspaceMap = await mapWorkspaces({
+            pkg: { workspaces: expandedGlobs },
+            cwd: baseDir,
+        });
+    }
+    catch (e) {
+        logger.debug(`Failed to resolve workspace patterns in ${baseDir} via map-workspaces: ${e}`);
+        return [];
+    }
+    const resolved = new Set();
+    for (const dir of workspaceMap.values()) {
         try {
-            // Use glob to find matching directories
-            const matches = await glob(absolutePattern, {
-                absolute: true,
-                withFileTypes: false,
-            });
-            // Filter to directories that contain package.json
-            for (const match of matches) {
-                try {
-                    const stats = await fsPromises.stat(match);
-                    if (stats.isDirectory()) {
-                        const packageJsonPath = path.join(match, 'package.json');
-                        try {
-                            await fsPromises.access(packageJsonPath, fs.constants.F_OK);
-                            resolvedDirs.add(match);
-                        }
-                        catch {
-                            // Directory exists but doesn't contain package.json - skip silently
-                        }
-                    }
-                }
-                catch (e) {
-                    // Inaccessible directories may indicate permission issues or broken symlinks
-                    logger.warn(`Cannot access directory ${match}: ${e}`);
-                }
+            const stats = await fsPromises.stat(dir);
+            if (!stats.isDirectory()) {
+                continue;
+            }
+            const packageJsonPath = path.join(dir, 'package.json');
+            try {
+                await fsPromises.access(packageJsonPath, fs.constants.F_OK);
+                resolved.add(dir);
+            }
+            catch {
+                // Directory exists but doesn't contain package.json — skip silently.
             }
         }
         catch (e) {
-            logger.debug(`Failed to resolve workspace pattern "${pattern}": ${e}`);
+            logger.warn(logMessages.workspaces.cannotAccessDirectory(dir, e));
         }
     }
-    return Array.from(resolvedDirs);
+    return Array.from(resolved);
 }
 /**
  * Collects all workspace directories that need to be uploaded.
@@ -142,9 +195,8 @@ export async function collectWorkspaceDirectories(parsedPackageJsons) {
     const workspaceMappings = [];
     // Track (sourcePackageJsonPath, workspaceDir) pairs to avoid duplicates within
     // the same source, while still allowing the same workspace dir to appear in
-    // mappings from multiple different package.json files. This ensures every
-    // package.json that declares a workspace gets its workspaces field rewritten,
-    // regardless of whether another package.json already references the same dir.
+    // mappings from multiple different package.json files. Both keys use realpath
+    // form so case-only differences on case-insensitive filesystems collapse.
     const visited = new Set();
     for (const parsed of parsedPackageJsons) {
         if (!parsed.content) {
@@ -156,8 +208,14 @@ export async function collectWorkspaceDirectories(parsedPackageJsons) {
         }
         logger.debug(`Found workspaces in ${parsed.path}: ${workspaceGlobs.join(', ')}`);
         const resolved = await resolveWorkspaceDirectories(parsed.dir, workspaceGlobs);
+        let sourceRealPath;
+        try {
+            sourceRealPath = await fsPromises.realpath(parsed.path);
+        }
+        catch {
+            sourceRealPath = parsed.path;
+        }
         for (const dir of resolved) {
-            // Resolve symlinks to real path
             let realDir;
             try {
                 realDir = await fsPromises.realpath(dir);
@@ -165,19 +223,12 @@ export async function collectWorkspaceDirectories(parsedPackageJsons) {
             catch (e) {
                 throw new WorkspaceResolutionError(dir, parsed.path, e instanceof Error ? e : undefined);
             }
-            // Skip duplicate (source, workspace) pairs only — the same workspace dir
-            // may legitimately be referenced by multiple package.json files and each
-            // needs its own mapping so its workspaces field is rewritten correctly.
-            const pairKey = `${parsed.path}::${realDir}`;
+            const pairKey = `${sourceRealPath}::${realDir}`;
             if (visited.has(pairKey)) {
                 logger.debug(`Skipping duplicate workspace mapping: ${realDir} from ${parsed.path}`);
                 continue;
             }
             visited.add(pairKey);
-            // Include all workspaces - both internal (inside srcDir) and external.
-            // The CLI determines the archive path:
-            // - Internal: preserved as-is (already included via srcDir walk)
-            // - External: _workspaces/<name>-<hash>
             workspaceMappings.push({
                 workspaceDir: realDir,
                 sourcePackageJsonPath: parsed.path,
@@ -188,7 +239,7 @@ export async function collectWorkspaceDirectories(parsedPackageJsons) {
     return workspaceMappings;
 }
 /**
- * Extracts file: dependencies from parsed package.json content.
+ * Extracts file: and link: dependencies from parsed package.json content.
  * Only scans production dependencies since devDependencies and optionalDependencies
  * are not needed for the build pipeline.
  */
@@ -199,18 +250,24 @@ function extractFileDependencies(packageJson) {
         return fileDeps;
     }
     for (const [packageName, version] of Object.entries(deps)) {
-        // Only handle file: dependencies. workspace: dependencies reference packages
-        // already collected via the workspaces field, so they don't need separate handling.
-        if (typeof version === 'string' && version.startsWith('file:')) {
-            const filePath = version.slice(5); // Remove 'file:' prefix
-            fileDeps.push({ packageName, filePath });
+        if (typeof version !== 'string') {
+            continue;
+        }
+        const parsed = parseLocalSpec(version);
+        if (parsed) {
+            fileDeps.push({
+                packageName,
+                protocol: parsed.protocol,
+                rawPath: parsed.rawPath,
+            });
         }
     }
     return fileDeps;
 }
 /**
- * Collects all file: dependencies that need to be uploaded.
- * Returns mappings that track the package name, resolved path, and source package.json.
+ * Collects all `file:` and `link:` dependencies that need to be uploaded.
+ * Returns mappings that track the package name, resolved path, source
+ * package.json, kind (directory vs tarball) and protocol (file vs link).
  */
 export async function collectFileDependencies(parsedPackageJsons) {
     const fileDependencyMappings = [];
@@ -223,11 +280,14 @@ export async function collectFileDependencies(parsedPackageJsons) {
         if (fileDeps.length === 0) {
             continue;
         }
-        logger.debug(`Found file: dependencies in ${parsed.path}: ${fileDeps.map(d => d.packageName).join(', ')}`);
-        for (const { packageName, filePath } of fileDeps) {
-            const expandedPath = expandTildePath(filePath);
+        logger.debug(`Found file:/link: dependencies in ${parsed.path}: ${fileDeps.map(d => d.packageName).join(', ')}`);
+        for (const { packageName, protocol, rawPath } of fileDeps) {
+            const expandedPath = expandTildePath(rawPath);
             const absolutePath = path.resolve(parsed.dir, expandedPath);
-            // Resolve symlinks to real path
+            const looksLikeTarball = hasTarballExtension(absolutePath);
+            if (looksLikeTarball && protocol === 'link') {
+                throw new FileDependencyResolutionError(packageName, absolutePath, parsed.path, new Error('`link:` protocol is for directories (symlink semantics); use `file:` for tarballs'));
+            }
             let realPath;
             try {
                 realPath = await fsPromises.realpath(absolutePath);
@@ -235,38 +295,93 @@ export async function collectFileDependencies(parsedPackageJsons) {
             catch (e) {
                 throw new FileDependencyResolutionError(packageName, absolutePath, parsed.path, e instanceof Error ? e : undefined);
             }
-            // Verify it's a directory with a package.json
-            const stats = await fsPromises.stat(realPath);
-            if (!stats.isDirectory()) {
-                throw new FileDependencyResolutionError(packageName, realPath, parsed.path, new Error('Path is not a directory'));
-            }
-            const depPackageJsonPath = path.join(realPath, 'package.json');
+            let stats;
             try {
-                await fsPromises.access(depPackageJsonPath, fs.constants.F_OK);
+                stats = await fsPromises.stat(realPath);
             }
-            catch {
-                throw new FileDependencyResolutionError(packageName, realPath, parsed.path, new Error('Directory does not contain package.json'));
+            catch (e) {
+                throw new FileDependencyResolutionError(packageName, realPath, parsed.path, e instanceof Error ? e : undefined);
+            }
+            let kind;
+            if (looksLikeTarball) {
+                if (!stats.isFile()) {
+                    throw new FileDependencyResolutionError(packageName, realPath, parsed.path, new Error('Tarball path is not a regular file'));
+                }
+                kind = 'tarball';
+            }
+            else if (stats.isDirectory()) {
+                const depPackageJsonPath = path.join(realPath, 'package.json');
+                try {
+                    await fsPromises.access(depPackageJsonPath, fs.constants.F_OK);
+                }
+                catch {
+                    throw new FileDependencyResolutionError(packageName, realPath, parsed.path, new Error('Directory does not contain package.json'));
+                }
+                kind = 'directory';
+            }
+            else {
+                throw new FileDependencyResolutionError(packageName, realPath, parsed.path, new Error('Path is not a directory'));
             }
-            // Skip if already visited (same path referenced multiple times)
             if (visited.has(realPath)) {
                 logger.debug(`Skipping already visited file: dependency: ${realPath}`);
                 continue;
             }
             visited.add(realPath);
-            // Include all file: dependencies - both internal (inside srcDir) and external
-            // The CLI determines the archive path:
-            // - Internal: _workspaces/<relative-path>
-            // - External: _workspaces/external/<name>-<hash>
             fileDependencyMappings.push({
                 packageName,
                 localPath: realPath,
                 sourcePackageJsonPath: parsed.path,
+                kind,
+                protocol,
             });
-            logger.debug(`Resolved file: dependency ${packageName}: ${realPath}`);
+            logger.debug(`Resolved ${protocol}: dependency ${packageName} (${kind}): ${realPath}`);
         }
     }
     return fileDependencyMappings;
 }
+/**
+ * Validates that every `workspace:` protocol dependency in the parsed package
+ * trees matches a known workspace member. Throws OrphanWorkspaceProtocolError
+ * for the first orphan found.
+ *
+ * npm itself does not implement the `workspace:` protocol; only pnpm and yarn
+ * berry do. If a project uses `workspace:*` without a matching member declared
+ * under `workspaces`, the install fails server-side with a confusing message —
+ * fail fast with a clearer one.
+ */
+export function validateWorkspaceProtocolDependencies(parsedPackageJsons, workspaceMappings) {
+    const workspacePackageNames = new Set();
+    const workspaceDirs = new Set(workspaceMappings.map(m => m.workspaceDir));
+    for (const parsed of parsedPackageJsons) {
+        if (!parsed.content?.name) {
+            continue;
+        }
+        let realDir;
+        try {
+            realDir = fs.realpathSync(parsed.dir);
+        }
+        catch {
+            continue;
+        }
+        if (workspaceDirs.has(realDir)) {
+            workspacePackageNames.add(parsed.content.name);
+        }
+    }
+    for (const parsed of parsedPackageJsons) {
+        const deps = parsed.content?.dependencies;
+        if (!deps) {
+            continue;
+        }
+        for (const [packageName, version] of Object.entries(deps)) {
+            if (typeof version !== 'string' || !version.startsWith('workspace:')) {
+                continue;
+            }
+            if (!workspacePackageNames.has(packageName)) {
+                throw new OrphanWorkspaceProtocolError(packageName, parsed.path);
+            }
+        }
+    }
+}
 /**
  * Returns the set of files that npm would include when publishing a package.
  * Uses npm-packlist which respects the "files" field in package.json,
@@ -277,8 +392,6 @@ export async function collectFileDependencies(parsedPackageJsons) {
 export async function getPackableFiles(dir) {
     try {
         const tree = createMinimalTree(dir);
-        // Cast to Parameters<typeof packlist>[0] since npm-packlist only uses
-        // a subset of the Arborist Node properties at runtime
         const files = await packlist(tree);
         return new Set(files);
     }