@hadden-industries/markdown-quality 0.1.0-alpha.2

package/src/prose-diagnostics.js

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// List-boundary recheck adapted from OwlAPI at 1cdc5a33b9538cce8ced88f21af18138da7a8923,
+// scripts/documentation-quality.mjs, originally from universal-ontology at
+// 58a306013d3701f59dfe34341e96fac5a011e3ed. Copyright 2026 Hadden Industries Ltd.
+// Original MIT terms retained in LICENSES/MIT-universal-ontology.txt.
+import { runNative } from "./native-tool.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 = "") {
+  let offset = 0,
+    quotes = 0;
+  while (true) {
+    const match = /^[ ]{0,3}> ?/u.exec(line.slice(offset));
+    if (!match) break;
+    offset += match[0].length;
+    quotes++;
+  }
+  const match = /^( {0,3})(\d{1,9}[.)]|[-+*]) +(\S.*)$/u.exec(
+    line.slice(offset),
+  );
+  if (!match) return undefined;
+  return {
+    prefix: line.slice(0, offset),
+    quotes,
+    indent: match[1].length,
+    ordered: /^\d/u.test(match[2]),
+    contentOffset: line.length - match[3].length,
+    prose: match[3],
+  };
+}
+export function checkProse(tool, text) {
+  const lines = text.split(/\r?\n/u);
+  return runNative(tool, text, true).filter((d) => {
+    const index = d.line - 1,
+      item = listItem(lines[index]);
+    if (!item) return true;
+    const previous = listItem(lines[index - 1]);
+    const quotedNumber = d.rule === "fused" && item.quotes > 0 && item.ordered;
+    const adjacent =
+      d.rule === "wrap" &&
+      previous &&
+      previous.prefix === item.prefix &&
+      previous.indent === item.indent &&
+      previous.ordered === item.ordered;
+    if (!quotedNumber && !adjacent) return true;
+    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));
+    }
+    // Malformed output, unknown findings, crashes, and timeouts still fail closed.
+    return runNative(tool, prose.join("\n") + "\n", true).length !== 0;
+  });
+}

