@hyperfrontend/builder 0.1.0

package/package/licenses/index.cjs.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const index_cjs_js$3 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/regexp/index.cjs.js');
+const index_cjs_js$1 = require('../../_dependencies/@hyperfrontend/logging/index.cjs.js');
+const index_cjs_js$2 = require('../../_dependencies/@hyperfrontend/project-scope/core/index.cjs.js');
+const index_cjs_js = require('../../_dependencies/@hyperfrontend/versioning/repository/parse/index.cjs.js');
+const { generateThirdPartyLicensesContent } = require('../../_shared/package/licenses/generate-content/index.cjs.js');
+const { writeThirdPartyLicensesFile } = require('../../_shared/package/licenses/write/index.cjs.js');
+
+const extractRepositoryUrl = (repository) => {
+    if (typeof repository === 'string')
+        return repository;
+    if (repository && typeof repository === 'object')
+        return repository.url;
+    return null;
+};
+const formatLicenseUrl = (platform, baseUrl, fileName) => {
+    if (platform === 'github')
+        return `${baseUrl}/blob/HEAD/${fileName}`;
+    if (platform === 'gitlab')
+        return `${baseUrl}/-/blob/HEAD/${fileName}`;
+    if (platform === 'bitbucket')
+        return `${baseUrl}/src/HEAD/${fileName}`;
+    return null;
+};
+/**
+ * Derives a canonical license-file URL for a dependency from its `package.json`
+ * `repository` field and the discovered LICENSE filename.
+ *
+ * Returns `null` for missing repository fields, unparseable URLs, and platforms
+ * outside the supported set (GitHub, GitLab, Bitbucket).
+ *
+ * @param repository - Source `package.json` `repository` field (string or object form).
+ * @param licenseFileName - Filename of the LICENSE inside the upstream repo.
+ * @returns Resolved license URL, or `null` when one cannot be derived.
+ *
+ * @example Resolving a GitHub LICENSE URL from a string-form repository field
+ * ```typescript
+ * const url = constructLicenseUrl('https://github.com/x/y.git', 'LICENSE')
+ * // → 'https://github.com/x/y/blob/HEAD/LICENSE'
+ * ```
+ */
+const constructLicenseUrl = (repository, licenseFileName) => {
+    const url = extractRepositoryUrl(repository);
+    if (!url)
+        return null;
+    const parsed = index_cjs_js.parseRepositoryUrl(url);
+    if (!parsed)
+        return null;
+    return formatLicenseUrl(parsed.platform, parsed.baseUrl, licenseFileName);
+};
+
+const log = index_cjs_js$1.logger.channel('builder:package:licenses');
+const matchPattern = (content, source) => 
+// eslint-disable-next-line workspace/no-unsafe-regex -- @preserve: SPDX patterns are static, vetted strings declared inline
+index_cjs_js$3.createRegExp(source, 'i').test(content);
+const findLicenseFile = (packageDir) => {
+    const match = index_cjs_js$2.readDirectory(packageDir).find((f) => f.isFile && /^license(\.md|\.txt)?$/i.test(f.name));
+    return match?.name ?? null;
+};
+const detectLicenseFromContent = (content) => {
+    if (matchPattern(content, 'MIT License'))
+        return 'MIT';
+    if (matchPattern(content, 'Apache License.*Version 2\\.0'))
+        return 'Apache-2.0';
+    if (matchPattern(content, 'BSD 3-Clause License'))
+        return 'BSD-3-Clause';
+    if (matchPattern(content, 'BSD 2-Clause License'))
+        return 'BSD-2-Clause';
+    if (matchPattern(content, 'ISC License'))
+        return 'ISC';
+    if (matchPattern(content, 'GNU General Public License.*version 3'))
+        return 'GPL-3.0';
+    if (matchPattern(content, 'GNU Lesser General Public License.*version 3'))
+        return 'LGPL-3.0';
+    if (matchPattern(content, 'Mozilla Public License.*2\\.0'))
+        return 'MPL-2.0';
+    return null;
+};
+const resolvePackageDir = (workspaceRoot, depName) => depName.startsWith('@') ? index_cjs_js$2.join(workspaceRoot, 'node_modules', ...depName.split('/')) : index_cjs_js$2.join(workspaceRoot, 'node_modules', depName);
+const collectDependencyLicense = (depName, workspaceRoot) => {
+    const packageDir = resolvePackageDir(workspaceRoot, depName);
+    const pkgPath = index_cjs_js$2.join(packageDir, 'package.json');
+    if (!index_cjs_js$2.exists(pkgPath)) {
+        log.warn(`could not find package.json for ${depName}`);
+        return null;
+    }
+    const pkg = index_cjs_js$2.readJsonFile(pkgPath);
+    const licenseFileName = findLicenseFile(packageDir);
+    let licenseType = typeof pkg.license === 'string' ? pkg.license : 'Unknown';
+    if (licenseFileName) {
+        const detected = detectLicenseFromContent(index_cjs_js$2.readFileContent(index_cjs_js$2.join(packageDir, licenseFileName)));
+        if (detected)
+            licenseType = detected;
+    }
+    const licenseUrl = licenseFileName ? constructLicenseUrl(pkg.repository, licenseFileName) : null;
+    return { name: depName, licenseType, licenseUrl };
+};
+/**
+ * Collects license information for every external dependency of the project
+ * being built.
+ *
+ * The dependency list is supplied by the caller (typically the resolved external
+ * list from the bundle phase, with workspace-internal entries already removed).
+ * For each dependency, the function locates the installed package under
+ * `<workspaceRoot>/node_modules`, parses its `package.json`, scans for a LICENSE
+ * file, and attempts to derive a canonical license URL from the upstream
+ * repository field. Missing dependencies are logged at warn level and dropped
+ * from the result.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root containing
+ * `node_modules`.
+ * @param externals - List of external (non-workspace) dependency names to inspect.
+ * @returns Sorted list of license entries, one per resolvable dependency.
+ *
+ * @example Collecting licenses for a built library's bundle phase externals
+ * ```typescript
+ * const entries = collectThirdPartyLicenses('/abs/repo', ['rollup', 'typescript'])
+ * ```
+ */
+const collectThirdPartyLicenses = (workspaceRoot, externals) => {
+    if (externals.length === 0)
+        return [];
+    const entries = [];
+    for (const dep of externals) {
+        const entry = collectDependencyLicense(dep, workspaceRoot);
+        if (entry)
+            entries.push(entry);
+    }
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+};
+
+exports.collectThirdPartyLicenses = collectThirdPartyLicenses;
+exports.generateThirdPartyLicensesContent = generateThirdPartyLicensesContent;
+exports.writeThirdPartyLicensesFile = writeThirdPartyLicensesFile;

