@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.10

package/dist/core/release-notes/parser.js

@@ -1,241 +0,0 @@
-/**
- * Keep-a-Changelog parser — .
- *
- * Parses a `CHANGELOG.md` written в the Keep-a-Changelog v1.1 layout
- * (https://keepachangelog.com) into an ordered list of version
- * sections. The parser is intentionally minimal — it understands the
- * `## [<version>] - <date>` header marker and the section body up к
- * the next header, and ignores every other Markdown construct (links,
- * footnotes, sub-sub-headers). That is enough к drive the
- * `pugi release-notes` diff between last-seen and current.
- *
- * # Module contract
- *
- *  - Pure function. Takes the raw CHANGELOG text + returns parsed
- *    sections. Zero IO; the file read happens at the call site so the
- *    spec can pin fixtures without touching disk.
- *
- *  - Header grammar: `## [<version>] - <YYYY-MM-DD>`. The leading
- *    `## ` is required (h2). The version is everything between the
- *    square brackets — semver-shaped strings are not validated
- *    beyond non-emptiness so pre-release tags like `0.1.0-beta.21`
- *    parse correctly. The date is captured verbatim; the comparator
- *    does not parse it — version ordering is enough.
- *
- *  - Section body: every line from the header (exclusive) up к the
- *    next `## [...] - ...` header (exclusive). Lines are joined
- *    verbatim with `\n`; leading + trailing blank lines are trimmed
- *    so the renderer can paste sections back-to-back without double
- *    blank lines piling up.
- *
- *  - Pre-header content (the leading `# Changelog` + introduction
- *    blurb) is discarded. The parser only surfaces version sections;
- *    callers that want к render the introduction read the source
- *    file directly.
- *
- *  - Sections appear в the order they are written in the file. The
- *    Keep-a-Changelog convention is newest-first; the parser does
- *    NOT re-sort. The slicing helpers (`sliceVersionsBetween`) trust
- *    the input order so a malformed CHANGELOG with shuffled
- *    versions produces a deterministic — if surprising — diff
- *    instead of silently swallowing entries.
- *
- *  - Semver comparison (`compareSemver`) handles the canonical
- *    `MAJOR.MINOR.PATCH[-PRERELEASE]` shape. The pre-release tail
- *    is compared lexicographically by dot-separated identifier per
- *    semver §11. Unknown / malformed input compares lower than any
- *    valid semver so an accidental `unknown` last-seen marker
- *    never blocks the operator from seeing new notes.
- */
-const SECTION_HEADER_RE = /^##\s+\[([^\]]+)\](?:\s*-\s*(.+))?\s*$/u;
-/**
- * Parse the raw `CHANGELOG.md` text into ordered version sections.
- *
- * Returns sections in the same order they appear in the source. The
- * Keep-a-Changelog convention is newest-first; the parser does not
- * re-sort.
- */
-export function parseChangelog(raw) {
-    const lines = raw.split(/\r?\n/u);
-    const sections = [];
-    let current = null;
-    const flush = () => {
-        if (!current)
-            return;
-        sections.push({
-            version: current.version,
-            date: current.date,
-            body: trimBlankEdges(current.lines).join('\n'),
-        });
-        current = null;
-    };
-    for (const line of lines) {
-        const match = SECTION_HEADER_RE.exec(line);
-        if (match) {
-            flush();
-            const version = (match[1] ?? '').trim();
-            const date = (match[2] ?? '').trim();
-            if (version.length === 0) {
-                // Malformed `## []` header — skip entirely instead of
-                // emitting a zero-version row that would corrupt the diff.
-                continue;
-            }
-            current = { version, date, lines: [] };
-            continue;
-        }
-        if (current) {
-            current.lines.push(line);
-        }
-    }
-    flush();
-    return sections;
-}
-/**
- * Slice the section list к those strictly newer than `lastSeen` and
- * up к (and including) `current`. Both bounds are matched on the
- * verbatim version string — the comparator runs on every section к
- * decide membership.
- *
- * Semantics:
- *
- *  - If `lastSeen` is null OR empty OR matches no section, every
- *    section ≤ current is returned. This is the first-run path —
- *    the operator has never run the command before, so the entire
- *    bundled changelog is fair game.
- *
- *  - If `lastSeen` equals `current`, the empty array is returned.
- *    The caller renders the "no new release notes" copy.
- *
- *  - If `lastSeen` is newer than `current`, the empty array is
- *    returned. This is the dev-build path — operators running a
- *    local build of `0.1.0-beta.30` against a registry that
- *    publishes `0.1.0-beta.22` would otherwise see the stale
- *    bundled notes; the caller still surfaces the same no-op copy.
- *
- *  - Otherwise: sections strictly newer than `lastSeen` and ≤
- *    `current`, in the source order (newest-first by convention).
- *
- * The function is pure — no IO, no clock — so the spec can pin every
- * branch with hand-rolled fixtures.
- */
-export function sliceVersionsBetween(sections, lastSeen, current) {
-    if (sections.length === 0)
-        return [];
-    // Treat а blank / sentinel last-seen as "never seen".
-    const lastSeenValue = typeof lastSeen === 'string' && lastSeen.trim().length > 0 && lastSeen !== 'none'
-        ? lastSeen.trim()
-        : null;
-    // Dev-build path: operator's last-seen marker is strictly newer than
-    // the installed CLI version. This happens when running а local build
-    // older than the registry, or when the operator manually edited the
-    // marker. Either way, return the empty array — re-rendering the
-    // bundled notes would be misleading. The renderer surfaces the same
-    // "no new release notes" copy as the up-to-date branch.
-    if (lastSeenValue !== null && compareSemver(lastSeenValue, current) > 0) {
-        return [];
-    }
-    // Diff path: surface sections strictly newer than the marker and ≤
-    // current. The comparator drives every section — а marker that does
-    // not appear in the bundled changelog (operator on а stale build,
-    // hand-edited marker, version no longer published) still bisects
-    // correctly because every comparison runs against the marker value
-    // directly, not the matching-section guard.
-    const out = [];
-    for (const section of sections) {
-        // Anything newer than current is а future entry that should not
-        // surface until the operator actually upgrades — guards against а
-        // dev build of CHANGELOG.md leaking unreleased notes к а customer
-        // install.
-        if (compareSemver(section.version, current) > 0)
-            continue;
-        if (lastSeenValue !== null && compareSemver(section.version, lastSeenValue) <= 0) {
-            continue;
-        }
-        out.push(section);
-    }
-    return out;
-}
-/**
- * Semver comparator. Returns a negative number when `a < b`, zero
- * when equal, and a positive number when `a > b`. Pre-release tags
- * compare lexicographically by dot-separated identifier per semver §11.
- *
- * Unknown / malformed input compares lower than any valid semver so
- * an accidental sentinel like `unknown` or `none` never accidentally
- * blocks the diff from surfacing newer entries.
- */
-export function compareSemver(a, b) {
-    const left = parseSemver(a);
-    const right = parseSemver(b);
-    if (!left && !right)
-        return 0;
-    if (!left)
-        return -1;
-    if (!right)
-        return 1;
-    for (let i = 0; i < 3; i += 1) {
-        const cmp = (left.core[i] ?? 0) - (right.core[i] ?? 0);
-        if (cmp !== 0)
-            return cmp;
-    }
-    // A version without a pre-release tag is newer than the same core
-    // with a pre-release tag (per semver §11: 1.0.0 > 1.0.0-rc).
-    if (left.pre.length === 0 && right.pre.length === 0)
-        return 0;
-    if (left.pre.length === 0)
-        return 1;
-    if (right.pre.length === 0)
-        return -1;
-    const len = Math.max(left.pre.length, right.pre.length);
-    for (let i = 0; i < len; i += 1) {
-        const li = left.pre[i];
-        const ri = right.pre[i];
-        if (li === undefined)
-            return -1;
-        if (ri === undefined)
-            return 1;
-        const ln = Number.parseInt(li, 10);
-        const rn = Number.parseInt(ri, 10);
-        const liNumeric = Number.isFinite(ln) && String(ln) === li;
-        const riNumeric = Number.isFinite(rn) && String(rn) === ri;
-        if (liNumeric && riNumeric) {
-            if (ln !== rn)
-                return ln - rn;
-            continue;
-        }
-        if (liNumeric)
-            return -1; // numeric < alphanumeric per §11
-        if (riNumeric)
-            return 1;
-        if (li < ri)
-            return -1;
-        if (li > ri)
-            return 1;
-    }
-    return 0;
-}
-function parseSemver(raw) {
-    if (typeof raw !== 'string')
-        return null;
-    const trimmed = raw.trim();
-    if (trimmed.length === 0)
-        return null;
-    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/u.exec(trimmed);
-    if (!match)
-        return null;
-    const major = Number.parseInt(match[1] ?? '0', 10);
-    const minor = Number.parseInt(match[2] ?? '0', 10);
-    const patch = Number.parseInt(match[3] ?? '0', 10);
-    const pre = match[4] ? match[4].split('.') : [];
-    return { core: [major, minor, patch], pre };
-}
-function trimBlankEdges(lines) {
-    let start = 0;
-    let end = lines.length;
-    while (start < end && (lines[start] ?? '').trim().length === 0)
-        start += 1;
-    while (end > start && (lines[end - 1] ?? '').trim().length === 0)
-        end -= 1;
-    return lines.slice(start, end);
-}
-//# sourceMappingURL=parser.js.map

