doc-detective 4.29.1 → 4.30.0

package/dist/lsp/yaml/positions.js

@@ -0,0 +1,92 @@
+import YAML from "yaml";
+import { instancePathToSegments, pointerFromPath } from "../json/positions.js";
+/** Parse YAML into a position-preserving document plus its plain JS value. */
+export function parseYamlTree(text) {
+    const doc = YAML.parseDocument(text, { keepSourceTokens: true });
+    // `toJS()` resolves aliases and can throw on a pathological document (the
+    // "billion laughs" alias bomb the yaml lib guards with maxAliasCount). Catch
+    // it so a malicious/degenerate buffer can't crash the server — surface it as
+    // a document-level error instead.
+    try {
+        return { doc, value: doc.toJS() };
+    }
+    catch (error) {
+        /* c8 ignore next - the yaml lib always throws an Error with a message; the String() fallback guards a hypothetical non-Error throw */
+        const message = error instanceof Error ? error.message : String(error);
+        return { doc, value: undefined, valueError: message };
+    }
+}
+/** Collect YAML syntax errors as offset spans (empty when the doc is clean). */
+export function yamlSyntaxErrors(doc) {
+    return doc.errors.map((error) => {
+        const [start, end] = error.pos;
+        return { range: { start, end }, message: error.message };
+    });
+}
+/** Node range → OffsetRange, using [start, valueEnd] for a tight span. */
+function nodeRange(node) {
+    const range = node?.range;
+    if (!Array.isArray(range))
+        return null;
+    return { start: range[0], end: range[1] };
+}
+/**
+ * Resolve the source span for an AJV `instancePath` in a YAML document. Walks
+ * up to the nearest present ancestor (like the JSON resolver) so a
+ * `required`-style error still anchors somewhere. Returns null only when even
+ * the document contents can't be located.
+ */
+export function rangeForInstancePathYaml(doc, instancePath) {
+    const segments = instancePathToSegments(instancePath);
+    for (let end = segments.length; end >= 0; end--) {
+        const node = end === 0 ? doc.contents : doc.getIn(segments.slice(0, end), true);
+        const range = nodeRange(node);
+        if (range)
+            return range;
+    }
+    // Reached only for an empty document (no contents node has a range).
+    return null;
+}
+/**
+ * Find every step written as a map carrying an `action` key inside a `steps`
+ * sequence — the YAML twin of the JSON detector. Returns the offending `action`
+ * key span and the step's JSON-Pointer.
+ */
+export function findActionKeyedStepsYaml(doc) {
+    const found = [];
+    const visit = (node, path) => {
+        if (YAML.isMap(node)) {
+            for (const pair of node.items) {
+                const key = pair.key?.value;
+                if (key === "steps" && YAML.isSeq(pair.value)) {
+                    collectSteps(pair.value, [...path, "steps"]);
+                }
+                if (pair.value)
+                    visit(pair.value, [...path, key]);
+            }
+        }
+        else if (YAML.isSeq(node)) {
+            node.items.forEach((item, index) => visit(item, [...path, index]));
+        }
+    };
+    const collectSteps = (seq, seqPath) => {
+        seq.items.forEach((item, index) => {
+            if (!YAML.isMap(item))
+                return;
+            const actionPair = item.items.find((p) => p.key?.value === "action");
+            if (actionPair) {
+                const range = nodeRange(actionPair.key);
+                if (range) {
+                    found.push({
+                        keyRange: range,
+                        pointer: pointerFromPath([...seqPath, index]),
+                    });
+                }
+            }
+        });
+    };
+    if (doc.contents)
+        visit(doc.contents, []);
+    return found;
+}
+//# sourceMappingURL=positions.js.map

