balm-core 5.2.0 → 6.0.0-alpha.0

package/src/index.ts

@@ -0,0 +1,16 @@
+import { balm, Balm } from './balm.js';
+
+export default balm;
+export { Balm, balm };
+export * from './types/index.js';
+export * from './config/index.js';
+export * from './runner/task.js';
+export * from './runner/dag.js';
+export * from './pipeline/index.js';
+export * from './bundler/index.js';
+export * from './tasks/index.js';
+export * from './hooks/index.js';
+export * from './utilities/logger.js';
+export * from './utilities/file.js';
+export * from './utilities/utils.js';
+export * from './utilities/workspace.js';

package/src/pipeline/file.ts

@@ -0,0 +1,69 @@
+import path from 'node:path';
+
+export interface VirtualFileOptions {
+  cwd: string;
+  base: string;
+  path: string;
+  contents: Buffer | string;
+}
+
+export class VirtualFile {
+  cwd: string;
+  base: string;
+  path: string;
+  contents: Buffer;
+  revPathOriginal?: string;
+
+  constructor(options: VirtualFileOptions) {
+    this.cwd = options.cwd;
+    this.base = options.base;
+    this.path = options.path;
+    this.contents = typeof options.contents === 'string'
+      ? Buffer.from(options.contents)
+      : options.contents;
+  }
+
+  get relative(): string {
+    return path.relative(this.base, this.path);
+  }
+
+  get extname(): string {
+    return path.extname(this.path);
+  }
+  set extname(val: string) {
+    const dir = path.dirname(this.path);
+    const basename = path.basename(this.path, this.extname);
+    this.path = path.join(dir, `${basename}${val.startsWith('.') ? val : `.${val}`}`);
+  }
+
+  get basename(): string {
+    return path.basename(this.path);
+  }
+  set basename(val: string) {
+    const dir = path.dirname(this.path);
+    this.path = path.join(dir, val);
+  }
+
+  get stem(): string {
+    return path.basename(this.path, this.extname);
+  }
+  set stem(val: string) {
+    const dir = path.dirname(this.path);
+    this.path = path.join(dir, `${val}${this.extname}`);
+  }
+
+  toString(encoding: BufferEncoding = 'utf8'): string {
+    return this.contents.toString(encoding);
+  }
+
+  clone(): VirtualFile {
+    const cloned = new VirtualFile({
+      cwd: this.cwd,
+      base: this.base,
+      path: this.path,
+      contents: Buffer.from(this.contents)
+    });
+    cloned.revPathOriginal = this.revPathOriginal;
+    return cloned;
+  }
+}

package/src/pipeline/index.ts

@@ -0,0 +1,10 @@
+export * from './file.js';
+export * from './pipeline.js';
+export * from './transforms/sass.js';
+export * from './transforms/less.js';
+export * from './transforms/postcss.js';
+export * from './transforms/htmlmin.js';
+export * from './transforms/terser.js';
+export * from './transforms/replace.js';
+export * from './transforms/rename.js';
+export * from './transforms/cache.js';

package/src/pipeline/pipeline.ts

