@ok-ggwp/git-gloss 0.5.0 → 0.7.0

package/dist/commands/sync.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
-import { git, gitTry, GitError, NOTES_REF } from '../git.js';
+import { git, gitTry, GitError, gitCleanup, NETWORK_TIMEOUT, NOTES_REF, rethrowTimeout } from '../git.js';
 import { carryNew } from '../origins.js';
 import { REVIEWS_REF } from '../reviews.js';
 import { carry } from './carry.js';
@@ -22,7 +22,8 @@ function createdAt(blob) {
         const value = JSON.parse(git(['cat-file', 'blob', blob]))?.created_at;
         return typeof value === 'string' ? value : null;
     }
-    catch {
+    catch (err) {
+        rethrowTimeout(err);
         return null;
     }
 }
@@ -50,12 +51,34 @@ function shareable(remote, pushing) {
 // code (or an update-ref onto our own notes ref) touches it.
 function checkTracking(remote, ref, tracking) {
     if (gitTry(['rev-parse', '-q', '--verify', `${tracking}^{commit}`]) === null) {
-        gitTry(['update-ref', '-d', tracking]);
+        gitCleanup(['update-ref', '-d', tracking]);
         throw new GitError(`${remote}'s ${ref} is not a notes commit; ignoring it (nothing was changed here)`);
     }
 }
+// `init`'s refspec is a glob (refs/notes/gloss*), so a remote that once published
+// refs/notes/gloss/x leaves refs/notes/remotes/<remote>/gloss/x behind, and git
+// then cannot create refs/notes/remotes/<remote>/gloss once the remote has that
+// ref (a ref cannot be both a file and a directory): every fetch fails until
+// `git remote prune`. We are about to fetch the ref into `tracking`, so
+// whatever sits below it is stale and cannot be valid together with it. Only
+// that namespace is touched, in one batched update-ref.
+function clearBlockingTracking(tracking) {
+    const stale = (gitTry(['for-each-ref', '--format=%(refname)', `${tracking}/`]) ?? '').split('\n').filter((r) => r.startsWith(`${tracking}/`));
+    if (stale.length)
+        git(['update-ref', '--stdin'], stale.map((r) => `delete ${r}\n`).join(''));
+}
 function fetchTracking(remote, ref, tracking) {
-    git(['fetch', '-q', remote, `+${ref}:${tracking}`]);
+    try {
+        clearBlockingTracking(tracking);
+        git(['fetch', '-q', remote, `+${ref}:${tracking}`], undefined, {}, NETWORK_TIMEOUT);
+    }
+    catch (err) {
+        rethrowTimeout(err);
+        if (err instanceof GitError && /cannot lock ref|Unable to create .*\.lock|some local refs could not be updated/.test(err.message)) {
+            throw new GitError(`${err.message}\n  a stale remote-tracking ref may be in the way; try: git remote prune ${remote}`);
+        }
+        throw err;
+    }
     checkTracking(remote, ref, tracking);
 }
 const PUSH_REF = 'refs/notes/gloss-sync-tmp';
@@ -63,7 +86,7 @@ const PUSH_REF = 'refs/notes/gloss-sync-tmp';
 // someone else's push and the round should be retried.
 function round(remote, pushing, carried) {
     const tracking = `refs/notes/remotes/${remote}/gloss`;
-    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, NOTES_REF]) !== null;
+    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, NOTES_REF], undefined, NETWORK_TIMEOUT) !== null;
     if (remoteHas)
         fetchTracking(remote, NOTES_REF, tracking);
     const local = noteList(NOTES_REF);
@@ -142,13 +165,13 @@ function round(remote, pushing, carried) {
         if (remoteHas)
             git(['update-ref', PUSH_REF, tracking]);
         else
-            gitTry(['update-ref', '-d', PUSH_REF]);
+            gitCleanup(['update-ref', '-d', PUSH_REF]);
         for (const [object, blob] of toPush)
             git(['notes', '--ref', PUSH_REF, 'add', '-f', '-C', blob, object]);
         try {
             // --no-verify: don't run the pre-push hook for the notes push itself,
             // which would call sync again.
-            git(['push', '-q', '--no-verify', remote, `${PUSH_REF}:${NOTES_REF}`]);
+            git(['push', '-q', '--no-verify', remote, `${PUSH_REF}:${NOTES_REF}`], undefined, {}, NETWORK_TIMEOUT);
         }
         catch (err) {
             if (/\(fetch first\)|non-fast-forward/.test(err.message))
@@ -159,7 +182,7 @@ function round(remote, pushing, carried) {
         git(['notes', '--ref', NOTES_REF, 'merge', '-q', '-s', 'ours', PUSH_REF]);
     }
     finally {
-        gitTry(['update-ref', '-d', PUSH_REF]);
+        gitCleanup(['update-ref', '-d', PUSH_REF]);
     }
     return { fetched, pushed: toPush.length, withheld, conflicts };
 }
@@ -169,7 +192,7 @@ const REVIEWS_PUSH_REF = 'refs/notes/gloss-reviews-sync-tmp';
 // commits the remote may see are sent. Returns null if the push lost a race.
 function syncReviews(remote, pushing) {
     const tracking = `refs/notes/remotes/${remote}/gloss-reviews`;
-    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, REVIEWS_REF]) !== null;
+    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, REVIEWS_REF], undefined, NETWORK_TIMEOUT) !== null;
     if (remoteHas)
         fetchTracking(remote, REVIEWS_REF, tracking);
     const before = noteList(REVIEWS_REF);
