@vinktarhq/cli 0.1.0

package/dist/cjs/bundler/rollup.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stampChunk = stampChunk;
+exports.repairChunks = repairChunks;
+exports.writeMaps = writeMaps;
+exports.vinktarRollup = vinktarRollup;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const debug_id_js_1 = require("../debug-id.js");
+const discover_js_1 = require("../discover.js");
+const core_js_1 = require("./core.js");
+/**
+ * Whether the snippet can go at the TOP of this chunk without corrupting its map.
+ *
+ * Under Rollup it can: nothing re-derives the map after `renderChunk`, so the inserted line is
+ * accounted for exactly, in `repairChunks`.
+ *
+ * Under Rolldown it cannot, and this is the difference between a working map and a meaningless
+ * one. Rolldown's Oxc minifier runs AFTER every `renderChunk` hook and rebuilds the chunk's map
+ * from the code we hand it, composed against a base that knows nothing about our extra line — so
+ * every mapping in the file lands inside the snippet. A build proved it: the first segment of a
+ * Vite 8 chunk pointed at generated column 1, which is the middle of the injected IIFE.
+ *
+ * There is no hook between those two steps, and expressing the insertion as a real transform map
+ * would mean emitting a segment per token for every chunk — which is what both incumbents do, and
+ * what their magic-string dependency is for. Appending moves nothing, so it needs no map at all;
+ * the cost is that a chunk which throws while initialising does not register its id there.
+ *
+ * `this.meta.rolldownVersion` is Rolldown's own marker, absent under Rollup.
+ */
+function prependable(context) {
+    return context?.meta?.rolldownVersion === undefined;
+}
+/**
+ * The name a chunk answers to in every hook.
+ *
+ * `fileName` still holds a hash PLACEHOLDER during `renderChunk` — the whole point of the hook is
+ * that the hash has not been computed yet — so keying on it there and looking it up by the final
+ * name later matched nothing at all. `preliminaryFileName` is the one that is stable across both.
+ */
+function keyOf(chunk) {
+    return chunk.preliminaryFileName ?? chunk.fileName ?? '';
+}
+/** Stamp one chunk and remember what its map will owe. Shared with the Vite plugin. */
+function stampChunk(code, rawChunk, tracked, context) {
+    const chunk = (rawChunk ?? {});
+    const stamped = (0, core_js_1.stamp)(code, { prepend: prependable(context) });
+    tracked.set(keyOf(chunk), { debugId: stamped.debugId, line: stamped.line });
+    /**
+     * `map: null`, and it must be exactly that — not an omitted key.
+     *
+     * Rollup reads it as a strict null check: `null` keeps this transform OUT of the chunk's
+     * sourcemap chain and leaves the existing map alone, while `undefined` (an omitted key) enters
+     * the chain as a MISSING link, which makes Rollup log `SOURCEMAP_BROKEN` and collapse the whole
+     * chain to empty mappings. The line this inserted is accounted for in {@link repairChunks}
+     * instead, exactly, rather than through a generated transform map.
+     */
+    return stamped.changed ? { code: stamped.code, map: null } : null;
+}
+/**
+ * Square the chunk's map up with the snippet, and put back the comment that ran after us.
+ *
+ * Both halves belong in `generateBundle` with `order: 'pre'`, and both are load-bearing:
+ *
+ * - **The comment.** Vite 8 is Rolldown, and its Oxc minifier runs after `renderChunk`: it strips
+ *   the `//# debugId=` line and leaves the snippet, so the uploader read no id, derived a fresh
+ *   one from the minified bytes and filed the map under an id no stack frame reports. The
+ *   embedded marker survives minification and is what this package reads back, but the comment is
+ *   what every OTHER tool reads.
+ * - **The mappings.** Inserting a line above the code shifts every generated line below it by
+ *   one, and splicing one empty group into `mappings` is the exact repair. It has to happen HERE,
+ *   before any other plugin's `generateBundle`, because Vite's own
+ *   `vite:build-import-analysis` rewrites the entry chunk and then does
+ *   `combineSourcemaps(fileName, [itsMap, chunk.map])`. Its map is measured against the code
+ *   INCLUDING our line; combining it with a `chunk.map` that is one line short does not merely
+ *   lose precision, it collapses to empty mappings — the entry chunk of every Vite build with a
+ *   dynamic import, silently resolving nothing.
+ *
+ * `order: 'pre'` is therefore not politeness; it is the difference between a working map and an
+ * empty one.
+ */
+function repairChunks(bundle, tracked) {
+    for (const asset of Object.values(bundle)) {
+        const chunk = asset;
+        if (chunk.type !== 'chunk' || typeof chunk.code !== 'string')
+            continue;
+        const found = tracked.get(keyOf(chunk));
+        if (found === undefined)
+            continue;
+        // Placed the way `inject` places it — before a trailing `sourceMappingURL`, never after.
+        // Devtools stop reading at the mapping comment, so a debugId line below it would make the map
+        // unreachable, which is a strange way to fix a source-map tool.
+        chunk.code = (0, debug_id_js_1.setDebugIdComment)(chunk.code, found.debugId);
+        const map = chunk.map;
+        if (map === null || map === undefined || typeof map.mappings !== 'string')
+            continue;
+        if (found.line !== null) {
+            map.mappings = String((0, debug_id_js_1.shiftMappings)({ mappings: map.mappings }, found.line)['mappings']);
+        }
+        // Vite carries `debugId` across its own re-combination by name, and nothing else, so this is
+        // the one field worth setting here rather than only on disk.
+        map['debugId'] = found.debugId;
+    }
+}
+/**
+ * Write each chunk's map to disk, because Rollup will not write ours.
+ *
+ * Rollup emits a chunk's map from the reference it captured while rendering, so an edit made in
+ * `generateBundle` reaches the bundle object every other plugin sees and never reaches the file.
+ * It survived for chunks a later Vite plugin happened to rebuild and vanished for the rest, which
+ * is the worst shape a bug of this kind can take: half the maps in a build one line out, and no
+ * warning from anything.
+ *
+ * Writing the file afterwards is safe in a way that rewriting a chunk would not be. Nothing hashes
+ * a source map: its name comes from the chunk's, no integrity attribute covers it, and no importer
+ * reads its contents.
+ */
+async function writeMaps(dir, bundle, tracked, done) {
+    const chunks = Object.values(bundle).filter((asset) => {
+        const chunk = asset;
+        return chunk.type === 'chunk' && tracked.has(keyOf(chunk));
+    });
+    if (process.env['VINKTAR_DEBUG_TRACK'])
+        console.log('WRITEMAPS', dir, chunks.length, [...tracked.keys()], Object.keys(bundle));
+    if (chunks.length === 0)
+        return;
+    // One walk of the output, reusing the chunk-to-map resolution the uploader uses — which asks
+    // the chunk what its map is called before assuming a `<file>.map` sibling, and so copes with
+    // `output.sourcemapFileNames`.
+    const { artifacts } = await (0, discover_js_1.discover)(dir).catch(() => ({ artifacts: [] }));
+    const maps = new Map(artifacts.map((artifact) => [artifact.file, artifact.map]));
+    for (const chunk of chunks) {
+        const found = tracked.get(keyOf(chunk));
+        const map = chunk.map;
+        if (map === null || map === undefined || typeof map.mappings !== 'string')
+            continue;
+        const path = maps.get((0, node_path_1.join)(dir, chunk.fileName ?? ''));
+        if (process.env['VINKTAR_DEBUG_TRACK'])
+            console.log('WM', chunk.fileName, path, found.line, typeof map.mappings);
+        // Idempotent per file per build: `writeBundle` fires once per output, and two outputs writing
+        // into one directory must not each rewrite the other's maps.
+        if (path === undefined || path === null || done.has(path))
+            continue;
+        done.add(path);
+        try {
+            await (0, promises_1.writeFile)(path, JSON.stringify({ ...map, debugId: found.debugId, debug_id: found.debugId }), 'utf8');
+        }
+        catch {
+            // A read-only volume, or a map the bundler did not actually write. The chunk still carries
+            // its id, and the uploader will stamp whatever map it does find.
+        }
+    }
+}
+function vinktarRollup(options = {}) {
+    if ((0, core_js_1.disabled)(options))
+        return inert();
+    const tracked = new Map();
+    const repaired = new Set();
+    const stamping = options.injectDebugIds !== false;
+    const run = (0, core_js_1.session)(options);
+    return {
+        name: 'vinktar',
+        buildStart() {
+            // A watch rebuild rewrites every file, so last build's bookkeeping would suppress this
+            // build's repairs.
+            tracked.clear();
+            repaired.clear();
+        },
+        renderChunk: {
+            order: 'post',
+            handler(code, chunk) {
+                return stamping ? stampChunk(code, chunk, tracked, this) : null;
+            },
+        },
+        generateBundle: {
+            order: 'pre',
+            handler(_options, bundle) {
+                repairChunks(bundle, tracked);
+            },
+        },
+        /**
+         * Every output, not the first one.
+         *
+         * The previous version latched on the output directory and returned early for the rest, so a
+         * build with a client output and an SSR output — SvelteKit, Nuxt, Remix, or plain
+         * `output: [a, b]` — uploaded the first and silently dropped the second. Re-uploading costs
+         * nothing: the content hashes are checked against the server before any bytes are sent.
+         */
+        async writeBundle(output, bundle) {
+            const dir = outputDir(output);
+            if (dir === '')
+                return;
+            await writeMaps(dir, bundle, tracked, repaired);
+            await run.upload(dir);
+            // Deleting here rather than only in `closeBundle`, because `closeBundle` fires only when the
+            // caller closes the bundle — Vite and the Rollup CLI do, `rollup.rollup().write()` does not.
+            // Leaving the maps in a public directory on that path is the exact leak this deletes.
+            await run.cleanup();
+        },
+        async closeBundle() {
+            await run.cleanup();
+        },
+    };
+}
+/**
+ * The plugin that does nothing, for `disable: true`.
+ *
+ * A whole plugin rather than a flag threaded through every hook, so that a config reused by
+ * vitest or Storybook costs a function call and not a directory walk.
+ */
+function inert() {
+    return {
+        name: 'vinktar',
+        buildStart() { },
+        renderChunk: { order: 'post', handler: () => null },
+        generateBundle: { order: 'pre', handler: () => { } },
+        writeBundle: async () => { },
+        closeBundle: async () => { },
+    };
+}
+function outputDir(output) {
+    const dir = output.dir ?? (output.file === undefined ? '' : (0, node_path_1.join)(output.file, '..'));
+    if (dir === '')
+        return '';
+    return (0, node_path_1.isAbsolute)(dir) ? dir : (0, node_path_1.join)(process.cwd(), dir);
+}

