vantris 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -6,6 +6,113 @@
  * single extension point through which future versions will grow (plugins,
  * build options, HMR, server tuning, …) without breaking existing configs.
  */
+/**
+ * Development server options.
+ *
+ * Extension point for the dev server. v0.2.0 exposes only `port` and `host`;
+ * future versions will add HMR, proxy, HTTPS, and middleware hooks here
+ * without breaking existing configs.
+ */
+interface DevConfig {
+    /**
+     * Port the dev server listens on.
+     *
+     * @default 3000
+     */
+    port?: number;
+    /**
+     * Host the dev server binds to.
+     *
+     * @default "localhost"
+     */
+    host?: string;
+}
+/**
+ * Information about a chunk, passed to a {@link ChunkFileNames} function.
+ *
+ * This is a Vantris-owned mirror of the bundler's pre-render data: it exposes a
+ * stable, curated subset so naming functions never touch Rolldown's types.
+ */
+interface ChunkInfo {
+    /** Chunk name used in naming patterns. */
+    name: string;
+    /** Whether this is a static entry chunk. */
+    isEntry: boolean;
+    /** Whether this is a dynamic-import entry chunk. */
+    isDynamicEntry: boolean;
+    /** Absolute id of the module this chunk represents, if any. */
+    facadeModuleId: string | null;
+    /** Absolute ids of the modules included in this chunk. */
+    moduleIds: string[];
+    /** Names exported by this chunk. */
+    exports: string[];
+}
+/** Information about an asset, passed to an {@link AssetFileNames} function. */
+interface AssetInfo {
+    /** Candidate names for the asset. */
+    names: string[];
+    /** Absolute paths of the asset's original source files. */
+    originalFileNames: string[];
+}
+/** A chunk naming pattern, or a function returning one per chunk. */
+type ChunkFileNames = string | ((chunk: ChunkInfo) => string);
+/** An asset naming pattern, or a function returning one per asset. */
+type AssetFileNames = string | ((asset: AssetInfo) => string);
+/**
+ * Production build options.
+ *
+ * Extension point for the build system. v0.3.0 exposes a small surface; the
+ * interface is shaped to grow (e.g. `target`, `manifest`, `cssCodeSplit`,
+ * build hooks/plugins) without breaking existing configs. The underlying
+ * bundler (Rolldown) is an internal detail and is never exposed here.
+ */
+interface BuildConfig {
+    /**
+     * Minify the output.
+     *
+     * @default true
+     */
+    minify?: boolean;
+    /**
+     * Source map strategy.
+     *
+     * - `false` — no source maps
+     * - `true` — separate `.map` files
+     * - `"inline"` — appended to each file as a data URL
+     * - `"hidden"` — separate files without the `//# sourceMappingURL` comment
+     *
+     * @default false
+     */
+    sourcemap?: boolean | "inline" | "hidden";
+    /**
+     * Directory (relative to `outDir`) for built chunks and assets. Used to
+     * derive the default `*FileNames` patterns below.
+     *
+     * @default "assets"
+     */
+    assetsDir?: string;
+    /**
+     * Naming pattern for entry chunks — a string with `[name]`, `[hash]`,
+     * `[ext]`, `[extname]` placeholders, or a function receiving {@link ChunkInfo}.
+     *
+     * @default `${assetsDir}/[name]-[hash].js`
+     */
+    entryFileNames?: ChunkFileNames;
+    /**
+     * Naming pattern for shared/dynamic chunks (code splitting). String or a
+     * function receiving {@link ChunkInfo}.
+     *
+     * @default `${assetsDir}/[name]-[hash].js`
+     */
+    chunkFileNames?: ChunkFileNames;
+    /**
+     * Naming pattern for emitted assets (images, fonts, …). String or a function
+     * receiving {@link AssetInfo}.
+     *
+     * @default `${assetsDir}/[name]-[hash][extname]`
+     */
+    assetFileNames?: AssetFileNames;
+}
 interface Config {
     /**
      * Project root. Resolved relative to the current working directory.
@@ -33,6 +140,23 @@ interface Config {
      * @default "./dist"
      */
     outDir?: string;
+    /**
+     * Public base path the app is served from. Prefixed to built asset and entry
+     * URLs so they resolve correctly when deployed under a sub-path or a CDN.
+     * Normalised to always start and end with `/` (URLs keep their trailing `/`).
+     *
+     * @example "/" (default), "/my-app/", "https://cdn.example.com/assets/"
+     * @default "/"
+     */
+    base?: string;
+    /**
+     * Development server options. See {@link DevConfig}.
+     */
+    dev?: DevConfig;
+    /**
+     * Production build options. See {@link BuildConfig}.
+     */
+    build?: BuildConfig;
 }
 /**
  * A factory form of {@link Config}. Supporting a function (sync or async)
@@ -119,6 +243,20 @@ interface ResolvedPaths {
     outDir: string;
 }
 
+/** Dev-server options after defaults have been applied (no optionals). */
+interface ResolvedDevConfig {
+    readonly port: number;
+    readonly host: string;
+}
+/** Build options after defaults have been applied (no optionals). */
+interface ResolvedBuildConfig {
+    readonly minify: boolean;
+    readonly sourcemap: boolean | "inline" | "hidden";
+    readonly assetsDir: string;
+    readonly entryFileNames: ChunkFileNames;
+    readonly chunkFileNames: ChunkFileNames;
+    readonly assetFileNames: AssetFileNames;
+}
 /**
  * A {@link Config} after defaults have been applied and paths resolved.
  *
@@ -131,6 +269,12 @@ interface ResolvedConfig {
     readonly raw: Config;
     /** Absolute paths derived from the configuration. */
     readonly paths: ResolvedPaths;