@@ -190,11 +213,11 @@ function syncReviews(remote, pushing) {
         if (remoteHas)
             git(['update-ref', REVIEWS_PUSH_REF, tracking]);
         else
-            gitTry(['update-ref', '-d', REVIEWS_PUSH_REF]);
+            gitCleanup(['update-ref', '-d', REVIEWS_PUSH_REF]);
         for (const [object, blob] of toPush)
             git(['notes', '--ref', REVIEWS_PUSH_REF, 'add', '-f', '-C', blob, object]);
         try {
-            git(['push', '-q', '--no-verify', remote, `${REVIEWS_PUSH_REF}:${REVIEWS_REF}`]);
+            git(['push', '-q', '--no-verify', remote, `${REVIEWS_PUSH_REF}:${REVIEWS_REF}`], undefined, {}, NETWORK_TIMEOUT);
         }
         catch (err) {
             if (/\(fetch first\)|non-fast-forward/.test(err.message))
@@ -204,7 +227,7 @@ function syncReviews(remote, pushing) {
         git(['notes', '--ref', REVIEWS_REF, 'merge', '-q', '-s', 'cat_sort_uniq', REVIEWS_PUSH_REF]);
     }
     finally {
-        gitTry(['update-ref', '-d', REVIEWS_PUSH_REF]);
+        gitCleanup(['update-ref', '-d', REVIEWS_PUSH_REF]);
     }
     return { fetched, pushed: toPush.length };
 }

package/dist/commands/versions.js

@@ -1,6 +1,9 @@
 import { parseArgs } from 'node:util';
-import { commitDiff, git, gitTry, GlossError, NOTES_REF, resolveCommit, WIP_NOTES_REF, WIP_REF, writeNote } from '../git.js';
+import { commitDiff, git, GitError, gitTry, GlossError, noteSizeProblem, NOTES_REF, parseNote, resolveCommit, WIP_NOTES_REF, WIP_REF, rethrowTimeout, writeNote } from '../git.js';
+import { plain } from '../plain.js';
 import { location, parseDiff } from '../diff.js';
+import { loadGlossOf } from '../loader.js';
+import { carriedErrors } from '../validate.js';
 import { mergeGlosses } from '../merge.js';
 import { noteFormat } from '../schema.js';
 import { refLabel } from '../selection.js';
@@ -51,18 +54,29 @@ function history(ref, only) {
     flush();
     return out;
 }
+// How many group ids the listing names for one version.
+const MAX_LISTED = 20;
+// Everything a version of the history prints comes from a note that may have been
+// pushed by anyone: it is size-checked before it is read, cleaned, and bounded.
 function summary(blob) {
+    const size = Number(gitTry(['cat-file', '-s', blob]));
+    const big = noteSizeProblem(size);
+    if (big)
+        return `(not read: ${big})`;
     try {
         const note = JSON.parse(git(['cat-file', 'blob', blob]));
         const a = note.annotation;
-        const from = note.sources ? `carried from ${note.sources.map((s) => s.slice(0, 7)).join(', ')}; ` : '';
-        return `${from}${a.groups.length} group${a.groups.length === 1 ? '' : 's'}: ${a.groups.map((g) => g.id).join(', ')}\n       task: ${JSON.stringify(a.task)}`;
+        const from = Array.isArray(note.sources) ? `carried from ${note.sources.slice(0, 5).map((s) => plain(String(s)).slice(0, 7)).join(', ')}; ` : '';
+        const ids = a.groups.slice(0, MAX_LISTED).map((g) => plain(String(g.id)).slice(0, 40));
+        const n = a.groups.length;
+        return `${from}${n} group${n === 1 ? '' : 's'}: ${ids.join(', ')}${n > MAX_LISTED ? `, and ${n - MAX_LISTED} more` : ''}\n       task: ${JSON.stringify(plain(String(a.task)).slice(0, 200))}`;
     }
-    catch {
+    catch (err) {
+        rethrowTimeout(err);
         return '(not a readable gloss: joined notes from a squash, or not JSON)';
     }
 }
-const when = (iso) => iso.slice(0, 16).replace('T', ' ');
+const when = (iso) => plain(iso).slice(0, 16).replace('T', ' ');
 export function run(argv) {
     const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { show: { type: 'string' }, restore: { type: 'string' } } });
     const wip = positionals[0] === 'wip';
@@ -84,12 +98,37 @@ export function run(argv) {
         return { n, v: v };
     };
     if (values.show !== undefined) {
-        process.stdout.write(git(['cat-file', 'blob', pick(values.show, '--show').v.blob]));
+        // Cleaned like everything else printed (control characters, escape sequences, bidi and
+        // zero-width characters become spaces), so not byte-identical to the stored blob.
+        process.stdout.write(plain(git(['cat-file', 'blob', pick(values.show, '--show').v.blob]), true));
         return 0;
     }
     if (values.restore !== undefined) {
         const { n, v } = pick(values.restore, '--restore');
+        // Only a gloss that readers accept is brought back (a restore must not plant what they refuse).
+        const text = git(['cat-file', 'blob', v.blob]);
+        let note;
+        try {
+            note = parseNote(text, `version ${n}`);
+        }
+        catch (err) {
+            if (!(err instanceof GlossError) || err instanceof GitError)
+                throw err;
+            throw new GlossError(`${err.message.replace(/; (replace it|re-gloss it|upgrade).*$/, '')}, so it is not restored (read it with --show ${n})`);
+        }
+        // What readers refuse for the commit it would go on (too many claimed lines).
+        const checkOn = (target) => {
+            try {
+                loadGlossOf(target, note);
+            }
+            catch (err) {
+                if (!(err instanceof GlossError) || err instanceof GitError)
+                    throw err;
+                throw new GlossError(`version ${n} would be refused on ${target.slice(0, 7)}: ${err.message.replace(/^the gloss on \S+ is refused: /, '')} (not restored; read it with --show ${n})`);
+            }
+        };
         if (!wip) {
+            checkOn(sha);
             git(['notes', '--ref', ref, 'add', '-f', '-C', v.blob, sha]);
             console.log(`restored version ${n} as the gloss of ${label}`);
             return 0;
@@ -100,8 +139,8 @@ export function run(argv) {
         const onto = gitTry(['rev-parse', '-q', '--verify', WIP_REF])?.trim();
         if (!onto)
             throw new GlossError('there is no snapshot of uncommitted work to restore onto; run git gloss hunks wip first');
-        const note = JSON.parse(git(['cat-file', 'blob', v.blob]));
         if (v.object === onto || gitTry(['cat-file', '-e', `${v.object}^{commit}`]) === null) {
+            checkOn(onto);
             git(['notes', '--ref', ref, 'add', '-f', '-C', v.blob, onto]);
             console.log(`restored version ${n} onto the wip snapshot ${onto.slice(0, 7)}` +
                 (v.object === onto ? '' : `; its snapshot ${v.object.slice(0, 7)} is gone, so hunk references may not match: check with git gloss show wip`));
@@ -109,6 +148,11 @@ export function run(argv) {
         }
         const current = parseDiff(commitDiff(onto));
         const merged = mergeGlosses([{ sha: v.object, note, hunks: parseDiff(commitDiff(v.object)) }], current);
+        if (merged.annotation) {
+            const errors = carriedErrors(merged.annotation, current);
+            if (errors.length)
+                throw new GlossError(`version ${n} doesn't fit the uncommitted work: ${errors.join('; ')} (not restored)`);
+        }
         if (!merged.annotation)
             throw new GlossError(`none of version ${n}'s glossed changes are in the uncommitted work any more; read it with --show ${n}`);
         writeNote(onto, {
@@ -122,7 +166,7 @@ export function run(argv) {
     }
     console.log(`glosses of ${label}, newest first:`);
     versions.forEach((v, i) => {
-        const head = `${String(i + 1).padStart(3)}  ${when(v.at)}  ${v.how}${wip ? `  (snapshot ${v.object.slice(0, 7)})` : ''}`;
+        const head = `${String(i + 1).padStart(3)}  ${when(v.at)}  ${plain(v.how)}${wip ? `  (snapshot ${v.object.slice(0, 7)})` : ''}`;
         console.log(`${head}${i === 0 && v.blob && !wip ? '  [current]' : ''}`);
         console.log(`       ${v.blob ? summary(v.blob) : 'removed'}`);
     });

package/dist/commands/why.js

@@ -1,7 +1,7 @@
 import { plain } from '../plain.js';
 import { parseArgs } from 'node:util';
 import { blameRange, commitSubject, lineHistory } from '../git.js';
-import { loadGloss } from '../loader.js';
+import { loadGlossInRange, refusedWarning } from '../loader.js';
 import { servesOf } from '../schema.js';
 import { field, groupHeader, style } from '../render.js';
 import { bodyLines, formatRanges } from '../selection.js';
@@ -10,8 +10,13 @@ export const usage = 'why <file>:<line>[-<end>] [--history] [--rev <commit>] [--
 // refer to it; each load diffs the commit.
 const glossCache = new Map();
 function glossFor(commit) {
-    if (!glossCache.has(commit))
-        glossCache.set(commit, loadGloss(commit));
+    if (!glossCache.has(commit)) {
+        // A refused gloss (hostile or broken) is skipped with a warning, once, not a failed command.
+        const { gloss, refused } = loadGlossInRange(commit);
+        if (refused)
+            console.error(refusedWarning(commit, refused));
+        glossCache.set(commit, gloss);
+    }
     return glossCache.get(commit);
 }
 // Groups in a gloss that own `line` of `file` on the new side of the commit's

package/dist/config.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { git, GitError, GlossError, gitTry } from './git.js';
+import { git, GitError, GlossError, gitTry, rethrowTimeout } from './git.js';
 import { globToRegExp } from './glob.js';
 // Settings for the computed signals, in three layers (later wins for scalars,
 // repo config extends the lists of the one before):
@@ -137,10 +137,12 @@ function gitInt(key) {
 }
 // Git failing (a broken repo, an unreadable object, no permission) is not the
 // same as "no base" or "no file": the repo's own, perhaps stricter, config
-// would silently not apply. It is not fatal either (the built-in defaults
-// still give a floor, and refusing to rate anything would make every command
-// fail in a damaged repo), so it is warned about on stderr, once per message,
-// and the defaults are used.
+// would silently not apply, and a floor computed from the defaults alone could
+// be lower than the real one. So the ratings are unverifiable: loadConfig
+// throws a ConfigError, which `add` and `signals` report as an error, and
+// `show`, `lint`, `html` and `hunks` meet through withSignals (the signals are
+// unavailable, `lint` says "incomplete"). A broken base candidate is only
+// warned about (once per message) while a later one still works.
 const warned = new Set();
 function warnOnce(msg) {
     if (warned.has(msg))
@@ -171,8 +173,14 @@ function gitAnswer(args) {
 // is always a `sensitive` path.
 function trustedRef() {
     // No commits yet: no base, and nothing failed.
-    if (gitAnswer(['rev-parse', '--verify', '-q', 'HEAD']) === null)
-        return noBase();
+    try {
+        if (gitAnswer(['rev-parse', '--verify', '-q', 'HEAD']) === null)
+            return noBase();
+    }
+    catch (err) {
+        rethrowTimeout(err);
+        throw new ConfigError(`git failed finding HEAD (${err.message}), so ${CONFIG_FILE} cannot be read and the ratings cannot be verified`);
+    }
     let failed = false;
     // Full ref names, so a tag called "main" cannot stand in for the branch.
     for (const b of ['refs/remotes/origin/main', 'refs/heads/main', 'refs/remotes/origin/master', 'refs/heads/master']) {
@@ -184,20 +192,23 @@ function trustedRef() {
                 return mb;
         }
         catch (err) {
+            rethrowTimeout(err);
             // A broken candidate does not hide the ones after it.
             failed = true;
             warnOnce(`git failed finding the base branch with ${b} (${err.message}); trying the next candidate`);
         }
     }
     // Some candidate failed: git's warning above is the reason, not an absent branch.
-    return failed ? (console.error(`warning: no working base branch, so ${CONFIG_FILE} is not read; using the built-in defaults`), null) : noBase();
+    if (failed)
+        throw new ConfigError(`git failed on every base branch candidate, so ${CONFIG_FILE} cannot be read and the ratings cannot be verified (the repo's own patterns would not apply); fix the repository, or see the warnings above`);
+    return noBase();
 }
 function noBase() {
     console.error('warning: no base branch (origin/main, main, origin/master, master) found, so .gloss/config.json is not read; using the built-in defaults');
     return null;
 }
 // The config file at `ref`: null when the file is not there (the usual case),
-// a warning and null when git could not tell or could not read it. Presence
+// a ConfigError when git could not tell or could not read it. Presence
 // is asked of ls-tree (empty output: absent), not read off an error message.
 function configAt(ref) {
     try {
@@ -206,8 +217,8 @@ function configAt(ref) {
         return git(['show', `${ref}:${CONFIG_FILE}`]);
     }
     catch (err) {
-        warnOnce(`${CONFIG_FILE} could not be read from the base branch (${err.message}); using the built-in defaults, so the repo's own patterns do not apply`);
-        return null;
+        rethrowTimeout(err);
+        throw new ConfigError(`${CONFIG_FILE} could not be read from the base branch (${err.message}); the repo's own patterns cannot be applied, so the ratings cannot be verified`);
     }
 }
 function readRepoConfig() {