shell-aliasforge 0.0.0-stage → 0.1.0

package/dist/analyze/stats.js

@@ -0,0 +1,94 @@
+import { normalizeCommand, splitSubcommands, tokenize } from "./normalize.js";
+const ASSIGNMENT = /^[A-Za-z_]\w*=/;
+/** Words that run another command, so the real program is the next word. */
+const WRAPPERS = new Set(["sudo", "doas", "time", "nohup", "command", "env", "exec", "nice", "builtin"]);
+/** Shell syntax that can start a sub-command without being a program. */
+const SYNTAX = new Set(["do", "then", "else", "elif", "!", "{", "(", "if", "while", "until"]);
+const DAY_SECONDS = 86_400;
+/** The program a sub-command runs, skipping `VAR=x`, `sudo`, `time` and similar. */
+export function programOf(unit) {
+    const tokens = tokenize(unit);
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        if (ASSIGNMENT.test(token) || SYNTAX.has(token)) {
+            i++;
+        }
+        else if (WRAPPERS.has(token)) {
+            i++;
+            while (i < tokens.length && tokens[i].startsWith("-"))
+                i++;
+        }
+        else {
+            break;
+        }
+    }
+    const program = tokens[i];
+    if (program === undefined || program.startsWith("#"))
+        return undefined;
+    return program.slice(program.lastIndexOf("/") + 1) || undefined;
+}
+function isoDate(seconds) {
+    return new Date(seconds * 1000).toISOString().slice(0, 10);
+}
+function validTimestamps(entries) {
+    return entries.flatMap((entry) => {
+        const t = entry.timestamp;
+        return t !== undefined && Number.isFinite(t) && !Number.isNaN(new Date(t * 1000).getTime()) ? [t] : [];
+    });
+}
+function countPrograms(entries) {
+    const counts = new Map();
+    for (const entry of entries) {
+        for (const unit of splitSubcommands(normalizeCommand(entry.command))) {
+            const program = programOf(unit);
+            if (program !== undefined)
+                counts.set(program, (counts.get(program) ?? 0) + 1);
+        }
+    }
+    return [...counts]
+        .map(([command, count]) => ({ command, count }))
+        .sort((a, b) => b.count - a.count || a.command.localeCompare(b.command));
+}
+/** Summarize parsed history: size, most-used programs and time span. */
+export function computeStats(entries, top) {
+    const unique = new Set(entries.map((entry) => normalizeCommand(entry.command)));
+    unique.delete("");
+    const times = validTimestamps(entries);
+    const stats = {
+        historyEntries: entries.length,
+        uniqueCommands: unique.size,
+        timestampedEntries: times.length,
+        topCommands: countPrograms(entries).slice(0, top),
+    };
+    if (times.length === 0)
+        return stats;
+    const first = times.reduce((a, b) => Math.min(a, b));
+    const last = times.reduce((a, b) => Math.max(a, b));
+    return {
+        ...stats,
+        firstDate: isoDate(first),
+        lastDate: isoDate(last),
+        spanDays: Math.floor((last - first) / DAY_SECONDS),
+    };
+}
+export function renderStats(shell, stats) {
+    const lines = [
+        `Shell: ${shell}`,
+        `Entries: ${stats.historyEntries.toLocaleString("en-US")} (${stats.uniqueCommands.toLocaleString("en-US")} unique)`,
+    ];
+    if (stats.firstDate !== undefined) {
+        lines.push(`Time span: ${stats.firstDate} to ${stats.lastDate} (${stats.spanDays} days, ${stats.timestampedEntries.toLocaleString("en-US")} entries with a time)`);
+    }
+    else {
+        lines.push("Time span: unknown (this history has no timestamps)");
+    }
+    if (stats.topCommands.length === 0)
+        return lines.join("\n");
+    const width = Math.max(...stats.topCommands.map((c) => c.command.length));
+    lines.push("", "Top commands:");
+    stats.topCommands.forEach((item, index) => {
+        lines.push(`  ${String(index + 1).padStart(2)}  ${item.command.padEnd(width)}  ${item.count}`);
+    });
+    return lines.join("\n");
+}

package/dist/analyze/suggest.js