package/dist/cjs/bundler/rspack.d.ts

@@ -0,0 +1,8 @@
+/**
+ * rspack reimplements webpack's plugin API — `thisCompilation`, `processAssets`, the stage
+ * constants and `compilation.updateAsset` all behave the same way — so the plugin is the same
+ * plugin. This module exists so an rspack config can say `vinktarRspack` and read correctly,
+ * rather than importing something called "webpack" into a build that is not one.
+ */
+export { VinktarWebpackPlugin as VinktarRspackPlugin, vinktarWebpack as vinktarRspack } from './webpack.js';
+export type { BundlerOptions } from './core.js';

package/dist/cjs/bundler/rspack.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vinktarRspack = exports.VinktarRspackPlugin = void 0;
+/**
+ * rspack reimplements webpack's plugin API — `thisCompilation`, `processAssets`, the stage
+ * constants and `compilation.updateAsset` all behave the same way — so the plugin is the same
+ * plugin. This module exists so an rspack config can say `vinktarRspack` and read correctly,
+ * rather than importing something called "webpack" into a build that is not one.
+ */
+var webpack_js_1 = require("./webpack.js");
+Object.defineProperty(exports, "VinktarRspackPlugin", { enumerable: true, get: function () { return webpack_js_1.VinktarWebpackPlugin; } });
+Object.defineProperty(exports, "vinktarRspack", { enumerable: true, get: function () { return webpack_js_1.vinktarWebpack; } });