package/dist/lsp/yaml/positions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"positions.js","sourceRoot":"","sources":["../../../src/lsp/yaml/positions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "doc-detective",
-  "version": "4.29.1",
+  "version": "4.30.0",
   "description": "Treat doc content as testable assertions to validate doc accuracy and product UX.",
   "bin": {
     "doc-detective": "bin/doc-detective.js",
-    "doc-detective-runner": "bin/runner-entrypoint.js"
+    "doc-detective-runner": "bin/runner-entrypoint.js",
+    "doc-detective-lsp": "bin/doc-detective-lsp.js"
   },
   "type": "module",
   "engines": {
@@ -86,8 +87,11 @@
     "fast-xml-parser": "^5.9.3",
     "jq-web": "^0.6.2",
     "json-schema-faker": "^0.6.2",
+    "jsonc-parser": "^3.3.1",
     "posthog-node": "^5.38.6",
     "tree-kill": "^1.2.2",
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.12",
     "yaml": "^2.9.0",
     "yargs": "^18.0.0"
   },

package/scripts/postinstall.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -16,11 +16,154 @@ const CLI_PATH = path.join(__dirname, "..", "bin", "doc-detective.js");
 //      DOC_DETECTIVE_AUTOINSTALL=0.
 //   2. maybePromptInstallAgents(): the optional agent-tools install prompt —
 //      lightweight (TTY-gated, time-bounded, skipped in CI).
+//
+// Both are skipped for a first-time install triggered solely to run the
+// language server (`npx doc-detective lsp`): the LSP needs none of the heavy
+// runtime, so pre-warming browsers/drivers there is pure waste. The runtime
+// still lazy-installs on the first actual test run if one ever happens.
 async function main() {
+  if (isLspInvocation()) return;
   await maybeInstallRuntime();
   await maybePromptInstallAgents();
 }
 
+// --- LSP-invocation detection -----------------------------------------------
+
+/**
+ * Does this command line invoke `doc-detective lsp`? Matches the package name
+ * plus a standalone `lsp` argument, covering `npx doc-detective lsp`,
+ * `npx --yes doc-detective lsp --stdio`, and `node …/bin/doc-detective.js lsp`.
+ * The `\blsp\b`-as-a-word check avoids false hits like a `lsp-…` path segment.
+ * Exported for tests.
+ */
+export function isDocDetectiveLspCommand(cmdline) {
+  if (typeof cmdline !== "string") return false;
+  return /doc-detective/i.test(cmdline) && /(^|\s)lsp(\s|$)/.test(cmdline);
+}
+
+/**
+ * Read the process table (pid → { ppid, cmd }) for the current platform. On
+ * Linux this reads `/proc` directly (no child process); elsewhere it makes a
+ * single `powershell`/`ps` call. Best-effort — the caller wraps it in a guard.
+ * `deps.readProcessTable` overrides the real reader for tests.
+ */
+function buildProcessTable(platform, deps = {}) {
+  if (deps.readProcessTable) return deps.readProcessTable();
+
+  if (platform === "win32") {
+    const json = execFileSync(
+      "powershell",
+      [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine | ConvertTo-Json -Compress",
+      ],
+      {
+        encoding: "utf8",
+        timeout: 5000,
+        // A busy host's full process list (with command lines) can be large;
+        // raise the buffer well past the 1 MB default so the read doesn't abort.
+        maxBuffer: 32 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+      },
+    );
+    const parsed = JSON.parse(json);
+    const rows = Array.isArray(parsed) ? parsed : [parsed];
+    const table = new Map();
+    for (const row of rows) {
+      table.set(Number(row.ProcessId), {
+        ppid: Number(row.ParentProcessId),
+        cmd: row.CommandLine || "",
+      });
+    }
+    return table;
+  }
+
+  if (platform === "linux") {
+    const table = new Map();
+    for (const name of fs.readdirSync("/proc")) {
+      if (!/^\d+$/.test(name)) continue;
+      try {
+        // `/proc/<pid>/stat`: the ppid is the 2nd field AFTER the `(comm)`
+        // parenthesized name, which itself can contain spaces/parens.
+        const stat = fs.readFileSync(`/proc/${name}/stat`, "utf8");
+        const afterComm = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+        const ppid = Number(afterComm[1]);
+        let cmd = "";
+        try {
+          cmd = fs
+            .readFileSync(`/proc/${name}/cmdline`)
+            .toString()
+            .replace(/\0/g, " ")
+            .trim();
+        } catch {
+          /* process vanished / no cmdline (kernel thread) */
+        }
+        table.set(Number(name), { ppid, cmd });
+      } catch {
+        /* process vanished between readdir and read */
+      }
+    }
+    return table;
+  }
+
+  // macOS and other Unixes. `-ww` disables ps's default command-line
+  // truncation (otherwise a long path can cut off the `lsp` token before the
+  // matcher ever sees it); maxBuffer guards a busy host's large process list.
+  const out = execFileSync("ps", ["-A", "-ww", "-o", "pid=,ppid=,command="], {
+    encoding: "utf8",
+    timeout: 5000,
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  const table = new Map();
+  for (const line of out.split(/\r?\n/)) {
+    const m = line.match(/^\s*(\d+)\s+(\d+)\s+(.*)$/);
+    if (m) table.set(Number(m[1]), { ppid: Number(m[2]), cmd: m[3] });
+  }
+  return table;
+}
+
+/**
+ * Walk the ancestry from `deps.pid` (default this process) up the parent chain
+ * and return each ancestor's command line. Bounded and cycle-guarded. Never
+ * throws — returns `[]` on any failure so callers fall back to default
+ * behavior. Exported for tests.
+ */
+export function readAncestorCommandLines(deps = {}) {
+  const platform = deps.platform || process.platform;
+  let pid = deps.pid || process.pid;
+  try {
+    const table = buildProcessTable(platform, deps);
+    const lines = [];
+    const seen = new Set();
+    for (let hops = 0; hops < 12 && pid && !seen.has(pid); hops++) {
+      seen.add(pid);
+      const entry = table.get(pid);
+      if (!entry) break;
+      if (entry.cmd) lines.push(entry.cmd);
+      pid = entry.ppid;
+    }
+    return lines;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Is this postinstall running as part of `npx doc-detective lsp`? Only an
+ * `npm exec` (npx) invocation can be an lsp-first-use, so a plain
+ * `npm install` / Docker build returns `false` immediately without walking the
+ * process tree (they always pre-warm). For npx, inspect the ancestry for a
+ * `doc-detective lsp` command. `ancestorLines` is injectable for tests.
+ * Exported for tests.
+ */
+export function isLspInvocation(env = process.env, ancestorLines) {
+  if (env.npm_command !== "exec") return false;
+  const lines = ancestorLines || readAncestorCommandLines();
+  return lines.some(isDocDetectiveLspCommand);
+}
+
 // Only run the install steps when executed as the npm lifecycle script, not
 // when a test imports this module for the exported pure helpers below.
 function isInvokedDirectly() {