@ok-ggwp/git-gloss 0.3.0 → 0.4.0

package/dist/floor.js

@@ -0,0 +1,148 @@
+import { ConfigError, loadConfig } from './config.js';
+import { attentionForImpact, attentionRank, impactRank, maxAttention, maxImpact, raise } from './attention.js';
+import { servesOf } from './schema.js';
+import { analyze, CONFIG_EDIT_NOTE, partFloor } from './signals.js';
+import { changedCount, selections } from './selection.js';
+// The groups of a loaded gloss with their current hunks (a hunk that is gone is skipped).
+export function groupInputs(gloss) {
+    return gloss.groups.map((g) => ({
+        group: g.group,
+        parts: g.hunks.flatMap((h) => (h.current ? [{ hunk: h.current, lines: h.lines }] : [])),
+    }));
+}
+// The groups of an annotation over hunks of the diff (as `add` has them).
+export function groupInputsFor(a, hunks) {
+    const byId = new Map(hunks.map((h) => [h.id, h]));
+    return a.groups.map((group) => ({
+        group,
+        parts: [...selections(group.hunks, (id) => { const h = byId.get(id); return h && changedCount(h); })]
+            .flatMap(([id, lines]) => { const hunk = byId.get(id); return hunk ? [{ hunk, lines }] : []; }),
+    }));
+}
+// Group floors, and the derivation of the attention for when the author declares none:
+//
+//   start from the highest group impact (declared, else the group's floor):
+//     local skim, module look, shared and contract careful, sensitive must-read;
+//   raise it ONE step (capped at must-read), however many of these apply:
+//     - a behaviour-changing group no test-only group serves (see GroupFloor);
+//     - a speculative or defensive group that is not made only of test hunks;
+//     - more than attention.largeChangeFiles files changed;
+//   never below the change's floor (which is the highest hunk floor, and at
+//   least careful for a large change).
+export function analyzeGroups(hunks, groups, cfg) {
+    const signals = analyze(hunks, cfg);
+    const sigOf = new Map(signals.hunks.map((s) => [s.id, s]));
+    const floors = new Map();
+    for (const { group, parts } of groups) {
+        let floor = 'local';
+        const found = [];
+        for (const { hunk, lines } of parts) {
+            const s = sigOf.get(hunk.id);
+            if (!s)
+                continue;
+            const p = partFloor(s, lines);
+            floor = maxImpact(floor, p.floor);
+            found.push({ floor: p.floor, why: p.why.map((w) => `${hunk.file}: ${w}`) });
+        }
+        const sigs = parts.map((p) => sigOf.get(p.hunk.id)).filter((s) => !!s);
+        floors.set(group.id, {
+            floor,
+            why: [...new Set(found.filter((f) => f.floor === floor).flatMap((f) => f.why))].slice(0, 3),
+            behaviour: group.necessity !== 'mechanical' && sigs.some((s) => !s.inert),
+            testsOnly: sigs.length > 0 && sigs.every((s) => s.test),
+            tested: false,
+        });
+    }
+    // A test-only group serves what it names, and what those groups serve in turn.
+    const byId = new Map(groups.map((g) => [g.group.id, g.group]));
+    for (const { group } of groups) {
+        if (!floors.get(group.id).testsOnly)
+            continue;
+        const seen = new Set();
+        const queue = servesOf(group).filter((t) => t !== 'task');
+        while (queue.length) {
+            const id = queue.shift();
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const f = floors.get(id);
+            if (f)
+                f.tested = true;
+            const g = byId.get(id);
+            if (g)
+                queue.push(...servesOf(g).filter((t) => t !== 'task'));
+        }
+    }
+    // Derivation.
+    let top = { impact: undefined, id: '', declared: false };
+    for (const { group } of groups) {
+        const impact = group.impact ?? floors.get(group.id).floor;
+        if (impactRank(impact) > impactRank(top.impact))
+            top = { impact, id: group.id, declared: !!group.impact };
+    }
+    const reasons = [];
+    let level = top.impact ? attentionForImpact(top.impact) : signals.floor.attention;
+    if (top.impact)
+        reasons.push(`highest group impact: ${top.impact} (${top.id}, ${top.declared ? 'declared' : 'from the diff'})`);
+    const raises = [];
+    const untested = groups.filter((g) => floors.get(g.group.id).behaviour && !floors.get(g.group.id).tested).map((g) => g.group.id);
+    if (untested.length)
+        raises.push(`behaviour change without a test serving it: ${untested.join(', ')}`);
+    const hedged = groups.filter((g) => (g.group.necessity === 'speculative' || g.group.necessity === 'defensive') && !floors.get(g.group.id).testsOnly);
+    if (hedged.length)
+        raises.push(`speculative or defensive code: ${hedged.map((g) => g.group.id).join(', ')}`);
+    if (signals.stats.files > cfg.attention.largeChangeFiles)
+        raises.push(`${signals.stats.files} files changed (more than ${cfg.attention.largeChangeFiles})`);
+    if (raises.length) {
+        level = raise(level);
+        reasons.push(...raises.map((r) => `raised one step: ${r}`));
+    }
+    if (attentionRank(signals.floor.attention) > attentionRank(level)) {
+        level = maxAttention(level, signals.floor.attention);
+        reasons.push(`floor ${signals.floor.attention}: ${signals.floor.reasons[0] ?? signals.floor.impact}`);
+    }
+    return { signals, groups: floors, floor: signals.floor.attention, derived: { level, reasons } };
+}
+export const analyzeGloss = (gloss, cfg) => analyzeGroups(gloss.hunks, groupInputs(gloss), cfg);
+export function ratingProblems(a, an) {
+    const warnings = [];
+    if (an.signals.floor.reasons.includes(CONFIG_EDIT_NOTE))
+        warnings.push(CONFIG_EDIT_NOTE);
+    for (const g of a.groups) {
+        const f = an.groups.get(g.id);
+        // A floor of plain "module" is the baseline for source files, not a signal
+        // to warn about: a private helper may honestly be `local`.
+        if (!g.impact || !f || impactRank(f.floor) <= impactRank('module') || impactRank(g.impact) >= impactRank(f.floor))
+            continue;
+        warnings.push(`group "${g.id}" is rated impact "${g.impact}" but its floor is "${f.floor}" (${f.why.join('; ') || 'computed from the diff'}); raise it, or say why in impact_reason`);
+    }
+    let underrated = null;
+    const att = a.attention;
+    if (att && attentionRank(att.level) < attentionRank(an.floor) && !att.override_reason) {
+        const why = an.signals.floor.reasons.length ? an.signals.floor.reasons.join('; ') : `${an.signals.floor.impact}: ordinary source changes`;
+        underrated = `attention.level "${att.level}" is below the computed floor "${an.floor}" (${why}); raise it, or explain with attention.override_reason`;
+    }
+    return { warnings, underrated };
+}
+let warned = false;
+// Run something that needs the signals' config; null when the config is
+// malformed (say why once on stderr), so callers fall back to what is declared.
+export function withSignals(fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        if (!(err instanceof ConfigError))
+            throw err;
+        if (!warned)
+            console.error(`warning: signals unavailable: ${err.message}`);
+        warned = true;
+        return null;
+    }
+}
+// The analysis of a loaded gloss, or null when the signals cannot be computed.
+export const tryAnalyze = (gloss) => withSignals(() => analyzeGloss(gloss, loadConfig()));
+// Whether a gloss's groups get an impact column (show) or badges (html): some
+// group declares an impact, or the diff puts a group's floor above the module
+// baseline. Then undeclared groups show their floor as a derived impact.
+export const showsImpact = (groups, an) => groups.some((g) => g.impact || impactRank(an?.groups.get(g.id)?.floor) > impactRank('module'));