package/package/licenses/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * License entry for a single third-party dependency.
+ */
+type ThirdPartyLicenseEntry = {
+    /** Package name. */
+    name: string;
+    /** Detected SPDX-style license identifier (or `Unknown`). */
+    licenseType: string;
+    /** URL to the license file in the upstream repository, when known. */
+    licenseUrl: string | null;
+};
+
+/**
+ * Collects license information for every external dependency of the project
+ * being built.
+ *
+ * The dependency list is supplied by the caller (typically the resolved external
+ * list from the bundle phase, with workspace-internal entries already removed).
+ * For each dependency, the function locates the installed package under
+ * `<workspaceRoot>/node_modules`, parses its `package.json`, scans for a LICENSE
+ * file, and attempts to derive a canonical license URL from the upstream
+ * repository field. Missing dependencies are logged at warn level and dropped
+ * from the result.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root containing
+ * `node_modules`.
+ * @param externals - List of external (non-workspace) dependency names to inspect.
+ * @returns Sorted list of license entries, one per resolvable dependency.
+ *
+ * @example Collecting licenses for a built library's bundle phase externals
+ * ```typescript
+ * const entries = collectThirdPartyLicenses('/abs/repo', ['rollup', 'typescript'])
+ * ```
+ */
+declare const collectThirdPartyLicenses: (workspaceRoot: string, externals: string[]) => ThirdPartyLicenseEntry[];
+
+/**
+ * Renders the markdown body for `THIRD_PARTY_LICENSES.md` from a collected list
+ * of license entries.
+ *
+ * The output is a top-level heading followed by a two-column table mapping each
+ * dependency to a markdown link pointing at the upstream license file (or the
+ * raw license type when no URL is available). The body always ends with a
+ * trailing newline.
+ *
+ * @param entries - License entries produced by {@link collectThirdPartyLicenses}.
+ * @returns Markdown content suitable for writing to disk.
+ *
+ * @example Generating the markdown body from a license collection
+ * ```typescript
+ * const md = generateThirdPartyLicensesContent(entries)
+ * ```
+ */
+declare const generateThirdPartyLicensesContent: (entries: ThirdPartyLicenseEntry[]) => string;
+
+/**
+ * Writes the rendered third-party-licenses content as
+ * `<outputPath>/THIRD_PARTY_LICENSES.md`. Parent directories are created if
+ * necessary by the underlying project-scope writer.
+ *
+ * @param outputPath - Absolute path to the build output directory (the dist root).
+ * @param content - Rendered markdown body produced by
+ * {@link generateThirdPartyLicensesContent}.
+ *
+ * @example Writing the file at the dist root
+ * ```typescript
+ * writeThirdPartyLicensesFile(ctx.outputPath, content)
+ * ```
+ */
+declare const writeThirdPartyLicensesFile: (outputPath: string, content: string) => void;
+
+export { collectThirdPartyLicenses, generateThirdPartyLicensesContent, writeThirdPartyLicensesFile };
+export type { ThirdPartyLicenseEntry };

