@nightlab-agent/still-true 0.3.0 → 0.5.0

package/README.md

@@ -39,6 +39,11 @@ In a Markdown file with headings, it reads a section only if its heading starts
 - `look: waits on ..., which is merged`: the note waits on something finished. It may be waiting for a release or a reply, so read it. This does not fail the run.
 - `look: queued work on ..., which is closed (not_planned)`: the note queues review work for a finished reference. Read whether that work still belongs in the queue. This does not fail the run.
 - `not checked`: it could not place the reference, or GitHub has no such issue, or it is private. Nothing was verified for that line.
+- `no claim read`: a reference on a line it read, where it found no statement about that reference's state. `see #12` lands here, and so can a real statement in a sentence it could not parse. It is a list to read, not a verdict: no exit code changes for it. It does not cover statements that name no reference at all.
+
+A statement about a reference's state may start with `only`, as in `only owner/repo#12 (merged 11-07, known)`. `owner/repo#12, merged 11-07` also reads one merged claim, including after a separate clause such as `Status: draft;`. These are narrow subject-and-state forms: `see owner/repo#12, merged 11-07` still gives no claim.
+
+A standalone retraction field in parentheses or after a comma takes back its clause. A field immediately after a semicolon does too: `#12 is open; no longer true` gives no claim. The wording is `no longer` or `not` followed by `true`, `the case`, `accurate` or `current`, or just `outdated`, `wrong` or `incorrect`; filler such as `which is` or `anymore` is allowed. Extra prose such as `fixes outdated documentation`, quoted text and inline code do not retract. A semicolon retraction takes back the clause before it, back to the previous semicolon or sentence end, so `#12 is open, #13 is open; no longer true` retracts both; a claim in its own clause is still checked: `#12 is open; no longer true; #13 is open` still checks #13. A note containing only a retracted claim exits `0` normally and `3` with `--strict`, since nothing was verified; its reference appears under `no claim read`.
 
 Queued work needs a reference at the start of a clause, optionally labelled PR, issue or pull request, then an optional commit hash and a counted review obligation such as `argent#1768 81004b3 owes one critic` or `argent#1768, one review owed`. Counts are a, an, one, two, three or a positive integer; the nouns are critic(s) or review(s). `still` may precede the obligation. One comma may separate the reference/hash from it, and a following wait may start with `and` or a comma. An open reference stays quiet. A reference alone, a past-tense obligation, or other unquoted trailing prose in that clause does not qualify. Quoted text and inline code are masked before matching: `argent#1768 owes one critic "not anymore"` and ``argent#1768 owes one critic `done` `` still qualify. A wholly quoted obligation stays out, as do historical and planning scopes. Blockquoted lines contribute no claims, including when the quote follows nested list markers. A quote does not silence the preceding paragraph or an independent list item after it; an immediately following unmarked prose line can still continue the quote.
 
@@ -66,7 +71,8 @@ Add `--json` for one JSON object on stdout, with no text lines. Exit codes stay
 The object has `schema: 1`, `complete`, `reason` (`null` on success), `counts` and `claims`.
 Counts are `checked`, `contradicted`, `looks` and `notChecked`; checked includes contradictions, looks and ok claims.
 Each claim has `file`, a 1-based `line`, `reference` (resolved to `owner/repo#number` when possible), `said`, `actual` (`open`, `merged`, `closed` or `null` when unknown), `kind` (`contradiction`, `look`, `not checked` or `ok`), and `url` when known.
-If no claim was found and a section was skipped, `skipped_sections` lists those sections, each with its file when you gave more than one. `complete` is still `true` and the exit is `0` without `--strict`, so a script that must know a note was really read should use `--strict`.
+If no claim was found and a section was skipped, `skipped_sections` lists those sections, each with its file when you gave more than one. `complete` is still `true` and the exit is `0` without `--strict`, so a script that must know something was verified should use `--strict`. Strict does not say every reference gave a claim: read `no claim read` for that.
+`unread_references`, present only when there are some, lists `file`, `line` and `reference` for each reference that gave no claim. It does not change `counts` or the exit.
 `said` can also be `queued`, for the review obligations above. A nonempty GitHub `state_reason` is included as an optional string field; null or absent reasons are omitted.
 
 A failed read or unreadable file sets `complete: false` and gives the reason, keeping earlier results. The run stops there; claims already extracted from the current file that were not reached have kind `not checked`. Later files have no entries. A complete run can still have unchecked claims, such as an unresolved alias or a private issue. No claims gives an empty array and zero counts. `--json --help` returns the help text in a `help` field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightlab-agent/still-true",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Check a handoff note against GitHub: finds what it says about PRs and issues and prints the claims that are no longer true. Exits 1 on a contradiction.",
   "type": "module",
   "bin": { "still-true": "bin/still-true.js" },

