@ok-ggwp/git-gloss 0.3.0 → 0.4.0

package/README.md

@@ -12,8 +12,11 @@ git gloss init [--hooks]              follow amends/rebases; fetch origin's glos
 git gloss sync [<remote>]             fetch, merge and push glosses (default: origin)
 git gloss hunks [<commit>|wip]        list hunks, numbering changed lines for h3:2-5 references;
                                       wip snapshots your uncommitted work instead
+git gloss signals [<commit>|<range>|wip] [--json]
+                                      what the diff itself says about attention: path classes, pattern
+                                      hits, dependency bumps and the computed floor
 git gloss adopt [<commit>]            move the gloss of uncommitted work onto the commit made from it
-git gloss add [<commit>] -f a.json    attach an annotation (validated against the diff)
+git gloss add [<commit>] -f a.json    attach an annotation (validated against the diff; --allow-underrate)
 git gloss carry <source>... [--to <c>] gloss a commit from the glosses of the commits its changes came from
                                       (a squash, cherry-pick or rebase): git gloss carry main..feature --to <squash>
       --find [--squash] [<commit>...] ...working out which commits those are
@@ -21,7 +24,8 @@ git gloss show [<commit>|<range>]     summary: one line per group, alternatives,
       -g <group>                      ...expand groups, with their code
       --full                          ...every group's details
       --diff                          ...every group's details and code
-      --only speculative,incidental   ...just the parts you might cut
+      --only speculative,incidental   ...just the parts you might cut (impact values work too: --only contract,sensitive; naming both kinds needs both to match)
+      --sort impact                   ...most consequential groups first
 git gloss html [<commit>|<range>]     self-contained HTML view, of one commit or a branch (--open, -o <file>)
 git gloss ary [--port <n>] [--no-open] browse branches, commits and wip in a local web page (see "Browsing")
 git gloss why <file>:<line>[-<end>]   explain why code exists (via blame), looking past mechanical edits
@@ -157,6 +161,47 @@ A review says that something was checked, not that it passed. Each review ends w
 
 Like glosses, reviews follow rebased commits in repos set up with `git gloss init`. Reviews are shared by `git gloss sync` (and so by every push with the hooks) like glosses, for commits the remote has. They never conflict: everyone's reviews are kept. Other tools can record reviews too: `git gloss reviews --stamp <rev>` before the review, then `git gloss reviews --record` with the stamp and the report as JSON on stdin.
 