@@ -0,0 +1,132 @@
+import path from 'node:path';
+import fg from 'fast-glob';
+import fs from 'node:fs/promises';
+import { VirtualFile } from './file.js';
+import { file as fsUtil } from '../utilities/file.js';
+
+export type TransformFn = (
+  file: VirtualFile
+) => Promise<VirtualFile | VirtualFile[] | null | void> | VirtualFile | VirtualFile[] | null | void;
+
+export interface PipelineOptions {
+  cwd?: string;
+  base?: string;
+  allowEmpty?: boolean;
+}
+
+export class Pipeline {
+  private cwd: string;
+  private base?: string;
+  private allowEmpty: boolean;
+  private files: VirtualFile[] = [];
+  private transforms: TransformFn[] = [];
+
+  constructor(options: PipelineOptions = {}) {
+    this.cwd = options.cwd || process.cwd();
+    this.base = options.base;
+    this.allowEmpty = options.allowEmpty ?? true;
+  }
+
+  static from(
+    patterns: string | string[],
+    options: PipelineOptions = {}
+  ): Pipeline {
+    const pipeline = new Pipeline(options);
+    return pipeline.src(patterns);
+  }
+
+  src(patterns: string | string[], options: PipelineOptions = {}): this {
+    if (options.cwd) this.cwd = options.cwd;
+    if (options.base) this.base = options.base;
+    if (options.allowEmpty !== undefined) this.allowEmpty = options.allowEmpty;
+
+    this.transforms.push(async () => {
+      const matched = await fg(patterns, {
+        cwd: this.cwd,
+        absolute: true,
+        dot: true,
+        onlyFiles: true
+      });
+
+      if (!matched.length && !this.allowEmpty) {
+        throw new Error(`File not found with pattern: ${patterns}`);
+      }
+
+      // Calculate common base if not explicitly provided
+      let effectiveBase = this.base;
+      if (!effectiveBase) {
+        const patternArr = Array.isArray(patterns) ? patterns : [patterns];
+        const firstPos = patternArr.find((p) => !p.startsWith('!'));
+        if (firstPos) {
+          const globIdx = firstPos.indexOf('*');
+          if (globIdx !== -1) {
+            effectiveBase = path.resolve(this.cwd, firstPos.slice(0, globIdx));
+          } else {
+            effectiveBase = path.resolve(this.cwd, path.dirname(firstPos));
+          }
+        } else {
+          effectiveBase = this.cwd;
+        }
+      }
+
+      this.files = await Promise.all(
+        matched.map(async (filePath) => {
+          const buffer = await fs.readFile(filePath);
+          return new VirtualFile({
+            cwd: this.cwd,
+            base: effectiveBase!,
+            path: filePath,
+            contents: buffer
+          });
+        })
+      );
+    });
+
+    return this;
+  }
+
+  pipe(transform: TransformFn): this {
+    this.transforms.push(transform);
+    return this;
+  }
+
+  async process(): Promise<VirtualFile[]> {
+    let isSrcLoaded = false;
+    for (const transform of this.transforms) {
+      if (!isSrcLoaded) {
+        // Initial src loader
+        await transform(null as any);
+        isSrcLoaded = true;
+      } else {
+        if (this.files.length === 0) break;
+        const nextFiles: VirtualFile[] = [];
+        for (const file of this.files) {
+          const result = await transform(file);
+          if (result === undefined || result === file) {
+            nextFiles.push(file);
+          } else if (Array.isArray(result)) {
+            nextFiles.push(...result);
+          } else if (result !== null) {
+            nextFiles.push(result);
+          }
+        }
+        this.files = nextFiles;
+      }
+    }
+    return this.files;
+  }
+
+  async dest(outDir: string): Promise<string[]> {
+    const files = await this.process();
+    const writtenPaths: string[] = [];
+    const absOutDir = path.isAbsolute(outDir) ? outDir : path.resolve(this.cwd, outDir);
+
+    for (const file of files) {
+      const targetPath = path.resolve(absOutDir, file.relative);
+      await fsUtil.writeFile(targetPath, file.contents);
+      writtenPaths.push(targetPath);
+    }
+
+    return writtenPaths;
+  }
+}

