@amritk/lint 0.2.0 → 0.3.1

package/dist/parsers/edit-model.js

@@ -1,11 +1,16 @@
-import { isMap, isScalar, isSeq, parseDocument } from '@amritk/yaml';
-import { applyEdits, findNodeAtLocation, getNodeValue, modify, parseTree } from 'jsonc-parser';
+import { isAlias, isMap, isScalar, isSeq, parseDocument } from '@amritk/yaml';
+import { applyEdits, findNodeAtLocation, 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;
+/** The offset of the start of the line containing `offset`. */
+const lineStart = (text, offset) => {
+    let s = offset;
     while (s > 0 && text.charCodeAt(s - 1) !== 10)
         s--;
+    return s;
+};
+/** Expands `[start, end)` to cover whole lines: back to the line start, forward past the trailing newline. */
+const expandLine = (text, start, end) => {
+    const s = lineStart(text, start);
     let e = end;
     while (e < text.length && text.charCodeAt(e) !== 10)
         e++;
@@ -13,8 +18,32 @@ const expandLine = (text, start, end) => {
         e++;
     return [s, e];
 };
+/**
+ * The document's dominant line ending. We look at the first break so inserted
+ * lines match the file rather than always emitting a bare `\n` (which would leave
+ * a CRLF file with mixed endings).
+ */
+const detectEol = (text) => {
+    const i = text.indexOf('\n');
+    return i > 0 && text.charCodeAt(i - 1) === 13 ? '\r\n' : '\n';
+};
 // --- YAML ------------------------------------------------------------------
-const keyName = (key) => (isScalar(key) ? String(key.value) : String(key));
+/**
+ * Stringifies a key the way `toJS` does, so the paths we address by match the
+ * keys the projected data exposes: a null key is `null`, a bool/number key is its
+ * `String()` form, an alias key is `*name`, and a complex (map/seq) key is empty.
+ */
+const keyName = (key) => {
+    if (isScalar(key)) {
+        const v = key.value;
+        return typeof v === 'string' ? v : v === null ? 'null' : String(v);
+    }
+    if (isAlias(key))
+        return `*${key.source}`;
+    if (isMap(key) || isSeq(key))
+        return '';
+    return String(key);
+};
 /** Navigates the YAML CST to the node at `path`, or `undefined` if absent. */
 const yamlNodeAt = (root, path) => {
     let current = root ?? undefined;
@@ -23,7 +52,10 @@ const yamlNodeAt = (root, path) => {
             return undefined;
         if (isMap(current)) {
             const target = String(segment);
-            const pair = current.items.find((item) => keyName(item.key) === target);
+            // Last-wins: duplicate keys resolve to the final occurrence, matching how
+            // `toJS` and the position index treat them, so an edit is not a silent no-op
+            // that lands on a shadowed earlier copy.
+            const pair = current.items.findLast((item) => keyName(item.key) === target);
             current = pair?.value ?? undefined;
         }
         else if (isSeq(current)) {
@@ -41,11 +73,25 @@ const yamlPairAt = (root, path) => {
     if (!parent || !isMap(parent))
         return {};
     const last = String(path[path.length - 1]);
-    const pair = parent.items.find((item) => keyName(item.key) === last);
+    const pair = parent.items.findLast((item) => keyName(item.key) === last);
     if (!pair)
         return {};
     return { key: pair.key, ...(pair.value ? { value: pair.value } : {}) };
 };
+/**
+ * Checks that writing `plain` bare into YAML round-trips back to the string
+ * `value`. A bare scalar can silently change meaning — `true` becomes a boolean,
+ * `1.0` a number, an empty string a null — and text carrying `: ` or ` #` or a
+ * newline reshapes the line, so we parse the candidate on its own and require it
+ * to come back as exactly the same string before trusting it unquoted.
+ */
+const plainStringRoundTrips = (plain, value) => {
+    const doc = parseDocument(plain);
+    return doc.errors.length === 0 && isScalar(doc.contents) && doc.contents.value === value;
+};
+// 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 scalar, preserving the quoting style of the value it replaces. */
 const yamlScalar = (value, original) => {
     if (typeof value !== 'string')
@@ -55,7 +101,10 @@ const yamlScalar = (value, original) => {
         return JSON.stringify(value);
     if (quote === 39 /* ' */)
         return `'${value.replace(/'/g, "''")}'`;
-    return value;
+    // Plain (unquoted) original: keep it bare only when the bare text still means
+    // this exact string; otherwise fall back to a double-quoted literal so we never
+    // turn a string into a bool/number/null or corrupt the line.
+    return plainStringRoundTrips(value, value) ? value : JSON.stringify(value);
 };
 const yamlKey = (key, original) => {
     const quote = original.charCodeAt(0);
@@ -63,11 +112,10 @@ const yamlKey = (key, original) => {
         return JSON.stringify(key);
     if (quote === 39)
         return `'${key.replace(/'/g, "''")}'`;
-    return key;
+    // A plain key that would resolve to a non-string (e.g. `true`, `1.0`) or is not
+    // otherwise safe bare gets quoted, matching the value-side treatment.
+    return SAFE_YAML_KEY.test(key) && plainStringRoundTrips(key, key) ? key : JSON.stringify(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));
 /**
@@ -77,23 +125,54 @@ const yamlInsertKey = (key) => (SAFE_YAML_KEY.test(key) ? key : JSON.stringify(k
  * one line without us having to re-implement a block serializer.
  */
 const yamlInsertValue = (value) => JSON.stringify(value) ?? 'null';
+/** Serializes a fresh scalar (no original to mirror), quoting strings only when bare would change meaning. */
+const yamlFreshScalar = (value) => {
+    if (value !== null && typeof value === 'object')
+        return yamlInsertValue(value);
+    if (typeof value === 'string')
+        return plainStringRoundTrips(value, value) ? value : JSON.stringify(value);
+    return value === null ? 'null' : String(value);
+};
 /** 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--;
+    const start = lineStart(text, offset);
     let end = start;
     while (end < text.length && (text.charCodeAt(end) === 32 || text.charCodeAt(end) === 9))
         end++;
     return text.slice(start, end);
 };
+/**
+ * The indentation a new block-sequence item should carry, measured from the
+ * column of the first item's own `- ` dash. Using the dash column (not the line's
+ * leading whitespace) keeps a nested sequence correct: for `- - 1` the inner
+ * item's dash sits at column 2, so a new inner item indents to match it rather
+ * than appending to the outer sequence.
+ */
+const seqItemIndent = (text, firstItem) => {
+    const start = lineStart(text, firstItem.start);
+    let dash = firstItem.start - 1;
+    while (dash > start && text.charCodeAt(dash) !== 45 /* - */)
+        dash--;
+    return text.charCodeAt(dash) === 45 ? ' '.repeat(dash - start) : lineIndent(text, firstItem.start);
+};
 const applyYamlOp = (text, op) => {
     const root = parseDocument(text).contents;
+    const eol = detectEol(text);
     switch (op.op) {
         case 'setValue': {
             const node = yamlNodeAt(root, op.path);
-            if (!node)
+            if (!node) {
+                // The target may be an explicit-empty key (`key:` with a null value). The
+                // value node does not exist yet, so splice a scalar in right after the
+                // colon rather than silently doing nothing.
+                const { key, value } = yamlPairAt(root, op.path);
+                if (key && value === undefined) {
+                    const colon = text.indexOf(':', key.end);
+                    if (colon !== -1)
+                        return splice(text, colon + 1, colon + 1, ` ${yamlFreshScalar(op.value)}`);
+                }
                 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'
@@ -112,7 +191,7 @@ const applyYamlOp = (text, op) => {
             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);
+            const index = parent.items.findLastIndex((item) => keyName(item.key) === last);
             if (index === -1)
                 return text;
             const pair = parent.items[index];
@@ -133,6 +212,17 @@ const applyYamlOp = (text, op) => {
                 const prevEnd = (prev?.value ?? prev?.key).end;
                 return splice(text, prevEnd, (value ?? key).end, '');
             }
+            // Compact sequence-entry map (`- a: 1\n    b: 2`): the first pair shares its
+            // line with the parent seq's `- ` dash. Dropping the whole line would swallow
+            // the dash and merge this item into its sibling, so splice only the pair's own
+            // span. A lone key falls through to whole-line removal (the item disappears).
+            const dashPrefix = text.slice(lineStart(text, key.start), key.start);
+            if (/^\s*-\s+$/.test(dashPrefix) && parent.items.length > 1) {
+                const next = parent.items[index + 1]?.key;
+                if (next)
+                    return splice(text, key.start, next.start, '');
+                return splice(text, key.start, (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, '');
@@ -153,7 +243,21 @@ const applyYamlOp = (text, op) => {
         }
         case 'insertProperty': {
             const parent = yamlNodeAt(root, op.path);
-            if (!parent || !isMap(parent))
+            if (!parent) {
+                // The target may be an explicit-empty key (`parent:` with a null value).
+                // Turn it into a one-key block map on the next line rather than no-op.
+                const { key, value } = yamlPairAt(root, op.path);
+                if (key && value === undefined) {
+                    const colon = text.indexOf(':', key.end);
+                    if (colon !== -1) {
+                        const indent = ' '.repeat(key.start - lineStart(text, key.start) + 2);
+                        const pair = `${yamlInsertKey(op.key)}: ${yamlInsertValue(op.value)}`;
+                        return splice(text, colon + 1, colon + 1, `${eol}${indent}${pair}`);
+                    }
+                }
+                return text;
+            }
+            if (!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))
@@ -174,10 +278,15 @@ const applyYamlOp = (text, op) => {
             const lastKey = last?.key;
             if (!lastKey)
                 return text;
-            const indent = lineIndent(text, lastKey.start);
+            // Indent from the key's *column*, not the line's leading whitespace: in a
+            // compact seq-item map the last key sits after a `- ` dash, so the line
+            // indent (2) would place the new key outside the item — use the column (4).
+            const keyLineStart = lineStart(text, lastKey.start);
+            const prefix = text.slice(keyLineStart, lastKey.start);
+            const indent = /^\s*$/.test(prefix) ? prefix : ' '.repeat(lastKey.start - keyLineStart);
             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`);
+            const lead = end > 0 && text.charCodeAt(end - 1) !== 10 ? eol : '';
+            return splice(text, end, end, `${lead}${indent}${pair}${eol}`);
         }
         case 'insertItem': {
             const seq = yamlNodeAt(root, op.path);
@@ -192,22 +301,41 @@ const applyYamlOp = (text, op) => {
             // 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 blocks = seqBlocks(text, seq.items);
             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`);
+            const newLine = `${seqItemIndent(text, seq.items[0])}- ${value}${eol}`;
+            lines.splice(clampIndex(op.index, lines.length), 0, newLine);
             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));
+/**
+ * Whole-line spans for each block-sequence item, with any comment-only or blank
+ * lines that precede an item folded into that item's block. Attaching leading
+ * comments to the following item means a reorder carries them along and a removal
+ * takes only the comments that belong to the dropped item — honoring the module's
+ * promise to preserve comments rather than dropping every line between items.
+ */
+const seqBlocks = (text, items) => {
+    const blocks = [];
+    items.forEach((item, i) => {
+        const [start, end] = expandLine(text, item.start, item.end);
+        // For every item after the first, start the block at the end of the previous
+        // item's line so the comment/blank lines between the two travel with this item.
+        blocks.push([i === 0 ? start : blocks[i - 1][1], end]);
+    });
+    return blocks;
+};
 /**
  * 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.
+ * `- item` per line) are rebuilt from their whole-line spans, carrying each item's
+ * preceding comments with it.
  */
 const rewriteYamlSeq = (text, seq, newItems) => {
     const isFlow = text.charCodeAt(seq.start) === 91; /* [ */
@@ -217,7 +345,7 @@ const rewriteYamlSeq = (text, seq, newItems) => {
     }
     if (seq.items.length === 0)
         return text;
-    const blocks = seq.items.map((item) => expandLine(text, item.start, item.end));
+    const blocks = seqBlocks(text, seq.items);
     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])]));
@@ -225,7 +353,12 @@ const rewriteYamlSeq = (text, seq, newItems) => {
     return splice(text, regionStart, regionEnd, rebuilt);
 };
 // --- JSON ------------------------------------------------------------------
-const JSON_FORMAT = { insertSpaces: true, tabSize: 2, eol: '\n' };
+/** Formatting options for jsonc-parser edits, carrying the file's own line ending. */
+const jsonFormat = (eol) => ({
+    insertSpaces: true,
+    tabSize: 2,
+    eol,
+});
 /**
  * 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
@@ -243,40 +376,76 @@ const normalizeJsonPath = (root, path) => {
     }
     return result;
 };
+/**
+ * Rewrites a JSON array to contain exactly `keptChildren`, slicing each element's
+ * original source so numeric literals (`1.50`), escapes, and Unicode survive byte
+ * for byte. Separators, leading, and trailing whitespace are taken from the
+ * original array, so a one-line array stays on one line and a multi-line array
+ * keeps its indentation instead of being re-serialized with a hardcoded style.
+ */
+const rewriteJsonArray = (text, node, keptChildren) => {
+    const children = node.children ?? [];
+    const open = node.offset + 1;
+    const close = node.offset + node.length - 1;
+    if (children.length === 0)
+        return text;
+    const first = children[0];
+    const last = children[children.length - 1];
+    if (keptChildren.length === 0)
+        return splice(text, open, close, '');
+    const leading = text.slice(open, first.offset);
+    const trailing = text.slice(last.offset + last.length, close);
+    // The separator between two elements, captured from the source so we reuse the
+    // file's own comma, newline, and indentation rather than inventing them.
+    const separator = children.length > 1 ? text.slice(first.offset + first.length, children[1].offset) : ', ';
+    const inner = keptChildren.map((child) => text.slice(child.offset, child.offset + child.length)).join(separator);
+    return splice(text, open, close, leading + inner + trailing);
+};
 const applyJsonOp = (text, op) => {
     const root = parseTree(text);
     if (!root)
         return text;
     const path = normalizeJsonPath(root, op.path);
+    const format = jsonFormat(detectEol(text));
     switch (op.op) {
         case 'setValue':
-            return applyEdits(text, modify(text, path, op.value, { formattingOptions: JSON_FORMAT }));
+            // `modify` would happily *create* a missing path (and every ancestor along
+            // it), which violates the contract that an unresolved path is a no-op — so
+            // only edit when the node actually exists.
+            if (!findNodeAtLocation(root, path))
+                return text;
+            return applyEdits(text, modify(text, path, op.value, { formattingOptions: format }));
         case 'removeProperty':
-            return applyEdits(text, modify(text, path, undefined, { formattingOptions: JSON_FORMAT }));
+            if (!findNodeAtLocation(root, path))
+                return text;
+            return applyEdits(text, modify(text, path, undefined, { formattingOptions: format }));
         case 'renameProperty': {
             const valueNode = findNodeAtLocation(root, path);
-            const keyNode = valueNode?.parent?.children?.[0];
+            // Only a real object member can be renamed. An array-index path has an
+            // `array` parent, whose first child is element 0 — renaming there would
+            // overwrite that element, so bail instead.
+            if (valueNode?.parent?.type !== 'property')
+                return text;
+            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)
+            if (!node || node.type !== 'array')
                 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 }));
+            const kept = (node.children ?? []).filter((_, index) => !removed.has(index));
+            return rewriteJsonArray(text, node, kept);
         }
         case 'reorderArray': {
             const node = findNodeAtLocation(root, path);
-            if (!node)
+            if (!node || node.type !== 'array')
                 return text;
-            const array = getNodeValue(node);
-            const reordered = op.order.map((index) => array[index]);
-            return applyEdits(text, modify(text, path, reordered, { formattingOptions: JSON_FORMAT }));
+            const children = node.children ?? [];
+            const reordered = op.order.map((index) => children[index]).filter((child) => child != null);
+            return rewriteJsonArray(text, node, reordered);
         }
         case 'insertProperty': {
             const node = findNodeAtLocation(root, path);
@@ -285,14 +454,14 @@ const applyJsonOp = (text, op) => {
             // 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 }));
+            return applyEdits(text, modify(text, [...path, op.key], op.value, { formattingOptions: 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 }));
+            return applyEdits(text, modify(text, [...path, index], op.value, { formattingOptions: format, isArrayInsertion: true }));
         }
     }
 };

package/dist/parsers/types.d.ts

@@ -43,8 +43,20 @@ export type IParseResult<T = unknown> = {
 };
 /** Tuning for how strictly the parser treats YAML/JSON edge cases. */
 export type IParserOptions = {
-    /** Severity for duplicate object keys. Default: error. `false`/`"off"` disables. */
+    /**
+     * Severity for duplicate object keys. Default: error. `false`/`"off"` disables
+     * detection entirely; any {@link DiagnosticSeverity} reports the duplicate at
+     * that level instead of the default error.
+     */
     duplicateKeys?: DiagnosticSeverity | 'off' | false;
-    /** Severity for YAML values incompatible with JSON (e.g. bigints). Default: error. */
+    /**
+     * Severity for YAML values that cannot round-trip through JSON. The core
+     * schema projects `.nan`/`.inf`/`-.inf` to the non-finite numbers `NaN`,
+     * `Infinity`, and `-Infinity`, which `JSON.stringify` silently rewrites to
+     * `null`; each such value is reported at the configured severity.
+     *
+     * Detection is opt-in. Default (`undefined`), `false`, and `"off"` disable it;
+     * any {@link DiagnosticSeverity} enables detection and reports at that level.
+     */
     incompatibleValues?: DiagnosticSeverity | 'off' | false;
 };

package/dist/parsers/yaml.d.ts

@@ -2,5 +2,15 @@ import { type IParseResult, type IParserOptions } from './types.js';
 /**
  * Parses YAML (a JSON superset, so this handles both) into data plus a source
  * map, surfacing duplicate-key and incompatible-value diagnostics per `options`.
+ *
+ * A `---`-separated stream is parsed as multiple documents (via
+ * `parseAllDocuments`), each linted independently: `data` becomes an array of
+ * per-document values and every position key / finding path is prefixed with the
+ * zero-based document index, so a violation in a later document resolves to its
+ * own range instead of being silently dropped. A single-document source keeps the
+ * flat shape — `data` is the document value and paths are unprefixed — so existing
+ * callers and rulesets are unaffected. Node ranges are absolute offsets into the
+ * shared source, so diagnostics and positions in later documents are already
+ * correct without any per-document offset arithmetic.
  */
 export declare const parseYaml: <T = unknown>(source: string, options?: IParserOptions) => IParseResult<T>;