@texuli/tools 0.0.0-stage → 0.1.0-next.0

package/dist/cli-update/cli.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+export type UpdateCliArgs = {
+    command: 'diff' | 'update' | null;
+    id: string | null;
+    cwd: string;
+    sourceRoot: string;
+    baseRoot: string | null;
+    baseVersion: string | null;
+    outDir: string | null;
+    version: string | null;
+    conflicts: 'refuse' | 'markers';
+    json: boolean;
+    dryRun: boolean;
+    prune: boolean;
+    help: boolean;
+};
+/** Parse argv after the process name: a `diff` or `update` verb, then the id. */
+export declare function parseUpdateArgs(argv: readonly string[], defaults?: {
+    cwd?: string;
+    sourceRoot?: string;
+}): UpdateCliArgs;
+/** Run the diff/update CLI. Returns a process exit code. */
+export declare function runUpdateCli(argv: readonly string[], defaults?: {
+    cwd?: string;
+    sourceRoot?: string;
+}): Promise<number>;

package/dist/cli-update/cli.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+/**
+ * `texuli diff <component>` and `texuli update <component>`
+ *
+ * Three-way merge of a copied component against the installed version and the
+ * new source. No network.
+ *
+ *   pnpm exec tsx packages/tools/src/cli-update/cli.ts diff button --cwd <app> \
+ *     --source-root <new repo> --base-root <repo at the installed version>
+ *   … update button … [--dry-run] [--prune] [--conflicts markers] [--json]
+ */
+import { isMainModule } from "../cli-add/cli.js";
+import { diffComponent, updateComponent } from "./update.js";
+const USAGE = `Usage: texuli diff <component> [options]
+       texuli update <component> [options]
+
+Three-way merge of a copied component (texuli add) with a new Texuli source.
+
+Options:
+  --cwd <dir>             Consumer project root (default: process.cwd())
+  --source-root <dir>     Root that holds the new source under packages/ (default: cwd)
+  --base-root <dir>       Root that holds the source at the installed version (the merge base)
+  --base-version <ver>    Refuse unless the installed version (from the headers) equals this
+  --out <dir>             Component directory relative to cwd (default: src/components/texuli/<id>)
+  --version <semver>      Version stamped in the new headers (default: 0.0.0)
+  --conflicts <mode>      refuse (default: write nothing) or markers (write conflict markers)
+  --prune                 Delete files removed upstream that were not edited locally
+  --dry-run               update: plan only; write nothing
+  --json                  Machine-readable result on stdout
+  --help                  Show this help
+`;
+/** Parse argv after the process name: a `diff` or `update` verb, then the id. */
+export function parseUpdateArgs(argv, defaults) {
+    const cwd = defaults?.cwd ?? process.cwd();
+    const args = {
+        command: null,
+        id: null,
+        cwd,
+        sourceRoot: defaults?.sourceRoot ?? cwd,
+        baseRoot: null,
+        baseVersion: null,
+        outDir: null,
+        version: null,
+        conflicts: 'refuse',
+        json: false,
+        dryRun: false,
+        prune: false,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined)
+            break;
+        const next = () => {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('-'))
+                throw new Error(`${arg} needs a value`);
+            i += 1;
+            return value;
+        };
+        if (arg === '--help' || arg === '-h')
+            args.help = true;
+        else if (arg === '--json')
+            args.json = true;
+        else if (arg === '--dry-run')
+            args.dryRun = true;
+        else if (arg === '--prune')
+            args.prune = true;
+        else if (arg === '--cwd')
+            args.cwd = next();
+        else if (arg === '--source-root')
+            args.sourceRoot = next();
+        else if (arg === '--base-root')
+            args.baseRoot = next();
+        else if (arg === '--base-version')
+            args.baseVersion = next();
+        else if (arg === '--out')
+            args.outDir = next();
+        else if (arg === '--version')
+            args.version = next();
+        else if (arg === '--conflicts') {
+            const mode = next();
+            if (mode !== 'refuse' && mode !== 'markers') {
+                throw new Error(`--conflicts is refuse or markers (got ${mode})`);
+            }
+            args.conflicts = mode;
+        }
+        else if (arg.startsWith('-'))
+            throw new Error(`Unknown option: ${arg}`);
+        else if (args.command === null) {
+            if (arg !== 'diff' && arg !== 'update')
+                throw new Error(`Unknown command: ${arg}`);
+            args.command = arg;
+        }
+        else if (args.id === null)
+            args.id = arg;
+        else
+            throw new Error(`Unexpected argument: ${arg}`);
+    }
+    return args;
+}
+function printHuman(result, command) {
+    for (const error of result.errors)
+        console.error(error);
+    const from = result.installedVersion ?? '(not installed)';
+    console.log(`${command} ${result.id} (${result.package}) ${from} → ${result.version}: ${result.outDir}`);
+    for (const file of result.files) {
+        const note = file.conflicts > 0 ? ` (${file.conflicts} conflict(s))` : '';
+        console.log(`  ${file.status.padEnd(16)} ${file.action.padEnd(12)} ${file.path}${note}`);
+    }
+    if (command === 'diff') {
+        for (const file of result.files)
+            if (file.diff)
+                process.stdout.write(file.diff);
+    }
+}
+/** Run the diff/update CLI. Returns a process exit code. */
+export async function runUpdateCli(argv, defaults) {
+    let args;
+    try {
+        args = parseUpdateArgs(argv, defaults);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        console.error(USAGE);
+        return 1;
+    }
+    if (args.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (!args.command || !args.id) {
+        console.error('A command (diff or update) and a component id are required.');
+        console.error(USAGE);
+        return 1;
+    }
+    const options = {
+        id: args.id,
+        cwd: args.cwd,
+        sourceRoot: args.sourceRoot,
+        ...(args.baseRoot ? { baseRoot: args.baseRoot } : {}),
+        ...(args.baseVersion ? { baseVersion: args.baseVersion } : {}),
+        ...(args.outDir ? { outDir: args.outDir } : {}),
+        ...(args.version ? { version: args.version } : {}),
+        conflicts: args.conflicts,
+        dryRun: args.dryRun,
+        prune: args.prune,
+    };
+    const result = args.command === 'diff' ? await diffComponent(options) : await updateComponent(options);
+    if (args.json)
+        console.log(JSON.stringify(result));
+    else
+        printHuman(result, args.command);
+    return result.ok ? 0 : 1;
+}
+if (isMainModule(import.meta.url)) {
+    runUpdateCli(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}

package/dist/cli-update/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@texuli/tools/cli-update` — `texuli diff <component>` and `texuli update <component>`
+ *
+ * Three-way merge of a copied component (from `texuli add`) against the
+ * installed version and the new source. Local filesystem only (no network).
+ */
+export { parseUpdateArgs, runUpdateCli, type UpdateCliArgs } from './cli.js';
+export { type MergeLabels, type MergeResult, matchLines, merge3, splitLines, unifiedDiff, } from './lines.js';
+export { type ParsedProvenance, parseProvenance } from './provenance.js';
+export type { UpdateFile, UpdateFileStatus, UpdateOptions, UpdateResult, } from './types.js';
+export { diffComponent, updateComponent } from './update.js';

package/dist/cli-update/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@texuli/tools/cli-update` — `texuli diff <component>` and `texuli update <component>`
+ *
+ * Three-way merge of a copied component (from `texuli add`) against the
+ * installed version and the new source. Local filesystem only (no network).
+ */
+export { parseUpdateArgs, runUpdateCli } from "./cli.js";
+export { matchLines, merge3, splitLines, unifiedDiff, } from "./lines.js";
+export { parseProvenance } from "./provenance.js";
+export { diffComponent, updateComponent } from "./update.js";

package/dist/cli-update/lines.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Line diffing for `texuli diff` and `texuli update`: Myers' O(ND) diff,
+ * a diff3 three-way merge and unified diff output. Plain strings only.
+ */
+/** Split text into lines that keep their `\n` (so `\r\n` and a missing final newline survive). */
+export declare function splitLines(text: string): string[];
+/**
+ * For each line of `a`, the index of the matching line in `b`, or -1.
+ * Matches increase monotonically (a longest common subsequence). When the
+ * files differ by more than {@link MAX_EDITS} lines, only the common prefix
+ * and suffix match.
+ */
+export declare function matchLines(a: readonly string[], b: readonly string[]): Int32Array;
+export interface MergeLabels {
+    local: string;
+    base: string;
+    upstream: string;
+}
+export interface MergeResult {
+    text: string;
+    /** Conflict regions written with markers (0 for a clean merge). */
+    conflicts: number;
+}
+/**
+ * diff3 three-way merge of `local` and `upstream`, which both started from
+ * `base`. A region only one side changed takes that side; a region both
+ * changed the same way takes it once; any other region becomes a conflict
+ * with `<<<<<<<`, `|||||||`, `=======` and `>>>>>>>` markers.
+ */
+export declare function merge3(base: string, local: string, upstream: string, labels: MergeLabels): MergeResult;
+/**
+ * A unified diff (`---`/`+++` headers and `@@` hunks) from `before` to
+ * `after`, or an empty string when they are equal.
+ */
+export declare function unifiedDiff(before: string, after: string, names: {
+    from: string;
+    to: string;
+}, context?: number): string;

package/dist/cli-update/lines.js

@@ -0,0 +1,189 @@
+/**
+ * Line diffing for `texuli diff` and `texuli update`: Myers' O(ND) diff,
+ * a diff3 three-way merge and unified diff output. Plain strings only.
+ */
+/** Edit distance past which the middle of two files is treated as replaced. */
+const MAX_EDITS = 4000;
+/** Split text into lines that keep their `\n` (so `\r\n` and a missing final newline survive). */
+export function splitLines(text) {
+    return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+/**
+ * For each line of `a`, the index of the matching line in `b`, or -1.
+ * Matches increase monotonically (a longest common subsequence). When the
+ * files differ by more than {@link MAX_EDITS} lines, only the common prefix
+ * and suffix match.
+ */
+export function matchLines(a, b) {
+    const match = new Int32Array(a.length).fill(-1);
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start]) {
+        match[start] = start;
+        start += 1;
+    }
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+        endA -= 1;
+        endB -= 1;
+        match[endA] = endB;
+    }
+    const n = endA - start;
+    const m = endB - start;
+    if (n === 0 || m === 0)
+        return match;
+    const max = Math.min(n + m, MAX_EDITS);
+    const offset = max + 1;
+    const v = new Int32Array(2 * max + 3);
+    const trace = [];
+    let found = false;
+    search: for (let d = 0; d <= max; d += 1) {
+        trace.push(v.slice());
+        for (let k = -d; k <= d; k += 2) {
+            const down = k === -d || (k !== d && (v[offset + k - 1] ?? 0) < (v[offset + k + 1] ?? 0));
+            let x = down ? (v[offset + k + 1] ?? 0) : (v[offset + k - 1] ?? 0) + 1;
+            let y = x - k;
+            while (x < n && y < m && a[start + x] === b[start + y]) {
+                x += 1;
+                y += 1;
+            }
+            v[offset + k] = x;
+            if (x >= n && y >= m) {
+                found = true;
+                break search;
+            }
+        }
+    }
+    if (!found)
+        return match;
+    let x = n;
+    let y = m;
+    for (let d = trace.length - 1; d >= 0; d -= 1) {
+        const prev = trace[d];
+        const k = x - y;
+        const down = k === -d || (k !== d && (prev[offset + k - 1] ?? 0) < (prev[offset + k + 1] ?? 0));
+        const prevK = down ? k + 1 : k - 1;
+        const prevX = prev[offset + prevK] ?? 0;
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            x -= 1;
+            y -= 1;
+            match[start + x] = start + y;
+        }
+        x = prevX;
+        y = prevY;
+    }
+    return match;
+}
+const sameLines = (a, b) => a.length === b.length && a.every((line, i) => line === b[i]);
+const withNewline = (lines) => lines.map((line, i) => (i === lines.length - 1 && !line.endsWith('\n') ? `${line}\n` : line));
+/**
+ * diff3 three-way merge of `local` and `upstream`, which both started from
+ * `base`. A region only one side changed takes that side; a region both
+ * changed the same way takes it once; any other region becomes a conflict
+ * with `<<<<<<<`, `|||||||`, `=======` and `>>>>>>>` markers.
+ */
+export function merge3(base, local, upstream, labels) {
+    const o = splitLines(base);
+    const a = splitLines(local);
+    const b = splitLines(upstream);
+    const ma = matchLines(o, a);
+    const mb = matchLines(o, b);
+    const out = [];
+    let conflicts = 0;
+    let i = 0;
+    let ia = 0;
+    let ib = 0;
+    while (i < o.length || ia < a.length || ib < b.length) {
+        if (i < o.length && ma[i] === ia && mb[i] === ib) {
+            out.push(o[i]);
+            i += 1;
+            ia += 1;
+            ib += 1;
+            continue;
+        }
+        let k = i;
+        while (k < o.length && (ma[k] === -1 || mb[k] === -1))
+            k += 1;
+        const endA = k < o.length ? ma[k] : a.length;
+        const endB = k < o.length ? mb[k] : b.length;
+        const chunkO = o.slice(i, k);
+        const chunkA = a.slice(ia, endA);
+        const chunkB = b.slice(ib, endB);
+        if (sameLines(chunkA, chunkO))
+            out.push(...chunkB);
+        else if (sameLines(chunkB, chunkO) || sameLines(chunkA, chunkB))
+            out.push(...chunkA);
+        else {
+            conflicts += 1;
+            out.push(`<<<<<<< ${labels.local}\n`, ...withNewline(chunkA), `||||||| ${labels.base}\n`, ...withNewline(chunkO), '=======\n', ...withNewline(chunkB), `>>>>>>> ${labels.upstream}\n`);
+        }
+        i = k;
+        ia = endA;
+        ib = endB;
+    }
+    return { text: out.join(''), conflicts };
+}
+/**
+ * A unified diff (`---`/`+++` headers and `@@` hunks) from `before` to
+ * `after`, or an empty string when they are equal.
+ */
+export function unifiedDiff(before, after, names, context = 3) {
+    if (before === after)
+        return '';
+    const a = splitLines(before);
+    const b = splitLines(after);
+    const match = matchLines(a, b);
+    const ops = [];
+    let j = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        const target = match[i];
+        if (target === -1) {
+            ops.push({ op: '-', line: a[i] });
+            continue;
+        }
+        for (; j < target; j += 1)
+            ops.push({ op: '+', line: b[j] });
+        ops.push({ op: ' ', line: a[i] });
+        j += 1;
+    }
+    for (; j < b.length; j += 1)
+        ops.push({ op: '+', line: b[j] });
+    // Hunks: every change with `context` lines around it, overlapping ranges joined.
+    const ranges = [];
+    ops.forEach((entry, index) => {
+        if (entry.op === ' ')
+            return;
+        const start = Math.max(0, index - context);
+        const end = Math.min(ops.length, index + context + 1);
+        const last = ranges[ranges.length - 1];
+        if (last && start <= last.end)
+            last.end = Math.max(last.end, end);
+        else
+            ranges.push({ start, end });
+    });
+    const out = [`--- ${names.from}\n`, `+++ ${names.to}\n`];
+    let cursor = 0;
+    let oldLine = 0;
+    let newLine = 0;
+    for (const range of ranges) {
+        for (; cursor < range.start; cursor += 1) {
+            if (ops[cursor]?.op !== '+')
+                oldLine += 1;
+            if (ops[cursor]?.op !== '-')
+                newLine += 1;
+        }
+        const hunk = ops.slice(range.start, range.end);
+        const oldCount = hunk.filter((h) => h.op !== '+').length;
+        const newCount = hunk.filter((h) => h.op !== '-').length;
+        const oldStart = oldCount === 0 ? oldLine : oldLine + 1;
+        const newStart = newCount === 0 ? newLine : newLine + 1;
+        out.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@\n`);
+        for (const h of hunk) {
+            out.push(`${h.op}${h.line}`);
+            if (!h.line.endsWith('\n'))
+                out.push('\n\\n');
+        }
+    }
+    return out.join('');
+}

package/dist/cli-update/provenance.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read the provenance header `texuli add` stamps on copied files.
+ */
+import type { ProvenanceMeta } from '../cli-add/provenance.js';
+export interface ParsedProvenance {
+    meta: ProvenanceMeta;
+    /** The file without its header: the text the merge compares. */
+    body: string;
+}
+/**
+ * Parse the header at the very start of `content`, or `null` when the file
+ * has none (a file the consumer added, or a header they edited away).
+ */
+export declare function parseProvenance(content: string): ParsedProvenance | null;

package/dist/cli-update/provenance.js

@@ -0,0 +1,51 @@
+const BEGIN = '@texuli/add — copied styled source. Do not remove this block.';
+const FIELDS = ['id', 'package', 'version', 'source'];
+/** Each header form `provenanceHeader` writes: opening line, line prefix, closing line. */
+const FORMS = [
+    { open: '/**', prefix: ' * ', close: ' */' },
+    { open: '<!--', prefix: '  ', close: '-->' },
+    { open: null, prefix: '# ', close: null },
+];
+/**
+ * Parse the header at the very start of `content`, or `null` when the file
+ * has none (a file the consumer added, or a header they edited away).
+ */
+export function parseProvenance(content) {
+    for (const form of FORMS) {
+        const expected = 1 + FIELDS.length + (form.open ? 1 : 0) + (form.close ? 1 : 0);
+        const lines = content.split('\n', expected);
+        if (lines.length < expected)
+            continue;
+        let at = 0;
+        if (form.open !== null && lines[at++] !== form.open)
+            continue;
+        if (lines[at++] !== `${form.prefix}${BEGIN}`)
+            continue;
+        const values = {};
+        let valid = true;
+        for (const field of FIELDS) {
+            const line = lines[at++] ?? '';
+            const head = `${form.prefix}${field}: `;
+            if (!line.startsWith(head)) {
+                valid = false;
+                break;
+            }
+            values[field] = line.slice(head.length);
+        }
+        if (!valid)
+            continue;
+        if (form.close !== null && lines[at++] !== form.close)
+            continue;
+        const headerLength = lines.slice(0, at).join('\n').length + 1;
+        return {
+            meta: {
+                id: values.id ?? '',
+                package: values.package ?? '',
+                version: values.version ?? '',
+                source: values.source ?? '',
+            },
+            body: content.slice(headerLength),
+        };
+    }
+    return null;
+}

package/dist/cli-update/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Types for `texuli diff` and `texuli update`: three-way merge of copied
+ * components against the installed version.
+ */
+import type { AddableComponent } from '../cli-add/types.js';
+/** What happens to one file of the component. */
+export type UpdateFileStatus = 
+/** Local copy already equals the new source. */
+'unchanged'
+/** Not edited locally: replaced by the new source. */
+ | 'fast-forward'
+/** Edited locally, unchanged upstream: the local edit is kept. */
+ | 'kept-local'
+/** Edited on both sides without overlap: merged. */
+ | 'merged'
+/** Edited on both sides in the same region. */
+ | 'conflict'
+/** New upstream file. */
+ | 'added'
+/** Removed upstream and not edited locally (deleted only with `prune`). */
+ | 'removed'
+/** Removed upstream but edited locally: kept. */
+ | 'removed-modified'
+/** Deleted locally, still upstream: stays deleted. */
+ | 'deleted-locally'
+/** Local and new source differ but no base was given, so they cannot merge. */
+ | 'needs-base'
+/** A local file without a provenance header: never touched. */
+ | 'untracked';
+export type UpdateFile = {
+    /** Path relative to the component directory (`/` separators). */
+    path: string;
+    status: UpdateFileStatus;
+    action: 'write' | 'would-write' | 'delete' | 'would-delete' | 'none';
+    /** Unified diff from the local file to its result (empty when unchanged). */
+    diff: string;
+    /** Conflict regions in the result (written only with `conflicts: 'markers'`). */
+    conflicts: number;
+};
+export type UpdateResult = {
+    ok: boolean;
+    id: string;
+    package: string;
+    /** The component directory in the consumer project. */
+    outDir: string;
+    /** Version in the local provenance headers, or null when none is installed. */
+    installedVersion: string | null;
+    /** Version stamped by the update. */
+    version: string;
+    files: UpdateFile[];
+    /** Total conflict regions. */
+    conflicts: number;
+    errors: string[];
+    /** True when nothing was written (`diff`, or `update --dry-run`). */
+    dryRun: boolean;
+};
+export type UpdateOptions = {
+    /** Component id (as given to `texuli add`). */
+    id: string;
+    /** Consumer project root. */
+    cwd: string;
+    /** Monorepo (or fixture) root with the **new** source under `packages/`. */
+    sourceRoot: string;
+    /**
+     * Monorepo root with the source at the **installed** version, the merge
+     * base. Without it only files that need no merge can update.
+     */
+    baseRoot?: string;
+    /** When set, refuse unless the installed version equals it. */
+    baseVersion?: string;
+    /** Component directory relative to `cwd` (default `src/components/texuli/<id>`). */
+    outDir?: string;
+    /** Version stamped into the new headers (default `0.0.0`). */
+    version?: string;
+    /** Plan only; write nothing. */
+    dryRun?: boolean;
+    /** Delete files removed upstream that were not edited locally. */
+    prune?: boolean;
+    /** `refuse` (default): any conflict writes nothing. `markers`: write conflict markers. */
+    conflicts?: 'refuse' | 'markers';
+    /** Override the built-in registry (tests). */
+    registry?: readonly AddableComponent[];
+};

package/dist/cli-update/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli-update/update.d.ts

@@ -0,0 +1,12 @@
+import type { UpdateOptions, UpdateResult } from './types.js';
+/**
+ * Show what `texuli update` would do: each file's status and a unified diff
+ * from the local file to its result. Writes nothing.
+ */
+export declare function diffComponent(options: UpdateOptions): Promise<UpdateResult>;
+/**
+ * Update a copied component to the new source with a three-way merge.
+ * Writes nothing when any file conflicts (unless `conflicts: 'markers'`) or
+ * needs a base that was not given.
+ */
+export declare function updateComponent(options: UpdateOptions): Promise<UpdateResult>;