package/src/pipeline/transforms/cache.ts

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { VirtualFile } from '../file.js';
+import { file as fsUtil } from '../../utilities/file.js';
+
+export interface CacheTransformOptions {
+  fileNameManifest?: string;
+  dontRenameFile?: (string | RegExp)[];
+  dontUpdateReference?: (string | RegExp)[];
+  hashLength?: number;
+  [key: string]: any;
+}
+
+function matchesAny(filePath: string, rules?: (string | RegExp)[]): boolean {
+  if (!rules || !rules.length) return false;
+  for (const rule of rules) {
+    if (typeof rule === 'string') {
+      if (filePath.endsWith(rule) || picomatch.isMatch(filePath, rule)) {
+        return true;
+      }
+    } else if (rule instanceof RegExp) {
+      if (rule.test(filePath)) return true;
+    }
+  }
+  return false;
+}
+
+export class AssetRevisioner {
+  private options: CacheTransformOptions;
+  private manifest: Record<string, string> = {};
+
+  constructor(options: CacheTransformOptions = {}) {
+    this.options = {
+      fileNameManifest: 'rev-manifest.json',
+      dontRenameFile: ['.html'],
+      dontUpdateReference: [],
+      hashLength: 8,
+      ...options
+    };
+  }
+
+  process(files: VirtualFile[]): VirtualFile[] {
+    const hashLength = this.options.hashLength || 8;
+    const outputFiles: VirtualFile[] = [];
+
+    // Phase 1: Calculate hashes and renames
+    for (const file of files) {
+      const origRelative = file.relative;
+      file.revPathOriginal = file.path;
+
+      const shouldRename = !matchesAny(file.path, this.options.dontRenameFile) &&
+        !matchesAny(file.relative, this.options.dontRenameFile);
+
+      if (shouldRename) {
+        const fileHash = fsUtil.hash(file.contents, hashLength);
+        const dir = path.dirname(file.path);
+        const newFilename = `${file.stem}.${fileHash}${file.extname}`;
+        file.path = path.join(dir, newFilename);
+      }
+
+      this.manifest[origRelative] = file.relative;
+      outputFiles.push(file);
+    }
+
+    // Phase 2: Rewrite references
+    for (const file of outputFiles) {
+      const shouldUpdate = !matchesAny(file.path, this.options.dontUpdateReference) &&
+        !matchesAny(file.relative, this.options.dontUpdateReference);
+
+      if (shouldUpdate && /\.(html|css|js)$/i.test(file.extname)) {
+        let content = file.toString();
+        for (const [orig, reved] of Object.entries(this.manifest)) {
+          if (orig !== reved) {
+            const origBase = path.basename(orig);
+            const revedBase = path.basename(reved);
+            content = content.replaceAll(origBase, revedBase);
+          }
+        }
+        file.contents = Buffer.from(content);
+      }
+    }
+
+    // Phase 3: Add manifest file
+    const manifestName = this.options.fileNameManifest || 'rev-manifest.json';
+    const firstBase = files[0]?.base || process.cwd();
+    const manifestFile = new VirtualFile({
+      cwd: files[0]?.cwd || process.cwd(),
+      base: firstBase,
+      path: path.join(firstBase, manifestName),
+      contents: JSON.stringify(this.manifest, null, 2)
+    });
+    outputFiles.push(manifestFile);
+
+    return outputFiles;
+  }
+}

package/src/pipeline/transforms/htmlmin.ts

