@govela/eslint-plugin 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abullo
+
+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

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @govela/eslint-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ESLint for Vela components. The processor lints the `<script>` and the
+template expressions of a `.vela` file as one program, the virtual
+document of `vela document`: a variable used only in the template is
+used, an undefined name in `{expression}` is reported at its place, and
+the names of `{#each}` and `{#await}` are declared. Messages about
+generated text are dropped; fixes inside the component's own text apply.
+
+```sh
+npm i -D @govela/eslint-plugin eslint @eslint/js globals
+```
+
+```js
+// eslint.config.js
+import js from '@eslint/js';
+import globals from 'globals';
+import vela from '@govela/eslint-plugin';
+
+export default [
+  js.configs.recommended,
+  ...vela.configs.recommended,
+  // The code of the components: the virtual files App.vela/0_App.vela.js.
+  { files: ['**/*.vela/*.js'], languageOptions: { globals: globals.browser } },
+];
+```
+
+In TypeScript, typescript-eslint parses the virtual file of a `lang="ts"`
+component (`**/*.vela/*.ts`). Type-aware rules cannot run on components:
+turn them off there with `tseslint.configs.disableTypeChecked`.
+
+`configs.recommended` sets the processor for `**/*.vela` and declares
+`$state`, `$derived`, `$effect`, `$bindable` and `$$dispatch`. The
+template markup is not linted. The compiler binary is the one of
+`@govela/compiler` (or `VELA_BINARY`).
+
+License: MIT.

package/index.d.ts

@@ -0,0 +1,14 @@
+// Types of @govela/eslint-plugin.
+import type { ESLint, Linter } from 'eslint';
+
+/** The compiler intrinsics, as globals of the components' code. */
+export const globals: Record<'$state' | '$derived' | '$effect' | '$bindable' | '$$dispatch', 'readonly'>;
+
+/** The processor of .vela files. */
+export const processor: Linter.Processor;
+
+declare const plugin: ESLint.Plugin & {
+  configs: { recommended: Linter.Config[] };
+};
+
+export default plugin;

package/index.js

