@herb-tools/core 0.1.0

package/dist/types/parse-result.d.ts

@@ -0,0 +1,62 @@
+import { Result } from "./result.js";
+import { DocumentNode } from "./nodes.js";
+import { HerbError } from "./error.js";
+import { HerbWarning } from "./warning.js";
+import type { SerializedHerbError } from "./error.js";
+import type { SerializedHerbWarning } from "./warning.js";
+import type { SerializedDocumentNode } from "./nodes.js";
+import type { Visitor } from "./visitor.js";
+export type SerializedParseResult = {
+    value: SerializedDocumentNode;
+    source: string;
+    warnings: SerializedHerbWarning[];
+    errors: SerializedHerbError[];
+};
+/**
+ * Represents the result of a parsing operation, extending the base `Result` class.
+ * It contains the parsed document node, source code, warnings, and errors.
+ */
+export declare class ParseResult extends Result {
+    /** The document node generated from the source code. */
+    readonly value: DocumentNode;
+    /**
+     * Creates a `ParseResult` instance from a serialized result.
+     * @param result - The serialized parse result containing the value and source.
+     * @returns A new `ParseResult` instance.
+     */
+    static from(result: SerializedParseResult): ParseResult;
+    /**
+     * Constructs a new `ParseResult`.
+     * @param value - The document node.
+     * @param source - The source code that was parsed.
+     * @param warnings - An array of warnings encountered during parsing.
+     * @param errors - An array of errors encountered during parsing.
+     */
+    constructor(value: DocumentNode, source: string, warnings?: HerbWarning[], errors?: HerbError[]);
+    /**
+     * Determines if the parsing failed.
+     * @returns `true` if there are errors, otherwise `false`.
+     */
+    failed(): boolean;
+    /**
+     * Determines if the parsing was successful.
+     * @returns `true` if there are no errors, otherwise `false`.
+     */
+    success(): boolean;
+    /**
+     * Returns a pretty-printed JSON string of the errors.
+     * @returns A string representation of the errors.
+     */
+    prettyErrors(): string;
+    recursiveErrors(): HerbError[];
+    /**
+     * Returns a pretty-printed string of the parse result.
+     * @returns A string representation of the parse result.
+     */
+    inspect(): string;
+    /**
+     * Accepts a visitor to traverse the document node.
+     * @param visitor - The visitor instance.
+     */
+    visit(visitor: Visitor): void;
+}

package/dist/types/position.d.ts

@@ -0,0 +1,15 @@
+export type SerializedPosition = {
+    line: number;
+    column: number;
+};
+export declare class Position {
+    readonly line: number;
+    readonly column: number;
+    static from(position: SerializedPosition): Position;
+    constructor(line: number, column: number);
+    toHash(): SerializedPosition;
+    toJSON(): SerializedPosition;
+    treeInspect(): string;
+    inspect(): string;
+    toString(): string;
+}

package/dist/types/range.d.ts

@@ -0,0 +1,12 @@
+export type SerializedRange = [number, number];
+export declare class Range {
+    readonly start: number;
+    readonly end: number;
+    static from(range: SerializedRange): Range;
+    constructor(start: number, end: number);
+    toArray(): SerializedRange;
+    toJSON(): SerializedRange;
+    treeInspect(): string;
+    inspect(): string;
+    toString(): string;
+}

package/dist/types/result.d.ts

@@ -0,0 +1,10 @@
+import { HerbError } from "./error.js";
+import { HerbWarning } from "./warning.js";
+export declare class Result {
+    readonly source: string;
+    readonly warnings: HerbWarning[];
+    readonly errors: HerbError[];
+    constructor(source: string, warnings?: HerbWarning[], errors?: HerbError[]);
+    success(): boolean;
+    failed(): boolean;
+}

package/dist/types/token-list.d.ts

@@ -0,0 +1,16 @@
+import { Token, SerializedToken } from "./token.js";
+export type SerializedTokenList = SerializedToken[];
+export declare class TokenList implements Iterable<Token> {
+    private list;
+    static from(list: SerializedTokenList): TokenList;
+    constructor(list: Token[]);
+    get length(): number;
+    [Symbol.iterator](): Iterator<Token>;
+    at(index: number): Token | undefined;
+    forEach(callback: (token: Token, index: number, array: Token[]) => void): void;
+    map<U>(callback: (token: Token, index: number, array: Token[]) => U): U[];
+    filter(predicate: (token: Token, index: number, array: Token[]) => boolean): Token[];
+    __getobj__(): Token[];
+    inspect(): string;
+    toString(): string;
+}

package/dist/types/token.d.ts

@@ -0,0 +1,22 @@
+import { Range, SerializedRange } from "./range.js";
+import { Location, SerializedLocation } from "./location.js";
+export type SerializedToken = {
+    value: string;
+    range: SerializedRange;
+    location: SerializedLocation;
+    type: string;
+};
+export declare class Token {
+    readonly value: string;
+    readonly range: Range;
+    readonly location: Location;
+    readonly type: string;
+    static from(token: SerializedToken): Token;
+    constructor(value: string, range: Range, location: Location, type: string);
+    toHash(): SerializedToken;
+    toJSON(): SerializedToken;
+    treeInspect(): string;
+    valueInspect(): string;
+    inspect(): string;
+    toString(): string;
+}

package/dist/types/util.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureString(object: any): string;
+export declare function convertToUTF8(string: string): string;

package/dist/types/visitor.d.ts