@@ -0,0 +1,18 @@
+import { minify } from 'html-minifier-terser';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export function transformHtmlmin(options: Record<string, any> = {}): TransformFn {
+  return async (file) => {
+    if (!/\.html$/i.test(file.extname)) return file;
+
+    try {
+      const minified = await minify(file.toString(), options);
+      file.contents = Buffer.from(minified);
+      return file;
+    } catch (err: any) {
+      logger.error('htmlmin', `Error minifying ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}

package/src/pipeline/transforms/less.ts

@@ -0,0 +1,75 @@
+import less from 'less';
+import path from 'node:path';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export interface LessTransformOptions {
+  paths?: string[];
+  alias?: Record<string, string>;
+  [key: string]: any;
+}
+
+class AliasFileManager extends less.FileManager {
+  private alias: Record<string, string>;
+
+  constructor(alias: Record<string, string> = {}) {
+    super();
+    this.alias = alias;
+  }
+
+  supports(filename: string): boolean {
+    const clean = filename.startsWith('~') ? filename.slice(1) : filename;
+    return Object.keys(this.alias).some((k) => clean === k || clean.startsWith(`${k}/`));
+  }
+
+  loadFile(filename: string, currentDirectory: string, options: any, environment: any): Promise<any> {
+    const clean = filename.startsWith('~') ? filename.slice(1) : filename;
+    for (const [k, v] of Object.entries(this.alias)) {
+      if (clean === k) {
+        return super.loadFile(v, currentDirectory, options, environment);
+      } else if (clean.startsWith(`${k}/`)) {
+        const sub = clean.slice(k.length + 1);
+        return super.loadFile(path.join(v, sub), currentDirectory, options, environment);
+      }
+    }
+    return super.loadFile(filename, currentDirectory, options, environment);
+  }
+}
+
+export function transformLess(options: LessTransformOptions = {}): TransformFn {
+  return async (file) => {
+    if (!/\.less$/i.test(file.extname)) return file;
+    if (path.basename(file.path).startsWith('_')) return null;
+
+    try {
+      const paths = [
+        path.dirname(file.path),
+        path.resolve(file.cwd, 'node_modules'),
+        ...(options.paths || [])
+      ];
+
+      const plugins = [...(options.plugins || [])];
+      if (options.alias && Object.keys(options.alias).length > 0) {
+        plugins.push({
+          install: (lessInstance: any, pluginManager: any) => {
+            pluginManager.addFileManager(new AliasFileManager(options.alias));
+          }
+        });
+      }
+
+      const result = await less.render(file.toString(), {
+        filename: file.path,
+        paths,
+        ...options,
+        plugins
+      });
+
+      file.contents = Buffer.from(result.css);
+      file.extname = '.css';
+      return file;
+    } catch (err: any) {
+      logger.error('less', `Error compiling ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}

package/src/pipeline/transforms/postcss.ts

@@ -0,0 +1,43 @@
+import postcss, { AcceptedPlugin } from 'postcss';
+import autoprefixer from 'autoprefixer';
+import postcssPresetEnv from 'postcss-preset-env';
+import cssnano from 'cssnano';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export interface PostcssTransformOptions {
+  plugins?: AcceptedPlugin[];
+  minify?: boolean;
+  [key: string]: any;
+}
+
+export function transformPostcss(options: PostcssTransformOptions = {}): TransformFn {
+  const plugins: AcceptedPlugin[] = [
+    ...(options.plugins || []),
+    autoprefixer(),
+    postcssPresetEnv()
+  ];
+
+  if (options.minify) {
+    plugins.push(cssnano({ preset: 'default' }));
+  }
+
+  const processor = postcss(plugins);
+
+  return async (file) => {
+    if (!/\.css$/i.test(file.extname)) return file;
+
+    try {
+      const result = await processor.process(file.toString(), {
+        from: file.path,
+        to: file.path
+      });
+
+      file.contents = Buffer.from(result.css);
+      return file;
+    } catch (err: any) {
+      logger.error('postcss', `Error processing ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}

package/src/pipeline/transforms/rename.ts

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { TransformFn } from '../pipeline.js';
+import { RenameOptions } from '../../types/index.js';
+
+export function transformRename(
+  options: string | Function | RenameOptions = {}
+): TransformFn {
+  return async (file) => {
+    if (typeof options === 'string') {
+      file.path = path.resolve(path.dirname(file.path), options);
+      return file;
+    }
+
+    if (typeof options === 'function') {
+      const parsed = {
+        dirname: path.dirname(file.path),
+        basename: file.stem,
+        extname: file.extname
+      };
+      const result = options(parsed);
+      if (result) {
+        if (result.dirname) file.path = path.join(result.dirname, path.basename(file.path));
+        if (result.basename) file.stem = result.basename;
+        if (result.extname) file.extname = result.extname;
+      }
+      return file;
+    }
+
+    const { dirname, prefix = '', basename, suffix = '', extname } = options;
+    const currentDir = dirname ? path.resolve(file.cwd, dirname) : path.dirname(file.path);
+    const base = basename !== undefined ? basename : file.stem;
+    const ext = extname !== undefined ? extname : file.extname;
+
+    file.path = path.join(currentDir, `${prefix}${base}${suffix}${ext.startsWith('.') ? ext : `.${ext}`}`);
+    return file;
+  };
+}

package/src/pipeline/transforms/replace.ts

@@ -0,0 +1,30 @@
+import { TransformFn } from '../pipeline.js';
+import { ReplaceOptions } from '../../types/index.js';
+
+export function transformReplace(
+  options: ReplaceOptions | ReplaceOptions[] | string | RegExp,
+  replacement?: string | ((substring: string, ...args: any[]) => string)
+): TransformFn {
+  let rules: ReplaceOptions[] = [];
+
+  if (Array.isArray(options)) {
+    rules = options;
+  } else if (typeof options === 'object' && 'substr' in options) {
+    rules = [options];
+  } else if (typeof options === 'string' || options instanceof RegExp) {
+    rules = [{ substr: options, replacement: replacement || '' }];
+  }
+
+  return async (file) => {
+    let content = file.toString();
+    for (const rule of rules) {
+      if (typeof rule.replacement === 'function') {
+        content = content.replace(rule.substr, rule.replacement as any);
+      } else {
+        content = content.replace(rule.substr, rule.replacement);
+      }
+    }
+    file.contents = Buffer.from(content);
+    return file;
+  };
+}

package/src/pipeline/transforms/sass.ts

@@ -0,0 +1,106 @@
+import * as sass from 'sass';
+import path from 'node:path';
+import fs from 'node:fs';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export interface SassTransformOptions {
+  includePaths?: string[];
+  alias?: Record<string, string>;
+  style?: 'expanded' | 'compressed';
+  sourceMap?: boolean;
+  [key: string]: any;
+}
+
+function resolveFile(baseDir: string, url: string): string | null {
+  const possiblePaths = [
+    path.resolve(baseDir, url),
+    path.resolve(baseDir, `${url}.scss`),
+    path.resolve(baseDir, `${url}.sass`),
+    path.resolve(baseDir, `${url}.css`),
+    path.resolve(baseDir, path.dirname(url), `_${path.basename(url)}.scss`),
+    path.resolve(baseDir, path.dirname(url), `_${path.basename(url)}.sass`),
+    path.resolve(baseDir, url, '_index.scss'),
+    path.resolve(baseDir, url, '_index.sass'),
+    path.resolve(baseDir, url, 'index.scss'),
+    path.resolve(baseDir, url, 'index.sass')
+  ];
+
+  for (const p of possiblePaths) {
+    try {
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+        return p;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return null;
+}
+
+export function transformSass(options: SassTransformOptions = {}): TransformFn {
+  return async (file) => {
+    // Only process .scss / .sass files
+    if (!/\.(scss|sass)$/i.test(file.extname)) return file;
+    // Skip partials starting with '_'
+    if (path.basename(file.path).startsWith('_')) return null;
+
+    try {
+      const searchDirs = [
+        path.dirname(file.path),
+        path.resolve(file.cwd, 'node_modules'),
+        path.resolve(process.cwd(), 'node_modules'),
+        path.resolve(process.cwd(), '..', 'node_modules'),
+        ...(options.includePaths || [])
+      ];
+
+      const customImporter: sass.FileImporter<'async'> = {
+        findFileUrl(url) {
+          let cleanUrl = url;
+          if (cleanUrl.startsWith('~')) {
+            cleanUrl = cleanUrl.slice(1);
+          }
+
+          // 1. Check alias resolution
+          if (options.alias) {
+            for (const [aliasKey, aliasTarget] of Object.entries(options.alias)) {
+              if (cleanUrl === aliasKey) {
+                const resolved = resolveFile(path.dirname(aliasTarget), path.basename(aliasTarget));
+                if (resolved) return new URL(`file://${resolved}`);
+              } else if (cleanUrl.startsWith(`${aliasKey}/`)) {
+                const subPath = cleanUrl.slice(aliasKey.length + 1);
+                const resolved = resolveFile(aliasTarget, subPath);
+                if (resolved) return new URL(`file://${resolved}`);
+              }
+            }
+          }
+
+          // 2. Check searchDirs
+          for (const dir of searchDirs) {
+            const resolved = resolveFile(dir, cleanUrl);
+            if (resolved) {
+              return new URL(`file://${resolved}`);
+            }
+          }
+          return null;
+        }
+      };
+
+      const result = await sass.compileStringAsync(file.toString(), {
+        url: new URL(`file://${file.path}`),
+        syntax: file.extname === '.sass' ? 'indented' : 'scss',
+        loadPaths: searchDirs,
+        importers: [customImporter, new sass.NodePackageImporter()],
+        style: options.style || 'expanded',
+        sourceMap: options.sourceMap || false
+      });
+
+      file.contents = Buffer.from(result.css);
+      file.extname = '.css';
+      return file;
+    } catch (err: any) {
+      logger.error('sass', `Error compiling ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}

package/src/pipeline/transforms/terser.ts

@@ -0,0 +1,20 @@
+import { minify, MinifyOptions } from 'terser';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export function transformTerser(options: MinifyOptions = {}): TransformFn {
+  return async (file) => {
+    if (!/\.js$/i.test(file.extname)) return file;
+
+    try {
+      const result = await minify(file.toString(), options);
+      if (result.code) {
+        file.contents = Buffer.from(result.code);
+      }
+      return file;
+    } catch (err: any) {
+      logger.error('terser', `Error minifying ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}