+## Impact and attention
+
+Necessity and consequence are separate: a `required` one-line fix to a login helper matters more than a `required` rename in a leaf component. Two optional fields say so. Each group may have `impact` (`local < module < shared < contract < sensitive`, the farthest its effect reaches if it is wrong) and an `impact_reason` of up to 120 characters. The annotation may have `attention`: `level` (`skim`, `look`, `careful` or `must-read`), one to three `focus` group ids to read first, `reasons`, and an optional `override_reason`. `git gloss schema` lists them all.
+
+`show` leads with `attention: CAREFUL (declared) · floor: careful · focus: a, b` and the reasons, and badges each group with its impact; `html` shows the same as a banner whose focus links jump to the groups. Where nothing is declared, `show` and `html` show a value computed from the diff and mark it, as in `attention: LOOK (derived)` (a group's derived impact is in parentheses); a gloss reads as `attention: unrated` only where no signals can be computed. When glosses are combined (`carry`, a squash, a rebase) the attention level is the highest of them and the focus groups are the most impactful three, with the reasons joined; if any of them declared none, the combined gloss declares none and shows a derived one.
+
+Notes using these fields are format 4; a git-gloss that predates them refuses such a note ("written by a newer git-gloss") rather than silently dropping the fields. A gloss that doesn't use them is still written in its old format. Derived values and floors are computed on every read and never stored in a note.
+
+### Computed signals and the floor
+
+`git gloss signals [<commit>|<range>|wip] [--json]` reports, per hunk, file and change: the path classes (`sensitive`, `shared`, `contract`, `generated`, `test`, `docs`, plus `lockfile` and `manifest`), pattern hits, stats (files, hunks, lines, test files, share of hunks in tests), dependency changes, and the floor. `wip` is the working tree as it is now (no snapshot is taken). `hunks` ends with a short summary of the same, so read it before writing a gloss. Signals are cheap heuristics from globs and regexes, not a security scanner.
+
+- **Pattern hits** are regexes (case-insensitive unless the pattern sets `flags`) matched against the *added and removed* lines of a hunk only: never unchanged context lines, never the `@@` header. In test, docs and lockfile paths they are *damped*: still reported, but they don't count towards the floor (a `password` in a test file is not sensitive).
+- **Dependencies.** Edits to manifests and lockfiles are listed. `package-lock.json` and `pnpm-lock.yaml` are parsed from their changed lines for version bumps, and a bump of a package that no `package.json` change names is flagged as transitive. Other lockfiles are `contract` with no version detail.
+- **Floor of a hunk**: the highest of its path class (`sensitive`, `contract`, `shared`; lockfiles and manifests are at least `contract`; otherwise `module`) and its undamped pattern hits. Test, docs and generated files cap at `local` (a pattern hit in generated code still counts). A group's floor is the highest floor of its hunks; for a group that claims only some lines of a hunk, only the hits on those lines count.
+- **Floor of the change**: skim for `local`, look for `module`, careful for `shared` and `contract`, must-read for `sensitive`, and at least careful when more than `attention.largeChangeFiles` (default 50) files changed.
+- **Derived attention** (when the gloss declares none): start from the highest group impact (declared, else the group's floor) with the same mapping, then raise it one step (capped at must-read, once however many apply) for a behaviour-changing group that no test group serves, for a speculative or defensive group outside tests, or for more than `largeChangeFiles` files; never below the floor. A group is *behaviour-changing* when its necessity is not `mechanical` and not all its hunks are tests, docs, generated files or lockfiles. It is *served by tests* when a group made only of test-file hunks names it in `serves`, directly or through groups it serves; a test group serving `"task"` doesn't count.
+
+`add` checks a gloss against the floor. A group whose declared `impact` is below its floor (above plain `module`) is a warning naming the signal. A declared `attention.level` below the floor is an error unless `attention.override_reason` says why; `--allow-underrate` turns that error into a warning. Leaving `impact` or `attention` out is always allowed. An `override_reason` is shown by `show` and `html` next to the floor, flagged as a mismatch.
+
+### Config
+
+The built-in defaults name no language, framework or tool, only common file names. A repo adds to them with `.gloss/config.json`, committed in that repo. The file is read from the base branch (the merge base of the checked-out `HEAD` and `origin/main`, `main`, `origin/master` or `master`, so a long-lived branch sees the config as of where it forked; a commit on the base branch itself reads its own config, flagged `sensitive` if it edits the file), never from the working tree, so a change cannot reclassify its own paths; a config edit only takes effect once it is on the base branch. With none of those branches the defaults apply, with a warning. Editing the file is itself always a `sensitive` path. A pattern that takes over 250 ms on a hunk is cut off and from then on counts as matching every changed line (with a warning), so a slow or padded line raises the floor and never lowers it:
+
+```json
+{
+  "attention": { "largeChangeFiles": 80 },
+  "paths": {
+    "shared": ["packages/shared/**", "tsconfig.base.json"],
+    "sensitive": ["src/devices/**"],
+    "test": { "extends": false, "globs": ["**/*.spec.*", "e2e/**"] }
+  },
+  "patterns": {
+    "sensitive": [{ "regex": "\\bdevice\\.write\\(", "name": "device write" }],
+    "contract": ["<regex for the repo's public-API markers>"]
+  }
+}
+```
+
+A class is a list that extends the default list, or `{ "extends": false, "globs": [...] }` (`"regexes"` for patterns) to replace it. Path classes: `sensitive`, `shared`, `contract`, `generated`, `test`, `docs`, `lockfile`, `manifest`; pattern classes: `sensitive`, `contract`, `shared`. Globs support `**`, `*`, `?` and `{a,b}`; a glob without a `/` matches that name at any depth. `git config gloss.attention.largeChangeFiles <n>` overrides the file. A malformed config is an error naming the file and key (`add` and `signals` stop; `show` falls back to declared values and "unrated").
+
 ## HTML view
 
 `git gloss html --open` writes a single HTML file (no network access, works offline) and opens it. It shows the task and summary, a bar of how the changed lines split across necessity categories, and a card per group with its rationale; code is collapsed until you ask for it. Click categories to filter, use the sidebar to jump between groups, or press `j`/`k` to move, `o` to show code, and `e`/`c` to expand or collapse everything. `#g-<group>` in the URL opens that group.

package/dist/attention.js

@@ -0,0 +1,34 @@
+import { ATTENTION, IMPACT } from './schema.js';
+// Rank of a group's impact; a group with none is below every level.
+export const impactRank = (i) => (i ? IMPACT.indexOf(i) : -1);
+export const maxImpact = (a, b) => (impactRank(b) > impactRank(a) ? b : a);
+export const attentionRank = (a) => (a ? ATTENTION.indexOf(a) : -1);
+export const maxAttention = (a, b) => (attentionRank(b) > attentionRank(a) ? b : a);
+// One step up, capped at must-read.
+export const raise = (a) => ATTENTION[Math.min(ATTENTION.length - 1, ATTENTION.indexOf(a) + 1)];
+// The attention a given impact calls for, before any raising.
+const ATTENTION_FOR_IMPACT = {
+    local: 'skim', module: 'look', shared: 'careful', contract: 'careful', sensitive: 'must-read',
+};
+export const attentionForImpact = (i) => ATTENTION_FOR_IMPACT[i];
+// What the reviewer should do when glosses are combined (a squash, a rebase):
+// the highest level of any of them. Focus groups of all of them, renamed to
+// their new ids (`rename` returns undefined for a group that is gone), most
+// impactful first, without repeats, at most three. Reasons are unioned.
+export function combineAttention(parts, rename, groups) {
+    if (!parts.length)
+        return undefined;
+    const level = parts.map((p) => p.level).reduce((a, b) => (ATTENTION.indexOf(b) > ATTENTION.indexOf(a) ? b : a));
+    const impactOf = new Map(groups.map((g) => [g.id, g.impact]));
+    const focus = [...new Set(parts.flatMap((p, i) => (p.focus ?? []).flatMap((id) => rename(i, id) ?? [])))]
+        .sort((a, b) => impactRank(impactOf.get(b)) - impactRank(impactOf.get(a)))
+        .slice(0, 3);
+    const reasons = [...new Set(parts.flatMap((p) => p.reasons ?? []))];
+    const overrides = [...new Set(parts.flatMap((p) => (p.override_reason && p.level === level ? [p.override_reason] : [])))];
+    return {
+        level,
+        ...(focus.length ? { focus } : {}),
+        ...(reasons.length ? { reasons } : {}),
+        ...(overrides.length ? { override_reason: overrides.join('; ') } : {}),
+    };
+}

package/dist/carry.js

@@ -52,5 +52,8 @@ export function carryGloss(note, current, previous = []) {
     const byId = new Map(current.map((h) => [h.id, h]));
     const claims = groups.flatMap((g) => [...selections(g.hunks, (id) => { const h = byId.get(id); return h && changedCount(h); })]
         .flatMap(([id, lines]) => { const h = byId.get(id); return h ? [{ hunk: h, lines }] : []; }));
-    return { annotation: { ...a, groups }, kept: groups.length, total: a.groups.length, dropped, gaps: uncovered(current, claims), partialMatch };
+    // Focus groups that were left behind can't be pointed at.
+    const focus = a.attention?.focus?.filter((id) => keptIds.has(id));
+    const attention = a.attention && { ...a.attention, focus: focus?.length ? focus : undefined };
+    return { annotation: { ...a, groups, ...(attention ? { attention } : {}) }, kept: groups.length, total: a.groups.length, dropped, gaps: uncovered(current, claims), partialMatch };
 }

package/dist/cli.js

@@ -10,11 +10,12 @@ import * as review from './commands/review.js';
 import * as reviews from './commands/reviews.js';
 import * as schema from './commands/schema.js';
 import * as show from './commands/show.js';
+import * as signals from './commands/signals.js';
 import * as sync from './commands/sync.js';
 import * as versions from './commands/versions.js';
 import * as why from './commands/why.js';
 const COMMANDS = {
-    init, hunks, add, adopt, carry, show, html, ary, why, review, reviews, sync, versions, schema,
+    init, hunks, signals, add, adopt, carry, show, html, ary, why, review, reviews, sync, versions, schema,
 };
 function help() {
     return 'usage: git gloss <command> [options]\n\n' +

package/dist/commands/add.js

@@ -5,7 +5,9 @@ import { commitDiff, isWipSnapshot, NOTES_REF, readNote, resolveCommit, WIP_NOTE
 import { location, parseDiff } from '../diff.js';
 import { Annotation, noteFormat } from '../schema.js';
 import { validate } from '../validate.js';
-export const usage = 'add [<commit>] [-f <file>] [--force] [--partial] [--dry-run]   attach an annotation (JSON from file or stdin)';
+import { loadConfig } from '../config.js';
+import { analyzeGroups, groupInputsFor, ratingProblems } from '../floor.js';
+export const usage = 'add [<commit>] [-f <file>] [--force] [--partial] [--allow-underrate] [--dry-run]   attach an annotation (JSON from file or stdin)';
 export function run(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
@@ -14,6 +16,7 @@ export function run(argv) {
             file: { type: 'string', short: 'f' },
             force: { type: 'boolean' },
             partial: { type: 'boolean' },
+            'allow-underrate': { type: 'boolean' },
             'dry-run': { type: 'boolean' },
         },
     });
@@ -41,10 +44,23 @@ export function run(argv) {
     if (uncovered.length && !values.partial) {
         errors.push(`hunks not assigned to any group: ${uncovered.join(', ')} (every hunk needs a group, or pass --partial)`);
     }
+    // Computed signals: group impact below its floor is a warning; attention
+    // below the floor is an error unless explained (override_reason) or allowed.
+    // A malformed config stops here with its own message.
+    const warnings = [];
+    if (!errors.length) {
+        const analysis = analyzeGroups(hunks, groupInputsFor(parsed.data, hunks), loadConfig());
+        const problems = ratingProblems(parsed.data, analysis);
+        warnings.push(...problems.warnings);
+        if (problems.underrated)
+            (values['allow-underrate'] ? warnings : errors).push(problems.underrated);
+    }
     if (errors.length) {
         console.error('error: annotation is inconsistent with the commit:\n' + errors.map((e) => `  ✖ ${e}`).join('\n'));
         return 1;
     }
+    for (const w of warnings)
+        console.error(`warning: ${w}`);
     // Not an error: long intents still work, but they make the summary rows tall.
     for (const g of parsed.data.groups.filter((g) => g.intent.length > 100)) {
         console.error(`note: group "${g.id}" has a ${g.intent.length}-character intent; keep it under ~80 and move detail to "notes"`);

package/dist/commands/hunks.js

@@ -6,6 +6,10 @@ import { location, parseDiff } from '../diff.js';
 import { noteFormat } from '../schema.js';
 import { colorDiff, hunkLabel, page, style } from '../render.js';
 import { bodyLines, changedCount } from '../selection.js';
+import { loadConfig } from '../config.js';
+import { withSignals } from '../floor.js';
+import { analyze } from '../signals.js';
+import { summaryLines } from './signals.js';
 export const usage = 'hunks [<commit> | wip] [--stat] [--json]   list a commit\'s hunks (or snapshot uncommitted work with wip), numbering changed lines';
 export function run(argv) {
     const { values, positionals } = parseArgs({
@@ -59,6 +63,9 @@ export function run(argv) {
             return colorDiff(h.text, '       ');
         return [colorDiff(header, '       '), ...body.map((l) => style('dim', (l.idx === null ? '' : String(l.idx)).padStart(5)) + '  ' + colorDiff(l.raw))].join('\n');
     };
-    page(hunks.map((h) => hunkLabel(h) + style('dim', `  (${changedCount(h)} changed)`) + (values.stat ? '' : '\n' + numbered(h) + '\n')).join('\n'));
+    // What the diff itself says about attention, for the author to read before glossing.
+    const summary = withSignals(() => summaryLines(analyze(hunks, loadConfig())));
+    const signals = summary ? ['', ...summary] : [];
+    page([hunks.map((h) => hunkLabel(h) + style('dim', `  (${changedCount(h)} changed)`) + (values.stat ? '' : '\n' + numbered(h) + '\n')).join('\n'), ...signals].join('\n'));
     return 0;
 }

package/dist/commands/show.js

@@ -2,10 +2,12 @@ import { parseArgs } from 'node:util';
 import { commitSubject, gitTry, readNote, resolveCommits } from '../git.js';
 import { refLabel, sliceStats, sliceText } from '../selection.js';
 import { loadGloss } from '../loader.js';
-import { NECESSITY } from '../schema.js';
+import { impactRank } from '../attention.js';
+import { showsImpact, tryAnalyze } from '../floor.js';
+import { IMPACT, NECESSITY, isImpact, isNecessity } from '../schema.js';
 import { current, reviewStatus, statusPhrase, verdict } from '../reviews.js';
-import { colorDiff, field, groupHeader, hunkLabel, necessityWord, noteFooter, page, style, termWidth, wrap, } from '../render.js';
-export const usage = 'show [<commit> | <range>] [-g <group>]... [--full] [--diff] [--only <necessity,...>]   summarise a gloss, or each commit in a range';
+import { attentionBlock, colorDiff, derivedImpactTag, field, groupHeader, hunkLabel, IMPACT_W, impactTag, necessityWord, noteFooter, page, style, termWidth, wrap, } from '../render.js';
+export const usage = 'show [<commit> | <range>] [-g <group>]... [--full] [--diff] [--only <necessity|impact,...> (a group must match each kind named)] [--sort impact]   summarise a gloss, or each commit in a range';
 // Counts over the lines each part selects, not whole hunks, so groups that
 // split a hunk don't both count all of it.
 function stats(parts) {
@@ -26,12 +28,18 @@ export function run(argv) {
             full: { type: 'boolean' },
             diff: { type: 'boolean' },
             only: { type: 'string' },
+            sort: { type: 'string' },
         },
     });
-    const only = values.only?.split(',').map((s) => s.trim());
-    const unknown = only?.filter((n) => !NECESSITY.includes(n));
+    const names = values.only?.split(',').map((s) => s.trim());
+    const unknown = names?.filter((n) => !isNecessity(n) && !isImpact(n));
     if (unknown?.length) {
-        console.error(`error: unknown necessity ${unknown.join(', ')}; expected ${NECESSITY.join(', ')}`);
+        console.error(`error: unknown necessity or impact ${unknown.join(', ')}; expected ${NECESSITY.join(', ')} or ${IMPACT.join(', ')}`);
+        return 2;
+    }
+    const only = names && { names, necessities: names.filter(isNecessity), impacts: names.filter(isImpact) };
+    if (values.sort !== undefined && values.sort !== 'impact') {
+        console.error(`error: unknown sort ${values.sort}; expected impact`);
         return 2;
     }
     const { shas, merges, range } = resolveCommits(positionals[0] ?? 'HEAD');
@@ -63,7 +71,7 @@ export function run(argv) {
         }
         const out = renderCommit(sha, gloss, values, only, true);
         if (!out) {
-            console.error(`no groups match ${[values.group && `-g ${values.group.join(',')}`, only && `--only ${only.join(',')}`].filter(Boolean).join(' and ')}`);
+            console.error(`no groups match ${[values.group && `-g ${values.group.join(',')}`, only && `--only ${only.names.join(',')}`].filter(Boolean).join(' and ')}`);
             return 1;
         }
         page(out.join('\n'));
@@ -99,13 +107,15 @@ export function run(argv) {
         }
         // An --only filter can leave a commit with nothing to show; say so and move on.
         out.push(...(renderCommit(sha, gloss, values, only, false) ??
-            [`${style('yellow', sha.slice(0, 10))} ${style('bold', gloss.subject)}`, style('dim', `no ${only?.join('/')} groups`)]));
+            [`${style('yellow', sha.slice(0, 10))} ${style('bold', gloss.subject)}`, style('dim', `no ${only?.names.join('/')} groups`)]));
     });
     if (glossed)
         out.push('', style('dim', 'One commit in detail: git gloss show <commit> --full   (or -g <group> for its code)'));
     page(out.join('\n'));
     return 0;
 }
+const matchesOnly = (g, only) => !only ||
+    ((!only.necessities.length || only.necessities.includes(g.necessity)) && (!only.impacts.length || (!!g.impact && only.impacts.includes(g.impact))));
 // One line on whether the commit as it is now was reviewed, per stage.
 function reviewsLine(sha) {
     const statuses = reviewStatus(sha);
@@ -126,15 +136,25 @@ function renderCommit(sha, gloss, values, only, hints) {
         out.push(...field('summary:', a.summary, 0));
     for (const w of gloss.warnings)
         out.push(...field('⚠', w, 0).map((l) => style('red', l)));
-    out.push(reviewsLine(sha));
+    const an = tryAnalyze(gloss);
+    out.push(...attentionBlock(a.attention, an ? { floor: an.floor, derived: an.derived } : undefined), reviewsLine(sha));
     const groups = gloss.groups
-        .filter((g) => !only || only.includes(g.group.necessity))
+        .filter((g) => matchesOnly(g.group, only))
         .filter((g) => !values.group || values.group.includes(g.group.id));
     if (!groups.length)
         return null;
+    // --sort impact: the most consequential first, then by necessity as usual.
+    const byNecessity = (x, y) => NECESSITY.indexOf(x.group.necessity) - NECESSITY.indexOf(y.group.necessity);
+    const byImpact = (x, y) => impactRank(y.group.impact) - impactRank(x.group.impact) || byNecessity(x, y);
+    const detail = values.group || values.full || values.diff;
+    // The summary lists required first; detail views keep the gloss's order unless asked.
+    if (values.sort === 'impact')
+        groups.sort(byImpact);
+    else if (!detail)
+        groups.sort(byNecessity);
     // -g: chosen groups with their code. --full: every group's details, plus
     // alternatives and risks. --diff: --full plus code.
-    if (values.group || values.full || values.diff) {
+    if (detail) {
         const withCode = values.diff || !!values.group;
         for (const g of groups) {
             out.push('', ...groupHeader(g.group));
@@ -163,13 +183,12 @@ function renderCommit(sha, gloss, values, only, hints) {
         return out;
     }
     // Summary: one line per group.
-    const sorted = [...groups].sort((x, y) => NECESSITY.indexOf(x.group.necessity) - NECESSITY.indexOf(y.group.necessity));
     const tally = NECESSITY.map((n) => [n, gloss.groups.filter((g) => g.group.necessity === n).length])
         .filter(([, c]) => c > 0)
         .map(([n, c]) => `${c} ${necessityWord(n)}`);
-    const showing = groups.length < gloss.groups.length ? style('dim', `  (showing ${groups.length}: --only ${only?.join(',')})`) : '';
+    const showing = groups.length < gloss.groups.length ? style('dim', `  (showing ${groups.length}: --only ${only?.names.join(',')})`) : '';
     out.push('', `${style('bold', `${gloss.groups.length} groups:`)} ${tally.join(style('dim', ' · '))}${showing}`, '');
-    const rows = sorted.map((g) => {
+    const rows = groups.map((g) => {
         const s = stats(currentParts(g));
         const stale = g.hunks.filter((h) => h.status !== 'ok').length;
         return {
@@ -182,14 +201,21 @@ function renderCommit(sha, gloss, values, only, hints) {
     const statW = Math.max(...rows.map((r) => r.stat.length), un.count ? 8 : 0);
     const addW = Math.max(...rows.map((r) => r.added.length));
     const remW = Math.max(...rows.map((r) => r.removed.length));
-    const intentCol = 2 + 11 + 2 + idW + 2;
+    // An impact column only when some group declares one or the diff puts one
+    // above the baseline (module), so plain glosses look as before. Undeclared
+    // ones show the group's floor in parentheses.
+    const floorOf = (g) => an?.groups.get(g.group.id)?.floor;
+    const showImpact = showsImpact(gloss.groups.map((g) => g.group), an);
+    const impactW = showImpact ? IMPACT_W + 2 : 0;
+    const anyDerived = showImpact && gloss.groups.some((g) => !g.group.impact && floorOf(g));
+    const intentCol = 2 + 11 + 2 + impactW + idW + 2;
     const statsW = 2 + statW + 1 + addW + 1 + remW;
     const intentW = Math.max(20, termWidth() - intentCol - statsW);
     for (const r of rows) {
         // Intents wrap within their column rather than being cut off; the stats
         // stay on the first line so the numbers still line up.
         const [first, ...rest] = wrap(r.g.group.intent, intentW);
-        out.push(`  ${necessityWord(r.g.group.necessity, 11)}  ${style('bold', r.g.group.id.padEnd(idW))}  ` +
+        out.push(`  ${necessityWord(r.g.group.necessity, 11)}  ${impactW ? (r.g.group.impact ? impactTag(r.g.group.impact, IMPACT_W) : floorOf(r.g) ? derivedImpactTag(floorOf(r.g), IMPACT_W) : ' '.repeat(IMPACT_W)) + '  ' : ''}${style('bold', r.g.group.id.padEnd(idW))}  ` +
             `${first.padEnd(intentW)}  ` +
             style('dim', r.stat.padStart(statW)) + ' ' + style('green', r.added.padStart(addW)) + ' ' + style('red', r.removed.padStart(remW)), ...rest.map((l) => ' '.repeat(intentCol) + l));
         if (r.stale) {
@@ -200,6 +226,8 @@ function renderCommit(sha, gloss, values, only, hints) {
         const where = gloss.unannotated.map((u) => refLabel(u.hunk.id, u.lines)).join(', ');
         out.push(`  ${style(['bold', 'red'], 'unannotated'.padEnd(11))}  ${style('red', `+${un.added} -${un.removed} not in any group: ${where}`)}`);
     }
+    if (anyDerived)
+        out.push('', style('dim', '(impact in parentheses is derived from the diff, not declared)'));
     // Rejected alternatives and risks: short, and often what a reader most
     // lacks, so they're in the summary rather than only behind --full.
     out.push(...noteFooter(gloss.note));

package/dist/commands/signals.js

@@ -0,0 +1,88 @@
+import { parseArgs } from 'node:util';
+import { loadConfig } from '../config.js';
+import { commitDiff, diffBetween, git, GitError, resolveCommit, workingDiff } from '../git.js';
+import { parseDiff } from '../diff.js';
+import { analyze, CONFIG_EDIT_NOTE } from '../signals.js';
+import { impactRank } from '../attention.js';
+import { ATTENTION_STYLE, impactTag, page, style } from '../render.js';
+export const usage = 'signals [<commit> | <range> | wip] [--json]   what the diff itself says about attention: path classes, pattern hits, dependency bumps and the computed floor';
+const pct = (x) => `${Math.round(x * 100)}%`;
+const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
+const statsLine = (s) => `${plural(s.files, 'file')}, ${plural(s.hunks, 'hunk')}, +${s.added} -${s.removed}, ${plural(s.testFiles, 'test file')}` +
+    (s.hunks ? ` (${pct(s.testHunkShare)} of hunks in tests)` : '');
+// The short form `hunks` prints at its end: the floor, the files that set it,
+// and the stats.
+export function summaryLines(sig, max = 6) {
+    const out = [style('bold', 'signals:') + ` floor attention = ${style(['bold', ATTENTION_STYLE[sig.floor.attention]], sig.floor.attention)}`];
+    const files = sig.files.filter((f) => impactRank(f.floor) >= impactRank('shared'))
+        .sort((a, b) => impactRank(b.floor) - impactRank(a.floor) || a.file.localeCompare(b.file));
+    for (const f of files.slice(0, max))
+        out.push(`  ${(f.floor + ':').padEnd(10)} ${f.file}${f.why.length ? ` (${f.why.join('; ')})` : ''}`);
+    if (files.length > max)
+        out.push(`  ... and ${files.length - max} more at shared or above (git gloss signals)`);
+    for (const r of sig.floor.reasons.filter((r) => / files changed /.test(r)))
+        out.push(`  large:     ${r}`);
+    if (sig.floor.reasons.includes(CONFIG_EDIT_NOTE))
+        out.push(`  note:      ${CONFIG_EDIT_NOTE}`);
+    out.push(`  stats: ${statsLine(sig.stats)}`);
+    return out;
+}
+function detailLines(sig, label) {
+    const out = [style('bold', `signals for ${label}:`) + ` floor attention = ${style(['bold', ATTENTION_STYLE[sig.floor.attention]], sig.floor.attention)}` +
+            style('dim', `  (floor impact: ${sig.floor.impact})`)];
+    for (const r of sig.floor.reasons)
+        out.push(`  why: ${r}`);
+    out.push(`  stats: ${statsLine(sig.stats)}`);
+    const notable = sig.hunks.filter((h) => impactRank(h.floor) > impactRank('module') || h.hits.length);
+    if (notable.length)
+        out.push('', style('bold', 'hunks with signals'));
+    for (const h of notable) {
+        out.push(`  ${style('bold', h.id.padEnd(5))} ${impactTag(h.floor, 11)} ${h.file}` +
+            style('dim', `  [${h.classes.join(', ') || 'no class'}]${h.why.length ? ' ' + h.why.join('; ') : ''}`));
+        for (const x of h.hits.slice(0, 8)) {
+            out.push(`        ${h.id}:${x.line} ${x.sign} ${x.class} pattern "${x.name}"${x.damped ? style('dim', ' (damped: test, docs or lockfile path)') : ''}  ${style('dim', x.text)}`);
+        }
+        if (h.hits.length > 8)
+            out.push(style('dim', `        ... ${h.hits.length - 8} more hits (--json)`));
+    }
+    const quiet = sig.hunks.length - notable.length;
+    if (quiet)
+        out.push(style('dim', `  (${plural(quiet, 'other hunk')} at module or below, no pattern hits)`));
+    if (sig.dependencies.length)
+        out.push('', style('bold', 'dependency changes'));
+    for (const d of sig.dependencies) {
+        out.push(`  ${d.file} (${d.kind}${d.format ? `, parsed as ${d.format}` : d.kind === 'lockfile' ? ', no version detail for this format' : ''})`);
+        for (const b of d.bumps.slice(0, 20)) {
+            const what = b.kind === 'bump' ? `${b.name} ${b.from} -> ${b.to}` : b.kind === 'added' ? `+ ${b.name} ${b.to}` : `- ${b.name} ${b.from}`;
+            out.push(`    ${what}${b.unrelated ? style('yellow', '  (transitive: no manifest change names it)') : ''}`);
+        }
+        if (d.bumps.length > 20)
+            out.push(style('dim', `    ... ${d.bumps.length - 20} more (--json)`));
+    }
+    return out;
+}
+// The diff to analyse: wip is the working tree as it is now (no snapshot is taken).
+function target(arg) {
+    if (arg === 'wip')
+        return { diff: workingDiff().diff, label: 'uncommitted changes' };
+    if (arg.includes('...'))
+        throw new GitError(`${arg}: use A..B for the commits on B since A`);
+    if (arg.includes('..')) {
+        const [a, b] = arg.split('..');
+        const base = git(['merge-base', '--end-of-options', a || 'HEAD', b || 'HEAD']).trim();
+        return { diff: diffBetween(base, resolveCommit(b || 'HEAD')), label: arg };
+    }
+    const sha = resolveCommit(arg);
+    return { diff: commitDiff(sha), label: sha.slice(0, 10) };
+}
+export function run(argv) {
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { json: { type: 'boolean' } } });
+    const { diff, label } = target(positionals[0] ?? 'HEAD');
+    const sig = analyze(parseDiff(diff), loadConfig());
+    if (values.json) {
+        console.log(JSON.stringify({ target: label, ...sig }, null, 2));
+        return 0;
+    }
+    page(detailLines(sig, label).join('\n'));
+    return 0;
+}

package/dist/config.js

@@ -0,0 +1,192 @@
+import { z } from 'zod';
+import { GlossError, gitTry } 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):
+//   1. DEFAULTS below: only conventions true almost everywhere, no language,
+//      framework or build tool beyond well-known file names.
+//   2. `.gloss/config.json`, committed in the repo that uses git-gloss.
+//   3. `git config gloss.attention.<key>`, for the scalars.
+// A path or pattern class in the repo config is a list that is added to the
+// default list, or `{ "extends": false, "globs": [...] }` (`"regexes"` for a
+// pattern class) to replace the default list instead.
+export const CONFIG_FILE = '.gloss/config.json';
+export class ConfigError extends GlossError {
+}
+// Classes whose paths decide a hunk's floor, and the ones that only mark it.
+export const PATH_CLASSES = ['sensitive', 'shared', 'contract', 'generated', 'test', 'docs', 'lockfile', 'manifest'];
+// Impact a pattern hit raises a hunk to.
+export const PATTERN_CLASSES = ['sensitive', 'contract', 'shared'];
+export const DEFAULTS = {
+    attention: { largeChangeFiles: 50 },
+    paths: {
+        sensitive: ['**/auth/**', '**/*crypto*', '**/*secret*', '**/*password*', '**/permissions/**', '**/migrations/**'],
+        shared: [],
+        contract: [
+            '**/package.json', '**/package-lock.json', '**/pnpm-lock.yaml', '**/yarn.lock',
+            '**/Cargo.toml', '**/Cargo.lock', '**/go.mod', '**/go.sum',
+            '**/pyproject.toml', '**/poetry.lock', '**/requirements*.txt',
+            '.github/workflows/**', '.gitlab-ci.yml', 'azure-pipelines*.yml', 'Jenkinsfile',
+            '**/Dockerfile', '**/*.proto', '**/openapi*.{yml,yaml,json}',
+        ],
+        generated: ['**/*.lock', '**/*-lock.*', '**/*.snap', '**/__snapshots__/**'],
+        test: ['**/*.{spec,test}.*', '**/test/**', '**/tests/**', '**/__tests__/**'],
+        docs: ['**/*.md', '**/docs/**'],
+        // Dependency files: always at least `contract`; changes to them are listed
+        // as dependency changes, and package-lock.json and pnpm-lock.yaml are
+        // parsed for version bumps.
+        lockfile: ['**/package-lock.json', '**/pnpm-lock.yaml', '**/yarn.lock', '**/Cargo.lock', '**/go.sum', '**/poetry.lock', '**/*.lock'],
+        manifest: ['**/package.json', '**/Cargo.toml', '**/go.mod', '**/pyproject.toml', '**/requirements*.txt'],
+    },
+    patterns: {
+        sensitive: [
+            { regex: '\\b(password|secret|private[_-]?key|api[_-]?key)\\b', name: 'secret or credential' },
+            { regex: '\\b(encrypt|decrypt)\\b', name: 'encryption' },
+            { regex: '\\b(DROP|TRUNCATE|ALTER)\\s+TABLE\\b', name: 'schema change' },
+        ],
+        contract: [],
+        shared: [],
+    },
+};
+const Glob = z.string().min(1).superRefine((g, ctx) => {
+    try {
+        globToRegExp(g);
+    }
+    catch (e) {
+        ctx.addIssue({ code: 'custom', message: `invalid glob "${g}": ${e.message}` });
+    }
+});
+const Globs = z.union([
+    z.array(Glob),
+    z.object({ extends: z.boolean().optional(), globs: z.array(Glob) }).strict(),
+]);
+// One place for how a pattern entry reads: the source, its flags (case-insensitive
+// unless it sets some) and the name shown for its hits.
+function normalise(p) {
+    if (typeof p === 'string')
+        return { source: p, flags: 'i', name: p };
+    // g and y make a RegExp remember where it last matched, which would skip hits
+    // on the next line; each line is tested on its own, so they are dropped.
+    return { source: p.regex, flags: (p.flags ?? 'i').replace(/[gy]/g, ''), name: p.name ?? p.regex };
+}
+const Regex = z.union([
+    z.string().min(1),
+    z.object({ regex: z.string().min(1), name: z.string().optional(), flags: z.string().optional() }).strict(),
+]).superRefine((p, ctx) => {
+    const { source, flags } = normalise(p);
+    try {
+        new RegExp(source, flags);
+    }
+    catch (e) {
+        ctx.addIssue({ code: 'custom', message: `invalid regular expression ${JSON.stringify(source)}: ${e.message}` });
+    }
+});
+const Regexes = z.union([
+    z.array(Regex),
+    z.object({ extends: z.boolean().optional(), regexes: z.array(Regex) }).strict(),
+]);
+const shape = (keys, v) => z.object(Object.fromEntries(keys.map((k) => [k, v.optional()]))).strict();
+export const RepoConfig = z.object({
+    attention: z.object({
+        largeChangeFiles: z.number().int().min(1).optional(),
+    }).strict().optional(),
+    paths: shape(PATH_CLASSES, Globs).optional(),
+    patterns: shape(PATTERN_CLASSES, Regexes).optional(),
+}).strict();
+const compile = (p) => {
+    const n = normalise(p);
+    return { ...n, re: new RegExp(n.source, n.flags) };
+};
+function describe(file, err) {
+    const lines = err.issues.map((i) => {
+        const where = i.path.length ? i.path.map(String).join('.') : '(top level)';
+        // Name the unknown key rather than "Unrecognized key".
+        const extra = i.code === 'unrecognized_keys' ? ` ${i.keys.map((k) => `"${k}"`).join(', ')}` : '';
+        return `  ${where}: ${i.message}${extra}`;
+    });
+    return `${file} is not a valid git-gloss config:\n${lines.join('\n')}`;
+}
+// Merge a repo config over the defaults. Pure, so tests can call it directly.
+export function mergeConfig(raw) {
+    const list = (base, over, key) => {
+        if (!over)
+            return base;
+        if (Array.isArray(over))
+            return [...base, ...over];
+        const items = over[key];
+        return over.extends === false ? items : [...base, ...items];
+    };
+    const paths = {};
+    for (const k of PATH_CLASSES)
+        paths[k] = list(DEFAULTS.paths[k], raw?.paths?.[k], 'globs');
+    const patterns = {};
+    for (const k of PATTERN_CLASSES)
+        patterns[k] = list(DEFAULTS.patterns[k], raw?.patterns?.[k], 'regexes').map(compile);
+    // Editing the config changes how every later change is rated; no repo config can drop this.
+    paths.sensitive = [...paths.sensitive, CONFIG_FILE];
+    return { attention: { ...DEFAULTS.attention, ...raw?.attention }, paths, patterns };
+}
+// `git config gloss.attention.<key>` as a positive integer; throws naming the key.
+function gitInt(key) {
+    const v = gitTry(['config', '--get', `gloss.attention.${key}`])?.trim();
+    if (v === undefined || v === '')
+        return undefined;
+    if (!/^[1-9]\d*$/.test(v))
+        throw new ConfigError(`git config gloss.attention.${key} must be a positive integer, got "${v}"`);
+    return Number(v);
+}
+// The config is read from the base branch, not the working tree: a change under
+// review must not be able to reclassify its own paths or add patterns that
+// lower its own floor. The base is the merge base of the checked-out HEAD (not
+// the commit under review) and the first of origin/main, main, origin/master,
+// master that shares history with it, so a long-lived branch sees the config as
+// of its fork point. With none of them there
+// is no trusted base, so the built-in defaults apply (with a warning), never
+// the change's own config. Editing the file in a change is itself flagged: it
+// is always a `sensitive` path.
+function trustedRef() {
+    // 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']) {
+        const mb = gitTry(['merge-base', 'HEAD', b])?.trim();
+        if (mb)
+            return mb;
+    }
+    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;
+}
+function readRepoConfig() {
+    const ref = trustedRef();
+    const text = ref ? gitTry(['show', `${ref}:${CONFIG_FILE}`]) : null;
+    if (text === null)
+        return undefined;
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        throw new ConfigError(`${CONFIG_FILE} is not valid JSON: ${err.message}`);
+    }
+    const parsed = RepoConfig.safeParse(json);
+    if (!parsed.success)
+        throw new ConfigError(describe(CONFIG_FILE, parsed.error));
+    return parsed.data;
+}
+// Per working directory, so a command over many commits resolves the repo once.
+const cache = new Map();
+export const resetConfigCache = () => cache.clear();
+// The effective config for the repository the process runs in (the repo file
+// as of the base branch, see trustedRef). Throws ConfigError (with the file
+// and key) for a malformed repo config or git setting. Memoised per working
+// directory.
+export function loadConfig() {
+    const hit = cache.get(process.cwd());
+    if (hit)
+        return hit;
+    const raw = readRepoConfig();
+    const config = mergeConfig(raw);
+    const files = gitInt('largeChangeFiles');
+    if (files !== undefined)
+        config.attention.largeChangeFiles = files;
+    cache.set(process.cwd(), config);
+    return config;
+}