+    /** Public base path, normalised to start and end with `/`. */
+    readonly base: string;
+    /** Resolved dev-server options. */
+    readonly dev: ResolvedDevConfig;
+    /** Resolved build options. */
+    readonly build: ResolvedBuildConfig;
     /** Absolute path of the config file that was loaded, if any. */
     readonly configFile: string | null;
 }
@@ -146,17 +290,31 @@ interface ResolvedConfig {
  */
 declare function resolveConfig(raw: Config, cwd: string, configFile?: string | null): ResolvedConfig;
 
+/**
+ * A `<script type="module">` reference discovered in the HTML entry.
+ *
+ * Only the `src` is captured in v0.2.0. The shape is deliberately an object
+ * (rather than a bare string) so later versions can attach resolved paths,
+ * inline contents, or transform metadata without breaking consumers.
+ */
+interface HtmlModuleScript {
+    /** The `src` attribute value, exactly as authored (e.g. `/src/main.ts`). */
+    src: string;
+}
 /**
  * The HTML entry point of a project, as discovered and parsed by the
- * `html` subsystem. Parsing is deliberately minimal in v0.1.0 — only what is
- * needed to locate the entry — but the shape anticipates richer analysis
- * (script tags, module graph roots, asset references) in later versions.
+ * `html` subsystem. Parsing stays intentionally lightweight — just enough to
+ * locate the entry and its module scripts — but the shape anticipates richer
+ * analysis (asset references, injection points, module graph roots) in later
+ * versions on the road to HMR and plugin transforms.
  */
 interface HtmlEntry {
     /** Absolute path to the `index.html` file. */
     file: string;
     /** Raw HTML contents. */
     html: string;
+    /** Module scripts (`<script type="module" src=...>`) found in the entry. */
+    scripts: HtmlModuleScript[];
 }
 
 /**
@@ -167,32 +325,33 @@ interface HtmlEntry {
 declare function detectHtmlEntry(root: string): Promise<HtmlEntry | null>;
 
 /**
- * Parses raw HTML into an {@link HtmlEntry}.
+ * Parses raw HTML into an {@link HtmlEntry}, extracting `<script type="module">`
+ * `src` references.
  *
- * v0.1.0 keeps this intentionally minimal: it only wraps the file path and
- * contents. The function exists as the single, isolated home for HTML
- * analysis so later versions can grow it (extracting `<script type="module">`
- * entries, asset references, injection points for HMR) without scattering
- * parsing logic across the codebase.
+ * The analysis is intentionally regex-light rather than a full DOM parse: in
+ * dev we only need to know the module entry points. This module is the single,
+ * isolated home for HTML analysis, so it can grow toward a real parser (for
+ * HMR boundaries, plugin transforms, virtual modules) without touching callers.
  */
 declare function parseHtml(file: string, html: string): HtmlEntry;
 
-/** Current Vantris version. Kept in sync with package.json at release time. */
-declare const VERSION = "0.1.0";
-
-interface LoggerOptions {
-    /** When `false`, `debug` calls are dropped. @default false */
-    verbose?: boolean;
-    /** Sink for output. Defaults to the console; overridable for tests. */
-    sink?: Pick<Console, "log" | "warn" | "error">;
-}
 /**
- * Creates the default console-backed {@link Logger}.
+ * The dev-only live-reload client, injected into the served HTML.
  *
- * The sink is injectable so tests can capture output, and verbosity is a
- * construction-time concern rather than a global flag.
+ * v0.2.0 does a full page reload on any change. The WebSocket URL is derived
+ * from `location.host` so it works regardless of how the host is addressed
+ * (`localhost`, `127.0.0.1`, LAN IP). The message payload is ignored for now;
+ * v1.x will branch on it to drive HMR instead of a full reload.
  */
-declare function createLogger(options?: LoggerOptions): Logger;
+declare const DEV_CLIENT_SCRIPT = "<script type=\"module\">\n  // Injected by Vantris dev server \u2014 live reload (full page).\n  const connect = () => {\n    const ws = new WebSocket(\"ws://\" + location.host);\n    ws.addEventListener(\"message\", () => location.reload());\n    // Reconnect if the dev server restarts.\n    ws.addEventListener(\"close\", () => setTimeout(connect, 1000));\n  };\n  connect();\n</script>";
+/**
+ * Injects {@link DEV_CLIENT_SCRIPT} into an HTML document.
+ *
+ * The script is placed just before `</head>` when present, otherwise before
+ * `</body>`, otherwise appended — so it loads before user modules without
+ * requiring a well-formed document.
+ */
+declare function injectDevClient(html: string): string;
 
 /**
  * The execution context threaded into every command.
@@ -210,6 +369,84 @@ interface Context {
     readonly logger: Logger;
 }
 
+/** Options for {@link startDevServer}. */
+interface DevServerOptions {
+    ctx: Context;
+    /** The detected HTML entry, when present. */
+    entry: HtmlEntry | null;
+}
+/** A running dev server. */
+interface DevServerHandle {
+    /** Address the server is listening on, e.g. `http://localhost:3000/`. */
+    readonly url: string;
+    readonly host: string;
+    readonly port: number;
+    /** Pushes a full-page reload to every connected browser. */
+    broadcastReload(): void;
+    /** Stops the HTTP and WebSocket servers. */
+    close(): Promise<void>;
+}
+/**
+ * Starts the H3-based development server.
+ *
+ * Responsibilities are split across the `server` module: this file owns the
+ * HTTP routing (H3) and lifecycle, {@link createStaticLoader} owns file
+ * resolution + transpilation, and {@link createReloadSocket} owns live reload.
+ * The HTTP and WebSocket servers share a single port.
+ */
+declare function startDevServer(options: DevServerOptions): Promise<DevServerHandle>;
+
+/** Options handed to the build pipeline. */
+interface BuildOptions {
+    ctx: Context;
+    /** The detected HTML entry; required for a build. */
+    entry: HtmlEntry | null;
+}
+/** Summary of a completed build. */
+interface BuildResult {
+    /** Absolute output directory. */
+    outDir: string;
+    /** Entry points: original HTML `src` → emitted file name. */
+    entries: ReadonlyArray<{
+        src: string;
+        fileName: string;
+    }>;
+    /** Total build duration in milliseconds. */
+    durationMs: number;
+    /** Number of files emitted by the bundler (chunks + assets), plus HTML. */
+    fileCount: number;
+}
+/**
+ * Produces an optimised production build into `outDir`.
+ *
+ * The pipeline is split across the `build` module by responsibility — entry
+ * resolution + HTML ({@link resolveHtmlEntry}/{@link renderProductionHtml}),
+ * bundling ({@link bundle}), assets ({@link copyPublicDir}), and filesystem
+ * output ({@link cleanOutDir}/{@link writeHtml}). This file only orchestrates
+ * and logs, which keeps each stage independently testable and leaves room for
+ * future build hooks/plugins to slot between stages.
+ *
+ * @throws {HtmlEntryError | BuildError} with an explicit message on failure.
+ */
+declare function runBuild(options: BuildOptions): Promise<BuildResult>;
+
+/** Current Vantris version. Kept in sync with package.json at release time. */
+declare const VERSION = "0.3.0";
+
+interface LoggerOptions {
+    /** When `false`, `debug` calls are dropped. @default false */
+    verbose?: boolean;
+    /** Sink for output. Defaults to the console; overridable for tests. */
+    sink?: Pick<Console, "log" | "warn" | "error">;
+}
+/**
+ * Creates the default console-backed {@link Logger}.
+ *
+ * The sink is injectable so tests can capture output, and verbosity is a
+ * construction-time concern rather than a global flag.
+ */
+declare function createLogger(options?: LoggerOptions): Logger;
+
 interface CreateContextOptions {
     /** Working directory the command was invoked from. */
     cwd: string;
@@ -227,6 +464,34 @@ interface CreateContextOptions {
  */
 declare function createContext(options: CreateContextOptions): Promise<Context>;
 
+/** A change reported by the {@link Watcher}. */
+interface WatchEvent {
+    /** What happened to the file. */
+    kind: "add" | "change" | "unlink";
+    /** Absolute path of the affected file. */
+    file: string;
+}
+interface WatcherOptions {
+    /** Directory tree to watch (typically `rootDir`). */
+    dir: string;
+    logger: Logger;
+    /** Called on every relevant filesystem change. */
+    onChange: (event: WatchEvent) => void;
+}
+/** A running filesystem watcher. */
+interface Watcher {
+    /** Stops watching and releases OS resources. */
+    close(): Promise<void>;
+}
+/**
+ * Watches a directory tree and reports file changes.
+ *
+ * This is the single home for filesystem watching — the dev server depends on
+ * the {@link Watcher} interface, not on chokidar, so the backing implementation
+ * can change (or gain HMR-oriented metadata) without rippling outward.
+ */
+declare function createWatcher(options: WatcherOptions): Watcher;
+
 /**
  * Base class for all errors thrown intentionally by Vantris. The CLI layer can
  * recognise these and render them cleanly (without a stack trace), while
@@ -244,6 +509,10 @@ declare class ConfigError extends VantrisError {
 declare class HtmlEntryError extends VantrisError {
     readonly name = "HtmlEntryError";
 }
+/** Thrown when the production build fails (bundling, HTML, asset copy, …). */
+declare class BuildError extends VantrisError {
+    readonly name = "BuildError";
+}
 /** Thrown for functionality declared but not yet implemented in this version. */
 declare class NotImplementedError extends VantrisError {
     readonly name = "NotImplementedError";
@@ -296,4 +565,4 @@ declare const enum ExitCode {
  */
 declare function run(argv: readonly string[], options?: RunOptions): Promise<ExitCode>;
 
-export { type Command, type Config, ConfigError, type ConfigFn, type ConfigInput, type Context, type HtmlEntry, HtmlEntryError, type Logger, NotImplementedError, type ResolvedConfig, type ResolvedPaths, VERSION, VantrisError, commands, createContext, createLogger, defineConfig, detectHtmlEntry, isVantrisError, loadConfig, parseHtml, resolveConfig, run };
+export { type AssetFileNames, type AssetInfo, type BuildConfig, BuildError, type BuildOptions, type BuildResult, type ChunkFileNames, type ChunkInfo, type Command, type Config, ConfigError, type ConfigFn, type ConfigInput, type Context, DEV_CLIENT_SCRIPT, type DevConfig, type DevServerHandle, type DevServerOptions, type HtmlEntry, HtmlEntryError, type HtmlModuleScript, type Logger, NotImplementedError, type ResolvedBuildConfig, type ResolvedConfig, type ResolvedDevConfig, type ResolvedPaths, VERSION, VantrisError, type WatchEvent, type Watcher, type WatcherOptions, commands, createContext, createLogger, createWatcher, defineConfig, detectHtmlEntry, injectDevClient, isVantrisError, loadConfig, parseHtml, resolveConfig, run, runBuild, startDevServer };

package/dist/index.js

@@ -1,4 +1,4 @@
-export { ConfigError, HtmlEntryError, NotImplementedError, VERSION, VantrisError, commands, createContext, createLogger, detectHtmlEntry, isVantrisError, loadConfig, parseHtml, resolveConfig, run } from './chunk-PSXNP5S5.js';
+export { BuildError, ConfigError, DEV_CLIENT_SCRIPT, HtmlEntryError, NotImplementedError, VERSION, VantrisError, commands, createContext, createLogger, createWatcher, detectHtmlEntry, injectDevClient, isVantrisError, loadConfig, parseHtml, resolveConfig, run, runBuild, startDevServer } from './chunk-LRSN7SF4.js';
 
 // src/config/define-config.ts
 function defineConfig(config) {

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "vantris",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A modern bundler for JavaScript/TypeScript",
   "type": "module",
   "license": "MIT",
-  "keywords": ["bundler", "build-tool", "dev-server", "typescript"],
+  "keywords": [
+    "bundler",
+    "build-tool",
+    "dev-server",
+    "typescript"
+  ],
   "bin": {
     "vantris": "dist/cli/index.js"
   },
@@ -17,7 +22,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "engines": {
     "node": ">=20.11.0"
   },
@@ -25,10 +32,35 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "clean": "rm -rf dist",
     "prepublishOnly": "pnpm run build"
   },
   "devDependencies": {
-    "tsup": "^8.3.5"
+    "@types/ws": "^8.18.1",
+    "less": "^4.6.7",
+    "sass": "^1.101.0",
+    "tsup": "^8.3.5",
+    "vitest": "^4.1.9"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "esbuild": "^0.28.1",
+    "h3": "2.0.1-rc.22",
+    "lightningcss": "^1.32.0",
+    "magic-string": "^0.30.21",
+    "postcss": "^8.5.15",
+    "postcss-load-config": "^6.0.1",
+    "rolldown": "^1.1.3",
+    "ws": "^8.21.0"
+  },
+  "peerDependencies": {
+    "less": "*",
+    "sass": "*"
+  },
+  "peerDependenciesMeta": {
+    "sass": { "optional": true },
+    "less": { "optional": true }
   }
 }