package/package/licenses/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/package/licenses/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AACrD,OAAO,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,EAAE,iCAAiC,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAA"}

package/package/licenses/index.esm.js

@@ -0,0 +1,89 @@
+import { createRegExp } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/regexp/index.esm.js';
+import { logger } from '../../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { join, exists, readJsonFile, readFileContent, readDirectory, writeFileContent } from '../../_dependencies/@hyperfrontend/project-scope/core/index.esm.js';
+import { parseRepositoryUrl } from '../../_dependencies/@hyperfrontend/versioning/repository/parse/index.esm.js';
+import { constructLicenseUrl } from '../../_shared/package/licenses/license-url/index.esm.js';
+import { generateThirdPartyLicensesContent } from '../../_shared/package/licenses/generate-content/index.esm.js';
+import { writeThirdPartyLicensesFile } from '../../_shared/package/licenses/write/index.esm.js';
+
+const log = logger.channel('builder:package:licenses');
+const matchPattern = (content, source) => 
+// eslint-disable-next-line workspace/no-unsafe-regex -- @preserve: SPDX patterns are static, vetted strings declared inline
+createRegExp(source, 'i').test(content);
+const findLicenseFile = (packageDir) => {
+    const match = readDirectory(packageDir).find((f) => f.isFile && /^license(\.md|\.txt)?$/i.test(f.name));
+    return match?.name ?? null;
+};
+const detectLicenseFromContent = (content) => {
+    if (matchPattern(content, 'MIT License'))
+        return 'MIT';
+    if (matchPattern(content, 'Apache License.*Version 2\\.0'))
+        return 'Apache-2.0';
+    if (matchPattern(content, 'BSD 3-Clause License'))
+        return 'BSD-3-Clause';
+    if (matchPattern(content, 'BSD 2-Clause License'))
+        return 'BSD-2-Clause';
+    if (matchPattern(content, 'ISC License'))
+        return 'ISC';
+    if (matchPattern(content, 'GNU General Public License.*version 3'))
+        return 'GPL-3.0';
+    if (matchPattern(content, 'GNU Lesser General Public License.*version 3'))
+        return 'LGPL-3.0';
+    if (matchPattern(content, 'Mozilla Public License.*2\\.0'))
+        return 'MPL-2.0';
+    return null;
+};
+const resolvePackageDir = (workspaceRoot, depName) => depName.startsWith('@') ? join(workspaceRoot, 'node_modules', ...depName.split('/')) : join(workspaceRoot, 'node_modules', depName);
+const collectDependencyLicense = (depName, workspaceRoot) => {
+    const packageDir = resolvePackageDir(workspaceRoot, depName);
+    const pkgPath = join(packageDir, 'package.json');
+    if (!exists(pkgPath)) {
+        log.warn(`could not find package.json for ${depName}`);
+        return null;
+    }
+    const pkg = readJsonFile(pkgPath);
+    const licenseFileName = findLicenseFile(packageDir);
+    let licenseType = typeof pkg.license === 'string' ? pkg.license : 'Unknown';
+    if (licenseFileName) {
+        const detected = detectLicenseFromContent(readFileContent(join(packageDir, licenseFileName)));
+        if (detected)
+            licenseType = detected;
+    }
+    const licenseUrl = licenseFileName ? constructLicenseUrl(pkg.repository, licenseFileName) : null;
+    return { name: depName, licenseType, licenseUrl };
+};
+/**
+ * Collects license information for every external dependency of the project
+ * being built.
+ *
+ * The dependency list is supplied by the caller (typically the resolved external
+ * list from the bundle phase, with workspace-internal entries already removed).
+ * For each dependency, the function locates the installed package under
+ * `<workspaceRoot>/node_modules`, parses its `package.json`, scans for a LICENSE
+ * file, and attempts to derive a canonical license URL from the upstream
+ * repository field. Missing dependencies are logged at warn level and dropped
+ * from the result.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root containing
+ * `node_modules`.
+ * @param externals - List of external (non-workspace) dependency names to inspect.
+ * @returns Sorted list of license entries, one per resolvable dependency.
+ *
+ * @example Collecting licenses for a built library's bundle phase externals
+ * ```typescript
+ * const entries = collectThirdPartyLicenses('/abs/repo', ['rollup', 'typescript'])
+ * ```
+ */
+const collectThirdPartyLicenses = (workspaceRoot, externals) => {
+    if (externals.length === 0)
+        return [];
+    const entries = [];
+    for (const dep of externals) {
+        const entry = collectDependencyLicense(dep, workspaceRoot);
+        if (entry)
+            entries.push(entry);
+    }
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+};
+
+export { collectThirdPartyLicenses, generateThirdPartyLicensesContent, writeThirdPartyLicensesFile };