@@ -0,0 +1,70 @@
+import { proposeNames } from "./naming.js";
+import { normalizeCommand, splitSubcommands } from "./normalize.js";
+import { renderDefinition } from "./render.js";
+import { aliasScore } from "./score.js";
+import { buildCandidates, kindOf } from "./templates.js";
+/** Full normalized line plus its sub-commands, each counted once per entry. */
+function unitsOf(entry) {
+    const line = normalizeCommand(entry.command);
+    if (line === "" || line.startsWith("#"))
+        return [];
+    return [...new Set([line, ...splitSubcommands(line)])];
+}
+function candidatePool(entries, options) {
+    const units = entries.map(unitsOf).filter((list) => list.length > 0);
+    const eligible = buildCandidates(units).filter((c) => c.count >= options.minCount && c.replacedLength >= options.minLength);
+    const upperBound = (c) => c.count * c.replacedLength;
+    eligible.sort((a, b) => upperBound(b) - upperBound(a));
+    return eligible.slice(0, Math.max(options.top * 10, 100));
+}
+function nameAndScore(candidate, isTaken) {
+    const names = proposeNames(candidate, isTaken);
+    const first = names[0];
+    if (first === undefined)
+        return undefined;
+    return { candidate, names, score: aliasScore(candidate, first) };
+}
+/** An exact command already covered by a chosen `<prefix> <arg>` alias. */
+function isCovered(candidate, chosen) {
+    if (candidate.shape !== "exact")
+        return false;
+    const prefix = candidate.command.slice(0, candidate.command.lastIndexOf(" "));
+    return chosen.some((c) => c.candidate.shape === "trailing" && c.candidate.command === prefix);
+}
+function select(named, top) {
+    const chosen = [];
+    const used = new Set();
+    for (const item of named) {
+        if (chosen.length >= top)
+            break;
+        const name = item.names.find((n) => !used.has(n));
+        if (name === undefined || isCovered(item.candidate, chosen))
+            continue;
+        used.add(name);
+        chosen.push({ ...item, names: [name, ...item.names.filter((n) => n !== name)] });
+    }
+    return chosen;
+}
+function toSuggestion(item, rank, shell) {
+    const { candidate, names } = item;
+    const kind = kindOf(candidate);
+    const name = names[0];
+    return {
+        rank,
+        kind,
+        pattern: candidate.pattern,
+        command: candidate.command,
+        count: candidate.count,
+        score: aliasScore(candidate, name),
+        names,
+        definition: renderDefinition(shell, { kind, name, command: candidate.command }),
+    };
+}
+/** Rank alias and function suggestions from parsed history. */
+export function suggest(entries, isTaken, options) {
+    const named = candidatePool(entries, options)
+        .map((candidate) => nameAndScore(candidate, isTaken))
+        .filter((item) => item !== undefined && item.score > 0)
+        .sort((a, b) => b.score - a.score || a.candidate.pattern.localeCompare(b.candidate.pattern));
+    return select(named, options.top).map((item, index) => toSuggestion(item, index + 1, options.shell));
+}

package/dist/analyze/templates.js