package/src/quality.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+import { loadConfiguration } from "./configuration.js";
+import { selectDocuments, readDocument } from "./documents.js";
+import { resolveTool, manifest } from "./native-tool.js";
+import { createDocumentAnalyzer } from "./document-analysis.js";
+import { replaceDocument } from "./replacement.js";
+import {
+  decode,
+  fail,
+  limits,
+  metadata,
+  OperationError,
+  diagnosticBudget,
+} from "./contracts.js";
+export function createResult(mode = "check", explicit = false) {
+  return {
+    schemaVersion: 1,
+    package: { name: metadata.name, version: metadata.version },
+    preset: "authored-gfm@1",
+    tools: {
+      prettier: "3.9.9",
+      eslint: "10.12.0",
+      markdown: "8.0.3",
+      snapper: manifest.snapperVersion,
+    },
+    operation: ["check", "format", "inspect"].includes(mode) ? mode : "unknown",
+    configDigest: null,
+    configuration: null,
+    selection: {
+      mode: explicit ? "explicit" : "full",
+      files: [],
+      exclusions: [],
+    },
+    diagnostics: [],
+    outcome: "error",
+    exitCode: 2,
+    written: [],
+    unchanged: [],
+    unprocessed: [],
+    errors: [],
+  };
+}
+/** Run full or explicit read-only checking, inspection, or guarded formatting. */
+export async function runQuality(options = {}) {
+  const mode = options.mode ?? "check";
+  const result = createResult(mode, options.files !== undefined);
+  let analyzer;
+  try {
+    if (!["check", "format", "inspect"].includes(mode))
+      fail("INVALID_OPERATION", "Unknown operation.");
+    const context = loadConfiguration(options);
+    result.configDigest = context.configDigest;
+    result.configuration = context.config;
+    result.selection = await selectDocuments(context, options.files);
+    result.unprocessed = [...result.selection.files];
+    // No native process or tool resolution is necessary for a zero selection.
+    if (result.selection.files.length === 0) {
+      result.outcome = "clean";
+      result.exitCode = 0;
+      return result;
+    }
+    const tool = resolveTool();
+    if (mode === "inspect") {
+      result.unprocessed = [];
+      result.outcome = "clean";
+      result.exitCode = 0;
+      return result;
+    }
+    analyzer = createDocumentAnalyzer(context, tool);
+    const candidates = [];
+    let total = 0,
+      outputTotal = 0,
+      diagnosticBytes = 0;
+    for (const file of result.selection.files) {
+      const item = readDocument(context.root, file);
+      if (mode === "format" && item.stat.nlink !== 1n)
+        fail("HARD_LINK", "Hard-linked documents cannot be formatted.");
+      total += item.bytes.length;
+      if (total > limits.totalBytes)
+        fail("BATCH_LIMIT", "Total document bytes exceed the limit.");
+      const original = decode(item.bytes);
+      const formatted = await analyzer.analyze({ text: original, file, mode });
+      const outputBytes = Buffer.byteLength(formatted.output);
+      if (outputBytes > limits.fileBytes)
+        fail("DOCUMENT_LIMIT", "Formatted document exceeds the size limit.");
+      outputTotal += outputBytes;
+      if (outputTotal > limits.totalBytes)
+        fail("BATCH_LIMIT", "Total formatted document bytes exceed the limit.");
+      const diagnostics = formatted.diagnostics;
+      if (mode === "check" && !item.bytes.equals(Buffer.from(formatted.output)))
+        diagnostics.push({
+          source: "formatter",
+          rule: "layout",
+          line: 1,
+          column: 1,
+          severity: "error",
+          message: "Document requires formatting.",
+        });
+      diagnosticBudget(diagnostics);
+      for (const d of diagnostics) {
+        const diagnostic = { path: file, ...d };
+        diagnosticBytes += Buffer.byteLength(JSON.stringify(diagnostic)) + 1;
+        if (
+          result.diagnostics.length >= limits.diagnostics ||
+          diagnosticBytes > limits.diagnosticBytes
+        )
+          fail(
+            "DIAGNOSTIC_LIMIT",
+            "Diagnostic count or output bytes exceed the limit.",
+          );
+        result.diagnostics.push(diagnostic);
+      }
+      if (mode === "format")
+        candidates.push({ file, item, output: formatted.output });
+    }
+    result.diagnostics.sort((a, b) =>
+      a.path < b.path
+        ? -1
+        : a.path > b.path
+          ? 1
+          : a.line - b.line ||
+            a.column - b.column ||
+            a.rule.localeCompare(b.rule, "en"),
+    );
+    if (result.diagnostics.length) {
+      result.outcome = "findings";
+      result.exitCode = 1;
+      return result;
+    }
+    if (mode === "format")
+      for (const candidate of candidates) {
+        if (candidate.item.bytes.equals(Buffer.from(candidate.output)))
+          result.unchanged.push(candidate.file);
+        else {
+          replaceDocument(context.root, candidate.item, candidate.output);
+          result.written.push(candidate.file);
+        }
+        result.unprocessed.shift();
+      }
+    else {
+      result.unchanged = [...result.selection.files];
+      result.unprocessed = [];
+    }
+    result.outcome = "clean";
+    result.exitCode = 0;
+  } catch (error) {
+    result.errors.push({
+      code: error instanceof OperationError ? error.code : "OPERATION_FAILED",
+      message:
+        error instanceof OperationError ? error.message : "Operation failed.",
+    });
+  } finally {
+    if (analyzer) await analyzer.close();
+  }
+  return result;
+}

package/src/replacement.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+import {
+  openSync,
+  closeSync,
+  writeFileSync,
+  fsyncSync,
+  chmodSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { safePath } from "./configuration.js";
+import { fail } from "./contracts.js";
+import { readDocument } from "./documents.js";
+function unchanged(root, item) {
+  safePath(root, item.path, { file: true });
+  const { stat, bytes } = readDocument(root, item.path);
+  if (
+    stat.dev !== item.stat.dev ||
+    stat.ino !== item.stat.ino ||
+    stat.nlink !== 1n ||
+    stat.mode !== item.stat.mode ||
+    !bytes.equals(item.bytes)
+  )
+    fail(
+      "PREIMAGE_CHANGED",
+      "File identity, permissions, or bytes changed before replacement.",
+    );
+}
+export function replaceDocument(root, item, output) {
+  unchanged(root, item);
+  if (
+    typeof process.getuid === "function" &&
+    item.stat.uid !== BigInt(process.getuid())
+  )
+    fail(
+      "FILE_OWNERSHIP",
+      "Formatting a file owned by another user is unsupported.",
+    );
+  const temp = join(
+    dirname(item.path),
+    `.markdown-quality-${randomUUID()}.tmp`,
+  );
+  let fd,
+    created = false;
+  try {
+    fd = openSync(temp, "wx", Number(item.stat.mode & 0o777n));
+    created = true;
+    writeFileSync(fd, output, "utf8");
+    chmodSync(temp, Number(item.stat.mode & 0o777n));
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    unchanged(root, item);
+    renameSync(temp, item.path);
+    created = false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (created) unlinkSync(temp);
+  }
+}