@amritk/lint 0.0.0 → 0.2.0

package/dist/index.js

@@ -0,0 +1,168 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, resolve as resolvePath } from 'node:path';
+import { createRuleset as createCoreRuleset, lintWithResult, } from './core/index.js';
+import { createFixPlugin, FIX_PLUGIN_NAME } from './fix/index.js';
+import { builtinFunctions } from './functions/index.js';
+import { parseWithPointers } from './parsers/index.js';
+// Re-export the engine, built-in functions, and fix subsystem as the package's
+// public API. `export *` from `./core` also provides a low-level `createRuleset`,
+// but the higher-level wrapper defined below (which layers in the built-in
+// functions and file/package `extends` resolution) is the local export and wins.
+// Rendering findings is a consumer concern: `lintDocument` returns structured
+// `IDiagnostic[]`, and the caller decides how to display or serialize them.
+export * from './core/index.js';
+export * from './fix/index.js';
+export * from './functions/index.js';
+export { detectFormat, parseWithPointers } from './parsers/index.js';
+const require = createRequire(import.meta.url);
+/** Loads a ruleset definition from a file path by extension (YAML/JSON parsed, JS/CJS/MJS required). */
+const loadRulesetFile = (file) => {
+    if (/\.(ya?ml|json)$/i.test(file)) {
+        return parseWithPointers(readFileSync(file, 'utf8')).data;
+    }
+    const module = require(file);
+    return (module.default ?? module);
+};
+/**
+ * Resolves an `extends` reference to a ruleset definition. Supports:
+ * - local file paths (relative to `basePath`, or absolute): `.yaml` / `.yml` / `.json` / `.js`,
+ * - npm package specifiers (resolved from `basePath`), including subpaths.
+ *
+ * The engine ships no named built-in rulesets, so every string `extends` target
+ * is a file path or an npm package.
+ */
+export const resolveNamedRuleset = (name, basePath = process.cwd()) => {
+    if (name.startsWith('.') || isAbsolute(name)) {
+        const file = resolvePath(basePath, name);
+        return { definition: loadRulesetFile(file), basePath: dirname(file) };
+    }
+    let file;
+    try {
+        file = require.resolve(name, { paths: [basePath] });
+    }
+    catch {
+        throw new Error(`Cannot resolve extended ruleset "${name}" from ${basePath}`);
+    }
+    return { definition: loadRulesetFile(file), basePath: dirname(file) };
+};
+/** Loads a single custom function module (`<dir>/<name>.{js,cjs,mjs}` or a bare path). */
+const loadFunctionByName = (basePath, dir, name) => {
+    const baseFile = resolvePath(basePath, dir, name);
+    for (const candidate of [baseFile, `${baseFile}.js`, `${baseFile}.cjs`, `${baseFile}.mjs`]) {
+        try {
+            const resolvedFile = require.resolve(candidate);
+            const module = require(resolvedFile);
+            const fn = module.default ?? module;
+            if (typeof fn !== 'function')
+                throw new Error(`"${name}" did not export a function`);
+            return fn;
+        }
+        catch (error) {
+            if (error.code !== 'MODULE_NOT_FOUND')
+                throw error;
+        }
+    }
+    throw new Error(`Cannot resolve custom function "${name}" from ${resolvePath(basePath, dir)}`);
+};
+/**
+ * Walks a ruleset definition (and its string `extends`) collecting custom
+ * functions declared via `functions` / `functionsDir`, each loaded relative to
+ * the directory of the ruleset that declared it. YAML/JSON rulesets reference
+ * functions by name; JS rulesets can instead pass direct references in `then`.
+ */
+const collectCustomFunctions = (definition, basePath, into, seen) => {
+    if (seen.has(definition))
+        return;
+    seen.add(definition);
+    if (definition.extends) {
+        const entries = Array.isArray(definition.extends) ? definition.extends : [definition.extends];
+        for (const entry of entries) {
+            const target = Array.isArray(entry) ? entry[0] : entry;
+            if (typeof target === 'string') {
+                const resolved = resolveNamedRuleset(target, basePath);
+                collectCustomFunctions(resolved.definition, resolved.basePath, into, seen);
+            }
+            else {
+                collectCustomFunctions(target, basePath, into, seen);
+            }
+        }
+    }
+    if (Array.isArray(definition.functions)) {
+        const dir = definition.functionsDir ?? 'functions';
+        for (const name of definition.functions)
+            into[name] = loadFunctionByName(basePath, dir, name);
+    }
+};
+/**
+ * Builds a runnable {@link Ruleset} from a ruleset definition, layering the
+ * built-in functions (plus any custom ones the definition declares via
+ * `functions` / `functionsDir`) over the core engine and wiring up `extends`
+ * resolution against files and npm packages. With no definition it produces an
+ * empty ruleset (no rules run).
+ */
+export const createRuleset = (definition, basePath) => {
+    const resolved = definition ?? {};
+    // Custom functions referenced by name (YAML/JSON rulesets) are loaded relative
+    // to the declaring ruleset's directory and layered over the built-ins.
+    let functions = builtinFunctions;
+    const custom = {};
+    collectCustomFunctions(resolved, basePath ?? process.cwd(), custom, new Set());
+    if (Object.keys(custom).length > 0)
+        functions = { ...builtinFunctions, ...custom };
+    return createCoreRuleset(resolved, {
+        functions,
+        resolve: resolveNamedRuleset,
+        ...(basePath !== undefined ? { basePath } : {}),
+    });
+};
+/**
+ * Lints a JSON/YAML `input` end to end: parses with source maps and applies the
+ * ruleset. Returns just the findings; use {@link lintDocumentWithResult} for the
+ * full result.
+ */
+export const lintDocument = async (input, options = {}) => (await lintDocumentWithResult(input, options)).diagnostics;
+/**
+ * Like {@link lintDocument}, but returns the full {@link ILintResult} — including
+ * anything the configured `plugins` produced (e.g. the auto-fix plugin's
+ * rewritten `output`).
+ */
+export const lintDocumentWithResult = async (input, options = {}) => {
+    const { ruleset: rulesetDefinition, rulesetBasePath, resolve, plugins, ...documentOptions } = options;
+    const ruleset = createRuleset(rulesetDefinition, rulesetBasePath);
+    return lintWithResult(input, {
+        ...documentOptions,
+        ruleset,
+        ...(resolve ? { resolve } : {}),
+        ...(plugins ? { plugins } : {}),
+    });
+};
+// One fix pass can unblock the next, so we lint-and-fix to a fixpoint. The cap is
+// a safety net against a fixer that oscillates rather than converging — in
+// practice a couple of passes is plenty.
+const MAX_FIX_PASSES = 10;
+/**
+ * Lints a document and applies the supplied `fixers` repeatedly until the
+ * document stops changing (or {@link MAX_FIX_PASSES} is reached), then re-lints
+ * so `remaining` reflects the fixed document. A one-call convenience over
+ * {@link lintDocumentWithResult} + `createFixPlugin`. With no `fixers` this is a
+ * no-op that just returns the findings.
+ */
+export const fixDocument = async (input, options = {}) => {
+    const { fixers = {}, safeOnly, ...lintOptions } = options;
+    const plugin = createFixPlugin(fixers, { safeOnly: safeOnly !== false });
+    let current = input;
+    const applied = [];
+    for (let pass = 0; pass < MAX_FIX_PASSES; pass++) {
+        const result = await lintDocumentWithResult(current, { ...lintOptions, plugins: [plugin] });
+        // No rewrite, or a rewrite that matches what we already have, means we have converged.
+        if (result.output === undefined || result.output === current)
+            break;
+        current = result.output;
+        const data = result.pluginData[FIX_PLUGIN_NAME];
+        if (data)
+            applied.push(...data.applied);
+    }
+    const remaining = await lintDocument(current, lintOptions);
+    return { output: current, fixed: applied.length > 0, remaining, applied };
+};

