@pretextbook/schema 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+import { Diagnostic, CompletionItem, Range, Position } from 'vscode-languageserver-types';
+export type { Diagnostic, CompletionItem, Range, Position };
+/**
+ * A grammar produced by salve from a (precompiled or freshly-converted) RELAX NG
+ * schema. Kept opaque here so consumers do not need to depend on salve's types
+ * directly.
+ */
+export interface Grammar {
+    newWalker(nameResolver?: unknown): unknown;
+}
+/**
+ * The category of a raw validation error, derived from salve's error class.
+ * Rule predicates and message templates key off this.
+ */
+export type SchemaErrorKind = "element-not-allowed" | "attribute-not-allowed" | "attribute-value-invalid" | "choice-not-satisfied" | "text-not-allowed" | "unexpected-end" | "xinclude-missing" | "xinclude-circular" | "well-formedness" | "duplicate-id" | "dangling-reference" | "other";
+/**
+ * A normalized validation error, produced before rule/severity/message
+ * customization is applied. This is the shape rule predicates receive.
+ */
+export interface SchemaError {
+    kind: SchemaErrorKind;
+    /** The raw message produced by the underlying engine. */
+    message: string;
+    /** The element or attribute local name involved (when applicable). */
+    name?: string;
+    /** The namespace URI involved (when applicable). */
+    ns?: string;
+    /** Names offered as alternatives (e.g. for choice errors). */
+    alternatives?: string[];
+    /**
+     * Local name of the immediate enclosing element at the point of the error.
+     * For a misplaced child element this is the element it appears inside; for an
+     * invalid attribute it is the element carrying the attribute. Undefined at the
+     * document root (e.g. unexpected-end errors).
+     */
+    parent?: string;
+    /**
+     * The chain of open elements at the point of the error, outermost first and
+     * ending with {@link parent}. Enables context-aware rules (e.g. only relax an
+     * element when it appears inside a specific ancestor).
+     */
+    ancestors?: string[];
+    /** Location of the error in the (mapped-back) source document. */
+    range: Range;
+    /** URI of the document the error belongs to (after XInclude mapping). */
+    uri: string;
+}
+/**
+ * A rule that customizes how a raw {@link SchemaError} becomes an LSP
+ * {@link Diagnostic}: overriding severity, rewriting the message, tagging it
+ * with a stable rule id, or filtering it out entirely.
+ */
+export interface Rule {
+    /** Stable identifier reported as the diagnostic `code`. */
+    id: string;
+    /** Returns true if this rule applies to the given error. */
+    match: (error: SchemaError) => boolean;
+    /** Severity to report. Defaults to the ruleset default (Error). */
+    severity?: DiagnosticSeverityValue;
+    /** Rewrites the diagnostic message. Receives the raw error. */
+    message?: (error: SchemaError) => string;
+    /** When true, the error is suppressed rather than reported. */
+    suppress?: boolean;
+}
+/** Mirrors `vscode-languageserver-types` DiagnosticSeverity numeric values. */
+export type DiagnosticSeverityValue = 1 | 2 | 3 | 4;
+export interface Ruleset {
+    rules: Rule[];
+    /** Severity applied when no rule overrides it. Defaults to Error (1). */
+    defaultSeverity?: DiagnosticSeverityValue;
+    /** Diagnostic `source` label. Defaults to "pretext". */
+    source?: string;
+}
+/** Reads the contents of an absolute file path, or returns undefined if absent. */
+export type FileReader = (absolutePath: string) => string | undefined;
+export interface ValidateOptions {
+    /** URI of the document being validated (used for reporting + XInclude base). */
+    uri?: string;
+    /** Cancels in-flight validation. */
+    signal?: AbortSignal;
+    /** Resolve `xi:include` references before validating. Default: true. */
+    resolveXIncludes?: boolean;
+    /** Reads included files. Defaults to a Node `fs` reader. */
+    readFile?: FileReader;
+    /** Rule customization applied to raw errors. Defaults to {@link defaultRuleset}. */
+    ruleset?: Ruleset;
+}
+export interface ValidationResult {
+    /** Diagnostics for the primary document ({@link ValidateOptions.uri}). */
+    diagnostics: Diagnostic[];
+    /** All diagnostics keyed by document URI (primary + XIncluded files). */
+    diagnosticsByUri: Record<string, Diagnostic[]>;
+}
+export interface CompletionContext {
+    /** Full source text of the document. */
+    text: string;
+    /** Cursor position (0-based line and character). */
+    position: Position;
+    /** The compiled grammar to consult. */
+    grammar: Grammar;
+    /**
+     * URI of the document, used to cache and incrementally extend walker state
+     * across repeated completion requests on the same (growing) document.
+     * Completions still work without it; caching is simply skipped.
+     */
+    uri?: string;
+}

