@gjsify/oxlint-plugin-gjsify 0.53.0

package/README.md

@@ -0,0 +1,122 @@
+# @gjsify/oxlint-plugin-gjsify
+
+An [oxlint](https://oxc.rs/docs/guide/usage/linter/linter.html) JS plugin carrying the lint
+rules gjsify needs for GJS and GTK code — and that oxlint's own Rust rule set cannot have,
+because each one is a claim about a HOST (GJS's exit semantics, `xgettext`'s view of a
+Blueprint file) rather than about JavaScript.
+
+## Installation
+
+```bash
+npm install --save-dev @gjsify/oxlint-plugin-gjsify oxlint
+```
+
+`oxlint` is a peer dependency: the plugin runs inside oxlint's JavaScript plugin host, so the
+two versions have to be the ones you actually run.
+
+## Usage
+
+Add the package to `jsPlugins` in `.oxlintrc.json` and switch on the rules you want. The
+rules are namespaced `gjsify/<rule>`, from the plugin's `meta.name`:
+
+```json
+{
+    "jsPlugins": ["@gjsify/oxlint-plugin-gjsify"],
+    "rules": {
+        "gjsify/prefer-blueprint-template": "error",
+        "gjsify/no-literal-widget-label": "error"
+    }
+}
+```
+
+Then run `npx oxlint .`, or `gjsify lint` if your project uses the gjsify CLI (which spawns
+the same oxlint). `gjsify fix` applies the autofixes below.
+
+> **A missing plugin is a hard failure, not a silent skip.** oxlint reports
+> `Failed to load JS plugin` and exits non-zero rather than linting without the rules, so a
+> scaffolded project that names the plugin but has not installed it fails loudly at the
+> config step. If you see that message, run the install above.
+
+### Which rules to enable
+
+Not all seven suit every project. Two are about GTK application interface and are the reason
+this package exists for most gjsify apps; the rest are narrower.
+
+| Rule | Reports | Autofix |
+|---|---|---|
+| `prefer-blueprint-template` | a widget subclass that assembles its interface in TypeScript instead of declaring it in a Blueprint `.blp` | no — writing the `.blp` is the work |
+| `no-literal-widget-label` | user-visible text hard-coded into a widget, where no catalogue can ever hold it | no — the repair is context-dependent |
+| `register-class-order` | static GObject metadata declared below the `GObject.registerClass` static block | **yes** — hoists the fields |
+| `deferred-process-exit` | a bare `process.exit()` with statements after it, which does not halt under GJS | no — usually `return process.exit(...)` |
+| `todo-needs-anchor` | a `TODO`/`FIXME`/`HACK`/`XXX` that names nothing to track it | no |
+| `no-css-side-effect-import` | a bare `import '<something that is CSS>'`, which tree-shakes away to nothing under a gjsify build | no |
+| `spawn-node-binary` | `spawn(process.execPath, …)` under the GJS bundle, where that path is `gjs-console` | no |
+
+Two of them are aimed at this repository rather than at consumers, and are listed here only
+because they ship in the same plugin: `spawn-node-binary` fires on `spawn(process.execPath, …)`,
+which this repo scopes to its own CLI sources in `.oxlintrc.json` and a consumer has to scope
+itself (or leave off), and `no-css-side-effect-import` depends on how YOUR build treats CSS —
+under a real CSS pipeline the side-effect form is correct. Enable what you have measured.
+
+### Scope-outs
+
+Library code that implements widgets FOR others — renderers, storybook fixtures, component
+catalogues — legitimately builds widgets at runtime, and `prefer-blueprint-template` reports
+every one. Scope those directories off in `.oxlintrc.json` rather than disabling line by line
+(the paths below are examples, not paths of yours):
+
+```json
+{
+    "overrides": [
+        {
+            "files": ["packages/web/adwaita-app/**", "**/*.story.ts"],
+            "rules": { "gjsify/prefer-blueprint-template": "off" }
+        }
+    ]
+}
+```
+
+With `reportUnusedDisableDirectives` on — which `gjsify format --init` writes — a directive that
+suppresses nothing is itself an error, so a scope-out that stops applying retires itself.
+
+## Rules
+
+Each rule's own trade-offs — what it deliberately does NOT report, and why — are documented
+with its implementation:
+
+- `gjsify/register-class-order` — enforces that static GObject metadata fields (`GTypeName`, `Properties`, `Signals`, etc.) are declared above `GObject.registerClass` static blocks, with autofix to reorder them automatically.
+- `gjsify/deferred-process-exit` — a bare `process.exit()` does not halt under GJS (no atexit; the GLib main loop may still be armed): the call returns, the statements after it still run, and the requested exit code can be lost. The rule flags a statement containing a bare `process.exit()` when another statement follows it in the same statement list; tail-position exits are deliberately not flagged, and there is no autofix (the right repair — usually `return process.exit(...)` — is context-dependent, and a wrong one is a syntax error).
+- `gjsify/todo-needs-anchor` — a deferral marker (`TODO`, `FIXME`, `HACK`, `XXX`) that OPENS a comment line must name where it is tracked: `#123`, a forge issue URL, `open-todos` for the `status/` ledger, or the `fixed upstream in …` shim note. A bare marker has no owner and no retirement path — nothing fails when the work lands and nothing fails when it is dropped. Markers read from the comment stream rather than the source text, so one inside a string is not a finding; mid-sentence occurrences are prose about markers, not markers. No autofix (only a human knows whether the repair is fixing it, filing an issue, or adding a ledger entry).
+
+- `gjsify/no-css-side-effect-import` — a bare `import '<something that is CSS>';` registers nothing under a gjsify build. `cssAsStringPlugin` emits `export default "<css>"`, a module with no side effect, so the import is tree-shaken and the build exits 0. Measured on 0.41.0: a probe entry whose only statement was `import '@gjsify/adwaita-fonts';` — the line `@gjsify/adwaita-web` carried for its whole life while declaring `font-family: 'Adwaita Sans'` — built to a **0-byte bundle with zero `@font-face`**. The rule resolves the target package's `exports` off disk, so the extensionless shape (`@gjsify/adwaita-fonts` → `index.css`) is caught too; a VALUE import and a JS side-effect import stay silent. No autofix: deleting the line is right where the stylesheet arrives some other way and wrong where the author meant the CSS to arrive, and only the author knows which. Under a real CSS pipeline the side-effect form IS correct — say so with a per-line `// oxlint-disable-next-line gjsify/no-css-side-effect-import -- <reason>`, which `reportUnusedDisableDirectives` retires the day the import goes; this repo has exactly one such site, an Astro component.
+- `gjsify/prefer-blueprint-template` — a `Gtk`/`Adw` widget subclass that ASSEMBLES its interface in TypeScript with no Blueprint `Template`. Measured across this workspace 2026-08: Learn6502 carries a whole application in 24 `.blp` files with 8 programmatic constructions and reports zero; two apps that grew the other way report 31 template-free widget classes between them. The cost is not style — a caption assigned from TypeScript carries no `translatable` attribute, so `xgettext` never sees it and no catalogue can hold it: the interface is untranslatABLE while looking merely untranslated, which is why nobody files it. Requires BOTH signals before reporting (constructs a `Gtk`/`Adw` type AND calls a parenting method like `append`/`set_child`/`add_row`), because either alone is ordinary code — a class that only builds a `Gtk.Adjustment` is silent, and so is one that reparents an existing widget. Neither signal can type-check its operand: the rule sees `new Gtk.X` and a method NAME, never a GType. Where a non-widget's own API collides with a parenting name — `Gtk.StringList` filled by `.append()` being the case that occurs — a deny-list of known non-widget constructions keeps it quiet. `add_action` is deliberately NOT a parenting method: it is `Gio.ActionMap.add_action`, and treating it as one reported every widget that registers an action. A template that fills DATA-DRIVEN children at runtime is the intended pattern and is silent too (it has a `Template`). `Gtk.Application`/`Adw.Application` are excluded: an application object is not a widget and legitimately builds its own `Gtk.CssProvider` and `Adw.AboutDialog`. No autofix — writing the `.blp` is the work. Library code that implements widgets FOR others, plus fixtures and demos, are scoped off in `.oxlintrc.json` rather than disabled line by line.
+- `gjsify/no-literal-widget-label` — user-visible text hard-coded into a widget from TypeScript: a bare string literal in a prose position (`label`, `title`, `subtitle`, `description`, `heading`, `body`, `tooltip-text`, `placeholder-text`, `secondary-text`) of a `new Gtk.X`/`new Adw.X` constructor object or the matching `set_*` call. This is the half of the problem that survives even after a class HAS a template. Extraction sees `translatable="yes"` from Blueprint and `_("…")` from TypeScript; a bare literal is neither, so the string reaches no catalogue. Two repairs and the rule accepts both: move it into the co-located `.blp` as `title: _("…")`, or wrap it in place as `_("…")` when a runtime value picks it — wrapping is why there is no autofix. Also covers the captions that arrive as a LATER argument — `Adw.AlertDialog`'s `add_response(id, label)` and `set_response_label(id, label)`, which are the only way that dialog gets its buttons: without them a dialog whose `heading` the rule reports would still ship English-only buttons, in the same function (measured: 24 live call sites across two consumer apps). Only PROSE positions are checked: `icon-name`, `css-classes`, `action-name`, a stack page's `name` and an `Adw.EntryRow`'s `text` (user data, not a caption) are deliberately absent, and a literal with no letters (`"—"`, `"%"`, `"3"`) is not reported, because a rule that flags punctuation loses its audience. A default behind a caller override (`options.label ?? 'OK'`) is not a literal in this position and stays silent — that IS the escape hatch for library code with no text domain of its own. The setter half matches on method NAME alone, so a non-GTK object with a `set_title` method is reported too; the message names the Blueprint PROPERTY (`title`), never the setter.
+- `gjsify/spawn-node-binary` — `spawn(process.execPath, …)` means "start the current runtime again", which is right in a Node program and wrong in a DUAL-HOST one: under `dist/cli.gjs.mjs` that path is `gjs-console`, so the spawn hands a Node script to GJS, which runs it and dies inside the payload. Use `nodeBinary()` from `utils/run-node.ts`. Scoped to `packages/infra/cli/src/**`.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+
+### How gjsify itself wires it
+
+The gjsify repository runs all seven rules. Its root `.oxlintrc.json` names the SOURCE path
+(`./packages/infra/oxlint-plugin-gjsify/src/index.ts`) rather than the package name, because
+oxlint `import()`s a `.ts` file directly through Node's type-stripping and `gjsify lint` must
+work on an unbuilt checkout — the same rules, loaded without a build step:
+
+```json
+{
+    "jsPlugins": ["./packages/infra/oxlint-plugin-gjsify/src/index.ts"],
+    "rules": {
+        "gjsify/register-class-order": "error",
+        "gjsify/deferred-process-exit": "error",
+        "gjsify/todo-needs-anchor": "error",
+        "gjsify/spawn-node-binary": "error",
+        "gjsify/no-css-side-effect-import": "error",
+        "gjsify/prefer-blueprint-template": "error",
+        "gjsify/no-literal-widget-label": "error"
+    }
+}
+```
+
+## License
+
+MIT

package/lib/deferred-process-exit.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from './types.ts';
+export declare const deferredProcessExitRule: Rule;

package/lib/deferred-process-exit.js

@@ -0,0 +1,150 @@
+// `gjsify/deferred-process-exit` — a bare `process.exit()` does not halt under
+// GJS, so code after it still runs.
+//
+// GJS has no atexit hook and the GLib main loop may still be armed, so
+// `process.exit()` is DEFERRED: the call returns, the surrounding function
+// keeps executing, and the exit code the caller asked for can be lost entirely.
+// On Node/bun/deno the same call halts immediately, which is what makes this so
+// easy to ship — the bug is invisible on the runtime most people test on.
+//
+// Measured on `gjsify storybook` in a directory with no stories:
+//
+//     if (initialCount === 0) {
+//         console.error('No *.story.ts files found under src');
+//         process.exit(1);                 // ← last statement of ITS block …
+//     }
+//     console.log(`Found ${initialCount} story file(s) …`);   // … but this ran
+//
+//     $ bunx @gjsify/cli storybook   → one message, exit 1
+//     $ gjsify storybook             → BOTH messages, exit 0
+//
+// A command that reports a failure and exits 0 is worse than a crash: a script
+// or CI step wrapping it reads success.
+//
+// The fix is `return process.exit(…)` — the `return` is what actually halts the
+// handler; the deferred exit then carries its code on the way out.
+//
+// SCOPE — this rule flags the DANGEROUS shape, not every bare call. An exit in
+// tail position (nothing follows it, anywhere up the statement list) is fine,
+// and demanding `return` there would be style, not correctness. What it looks
+// for is: a statement that CONTAINS a bare `process.exit()` while another
+// statement follows it in the same block. That is precisely the case where the
+// deferral changes behaviour.
+//
+// Deliberately NOT autofixable: the correct repair depends on context (`return
+// process.exit()` inside a function, restructuring at module top level where
+// `return` is a syntax error), and a wrong autofix here produces unparseable
+// source. Reference: AGENTS.md § Lint & format, and `showcase.ts`, which
+// carries the same reasoning inline at each of its call sites.
+/** Node types that open a new function scope — an exit inside one is not ours. */
+const FUNCTION_TYPES = new Set([
+    'FunctionDeclaration',
+    'FunctionExpression',
+    'ArrowFunctionExpression',
+    'TSDeclareFunction',
+    'TSEmptyBodyFunctionExpression',
+]);
+/** Statement-list containers whose `body` is an ordered list of statements. */
+const STATEMENT_LIST_KEYS = {
+    BlockStatement: 'body',
+    StaticBlock: 'body',
+    SwitchCase: 'consequent',
+    Program: 'body',
+};
+/** Is this node the expression statement `process.exit(...)`? */
+function isBareProcessExitStatement(node) {
+    if (node.type !== 'ExpressionStatement')
+        return false;
+    const expr = node.expression;
+    if (!expr || expr.type !== 'CallExpression')
+        return false;
+    const callee = expr.callee;
+    if (!callee || callee.type !== 'MemberExpression' || callee.computed === true)
+        return false;
+    const object = callee.object;
+    const property = callee.property;
+    return (object?.type === 'Identifier' &&
+        object.name === 'process' &&
+        property?.type === 'Identifier' &&
+        property.name === 'exit');
+}
+/**
+ * Find a bare `process.exit()` statement inside `node`'s subtree, without
+ * descending into nested functions (a callback's exit belongs to the callback,
+ * not to the statement list being examined).
+ *
+ * Returns the offending node, or `null`.
+ */
+function findBareExitInSubtree(node) {
+    // A function body runs later (or never) — its exits are evaluated against
+    // ITS own statement lists, when the visitor reaches them. Guarded at ENTRY
+    // (not only when descending into children) because the statement handed in
+    // by `checkStatementList` can itself be a hoisted FunctionDeclaration: a
+    // tail-position `process.exit()` inside `function forceExit() { … }` must
+    // not be flagged just because another top-level declaration follows the
+    // function in the module body.
+    if (FUNCTION_TYPES.has(node.type))
+        return null;
+    if (isBareProcessExitStatement(node))
+        return node;
+    for (const key of Object.keys(node)) {
+        // `parent` would walk back up and recurse forever; `range` is data.
+        if (key === 'parent' || key === 'range')
+            continue;
+        const value = node[key];
+        const children = Array.isArray(value) ? value : [value];
+        for (const child of children) {
+            if (!child || typeof child !== 'object')
+                continue;
+            const childNode = child;
+            if (typeof childNode.type !== 'string')
+                continue;
+            const found = findBareExitInSubtree(childNode);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+export const deferredProcessExitRule = {
+    meta: {
+        // No autofix — see the SCOPE note in the file header.
+        fixable: false,
+    },
+    create(context) {
+        const reported = new Set();
+        const checkStatementList = (node) => {
+            const key = STATEMENT_LIST_KEYS[node.type];
+            if (!key)
+                return;
+            const body = node[key];
+            if (!Array.isArray(body))
+                return;
+            // Only statements with something AFTER them can fall through.
+            for (let i = 0; i < body.length - 1; i++) {
+                const stmt = body[i];
+                if (!stmt || typeof stmt.type !== 'string')
+                    continue;
+                const offender = findBareExitInSubtree(stmt);
+                if (!offender || reported.has(offender.start))
+                    continue;
+                reported.add(offender.start);
+                context.report({
+                    message: 'Bare `process.exit()` does not halt under GJS (no atexit, the GLib loop may still ' +
+                        'be armed) — the statements after this one still run, and the exit code can be lost. ' +
+                        'In an async or void-returning function write `return process.exit(...)`. In a ' +
+                        'SYNCHRONOUS function that returns a value, `return` is the WRONG repair: under GJS ' +
+                        'the exit yields a forever-pending Promise, so the caller receives that Promise as ' +
+                        'the return value and keeps going — throw after the exit instead, and say so in a ' +
+                        'reasoned oxlint-disable comment.',
+                    node: offender,
+                });
+            }
+        };
+        const visitor = {};
+        for (const type of Object.keys(STATEMENT_LIST_KEYS)) {
+            visitor[type] = checkStatementList;
+        }
+        return visitor;
+    },
+};

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from './types.ts';
+declare const plugin: Plugin;
+export default plugin;

package/lib/index.js

@@ -0,0 +1,36 @@
+// oxlint JS plugin for gjsify — PUBLISHED as `@gjsify/oxlint-plugin-gjsify`.
+//
+// oxlint loads a plugin via `jsPlugins` in `.oxlintrc.json`, and its plugin host
+// reads the module's DEFAULT export expecting a `{ meta: { name }, rules }` shape
+// (see `refs/oxc/apps/oxlint/src-js/plugins/load.ts` → `registerPlugin`). The newer
+// `definePlugin` helper is an identity function and is not exported by the
+// published `oxlint@1.66/1.67`, so we export the plain object directly.
+//
+// TWO LOADING PATHS, one source. This repo's own `.oxlintrc.json` names the SOURCE
+// path (`src/index.ts`) — oxlint `import()`s it directly and Node's type-stripping
+// handles the types, so `gjsify lint` needs no build step — while a consumer names
+// the PACKAGE and gets `lib/index.js` from `tsc` (see `tsconfig.build.json`).
+// `rewriteRelativeImportExtensions` is what lets one set of `./x.ts` imports serve
+// both, so neither path needs its own copy of the rules.
+import { deferredProcessExitRule } from "./deferred-process-exit.js";
+import { noCssSideEffectImportRule } from "./no-css-side-effect-import.js";
+import { noLiteralWidgetLabelRule } from "./no-literal-widget-label.js";
+import { preferBlueprintTemplateRule } from "./prefer-blueprint-template.js";
+import { registerClassOrderRule } from "./register-class-order.js";
+import { spawnNodeBinaryRule } from "./spawn-node-binary.js";
+import { todoNeedsAnchorRule } from "./todo-needs-anchor.js";
+const plugin = {
+    meta: {
+        name: 'gjsify',
+    },
+    rules: {
+        'deferred-process-exit': deferredProcessExitRule,
+        'no-css-side-effect-import': noCssSideEffectImportRule,
+        'no-literal-widget-label': noLiteralWidgetLabelRule,
+        'prefer-blueprint-template': preferBlueprintTemplateRule,
+        'register-class-order': registerClassOrderRule,
+        'spawn-node-binary': spawnNodeBinaryRule,
+        'todo-needs-anchor': todoNeedsAnchorRule,
+    },
+};
+export default plugin;

package/lib/no-css-side-effect-import.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from './types.ts';
+export declare const noCssSideEffectImportRule: Rule;

package/lib/no-css-side-effect-import.js

@@ -0,0 +1,191 @@
+// `gjsify/no-css-side-effect-import` — a bare `import '<something that is CSS>';`
+// registers nothing in a gjsify build, and says so nowhere.
+//
+// THE MECHANISM. `cssAsStringPlugin` (`@gjsify/rolldown-plugin-gjsify`, composed by
+// every `--app browser`/`--app gjs` build) hooks `load` for `.css`/`.scss`/`.sass`
+// and returns `export default "<css>"` — a JS module, because Rolldown dropped CSS
+// bundling and would otherwise error on the extension. A module whose whole body is
+// a string literal has NO side effect, so a side-effect import of it is tree-shaken
+// and the build exits 0.
+//
+// THE INCIDENT it was written for — a 0-byte bundle, exit 0, invisible on a GNOME
+// host — is `docs/code-anti-patterns.md` § "a side-effect import that has no side
+// effect". Repo-wide there were exactly TWO instances, and both had the convention
+// already written down beside them (`@gjsify/adwaita-web`'s entry comment,
+// `style.css.d.ts`): two files followed it and one did not, which is the
+// measurement that turns a comment into a check.
+//
+// WHY A LINT RULE AND NOT THE PLUGIN, where the knowledge is: the hooks that
+// could see a dropped module are argument-less no-ops on the
+// `@gjsify/rolldown-native` bridge, so the diagnostic would exist under Node and
+// not under GJS. Full reasoning, and the consumer-facing half that is still
+// missing, in `status/open-todos/README.md`.
+//
+// WHAT IT FLAGS. An `ImportDeclaration` with NO specifiers whose source is CSS:
+// either by extension (`./app.css`), or because the package it names exports CSS
+// from that subpath (`@gjsify/adwaita-fonts` → `index.css`). The second half is
+// the one that matters — a specifier with no extension is exactly the shape that
+// reads like a JS side-effect module.
+//
+// WHAT IT DOES NOT FLAG. A VALUE import (`import css from './app.css'`) — that is
+// the correct spelling, and what the app does with the string is its business. A
+// bare import of anything that resolves to JS, which is the ordinary `/register`
+// pattern and must stay silent.
+//
+// SCOPE. Repo-wide, no config override: the one legitimate site (an Astro component
+// — Astro IS a CSS pipeline) carries a per-line reasoned disable, which
+// `reportUnusedDisableDirectives` retires the day the import goes. The rule found
+// that file on its first run; the author's own grep had missed it, not reading
+// `.astro`.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+/** Extensions `cssAsStringPlugin` claims in its `load` filter. */
+const CSS_EXTENSIONS = /\.(css|s[ac]ss)(\?|#|$)/i;
+/** Export conditions to follow, in the order a browser/ESM build resolves them. */
+const CONDITIONS = ['browser', 'import', 'module', 'default', 'require'];
+/** `@scope/pkg/sub/path` → `['@scope/pkg', './sub/path']`; `pkg` → `['pkg', '.']`. */
+function splitSpecifier(specifier) {
+    const parts = specifier.split('/');
+    const name = specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+    const rest = specifier.slice(name.length);
+    return [name, rest.length === 0 ? '.' : `.${rest}`];
+}
+/** The first string an `exports` value yields under {@link CONDITIONS}, or `undefined`. */
+function pickCondition(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const picked = pickCondition(entry);
+            if (picked !== undefined)
+                return picked;
+        }
+        return undefined;
+    }
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    for (const condition of CONDITIONS) {
+        if (condition in record) {
+            const picked = pickCondition(record[condition]);
+            if (picked !== undefined)
+                return picked;
+        }
+    }
+    return undefined;
+}
+/**
+ * The manifest of `name` as seen from `fromDir`, by walking `node_modules` upward.
+ *
+ * Deliberately NOT `createRequire(...).resolve()`: that answers with a path only
+ * when the target FILE exists, and half the interesting targets are build outputs
+ * (`@gjsify/adwaita-web/style.css` → `dist/adwaita-web.css`) that a fresh checkout
+ * has not produced yet. A rule that goes quiet on an unbuilt tree is a rule that
+ * is quiet in CI's lint job, which is where it has to speak. `exports` is a
+ * DECLARATION and is present either way.
+ */
+function readPackageManifest(fromDir, name) {
+    let dir = fromDir;
+    for (;;) {
+        const manifestPath = join(dir, 'node_modules', ...name.split('/'), 'package.json');
+        if (existsSync(manifestPath)) {
+            try {
+                return JSON.parse(readFileSync(manifestPath, 'utf8'));
+            }
+            catch {
+                // A manifest we cannot parse is not evidence of CSS. Stay silent
+                // rather than accuse — this rule's whole value is that a hit means
+                // something.
+                return undefined;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Where a bare specifier's declared entry points, per the target's `exports`/`main`. */
+function declaredTarget(fromDir, specifier) {
+    const [name, subpath] = splitSpecifier(specifier);
+    const manifest = readPackageManifest(fromDir, name);
+    if (!manifest)
+        return undefined;
+    const exportsField = manifest.exports;
+    if (exportsField !== undefined && exportsField !== null) {
+        if (typeof exportsField === 'string' || Array.isArray(exportsField)) {
+            return subpath === '.' ? pickCondition(exportsField) : undefined;
+        }
+        const map = exportsField;
+        // A conditions-only map (no `.`-prefixed keys) IS the `.` entry.
+        const isSubpathMap = Object.keys(map).some((key) => key.startsWith('.'));
+        if (!isSubpathMap)
+            return subpath === '.' ? pickCondition(map) : undefined;
+        if (subpath in map)
+            return pickCondition(map[subpath]);
+        for (const [pattern, value] of Object.entries(map)) {
+            if (!pattern.includes('*'))
+                continue;
+            const [head, tail] = pattern.split('*');
+            if (!subpath.startsWith(head) || !subpath.endsWith(tail))
+                continue;
+            const star = subpath.slice(head.length, subpath.length - tail.length);
+            return pickCondition(value)?.replace('*', star);
+        }
+        return undefined;
+    }
+    return subpath === '.' ? manifest.main : subpath;
+}
+/** Does this import specifier name CSS, as written or as the target package declares? */
+function resolvesToCss(specifier, fromDir) {
+    if (CSS_EXTENSIONS.test(specifier))
+        return true;
+    if (specifier.startsWith('.')) {
+        // A relative specifier with no CSS extension is JS. Extensionless relative
+        // imports do not resolve to `.css` under any loader this repo uses.
+        return false;
+    }
+    if (specifier.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(specifier))
+        return false;
+    const target = declaredTarget(fromDir, specifier);
+    return target !== undefined && CSS_EXTENSIONS.test(target);
+}
+export const noCssSideEffectImportRule = {
+    meta: {
+        // No autofix. Deleting the line is right where the stylesheet is applied
+        // some other way and WRONG where the author meant the CSS to arrive — the
+        // two repairs are opposite, and only the author knows which.
+        fixable: false,
+    },
+    create(context) {
+        const fromDir = dirname(resolvePath(context.filename));
+        return {
+            ImportDeclaration(node) {
+                const specifiers = node.specifiers;
+                if (Array.isArray(specifiers) && specifiers.length > 0)
+                    return;
+                const source = node.source;
+                const value = source?.value;
+                if (typeof value !== 'string')
+                    return;
+                if (!resolvesToCss(value, fromDir))
+                    return;
+                context.report({
+                    message: `\`import '${value}';\` imports CSS for a SIDE EFFECT it does not have. Every gjsify ` +
+                        '`--app browser`/`--app gjs` build loads CSS through `cssAsStringPlugin`, which emits ' +
+                        '`export default "<css>"` — a module with no side effect, so this import is tree-shaken ' +
+                        'and the build exits 0 with the stylesheet nowhere in it (measured: a probe entry whose ' +
+                        'only statement was this import produced a 0-byte bundle). Import the VALUE and apply it ' +
+                        `(\`import css from '${value}'\`, then a <style> whose textContent is that string), or ` +
+                        'drop the line if the stylesheet is already applied elsewhere. For a FONT that is still ' +
+                        'only half of it: a relative `url()` inside the recovered string resolves against the ' +
+                        'document, and an `--app browser` build emits one file and no assets, so the rule parses ' +
+                        'and the face 404s — it needs a `data:` URI or an asset-emitting pipeline. Under a real ' +
+                        'CSS pipeline (Vite/webpack) the side-effect form IS correct — say so in a reasoned ' +
+                        'oxlint-disable comment.',
+                    node,
+                });
+            },
+        };
+    },
+};

package/lib/no-literal-widget-label.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from './types.ts';
+export declare const noLiteralWidgetLabelRule: Rule;