@@ -0,0 +1,90 @@
+import { isBalanced, isFlag, tokenize } from "./normalize.js";
+export const VAR = "<arg>";
+/** Longest command (in words) we try to template. Keeps the work bounded. */
+const MAX_TOKENS = 12;
+function addToGroup(groups, tokens, index) {
+    const template = tokens.map((token, i) => (i === index ? VAR : token));
+    const key = template.join(" ");
+    const group = groups.get(key) ?? { tokens: template, values: new Set(), count: 0 };
+    group.values.add(tokens[index]);
+    group.count++;
+    groups.set(key, group);
+}
+function addTemplates(trailing, middle, tokens) {
+    if (tokens.length < 2 || tokens.length > MAX_TOKENS)
+        return;
+    const last = tokens.length - 1;
+    if (!isFlag(tokens[last]))
+        addToGroup(trailing, tokens, last);
+    for (let i = 1; i < last; i++) {
+        if (!isFlag(tokens[i]))
+            addToGroup(middle, tokens, i);
+    }
+}
+function exactCandidates(counts) {
+    return [...counts].map(([command, count]) => ({
+        shape: "exact",
+        command,
+        pattern: command,
+        count,
+        replacedLength: command.length,
+    }));
+}
+function trailingCandidates(groups) {
+    return [...groups.values()]
+        .filter((group) => group.values.size >= 2)
+        .map((group) => {
+        const command = group.tokens.slice(0, -1).join(" ");
+        return {
+            shape: "trailing",
+            command,
+            pattern: `${command} ${VAR}`,
+            count: group.count,
+            replacedLength: command.length,
+        };
+    });
+}
+/**
+ * A function body is pasted into an rc file, so reject text that could break
+ * out of it: unbalanced quotes or brackets, comments, heredocs, a trailing
+ * `&`, `|` or backslash.
+ */
+function safeForFunction(tokens) {
+    const command = tokens.join(" ");
+    return isBalanced(command) && !/[&|\\]$/.test(command) && !command.includes("<<") && !tokens.some((t) => t.startsWith("#"));
+}
+function middleCandidates(groups) {
+    return [...groups.values()]
+        .filter((group) => group.values.size >= 2 && safeForFunction(group.tokens))
+        .map((group) => {
+        const command = group.tokens.join(" ");
+        return {
+            shape: "middle",
+            command,
+            pattern: command,
+            count: group.count,
+            replacedLength: command.length - VAR.length,
+        };
+    });
+}
+/**
+ * Build alias/function candidates from per-entry lists of unique command units.
+ * Identical units group together; units that differ only in one argument group
+ * into a template. A last-argument template stays an alias (extra words pass
+ * through); a middle-argument template needs a function.
+ */
+export function buildCandidates(units) {
+    const exact = new Map();
+    const trailing = new Map();
+    const middle = new Map();
+    for (const entryUnits of units) {
+        for (const unit of entryUnits) {
+            exact.set(unit, (exact.get(unit) ?? 0) + 1);
+            addTemplates(trailing, middle, tokenize(unit));
+        }
+    }
+    return [...exactCandidates(exact), ...trailingCandidates(trailing), ...middleCandidates(middle)];
+}
+export function kindOf(candidate) {
+    return candidate.shape === "middle" ? "function" : "alias";
+}

package/dist/apply/apply.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { renderDefinition } from "../analyze/render.js";
+import { createBackup } from "./backup.js";
+import { mergeItems, readItems, writeItems } from "./block.js";
+import { unifiedDiff } from "./diff.js";
+export function rcPathFor(shell, home, env) {
+    if (shell === "bash")
+        return join(home, ".bashrc");
+    if (shell === "zsh")
+        return join(env.ZDOTDIR || home, ".zshrc");
+    return join(home, ".config", "fish", "config.fish");
+}
+function readIfExists(path) {
+    return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+}
+function itemFor(shell, selected, name) {
+    const { kind, command } = selected.suggestion;
+    return { name, lines: renderDefinition(shell, { kind, name, command }).split("\n") };
+}
+/** Choose a name per selection that does not clash with a different definition in the block. */
+function resolve(shell, selected, existing, explicit) {
+    const taken = new Map(existing.flatMap((item) => (item.name ? [[item.name, item.lines.join("\n")]] : [])));
+    const incoming = [];
+    const skipped = [];
+    for (const choice of selected) {
+        const names = explicit ? [choice.name] : choice.suggestion.names;
+        const item = names
+            .map((name) => itemFor(shell, choice, name))
+            .find((candidate) => {
+            const current = taken.get(candidate.name);
+            return current === undefined || current === candidate.lines.join("\n");
+        });
+        if (!item) {
+            skipped.push(choice.suggestion.pattern);
+            continue;
+        }
+        taken.set(item.name, item.lines.join("\n"));
+        incoming.push(item);
+    }
+    return { incoming, skipped };
+}
+/**
+ * Write the selected definitions into the managed block of the rc file.
+ * Existing definitions in the block are kept. A timestamped backup is made
+ * before any change, and nothing is touched when the result would be identical.
+ */
+export function applyToRc(input) {
+    const current = readIfExists(input.rcPath);
+    const content = current ?? "";
+    const existing = readItems(content, input.shell);
+    const { incoming, skipped } = resolve(input.shell, input.selected, existing, input.explicitNames);
+    const merged = mergeItems(existing, incoming);
+    const next = incoming.length === 0 ? content : writeItems(content, merged.items);
+    const result = {
+        rcPath: input.rcPath,
+        changes: merged.changes,
+        skipped,
+        diff: unifiedDiff(input.rcPath, content, next),
+        written: false,
+    };
+    if (next === content || input.dryRun)
+        return result;
+    const backupPath = current === undefined ? undefined : createBackup(input.rcPath, input.now);
+    mkdirSync(dirname(input.rcPath), { recursive: true });
+    writeFileSync(input.rcPath, next);
+    return backupPath === undefined ? { ...result, written: true } : { ...result, written: true, backupPath };
+}