package/dist/parsers/edit-model.d.ts

@@ -0,0 +1,69 @@
+import type { ParserFormat } from './index.js';
+import type { JsonPath } from './types.js';
+/**
+ * A single structural edit against a parsed document, expressed in terms of JSON
+ * paths and values rather than raw character offsets. {@link applyEditOps} lowers
+ * each op to a minimal text edit so that untouched parts of the source — including
+ * comments, key order, and quoting — keep their original formatting.
+ */
+export type EditOp = 
+/** Replace the scalar value at `path` (the existing quoting style is preserved). */
+{
+    op: 'setValue';
+    path: JsonPath;
+    value: unknown;
+}
+/** Remove the object property at `path` (the last segment is the key). */
+ | {
+    op: 'removeProperty';
+    path: JsonPath;
+}
+/** Rename the object property at `path` (the last segment is the current key). */
+ | {
+    op: 'renameProperty';
+    path: JsonPath;
+    newKey: string;
+}
+/** Remove the listed array indices from the array at `path`. */
+ | {
+    op: 'removeItems';
+    path: JsonPath;
+    indices: number[];
+}
+/** Reorder the array at `path`; `order` lists the original indices in their new order. */
+ | {
+    op: 'reorderArray';
+    path: JsonPath;
+    order: number[];
+}
+/** Add a `key: value` property to the object at `path` (a no-op when the key already exists). */
+ | {
+    op: 'insertProperty';
+    path: JsonPath;
+    key: string;
+    value: unknown;
+}
+/** Insert `value` into the array at `path` at `index` (appended when `index` is omitted). */
+ | {
+    op: 'insertItem';
+    path: JsonPath;
+    value: unknown;
+    index?: number;
+};
+/** The text after applying a batch of edits, plus which ops actually changed it. */
+export type ApplyEditOpsResult = {
+    output: string;
+    /** `changed[i]` is whether `ops[i]` altered the text (false when its path no longer resolved). */
+    changed: boolean[];
+};
+/**
+ * Applies `ops` to `source`, reporting both the edited text and, per op, whether
+ * it actually changed anything. Each op is lowered to a minimal text edit and
+ * applied sequentially (re-parsing between ops so offsets stay valid), preserving
+ * the formatting of everything it does not touch. An op whose target path no
+ * longer resolves is a no-op rather than an error — callers use `changed` to tell
+ * a real fix from one that quietly dropped out (e.g. its node was already gone).
+ */
+export declare const applyEditOpsWithChanges: (source: string, format: ParserFormat, ops: EditOp[]) => ApplyEditOpsResult;
+/** Applies `ops` to `source` and returns just the edited text. See {@link applyEditOpsWithChanges}. */
+export declare const applyEditOps: (source: string, format: ParserFormat, ops: EditOp[]) => string;