package/package/licenses/license-url.d.ts

@@ -0,0 +1,20 @@
+import type { PackageJson } from '../../models';
+/**
+ * Derives a canonical license-file URL for a dependency from its `package.json`
+ * `repository` field and the discovered LICENSE filename.
+ *
+ * Returns `null` for missing repository fields, unparseable URLs, and platforms
+ * outside the supported set (GitHub, GitLab, Bitbucket).
+ *
+ * @param repository - Source `package.json` `repository` field (string or object form).
+ * @param licenseFileName - Filename of the LICENSE inside the upstream repo.
+ * @returns Resolved license URL, or `null` when one cannot be derived.
+ *
+ * @example Resolving a GitHub LICENSE URL from a string-form repository field
+ * ```typescript
+ * const url = constructLicenseUrl('https://github.com/x/y.git', 'LICENSE')
+ * // → 'https://github.com/x/y/blob/HEAD/LICENSE'
+ * ```
+ */
+export declare const constructLicenseUrl: (repository: PackageJson["repository"], licenseFileName: string) => string | null;
+//# sourceMappingURL=license-url.d.ts.map

package/package/licenses/license-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"license-url.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/package/licenses/license-url.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAgB/C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,GAAI,YAAY,WAAW,CAAC,YAAY,CAAC,EAAE,iBAAiB,MAAM,KAAG,MAAM,GAAG,IAM7G,CAAA"}

