turva-llms-txt-validator 0.3.8 → 0.3.9

package/README.md

@@ -54,7 +54,7 @@ Use JSON for automation and strict mode when warnings should fail a CI step:
 npx --yes turva-llms-txt-validator example.com --json --strict
 ```
 
-Completed validation returns `{ target, summary, checks }`. Each check contains `{ id, status, label, detail }`. With `--json`, input and fetch errors return `{ "error": "..." }` and exit with code `2`. An unknown option, a second domain and a missing domain are input errors too, and `--help` exits with code `0`.
+Completed validation returns `{ target, summary, checks }`. Each check contains `{ id, status, label, detail }`. With `--json`, input and fetch errors return `{ "error": "...", "target": "..." }` and exit with code `2`. The target is the address given on the command line, with any user name, password and query value masked, and a network error adds `code`, such as `EAI_AGAIN`. An unknown option, a second domain and a missing domain are input errors too. `--help` exits with code `0`, and `--version` or `-V` prints the installed version and exits with code `0`.
 
 ## What it checks
 

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,40 @@
+# Third-party notices
+
+This package's own license is MIT, in `LICENSE`. The named character reference
+table in `src/index.mjs` (`NAMED_REFERENCE_DATA`) is generated from data
+published by a third-party package and carries that package's own license
+below. This is a build-time data source, not an installed runtime dependency:
+the table is generated once and copied into `src/index.mjs`, so no reference
+to it appears in `package.json` or in the dependency tree an installer sees.
+
+## character-entities
+
+- Package: `character-entities`
+- Version used to generate the table: 2.0.2
+- URL: <https://github.com/wooorm/character-entities>
+- License: MIT
+
+```
+(The MIT License)
+
+Copyright (c) 2015 Titus Wormer <tituswormer@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```

package/bin/cli.mjs

@@ -4,15 +4,18 @@
 // or bad input. The two v2 discovery checks and the input-path note carry status
 // "info" and move no exit code, by design. Same checks and JSON shape as the hosted validator:
 // curl -H "Accept: application/json" "https://turva.dev/llms-txt-validator?url=example.com"
-import { validateHost, stripControls } from "../src/index.mjs";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { validateHost, stripControls, maskLocation } from "../src/index.mjs";
 
 const USAGE = [
   "usage: llms-txt-validate <domain-or-url> [--json] [--strict]",
-  "  --json    print the result as JSON (same shape as the hosted validator)",
-  "  --strict  exit 1 on warnings too, for CI gates",
-  "  --help    print this help"
+  "  --json     print the result as JSON (same shape as the hosted validator)",
+  "  --strict   exit 1 on warnings too, for CI gates",
+  "  --help     print this help",
+  "  --version  print the installed version and exit"
 ];
-const KNOWN = new Set(["--json", "--strict", "--help", "-h"]);
+const KNOWN = new Set(["--json", "--strict", "--help", "-h", "--version", "-V"]);
 
 // The arguments are read strictly since 0.3.8 (Tek-496). An unknown flag such as a misspelled
 // --strcit used to be ignored, so a CI step ran without the gate it asked for, and a second
@@ -36,6 +39,15 @@ if (flags.includes("--help") || flags.includes("-h")) {
   for (const line of USAGE) console.log(line);
   process.exit(0);
 }
+if (flags.includes("--version") || flags.includes("-V")) {
+  // Read package.json relative to this file, not the caller's cwd, so this works the same
+  // whether the CLI runs installed, linked or through npx (V-04, outside audit 2026-09-26).
+  // No network read: the version is the one actually installed, not the npm registry's latest.
+  const pkgUrl = new URL("../package.json", import.meta.url);
+  const pkg = JSON.parse(readFileSync(fileURLToPath(pkgUrl), "utf8"));
+  console.log(pkg.version);
+  process.exit(0);
+}
 const unknown = flags.find((f) => !KNOWN.has(f));
 if (unknown) fail("unknown option " + JSON.stringify(stripControls(unknown).slice(0, 40)));
 if (targets.length === 0 || targets[0].trim() === "") fail("no domain or URL given");
@@ -61,7 +73,19 @@ try {
   // The hosted validator answers every failure as JSON when JSON was asked for, so a CI
   // step that parses --json output gets {"error": ...} here too instead of an empty stdout
   // and a plain-text stderr (round 16 S3-3). The exit code is unchanged.
-  if (json) console.log(JSON.stringify({ error: message }, null, 2));
-  else console.error("error: " + message);
+  //
+  // target and code are added as separate fields (V-05, outside audit 2026-09-26): a bare
+  // {"error": message} left a CI step unable to tell which target failed or why without
+  // parsing free text. code reads a network error's cause first (undici wraps the real
+  // errno code, such as EAI_AGAIN or ECONNREFUSED, in err.cause.code) and falls back to
+  // err.code for an error that sets it directly; it is omitted, not null, when neither is set.
+  // target goes through maskLocation like every other address the tool prints, so a user name,
+  // a password or a query value typed into the command line is never echoed back.
+  const code = (err && err.cause && err.cause.code) || (err && err.code);
+  if (json) {
+    const report = { error: message, target: stripControls(maskLocation(targets[0])) };
+    if (code) report.code = stripControls(String(code));
+    console.log(JSON.stringify(report, null, 2));
+  } else console.error("error: " + message);
   process.exit(2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turva-llms-txt-validator",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Validate a site's llms.txt structure: eight checks as pass/warn/fail plus two llms.txt v2 discovery checks that read pass or info and never move the summary, JSON output. Same checks as the hosted validator at turva.dev/llms-txt-validator.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -12,7 +12,8 @@
     "src",
     "bin",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "scripts": {
     "test": "node --test"

package/src/index.mjs

@@ -454,7 +454,11 @@ export function validateLlmsTxt(f) {
     add("h1-title", "fail", "Starts with an H1 title", "the first non-empty line should be a markdown H1 (# Site name)");
   }
   const afterH1 = lines.slice(firstIdx + 1).find((l) => l.trim() !== "") || "";
-  if (afterH1.trim().startsWith("> ")) {
+  // Read the same way as the H1 check and the "late" blockquote search below: at most three
+  // leading spaces, per CommonMark. A trim-first prefix test used to erase the difference, so
+  // a four-space or tab-indented code block right after the title passed as the summary until
+  // 2026-09-27 (Tek-496, mirrored from worker.js).
+  if (/^ {0,3}> /.test(afterH1)) {
     add("summary", "pass", "Blockquote summary after the title", JSON.stringify(cut(afterH1.trim(), 80)));
   } else {
     // A blockquote further down, before the first H2, is a summary in the wrong place and not a
@@ -679,8 +683,11 @@ var C1_REPLACEMENTS = {
 
 // The full WHATWG list of named character references, 2 231 names: "name!hex" is a name that
 // also decodes without its ";", "name=hex" one that needs it, and several code points are
-// separated by ",". Generated 2026-09-12 from the character-entities package, with every value
-// and every legacy name checked against the decoder of the entities package.
+// separated by ",". Generated 2026-09-12 from character-entities 2.0.2
+// (https://github.com/wooorm/character-entities), (c) 2015 Titus Wormer, MIT, with every value
+// and every legacy name checked against the decoder of the entities package. The full license
+// text is in THIRD-PARTY-NOTICES.md (E01, outside audit 2026-09-26); this is a build-time data
+// source copied in at generation time, not an installed runtime dependency.
 var NAMED_REFERENCE_DATA =
   "AElig!c6 AMP!26 Aacute!c1 Abreve=102 Acirc!c2 Acy=410 Afr=1d504 Agrave!c0 Alpha=391 Amacr=100 " +
   "And=2a53 Aogon=104 Aopf=1d538 ApplyFunction=2061 Aring!c5 Ascr=1d49c Assign=2254 Atilde!c3 " +