package/dist/apply/backup.js

@@ -0,0 +1,20 @@
+import { copyFileSync, constants } from "node:fs";
+function stamp(now) {
+    return now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "").replace("T", "-");
+}
+/** Copy `path` to `<path>.aliasforge-backup-<UTC timestamp>`. Never overwrites a backup. */
+export function createBackup(path, now) {
+    const base = `${path}.aliasforge-backup-${stamp(now)}`;
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const target = attempt === 0 ? base : `${base}-${attempt}`;
+        try {
+            copyFileSync(path, target, constants.COPYFILE_EXCL);
+            return target;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    throw new Error(`Could not create a backup next to ${path}`);
+}

package/dist/apply/block.js

@@ -0,0 +1,98 @@
+export const START = "# >>> aliasforge >>>";
+export const END = "# <<< aliasforge <<<";
+const NOTE = "# Managed by aliasforge. `aliasforge apply` edits only this block.";
+/** The rc file has a damaged managed block. Nothing is written when this is thrown. */
+export class BlockError extends Error {
+}
+function parse(content) {
+    const eol = content.includes("\r\n") ? "\r\n" : "\n";
+    const lines = content.split(/\r?\n/);
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return { lines, eol };
+}
+function indexesOf(lines, marker) {
+    return lines.flatMap((line, index) => (line.trimEnd() === marker ? [index] : []));
+}
+function locate(lines) {
+    const starts = indexesOf(lines, START);
+    const ends = indexesOf(lines, END);
+    if (starts.length === 0 && ends.length === 0)
+        return undefined;
+    const [start] = starts;
+    const [end] = ends;
+    if (starts.length !== 1 || ends.length !== 1 || start === undefined || end === undefined || start > end) {
+        throw new BlockError(`The aliasforge block is damaged (expected exactly one "${START}" before one "${END}"). Fix it by hand; nothing was changed.`);
+    }
+    return { start, end };
+}
+const ALIAS_LINE = /^alias\s+([^\s=]+)/;
+const FISH_FUNCTION = /^function\s+(\S+)/;
+const POSIX_FUNCTION = /^([A-Za-z_]\w*)\(\)\s*\{/;
+/** Split block lines into items. Multi-line fish functions stay together. */
+export function parseItems(lines, shell) {
+    const items = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "" || line === NOTE)
+            continue;
+        const fn = shell === "fish" ? FISH_FUNCTION.exec(line) : null;
+        if (fn) {
+            const close = lines.findIndex((candidate, at) => at > i && candidate.trim() === "end");
+            const last = close === -1 ? lines.length - 1 : close;
+            items.push({ name: fn[1], lines: lines.slice(i, last + 1) });
+            i = last;
+            continue;
+        }
+        const match = ALIAS_LINE.exec(line) ?? POSIX_FUNCTION.exec(line);
+        items.push(match ? { name: match[1], lines: [line] } : { lines: [line] });
+    }
+    return items;
+}
+/** Items in the managed block of an rc file's text. Empty when there is no block. */
+export function readItems(content, shell) {
+    const { lines } = parse(content);
+    const located = locate(lines);
+    return located ? parseItems(lines.slice(located.start + 1, located.end), shell) : [];
+}
+/** The text with the managed block removed (unchanged if absent or damaged). */
+export function stripManagedBlock(content) {
+    const { lines } = parse(content);
+    try {
+        const located = locate(lines);
+        if (!located)
+            return content;
+        return [...lines.slice(0, located.start), ...lines.slice(located.end + 1)].join("\n");
+    }
+    catch {
+        return content;
+    }
+}
+/** Add incoming items the block lacks. Items with the same name and text are unchanged. */
+export function mergeItems(existing, incoming) {
+    const items = [...existing];
+    const changes = [];
+    for (const item of incoming) {
+        const name = item.name;
+        const found = items.some((current) => current.name === name && current.lines.join("\n") === item.lines.join("\n"));
+        if (!found)
+            items.push(item);
+        changes.push({ name, status: found ? "unchanged" : "added" });
+    }
+    return { items, changes };
+}
+/** Insert or replace the managed block in the rc text, leaving everything else untouched. */
+export function writeItems(content, items) {
+    const { lines, eol } = parse(content);
+    const block = [START, NOTE, ...items.flatMap((item) => item.lines), END];
+    const located = locate(lines);
+    let next;
+    if (located) {
+        next = [...lines.slice(0, located.start), ...block, ...lines.slice(located.end + 1)];
+    }
+    else {
+        const spacer = lines.length > 0 && lines[lines.length - 1].trim() !== "" ? [""] : [];
+        next = [...lines, ...spacer, ...block];
+    }
+    return next.join(eol) + eol;
+}