package/dist/cjs/bundler/webpack.d.ts

@@ -0,0 +1,83 @@
+import { type BundlerOptions } from './core.js';
+/**
+ * The webpack plugin, which is also the rspack plugin.
+ *
+ * ```js
+ * const { vinktarWebpack } = require('@vinktarhq/cli/webpack');
+ * module.exports = { plugins: [new vinktarWebpack({ urlPrefix: '/static/' })] };
+ * ```
+ *
+ * rspack reimplements webpack's plugin API, including `processAssets` and its stage constants, so
+ * one class serves both. `@vinktarhq/cli/rspack` re-exports this under its own name because that is
+ * what a reader of an rspack config expects to see.
+ *
+ * ## The stage matters
+ *
+ * `PROCESS_ASSETS_STAGE_OPTIMIZE_HASH` is the documented point for "changing the asset in a way
+ * that affects its hash", and it is where the real content hashes are computed. Doing this any
+ * later — in `afterEmit`, say — means the file on disk no longer matches the hash in its own name,
+ * and everything downstream that recorded that hash (a PWA precache manifest, an integrity
+ * attribute, a precompressed copy) is pointing at bytes that are gone.
+ *
+ * One BEFORE it, though, not at it. Taps sharing a stage run in registration order, and rspack's
+ * real-content-hash pass is native and registered before any user plugin — so at the stage itself
+ * the hash was computed from the pre-injection bytes and the filename described a file that never
+ * existed. A build proved it: with the plugin and without it, rspack emitted the same
+ * `main.<hash>.js` for different content. webpack is unaffected either way, so both take the
+ * earlier slot.
+ *
+ * It is also after `PROCESS_ASSETS_STAGE_DEV_TOOLING`, which is where `SourceMapDevToolPlugin`
+ * emits the `.map` assets and appends the `sourceMappingURL` comment. That ordering is what lets
+ * the map be corrected in the same pass as the chunk: the injected line shifts every mapping
+ * below it, and a map fixed in a later hook would already have been hashed and written.
+ */
+/** Just enough of webpack's shape to compile without depending on it. */
+interface Compiler {
+    hooks: {
+        thisCompilation: {
+            tap(name: string, fn: (compilation: Compilation) => void): void;
+        };
+        afterEmit: {
+            tapPromise(name: string, fn: (compilation: Compilation) => Promise<void>): void;
+        };
+    };
+    options: {
+        output?: {
+            path?: string;
+        };
+    };
+    webpack?: {
+        Compilation?: {
+            PROCESS_ASSETS_STAGE_OPTIMIZE_HASH?: number;
+        };
+        sources?: SourceLibrary;
+    };
+}
+interface SourceLibrary {
+    RawSource: new (value: string) => unknown;
+}
+interface Compilation {
+    hooks: {
+        processAssets: {
+            tap(options: {
+                name: string;
+                stage: number;
+            }, fn: (assets: Record<string, Asset>) => void): void;
+        };
+    };
+    updateAsset(name: string, source: unknown): void;
+    getAsset(name: string): {
+        source: Asset;
+    } | undefined;
+}
+interface Asset {
+    source(): string | Buffer;
+}
+export declare class VinktarWebpackPlugin {
+    private readonly options;
+    constructor(options?: BundlerOptions);
+    apply(compiler: Compiler): void;
+}
+/** Named for how a config reads: `new vinktarWebpack({ … })`. */
+export declare const vinktarWebpack: typeof VinktarWebpackPlugin;
+export type { BundlerOptions } from './core.js';