package/dist/core/release-notes/state.js

@@ -1,116 +0,0 @@
-/**
- * `~/.pugi/.last-seen-version` state I/O — .
- *
- * The `pugi release-notes` command renders the diff between the
- * version the operator last saw notes for and the currently
- * installed CLI version. This module owns the on-disk marker that
- * tracks the last-seen value.
- *
- * # Module contract
- *
- *  - File path: `<home>/.pugi/.last-seen-version`. The leading dot
- *    keeps it out of casual `ls` output; the file is plain ASCII
- *    (one line, the version string) so operators can edit it by
- *    hand when reproducing scenarios. Missing parent dir is
- *    created on write.
- *
- *  - Reads: missing file → null. Unreadable / blank file → null.
- *    The caller treats null as "operator has never run the command"
- *    and surfaces every bundled section. Read failures NEVER throw —
- *    the command surface is informational and must keep working on
- *    a read-only mount or a misconfigured permission bit.
- *
- *  - Writes: best-effort. EACCES / EROFS / ENOSPC log а warning к
- *    the caller-supplied logger and return the failure code so the
- *    command renderer can footer the output with "could not persist
- *    last-seen — re-run will show the same notes". The command
- *    itself stays exit 0 because the value of the render did not
- *    depend on the write succeeding.
- *
- *  - The helpers are pure I/O wrappers — no clock, no random, no
- *    env reads. Callers pass `home` explicitly so the spec can
- *    pin a tmp dir without monkey-patching `os.homedir`.
- */
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-/** Filename inside `<home>/.pugi/` that holds the last-seen marker. */
-export const LAST_SEEN_VERSION_FILE = '.last-seen-version';
-/**
- * Resolve the absolute path of the last-seen marker file inside the
- * passed home directory. Pure helper — no IO.
- */
-export function lastSeenVersionPath(home) {
-    return resolve(home, '.pugi', LAST_SEEN_VERSION_FILE);
-}
-/**
- * Read the last-seen marker. Returns null when the file is missing,
- * unreadable, or empty. Never throws.
- */
-export function readLastSeenVersion(home) {
-    const path = lastSeenVersionPath(home);
-    try {
-        if (!existsSync(path))
-            return null;
-        const raw = readFileSync(path, 'utf8').trim();
-        if (raw.length === 0)
-            return null;
-        return raw;
-    }
-    catch {
-        // Read-only mount, permission denied, race with another process
-        // unlinking the file — every read failure degrades к null so the
-        // command treats the operator as a first-time viewer instead of
-        // dropping out of the slash dispatcher with an unhandled error.
-        return null;
-    }
-}
-/**
- * Persist the last-seen marker. Creates `<home>/.pugi/` if it does
- * not exist. Returns a structured envelope describing success or the
- * failure reason so the renderer can footer а warning when the write
- * could not be made durable.
- */
-export function writeLastSeenVersion(home, version) {
-    const path = lastSeenVersionPath(home);
-    try {
-        const dir = resolve(home, '.pugi');
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
-        // Trailing newline so `cat ~/.pugi/.last-seen-version` reads
-        // nicely in shells that do not auto-append one for the prompt.
-        writeFileSync(path, `${version}\n`, { encoding: 'utf8', mode: 0o600 });
-        return { status: 'ok', path };
-    }
-    catch (error) {
-        return {
-            status: 'failed',
-            path,
-            reason: error instanceof Error ? error.message : String(error),
-        };
-    }
-}
-/**
- * Clear the last-seen marker — used by `pugi release-notes --reset`
- * so the operator can force the full bundled changelog к re-render.
- * Returns `absent` when the marker did not exist, `cleared` on
- * success, `failed` on permission errors.
- */
-export function clearLastSeenVersion(home) {
-    const path = lastSeenVersionPath(home);
-    try {
-        if (!existsSync(path)) {
-            return { status: 'absent', path };
-        }
-        unlinkSync(path);
-        return { status: 'cleared', path };
-    }
-    catch (error) {
-        return {
-            status: 'failed',
-            path,
-            reason: error instanceof Error ? error.message : String(error),
-        };
-    }
-}
-//# sourceMappingURL=state.js.map