package/package/licenses/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * License entry for a single third-party dependency.
+ */
+export type ThirdPartyLicenseEntry = {
+    /** Package name. */
+    name: string;
+    /** Detected SPDX-style license identifier (or `Unknown`). */
+    licenseType: string;
+    /** URL to the license file in the upstream repository, when known. */
+    licenseUrl: string | null;
+};
+//# sourceMappingURL=types.d.ts.map

package/package/licenses/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/package/licenses/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,CAAA"}

package/package/licenses/write.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Writes the rendered third-party-licenses content as
+ * `<outputPath>/THIRD_PARTY_LICENSES.md`. Parent directories are created if
+ * necessary by the underlying project-scope writer.
+ *
+ * @param outputPath - Absolute path to the build output directory (the dist root).
+ * @param content - Rendered markdown body produced by
+ * {@link generateThirdPartyLicensesContent}.
+ *
+ * @example Writing the file at the dist root
+ * ```typescript
+ * writeThirdPartyLicensesFile(ctx.outputPath, content)
+ * ```
+ */
+export declare const writeThirdPartyLicensesFile: (outputPath: string, content: string) => void;
+//# sourceMappingURL=write.d.ts.map

package/package/licenses/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/package/licenses/write.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,GAAI,YAAY,MAAM,EAAE,SAAS,MAAM,KAAG,IAEjF,CAAA"}

package/package/run-package-phase.d.ts

@@ -0,0 +1,30 @@
+import type { BuildConfig, BuildContext, FormatOutputs } from '../models';
+/**
+ * Runs the complete package phase: synthesizes and writes the dist
+ * `package.json`, materializes any configured asset specs, and (when
+ * `config.thirdPartyLicenses` is enabled — defaulting to `true` for builds
+ * with at least one bundled dep) emits `THIRD_PARTY_LICENSES.md`.
+ *
+ * The phase consumes:
+ * - the source `package.json` (read fresh from `ctx.projectRoot`)
+ * - the resolved {@link BuildContext} (output path, workspace predicate, assets, discovery)
+ * - the {@link FormatOutputs} aggregated by the bundle phase
+ *
+ * Workspace-internal entries are stripped from the published `dependencies`
+ * map only when both `config.filterWorkspaceDepsFromOutput` and
+ * `ctx.isWorkspacePackage` are present. Inheritance and CDN overrides are
+ * forwarded verbatim to {@link synthesizePackageJson}.
+ *
+ * @param ctx - Resolved build context.
+ * @param config - Top-level builder configuration. Reads `inheritFieldsFrom`,
+ * `filterWorkspaceDepsFromOutput`, `unpkg`, `jsdelivr`, `bin`, and `thirdPartyLicenses`.
+ * The `files` allowlist is owned by {@link finalizeFilesAllowlist}, not this phase.
+ * @param formatOutputs - Outputs collected during the bundle phase.
+ *
+ * @example Driving the package phase from a custom orchestrator
+ * ```typescript
+ * await runPackagePhase(context, config, formatOutputs)
+ * ```
+ */
+export declare const runPackagePhase: (ctx: BuildContext, config: BuildConfig, formatOutputs: FormatOutputs) => Promise<void>;
+//# sourceMappingURL=run-package-phase.d.ts.map

package/package/run-package-phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-package-phase.d.ts","sourceRoot":"","sources":["../../../../../../../libs/builder/src/package/run-package-phase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAmBzE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,eAAe,GAAU,KAAK,YAAY,EAAE,QAAQ,WAAW,EAAE,eAAe,aAAa,KAAG,OAAO,CAAC,IAAI,CAyBxH,CAAA"}