package/dist/cjs/bundler/webpack.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vinktarWebpack = exports.VinktarWebpackPlugin = void 0;
+const core_js_1 = require("./core.js");
+const NAME = 'vinktar';
+/** webpack's own value for this stage, when the compiler does not expose the constant. */
+const STAGE_OPTIMIZE_HASH = 2500;
+class VinktarWebpackPlugin {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    apply(compiler) {
+        if ((0, core_js_1.disabled)(this.options))
+            return;
+        const stamping = this.options.injectDebugIds !== false;
+        const RawSource = compiler.webpack?.sources?.RawSource;
+        const stage = (compiler.webpack?.Compilation?.PROCESS_ASSETS_STAGE_OPTIMIZE_HASH ?? STAGE_OPTIMIZE_HASH) - 1;
+        const run = (0, core_js_1.session)(this.options);
+        compiler.hooks.thisCompilation.tap(NAME, (compilation) => {
+            compilation.hooks.processAssets.tap({ name: NAME, stage }, (assets) => {
+                if (!stamping)
+                    return;
+                const write = (name, value) => {
+                    // `RawSource` is reached through the compiler rather than imported, so this file has no
+                    // build-time dependency on webpack at all — and so rspack's own sources are used under
+                    // rspack rather than webpack's.
+                    compilation.updateAsset(name, RawSource === undefined ? value : new RawSource(value));
+                };
+                for (const name of Object.keys(assets)) {
+                    if (!(0, core_js_1.isScript)(name))
+                        continue;
+                    const asset = compilation.getAsset(name);
+                    if (asset === undefined)
+                        continue;
+                    const code = String(asset.source.source());
+                    const stamped = (0, core_js_1.stamp)(code);
+                    if (!stamped.changed)
+                        continue;
+                    write(name, stamped.code);
+                    // The map is corrected in the same stage, from the same bytes. Skipping it leaves every
+                    // line one out of step, which is worse than no map: the frame resolves, to the wrong
+                    // line, and nobody doubts a source map that answered.
+                    const mapName = mapAssetOf(name, code, assets);
+                    if (mapName === null)
+                        continue;
+                    const map = compilation.getAsset(mapName);
+                    if (map === undefined)
+                        continue;
+                    try {
+                        write(mapName, (0, core_js_1.injectIntoMap)(String(map.source.source()), stamped.debugId, stamped.line));
+                    }
+                    catch {
+                        // A map asset that is not JSON is not ours to rewrite.
+                    }
+                }
+            });
+        });
+        compiler.hooks.afterEmit.tapPromise(NAME, async () => {
+            const dir = compiler.options.output?.path ?? '';
+            if (dir === '')
+                return;
+            await run.upload(dir);
+            await run.cleanup();
+        });
+    }
+}
+exports.VinktarWebpackPlugin = VinktarWebpackPlugin;
+const SOURCE_MAPPING_COMMENT = /^\/\/[#@] sourceMappingURL=(.*)$/gm;
+/**
+ * The map asset belonging to a chunk asset.
+ *
+ * `output.sourceMapFilename` is configurable — `[file].map` is only the default, and a build that
+ * puts maps under `sourcemaps/[name].map` has no `<file>.map` asset at all. The chunk names its
+ * own map in the comment `SourceMapDevToolPlugin` just appended, so that is asked first and the
+ * sibling is the fallback.
+ */
+function mapAssetOf(name, code, assets) {
+    let last = null;
+    for (const match of code.matchAll(SOURCE_MAPPING_COMMENT))
+        last = match;
+    const referenced = last?.[1]?.trim();
+    if (referenced !== undefined && referenced !== '' && !referenced.startsWith('data:')) {
+        const slash = name.lastIndexOf('/');
+        const directory = slash === -1 ? '' : name.slice(0, slash + 1);
+        const target = normalise(`${directory}${(referenced.split('?')[0] ?? '').split('#')[0] ?? ''}`);
+        if (target in assets)
+            return target;
+    }
+    return `${name}.map` in assets ? `${name}.map` : null;
+}
+/** Collapse `a/../b` and `./b`, which a relative sourceMappingURL legitimately contains. */
+function normalise(path) {
+    const parts = [];
+    for (const segment of path.split('/')) {
+        if (segment === '.' || segment === '')
+            continue;
+        if (segment === '..') {
+            parts.pop();
+            continue;
+        }
+        parts.push(segment);
+    }
+    return parts.join('/');
+}
+/** Named for how a config reads: `new vinktarWebpack({ … })`. */
+exports.vinktarWebpack = VinktarWebpackPlugin;

package/dist/cjs/cli.d.ts

@@ -0,0 +1,17 @@
+import { VERSION } from './version.js';
+export interface Args {
+    readonly positional: string[];
+    readonly flags: Map<string, string | boolean>;
+    /** Values of repeatable flags, in order. `--ignore` and `--header` are the two. */
+    readonly repeated: Map<string, string[]>;
+}
+export declare function parse(argv: readonly string[]): Args;
+/**
+ * Exit codes: 0 fine, 1 the thing did not work, 2 it worked and something is wrong anyway.
+ *
+ * Two rather than one for `--strict`, so a pipeline can tell "the upload failed" from "the upload
+ * succeeded and half your chunks have no maps" — which are different problems with different
+ * owners, and merging them means neither gets fixed.
+ */
+export declare function run(argv: readonly string[], log?: (message?: any, ...optionalParams: any[]) => void, fail?: (message?: any, ...optionalParams: any[]) => void): Promise<number>;
+export { VERSION };