package/dist/parsers/edit-model.js

@@ -0,0 +1,326 @@
+import { isMap, isScalar, isSeq, parseDocument } from '@amritk/yaml';
+import { applyEdits, findNodeAtLocation, getNodeValue, modify, parseTree } from 'jsonc-parser';
+const splice = (text, start, end, replacement) => text.slice(0, start) + replacement + text.slice(end);
+/** Expands `[start, end)` to cover whole lines: back to the line start, forward past the trailing newline. */
+const expandLine = (text, start, end) => {
+    let s = start;
+    while (s > 0 && text.charCodeAt(s - 1) !== 10)
+        s--;
+    let e = end;
+    while (e < text.length && text.charCodeAt(e) !== 10)
+        e++;
+    if (e < text.length)
+        e++;
+    return [s, e];
+};
+// --- YAML ------------------------------------------------------------------
+const keyName = (key) => (isScalar(key) ? String(key.value) : String(key));
+/** Navigates the YAML CST to the node at `path`, or `undefined` if absent. */
+const yamlNodeAt = (root, path) => {
+    let current = root ?? undefined;
+    for (const segment of path) {
+        if (current === undefined)
+            return undefined;
+        if (isMap(current)) {
+            const target = String(segment);
+            const pair = current.items.find((item) => keyName(item.key) === target);
+            current = pair?.value ?? undefined;
+        }
+        else if (isSeq(current)) {
+            current = current.items[Number(segment)];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+};
+/** Resolves the key/value CST nodes of the property at `path` (last segment = key). */
+const yamlPairAt = (root, path) => {
+    const parent = yamlNodeAt(root, path.slice(0, -1));
+    if (!parent || !isMap(parent))
+        return {};
+    const last = String(path[path.length - 1]);
+    const pair = parent.items.find((item) => keyName(item.key) === last);
+    if (!pair)
+        return {};
+    return { key: pair.key, ...(pair.value ? { value: pair.value } : {}) };
+};
+/** Serializes a scalar, preserving the quoting style of the value it replaces. */
+const yamlScalar = (value, original) => {
+    if (typeof value !== 'string')
+        return value === null ? 'null' : String(value);
+    const quote = original.charCodeAt(0);
+    if (quote === 34 /* " */)
+        return JSON.stringify(value);
+    if (quote === 39 /* ' */)
+        return `'${value.replace(/'/g, "''")}'`;
+    return value;
+};
+const yamlKey = (key, original) => {
+    const quote = original.charCodeAt(0);
+    if (quote === 34)
+        return JSON.stringify(key);
+    if (quote === 39)
+        return `'${key.replace(/'/g, "''")}'`;
+    return key;
+};
+// Keys made only of these characters are safe to write bare in YAML; anything
+// else (spaces, colons, flow indicators) gets double-quoted to stay valid.
+const SAFE_YAML_KEY = /^[\w./-]+$/;
+/** Serializes a key for an inserted property, quoting it only when it needs to be. */
+const yamlInsertKey = (key) => (SAFE_YAML_KEY.test(key) ? key : JSON.stringify(key));
+/**
+ * Serializes a value for insertion. YAML is a JSON superset, so JSON output is
+ * always valid YAML: scalars become bare literals (`42`, `true`, `"text"`) and
+ * objects/arrays become inline flow (`{"a":1}`). That keeps the inserted node on
+ * one line without us having to re-implement a block serializer.
+ */
+const yamlInsertValue = (value) => JSON.stringify(value) ?? 'null';
+/** Returns the leading whitespace of the line containing `offset` (its indentation). */
+const lineIndent = (text, offset) => {
+    let start = offset;
+    while (start > 0 && text.charCodeAt(start - 1) !== 10)
+        start--;
+    let end = start;
+    while (end < text.length && (text.charCodeAt(end) === 32 || text.charCodeAt(end) === 9))
+        end++;
+    return text.slice(start, end);
+};
+const applyYamlOp = (text, op) => {
+    const root = parseDocument(text).contents;
+    switch (op.op) {
+        case 'setValue': {
+            const node = yamlNodeAt(root, op.path);
+            if (!node)
+                return text;
+            // Scalars keep the node's original quoting; objects/arrays are written as
+            // inline flow JSON (valid YAML) so a scalar can be widened to a collection.
+            const replacement = op.value !== null && typeof op.value === 'object'
+                ? yamlInsertValue(op.value)
+                : yamlScalar(op.value, text.slice(node.start, node.end));
+            return splice(text, node.start, node.end, replacement);
+        }
+        case 'renameProperty': {
+            const { key } = yamlPairAt(root, op.path);
+            if (!key)
+                return text;
+            return splice(text, key.start, key.end, yamlKey(op.newKey, text.slice(key.start, key.end)));
+        }
+        case 'removeProperty': {
+            const parent = yamlNodeAt(root, op.path.slice(0, -1));
+            if (!parent || !isMap(parent))
+                return text;
+            const last = String(op.path[op.path.length - 1]);
+            const index = parent.items.findIndex((item) => keyName(item.key) === last);
+            if (index === -1)
+                return text;
+            const pair = parent.items[index];
+            const key = pair?.key;
+            const value = pair?.value;
+            // Flow map (`{ a: 1, b: 2 }`): excise just this member plus one adjoining
+            // comma, keeping the braces and the surviving members on their shared line.
+            if (text.charCodeAt(parent.start) === 123 /* { */) {
+                if (parent.items.length === 1)
+                    return splice(text, parent.start + 1, parent.end - 1, '');
+                // Not the last member: take the comma and gap up to the next key.
+                if (index < parent.items.length - 1) {
+                    const next = parent.items[index + 1]?.key;
+                    return splice(text, key.start, next.start, '');
+                }
+                // Last member: take the trailing comma and gap left by the previous one.
+                const prev = parent.items[index - 1];
+                const prevEnd = (prev?.value ?? prev?.key).end;
+                return splice(text, prevEnd, (value ?? key).end, '');
+            }
+            // Block map: drop the whole line(s) the property occupies.
+            const [start, end] = expandLine(text, key.start, value ? value.end : key.end);
+            return splice(text, start, end, '');
+        }
+        case 'removeItems': {
+            const seq = yamlNodeAt(root, op.path);
+            if (!seq || !isSeq(seq))
+                return text;
+            const removed = new Set(op.indices);
+            return rewriteYamlSeq(text, seq, seq.items.filter((_, index) => !removed.has(index)));
+        }
+        case 'reorderArray': {
+            const seq = yamlNodeAt(root, op.path);
+            if (!seq || !isSeq(seq) || seq.items.length === 0)
+                return text;
+            const reordered = op.order.map((index) => seq.items[index]).filter((item) => item != null);
+            return rewriteYamlSeq(text, seq, reordered);
+        }
+        case 'insertProperty': {
+            const parent = yamlNodeAt(root, op.path);
+            if (!parent || !isMap(parent))
+                return text;
+            // Inserting is additive only; if the key is already there we leave it alone.
+            if (parent.items.some((item) => keyName(item.key) === op.key))
+                return text;
+            const pair = `${yamlInsertKey(op.key)}: ${yamlInsertValue(op.value)}`;
+            if (text.charCodeAt(parent.start) === 123 /* { */) {
+                const last = parent.items[parent.items.length - 1];
+                // Append right after the last entry (keeping the brace's own spacing); an
+                // empty `{}` gets the pair tucked just inside the opening brace.
+                if (last) {
+                    const lastEnd = (last.value ?? last.key).end;
+                    return splice(text, lastEnd, lastEnd, `, ${pair}`);
+                }
+                return splice(text, parent.start + 1, parent.start + 1, pair);
+            }
+            // Block map: mirror the existing keys' indentation and add a line after the last one.
+            const last = parent.items[parent.items.length - 1];
+            const lastKey = last?.key;
+            if (!lastKey)
+                return text;
+            const indent = lineIndent(text, lastKey.start);
+            const [, end] = expandLine(text, lastKey.start, (last?.value ?? lastKey).end);
+            const lead = end > 0 && text.charCodeAt(end - 1) !== 10 ? '\n' : '';
+            return splice(text, end, end, `${lead}${indent}${pair}\n`);
+        }
+        case 'insertItem': {
+            const seq = yamlNodeAt(root, op.path);
+            if (!seq || !isSeq(seq))
+                return text;
+            const value = yamlInsertValue(op.value);
+            if (text.charCodeAt(seq.start) === 91 /* [ */) {
+                const items = seq.items.map((item) => text.slice(item.start, item.end));
+                items.splice(clampIndex(op.index, items.length), 0, value);
+                return splice(text, seq.start + 1, seq.end - 1, items.join(', '));
+            }
+            // Block sequence: we need an existing `- item` line to mirror its indentation and style.
+            if (seq.items.length === 0)
+                return text;
+            const blocks = seq.items.map((item) => expandLine(text, item.start, item.end));
+            const regionStart = blocks[0][0];
+            const regionEnd = blocks[blocks.length - 1][1];
+            const lines = seq.items.map((_, index) => text.slice(...blocks[index]));
+            lines.splice(clampIndex(op.index, lines.length), 0, `${lineIndent(text, regionStart)}- ${value}\n`);
+            return splice(text, regionStart, regionEnd, lines.join(''));
+        }
+    }
+};
+/** Clamps an optional insertion index into `[0, length]`, defaulting to an append. */
+const clampIndex = (index, length) => Math.max(0, Math.min(index ?? length, length));
+/**
+ * Rewrites a YAML sequence to contain exactly `newItems` (a subset and/or
+ * reordering of the original nodes), preserving each kept item's own text. Flow
+ * sequences (`[a, b]`) are rebuilt inside their brackets; block sequences (one
+ * `- item` per line) are rebuilt from their whole-line spans.
+ */
+const rewriteYamlSeq = (text, seq, newItems) => {
+    const isFlow = text.charCodeAt(seq.start) === 91; /* [ */
+    if (isFlow) {
+        const inner = newItems.map((item) => text.slice(item.start, item.end)).join(', ');
+        return splice(text, seq.start + 1, seq.end - 1, inner);
+    }
+    if (seq.items.length === 0)
+        return text;
+    const blocks = seq.items.map((item) => expandLine(text, item.start, item.end));
+    const regionStart = blocks[0][0];
+    const regionEnd = blocks[blocks.length - 1][1];
+    const blockText = new Map(seq.items.map((item, index) => [item, text.slice(...blocks[index])]));
+    const rebuilt = newItems.map((item) => blockText.get(item) ?? '').join('');
+    return splice(text, regionStart, regionEnd, rebuilt);
+};
+// --- JSON ------------------------------------------------------------------
+const JSON_FORMAT = { insertSpaces: true, tabSize: 2, eol: '\n' };
+/**
+ * jsonc-parser keys path segments by JS type — strings index objects, numbers
+ * index arrays — but a finding's path carries numeric-like object keys (e.g. a
+ * `"200"` response) as plain numbers. Walk the tree and coerce each segment to
+ * the type its parent expects, so both keys and indices resolve (and `modify`
+ * doesn't mistake a `"200"` key for an array index and throw).
+ */
+const normalizeJsonPath = (root, path) => {
+    const result = [];
+    let node = root;
+    for (const segment of path) {
+        const normalized = node?.type === 'array' ? Number(segment) : String(segment);
+        result.push(normalized);
+        node = node ? findNodeAtLocation(node, [normalized]) : undefined;
+    }
+    return result;
+};
+const applyJsonOp = (text, op) => {
+    const root = parseTree(text);
+    if (!root)
+        return text;
+    const path = normalizeJsonPath(root, op.path);
+    switch (op.op) {
+        case 'setValue':
+            return applyEdits(text, modify(text, path, op.value, { formattingOptions: JSON_FORMAT }));
+        case 'removeProperty':
+            return applyEdits(text, modify(text, path, undefined, { formattingOptions: JSON_FORMAT }));
+        case 'renameProperty': {
+            const valueNode = findNodeAtLocation(root, path);
+            const keyNode = valueNode?.parent?.children?.[0];
+            if (!keyNode)
+                return text;
+            return splice(text, keyNode.offset, keyNode.offset + keyNode.length, JSON.stringify(op.newKey));
+        }
+        case 'removeItems': {
+            // jsonc-parser's per-index array removal is unreliable, so rewrite the
+            // whole array with the kept elements instead.
+            const node = findNodeAtLocation(root, path);
+            if (!node)
+                return text;
+            const removed = new Set(op.indices);
+            const kept = getNodeValue(node).filter((_, index) => !removed.has(index));
+            return applyEdits(text, modify(text, path, kept, { formattingOptions: JSON_FORMAT }));
+        }
+        case 'reorderArray': {
+            const node = findNodeAtLocation(root, path);
+            if (!node)
+                return text;
+            const array = getNodeValue(node);
+            const reordered = op.order.map((index) => array[index]);
+            return applyEdits(text, modify(text, path, reordered, { formattingOptions: JSON_FORMAT }));
+        }
+        case 'insertProperty': {
+            const node = findNodeAtLocation(root, path);
+            if (!node || node.type !== 'object')
+                return text;
+            // Additive only: writing to an existing key would replace its value, so bail.
+            if (node.children?.some((property) => property.children?.[0]?.value === op.key))
+                return text;
+            return applyEdits(text, modify(text, [...path, op.key], op.value, { formattingOptions: JSON_FORMAT }));
+        }
+        case 'insertItem': {
+            const node = findNodeAtLocation(root, path);
+            if (!node || node.type !== 'array')
+                return text;
+            const index = clampIndex(op.index, node.children?.length ?? 0);
+            return applyEdits(text, modify(text, [...path, index], op.value, { formattingOptions: JSON_FORMAT, isArrayInsertion: true }));
+        }
+    }
+};
+/**
+ * Applies `ops` to `source`, reporting both the edited text and, per op, whether
+ * it actually changed anything. Each op is lowered to a minimal text edit and
+ * applied sequentially (re-parsing between ops so offsets stay valid), preserving
+ * the formatting of everything it does not touch. An op whose target path no
+ * longer resolves is a no-op rather than an error — callers use `changed` to tell
+ * a real fix from one that quietly dropped out (e.g. its node was already gone).
+ */
+export const applyEditOpsWithChanges = (source, format, ops) => {
+    let text = source;
+    const changed = [];
+    for (const op of ops) {
+        const before = text;
+        // An op that can't be lowered (an unresolved path, a key the underlying
+        // editor rejects) must be a no-op, never a thrown error that aborts the
+        // whole batch — one bad edit should not drop every other fix.
+        try {
+            text = format === 'json' ? applyJsonOp(text, op) : applyYamlOp(text, op);
+        }
+        catch {
+            text = before;
+        }
+        changed.push(text !== before);
+    }
+    return { output: text, changed };
+};
+/** Applies `ops` to `source` and returns just the edited text. See {@link applyEditOpsWithChanges}. */
+export const applyEditOps = (source, format, ops) => applyEditOpsWithChanges(source, format, ops).output;

package/dist/parsers/index.d.ts

@@ -0,0 +1,18 @@
+export { type ApplyEditOpsResult, applyEditOps, applyEditOpsWithChanges, type EditOp } from './edit-model.js';
+export { parseJson } from './json.js';
+export { createLineMap, type LineMap } from './lines.js';
+export * from './types.js';
+export { parseYaml } from './yaml.js';
+import type { IParseResult, IParserOptions } from './types.js';
+/** Which concrete parser a document is routed to. */
+export type ParserFormat = 'yaml' | 'json';
+/** Guesses the format from the first non-whitespace character (`{`/`[` ⇒ JSON, else YAML). */
+export declare const detectFormat: (source: string) => ParserFormat;
+/**
+ * Parses a document with source maps. YAML is a JSON superset, so the YAML
+ * parser is the default and handles both; the JSON parser is used when a strict
+ * JSON document is detected or requested (it reports JSON-specific errors).
+ */
+export declare const parseWithPointers: <T = unknown>(source: string, options?: IParserOptions & {
+    format?: ParserFormat;
+}) => IParseResult<T>;

package/dist/parsers/index.js

@@ -0,0 +1,21 @@
+export { applyEditOps, applyEditOpsWithChanges } from './edit-model.js';
+export { parseJson } from './json.js';
+export { createLineMap } from './lines.js';
+export * from './types.js';
+export { parseYaml } from './yaml.js';
+import { parseJson } from './json.js';
+import { parseYaml } from './yaml.js';
+/** Guesses the format from the first non-whitespace character (`{`/`[` ⇒ JSON, else YAML). */
+export const detectFormat = (source) => {
+    const trimmed = source.trimStart();
+    return trimmed.startsWith('{') || trimmed.startsWith('[') ? 'json' : 'yaml';
+};
+/**
+ * Parses a document with source maps. YAML is a JSON superset, so the YAML
+ * parser is the default and handles both; the JSON parser is used when a strict
+ * JSON document is detected or requested (it reports JSON-specific errors).
+ */
+export const parseWithPointers = (source, options = {}) => {
+    const format = options.format ?? detectFormat(source);
+    return format === 'json' ? parseJson(source) : parseYaml(source, options);
+};

package/dist/parsers/json.d.ts

@@ -0,0 +1,3 @@
+import { type IParseResult } from './types.js';
+/** Parses strict JSON into data plus a source map, reporting JSON-specific syntax errors. */
+export declare const parseJson: <T = unknown>(source: string) => IParseResult<T>;

package/dist/parsers/json.js

@@ -0,0 +1,38 @@
+import { findNodeAtLocation, getNodeValue, parseTree, printParseErrorCode } from 'jsonc-parser';
+import { createLineMap } from './lines.js';
+import { DiagnosticSeverity } from './types.js';
+/** Parses strict JSON into data plus a source map, reporting JSON-specific syntax errors. */
+export const parseJson = (source) => {
+    const lineMap = createLineMap(source);
+    const errors = [];
+    const root = parseTree(source, errors, { allowTrailingComma: false, disallowComments: true });
+    const data = (root ? getNodeValue(root) : undefined);
+    const diagnostics = errors.map((err) => ({
+        message: printParseErrorCode(err.error),
+        severity: DiagnosticSeverity.Error,
+        range: {
+            start: lineMap.positionAt(err.offset),
+            end: lineMap.positionAt(err.offset + err.length),
+        },
+    }));
+    const getLocationForJsonPath = (path, closest = false) => {
+        if (!root)
+            return undefined;
+        const p = path.slice();
+        while (true) {
+            const node = findNodeAtLocation(root, p);
+            if (node) {
+                return {
+                    range: {
+                        start: lineMap.positionAt(node.offset),
+                        end: lineMap.positionAt(node.offset + node.length),
+                    },
+                };
+            }
+            if (!closest || p.length === 0)
+                return undefined;
+            p.pop();
+        }
+    };
+    return { data, diagnostics, getLocationForJsonPath };
+};

package/dist/parsers/lines.d.ts

@@ -0,0 +1,13 @@
+import type { IPosition } from './types.js';
+/**
+ * Resolves byte/char offsets to `{ line, character }` positions. Lines and
+ * characters are zero-based, matching LSP / Linter conventions.
+ */
+export type LineMap = {
+    positionAt(offset: number): IPosition;
+};
+/**
+ * Builds a {@link LineMap} for `source`. The line-start offsets are precomputed
+ * once so each `positionAt` lookup is a binary search rather than a re-scan.
+ */
+export declare const createLineMap: (source: string) => LineMap;