@golar-rstack/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oskar Lebuda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @golar-rstack/core
+
+Shared internals for the [golar](https://golar.dev) Rstack plugins: spawning the
+golar CLI, parsing its diagnostics, and formatting issues.
+
+You usually want [`@golar-rstack/rsbuild`](https://www.npmjs.com/package/@golar-rstack/rsbuild)
+or [`@golar-rstack/rspack`](https://www.npmjs.com/package/@golar-rstack/rspack)
+instead. This package is published for reuse by other bundler integrations.
+
+## Why a parser
+
+golar ships no machine-readable reporter, so diagnostics are recovered from
+stdout. It emits two unrelated layouts:
+
+```
+typecheck   src/App.vue(2,7): error TS2322: Type 'string' is not assignable to type 'number'.
+lint        src/math.ts:6:33: explicit-anys: Unexpected any. Specify a different type.
+```
+
+Indented lines elaborate on the diagnostic above them and are folded into its
+message. This is not a stable API. The parser is covered by tests pinned to the
+formats emitted by golar 0.1.10.
+
+## Usage
+
+```ts
+import { formatIssue, resolveGolarOptions, runGolar } from '@golar-rstack/core'
+
+const options = resolveGolarOptions({ mode: 'all' }, { cwd: process.cwd(), watch: false })
+const { issues } = await runGolar(options)
+
+for (const issue of issues)
+  console.log(formatIssue(issue, { cwd: options.cwd, formatter: 'codeframe' }))
+```
+
+`runGolar` accepts an `AbortSignal`; aborting kills the child process, which is
+how a new build cancels an in-flight check.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Creates an issue describing a failure of the plugin itself rather than a
+ * problem in the checked project, such as a crash of the golar process.
+ *
+ * @param message The text to report.
+ * @param severity How the issue should be reported. Defaults to `error`.
+ * @returns An issue with the `internal` origin.
+ */
+export declare function createInternalIssue(message: string, severity?: IssueSeverity): Issue;
+
+/**
+ * Removes duplicate issues, keeping the first occurrence of each.
+ *
+ * @param issues The issues to deduplicate.
+ * @returns A new array containing only distinct issues, in their original order.
+ */
+export declare function dedupeIssues(issues: Issue[]): Issue[];
+
+/**
+ * Looks for a golar config file, mirroring the CLI's own discovery order.
+ *
+ * @param cwd The directory golar will run in.
+ * @returns The path of the first config found, or `undefined` if there is none.
+ */
+export declare function findGolarConfig(cwd: string): string | undefined;
+
+/**
+ * Renders a single issue for display.
+ *
+ * @param issue The issue to render.
+ * @param options Directory to make paths relative to, and which formatter to
+ * use. The `codeframe` formatter appends a source excerpt when the file can be
+ * read.
+ * @returns The formatted text, without a trailing newline.
+ */
+export declare function formatIssue(issue: Issue, options: FormatOptions): string;
+
+/**
+ * Builds a one line summary of a set of issues.
+ *
+ * @param issues The issues to count.
+ * @returns Text such as `Found 2 errors and 1 warning.`, or a note that nothing
+ * was found.
+ */
+export declare function formatIssueSummary(issues: Issue[]): string;
+
+export declare interface FormatOptions {
+    cwd: string;
+    formatter: 'basic' | 'codeframe';
+}
+
+/**
+ * Builds the argument list for a golar invocation.
+ *
+ * The `all` mode is the bare command, which is what golar recommends, so it
+ * contributes no subcommand.
+ *
+ * @param options Resolved options carrying the mode and any extra arguments.
+ * @returns The arguments to pass to the golar executable.
+ */
+export declare function getGolarArgs(options: ResolvedGolarOptions): string[];
+
+/**
+ * Builds a stable identity for an issue.
+ *
+ * Overlapping runs can report the same diagnostic twice, so issues need a key
+ * that does not depend on object identity.
+ *
+ * @param issue The issue to identify.
+ * @returns A string that is equal for two issues describing the same problem.
+ */
+export declare function getIssueKey(issue: Issue): string;
+
+export declare class GolarAbortError extends Error {
+    constructor();
+}
+
+export declare type GolarMode = 'all' | 'typecheck' | 'lint';
+
+export declare interface GolarOptions {
+    cwd?: string;
+    mode?: GolarMode;
+    async?: boolean;
+    typecheckSeverity?: IssueSeverity;
+    lintSeverity?: IssueSeverity;
+    filter?: IssueFilter;
+    formatter?: 'basic' | 'codeframe';
+    bin?: string;
+    args?: string[];
+    env?: Record<string, string | undefined>;
+    failOnError?: boolean;
+}
+
+export declare interface GolarRunResult {
+    issues: Issue[];
+    output: string;
+    exitCode: number | null;
+    aborted: boolean;
+}
+
+export declare interface Issue {
+    severity: IssueSeverity;
+    code: string;
+    message: string;
+    origin: IssueOrigin;
+    file?: string;
+    location?: IssuePosition;
+}
+
+export declare type IssueFilter = (issue: {
+    file?: string;
+    code: string;
+    severity: IssueSeverity;
+    origin: string;
+}) => boolean;
+
+export declare type IssueOrigin = 'typecheck' | 'lint' | 'internal';
+
+export declare interface IssuePosition {
+    line: number;
+    column: number;
+}
+
+export declare type IssueSeverity = 'error' | 'warning';
+
+/**
+ * Parses golar's output into structured issues.
+ *
+ * golar has no machine readable reporter, so this consumes the human output.
+ * Indented continuation lines are TypeScript's elaborations and get folded into
+ * the message of the diagnostic that opened them. Lines matching nothing are
+ * CLI chatter, such as Node warnings or a stack trace from a crash, and are
+ * skipped. The runner surfaces those separately when the process fails.
+ *
+ * @param output The combined stdout and stderr of a golar run.
+ * @param options Working directory and the severity to apply to each phase.
+ * @returns The issues found, in the order golar reported them.
+ */
+export declare function parseGolarOutput(output: string, options: ParseOptions): Issue[];
+
+export declare interface ParseOptions {
+    cwd: string;
+    typecheckSeverity: IssueSeverity;
+    lintSeverity: IssueSeverity;
+}
+
+export declare interface ResolvedGolarOptions {
+    cwd: string;
+    mode: GolarMode;
+    async: boolean;
+    typecheckSeverity: IssueSeverity;
+    lintSeverity: IssueSeverity;
+    filter?: IssueFilter;
+    formatter: 'basic' | 'codeframe';
+    bin?: string;
+    args: string[];
+    env?: Record<string, string | undefined>;
+    failOnError: boolean;
+}
+
+/**
+ * Locates golar's entrypoint by walking up the directory tree.
+ *
+ * `require.resolve('golar/package.json')` is not an option, because golar's
+ * exports map only exposes `./unstable` and `./unstable-tsgo`.
+ *
+ * @param cwd The directory to start searching from.
+ * @returns The path of `golar/dist/bin.js`, or `undefined` if golar is not
+ * installed anywhere above `cwd`.
+ */
+export declare function resolveGolarBin(cwd: string): string | undefined;
+
+/**
+ * Fills in the defaults for a set of user supplied options.
+ *
+ * Checking asynchronously is the default while watching, so a rebuild is never
+ * held up, and off otherwise, so a one-off build fails on type errors. Lint
+ * findings default to `warning` because golar exits 0 when only lint rules
+ * fire, and reporting them as errors would fail builds golar considers clean.
+ *
+ * @param options The options given by the user.
+ * @param context The working directory to fall back to, and whether this run is
+ * a watch rather than a one-off build.
+ * @returns Options with every field resolved.
+ */
+export declare function resolveGolarOptions(options: GolarOptions, context: {
+    cwd: string;
+    watch: boolean;
+}): ResolvedGolarOptions;
+
+/**
+ * Runs golar once and collects the issues it reports.
+ *
+ * golar has no watch mode and no structured reporter, so every check is a fresh
+ * process whose output gets parsed. A non-zero exit that yields no issues means
+ * golar itself failed, and the raw output is reported instead of a clean check.
+ *
+ * @param options Resolved options describing where and how to run golar.
+ * @param signal Aborting this kills the child process, which is how a new build
+ * cancels a check that is still running.
+ * @returns The issues found, along with the raw output and exit code.
+ * @throws {GolarAbortError} If `signal` is aborted before or during the run.
+ * @throws If no golar config exists in the working directory, or golar cannot
+ * be located or spawned.
+ */
+export declare function runGolar(options: ResolvedGolarOptions, signal?: AbortSignal): Promise<GolarRunResult>;
+
+/**
+ * Orders issues by file and then by position, so output is stable across runs.
+ *
+ * @param issues The issues to sort.
+ * @returns A new sorted array. The input is left untouched.
+ */
+export declare function sortIssues(issues: Issue[]): Issue[];
+
+/**
+ * Removes ANSI colour escape sequences from a string.
+ *
+ * @param value The text to clean.
+ * @returns The text without escape sequences.
+ */
+export declare function stripAnsi(value: string): string;
+
+export { }

package/dist/index.js

@@ -0,0 +1,312 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { spawn } from "node:child_process";
+import node_process from "node:process";
+const CONTEXT_LINES = 2;
+function renderCodeFrame(file, line, column) {
+    let source;
+    try {
+        source = node_fs.readFileSync(file, 'utf8');
+    } catch  {
+        return;
+    }
+    const lines = source.split(/\r?\n/);
+    if (line < 1 || line > lines.length) return;
+    const start = Math.max(1, line - CONTEXT_LINES);
+    const end = Math.min(lines.length, line + CONTEXT_LINES);
+    const gutterWidth = String(end).length;
+    const frame = [];
+    for(let n = start; n <= end; n++){
+        const isTarget = n === line;
+        const gutter = String(n).padStart(gutterWidth, ' ');
+        frame.push(`${isTarget ? '>' : ' '} ${gutter} | ${lines[n - 1] ?? ''}`);
+        if (isTarget) {
+            const padding = ' '.repeat(Math.max(0, column - 1));
+            frame.push(`  ${' '.repeat(gutterWidth)} | ${padding}^`);
+        }
+    }
+    return frame.join('\n');
+}
+function formatIssue(issue, options) {
+    const parts = [];
+    const origin = 'lint' === issue.origin ? 'lint' : 'type';
+    if (issue.file) {
+        const relative = node_path.relative(options.cwd, issue.file) || issue.file;
+        const position = issue.location ? `:${issue.location.line}:${issue.location.column}` : '';
+        parts.push(`${relative}${position}`);
+    }
+    parts.push(`${origin} ${issue.code}: ${issue.message}`);
+    let result = parts.join('\n');
+    if ('codeframe' === options.formatter && issue.file && issue.location) {
+        const frame = renderCodeFrame(issue.file, issue.location.line, issue.location.column);
+        if (frame) result += `\n${frame}`;
+    }
+    return result;
+}
+function formatIssueSummary(issues) {
+    const errors = issues.filter((issue)=>'error' === issue.severity).length;
+    const warnings = issues.length - errors;
+    if (0 === errors && 0 === warnings) return 'No issues found.';
+    const parts = [];
+    if (errors > 0) parts.push(`${errors} ${1 === errors ? 'error' : 'errors'}`);
+    if (warnings > 0) parts.push(`${warnings} ${1 === warnings ? 'warning' : 'warnings'}`);
+    return `Found ${parts.join(' and ')}.`;
+}
+function getIssueKey(issue) {
+    const { file = '', location, code, message, severity } = issue;
+    return [
+        file,
+        location?.line ?? 0,
+        location?.column ?? 0,
+        severity,
+        code,
+        message
+    ].join(' ');
+}
+function dedupeIssues(issues) {
+    const seen = new Set();
+    const result = [];
+    for (const issue of issues){
+        const key = getIssueKey(issue);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(issue);
+        }
+    }
+    return result;
+}
+function sortIssues(issues) {
+    return [
+        ...issues
+    ].sort((a, b)=>{
+        if (a.file !== b.file) return (a.file ?? '').localeCompare(b.file ?? '');
+        const lineDiff = (a.location?.line ?? 0) - (b.location?.line ?? 0);
+        if (0 !== lineDiff) return lineDiff;
+        return (a.location?.column ?? 0) - (b.location?.column ?? 0);
+    });
+}
+function createInternalIssue(message, severity = 'error') {
+    return {
+        severity,
+        code: 'GOLAR',
+        message,
+        origin: 'internal'
+    };
+}
+const CONFIG_FILENAMES = [
+    'golar.config.ts',
+    'golar.config.mts',
+    'golar.config.mjs',
+    'golar.config.cts',
+    'golar.config.cjs',
+    'golar.config.js'
+];
+function findGolarConfig(cwd) {
+    for (const name of CONFIG_FILENAMES){
+        const candidate = node_path.join(cwd, name);
+        if (node_fs.existsSync(candidate)) return candidate;
+    }
+}
+function resolveGolarOptions(options, context) {
+    return {
+        cwd: options.cwd ? node_path.resolve(options.cwd) : context.cwd,
+        mode: options.mode ?? 'all',
+        async: options.async ?? context.watch,
+        typecheckSeverity: options.typecheckSeverity ?? 'error',
+        lintSeverity: options.lintSeverity ?? 'warning',
+        filter: options.filter,
+        formatter: options.formatter ?? 'codeframe',
+        bin: options.bin,
+        args: options.args ?? [],
+        env: options.env,
+        failOnError: options.failOnError ?? true
+    };
+}
+function getGolarArgs(options) {
+    const subcommand = 'all' === options.mode ? [] : [
+        options.mode
+    ];
+    return [
+        ...subcommand,
+        ...options.args
+    ];
+}
+const ANSI_PATTERN = /\u001B\[[0-?]*[ -/]*[@-~]/g;
+const TYPECHECK_PATTERN = /^(.+?)\((\d+),(\d+)\): (error|warning|message) (TS\d+): (.*)$/;
+const LINT_PATTERN = /^(.+?):(\d+):(\d+): ([\w@/-]+): (.*)$/;
+const GLOBAL_PATTERN = /^(error|warning) (TS\d+): (.*)$/;
+const HEADER_PATTERN = /^Using config from /;
+function stripAnsi(value) {
+    return value.replace(ANSI_PATTERN, '');
+}
+function resolveFile(cwd, file) {
+    return node_path.isAbsolute(file) ? file : node_path.resolve(cwd, file);
+}
+function parseGolarOutput(output, options) {
+    const { cwd, typecheckSeverity, lintSeverity } = options;
+    const issues = [];
+    let current;
+    for (const rawLine of stripAnsi(output).split(/\r?\n/)){
+        const line = rawLine.replace(/\s+$/, '');
+        if (0 === line.length) continue;
+        if (/^\s/.test(line)) {
+            if (current) current.message += `\n${line}`;
+            continue;
+        }
+        if (HEADER_PATTERN.test(line)) {
+            current = void 0;
+            continue;
+        }
+        const typecheck = TYPECHECK_PATTERN.exec(line);
+        if (typecheck) {
+            const [, file, lineNo, column, severity, code, message] = typecheck;
+            current = {
+                severity: 'message' === severity ? 'warning' : typecheckSeverity,
+                code: code,
+                message: message,
+                origin: 'typecheck',
+                file: resolveFile(cwd, file),
+                location: {
+                    line: Number(lineNo),
+                    column: Number(column)
+                }
+            };
+            issues.push(current);
+            continue;
+        }
+        const lint = LINT_PATTERN.exec(line);
+        if (lint) {
+            const [, file, lineNo, column, rule, message] = lint;
+            current = {
+                severity: lintSeverity,
+                code: rule,
+                message: message,
+                origin: 'lint',
+                file: resolveFile(cwd, file),
+                location: {
+                    line: Number(lineNo),
+                    column: Number(column)
+                }
+            };
+            issues.push(current);
+            continue;
+        }
+        const global = GLOBAL_PATTERN.exec(line);
+        if (global) {
+            const [, severity, code, message] = global;
+            current = {
+                severity: 'warning' === severity ? 'warning' : typecheckSeverity,
+                code: code,
+                message: message,
+                origin: 'typecheck'
+            };
+            issues.push(current);
+            continue;
+        }
+        current = void 0;
+    }
+    return issues;
+}
+class GolarAbortError extends Error {
+    constructor(){
+        super('golar run aborted');
+        this.name = 'GolarAbortError';
+    }
+}
+function resolveGolarBin(cwd) {
+    let dir = node_path.resolve(cwd);
+    while(true){
+        const entry = node_path.join(dir, 'node_modules', 'golar', 'dist', 'bin.js');
+        if (node_fs.existsSync(entry)) return entry;
+        const parent = node_path.dirname(dir);
+        if (parent === dir) return;
+        dir = parent;
+    }
+}
+function createCommand(options) {
+    if (options.bin) return options.bin.endsWith('.js') ? {
+        command: node_process.execPath,
+        args: [
+            options.bin
+        ]
+    } : {
+        command: options.bin,
+        args: []
+    };
+    const resolved = resolveGolarBin(options.cwd);
+    if (!resolved) throw new Error(`Could not find the "golar" package from "${options.cwd}". Install it with \`pnpm add -D golar\`, or set the \`bin\` option.`);
+    return {
+        command: node_process.execPath,
+        args: [
+            resolved
+        ]
+    };
+}
+async function runGolar(options, signal) {
+    if (signal?.aborted) throw new GolarAbortError();
+    if (!findGolarConfig(options.cwd)) throw new Error(`No golar config found in "${options.cwd}". Create a \`golar.config.ts\` there, or point the \`cwd\` option at the directory that has one.`);
+    const { command, args: commandArgs } = createCommand(options);
+    const args = [
+        ...commandArgs,
+        ...getGolarArgs(options)
+    ];
+    return await new Promise((resolve, reject)=>{
+        let settled = false;
+        let output = '';
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            stdio: [
+                'ignore',
+                'pipe',
+                'pipe'
+            ],
+            env: options.env ? {
+                ...node_process.env,
+                ...options.env
+            } : node_process.env
+        });
+        const cleanup = ()=>{
+            signal?.removeEventListener('abort', onAbort);
+            child.stdout?.removeAllListeners();
+            child.stderr?.removeAllListeners();
+            child.removeAllListeners();
+        };
+        const settle = (fn)=>{
+            if (settled) return;
+            settled = true;
+            cleanup();
+            fn();
+        };
+        function onAbort() {
+            child.kill('SIGKILL');
+            settle(()=>reject(new GolarAbortError()));
+        }
+        signal?.addEventListener('abort', onAbort, {
+            once: true
+        });
+        child.stdout?.on('data', (chunk)=>{
+            output += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk)=>{
+            output += chunk.toString();
+        });
+        child.on('error', (error)=>settle(()=>reject(error)));
+        child.on('close', (exitCode)=>{
+            settle(()=>{
+                const issues = sortIssues(dedupeIssues(parseGolarOutput(output, {
+                    cwd: options.cwd,
+                    typecheckSeverity: options.typecheckSeverity,
+                    lintSeverity: options.lintSeverity
+                })));
+                if (0 !== exitCode && 0 === issues.length) issues.push(createInternalIssue(`golar exited with code ${exitCode}.\n${stripAnsi(output).trim()}`));
+                resolve({
+                    issues,
+                    output,
+                    exitCode,
+                    aborted: false
+                });
+            });
+        });
+    });
+}
+export { GolarAbortError, createInternalIssue, dedupeIssues, findGolarConfig, formatIssue, formatIssueSummary, getGolarArgs, getIssueKey, parseGolarOutput, resolveGolarBin, resolveGolarOptions, runGolar, sortIssues, stripAnsi };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@golar-rstack/core",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Shared golar runner and diagnostic parsing for the Rstack golar plugins",
+  "license": "MIT",
+  "author": "Oskar Lebuda",
+  "keywords": [
+    "golar",
+    "typecheck",
+    "typescript",
+    "rstack"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "golar": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "golar": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rslib/core": "^0.23.2",
+    "@rstest/core": "^0.11.2",
+    "@types/node": "^24.13.3",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "test": "rstest run",
+    "check:publish": "publint && attw --pack ."
+  }
+}