package/dist/apply/diff.js

@@ -0,0 +1,41 @@
+const CONTEXT = 3;
+function split(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+/**
+ * Unified diff of two texts that differ in one contiguous region, which is
+ * all `apply` produces (the managed block). Empty string when equal.
+ */
+export function unifiedDiff(path, before, after) {
+    const a = split(before);
+    const b = split(after);
+    let prefix = 0;
+    while (prefix < a.length && prefix < b.length && a[prefix] === b[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < a.length - prefix && suffix < b.length - prefix && a[a.length - 1 - suffix] === b[b.length - 1 - suffix]) {
+        suffix++;
+    }
+    const removed = a.slice(prefix, a.length - suffix);
+    const added = b.slice(prefix, b.length - suffix);
+    if (removed.length === 0 && added.length === 0)
+        return before === after ? "" : `--- ${path}\n+++ ${path}\n(line endings or final newline changed)`;
+    const from = Math.max(0, prefix - CONTEXT);
+    const before3 = a.slice(from, prefix);
+    const after3 = a.slice(a.length - suffix, Math.min(a.length, a.length - suffix + CONTEXT));
+    const oldCount = before3.length + removed.length + after3.length;
+    const newCount = before3.length + added.length + after3.length;
+    const header = `@@ -${oldCount === 0 ? from : from + 1},${oldCount} +${newCount === 0 ? from : from + 1},${newCount} @@`;
+    return [
+        `--- ${before === "" ? "/dev/null" : path}`,
+        `+++ ${path}`,
+        header,
+        ...before3.map((line) => ` ${line}`),
+        ...removed.map((line) => `-${line}`),
+        ...added.map((line) => `+${line}`),
+        ...after3.map((line) => ` ${line}`),
+    ].join("\n");
+}

package/dist/apply/select.js

@@ -0,0 +1,23 @@
+import { UsageError } from "../errors.js";
+/**
+ * Pick suggestions by `--select`: a comma-separated list of ranks (from the
+ * `suggest` table) and/or proposed names. No selection means all of them.
+ */
+export function selectSuggestions(suggestions, spec) {
+    if (spec === undefined || spec.trim() === "") {
+        return suggestions.map((suggestion) => ({ suggestion, name: suggestion.names[0] }));
+    }
+    return spec.split(",").map((raw) => pick(suggestions, raw.trim()));
+}
+function pick(suggestions, token) {
+    if (/^\d+$/.test(token)) {
+        const suggestion = suggestions.find((s) => s.rank === Number(token));
+        if (!suggestion)
+            throw new UsageError(`--select: no suggestion with rank ${token}`);
+        return { suggestion, name: suggestion.names[0] };
+    }
+    const suggestion = suggestions.find((s) => s.names.includes(token));
+    if (!suggestion)
+        throw new UsageError(`--select: "${token}" is not a rank or proposed name`);
+    return { suggestion, name: token };
+}