@cosyte/script-utils 0.1.5 → 0.1.6

package/internal-refs.js

@@ -103,6 +103,16 @@ export const CONFIG_AXES = Object.freeze([
       "rules. `/** */` blocks compile into shipped type declarations, so they are public surface " +
       "in a repository that publishes types.",
   }),
+  Object.freeze({
+    name: "sourceStringLiterals",
+    required: false,
+    refusesEmpty: false,
+    default: "{ enabled: false }",
+    summary:
+      "Whether the source string-literal pass runs, over which tracked paths, and with which extra " +
+      "rules. A string literal reaches a consumer as error and warning text, so it is public " +
+      "surface; a comment is not, and this pass never reads one.",
+  }),
   Object.freeze({
     name: "exitCodes",
     required: false,
@@ -343,14 +353,21 @@ export function compileCanonicalRules(resolved) {
     {
       id: "internal-identifier",
       name: "internal project identifier",
-      patterns: [new RegExp(identifier, "g")],
-      positives: identifierPositives,
+      patterns: [
+        new RegExp(identifier, "g"),
+        // An umbrella spec or work-item id: `S` and four digits, then a lower-case slug
+        // (`S0228-github-profile-ci-drift`). The slug is what keeps a HCPCS code such as `S9083`
+        // out; dicom's gate carried the rule.
+        new RegExp("\\bS\\d{4}-[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\b", "g"),
+      ],
+      positives: [...identifierPositives, "Tracked as S0228-github-profile-ci-drift"],
       // The WORD-N trap turned into an assertion. Every token here is a segment-field reference or
       // a diagnosis-code range, and a prefix set that starts matching one of them reds HERE rather
       // than deleting it from a parser's documentation on the next sweep.
       negatives: [
         "MSH-2 encoding characters, PID-3 identifier list, OBX-5 value, SCH-11 timing, " +
           "TQ1-7 start, NM1-03 name, ICD-10-CM P00-P96, 835 remittance",
+        "HCPCS S9083 and S0630 are billing codes, and S0228 alone is one too",
       ],
     },
     {
@@ -364,6 +381,15 @@ export function compileCanonicalRules(resolved) {
             `documentation residual\\b|${ORDINAL} (?:slice|wave)\\b)`,
           "gi",
         ),
+        // Taken from dicom's gate: the adjective forms (`in subsequent phases`, `a later wave`), a
+        // plural wave count, and a citation of the roadmap. `of` after the noun is the clinical
+        // sense (`a later phase of the disease`, `the next wave of infections`), so it is let through.
+        new RegExp(
+          "\\b(?:subsequent|later|earlier|future|upcoming|next|previous|remaining)\\s+" +
+            "(?:phases?|waves?)\\b(?!\\s+of\\b)|\\bwaves\\s+\\d+\\b|" +
+            "\\b(?:the|this|its|our)\\s+(?:\\w+\\s+)?roadmaps?\\b",
+          "gi",
+        ),
       ],
       positives: [
         "Phase 5b closes it (Phase W, Phase-L and the thirteenth slice landed earlier, in wave 2)",
@@ -373,6 +399,9 @@ export function compileCanonicalRules(resolved) {
         // phase named before the words that make a bare `phase` a noun.
         "The connect-phase socket shipped in phase 2",
         "Phase 3 was where the error occurred",
+        "The helpers are populated in subsequent phases",
+        "It arrives in a later wave, after waves 2 and 3",
+        "Obsolete codes are tracked by the roadmap",
       ],
       negatives: [
         "CSP-1 Study Phase Identifier, CSP-2 Study Phase Start Date/Time, CSP-3 Study Phase End " +
@@ -385,15 +414,20 @@ export function compileCanonicalRules(resolved) {
         "All 5 phases are defined; Connection lifecycle phase where the error occurred; the " +
           "phase was open, the phases were closed, and a phase during which and a phase at which " +
           "the socket failed",
+        // The clinical senses of the adjective forms.
+        "A later phase of the disease, the next wave of infections, and the previous phase of " +
+          "the trial",
       ],
     },
     {
       id: "adr-reference",
       name: "ADR reference",
       // `[ /-]`: ten of the eleven per-repository copies also matched an ADR path segment.
-      patterns: [new RegExp("\\bADR[ /-]?\\d{3,4}\\b", "gi")],
+      // The plural, `#` and two-digit forms are dicom's: `ADRs 0015 and 0016`, `ADR #0018`, `ADR 23`.
+      patterns: [new RegExp("\\bADRs?[ /#-]?\\d{2,4}\\b", "gi")],
       positives: [
         "Decided in ADR 0015 and restated in ADR-0021",
+        "Superseded by ADRs 0015 and ADR #0018, after ADR 23",
         "Recorded in docs/adr/0001-scope.md",
       ],
       negatives: ["ADR is not a segment, and 0015 alone is a value"],
@@ -402,18 +436,50 @@ export function compileCanonicalRules(resolved) {
       id: "internal-jargon",
       name: 'internal jargon ("slice")',
       patterns: [
+        // `the` and `each` are NOT determiners here. A fixed-width code file's FIELD SLICE is a
+        // byte range and a public API parameter (terminology's `FixedWidthFieldSlice`), and with
+        // `the` in the class the rule flagged every `the field slice` and `the slice holding the
+        // concept code` in that documentation, which a remediator cannot rewrite. What the
+        // narrowing costs: a bare `the slice`, `the last slice` and `each slice` are no longer
+        // hits. `this`, `that`, `another`, `previous`, `next`, `final` and `current` still are,
+        // so `the final slice` and `the next slice` still red, and the ordinal forms
+        // (`the thirteenth slice`) are the phase rule's.
         new RegExp(
-          "\\b(?:this|that|the|each|another|previous|next|final|current)\\s+" +
+          "\\b(?:this|that|another|previous|next|final|current)\\s+" +
             "(?:(?!(?:of|in|on|between|per|for|to|with|at)\\s)[\\w-]+\\s+){0,2}slices?\\b" +
-            `(?!\\s+(?:${IMAGING_NOUNS}))`,
+            `(?!\\s+(?:${IMAGING_NOUNS}))` +
+            // An image slice in its volume is DICOM's word (dicom's own reference sentences).
+            "(?!\\s+in\\s+(?:the|this|a|an|each)\\s+(?:volume|series|stack|study|image|frame)\\b)",
+          "gi",
+        ),
+        // Process commentary, taken from dicom's gate: a pull request, changeset or work item named
+        // as ours, and work deferred out of scope. `this spec`, `this session` and `this port` are
+        // left out: a parser's specification, a TLS session and a TCP port are reader words here.
+        new RegExp(
+          "\\bthis\\s+(?:work item|changeset|change set|pull request|PR)\\b|" +
+            "\\b(?:a|the|another|one)\\s+(?:later|future|separate|follow-up|subsequent)\\s+" +
+            "(?:PR|pull request|work item|changeset)\\b|" +
+            "\\bout\\s+of\\s+scope\\s+for\\s+(?:this|the)\\s+(?:slice|item|change|pass)\\b",
           "gi",
         ),
       ],
-      positives: ["This slice adds the helper and the final slice removes it"],
+      positives: [
+        "This slice adds the helper and the final slice removes it",
+        // What the narrowing must still catch: the determiners it kept, after `the`.
+        "The next slice moves the parser, and that slice and another slice follow it",
+        "Landed by a later PR, and out of scope for this change",
+      ],
       negatives: [
         "The slice thickness and the number of slices are DICOM attributes, each slice location " +
           "is too, and the phase of the clinical study, the phase of illness and each phase of " +
           "the trial are the reader words this rule must not touch",
+        // A fixed-width field slice is reference material: the byte range a reader passes in.
+        "The consumer supplies the field slices, the reader takes the slices as a parameter, a " +
+          "line too short to contain the code slice is skipped, the field is empty when the slice " +
+          "is entirely past the line's end, and each slice is a start and an end. The slice " +
+          "holding the concept code. The field slice.",
+        "Slice Thickness and Slice Location describe the next slice in the volume, and this " +
+          "specification, this session and this port are the reader's",
       ],
     },
     {
@@ -426,10 +492,24 @@ export function compileCanonicalRules(resolved) {
             "|\\bBACKLOG\\.md\\b",
           "g",
         ),
+        // Taken from dicom's gate: the planning files a session writes, the umbrella named as a
+        // place, and its work and card directories.
+        new RegExp(
+          "\\b(?:\\d{2}-)?CONTEXT\\.md\\b|\\bREQUIREMENTS\\.md\\b|\\bPITFALLS\\.md\\b|" +
+            "\\b[Mm]eta[- ]repo\\b|\\b[Uu]mbrella repo\\b|" +
+            "\\bwork/(?:specs|backlog|inbox|archive)/|\\bcards/[a-z-]+\\.md\\b|" +
+            "\\bdecisions?/\\d{4}-[a-z0-9-]+",
+          "g",
+        ),
+      ],
+      positives: [
+        "Roadmap operations/roadmaps/hl7.md and documentation/decisions/0015-x.md",
+        "Locked by CONTEXT.md in the meta-repo, per work/specs/ and cards/hl7.md",
+        "Recorded in decisions/0015-scope.md",
       ],
-      positives: ["Roadmap operations/roadmaps/hl7.md and documentation/decisions/0015-x.md"],
       negatives: [
         "Parser operations are documented in the README, and documentation for the API is generated",
+        "The context and the requirements are in docs-content, and a repo's work is its own",
       ],
     },
     {
@@ -617,6 +697,21 @@ export function resolveConfig(config) {
     }
   }
 
+  const literals = config.sourceStringLiterals ?? { enabled: false };
+  if (!isPlainObject(literals)) {
+    problems.push("axis `sourceStringLiterals` is not an object");
+  } else if (literals.enabled === true) {
+    if (!isStringList(literals.paths) || literals.paths.length === 0) {
+      problems.push(
+        "axis `sourceStringLiterals.paths` is required when the pass is enabled, and must name at " +
+          "least one tracked path. An enabled pass with no paths reads nothing.",
+      );
+    }
+    if (literals.extraRules !== undefined && !Array.isArray(literals.extraRules)) {
+      problems.push("axis `sourceStringLiterals.extraRules` is not a list");
+    }
+  }
+
   if (config.extraRules !== undefined && !Array.isArray(config.extraRules)) {
     problems.push("axis `extraRules` is not a list");
   }
@@ -644,6 +739,11 @@ export function resolveConfig(config) {
         paths: source.enabled === true ? [...source.paths] : [],
         extraRules: source.extraRules === undefined ? [] : [...source.extraRules],
       },
+      sourceStringLiterals: {
+        enabled: literals.enabled === true,
+        paths: literals.enabled === true ? [...literals.paths] : [],
+        extraRules: literals.extraRules === undefined ? [] : [...literals.extraRules],
+      },
       exitCodes: codes,
       extraRules: config.extraRules === undefined ? [] : [...config.extraRules],
       extraSamples: config.extraSamples === undefined ? {} : config.extraSamples,
@@ -1050,10 +1150,260 @@ export function extractDocComments(text, file) {
 // ---------------------------------------------------------------------------
 
 /** A NUL byte is how every text matcher decides a file is not text. Refuse rather than skip it. */
+/** NUL bytes read as spaces in source text, counted so the clean line can say so. */
+let sourceNulBytes = 0;
+
+/**
+ * A source file's text for the two source passes. A NUL byte is legitimate in source (a raw
+ * separator inside a string literal, as deid's HMAC keys and dicom's charset table carry), and it
+ * reads as a SPACE rather than refusing the file or vanishing: a space keeps the word boundary on
+ * either side, so `x<NUL>DEID-77` is still an identifier where deleting the byte would glue it to
+ * the `x`. The public-surface pass still refuses a NUL-bearing target.
+ */
+function sourceText(bytes) {
+  let text = bytes.toString("utf8");
+  if (text.includes("\0")) {
+    sourceNulBytes += text.split("\0").length - 1;
+    text = text.replaceAll("\0", " ");
+  }
+  return text;
+}
+
 function looksBinary(bytes) {
   return bytes.includes(0);
 }
 
+/** Keywords after which a `/` starts a regular expression rather than a division. */
+const REGEX_AFTER_WORDS = new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "case",
+  "do",
+  "else",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "throw",
+  "yield",
+  "await",
+]);
+
+/** Punctuation after which a `/` starts a regular expression rather than a division. */
+const REGEX_AFTER_PUNCTUATION = new Set([..."(,=:[!&|?{};+-*%<>~^"]);
+
+/** The escapes a string literal decodes, so a hit spelled with them is still seen. */
+function decodeLiteral(raw) {
+  let out = "";
+  for (let i = 0; i < raw.length; i += 1) {
+    const ch = raw[i];
+    if (ch !== "\\" || i + 1 >= raw.length) {
+      out += ch;
+      continue;
+    }
+    const next = raw[i + 1];
+    if (next === "u" && raw[i + 2] === "{") {
+      const end = raw.indexOf("}", i + 3);
+      const body = end < 0 ? "" : raw.slice(i + 3, end);
+      if (/^[0-9a-fA-F]{1,6}$/.test(body) && Number.parseInt(body, 16) <= 0x10ffff) {
+        out += String.fromCodePoint(Number.parseInt(body, 16));
+        i = end;
+        continue;
+      }
+    }
+    if (next === "u" && /^[0-9a-fA-F]{4}$/.test(raw.slice(i + 2, i + 6))) {
+      out += String.fromCharCode(Number.parseInt(raw.slice(i + 2, i + 6), 16));
+      i += 5;
+      continue;
+    }
+    if (next === "x" && /^[0-9a-fA-F]{2}$/.test(raw.slice(i + 2, i + 4))) {
+      out += String.fromCharCode(Number.parseInt(raw.slice(i + 2, i + 4), 16));
+      i += 3;
+      continue;
+    }
+    // `\n`, `\t` and the rest of the single-character escapes read as a space: they separate
+    // words in the message a consumer sees. An escaped quote or backslash is itself.
+    out += /[nrtbfv0]/.test(next) ? " " : next === "\n" ? "" : next;
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * Extract the string literals of JavaScript or TypeScript source: double-quoted, single-quoted and
+ * template literals, each decoded. A string literal reaches a consumer as error and warning text,
+ * so it is public surface. A COMMENT IS NEVER READ HERE: a `//` line comment, a trailing one, and a
+ * `/* *\/` block are skipped whole, because a maintainer's note is where an item identifier is
+ * welcome (doc comments are the doc-comment pass's). A template literal's `${...}` reads as a
+ * space and any literal inside it is extracted on its own; a regular-expression literal is
+ * skipped, so a quote inside one is not mistaken for a string.
+ *
+ * IT IS A SCANNER, NOT A PARSER. A `/` after a value is division and after an operator, an opening
+ * bracket or a keyword such as `return` starts a regular expression, which is the rule every
+ * JavaScript tokenizer uses; a source that defeats it is not one this estate writes.
+ *
+ * @param {string} text The source.
+ * @param {string} file Its repo-relative path, for the report.
+ * @returns {{ literals: { text: string, where: string }[], lines: { text: string, where: string }[] }}
+ *   One entry per non-empty literal, and one per source line holding two or more literals, joined
+ *   with a space, so a phrase split across adjacent literals is still seen.
+ */
+export function extractStringLiterals(text, file) {
+  const literals = [];
+  const byLine = new Map();
+  let line = 1;
+  let i = 0;
+
+  const record = (raw, startLine) => {
+    const value = decodeLiteral(raw).replace(/\s+/g, " ").trim();
+    if (value === "") return;
+    literals.push({ text: value, where: `${file}:${startLine}` });
+    const onLine = byLine.get(startLine) ?? [];
+    onLine.push(value);
+    byLine.set(startLine, onLine);
+  };
+
+  /** Lex from `i` until the end, or until the `}` closing a template expression when `inBraces`. */
+  const lex = (inBraces) => {
+    let depth = 0;
+    let prev = "";
+    let prevWord = "";
+    while (i < text.length) {
+      const ch = text[i];
+      if (ch === "\n") {
+        line += 1;
+        i += 1;
+        continue;
+      }
+      if (ch === "/" && text[i + 1] === "/") {
+        while (i < text.length && text[i] !== "\n") i += 1;
+        continue;
+      }
+      if (ch === "/" && text[i + 1] === "*") {
+        i += 2;
+        while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) {
+          if (text[i] === "\n") line += 1;
+          i += 1;
+        }
+        i += 2;
+        continue;
+      }
+      if (ch === '"' || ch === "'") {
+        const start = line;
+        let raw = "";
+        i += 1;
+        while (i < text.length && text[i] !== ch && text[i] !== "\n") {
+          if (text[i] === "\\" && i + 1 < text.length) {
+            if (text[i + 1] === "\n") line += 1;
+            raw += text[i] + text[i + 1];
+            i += 2;
+            continue;
+          }
+          raw += text[i];
+          i += 1;
+        }
+        i += 1;
+        record(raw, start);
+        prev = "v";
+        prevWord = "";
+        continue;
+      }
+      if (ch === "`") {
+        const start = line;
+        let raw = "";
+        i += 1;
+        while (i < text.length && text[i] !== "`") {
+          if (text[i] === "\\" && i + 1 < text.length) {
+            if (text[i + 1] === "\n") line += 1;
+            raw += text[i] + text[i + 1];
+            i += 2;
+            continue;
+          }
+          if (text[i] === "$" && text[i + 1] === "{") {
+            i += 2;
+            lex(true);
+            raw += " ";
+            continue;
+          }
+          if (text[i] === "\n") line += 1;
+          raw += text[i];
+          i += 1;
+        }
+        i += 1;
+        record(raw, start);
+        prev = "v";
+        prevWord = "";
+        continue;
+      }
+      if (
+        ch === "/" &&
+        (prev === "" || REGEX_AFTER_PUNCTUATION.has(prev) || REGEX_AFTER_WORDS.has(prevWord))
+      ) {
+        // A regular-expression literal: up to the unescaped `/` outside a character class.
+        let inClass = false;
+        i += 1;
+        while (i < text.length && text[i] !== "\n") {
+          if (text[i] === "\\") {
+            i += 2;
+            continue;
+          }
+          if (text[i] === "[") inClass = true;
+          else if (text[i] === "]") inClass = false;
+          else if (text[i] === "/" && !inClass) break;
+          i += 1;
+        }
+        i += 1;
+        while (i < text.length && /[A-Za-z]/.test(text[i])) i += 1;
+        prev = "v";
+        prevWord = "";
+        continue;
+      }
+      if (/\s/.test(ch)) {
+        i += 1;
+        continue;
+      }
+      if (/[A-Za-z_$]/.test(ch)) {
+        let word = "";
+        while (i < text.length && /[\w$]/.test(text[i])) {
+          word += text[i];
+          i += 1;
+        }
+        prev = "v";
+        prevWord = word;
+        continue;
+      }
+      if (/[0-9]/.test(ch)) {
+        while (i < text.length && /[\w.]/.test(text[i])) i += 1;
+        prev = "v";
+        prevWord = "";
+        continue;
+      }
+      if (inBraces) {
+        if (ch === "{") depth += 1;
+        if (ch === "}") {
+          if (depth === 0) {
+            i += 1;
+            return;
+          }
+          depth -= 1;
+        }
+      }
+      prev = ch === ")" || ch === "]" || ch === "}" ? "v" : ch;
+      prevWord = "";
+      i += 1;
+    }
+  };
+
+  lex(false);
+  const lines = [];
+  for (const [startLine, values] of byLine) {
+    if (values.length > 1) lines.push({ text: values.join(" "), where: `${file}:${startLine}` });
+  }
+  return { literals, lines };
+}
+
 /**
  * Run the internal-reference gate and return an exit code drawn from `config.exitCodes`.
  *
@@ -1064,6 +1414,7 @@ function looksBinary(bytes) {
  * @returns {number} `exitCodes.clean`, `exitCodes.hits` or `exitCodes.refuse`.
  */
 export function runInternalRefsScan(config) {
+  sourceNulBytes = 0;
   const writeOut = config?.write?.out ?? ((s) => process.stdout.write(s));
   const writeErr = config?.write?.err ?? ((s) => process.stderr.write(s));
 
@@ -1305,14 +1656,8 @@ export function runInternalRefsScan(config) {
             "could not open its input.",
         );
       }
-      if (looksBinary(read.bytes)) {
-        return refuse(
-          `tracked source file ${rel} holds a NUL byte, so a text matcher classifies it as ` +
-            "binary. Refusing to report green over input it cannot read.",
-        );
-      }
       sourceFiles += 1;
-      const extracted = extractDocComments(read.bytes.toString("utf8"), rel);
+      const extracted = extractDocComments(sourceText(read.bytes), rel);
       docLines.push(...extracted.lines);
       docParagraphs.push(...extracted.paragraphs);
     }
@@ -1325,6 +1670,78 @@ export function runInternalRefsScan(config) {
     scanDocComments(docLines, docParagraphs, sourceRules, hits);
   }
 
+  // The source string-literal pass, when the caller has enabled it.
+  let literalFiles = 0;
+  if (resolved.sourceStringLiterals.enabled) {
+    const literalRules = [...rules];
+    let index = 0;
+    for (const rule of resolved.sourceStringLiterals.extraRules) {
+      const compiled = compileExtraRule(rule, index);
+      index += 1;
+      if (compiled.rule === undefined) {
+        return refuse(
+          "a source string-literal rule was refused:\n" +
+            compiled.problems
+              .map((p) => `       ${p}\n`)
+              .join("")
+              .trimEnd(),
+        );
+      }
+      literalRules.push(compiled.rule);
+    }
+    const literalSelfTest = runSelfTests(literalRules);
+    if (literalSelfTest.length > 0) {
+      return refuse(
+        "SELF-TEST FAILED for the source string-literal pass:\n" +
+          literalSelfTest
+            .map((f) => `       ${f}\n`)
+            .join("")
+            .trimEnd(),
+      );
+    }
+
+    const literalTracked = trackedEntriesUnder(root, resolved.sourceStringLiterals.paths);
+    if (literalTracked === null || literalTracked.length === 0) {
+      return refuse(
+        `no tracked source files under ${resolved.sourceStringLiterals.paths.join(", ")} to scan ` +
+          "for string literals. Either the source moved (update `sourceStringLiterals.paths`, " +
+          "deliberately) or the scan is about to cover less than it claims.",
+      );
+    }
+    const literalEntries = [];
+    const joinedEntries = [];
+    for (const entry of literalTracked) {
+      const rel = entry.path;
+      const verdict = classifyTrackedMode(entry.mode);
+      if (verdict === "skip") continue;
+      if (verdict === "refuse") {
+        return refuse(
+          `tracked source entry ${rel} has mode ${entry.mode}, which names nothing this scan can ` +
+            "read. Refusing to report green from a scan that skipped one of its inputs.",
+        );
+      }
+      const read = readTarget(join(root, rel));
+      if (read.error !== undefined) {
+        return refuse(
+          `tracked source file ${rel} ${read.error}. Refusing to report green from a scan that ` +
+            "could not open its input.",
+        );
+      }
+      literalFiles += 1;
+      const extracted = extractStringLiterals(sourceText(read.bytes), rel);
+      literalEntries.push(...extracted.literals);
+      joinedEntries.push(...extracted.lines);
+    }
+    if (literalEntries.length === 0) {
+      return refuse(
+        `extracted no string literals from ${literalFiles} tracked source file(s). A source tree ` +
+          "with no string literal at all is not one this estate writes, so an empty extraction " +
+          "means the extractor is broken, not that the source is clean.",
+      );
+    }
+    scanStringLiterals(literalEntries, joinedEntries, literalRules, hits);
+  }
+
   if (hits.length > 0) {
     writeErr(report(hits));
     return resolved.exitCodes.hits;
@@ -1336,6 +1753,10 @@ export function runInternalRefsScan(config) {
       (resolved.sourceDocComments.enabled
         ? `; ${sourceFiles} source file(s) scanned for doc-comment bookkeeping`
         : "") +
+      (resolved.sourceStringLiterals.enabled
+        ? `; ${literalFiles} source file(s) scanned for string-literal bookkeeping`
+        : "") +
+      (sourceNulBytes > 0 ? `; ${sourceNulBytes} NUL byte(s) in source read as spaces` : "") +
       `; ${gitlinks} gitlink(s) skipped)\n`,
   );
   return resolved.exitCodes.clean;
@@ -1390,6 +1811,31 @@ function scanDocComments(docLines, docParagraphs, rules, hits) {
   }
 }
 
+/** Scan extracted string literals, one by one and then joined per source line. */
+function scanStringLiterals(literals, joined, rules, hits) {
+  for (const rule of rules) {
+    const located = new Set();
+    for (const entry of literals) {
+      const found = firstMatch(rule, entry.text);
+      if (found === null) continue;
+      located.add(entry.where);
+      hits.push({
+        rule: rule.name,
+        file: entry.where,
+        line: null,
+        text: entry.text,
+        literal: true,
+      });
+    }
+    for (const entry of joined) {
+      const found = firstMatch(rule, entry.text);
+      if (found === null || located.has(entry.where)) continue;
+      located.add(entry.where);
+      hits.push({ rule: rule.name, file: entry.where, line: null, text: found, literal: true });
+    }
+  }
+}
+
 /** The hit report: every finding names its file, its line where it has one, and its rule. */
 function report(hits) {
   const lines = [];
@@ -1398,6 +1844,7 @@ function report(hits) {
     const label =
       `[${hit.rule}` +
       (hit.source ? " / src doc comment" : "") +
+      (hit.literal ? " / src string literal" : "") +
       (hit.wrapped ? " / wrapped across lines" : "") +
       "]";
     lines.push(`${label} ${where}: ${hit.text}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosyte/script-utils",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Zero-dependency helpers for the repo-local gate scripts in @cosyte/* repos.",
   "keywords": [
     "cli",

package/phi-scan.d.ts

@@ -296,3 +296,14 @@ export declare function readPhiExclusions(
  * `node node_modules/@cosyte/script-utils/phi-scan.js [--staged | <path>...]`.
  */
 export declare function runPhiScanCli(argv: string[]): number;
+
+/** Whether a repo-relative path is a JavaScript or TypeScript source, a container of literals. */
+export declare function isSourceLiteralContainer(relPath: string): boolean;
+
+/**
+ * Decode JavaScript and TypeScript string-literal escapes over a whole source (`\u002D`, `\u{2D}`,
+ * `\x2D`, `\n` and the rest), an escaped backslash first, so the document a literal spells can be
+ * scanned. A view, not a parser: it also decodes a `String.raw` template and a comment quoting an
+ * escape.
+ */
+export declare function decodeSourceLiterals(text: string): string;