@nette/neon 0.0.0-stage → 1.0.0

package/bin/neon-lint.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.js';
+
+process.exitCode = main(process.argv.slice(2));

package/dist/builder.d.ts

@@ -0,0 +1,28 @@
+import type { ArrayItemNode, ValueNode } from './nodes.ts';
+/** Where a built node will stand. */
+export interface Place {
+    /** Write arrays as blocks. */
+    block: boolean;
+    /** Indentation of the line of the item that will hold the value. */
+    indent: string;
+    /** Indentation unit of nested blocks. */
+    unit: string;
+    /** Line ending of the document. */
+    eol: string;
+    /** Write multiline strings in """, because a ''' would close an earlier string of the document. */
+    doubleQuoted?: boolean;
+}
+/**
+ * Makes nodes from values of the host. The text is what encode() writes, so new values look the
+ * same as encoded ones; it is parsed, so the nodes are valid by construction.
+ */
+export declare class Builder {
+    /** A value as a node, without edge trivia; a non-empty array is a block if the place allows it. */
+    static value(value: unknown, place: Place): ValueNode;
+    /** An item of a block, `key: value` or `- value`, with its indentation and line ending. */
+    static blockItem(key: string | null, value: unknown, place: Place): ArrayItemNode;
+    /** @internal The value of a document made of the text, detached, its tokens without an origin. */
+    static parse(text: string): ValueNode;
+    /** The text of a key: an integer key as digits, anything else as a string. */
+    static keyText(key: string): string;
+}

package/dist/builder.js

