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

package/docs/ci-trust.md

@@ -0,0 +1,40 @@
+# CI trust and acquisition
+
+The package repository, OwlAPI, and WebVOWL are public, as inspected through GitHub on 2026-10-05.
+The owner selected public npm distribution after the private upload was rejected with E402.
+Core and both native packages declare public access; anonymous installation is a required registry qualification.
+Ordinary fork pull requests need no registry credential or paid npm subscription.
+The direct CLI is the canonical integration.
+A private shared Action is optional and does not solve public caller access.
+
+| Event                    | Trusted graph and policy                              | Acquisition                                     | Candidate processing                                 | Current status                               |
+| ------------------------ | ----------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------- | -------------------------------------------- |
+| Package pull request     | Public locked dependencies and fixed native manifests | Public upstream inputs, no private secrets      | Package tests run without elevated authority         | Hosted qualification pending                 |
+| Pilot protected branch   | Reviewed capability release and consumer policy       | Public locked graph, lifecycle scripts disabled | Full authored scope without credentials              | Public registry qualification pending        |
+| Pilot same-repository PR | Reviewed base tooling and policy                      | Separate trusted acquisition                    | Candidate Markdown and link target tree only         | Architecture selected; qualification pending |
+| Pilot fork PR            | Reviewed base tooling and policy                      | Separate trusted acquisition                    | Candidate data only; no candidate scripts or graph   | Architecture selected; qualification pending |
+| Tool or policy update PR | Existing accepted graph until review                  | New graph requires owner review                 | Never treat candidate graph or exclusions as trusted | Required review remains explicit             |
+
+The package CI has no registry secret or OIDC permission.
+It installs with lifecycle scripts disabled and qualifies both OS targets.
+Packed-consumer tests acquire public JavaScript dependencies before testing offline frozen-lock reinstallation and runtime execution.
+The source lock acquisition alone does not populate metadata for a fresh consumer install.
+It cannot serve as evidence that a pilot's private access works.
+
+A pilot integration must acquire the exact public tool graph from a trusted source without registry credentials and process a separately fetched candidate data tree.
+Use reviewed base policy and ignore files at their original relative paths so candidate exclusions cannot silently weaken the required check.
+Candidate checkout must not execute application tooling, Git hooks, package lifecycle scripts, JavaScript configuration, or a candidate CLI.
+The checking process must not inherit checkout write credentials, npm configuration, or OIDC issuance authority.
+Trusted policy review is required for any change to required scope or exclusions.
+
+Do not give publication or repository-write credentials to a PR-controlled dependency graph.
+Do not execute candidate source in an elevated `pull_request_target` job.
+Public capability archives are available to all recipients; source/notice and integrity obligations still apply.
+Unqualified event isolation or a missing registry tuple blocks pilot cutover.
+
+The owner restored npm login and approved publish authentication on 2026-10-05.
+The private Windows upload was rejected by npm with E402, and no accessible alpha.1 version was found.
+The subsequent owner request selects public distribution and removes the paid-private-plan prerequisite.
+Pilot cutover still requires exact public tuple readback, fresh credential-free installation, event/policy isolation and accepted consumer deltas.
+
+References: [GitHub event trust](https://docs.github.com/en/actions/reference/security/securely-using-pull_request_target), [public scoped publication](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/), and [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).

package/docs/consumer-guide.md

@@ -0,0 +1,87 @@
+# Consumer guide
+
+Install an exact coordinated public release after registry availability is verified.
+Acquisition needs no npm account or token; disable lifecycle scripts.
+
+```sh
+npm install --save-dev --save-exact --ignore-scripts @hadden-industries/markdown-quality@0.1.0-alpha.2
+npm ci --ignore-scripts
+```
+
+The version above identifies the candidate; it is not currently a published registry promise.
+Keep the consumer lockfile.
+An isolated `tooling/markdown` npm project supports consumers that do not use Node for their application.
+Its commands must pass the actual repository root.
+
+Place this bounded JSON policy at the repository root.
+
+```json
+{
+  "schemaVersion": 1,
+  "preset": "authored-gfm@1",
+  "include": ["*.md", "docs/**/*.md"],
+  "exclude": ["docs/reviews/**", "docs/generated/**"],
+  "ignoreFiles": [".gitignore", ".prettierignore"],
+  "lint": {},
+  "links": { "localFiles": true, "rootRelative": "reject" },
+  "layout": { "endOfLine": "preserve", "tabWidth": 2 }
+}
+```
+
+Include and exclude entries are relative slash-separated globs supplied to picomatch.
+Explicit exclusions win.
+Prettier owns the configured ignore files' native semantics.
+Missing optional default ignore files are allowed.
+Dependency, Git, and tooling directories cannot become document inputs.
+Directory traversal never follows symbolic links or Windows junctions.
+Explicit linked paths fail.
+Formatting hard-linked files is unsupported.
+
+Unknown fields, versions, and lint rules fail.
+Lint overrides accept only `off`, `warn`, or `error` for installed `markdown/` rules.
+Warnings are unresolved findings and block formatting.
+GitHub alert labels are allowed.
+Consumer JavaScript configs, arbitrary plugins, inline ESLint disable comments, and native executable overrides are not execution authority.
+
+Local Markdown links, images, and definitions are parsed with maintained mdast/GFM libraries.
+Percent-encoded filenames resolve after decoding.
+Contained files and directories are valid targets.
+External schemes are classified without network access.
+Same-document fragments use the native ESLint Markdown rule.
+Cross-document heading fragments and remote availability are outside this version's contract.
+
+The library exports `runQuality({ root, config, mode, files })`.
+Omit `files` for full discovery.
+An explicit empty array selects nothing.
+CLI literal filenames follow `--`; `--files-json` accepts the JSON array directly.
+Results identify the package, preset, tools, config digest, selection, diagnostics, written paths, unchanged paths, unprocessed paths, and operational errors.
+Text and JSON share the same result.
+
+Exit `0` means clean or completed.
+Exit `1` means content findings.
+Exit `2` means configuration, tool, input, or operation failure.
+Machine output follows the shipped result schema even for CLI input failures.
+No excerpts, document bodies, or absolute root paths are emitted by default.
+
+Limits are 2 MiB per document, 32 MiB per batch, 10,000 selected documents, 100,000 enumerated entries, and 256 KiB per configuration or ignore file.
+Native invocations have a 15-second deadline and an 8 MiB output cap.
+Document analysis runs in a 128 MiB worker with a 30-second deadline.
+Discovered path bytes are capped at 4 MiB.
+Diagnostics are capped at 1,000 records per document, 10,000 records across the batch, and 4 MiB per document and batch.
+Exceeding a limit returns exit `2` before any formatting writes.
+Text diagnostics escape terminal control characters; JSON retains structured relative filenames.
+Lint messages describe the violated rule without quoting document content.
+These are conservative operational limits; benchmark and platform acceptance remains part of candidate qualification.
+
+Formatting compares maintained parsed structure and literals before replacement and verifies convergence.
+The parsed comparison is an additional backstop, not a universal rendered-equivalence guarantee.
+It conservatively refuses unsupported semantic or literal changes.
+Ordinary file permission bits are preserved; ownership changes, alternate streams, ACL inheritance, arbitrary metadata, and adversarial filesystem races are not promised as preserved.
+Use a clean baseline or retained preimages when original uncommitted bytes must be recoverable.
+
+CI acquisition uses the exact public release and a trusted reviewed graph without registry credentials.
+The checking process receives no publication, repository-write or OIDC credentials.
+The package itself needs no registry credentials at runtime.
+Fork content cannot supply the executable, dependency graph, workflow, scripts, or trusted policy.
+An unavailable check is a blocked required check, not a successful skip.
+The [CI trust decision](ci-trust.md) records the actual pilot constraints.

package/docs/support-and-release.md

@@ -0,0 +1,72 @@
+# Support and release
+
+The initial contract targets Node 24.21.0, Windows x64, and Ubuntu 24.04 x64 with glibc.
+Only observed passing platform evidence can establish support.
+Other Node majors, macOS, ARM, and musl are unqualified.
+Controlled Linux builds require glibc 2.39, as supplied by Ubuntu 24.04.
+Windows requires the installed x64 Microsoft Visual C++ runtime (`VCRUNTIME140.dll` and UCRT).
+No system runtime installer or runtime download is shipped.
+Core and platform packages share one immutable release version.
+Consumers pin the package, preset, and lockfile.
+
+The public contract includes CLI, library API, schemas, exit meanings, formatter output, and default diagnostics.
+A compatible repair may use a patch version.
+An opt-in compatible feature may use a minor version.
+Changed defaults require a new preset major, and a package major when existing invocations change.
+Dependency upgrades are classified from observed corpus and consumer deltas.
+Never overwrite a published version.
+
+The current alpha is not stable v1.0.
+Stable promotion requires the same qualified tuple on both platforms, public registry readback and unauthenticated installation, both pilot acceptances, and a timed restoration exercise.
+Changed/referrer mode and later fleet adoptions remain deferred.
+
+Prepare assets explicitly from their frozen manifest.
+Install source dependencies with `npm ci --ignore-scripts`.
+Complete formatting and cheap syntax checks before freezing a candidate.
+Run relevant tests and packed root/isolated consumers.
+Retain independent correctness, security, platform, and rights review.
+Recheck only affected questions after repairs.
+
+```sh
+node scripts/pack.js /approved/evidence/release
+npm sbom --sbom-format cyclonedx
+```
+
+The packer emits coordinated archives and a digest-bound release manifest.
+Its core manifest replaces development file dependencies with exact release versions.
+The source lock does not become the consumer lock.
+The JS SBOM must be reconciled with every compiled native/runtime component before release.
+An upstream Cargo lock is a superset of features and development inputs and does not prove exact shipped component coverage.
+The original upstream license and per-asset repack identity are retained.
+
+The owner selected public distribution after npm rejected the private publication with E402.
+All three packages declare public access and share version 0.1.0-alpha.2.
+The unpublished private alpha.1 candidate and all rejected attempts remain historical evidence.
+Direct first publication uses explicit public access; a staged placeholder is unnecessary.
+OIDC publication is preferred after actual package/workflow eligibility is configured.
+Public installation needs no registry token, subscription, or OIDC authority.
+Public npm provenance is eligible only through a qualified supported publisher; do not claim it for the local bootstrap.
+Retain attributable source/build/repack evidence and qualify attestations separately.
+
+Publish native packages first under a pilot tag and publish the core only when the tuple is coherent.
+Read back hashes, public visibility, and fresh unauthenticated archive acquisition for every package.
+Qualify root and isolated consumers on both supported platforms from the registry, without credentials.
+Do not perform registry publication while rights, publisher authentication, independent assurance, or platform evidence remains missing.
+A partial publication stays unpromoted and receives a new corrective version if bytes change.
+
+For recovery, retain the exact consumer base revision, old manifest and lock, workflows, selected document preimages, and unrelated-file sentinels.
+Restore only migration-owned changes.
+Verify byte identities and required checks, then record elapsed restoration time.
+Downgrading a package cannot restore formatted document bytes.
+One pilot rehearsal is required before stable promotion.
+
+Security reports use GitHub's private vulnerability reporting route when enabled; otherwise contact the repository owner through the project's existing private channel.
+No unattended observation service is assumed.
+During this authorized session, critical/high reports block promotion immediately.
+Durable acknowledgement, triage, mitigation targets, reporting availability, and maintenance ownership require owner acceptance before stable release.
+Retain release source, build inputs, notices, recipient delivery evidence, and recovery inputs for the maintained release lifetime and its accepted retention period.
+
+Provide AGPL corresponding source and build materials alongside object-code delivery to actual recipients.
+Preserve third-party license texts and attribution.
+Public registry access does not waive source obligations.
+The repository's original `LICENSE` bytes are verified by the full check.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hadden-industries/markdown-quality",
+  "version": "0.1.0-alpha.2",
+  "description": "Shared, bounded Markdown formatting, GFM linting, and local-link checking",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "engines": {
+    "node": ">=24.21.0 <25"
+  },
+  "bin": {
+    "markdown-quality": "src/cli.js"
+  },
+  "exports": {
+    ".": "./src/quality.js",
+    "./configuration-schema": "./schemas/configuration.schema.json",
+    "./result-schema": "./schemas/result.schema.json"
+  },
+  "files": [
+    "src",
+    "schemas",
+    "assets",
+    "LICENSE",
+    "LICENSES",
+    "README.md",
+    "THIRD-PARTY-NOTICES.md",
+    "docs/consumer-guide.md",
+    "docs/ci-trust.md",
+    "docs/support-and-release.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hadden-Industries/markdown-quality.git"
+  },
+  "dependencies": {
+    "@eslint/markdown": "8.0.3",
+    "ajv": "8.20.0",
+    "eslint": "10.12.0",
+    "mdast-util-from-markdown": "2.1.0",
+    "mdast-util-gfm": "3.1.0",
+    "micromark-extension-gfm": "3.0.0",
+    "picomatch": "4.0.7",
+    "prettier": "3.9.9"
+  },
+  "optionalDependencies": {
+    "@hadden-industries/markdown-quality-win32-x64": "0.1.0-alpha.2",
+    "@hadden-industries/markdown-quality-linux-x64": "0.1.0-alpha.2"
+  }
+}

