@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/lib/rfc-cli.js

@@ -2,21 +2,14 @@
 "use strict";
 
 /**
- * lib/rfc-cli.js — `exceptd rfc <number>` resolver.
- *
- * Local index (whole current RFC series, offline) -> resolved cache -> one
- * datatracker lookup to disambiguate obsoleted-vs-nonexistent. Resolves an RFC
- * number to its title + status so an agent can confirm a citation (e.g. "is
- * RFC 9404 the Sieve spec?") without the datatracker. Optional --check
- * "<claimed title>" reports whether the claimed title matches.
+ * `exceptd rfc <number>` — resolves an RFC number to its title and status:
+ * local index, then resolved cache, then one datatracker lookup to separate
+ * obsoleted from nonexistent.
  */
 
 const { resolveRfc } = require("./citation-resolve.js");
 
-// Stopwords that don't disambiguate one RFC title from another. A claimed title
-// run preceded by one of these in the index title is still a clean match; a run
-// preceded by a CONTENT word (e.g. "datagram" before "transport layer security")
-// is the tail of a more-specific title and must NOT be accepted as a match.
+// Stopwords don't disambiguate one RFC title from another.
 const TITLE_STOPWORDS = new Set(["the", "a", "an", "of", "for", "to", "in", "on", "and", "or"]);
 
 function normTitle(s) {
@@ -24,37 +17,19 @@ function normTitle(s) {
 }
 
 /**
- * Decide whether a claimed RFC title matches the authoritative index title.
- *
- * Replaces the old lenient bidirectional substring test (`a.includes(b) ||
- * b.includes(a)`), which let "TLS" match the DTLS title (substring of "dtls")
- * and let "Transport Layer Security" match the DTLS title (tail-of-phrase).
- * The comparison is now whole-word and phrase-aware:
- *
- *   1. Every claimed token must appear as a WHOLE word in the index title
- *      (so "tls" never matches inside "dtls").
- *   2. The claimed token sequence must appear as a CONTIGUOUS run in the index
- *      title, OR the claim must cover enough of the index title (containment
- *      ratio floor) to be unambiguous.
- *   3. A contiguous run that is immediately preceded by a distinguishing
- *      CONTENT word in the index title is rejected — it is the tail of a
- *      more-specific title (the "datagram transport layer security" trap).
- *
- * Returns true / false. Only called when both a claim and an index title exist.
+ * Whole-word, phrase-aware comparison of a claimed RFC title against the
+ * authoritative index title. Called only when both exist.
  */
 function titleMatches(claimed, indexTitle) {
   const claimTokens = normTitle(claimed).split(" ").filter(Boolean);
   const titleTokens = normTitle(indexTitle).split(" ").filter(Boolean);
   if (claimTokens.length === 0 || titleTokens.length === 0) return false;
 
-  // (1) Whole-word containment: every claimed token must be a standalone token
-  //     in the index title. Kills the tls-inside-dtls substring false positive.
   const titleSet = new Set(titleTokens);
   for (const t of claimTokens) {
     if (!titleSet.has(t)) return false;
   }
 
-  // Find every contiguous run of the claim inside the index title.
   const runStarts = [];
   for (let i = 0; i + claimTokens.length <= titleTokens.length; i++) {
     let hit = true;
@@ -65,16 +40,12 @@ function titleMatches(claimed, indexTitle) {
   }
 
   if (runStarts.length > 0) {
-    // A single-token claim that is a whole word in the title is unambiguous on
-    // its own — the whole-word check above already excluded the substring trap
-    // (e.g. "tls" is NOT a token inside "dtls"), so "TLS" correctly matches the
-    // 8446 title (standalone "tls" token) but not the 9147 DTLS title.
+    // A single-token claim that survived the whole-word check is unambiguous on
+    // its own — "tls" is not a token inside "dtls".
     if (claimTokens.length === 1) return true;
-    // (3) For a MULTI-token run, accept only if at least one occurrence is NOT
-    //     preceded by a distinguishing content word — i.e. it begins the title
-    //     or is preceded only by a stopword. A run preceded solely by a content
-    //     qualifier (e.g. "datagram" before "transport layer security") is the
-    //     tail of a more-specific title and must not be accepted as a match.
+    // A multi-token run counts only where some occurrence begins the title or
+    // is preceded by a stopword. Preceded by a content qualifier ("datagram"
+    // before "transport layer security") it is the tail of a different title.
     for (const start of runStarts) {
       if (start === 0) return true;
       const prev = titleTokens[start - 1];
@@ -83,13 +54,9 @@ function titleMatches(claimed, indexTitle) {
     return false;
   }
 
-  // No contiguous run, but all tokens present out of order. Accept only when the
-  // claim covers a strong majority of the index title's tokens (containment
-  // ratio floor) — a few scattered tokens against a long title is ambiguous,
-  // not a match. Count DISTINCT claim tokens that appear in the title: counting
-  // non-distinct tokens lets a repeated-token claim (e.g. "security security
-  // security security") inflate the ratio past the floor and falsely match an
-  // unrelated title.
+  // No contiguous run, all tokens present out of order: accept only when the
+  // claim covers a strong majority of the title's tokens. DISTINCT claim tokens
+  // are counted, or a repeated-token claim inflates the ratio past the floor.
   const distinct = new Set(claimTokens);
   const present = [...distinct].filter((t) => titleSet.has(t)).length;
   const ratio = present / titleTokens.length;
@@ -99,9 +66,8 @@ function titleMatches(claimed, indexTitle) {
 async function main() {
   const argv = process.argv.slice(2);
   const flags = new Set(argv.filter((a) => a.startsWith("--")));
-  // Reject unknown flags (same contract as the in-process verbs). `--check`
-  // consumes the following token as its value; that value is a positional, not
-  // a flag, so it isn't checked here.
+  // Unknown flags are rejected, as in the in-process verbs. `--check` consumes
+  // the following token, which is a positional and so isn't checked here.
   const KNOWN = new Set(["--json", "--pretty", "--air-gap", "--no-network", "--check", "--help", "-h"]);
   const unknown = [...flags].filter((f) => !KNOWN.has(f));
   if (unknown.length > 0) {
@@ -112,10 +78,8 @@ async function main() {
     process.exitCode = 1;
     return;
   }
-  // --check "<claimed title>" consumes the FOLLOWING token as its value. Exclude
-  // that value token by INDEX from the positional pool before selecting id, so
-  // the RFC number resolves correctly regardless of flag order
-  // (`rfc --check "Some Title" 9404` reads id=9404, not id="Some Title").
+  // The `--check` value token is excluded from the positional pool by INDEX, so
+  // `rfc --check "Some Title" 9404` reads id=9404, not id="Some Title".
   const checkIdx = argv.indexOf("--check");
   const checkValueIdx = (checkIdx !== -1 && argv[checkIdx + 1] && !argv[checkIdx + 1].startsWith("--")) ? checkIdx + 1 : -1;
   const positionals = argv.filter((a, i) => !a.startsWith("--") && i !== checkValueIdx);
@@ -123,9 +87,7 @@ async function main() {
   const pretty = flags.has("--pretty");
   const json = flags.has("--json") || pretty;
 
-  // The claimed title is exactly the excluded value token (kept in lockstep with
-  // checkValueIdx so the two never diverge); a trailing `--check` with no value
-  // leaves it null.
+  // Exactly the excluded value token; a trailing `--check` with no value is null.
   let claimedTitle = null;
   if (checkValueIdx !== -1) claimedTitle = argv[checkValueIdx];
 
@@ -143,10 +105,7 @@ async function main() {
   if (claimedTitle && r.title) {
     titleMatch = titleMatches(claimedTitle, r.title);
   }
-  // Derive `ok` from the resolved status + title-check the same way the exit
-  // code is derived below — a non-zero exit (status nonexistent OR an explicit
-  // title mismatch) must carry ok:false, not the inverted ok:true the envelope
-  // previously hardcoded.
+  // `ok` derives from the same condition as the exit code below.
   const fails = r.status === "nonexistent" || titleMatch === false;
   const body = { verb: "rfc", ...r, ...(claimedTitle ? { claimed_title: claimedTitle, title_match: titleMatch } : {}), ok: !fails };
 
@@ -171,15 +130,11 @@ async function main() {
   if (fails) process.exitCode = 2;
 }
 
-// Only run the CLI when invoked directly (`exceptd rfc ...`). When required by a
-// test the IIFE must not fire — it would read process.argv and write to stdout —
-// so the pure title-match helper can be exercised in-process.
+// Under require it would read process.argv and write stdout; keep it testable.
 if (require.main === module) {
   main().catch((err) => {
-    // A corrupt/unreadable RFC index (or any unexpected throw inside the async
-    // body) becomes a rejected promise. Emit the documented {ok:false,error}
-    // envelope rather than crashing with a raw stack trace, and signal failure
-    // via exitCode so the event loop drains stderr before exit.
+    // Any unexpected throw becomes the {ok:false,error} envelope, not a raw
+    // stack; `process.exitCode`, not `process.exit()`, so stderr drains.
     process.stderr.write(JSON.stringify({ ok: false, verb: "rfc", error: String((err && err.message) || err) }) + "\n");
     process.exitCode = 1;
   });