package/dist/git.js

@@ -142,6 +142,16 @@ export function wipStaleness(sha) {
         return 'the working tree has changed since this snapshot was taken';
     return null;
 }
+// The diff of uncommitted work against HEAD, as a snapshot would have it,
+// without taking a snapshot: no ref is written (only objects). Hunk ids match
+// those of `hunks wip` for the same working tree.
+export function workingDiff() {
+    const { tree, excluded } = workingTree();
+    const head = headSha();
+    if (head && git(['rev-parse', `${head}^{tree}`]).trim() === tree)
+        throw new GlossError('there are no uncommitted changes');
+    return { diff: diffBetween(head ?? EMPTY_TREE, tree), excluded };
+}
 export function resolveCommit(rev) {
     // "wip": the latest snapshot of uncommitted work (made by `hunks wip`). A
     // branch or tag named wip still works when there is no snapshot, and can be
@@ -236,7 +246,7 @@ export function readNote(sha) {
         throw new GlossError(`${at} was written by a newer git-gloss (format ${data.gloss}); upgrade to read it`);
     }
     const annotation = Annotation.safeParse(data?.annotation);
-    if (![1, 2, 3].includes(data?.gloss) || !Array.isArray(data.hunks) || !annotation.success) {
+    if (![1, 2, 3, 4].includes(data?.gloss) || !Array.isArray(data.hunks) || !annotation.success) {
         throw new GlossError(`${at} is malformed; replace it with \`git gloss add --force\``);
     }
     return { ...data, annotation: annotation.data };

package/dist/glob.js

@@ -0,0 +1,76 @@
+// A small glob matcher for repo paths (always "/"-separated, relative to the
+// repo root). Supports `**` (any number of directories, including none when
+// written as `**/` or `/**`), `*` (anything but "/"), `?` (one character but
+// "/"), `{a,b}` alternatives (nestable) and `\` to escape. A pattern without a
+// "/" matches the file name at any depth, as in .gitignore ("Jenkinsfile",
+// "*.lock"). Node's path.matchesGlob is not used: it is missing before Node 22.
+const SPECIAL = /[.+^$()|[\]\\]/;
+export class GlobError extends Error {
+}
+function translate(glob) {
+    let out = '';
+    let depth = 0;
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '\\') {
+            if (i + 1 >= glob.length)
+                throw new GlobError('trailing backslash');
+            out += glob[++i].replace(/[^a-zA-Z0-9]/, '\\$&');
+            continue;
+        }
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                let j = i + 1;
+                while (glob[j + 1] === '*')
+                    j++;
+                const atStart = i === 0 || glob[i - 1] === '/';
+                if (glob[j + 1] === '/' && atStart) {
+                    out += '(?:.*/)?';
+                    i = j + 1;
+                } // "**/": any directories, or none
+                else {
+                    out += '.*';
+                    i = j;
+                }
+            }
+            else
+                out += '[^/]*';
+            continue;
+        }
+        if (c === '?') {
+            out += '[^/]';
+            continue;
+        }
+        if (c === '{') {
+            depth++;
+            out += '(?:';
+            continue;
+        }
+        if (c === ',' && depth > 0) {
+            out += '|';
+            continue;
+        }
+        if (c === '}' && depth > 0) {
+            depth--;
+            out += ')';
+            continue;
+        }
+        out += SPECIAL.test(c) ? '\\' + c : c;
+    }
+    if (depth > 0)
+        throw new GlobError('unclosed "{"');
+    return out;
+}
+const cache = new Map();
+// The regular expression for a glob; throws GlobError if it is malformed.
+export function globToRegExp(glob) {
+    let re = cache.get(glob);
+    if (!re) {
+        const body = translate(glob);
+        // Without a "/", match the last path component at any depth.
+        re = new RegExp('^' + (glob.includes('/') ? '' : '(?:.*/)?') + body + '$');
+        cache.set(glob, re);
+    }
+    return re;
+}
+export const matchGlob = (glob, path) => globToRegExp(glob).test(path);