@nightlab-agent/still-true 0.2.0 → 0.3.0

package/README.md

@@ -49,9 +49,12 @@ Look and contradiction lines include GitHub's `state_reason` when supplied, such
 - `0`: nothing contradicted. Look lines may have printed.
 - `1`: at least one contradiction.
 - `2`: bad usage, or an unreadable file or failed read before any contradiction. The run is not complete.
+- `3`: only with `--strict`. A note had no claim to verify, or a claim could not be checked.
 
 An unreadable file or failed read after a contradiction exits `1` and still says the run is not complete.
 
+Without `--strict`, a note with no claims in the sections it reads exits `0`, and so does a claim GitHub has no record of. Add `--strict` when an agent or a script runs the check for you and a green run has to mean something was verified. A contradiction still exits `1` and a failed read still exits `2`. Each note is judged on its own, so a note with no claims fails the run even when another note checked out. Skipped sections alone do not fail a note that had a claim. With `--json`, a run that fails this way adds `strict_failed: true`.
+
 Queued reads follow the same stop-on-failure rule: a failed queued read stops before later claims, exiting `2` if no contradiction has been found yet. Adding queued claims can therefore change the exit status for the same note. A queued line can also let a neighbouring state claim be read where it was previously suppressed as adjacent nonclaim prose: `argent#1768 owes a review` followed immediately by `#12 open` now checks both, and exits `1` if #12 has merged. A look alone still exits `0`.
 
 ## JSON output
@@ -63,7 +66,7 @@ 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`, so a script that must know a note was really read should check `counts.checked` too.
+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`.
 `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.2.0",
+  "version": "0.3.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

@@ -3,9 +3,10 @@ import { spawnSync } from 'node:child_process';
 import { compare } from './compare.mjs';
 import { readState, resolveRef } from './github.mjs';
 
-const USAGE = 'usage: still-true NOTE.md [more.md] [--repo owner/name] [--alias Name=owner/name] [--json]';
+const USAGE = 'usage: still-true NOTE.md [more.md] [--repo owner/name] [--alias Name=owner/name] [--json] [--strict]';
 const JSON_HELP = '--json: print one JSON object (schema 1) with completeness, counts and every extracted claim.';
-const EXIT_HELP = 'exit 0: nothing contradicted, look lines may have printed\nexit 1: at least one contradiction\nexit 2: bad usage, or an unreadable file or failed read before any contradiction; the run is not complete';
+const STRICT_HELP = '--strict: exit 3 if any note had no claim to verify, or if any claim could not be checked. Use it when a green run has to mean the note was really read.';
+const EXIT_HELP = 'exit 0: nothing contradicted, look lines may have printed\nexit 1: at least one contradiction\nexit 2: bad usage, or an unreadable file or failed read before any contradiction; the run is not complete\nexit 3: with --strict only, nothing was verified or a claim was not checked';
 
 export function repoFromRemote(url) {
   const m = /^(?:[a-z+]+:\/\/(?:[^@/\s]+@)?|[^@/\s]+@)?(?:www\.)?github\.com(?::\d+)?[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?\s*$/i.exec(url ?? '');
@@ -15,7 +16,7 @@ export function repoFromRemote(url) {
 const FULL = /^[^/\s=]+\/[^/\s=]+$/;
 
 export function parseArgs(argv) {
-  const a = { files: [], aliases: {}, repo: undefined, bad: null, json: argv.includes('--json') };
+  const a = { files: [], aliases: {}, repo: undefined, bad: null, json: argv.includes('--json'), strict: false };
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--repo') {
       a.repo = argv[++i];
@@ -24,7 +25,8 @@ export function parseArgs(argv) {
       const [name, full, more] = (argv[++i] ?? '').split('=');
       if (name && FULL.test(full ?? '') && more === undefined) a.aliases[name] = full;
       else a.bad ??= '--alias needs Name=owner/name';
-    } else if (argv[i] !== '--json') a.files.push(argv[i]);
+    } else if (argv[i] === '--strict') a.strict = true;
+    else if (argv[i] !== '--json') a.files.push(argv[i]);
   }
   return a;
 }
@@ -52,8 +54,8 @@ export async function run(argv, deps) {
     return code;
   };
   if (argv.includes('--help')) {
-    print(USAGE); print(JSON_HELP); print(EXIT_HELP);
-    return finish(0, null, { help: `${USAGE}\n${JSON_HELP}\n${EXIT_HELP}` });
+    print(USAGE); print(JSON_HELP); print(STRICT_HELP); print(EXIT_HELP);
+    return finish(0, null, { help: `${USAGE}\n${JSON_HELP}\n${STRICT_HELP}\n${EXIT_HELP}` });
   }
   const odd = args.files.find((f) => f.startsWith('--'));
   if (odd) { print(`unknown option ${odd}`); print(USAGE); return finish(2, `unknown option ${odd}`); }
@@ -61,6 +63,7 @@ export async function run(argv, deps) {
   if (!args.files.length) { print(USAGE); return finish(2, USAGE); }
   const seen = new Map();
   const skipped = [];
+  const unread = [];
 
   try {
     const repo = args.repo ?? (typeof defaultRepo === 'function' ? defaultRepo() : defaultRepo);
@@ -84,6 +87,7 @@ export async function run(argv, deps) {
         if (entry) entries.push(entry);
         return { claim, ref, entry };
       });
+      if (!claims.length) unread.push(file);
       skipped.push(...here.map((section) => (args.files.length > 1 ? `${file}: ${section}` : section)));
       for (const { claim, ref, entry } of claims) {
         if (!ref) {
@@ -135,15 +139,23 @@ 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 strictFail = (extra = {}) => {
+    const why = [];
+    if (unplaced) why.push(`${unplaced} claim${unplaced === 1 ? '' : 's'} not checked`);
+    if (unread.length) why.push(`nothing was verified in ${unread.join(', ')}`);
+    print(`--strict: ${why.join(', ')}`);
+    return finish(3, null, { ...extra, strict_failed: true });
+  };
   if (!checked && !unplaced) {
     print('no claims about PR or issue state found');
-    if (!skipped.length) return finish(0);
+    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 finish(0, null, { skipped_sections: skipped });
+    return args.strict ? strictFail({ skipped_sections: skipped }) : finish(0, null, { skipped_sections: skipped });
   }
   const note = (looks ? `, ${looks} to look at` : '') + (unplaced ? `, ${unplaced} not checked` : '');
   print(`${checked} claim${checked === 1 ? '' : 's'} checked, ${contradicted} contradicted${note}`);
-  return finish(contradicted ? 1 : 0);
+  if (contradicted) return finish(1);
+  return args.strict && (unplaced || unread.length) ? strictFail() : finish(0);
 }
 
 export { readState };