@@ -0,0 +1,11 @@
+import { Node } from "./node.js";
+/**
+ * Represents a visitor that can traverse nodes.
+ */
+export declare class Visitor {
+    /**
+     * Visits a node and performs an action.
+     * @param node - The node to visit.
+     */
+    visit(node: Node): void;
+}

package/dist/types/warning.d.ts

@@ -0,0 +1,11 @@
+import { Location, SerializedLocation } from "./location.js";
+export interface SerializedHerbWarning {
+    message: string;
+    location: SerializedLocation;
+}
+export declare class HerbWarning {
+    message: string;
+    location: Location;
+    static from(warning: SerializedHerbWarning): HerbWarning;
+    constructor(message: string, location: Location);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@herb-tools/core",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://herb-tools.dev",
+  "bugs": "https://github.com/marcoroth/herb/issues/new?title=Package%20%60@herb-tools/core%60:%20",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marcoroth/herb.git",
+    "directory": "javascript/packages/core"
+  },
+  "main": "./dist/herb-core.cjs",
+  "module": "./dist/herb-core.esm.js",
+  "types": "./dist/types/index.d.ts",
+  "scripts": {
+    "build": "yarn clean && rollup -c",
+    "dev": "rollup -c -w",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "prepublishOnly": "yarn clean && yarn build && yarn test"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/herb-core.esm.js",
+      "require": "./dist/herb-core.cjs",
+      "default": "./dist/herb-core.esm.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.35.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.0"
+  },
+  "files": [
+    "package.json",
+    "README.md",
+    "dist/",
+    "src/"
+  ]
+}

package/src/ast.ts

@@ -0,0 +1,7 @@
+export class ASTNode {
+  readonly errors: any[]
+
+  constructor() {
+    this.errors = []
+  }
+}

package/src/backend.ts

@@ -0,0 +1,85 @@
+import type { SerializedParseResult } from "./parse-result.js"
+import type { SerializedLexResult } from "./lex-result.js"
+
+interface LibHerbBackendFunctions {
+  lex: (source: string) => SerializedLexResult
+  lexFile: (path: string) => SerializedLexResult
+
+  parse: (source: string) => SerializedParseResult
+  parseFile: (path: string) => SerializedParseResult
+
+  extractRuby: (source: string) => string
+  extractHTML: (source: string) => string
+
+  version: () => string
+}
+
+export type BackendPromise = () => Promise<LibHerbBackend>
+
+const expectedFunctions = [
+  "parse",
+  "lex",
+  "parseFile",
+  "lexFile",
+  "extractRuby",
+  "extractHTML",
+  "version",
+] as const
+
+type LibHerbBackendFunctionName = (typeof expectedFunctions)[number]
+
+type CheckFunctionsExistInInterface =
+  LibHerbBackendFunctionName extends keyof LibHerbBackendFunctions
+    ? true
+    : "Error: Not all expectedFunctions are defined in LibHerbBackendFunctions"
+
+type CheckInterfaceKeysInFunctions =
+  keyof LibHerbBackendFunctions extends LibHerbBackendFunctionName
+    ? true
+    : "Error: LibHerbBackendFunctions has keys not listed in expectedFunctions"
+
+// NOTE: This function should never be called and is only for type checking
+// so we can make sure `expectedFunctions` matches the functions defined
+// in `LibHerbBackendFunctions` and the other way around.
+//
+export function _TYPECHECK() {
+  const checkFunctionsExist: CheckFunctionsExistInInterface = true
+  const checkInterfaceComplete: CheckInterfaceKeysInFunctions = true
+
+  return { checkFunctionsExist, checkInterfaceComplete }
+}
+
+// Exported Types + Functions
+
+export type LibHerbBackend = {
+  [K in LibHerbBackendFunctionName]: LibHerbBackendFunctions[K]
+}
+
+export function isLibHerbBackend(
+  object: any,
+  libherbpath: string = "unknown",
+): object is LibHerbBackend {
+  for (const expectedFunction of expectedFunctions) {
+    if (object[expectedFunction] === undefined) {
+      throw new Error(
+        `Libherb at "${libherbpath}" doesn't expose function "${expectedFunction}".`,
+      )
+    }
+
+    if (typeof object[expectedFunction] !== "function") {
+      throw new Error(
+        `Libherb at "${libherbpath}" has "${expectedFunction}" but it's not a function.`,
+      )
+    }
+  }
+
+  return true
+}
+
+export function ensureLibHerbBackend(
+  object: any,
+  libherbpath: string = "unknown",
+): LibHerbBackend {
+  isLibHerbBackend(object, libherbpath)
+  return object
+}

package/src/error.ts

@@ -0,0 +1,38 @@
+import { Location, SerializedLocation } from "./location.js"
+import { fromSerializedError } from "./errors.js"
+
+export interface SerializedHerbError {
+  type: string
+  message: string
+  location: SerializedLocation
+}
+
+export abstract class HerbError {
+  readonly type: string
+  readonly message: string
+  readonly location: Location
+
+  static from(error: SerializedHerbError): HerbError {
+    return fromSerializedError(error)
+  }
+
+  constructor(type: string, message: string, location: Location) {
+    this.type = type
+    this.message = message
+    this.location = location
+  }
+
+  toJSON(): SerializedHerbError {
+    return {
+      type: this.type,
+      message: this.message,
+      location: this.location.toJSON(),
+    }
+  }
+
+  inspect(): string {
+    return this.treeInspect(0)
+  }
+
+  abstract treeInspect(indent?: number): string
+}