package/src/cli.mjs

@@ -43,13 +43,13 @@ export async function run(argv, deps) {
   const { out, extract, readFile = fsRead, read, token, defaultRepo = originRepo, env = process.env } = deps;
   const args = parseArgs(argv);
   const print = (line) => { if (!args.json) out(line); };
-  const entries = [];
+  const entries = [], noClaim = [];
   let checked = 0, contradicted = 0, looks = 0, unplaced = 0, failure = null;
   const finish = (code, reason = null, extra = {}) => {
     if (args.json) out(JSON.stringify({
       schema: 1, complete: reason === null, reason,
       counts: { checked, contradicted, looks, notChecked: entries.length - checked },
-      claims: entries, ...extra,
+      claims: entries, ...(noClaim.length ? { unread_references: noClaim } : {}), ...extra,
     }));
     return code;
   };
@@ -77,8 +77,8 @@ export async function run(argv, deps) {
         return finish(contradicted ? 1 : 2, reason);
       }
       // Record all claims in this file before reading GitHub, including those a failure may leave unchecked.
-      const here = [];
-      const claims = extract(text, { aliases: args.aliases, skipped: here }).map((claim) => {
+      const here = [], unreadHere = [];
+      const claims = extract(text, { aliases: args.aliases, skipped: here, unread: unreadHere }).map((claim) => {
         const ref = resolveRef(claim.ref, { defaultRepo: repo, aliases: args.aliases });
         const entry = args.json ? {
           file, line: claim.line, reference: name(ref ?? claim.ref), said: claim.said,
@@ -127,6 +127,12 @@ export async function run(argv, deps) {
           print(`  "${claim.quote}"`);
         }
       }
+      const written = new Map();
+      for (const { line, ref } of unreadHere) {
+        noClaim.push({ file, line, reference: name(resolveRef(ref, { defaultRepo: repo, aliases: args.aliases }) ?? ref) });
+        written.set(line, [...(written.get(line) ?? []), name(ref)]);
+      }
+      for (const [line, refs] of written) print(`${file}:${line}  no claim read: ${refs.join(', ')}`);
       if (failure !== null) break;
     }
   } catch (e) { failure = e instanceof Error ? e.message : String(e); }
@@ -139,6 +145,7 @@ export async function run(argv, deps) {
     if ((env.HTTPS_PROXY ?? env.https_proxy) && !env.NODE_USE_ENV_PROXY) print('You have a proxy set: run again with NODE_USE_ENV_PROXY=1.');
     return finish(contradicted ? 1 : 2, failure);
   }
+  const leftBehind = noClaim.length ? `${noClaim.length} reference${noClaim.length === 1 ? '' : 's'} with no claim read` : '';
   const strictFail = (extra = {}) => {
     const why = [];
     if (unplaced) why.push(`${unplaced} claim${unplaced === 1 ? '' : 's'} not checked`);
@@ -147,12 +154,12 @@ export async function run(argv, deps) {
     return finish(3, null, { ...extra, strict_failed: true });
   };
   if (!checked && !unplaced) {
-    print('no claims about PR or issue state found');
+    print(`no claims about PR or issue state found${leftBehind && `, ${leftBehind}`}`);
     if (!skipped.length) return args.strict ? strictFail() : finish(0);
     print(`skipped ${skipped.length} section${skipped.length === 1 ? '' : 's'}: ${skipped.join(', ')}. A section is read only if its heading, and every heading above it, apart from the file's title, starts with Now, Handoff, State, Status or Current.`);
     return args.strict ? strictFail({ skipped_sections: skipped }) : finish(0, null, { skipped_sections: skipped });
   }
-  const note = (looks ? `, ${looks} to look at` : '') + (unplaced ? `, ${unplaced} not checked` : '');
+  const note = (looks ? `, ${looks} to look at` : '') + (unplaced ? `, ${unplaced} not checked` : '') + (leftBehind && `, ${leftBehind}`);
   print(`${checked} claim${checked === 1 ? '' : 's'} checked, ${contradicted} contradicted${note}`);
   if (contradicted) return finish(1);
   return args.strict && (unplaced || unread.length) ? strictFail() : finish(0);

package/src/extract.mjs

@@ -13,11 +13,18 @@ const QUEUED = new RegExp(`^(?:(?:PR|issue|pull request)\\s+)?(${TOKEN})(?:\\s+[
 const LABEL_LIST = new RegExp(`(?:^|:\\s*)(open|merged|closed)(?:\\s+(?:PRs|issues|pull requests))?:\\s*(${TOKEN}(?:\\s*(?:,|and)\\s*${TOKEN})*)$`, 'i');
 
 const REF = /^(?:([a-z0-9-]+)\/)?([a-z0-9_.-]+)?#([1-9][0-9]*)$/i;
+const MENTION = /(?<![\w./#-])(?:[a-z0-9-]+\/)?[a-z0-9_.-]*#[1-9][0-9]*(?![\w-]|\.\w)/gi;
 const PLANNED = /\b(?:plans?|planned|planning|proposed|intended|expected|ideas?|goals?|draft|to[- ]?dos?|next|later|someday|old|previous|history|example)\b/i;
 const CURRENT_HEADING = /^(?:handoff|state|status|now|current)\b(?!-)/i;
 const PREAMBLE = /^(?:if|unless|once|after|when|until|yesterday|old note|example|suppose|imagine)\b/i;
 const UNCERTAIN = /\b(?:probably|maybe|might|should|could|would|if|unless|when|until|need|get|think|believe|locally|re-?opened)\b|\bonce\s+(?!at\b)\S|n['’]t\b|\bby\s+(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday|tomorrow|next)\b/i;
 const NONSTATE = /\b(?:(?:not|never|no longer)\s+(?:(?:yet|still|currently|already)\s+)?(?:open|merged|closed)|(?:was|were|used to be)\s+(?:(?:still|currently|already)\s+)?(?:open|closed)|(?:open|merged|closed)\s+or\s+(?:open|merged|closed))\b/i;
+// The writer takes the claim back on the same line: "#12 is open (no longer true)".
+// Only a field that is nothing but the retraction counts, so "(fixes outdated documentation)" keeps its claim.
+const RETRACTION = /^(?:(?:no\s+longer|not)\s+(?:true|the\s+case|accurate|current)|outdated|wrong|incorrect)$/i;
+const RETRACT_FILLER = /\b(?:which|that|this|it|is|was|now|anymore|any\s+more|see\s+below)\b/gi;
+const isRetraction = (field) => RETRACTION.test(field.replace(RETRACT_FILLER, ' ').replace(/[.!]/g, ' ').replace(/\s+/g, ' ').trim());
+const RETRACTED = { test: (body) => body.split(/[(),;]/).some(isRetraction) };
 const NOT_WAITING = /\b(?:(?:not|never|no\s+longer|no\s+more|stop(?:s|ped)?|done|finished|quit|gave\s+up|nothing(?:\s+is)?|without|instead\s+of)\s+(?:(?:yet|still|currently|really)\s+)?(?:waits?|waiting)|(?:n['’]t)\s+(?:waits?|waiting))\b/i;
 const QUALIFIED_STATE = /^\s+(?:to|into|for|or|after)\b/i;
 // A later comma field must look like a state fact, not "open question".
@@ -25,9 +32,9 @@ const COMMA_STATE_TAIL = /^(?:$|\s+(?:\d|today\b|yesterday\b|last\b|since\b|by\b
 // An initial "open PR" needs a predicate to distinguish it from a command.
 const OPEN_PREDICATE = /^\s+(?:is|has|needs|touches)\b/i;
 const OPEN_POSSESSIVE = /(?:['’]s|\b(?:my|our|your|their|his|her|its))\s*$/i;
-// Subjects may have a noun label or a possessive determiner, but objects of
+// Subjects may have "only", a noun label or a possessive determiner, but objects of
 // phrases such as "a PR for issue #12" are not the subject of that PR's state.
-const SUBJECT_PREFIX = /^(?:(?:PR|issue|pull request)|(?:[\w'-]+\s+)+(?:PR|issue|pull request)|(?:the\s+)?[\w-]+['’]s|(?:my|our|your|their|his|her|its)(?:\s+own)?)?$/i;
+const SUBJECT_PREFIX = /^(?:only|(?:PR|issue|pull request)|(?:[\w'-]+\s+)+(?:PR|issue|pull request)|(?:the\s+)?[\w-]+['’]s|(?:my|our|your|their|his|her|its)(?:\s+own)?)?$/i;
 const OBJECT_PREFIX = /\b(?:for|of|on|about|after)\b/i;
 
 function nextQuote(raw, i, quote) {
@@ -45,6 +52,12 @@ function endQuote(raw, quote) {
 
 function clauses(raw) {
   const result = [];
+  let afterSemicolon = false;
+  const add = (clause) => {
+    // Keep a standalone semicolon retraction with the clause it takes back.
+    if (afterSemicolon && isRetraction(unquoted(clause))) result[result.length - 1] += `; ${clause}`;
+    else result.push(clause);
+  };
   let start = 0, quote = null, code = null, depth = 0;
   for (let i = 0; i < raw.length; i++) {
     const char = raw[i];
@@ -61,11 +74,12 @@ function clauses(raw) {
     if (char === '(') depth++;
     if (char === ')') depth--;
     if (depth === 0 && (char === ';' || (/[.!?]/.test(char) && /\s|^$/.test(raw[i + 1] ?? '')))) {
-      result.push(raw.slice(start, char === ';' ? i : i + 1).trim());
+      add(raw.slice(start, char === ';' ? i : i + 1).trim());
+      afterSemicolon = char === ';';
       start = i + 1;
     }
   }
-  result.push(raw.slice(start).trim());
+  add(raw.slice(start).trim());
   return result.filter(Boolean);
 }
 
@@ -106,7 +120,7 @@ const laterStep = (field) => (field.includes('#') || /\b(?:only|just|not|except|
 
 function claimsFromClause(quote, line) {
   const body = unquoted(quote);
-  if (!body.includes('#') || body.includes('?') || UNCERTAIN.test(body.replace(LATER_STEP_ONCE, laterStep)) || NONSTATE.test(body)) return [];
+  if (!body.includes('#') || body.includes('?') || UNCERTAIN.test(body.replace(LATER_STEP_ONCE, laterStep)) || NONSTATE.test(body) || RETRACTED.test(body)) return [];
   const claims = [];
   const add = (tokens, said) => {
     for (const token of tokens) {
@@ -199,6 +213,24 @@ function claimsFromLine(raw, line) {
   return claims;
 }
 
+const refKey = (ref) => `${ref.owner ?? ''}/${ref.repo ?? ''}#${ref.number}`.toLowerCase();
+
+// References on read lines that gave no claim, once per line, in note order.
+function unreadReferences(read, claims) {
+  const claimed = new Set(claims.map((claim) => `${claim.line} ${refKey(claim.ref)}`));
+  const unread = [];
+  for (const { raw, line } of read) {
+    for (const [token] of unquoted(raw).matchAll(MENTION)) {
+      const ref = makeClaim(token, '', '', line)?.ref;
+      const id = ref && `${line} ${refKey(ref)}`;
+      if (!ref || claimed.has(id)) continue;
+      claimed.add(id);
+      unread.push({ line, ref });
+    }
+  }
+  return unread;
+}
+
 function closes(lines, from, open) {
   let quote = open;
   for (let i = from; i < lines.length && quote !== null; i++) quote = endQuote(lines[i], quote);
@@ -208,7 +240,7 @@ function closes(lines, from, open) {
 // Aliases and the default repository are resolved by the reader. Preserve the
 // identity written in the note, including refs that the reader cannot place.
 export function extractClaims(text, options = {}) {
-  const claims = [];
+  const claims = [], read = [];
   let paragraph = [], fence = null, quote = null, comment = false, sections = [], frontMatter = false, titled = false, planned = null;
   const flush = (keepLabel = false) => {
     // A wrapped condition, quotation or historical preamble can change the
@@ -300,6 +332,7 @@ export function extractClaims(text, options = {}) {
       const title = paragraph.map((entry) => entry.text).filter(Boolean).join(' ');
       // Preserve the conservative reading of multiline headings while naming them.
       const currentTitle = paragraph.length === 1 ? lines[index - 1].trim() : '';
+      while (read.at(-1)?.line > index - paragraph.length) read.pop(); // Those lines were a heading after all.
       paragraph = [];
       enterSection(underline[1][0] === '=' ? 1 : 2, currentTitle, title);
     } else if (underline && paragraph.length) {
@@ -313,6 +346,7 @@ export function extractClaims(text, options = {}) {
       const bare = body.replace(/[*_`]/g, '');
       const item = /^\s*(?:[-+*]|[0-9]+[.)])\s+/.test(raw);
       if (item && paragraph.at(-1)?.blockquote) flush(true); // A new list is not a quote continuation.
+      if (readable() && !/^(?: {4}|\t)/.test(raw) && !paragraph.at(-1)?.blockquote) read.push({ raw, line: index + 1 });
       if (!item && paragraph.at(-1)?.blockquote) { // Every unmarked line of a quoted paragraph stays in the quote.
         paragraph.push({ claims: [], list: false, indent: Infinity, blockquote: true });
         continue;
@@ -325,5 +359,6 @@ export function extractClaims(text, options = {}) {
     }
   }
   flush();
+  options.unread?.push(...unreadReferences(read, claims));
   return claims;
 }