@@ -0,0 +1,76 @@
+import { encode } from "./encoder.js";
+import { forgetOrigin, setItems, setLeading, setSlots, setTrailing } from "./internal.js";
+import { parse } from "./parser.js";
+import { NeonError } from "./errors.js";
+import { isIntegerKey } from "./values.js";
+/**
+ * Makes nodes from values of the host. The text is what encode() writes, so new values look the
+ * same as encoded ones; it is parsed, so the nodes are valid by construction.
+ */
+export class Builder {
+    /** A value as a node, without edge trivia; a non-empty array is a block if the place allows it. */
+    static value(value, place) {
+        const block = place.block && isCollection(value) && hasItems(value);
+        let text = encode(value, { blockMode: block, indentation: place.unit, doubleQuotedMultiline: place.doubleQuoted });
+        text = block
+            ? indent(text.replace(/\n+$/, ''), place.indent + place.unit, true)
+            : indent(text, place.indent, false);
+        const node = Builder.parse(text.replaceAll('\n', place.eol));
+        if (!block) {
+            node.getFirstToken()[setLeading]([]);
+        }
+        node.getLastToken()[setTrailing]([]);
+        return node;
+    }
+    /** An item of a block, `key: value` or `- value`, with its indentation and line ending. */
+    static blockItem(key, value, place) {
+        const head = key === null ? '-' : Builder.keyText(key) + ':';
+        let text;
+        if (value === null && key !== null) {
+            text = head;
+        }
+        else if (isCollection(value) && hasItems(value)) {
+            const body = encode(value, { blockMode: true, indentation: place.unit, doubleQuotedMultiline: place.doubleQuoted }).replace(/\n+$/, '');
+            text = head + '\n' + indent(body, place.unit, true);
+        }
+        else {
+            text = head + ' ' + encode(value, { indentation: place.unit, doubleQuotedMultiline: place.doubleQuoted });
+        }
+        const block = Builder.parse(indent(text, place.indent, true).replaceAll('\n', place.eol) + place.eol);
+        const item = block.items[0];
+        block[setItems]([]);
+        return item;
+    }
+    /** @internal The value of a document made of the text, detached, its tokens without an origin. */
+    static parse(text) {
+        const document = parse(text);
+        const node = document.value;
+        document[setSlots]({ value: null });
+        for (const token of node.getTokens()) {
+            token[forgetOrigin]();
+        }
+        return node;
+    }
+    /** The text of a key: an integer key as digits, anything else as a string. */
+    static keyText(key) {
+        if (key.includes('\n')) {
+            throw new NeonError('A key cannot contain a line break.');
+        }
+        return isIntegerKey(key) ? key : encode(key);
+    }
+}
+/** A non-empty array, Map or plain object. */
+function hasItems(value) {
+    return value instanceof Map ? value.size > 0 : Array.isArray(value) ? value.length > 0 : Object.keys(value).length > 0;
+}
+function isCollection(value) {
+    if (value instanceof Map || Array.isArray(value)) {
+        return true;
+    }
+    const proto = typeof value === 'object' && value !== null ? Object.getPrototypeOf(value) : undefined;
+    return proto === Object.prototype || proto === null;
+}
+/** Prefixes non-empty lines; the first one only if asked. */
+function indent(text, prefix, first) {
+    return text.split('\n').map((line, i) => line === '' || (i === 0 && !first) ? line : prefix + line).join('\n');
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+export interface Io {
+    out(text: string): void;
+    err(text: string): void;
+    stdin(): Uint8Array;
+}
+/** Runs the linter and returns the exit code. */
+export declare function main(args: string[], io?: Io): number;

package/dist/cli.js

@@ -0,0 +1,172 @@
+// The command line linter. Uses Node; the rest of the package does not.
+import { lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { NeonError } from "./errors.js";
+import { parse } from "./parser.js";
+import { Cursor } from "./position.js";
+import { decodeUtf8 } from "./utf8.js";
+const Usage = `Usage: neon-lint [options] <path>...
+
+Checks NEON files; a path is a file, a directory (searched for *.neon) or - for stdin.
+
+Options:
+  --check     also verify that printing the parsed tree gives back the file
+  --json      print the findings as JSON
+  --quiet     print nothing, only set the exit code
+  --verbose   print the number of files when all are valid
+`;
+const SkippedDirectories = new Set(['vendor', 'node_modules', '.git']);
+/** Runs the linter and returns the exit code. */
+export function main(args, io = nodeIo) {
+    const options = new Set(args.filter((arg) => arg.startsWith('--')));
+    const paths = args.filter((arg) => !arg.startsWith('--'));
+    const known = ['--check', '--json', '--quiet', '--verbose', '--help'];
+    const unknown = [...options].find((option) => !known.includes(option));
+    if (options.has('--help')) {
+        io.out(Usage);
+        return 0;
+    }
+    else if (unknown || !paths.length) {
+        io.err((unknown ? `Unknown option ${unknown}\n\n` : '') + Usage);
+        return 2;
+    }
+    const { files, findings } = collect(paths);
+    if (!files.length && !findings.length) {
+        findings.push({ path: paths.join(' '), line: null, column: null, message: 'No file found' });
+    }
+    for (const file of files) {
+        try {
+            const finding = lintFile(file, options.has('--check'), io);
+            if (finding) {
+                findings.push(finding);
+            }
+        }
+        catch (e) {
+            return internalError(file, e, io);
+        }
+    }
+    findings.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    if (options.has('--quiet')) {
+        // nothing
+    }
+    else if (options.has('--json')) {
+        io.out(JSON.stringify(findings) + '\n');
+    }
+    else if (findings.length) {
+        io.out(findings.map(formatFinding).join('\n') + '\n');
+    }
+    else if (options.has('--verbose')) {
+        io.out(`OK ${files.length} files\n`);
+    }
+    return findings.length ? 1 : 0;
+}
+function formatFinding(f) {
+    return f.line === null ? `${f.path}: ${f.message}` : `${f.path}:${f.line}:${f.column}: ${f.message}`;
+}
+function internalError(path, e, io) {
+    io.err(`Internal error in ${path}: ${e instanceof Error ? e.message : e}\nPlease report it at https://github.com/nette/neon-js/issues\n`);
+    return 2;
+}
+/** The text of a file, or the finding why it cannot be read. */
+function read(path, io) {
+    try {
+        return decodeUtf8(path === '-' ? io.stdin() : readFileSync(path));
+    }
+    catch (e) {
+        if (e instanceof NeonError) {
+            return { path, line: e.position.line, column: e.position.column, message: e.message };
+        }
+        return { path, line: null, column: null, message: e instanceof Error ? e.message : String(e) };
+    }
+}
+function lintFile(path, check, io) {
+    const input = read(path, io);
+    if (typeof input !== 'string') {
+        return input;
+    }
+    try {
+        const document = parse(input);
+        if (check) {
+            const printed = document.print();
+            if (printed !== input) {
+                let i = 0;
+                while (printed[i] === input[i]) {
+                    i++;
+                }
+                const position = new Cursor(input).at(i);
+                return { path, line: position.line, column: position.column, message: 'Printing the tree differs from the file' };
+            }
+        }
+    }
+    catch (e) {
+        if (e instanceof NeonError && e.position) {
+            return { path, line: e.position.line, column: e.position.column, message: e.message };
+        }
+        throw e;
+    }
+    return null;
+}
+/**
+ * The files to lint, sorted by path, each once even when two paths name it; a path given that does not
+ * exist, or a directory that cannot be read, is a finding. The recursion does not follow links, a path
+ * given is followed.
+ */
+function collect(paths) {
+    const files = (new Map); // identity of the file => the path shown
+    const findings = [];
+    const add = (path) => {
+        let identity = path;
+        try {
+            identity = path === '-' ? path : realpathSync.native(path);
+        }
+        catch {
+            // the path itself
+        }
+        if (!files.has(identity)) {
+            files.set(identity, path);
+        }
+    };
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch (e) {
+            findings.push({ path: dir, line: null, column: null, message: e instanceof Error ? e.message : String(e) });
+            return;
+        }
+        for (const entry of entries) {
+            const full = dir.replace(/[\\/]+$/, '') + '/' + entry; // the same output on every system
+            const stat = lstatSync(full, { throwIfNoEntry: false });
+            if (!stat || stat.isSymbolicLink() || entry.startsWith('.') || SkippedDirectories.has(entry)) {
+                continue;
+            }
+            else if (stat.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.endsWith('.neon')) {
+                add(full);
+            }
+        }
+    };
+    for (const path of paths) {
+        const stat = path === '-' ? null : statSync(path, { throwIfNoEntry: false });
+        if (path === '-' || stat?.isFile()) {
+            add(path);
+        }
+        else if (stat?.isDirectory()) {
+            walk(path);
+        }
+        else {
+            findings.push({ path, line: null, column: null, message: stat ? 'Not a file or a directory' : 'No file found' });
+        }
+    }
+    return {
+        files: [...files.values()].sort((a, b) => a < b ? -1 : a > b ? 1 : 0),
+        findings,
+    };
+}
+const nodeIo = {
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+    stdin: () => readFileSync(0),
+};

package/dist/dumper.d.ts

@@ -0,0 +1,5 @@
+import { Node } from './nodes.ts';
+import type { Token } from './token.ts';
+/** Text form of the tree, as in the conformance corpus. */
+export declare function dump(node: Node): string;
+export declare function dumpToken(token: Token): string;

package/dist/dumper.js

@@ -0,0 +1,75 @@
+import { Node } from "./nodes.js";
+/** Text form of the tree, as in the conformance corpus. */
+export function dump(node) {
+    const lines = [];
+    const write = (node, prefix, depth) => {
+        const indent = '\t'.repeat(depth);
+        lines.push(indent + prefix + node.constructor.name);
+        for (const [slot, value] of slots(node)) {
+            if (value === null) {
+                continue;
+            }
+            else if (Array.isArray(value)) {
+                if (!value.length) {
+                    lines.push(`${indent}\t${slot}: []`);
+                    continue;
+                }
+                lines.push(`${indent}\t${slot}:`);
+                for (const item of value) {
+                    write(item, '- ', depth + 2);
+                }
+            }
+            else if (value instanceof Node) {
+                write(value, slot + ': ', depth + 1);
+            }
+            else {
+                lines.push(`${indent}\t${slot}: ${dumpToken(value)}`);
+            }
+        }
+    };
+    write(node, '', 0);
+    return lines.join('\n') + '\n';
+}
+function slots(node) {
+    const n = node;
+    return (SlotNames[node.constructor.name] ?? []).map((name) => {
+        const value = n[name];
+        return [name, Array.isArray(value) ? [...value] : value];
+    });
+}
+const SlotNames = {
+    DocumentNode: ['value', 'endOfFile'],
+    BlockArrayNode: ['items'],
+    InlineArrayNode: ['openBracket', 'items', 'closeBracket'],
+    ArrayItemNode: ['bullet', 'key', 'colon', 'value', 'separator'],
+    EntityNode: ['value', 'attributes'],
+    EntityChainNode: ['entities'],
+    StringNode: ['token'],
+    LiteralNode: ['token'],
+};
+export function dumpToken(token) {
+    let res = `${token.kind} ${dumpText(token.text)}`;
+    if (token.leadingTrivia.length) {
+        res += ' <' + dumpTrivia(token.leadingTrivia);
+    }
+    if (token.trailingTrivia.length) {
+        res += ' >' + dumpTrivia(token.trailingTrivia);
+    }
+    return res;
+}
+function dumpTrivia(list) {
+    return '[' + list.map((trivia) => `${trivia.kind} ${dumpText(trivia.text)}`).join(', ') + ']';
+}
+/** JSON string escaping only quotes, backslashes and control characters. */
+function dumpText(text) {
+    let res = '"';
+    for (const c of text) {
+        const code = c.charCodeAt(0);
+        res += ShortEscapes[c]
+            ?? (c === '"' || c === '\\' ? '\\' + c : code < 0x20 ? '\\u' + code.toString(16).padStart(4, '0') : c);
+    }
+    return res + '"';
+}
+const ShortEscapes = {
+    '\b': '\\b', '\f': '\\f', '\n': '\\n', '\r': '\\r', '\t': '\\t',
+};

package/dist/editing.d.ts

@@ -0,0 +1,41 @@
+import { ArrayItemNode, ArrayNode, DocumentNode, LiteralNode, type Node, StringNode, ValueNode } from './nodes.ts';
+/** What happens to the comments a removed item owns: the one on its line and those directly above it; the comments inside its value go with it. */
+export declare const CommentPolicy: {
+    /** The comments that describe the item go with it. */
+    readonly Drop: "drop";
+    /** The comments stay, above whatever follows. */
+    readonly MoveToNextToken: "move";
+};
+export type CommentPolicy = typeof CommentPolicy[keyof typeof CommentPolicy];
+export type PathSegment = string | number | {
+    item: number;
+};
+/** Writes the value of an item; an equal value is a no-op, a changed one keeps the style where it can. */
+export declare function setItemValue(item: ArrayItemNode, value: unknown): void;
+/** Puts the node into the value slot or empties it, without the comparison and styling of setItemValue(). */
+export declare function setItemNode(item: ArrayItemNode, node: ValueNode | null): void;
+/** Adds an item to an array, at the end or before the item at the position. */
+export declare function addItem(array: ArrayNode, key: string | null, value: unknown, position?: number): ArrayItemNode;
+/**
+ * Inserts an item taken out of a tree, with its comments, reindented to its new place: the common
+ * prefix of the indentation of all its lines moves. The lines inside a multiline string are part
+ * of its token and its value, so they stay.
+ */
+export declare function insertItem(array: ArrayNode, item: ArrayItemNode, at: number): void;
+/** Removes the key at the path: the item found, and the items whose value it overwrote. */
+export declare function removeByPath(document: DocumentNode, path: readonly PathSegment[], comments: CommentPolicy, nullable?: boolean, mergeBlankLines?: boolean): void;
+/** Removes an item with the comments it owns. */
+export declare function removeItem(item: ArrayItemNode, comments: CommentPolicy, nullable?: boolean, mergeBlankLines?: boolean): void;
+/** Replaces the key of an item, in the quotes of the old one when it can be written in them; or by a key node. */
+export declare function setItemKey(item: ArrayItemNode, key: string | StringNode | LiteralNode): void;
+/** Puts the node into the slot the old one stands in; the slot decides what that means. */
+export declare function replaceNode(old: ValueNode, node: ValueNode): void;
+/** Takes the node out of its slot with its edge trivia; only a value of an item with a head and the root can be empty. */
+export declare function detachNode(node: ValueNode): void;
+/** Puts the node into the place of the root: a block gets the indentation of the old root block, or none. */
+export declare function setDocumentNode(document: DocumentNode, node: ValueNode | null): void;
+/** The item at the path, or an error naming the first key that is not there. */
+export declare function resolvePath(document: DocumentNode, path: readonly PathSegment[], fullPath?: readonly PathSegment[]): ArrayItemNode;
+/** The array of a container: the array itself, or the attributes of an entity. */
+export declare function arrayOf(node: Node | null): ArrayNode | null;
+export declare function setByPath(document: DocumentNode, path: readonly PathSegment[], value: unknown, create: boolean): void;