@@ -0,0 +1,186 @@
+// @govela/eslint-plugin: ESLint for the JavaScript and TypeScript of Vela
+// components (task 067). The processor lints the virtual document of a
+// component, which `vela document` writes: the <script> as written, then the
+// template expressions in a function whose blocks declare the {#each} and
+// {#await} names. A variable used only in the template is therefore used,
+// and a mistake in a template expression is reported at its place in the
+// .vela file. Messages about the generated text are dropped.
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { binaryPath } from '@govela/compiler';
+
+const manifest = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+
+/** The compiler intrinsics, as globals of the components' code. */
+export const globals = {
+  $state: 'readonly',
+  $derived: 'readonly',
+  $effect: 'readonly',
+  $bindable: 'readonly',
+  $$dispatch: 'readonly',
+};
+
+// The documents of the files being linted, from preprocess to postprocess.
+const documents = new Map();
+
+let binary;
+function velaBinary() {
+  binary ??= binaryPath();
+  return binary;
+}
+
+function lineStarts(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '\n') starts.push(i + 1);
+  }
+  return starts;
+}
+
+function offsetOf(starts, line, column) {
+  const start = starts[Math.min(Math.max(line, 1), starts.length) - 1];
+  return start + Math.max(column - 1, 0);
+}
+
+function positionOf(starts, offset) {
+  let lo = 0;
+  let hi = starts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (starts[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return { line: lo + 1, column: offset - starts[lo] + 1 };
+}
+
+// The copied segment holding the virtual offset: an offset inside one, or
+// at its end (a missing semicolon after the last statement).
+function segmentAt(segments, offset) {
+  let found = null;
+  for (const segment of segments) {
+    const [, virt, length] = segment;
+    if (virt <= offset && offset < virt + length) return segment;
+    if (offset === virt + length) found ??= segment;
+  }
+  return found;
+}
+
+function document(text, filename) {
+  const result = spawnSync(velaBinary(), ['document', '--path', filename, '--stdin'], {
+    input: text,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (result.error) throw new Error(`@govela/eslint-plugin: cannot run ${binary}: ${result.error.message}`);
+  if (result.status !== 0) throw new Error(`@govela/eslint-plugin: vela document ${filename}: ${result.stderr.trim()}`);
+  return JSON.parse(result.stdout);
+}
+
+function preprocess(text, filename) {
+  const doc = document(text, filename);
+  documents.set(filename, {
+    source: text,
+    sourceStarts: lineStarts(text),
+    virtualStarts: lineStarts(doc.text),
+    segments: doc.segments,
+  });
+  const base = filename.split(/[\\/]/).pop();
+  return [{ text: doc.text, filename: `${base}.${doc.typescript ? 'ts' : 'js'}` }];
+}
+
+// mapRange maps a virtual range into the component; null when it does not
+// start in copied text. The end is clipped to the segment of the start.
+function mapRange(doc, start, end) {
+  const segment = segmentAt(doc.segments, start);
+  if (!segment) return null;
+  const [src, virt, length] = segment;
+  const clipped = Math.min(Math.max(end, start), virt + length);
+  return [src + start - virt, src + clipped - virt];
+}
+
+// mapFix maps a fix whose range lies in one segment; others are dropped.
+function mapFix(doc, fix) {
+  if (!fix) return undefined;
+  const [start, end] = fix.range;
+  const segment = segmentAt(doc.segments, start);
+  if (!segment) return null;
+  const [src, virt, length] = segment;
+  if (end > virt + length) return null;
+  return { range: [src + start - virt, src + end - virt], text: fix.text };
+}
+
+function mapMessage(doc, message) {
+  if (!message.line) return message;
+  const start = offsetOf(doc.virtualStarts, message.line, message.column);
+  const end = message.endLine ? offsetOf(doc.virtualStarts, message.endLine, message.endColumn) : start;
+  const range = mapRange(doc, start, end);
+  if (!range) {
+    // A parse error stays visible, at the start of the file.
+    return message.fatal ? { ...message, line: 1, column: 1, endLine: undefined, endColumn: undefined } : null;
+  }
+  const from = positionOf(doc.sourceStarts, range[0]);
+  const mapped = { ...message, line: from.line, column: from.column };
+  if (message.endLine) {
+    const to = positionOf(doc.sourceStarts, range[1]);
+    mapped.endLine = to.line;
+    mapped.endColumn = to.column;
+  }
+  if ('fix' in message) {
+    const fix = mapFix(doc, message.fix);
+    if (fix) mapped.fix = fix;
+    else delete mapped.fix;
+  }
+  if (message.suggestions) {
+    mapped.suggestions = message.suggestions
+      .map((s) => ({ ...s, fix: mapFix(doc, s.fix) }))
+      .filter((s) => s.fix);
+  }
+  return mapped;
+}
+
+function postprocess(messages, filename) {
+  const doc = documents.get(filename);
+  documents.delete(filename);
+  if (!doc) return messages.flat();
+  return messages.flat().map((message) => mapMessage(doc, message)).filter(Boolean);
+}
+
+/** The processor: `processor: 'vela/vela'` for `**\/*.vela`. */
+export const processor = {
+  meta: { name: 'vela', version: manifest.version },
+  preprocess,
+  postprocess,
+  supportsAutofix: true,
+};
+
+const plugin = {
+  meta: { name: manifest.name, version: manifest.version },
+  processors: { vela: processor },
+  configs: {},
+};
+
+/**
+ * The recommended flat config: the processor for .vela files and the
+ * intrinsics as globals of their code. Add your own rules after it, for
+ * `**\/*.vela/*.js` (and `**\/*.vela/*.ts` with typescript-eslint).
+ */
+plugin.configs.recommended = [
+  {
+    name: 'vela/processor',
+    files: ['**/*.vela'],
+    plugins: { vela: plugin },
+    processor: 'vela/vela',
+  },
+  {
+    name: 'vela/globals',
+    files: ['**/*.vela/*.js', '**/*.vela/*.ts'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals,
+    },
+  },
+];
+
+export default plugin;

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@govela/eslint-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "ESLint for Vela components: a processor for the script and the template expressions of .vela files. Manifest generated by the compiler repository; do not edit.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elauven/vela.git",
+    "directory": "packages/eslint-plugin"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@govela/compiler": "0.7.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9"
+  }
+}