package/schemas/configuration.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "preset", "include"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "preset": { "const": "authored-gfm@1" },
+    "include": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 100,
+      "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+    },
+    "exclude": {
+      "type": "array",
+      "maxItems": 100,
+      "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+    },
+    "ignoreFiles": {
+      "type": "array",
+      "maxItems": 10,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+    },
+    "lint": {
+      "type": "object",
+      "maxProperties": 30,
+      "additionalProperties": { "enum": ["off", "warn", "error"] }
+    },
+    "links": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "localFiles": { "type": "boolean" },
+        "rootRelative": { "enum": ["reject", "root"] }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "endOfLine": { "enum": ["lf", "crlf", "preserve"] },
+        "tabWidth": { "type": "integer", "minimum": 1, "maximum": 8 }
+      }
+    }
+  }
+}

package/schemas/result.schema.json

@@ -0,0 +1,247 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "package",
+    "preset",
+    "tools",
+    "operation",
+    "configDigest",
+    "selection",
+    "diagnostics",
+    "outcome",
+    "exitCode",
+    "written",
+    "unchanged",
+    "unprocessed",
+    "errors",
+    "configuration"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "preset": {
+      "const": "authored-gfm@1"
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "operation": {
+      "enum": ["check", "format", "inspect", "unknown"]
+    },
+    "configDigest": {
+      "type": ["string", "null"]
+    },
+    "selection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "files", "exclusions"],
+      "properties": {
+        "mode": {
+          "enum": ["full", "explicit"]
+        },
+        "files": {
+          "$ref": "#/definitions/paths"
+        },
+        "exclusions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "reason"],
+            "additionalProperties": false,
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "reason": {
+                "enum": ["mandatory", "not-included", "excluded", "ignored"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "source",
+          "rule",
+          "line",
+          "column",
+          "message",
+          "severity"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "source": {
+            "enum": ["formatter", "snapper", "eslint", "links"]
+          },
+          "rule": {
+            "type": "string"
+          },
+          "line": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "column": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "message": {
+            "type": "string"
+          },
+          "severity": {
+            "enum": ["error", "warning"]
+          }
+        }
+      }
+    },
+    "outcome": {
+      "enum": ["clean", "findings", "error"]
+    },
+    "exitCode": {
+      "enum": [0, 1, 2]
+    },
+    "written": {
+      "$ref": "#/definitions/paths"
+    },
+    "unchanged": {
+      "$ref": "#/definitions/paths"
+    },
+    "unprocessed": {
+      "$ref": "#/definitions/paths"
+    },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "message"],
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "configuration": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schemaVersion", "preset", "include"],
+          "properties": {
+            "schemaVersion": {
+              "const": 1
+            },
+            "preset": {
+              "const": "authored-gfm@1"
+            },
+            "include": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 100,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              }
+            },
+            "exclude": {
+              "type": "array",
+              "maxItems": 100,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              }
+            },
+            "ignoreFiles": {
+              "type": "array",
+              "maxItems": 10,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              }
+            },
+            "lint": {
+              "type": "object",
+              "maxProperties": 30,
+              "additionalProperties": {
+                "enum": ["off", "warn", "error"]
+              }
+            },
+            "links": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "localFiles": {
+                  "type": "boolean"
+                },
+                "rootRelative": {
+                  "enum": ["reject", "root"]
+                }
+              }
+            },
+            "layout": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "endOfLine": {
+                  "enum": ["lf", "crlf", "preserve"]
+                },
+                "tabWidth": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 8
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "paths": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/src/analysis.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+import { ESLint } from "eslint";
+import markdown from "@eslint/markdown";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfm } from "micromark-extension-gfm";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { lstatSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { safePath } from "./configuration.js";
+import { fail, limits } from "./contracts.js";
+export const parse = (text) =>
+  fromMarkdown(text, {
+    extensions: [gfm()],
+    mdastExtensions: [gfmFromMarkdown()],
+  });
+export function createLinter(context) {
+  const defaults = {
+    ...markdown.configs.recommended[0].rules,
+    "markdown/table-column-count": "error",
+    "markdown/no-missing-label-refs": [
+      "error",
+      { allowLabels: ["!NOTE", "!TIP", "!IMPORTANT", "!WARNING", "!CAUTION"] },
+    ],
+  };
+  const rules = { ...defaults };
+  for (const [rule, severity] of Object.entries(context.config.lint))
+    rules[rule] = Array.isArray(defaults[rule])
+      ? [severity, ...defaults[rule].slice(1)]
+      : severity;
+  return new ESLint({
+    cwd: context.root,
+    overrideConfigFile: true,
+    ignore: false,
+    overrideConfig: [
+      {
+        files: ["**/*.md"],
+        plugins: { markdown },
+        language: "markdown/gfm",
+        linterOptions: { noInlineConfig: true },
+        rules,
+      },
+    ],
+  });
+}
+export async function lintDocument(linter, text, file) {
+  const [result] = await linter.lintText(text, { filePath: file });
+  if (result.messages.length > limits.documentDiagnostics)
+    fail(
+      "DIAGNOSTIC_LIMIT",
+      "Diagnostic count or output bytes exceed the limit.",
+    );
+  return result.messages.map((d) => ({
+    source: "eslint",
+    rule: d.ruleId ?? "parse",
+    line: d.line ?? 1,
+    column: d.column ?? 1,
+    message: d.ruleId
+      ? (markdown.rules[d.ruleId.slice(9)]?.meta.docs.description ??
+        "Markdown rule violation.")
+      : "Markdown parsing failed.",
+    severity: d.severity === 2 ? "error" : "warning",
+  }));
+}
+export function checkLinks(context, text, file) {
+  if (!context.config.links.localFiles) return [];
+  const diagnostics = [];
+  function walk(node) {
+    if (["link", "image", "definition"].includes(node.type)) {
+      const target = node.url;
+      if (
+        target &&
+        !target.startsWith("#") &&
+        !/^[a-zA-Z][a-zA-Z\d+.-]*:/u.test(target) &&
+        !target.startsWith("//")
+      ) {
+        try {
+          const raw = target.split(/[?#]/u)[0];
+          const decoded = decodeURIComponent(raw);
+          if (decoded.includes("\\") || decoded.includes("\0"))
+            throw new Error("Invalid target.");
+          if (
+            decoded.startsWith("/") &&
+            context.config.links.rootRelative === "reject"
+          )
+            throw new Error(
+              "Root-relative links require explicit root policy.",
+            );
+          const path = safePath(
+            context.root,
+            decoded.startsWith("/")
+              ? resolve(context.root, "." + decoded)
+              : resolve(context.root, dirname(file), decoded),
+          );
+          const stat = lstatSync(path);
+          if (!stat.isFile() && !stat.isDirectory())
+            throw new Error("Target is not a file or directory.");
+        } catch (error) {
+          if (diagnostics.length >= limits.documentDiagnostics)
+            fail(
+              "DIAGNOSTIC_LIMIT",
+              "Diagnostic count or output bytes exceed the limit.",
+            );
+          diagnostics.push({
+            source: "links",
+            rule: "local-target",
+            line: node.position.start.line,
+            column: node.position.start.column,
+            message:
+              "Local target is missing, invalid, linked, or outside the root.",
+            severity: "error",
+          });
+        }
+      }
+    }
+    for (const child of node.children ?? []) walk(child);
+  }
+  walk(parse(text));
+  return diagnostics;
+}