package/dist/validate.d.ts

@@ -0,0 +1,9 @@
+import { ValidateOptions, ValidationResult, Grammar } from './types';
+import { Severity } from './rules';
+/**
+ * Validate an XML document against a compiled PreTeXt grammar. Resolves
+ * `xi:include`s first (unless disabled) and maps errors in included files back
+ * to their originating file/line.
+ */
+export declare function validateDocument(source: string, grammar: Grammar, options?: ValidateOptions): ValidationResult;
+export { Severity };

package/dist/xinclude.d.ts

@@ -0,0 +1,42 @@
+import { FileReader } from './types';
+/** Where a line in the merged document originated. */
+export interface OriginEntry {
+    /** URI of the source file this line came from. */
+    uri: string;
+    /** 0-based line number within that source file. */
+    line: number;
+    /** Number of characters prepended to this line during merging (column shift). */
+    columnShift: number;
+}
+/** A problem with an `xi:include` element itself (missing target, cycle). */
+export interface IncludeProblem {
+    kind: "xinclude-missing" | "xinclude-circular";
+    message: string;
+    /** URI of the file containing the offending include. */
+    uri: string;
+    /** 0-based line of the include element. */
+    line: number;
+    /** 0-based start column of the include element. */
+    column: number;
+    /** Length of the matched include element text. */
+    length: number;
+}
+export interface ResolvedDocument {
+    /** The inlined document text with all includes expanded. */
+    text: string;
+    /** Per-line origin, indexed by 0-based line in {@link text}. */
+    origin: OriginEntry[];
+    /** Problems encountered resolving includes. */
+    problems: IncludeProblem[];
+}
+/** Default reader backed by Node's `fs`. */
+export declare function defaultFileReader(): FileReader;
+/**
+ * Expand every `xi:include` in `text`, producing a single merged document plus a
+ * per-line origin map so validation errors in included content can be mapped
+ * back to the file and line they actually came from.
+ *
+ * Handles nested includes and detects cycles and missing targets (reported as
+ * {@link IncludeProblem}s rather than throwing).
+ */
+export declare function resolveXIncludes(text: string, documentUri: string, readFile?: FileReader): ResolvedDocument;

package/eslint.config.cjs

@@ -0,0 +1,11 @@
+const baseConfig = require('../../.eslintrc.json');
+
+module.exports = [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    languageOptions: {
+      parser: require('jsonc-eslint-parser'),
+    },
+  },
+];

package/index.cjs

@@ -0,0 +1 @@
+module.exports = require('./dist/index.cjs');

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./dist/index.d.ts";

package/index.js

@@ -0,0 +1 @@
+export * from './dist/index.js';

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@pretextbook/schema",
+  "version": "0.0.1",
+  "description": "RELAX NG validation and context-aware completions for PreTeXt documents",
+  "author": "Oscar Levin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PreTeXtBook/pretext-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PreTeXtBook/pretext-tools/issues"
+  },
+  "homepage": "https://github.com/PreTeXtBook/pretext-tools/tree/main/packages/schema#readme",
+  "private": false,
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs",
+      "default": "./index.js"
+    },
+    "./compile": {
+      "types": "./compile.d.ts",
+      "import": "./compile.js",
+      "require": "./compile.cjs",
+      "default": "./compile.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "*.js",
+    "*.cjs",
+    "*.d.ts",
+    "*.d.cts",
+    "assets",
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "compile-grammar": "node ./scripts/compile-grammar.mjs",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "salve-annos": "^1.2.4",
+    "saxes": "^6.0.0",
+    "vscode-languageserver-types": "^3.17.5",
+    "xregexp": "^4.4.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}