@hadden-industries/markdown-quality 1.0.1 → 1.0.3

package/src/literal-layout.js

@@ -4,10 +4,12 @@ import * as prettier from "prettier";
 import { parse } from "./analysis.js";
 import { fail } from "./contracts.js";
 
-// embeddedLanguageFormatting: off still allows Prettier to trim code-line
-// whitespace. Keep those lines nonempty until layout finishes, then remove the
-// absent marker before native analysis or the unchanged semantic guard runs.
-export async function formatLayout(text, options) {
+/** Return split-array code-body row indices, optionally collecting empty indented rows. */
+export function codeBodyRows(
+  text,
+  tree = parse(text),
+  emptyIndentedRows = null,
+) {
   const rows = text.split(/(\r\n|\r|\n)/u);
   const selected = new Set();
   function visit(node, quoteDepth = 0) {
@@ -45,20 +47,52 @@ export async function formatLayout(text, options) {
       const endLine =
         node.position.end.line -
         (closed || node.position.end.column === 1 ? 1 : 0);
+      const valueRows =
+        !opening && emptyIndentedRows ? node.value.split(/\r\n|\r|\n/u) : null;
       for (
         let line = node.position.start.line - (opening ? 0 : 1);
         line < endLine;
         line++
-      )
-        if (
-          rows[line * 2] !== undefined &&
-          (rows[line * 2] === "" || /\s$/u.test(rows[line * 2]))
-        )
-          selected.add(line * 2);
+      ) {
+        if (rows[line * 2] !== undefined) selected.add(line * 2);
+        if (valueRows?.[line - node.position.start.line + 1] === "")
+          emptyIndentedRows.add(line * 2);
+      }
     }
     for (const child of node.children ?? []) visit(child, quoteDepth);
   }
-  visit(parse(text));
+  visit(tree);
+  return selected;
+}
+
+// embeddedLanguageFormatting: off still allows Prettier to trim code-line
+// whitespace. Keep those lines nonempty until layout finishes, then remove the
+// absent marker before native analysis or the unchanged semantic guard runs.
+export async function formatLayout(text, options, memo) {
+  return memo
+    ? memo.layout(text, options, () =>
+        protectLiteralLayout(text, options, memo),
+      )
+    : protectLiteralLayout(text, options);
+}
+
+async function protectLiteralLayout(text, options, memo) {
+  const rows = text.split(/(\r\n|\r|\n)/u);
+  const emptyIndentedRows = new Set();
+  const codeRows = codeBodyRows(
+    text,
+    memo ? memo.parse(text) : parse(text),
+    emptyIndentedRows,
+  );
+  const selected = new Set(
+    [...codeRows].filter(
+      // An empty indented-code value needs no protection. A marker without its
+      // missing indentation would become prose and split the code block.
+      (line) =>
+        !emptyIndentedRows.has(line) &&
+        (rows[line] === "" || /\s$/u.test(rows[line])),
+    ),
+  );
   if (!selected.size) return prettier.format(text, options);
   let marker;
   for (let code = 0xe000; code < 0xe100; code++) {

package/src/native-checks.js

@@ -0,0 +1,247 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+import { runNative } from "./native-tool.js";
+import { spawnSync } from "node:child_process";
+import { lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { decode, fail, limits } from "./contracts.js";
+import {
+  removeStagedFile,
+  nativeCheckConfig,
+  verifyNativeStaging,
+  writeStagedFile,
+} from "./native-staging.js";
+
+/** Bind an admitted check to its exact bytes, executable identity and owned policy. */
+export function bindNativeCheck(tool, input, report) {
+  return {
+    input,
+    toolSha256: tool.sha256,
+    configuration: nativeCheckConfig,
+    report,
+  };
+}
+export function matchesNativeCheck(tool, input, check) {
+  return (
+    check?.input === input &&
+    check.toolSha256 === tool.sha256 &&
+    check.configuration === nativeCheckConfig &&
+    typeof check.report?.wouldReformat === "boolean" &&
+    Array.isArray(check.report.diagnostics)
+  );
+}
+function reportBound(text, staging) {
+  return (
+    3200 * text.split("\n").length +
+    512 +
+    (staging
+      ? Buffer.byteLength(JSON.stringify(join(staging.path, "input-31.md")))
+      : 0)
+  );
+}
+/** Avoid speculative checking where the qualified file protocol cannot apply. */
+export function nativeFileCheckEligible(text, staging) {
+  return (
+    Boolean(staging) &&
+    Buffer.byteLength(text) <= limits.fileBytes &&
+    reportBound(text, staging) + 2 <= limits.nativeOutputBytes
+  );
+}
+
+/** Check bounded exact snapshots; partition before invocation, never retry failed groups. */
+export function runNativeChecks(tool, texts, staging, observer) {
+  const results = [];
+  let pending = [],
+    bound = 2,
+    bytes = 0;
+  function observe(indices, operation) {
+    observer?.start(indices);
+    const started = performance.now();
+    try {
+      return operation();
+    } finally {
+      observer?.finish(indices, performance.now() - started);
+    }
+  }
+  function flush() {
+    if (!pending.length) return;
+    const group = pending;
+    pending = [];
+    bound = 2;
+    bytes = 0;
+    results.push(
+      ...observe(
+        group.map((item) => item.index),
+        () =>
+          checkFiles(
+            tool,
+            group.map((item) => item.text),
+            staging,
+          ),
+      ),
+    );
+  }
+  for (const [index, text] of texts.entries()) {
+    const inputBytes = Buffer.byteLength(text);
+    if (inputBytes > limits.fileBytes)
+      fail("DOCUMENT_LIMIT", "Native input exceeds the size limit.");
+    // Pinned check.rs emits at most two retained findings per source line and
+    // at most 203 excerpt characters. Include worst JSON escaping, pretty-print
+    // overhead and the complete staged pathname; keep large cases on stdin.
+    const outputBound = reportBound(text, staging);
+    if (!staging || outputBound + 2 > limits.nativeOutputBytes) {
+      flush();
+      results.push(
+        observe([index], () => ({
+          diagnostics: runNative(tool, text, true),
+          wouldReformat: null,
+        })),
+      );
+      continue;
+    }
+    if (
+      pending.length === 32 ||
+      bytes + inputBytes > 4_194_304 ||
+      bound + outputBound > limits.nativeOutputBytes
+    )
+      flush();
+    pending.push({ index, text });
+    bytes += inputBytes;
+    bound += outputBound;
+  }
+  flush();
+  return results;
+}
+
+function checkFiles(tool, texts, staging) {
+  verifyNativeStaging(staging);
+  const files = [];
+  try {
+    for (const [index, text] of texts.entries())
+      files.push(writeStagedFile(staging, `input-${index}.md`, text));
+    verifyNativeStaging(staging);
+    for (const [index, file] of files.entries()) {
+      const stat = lstatSync(file.path, { bigint: true });
+      if (
+        !stat.isFile() ||
+        stat.isSymbolicLink() ||
+        stat.nlink !== 1n ||
+        Object.keys(file.identity).some(
+          (key) => stat[key] !== file.identity[key],
+        ) ||
+        stat.size !== BigInt(Buffer.byteLength(texts[index])) ||
+        readFileSync(file.path, "utf8") !== texts[index]
+      )
+        fail("NATIVE_STAGING", "Private native input changed before checking.");
+    }
+    const result = spawnSync(
+      tool.executable,
+      [
+        "--native",
+        "--config",
+        join(staging.path, "snapper-check.toml"),
+        "--format",
+        "markdown",
+        "--max-width",
+        "0",
+        "--color",
+        "never",
+        "--check",
+        "--output-format",
+        "json",
+        ...files.map((file) => file.path),
+      ],
+      {
+        cwd: fileURLToPath(new URL("../assets/", import.meta.url)),
+        env: {
+          ...Object.fromEntries(
+            ["SystemRoot", "WINDIR", "TEMP", "TMP", "LANG", "LC_ALL"]
+              .filter((key) => process.env[key])
+              .map((key) => [key, process.env[key]]),
+          ),
+          RAYON_NUM_THREADS: "1",
+        },
+        shell: false,
+        timeout: limits.nativeMs,
+        maxBuffer: limits.nativeOutputBytes,
+        windowsHide: true,
+      },
+    );
+    return readReports(result, files, texts);
+  } finally {
+    for (const file of files) removeStagedFile(staging, file);
+  }
+}
+
+function readReports(result, files, texts) {
+  if (result.error || result.signal || ![0, 1].includes(result.status))
+    fail("NATIVE_FAILURE", "Native check failed or exceeded resource limits.");
+  let reports;
+  try {
+    reports = JSON.parse(decode(result.stdout));
+  } catch {
+    fail("NATIVE_REPORT", "Malformed native JSON.");
+  }
+  if (!Array.isArray(reports) || reports.length > files.length)
+    fail("NATIVE_REPORT", "Invalid native group report.");
+  // Source/binary fixtures qualify omitted clean records: every eligible owned
+  // file is processed before JSON is emitted, and all I/O failures exit fatally.
+  const checked = texts.map(() => ({ diagnostics: [], wouldReformat: false }));
+  const paths = new Map(files.map((file, index) => [file.path, index]));
+  const seen = new Set();
+  for (const report of reports) {
+    if (
+      !report ||
+      typeof report !== "object" ||
+      Array.isArray(report) ||
+      Object.keys(report).length !== 5 ||
+      !paths.has(report.file) ||
+      seen.has(report.file)
+    )
+      fail("NATIVE_REPORT", "Invalid native group attribution.");
+    const index = paths.get(report.file),
+      text = texts[index];
+    const sourceLines =
+      text === "" ? 0 : text.split("\n").length - Number(text.endsWith("\n"));
+    if (
+      report.original_lines !== sourceLines ||
+      !Number.isSafeInteger(report.formatted_lines) ||
+      report.formatted_lines < 0 ||
+      report.formatted_lines > limits.nativeOutputBytes ||
+      typeof report.would_reformat !== "boolean" ||
+      !Array.isArray(report.diagnostics) ||
+      (!report.would_reformat && !report.diagnostics.length)
+    )
+      fail("NATIVE_REPORT", "Invalid native group coverage.");
+    seen.add(report.file);
+    const findings = new Set();
+    for (const diagnostic of report.diagnostics) {
+      if (
+        !diagnostic ||
+        Object.keys(diagnostic).length !== 3 ||
+        !["fused", "wrap", "long"].includes(diagnostic.kind) ||
+        !Number.isSafeInteger(diagnostic.line) ||
+        diagnostic.line < 1 ||
+        diagnostic.line > sourceLines ||
+        typeof diagnostic.excerpt !== "string" ||
+        [...diagnostic.excerpt].length > 203 ||
+        findings.has(`${diagnostic.kind}:${diagnostic.line}`)
+      )
+        fail("NATIVE_REPORT", "Invalid or unknown native diagnostic.");
+      findings.add(`${diagnostic.kind}:${diagnostic.line}`);
+      if (diagnostic.kind !== "long")
+        checked[index].diagnostics.push({
+          source: "snapper",
+          rule: diagnostic.kind,
+          line: diagnostic.line,
+          column: 1,
+          message: `Sentence layout: ${diagnostic.kind}.`,
+          severity: "error",
+        });
+    }
+    checked[index].wouldReformat = report.would_reformat;
+  }
+  if (result.status !== Number(checked.some((item) => item.wouldReformat)))
+    fail("NATIVE_REPORT", "Inconsistent native failure report.");
+  return checked;
+}

package/src/native-staging.js

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+import {
+  chmodSync,
+  closeSync,
+  fstatSync,
+  lstatSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { fail, limits } from "./contracts.js";
+
+export const nativeCheckConfig =
+  'format = "markdown"\nmax_width = 0\nclause_breaks = false\nlong_threshold = 2097153\n';
+const editorConfig = "root = true\n\n[*]\nmax_line_length = off\n";
+const configFiles = new Map([
+  ["snapper-check.toml", nativeCheckConfig],
+  [".editorconfig", editorConfig],
+]);
+const inputName = /^input-(?:[0-9]|[12][0-9]|3[01])\.md$/u;
+
+function identity(stat) {
+  return { dev: stat.dev, ino: stat.ino, birthtimeNs: stat.birthtimeNs };
+}
+function same(stat, expected) {
+  return Object.keys(expected).every((key) => stat[key] === expected[key]);
+}
+function contains(root, path) {
+  const part = relative(root, path);
+  return (
+    part === "" ||
+    (!isAbsolute(part) && part !== ".." && !part.startsWith(".." + sep))
+  );
+}
+
+/** Establish a private external capability, or preserve the stdin path if unavailable. */
+export function createNativeStaging(consumerRoot) {
+  let token;
+  try {
+    const parent = realpathSync(tmpdir());
+    // Never create even an empty staging directory inside the consumer checkout.
+    if (
+      contains(consumerRoot, parent) ||
+      (process.platform === "win32" && parent.startsWith("\\\\"))
+    )
+      return null;
+    const parentStat = lstatSync(parent, { bigint: true });
+    if (
+      process.platform !== "win32" &&
+      parentStat.mode & 0o022n &&
+      !(parentStat.mode & 0o1000n)
+    )
+      return null;
+    const path = mkdtempSync(join(parent, "markdown-quality-native-"));
+    token = { path, identity: identity(lstatSync(path, { bigint: true })) };
+    if (process.platform === "win32") restrictWindowsAccess(path);
+    else chmodSync(path, 0o700);
+    verifyNativeStaging(token, false);
+    for (const [name, text] of configFiles) writeStagedFile(token, name, text);
+    verifyNativeStaging(token);
+    let closed = false;
+    return {
+      token,
+      close() {
+        if (closed) return;
+        closed = true;
+        closeNativeStaging(token);
+      },
+    };
+  } catch {
+    // No private document payload is written during capability establishment.
+    if (token) closeNativeStaging(token);
+    return null;
+  }
+}
+
+function restrictWindowsAccess(path) {
+  const deadline = performance.now() + 1000;
+  const systemRoot = process.env.SystemRoot ?? process.env.WINDIR;
+  if (!systemRoot || !isAbsolute(systemRoot))
+    throw Error("No system directory.");
+  const system = join(systemRoot, "System32");
+  const options = {
+    cwd: fileURLToPath(new URL("../assets/", import.meta.url)),
+    env: { SystemRoot: systemRoot, WINDIR: systemRoot },
+    shell: false,
+    windowsHide: true,
+    maxBuffer: 65536,
+  };
+  function run(command, args) {
+    const remaining = Math.floor(deadline - performance.now());
+    if (remaining <= 0) throw Error("Private access deadline exceeded.");
+    return spawnSync(command, args, { ...options, timeout: remaining });
+  }
+  const user = run(join(system, "whoami.exe"), ["/user", "/fo", "csv", "/nh"]);
+  if (user.error || user.signal || user.status !== 0)
+    throw Error("Identity unavailable.");
+  const sid = /"(S-1-(?:\d+-)*\d+)"\s*$/u.exec(
+    user.stdout.toString("utf8").trim(),
+  )?.[1];
+  if (!sid) throw Error("Identity unavailable.");
+  // Reset an empty owned directory first, then remove inherited entries and grant
+  // only the current SID. No consumer ACL or existing directory is modified.
+  for (const args of [
+    [path, "/reset"],
+    [path, "/inheritance:r", "/grant:r", `*${sid}:(OI)(CI)F`],
+  ]) {
+    const result = run(join(system, "icacls.exe"), args);
+    if (result.error || result.signal || result.status !== 0)
+      throw Error("Private access unavailable.");
+  }
+}
+
+/** Validate the originally created directory and immutable configuration boundary. */
+export function verifyNativeStaging(token, checkConfiguration = true) {
+  try {
+    const stat = lstatSync(token.path, { bigint: true });
+    if (
+      !stat.isDirectory() ||
+      stat.isSymbolicLink() ||
+      !same(stat, token.identity) ||
+      realpathSync(token.path) !== token.path
+    )
+      throw Error("Changed staging root.");
+    if (
+      process.platform !== "win32" &&
+      ((stat.mode & 0o077n) !== 0n || stat.uid !== BigInt(process.getuid()))
+    )
+      throw Error("Staging access is not private.");
+    if (checkConfiguration)
+      for (const [name, text] of configFiles) {
+        const path = join(token.path, name);
+        const file = lstatSync(path, { bigint: true });
+        if (
+          !file.isFile() ||
+          file.isSymbolicLink() ||
+          file.nlink !== 1n ||
+          file.size !== BigInt(Buffer.byteLength(text)) ||
+          readFileSync(path, "utf8") !== text
+        )
+          throw Error("Changed staging configuration.");
+      }
+  } catch {
+    fail("NATIVE_STAGING", "Private native staging is unavailable or changed.");
+  }
+}
+
+/** Write one package-selected exclusive file; its caller owns the returned identity. */
+export function writeStagedFile(token, name, text) {
+  verifyNativeStaging(token, false);
+  if (!inputName.test(name) && !configFiles.has(name))
+    fail("NATIVE_STAGING", "Invalid native staging input.");
+  const path = join(token.path, name);
+  let descriptor;
+  try {
+    descriptor = openSync(path, "wx", 0o600);
+    writeFileSync(descriptor, text, "utf8");
+    return {
+      path,
+      identity: identity(fstatSync(descriptor, { bigint: true })),
+    };
+  } catch {
+    fail("NATIVE_STAGING", "Cannot prepare private native input.");
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+/** Remove only regular single-link files in the still-owned flat directory. */
+export function removeStagedFile(token, file) {
+  try {
+    verifyNativeStaging(token, false);
+    if (dirname(file.path) !== token.path) throw Error("Outside staging.");
+    const stat = lstatSync(file.path, { bigint: true });
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.nlink !== 1n ||
+      !same(stat, file.identity)
+    )
+      throw Error("Changed staging input.");
+    unlinkSync(file.path);
+  } catch {
+    fail("NATIVE_CLEANUP", "Private native staging cleanup is incomplete.");
+  }
+}
+
+function closeNativeStaging(token) {
+  try {
+    verifyNativeStaging(token, false);
+    const names = readdirSync(token.path);
+    if (
+      names.length > 34 ||
+      names.some((name) => !inputName.test(name) && !configFiles.has(name))
+    )
+      throw Error("Unexpected staging contents.");
+    for (const name of names) {
+      const path = join(token.path, name);
+      removeStagedFile(token, {
+        path,
+        identity: identity(lstatSync(path, { bigint: true })),
+      });
+    }
+    verifyNativeStaging(token, false);
+    rmdirSync(token.path);
+  } catch {
+    fail("NATIVE_CLEANUP", "Private native staging cleanup is incomplete.");
+  }
+}

package/src/prose-diagnostics.js

@@ -4,6 +4,7 @@
 // 58a306013d3701f59dfe34341e96fac5a011e3ed. Copyright 2026 Hadden Industries Ltd.
 // Original MIT terms retained in LICENSES/MIT-universal-ontology.txt.
 import { runNative } from "./native-tool.js";
+import { runNativeChecks } from "./native-checks.js";
 // Requalified against 0.11.9. Owner approval: this chat, 2026-10-05.
 // Mirrors OwlAPI's narrow container boundary and continuation recheck approach.
 function listItem(line = "") {
@@ -56,3 +57,121 @@ export function checkProse(tool, text) {
     return runNative(tool, prose.join("\n") + "\n", true).length !== 0;
   });
 }
+
+/** Recheck complete independent list items in bounded groups, retaining finding order. */
+export function checkProseGroup(
+  tool,
+  texts,
+  staging,
+  observer,
+  admittedChecks,
+) {
+  let checkMilliseconds = 0;
+  function check(inputs) {
+    const owners = inputs.map((input) => input.owner);
+    const uniqueOwners = [...new Set(owners)];
+    observer?.start(uniqueOwners);
+    const started = performance.now();
+    let nativeMilliseconds = 0;
+    try {
+      return runNativeChecks(
+        tool,
+        inputs.map((input) => input.text),
+        staging,
+        observer && {
+          start: (indices) =>
+            observer.start([...new Set(indices.map((index) => owners[index]))]),
+          finish: (indices, elapsed) => {
+            nativeMilliseconds += elapsed;
+            observer.finish(
+              [...new Set(indices.map((index) => owners[index]))],
+              elapsed,
+            );
+          },
+        },
+      );
+    } finally {
+      const elapsed = performance.now() - started;
+      checkMilliseconds += elapsed;
+      observer?.finish(uniqueOwners, Math.max(0, elapsed - nativeMilliseconds));
+    }
+  }
+  const checked = new Array(texts.length);
+  const unchecked = [];
+  for (const [owner, text] of texts.entries()) {
+    const admitted = admittedChecks?.[owner];
+    if (admitted) checked[owner] = admitted;
+    else unchecked.push({ text, owner });
+  }
+  if (unchecked.length) {
+    const results = check(unchecked);
+    for (const [index, input] of unchecked.entries())
+      checked[input.owner] = results[index];
+  }
+  const keep = checked.map((entry) => entry.diagnostics.map(() => true));
+  let pending = [],
+    pendingBytes = 0;
+  function flush() {
+    if (!pending.length) return;
+    const items = pending;
+    pending = [];
+    pendingBytes = 0;
+    const results = check(items);
+    for (const [index, result] of results.entries())
+      keep[items[index].owner][items[index].finding] =
+        result.diagnostics.length !== 0;
+  }
+  for (const [owner, text] of texts.entries()) {
+    observer?.start([owner]);
+    const started = performance.now(),
+      previousChecks = checkMilliseconds;
+    try {
+      const lines = text.split(/\r?\n/u);
+      for (const [finding, diagnostic] of checked[
+        owner
+      ].diagnostics.entries()) {
+        const index = diagnostic.line - 1,
+          item = listItem(lines[index]);
+        if (!item) continue;
+        const previous = listItem(lines[index - 1]);
+        const quotedNumber =
+          diagnostic.rule === "fused" && item.quotes > 0 && item.ordered;
+        const adjacent =
+          diagnostic.rule === "wrap" &&
+          previous &&
+          previous.prefix === item.prefix &&
+          previous.indent === item.indent &&
+          previous.ordered === item.ordered;
+        if (!quotedNumber && !adjacent) continue;
+        const prose = [item.prose];
+        for (let next = index + 1; next < lines.length; next++) {
+          const line = lines[next];
+          if (!line.startsWith(item.prefix) || listItem(line)) break;
+          const content = line.slice(item.prefix.length),
+            indent = item.contentOffset - item.prefix.length;
+          if (!content.startsWith(" ".repeat(indent))) break;
+          prose.push(content.slice(indent));
+        }
+        const snippet = prose.join("\n") + "\n",
+          bytes = Buffer.byteLength(snippet);
+        if (pending.length === 32 || pendingBytes + bytes > 4_194_304) flush();
+        pending.push({ text: snippet, owner, finding });
+        pendingBytes += bytes;
+      }
+    } finally {
+      // Native groups already charge their participants. Attribute owned snippet
+      // extraction separately, including time between successive rechecks.
+      observer?.finish(
+        [owner],
+        Math.max(
+          0,
+          performance.now() - started - (checkMilliseconds - previousChecks),
+        ),
+      );
+    }
+  }
+  flush();
+  return checked.map((entry, owner) =>
+    entry.diagnostics.filter((_, index) => keep[owner][index]),
+  );
+}