@nx/oxlint 23.3.0-pr.37068.f95e11e → 23.3.0-rc.0

package/README.md

@@ -12,7 +12,7 @@
 [![Semantic Release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](<>)
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 [![Join us on the Official Nx Discord Server](https://img.shields.io/discord/1143497901675401286?label=discord)](https://go.nx.dev/community)
-[![Nx Sandboxing](https://staging.nx.app/workspaces/62d013ea0852fe0a2df74438/sandbox-badge.svg)](https://nx.dev/docs/features/ci-features/sandboxing)
+[![Hours saved](https://img.shields.io/endpoint?url=https%3A%2F%2Fstaging.nx.app%2Fnx-cloud%2Fbadge%2F62d013ea0852fe0a2df74438%2Fhours-saved.json)](https://nx.dev/nx-cloud)
 
 </div>
 

package/dist/src/executors/lint/lint.batch-impl.d.ts

@@ -0,0 +1,11 @@
+import type { ExecutorContext, TaskGraph } from '@nx/devkit';
+import type { TaskResult } from '@nx/devkit/internal';
+import type { LintExecutorSchema } from './schema.js';
+/**
+ * Yields rather than returns, so Nx prints each task's output as its result
+ * streams in, unless it holds batch output for a log group.
+ */
+export default function batchLintExecutor(taskGraph: TaskGraph, inputs: Record<string, LintExecutorSchema>, _overrides: LintExecutorSchema, context: ExecutorContext): AsyncGenerator<{
+    task: string;
+    result: TaskResult;
+}>;

package/dist/src/executors/lint/lint.batch-impl.js

@@ -0,0 +1,18 @@
+import { runLintTasks } from './run-lint-tasks.js';
+/**
+ * Yields rather than returns, so Nx prints each task's output as its result
+ * streams in, unless it holds batch output for a log group.
+ */
+export default async function* batchLintExecutor(taskGraph, inputs, _overrides, context) {
+    const tasks = Object.values(taskGraph.tasks).map((task) => ({
+        taskId: task.id,
+        projectName: task.target.project,
+        projectRoot: task.projectRoot ??
+            context.projectsConfigurations.projects[task.target.project].root,
+        options: inputs[task.id],
+    }));
+    const results = runLintTasks(tasks, context.root);
+    for (const [task, result] of Object.entries(results)) {
+        yield { task, result };
+    }
+}

package/dist/src/executors/lint/lint.impl.d.ts

@@ -0,0 +1,9 @@
+import type { ExecutorContext } from '@nx/devkit';
+import type { LintExecutorSchema } from './schema.js';
+/**
+ * The non-batched entry (`--batch=false`, `parallelism: false`): the batch core
+ * with a single task, so both paths lint and report identically.
+ */
+export default function lintExecutor(options: LintExecutorSchema, context: ExecutorContext): Promise<{
+    success: boolean;
+}>;

package/dist/src/executors/lint/lint.impl.js

@@ -0,0 +1,17 @@
+import { runLintTasks } from './run-lint-tasks.js';
+/**
+ * The non-batched entry (`--batch=false`, `parallelism: false`): the batch core
+ * with a single task, so both paths lint and report identically.
+ */
+export default async function lintExecutor(options, context) {
+    const [result] = Object.values(runLintTasks([
+        {
+            taskId: context.projectName,
+            projectName: context.projectName,
+            projectRoot: context.projectsConfigurations.projects[context.projectName].root,
+            options,
+        },
+    ], context.root));
+    process.stdout.write(result.terminalOutput);
+    return { success: result.success };
+}

package/dist/src/executors/lint/options.d.ts

@@ -0,0 +1,15 @@
+import type { LintExecutorSchema, OxlintOutputFormat } from './schema.js';
+export interface ResolvedLintOptions {
+    /** Flags forwarded to Oxlint, in order: target options, `args`, then CLI overrides. */
+    flags: string[];
+    format: OxlintOutputFormat;
+    silent: boolean;
+    maxWarnings: number | undefined;
+    denyWarnings: boolean;
+}
+/**
+ * Splits the executor options into flags for Oxlint and the ones this executor
+ * applies per task: the run needs `--format=json`, `--silent` would empty the
+ * JSON, and Oxlint's exit code covers the whole run, not one project.
+ */
+export declare function resolveLintOptions(options: LintExecutorSchema): ResolvedLintOptions;

package/dist/src/executors/lint/options.js

@@ -0,0 +1,104 @@
+import { createCliOptions, createOverrides } from '@nx/devkit/internal';
+const SUPPORTED_FORMATS = [
+    'default',
+    'agent',
+    'github',
+    'json',
+];
+/**
+ * Splits the executor options into flags for Oxlint and the ones this executor
+ * applies per task: the run needs `--format=json`, `--silent` would empty the
+ * JSON, and Oxlint's exit code covers the whole run, not one project.
+ */
+export function resolveLintOptions(options) {
+    const { lintFilePatterns: _patterns, nestedProjectRoots: _nestedRoots, args, __unparsed__: unparsed = [], ...forwarded } = options;
+    // Nx passes each CLI override parsed (`config: 'a.json'`) and verbatim
+    // (`--config=a.json`), and the verbatim copy wins. Nx's parse names `-c` and
+    // positionals; the raw names add `--no-*` flags, which it names unprefixed.
+    const cliOverrides = createOverrides(unparsed);
+    const cliNames = new Set([
+        ...unparsed.map(flagName).filter(Boolean),
+        ...Object.keys(cliOverrides).map(kebabCase),
+    ]);
+    const fromOptions = Object.fromEntries(Object.entries(forwarded).filter(([key]) => !cliNames.has(kebabCase(key))));
+    const resolved = {
+        flags: [],
+        format: 'default',
+        silent: false,
+        maxWarnings: undefined,
+        denyWarnings: false,
+    };
+    const candidates = [
+        ...createCliOptions(fromOptions),
+        ...argsTokens(args, cliOverrides.args),
+        ...unparsed,
+    ];
+    for (let i = 0; i < candidates.length; i++) {
+        const flag = candidates[i];
+        const name = flagName(flag);
+        const value = () => flag.includes('=') ? flag.slice(flag.indexOf('=') + 1) : candidates[++i];
+        if (name === 'verbose' || name === 'no-verbose') {
+            // Nx keeps its own --verbose in the options it hands an executor.
+            continue;
+        }
+        else if (name &&
+            ['args', 'lint-file-patterns', 'nested-project-roots'].includes(kebabCase(name))) {
+            // The CLI copy of an option destructured above: drop it and its value.
+            value();
+        }
+        else if (name === 'format' || flag.startsWith('-f')) {
+            // Oxlint also takes the value attached, as in `-fjson`.
+            resolved.format = assertSupportedFormat(/^-f[^=]/.test(flag) ? flag.slice(2) : value());
+        }
+        else if (name === 'silent') {
+            resolved.silent = true;
+        }
+        else if (name === 'max-warnings') {
+            resolved.maxWarnings = Number(value());
+        }
+        else if (name === 'deny-warnings') {
+            resolved.denyWarnings = true;
+        }
+        else {
+            resolved.flags.push(flag);
+        }
+    }
+    return resolved;
+}
+function assertSupportedFormat(value) {
+    if (!SUPPORTED_FORMATS.includes(value)) {
+        throw new Error(`Unsupported Oxlint output format "${value}". @nx/oxlint renders ${SUPPORTED_FORMATS.map((f) => `"${f}"`).join(', ')}.`);
+    }
+    return value;
+}
+/** Splits on whitespace outside single or double quotes, and strips the quotes. */
+function splitArgsString(args) {
+    if (!args) {
+        return [];
+    }
+    const tokens = args.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+    return tokens.map((token) => token.replace(/"([^"]*)"|'([^']*)'/g, (_, double, single) => double ?? single));
+}
+/**
+ * Nx splits a CLI `--args` string on commas; rejoining recovers what was typed,
+ * with Nx's interpolation applied. A repeated `--args` arrives as an array.
+ */
+function argsTokens(args, cliArgs) {
+    if (cliArgs === undefined) {
+        return Array.isArray(args) ? args : splitArgsString(args);
+    }
+    const values = [args].flat();
+    return Array.isArray(cliArgs)
+        ? values.flatMap((value) => splitArgsString(value))
+        : splitArgsString(values.join(','));
+}
+function flagName(flag) {
+    if (!flag.startsWith('--')) {
+        return null;
+    }
+    const end = flag.indexOf('=');
+    return flag.slice(2, end === -1 ? undefined : end);
+}
+function kebabCase(key) {
+    return key.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase());
+}

package/dist/src/executors/lint/partition.d.ts

@@ -0,0 +1,34 @@
+import type { OxlintDiagnostic } from './run-oxlint.js';
+export interface TaskScope {
+    taskId: string;
+    /** Workspace-relative files or directories this task lints. */
+    paths: string[];
+    /** Nested project roots under `paths` whose files this task never lints. */
+    excludedRoots: string[];
+}
+/**
+ * Gives each diagnostic to every task that lints its file when run on its own,
+ * so overlapping paths report in each task. A diagnostic with no file, or
+ * outside every task's paths, goes to the `outsideOwners` tasks. Every task
+ * gets an entry, empty when nothing was reported.
+ */
+export declare function partitionDiagnostics(diagnostics: OxlintDiagnostic[], tasks: TaskScope[], outsideOwners: string[]): Map<string, OxlintDiagnostic[]>;
+export declare function excludedNestedRoots(paths: string[], nestedProjectRoots: string[]): string[];
+/**
+ * Oxlint reports `filename` workspace-relative, except under some terminals
+ * where it becomes a `file://` URL or an absolute path
+ * (https://github.com/oxc-project/oxc/issues/24916).
+ */
+export declare function normalizeFilename(filename: string, workspaceRoot: string): string;
+/**
+ * `--ignore-pattern` flags for the nested roots the tasks exclude, so Oxlint
+ * never lints or fixes files of a project outside this run. A root stays
+ * linted when its project is in the run or another task lints it, since a
+ * pattern applies to the whole run. Anchored, because a bare single-segment
+ * pattern also matches a same-named directory a task owns.
+ */
+export declare function nestedProjectIgnorePatterns(tasks: {
+    projectRoot: string;
+    paths: string[];
+    excludedRoots: string[];
+}[]): string[];

package/dist/src/executors/lint/partition.js

@@ -0,0 +1,92 @@
+import { isAbsolute, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Gives each diagnostic to every task that lints its file when run on its own,
+ * so overlapping paths report in each task. A diagnostic with no file, or
+ * outside every task's paths, goes to the `outsideOwners` tasks. Every task
+ * gets an entry, empty when nothing was reported.
+ */
+export function partitionDiagnostics(diagnostics, tasks, outsideOwners) {
+    const byTask = new Map(tasks.map(({ taskId }) => [taskId, []]));
+    for (const diagnostic of diagnostics) {
+        for (const task of tasks) {
+            if (diagnostic.filename && lintsFile(task, diagnostic.filename)) {
+                byTask.get(task.taskId).push(diagnostic);
+            }
+        }
+        if (!diagnostic.filename ||
+            !tasks.some((task) => task.paths.some((path) => contains(path, diagnostic.filename)))) {
+            for (const taskId of outsideOwners) {
+                byTask.get(taskId).push(diagnostic);
+            }
+        }
+    }
+    return byTask;
+}
+export function excludedNestedRoots(paths, nestedProjectRoots) {
+    return nestedProjectRoots.filter((root) => paths.some((path) => root !== normalizePath(path) && contains(path, root)));
+}
+function lintsFile(task, file) {
+    return (task.paths.some((path) => contains(path, file)) &&
+        !task.excludedRoots.some((root) => contains(root, file)));
+}
+/**
+ * Oxlint reports `filename` workspace-relative, except under some terminals
+ * where it becomes a `file://` URL or an absolute path
+ * (https://github.com/oxc-project/oxc/issues/24916).
+ */
+export function normalizeFilename(filename, workspaceRoot) {
+    let path = filename.startsWith('file://')
+        ? fileURLToPath(filename)
+        : filename;
+    if (isAbsolute(path)) {
+        path = relative(workspaceRoot, path);
+    }
+    path = path.split(sep).join('/');
+    return path.startsWith('./') ? path.slice(2) : path;
+}
+/**
+ * `--ignore-pattern` flags for the nested roots the tasks exclude, so Oxlint
+ * never lints or fixes files of a project outside this run. A root stays
+ * linted when its project is in the run or another task lints it, since a
+ * pattern applies to the whole run. Anchored, because a bare single-segment
+ * pattern also matches a same-named directory a task owns.
+ */
+export function nestedProjectIgnorePatterns(tasks) {
+    const inRun = new Set(tasks.map((t) => t.projectRoot));
+    const excluded = [];
+    for (const root of [
+        ...new Set(tasks.flatMap((t) => t.excludedRoots)),
+    ].sort()) {
+        if (inRun.has(root)) {
+            continue;
+        }
+        // Excluding a root already prunes everything under it.
+        if (excluded.some((parent) => root.startsWith(`${parent}/`))) {
+            continue;
+        }
+        if (!tasks.some((task) => lintsFile(task, root))) {
+            excluded.push(root);
+        }
+    }
+    return excluded.map((root) => `--ignore-pattern=/${escapeIgnorePattern(root)}`);
+}
+/**
+ * Escape the gitignore metacharacters in a path so `--ignore-pattern` matches
+ * it literally: to Oxlint's matcher `\`, `[`, `]`, `*` and `?` are pattern
+ * syntax, and a trailing space is stripped unless escaped.
+ */
+function escapeIgnorePattern(pattern) {
+    return pattern
+        .replace(/([\\[\]*?])/g, '\\$1')
+        .replace(/ +$/, (spaces) => spaces.replace(/ /g, '\\ '));
+}
+/** Oxlint expands no globs, so containment is the whole match. */
+function contains(path, file) {
+    const dir = normalizePath(path);
+    return dir === '' || file === dir || file.startsWith(`${dir}/`);
+}
+function normalizePath(path) {
+    const normalized = path.replace(/^\.\//, '').replace(/\/$/, '');
+    return normalized === '.' ? '' : normalized;
+}

package/dist/src/executors/lint/render/agent.d.ts

@@ -0,0 +1,3 @@
+import type { OxlintDiagnostic } from '../run-oxlint.js';
+/** One line per diagnostic, matching Oxlint's own agent formatter. */
+export declare function renderAgent(diagnostics: OxlintDiagnostic[]): string;

package/dist/src/executors/lint/render/agent.js

@@ -0,0 +1,18 @@
+import { position } from './shared.js';
+/** One line per diagnostic, matching Oxlint's own agent formatter. */
+export function renderAgent(diagnostics) {
+    return diagnostics
+        .map((d) => {
+        const { line, column } = position(d);
+        const location = d.filename
+            ? `${d.filename}:${line}:${column}`
+            : '<unknown>';
+        const code = d.code ? ` ${d.code}` : '';
+        const help = d.help ? ` help: ${compact(d.help)}` : '';
+        return `${location}: ${d.severity}${code}: ${compact(d.message)}${help}\n`;
+    })
+        .join('');
+}
+function compact(text) {
+    return text.split(/\s+/).filter(Boolean).join(' ');
+}

package/dist/src/executors/lint/render/default.d.ts

@@ -0,0 +1,6 @@
+import type { OxlintDiagnostic } from '../run-oxlint.js';
+/**
+ * Oxlint's terminal report. Source lines come from disk because the JSON report
+ * carries no source text.
+ */
+export declare function renderGraphical(diagnostics: OxlintDiagnostic[], workspaceRoot: string): string;

package/dist/src/executors/lint/render/default.js

@@ -0,0 +1,61 @@
+import pc from 'picocolors';
+import { position, SourceCache } from './shared.js';
+/**
+ * Oxlint's terminal report. Source lines come from disk because the JSON report
+ * carries no source text.
+ */
+export function renderGraphical(diagnostics, workspaceRoot) {
+    const sources = new SourceCache(workspaceRoot);
+    let out = '';
+    for (const d of diagnostics) {
+        const isError = d.severity === 'error';
+        const paint = isError ? pc.red : pc.yellow;
+        const { line, column } = position(d);
+        const code = d.code ? `${paint(d.code)}: ` : '';
+        out += `\n  ${paint(isError ? '×' : '⚠')} ${code}${indent(d.message, `  ${paint('│')} `)}\n`;
+        if (d.filename) {
+            out += `   ${pc.dim(`╭─[${d.filename}:${line}:${column}]`)}\n`;
+            const lines = sources.lines(d.filename);
+            const span = d.labels[0]?.span;
+            if (lines && span) {
+                // Oxlint shows no line for the empty string after a final newline.
+                const lineCount = lines.at(-1) === '' ? lines.length - 1 : lines.length;
+                const first = Math.max(1, line - 1);
+                const last = Math.min(lineCount, line + 1);
+                const width = String(last).length;
+                for (let n = first; n <= last; n++) {
+                    const text = lines[n - 1];
+                    out += ` ${pc.dim(String(n).padStart(width))} ${pc.dim('│')}${text ? ` ${text}` : ''}\n`;
+                    if (n === line) {
+                        out += underline(width, column, span, lines[n - 1], d.labels[0].label, paint);
+                    }
+                }
+            }
+            out += `   ${pc.dim('╰────')}\n`;
+        }
+        if (d.help) {
+            out += `  ${pc.cyan('help')}: ${indent(d.help, ' '.repeat(8))}\n`;
+        }
+        if (d.note) {
+            out += `  ${pc.cyan('note')}: ${indent(d.note, ' '.repeat(11))}\n`;
+        }
+    }
+    return out;
+}
+function indent(text, prefix) {
+    return text.replaceAll('\n', `\n${prefix}`);
+}
+function underline(width, column, span, lineText, label, paint) {
+    const bytes = Buffer.from(lineText);
+    // A multi-line span is underlined to the end of its first line.
+    const length = Math.max(1, bytes.subarray(column - 1, column - 1 + span.length).toString().length);
+    const gutter = ` ${' '.repeat(width)} ${pc.dim('·')} `;
+    const pad = ' '.repeat(bytes.subarray(0, column - 1).toString().length);
+    if (!label) {
+        return `${gutter}${pad}${paint('─'.repeat(length))}\n`;
+    }
+    const mid = Math.floor((length - 1) / 2);
+    const bar = '─'.repeat(mid) + '┬' + '─'.repeat(length - mid - 1);
+    return (`${gutter}${pad}${paint(bar)}\n` +
+        `${gutter}${pad}${' '.repeat(mid)}${paint('╰── ' + label)}\n`);
+}

package/dist/src/executors/lint/render/github.d.ts

@@ -0,0 +1,6 @@
+import type { OxlintDiagnostic } from '../run-oxlint.js';
+/**
+ * GitHub Actions workflow commands, one annotation per diagnostic
+ * (https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions).
+ */
+export declare function renderGithub(diagnostics: OxlintDiagnostic[], workspaceRoot: string): string;

package/dist/src/executors/lint/render/github.js

@@ -0,0 +1,37 @@
+import { position, SourceCache } from './shared.js';
+/**
+ * GitHub Actions workflow commands, one annotation per diagnostic
+ * (https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions).
+ */
+export function renderGithub(diagnostics, workspaceRoot) {
+    const sources = new SourceCache(workspaceRoot);
+    return diagnostics
+        .map((d) => {
+        const level = d.severity === 'error' ? 'error' : 'warning';
+        const title = `title=${escapeProperty(d.code ?? 'oxlint')}`;
+        if (!d.filename) {
+            return `::${level} ${title}::${escapeData(d.message)}\n`;
+        }
+        const span = d.labels[0]?.span;
+        const { line, column } = position(d);
+        const end = span ? sources.endOf(d.filename, span) : { line, column };
+        const props = [
+            `file=${escapeProperty(d.filename)}`,
+            `line=${line}`,
+            `endLine=${end.line}`,
+            `col=${column}`,
+            `endColumn=${end.column}`,
+            title,
+        ].join(',');
+        const message = escapeData(`${d.filename}:${line}:${column}: ${d.message}`);
+        return `::${level} ${props}::${message}\n`;
+    })
+        .join('');
+}
+// https://github.com/actions/toolkit/blob/main/packages/core/src/command.ts
+function escapeData(s) {
+    return s.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+function escapeProperty(s) {
+    return escapeData(s).replace(/:/g, '%3A').replace(/,/g, '%2C');
+}

package/dist/src/executors/lint/render/index.d.ts

@@ -0,0 +1,5 @@
+import type { OxlintDiagnostic } from '../run-oxlint.js';
+import type { OxlintOutputFormat } from '../schema.js';
+import { type RenderContext } from './shared.js';
+export { countBySeverity } from './shared.js';
+export declare function renderDiagnostics(format: OxlintOutputFormat, diagnostics: OxlintDiagnostic[], context: RenderContext): string;

package/dist/src/executors/lint/render/index.js

@@ -0,0 +1,20 @@
+import { renderAgent } from './agent.js';
+import { renderGraphical } from './default.js';
+import { renderGithub } from './github.js';
+import { summary } from './shared.js';
+export { countBySeverity } from './shared.js';
+export function renderDiagnostics(format, diagnostics, context) {
+    switch (format) {
+        case 'json':
+            return JSON.stringify({ diagnostics }, null, 2) + '\n';
+        case 'github':
+            return (renderGithub(diagnostics, context.workspaceRoot) + summary(diagnostics));
+        case 'agent':
+            return renderAgent(diagnostics);
+        case 'default':
+            return context.agentMode
+                ? renderAgent(diagnostics)
+                : renderGraphical(diagnostics, context.workspaceRoot) +
+                    summary(diagnostics);
+    }
+}

package/dist/src/executors/lint/render/shared.d.ts

@@ -0,0 +1,25 @@
+import type { OxlintDiagnostic, OxlintSpan } from '../run-oxlint.js';
+export interface RenderContext {
+    workspaceRoot: string;
+    /** In CI or under an AI agent `default` renders as `agent`, as Oxlint does. */
+    agentMode: boolean;
+}
+export declare function countBySeverity(diagnostics: OxlintDiagnostic[]): {
+    errors: number;
+    warnings: number;
+};
+export declare function summary(diagnostics: OxlintDiagnostic[]): string;
+export declare function position(d: OxlintDiagnostic): {
+    line: number;
+    column: number;
+};
+export declare class SourceCache {
+    private cache;
+    private workspaceRoot;
+    constructor(workspaceRoot: string);
+    lines(file: string): string[] | null;
+    endOf(file: string, span: OxlintSpan): {
+        line: number;
+        column: number;
+    };
+}

package/dist/src/executors/lint/render/shared.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import pc from 'picocolors';
+export function countBySeverity(diagnostics) {
+    let errors = 0;
+    for (const d of diagnostics) {
+        if (d.severity === 'error')
+            errors++;
+    }
+    return { errors, warnings: diagnostics.length - errors };
+}
+export function summary(diagnostics) {
+    const { errors, warnings } = countBySeverity(diagnostics);
+    const line = `Found ${warnings} warning${warnings === 1 ? '' : 's'} and ${errors} error${errors === 1 ? '' : 's'}.`;
+    return ((diagnostics.length ? '\n' : '') +
+        (errors ? pc.red(line) : warnings ? pc.yellow(line) : line) +
+        '\n');
+}
+export function position(d) {
+    const span = d.labels[0]?.span;
+    return { line: span?.line ?? 1, column: span?.column ?? 1 };
+}
+export class SourceCache {
+    // No parameter property: Node's strip-only TypeScript mode rejects them,
+    // which would push the whole executor onto the slower swc fallback.
+    constructor(workspaceRoot) {
+        this.cache = new Map();
+        this.workspaceRoot = workspaceRoot;
+    }
+    lines(file) {
+        if (!this.cache.has(file)) {
+            try {
+                this.cache.set(file, readFileSync(join(this.workspaceRoot, file), 'utf-8').split('\n'));
+            }
+            catch {
+                this.cache.set(file, null);
+            }
+        }
+        return this.cache.get(file);
+    }
+    endOf(file, span) {
+        const lines = this.lines(file);
+        if (!lines) {
+            return { line: span.line, column: span.column + span.length };
+        }
+        let remaining = span.offset + span.length;
+        for (let i = 0; i < lines.length; i++) {
+            const lineLength = Buffer.byteLength(lines[i]) + 1;
+            if (remaining < lineLength) {
+                return { line: i + 1, column: remaining + 1 };
+            }
+            remaining -= lineLength;
+        }
+        return {
+            line: lines.length,
+            column: Buffer.byteLength(lines.at(-1) ?? '') + 1,
+        };
+    }
+}

package/dist/src/executors/lint/run-lint-tasks.d.ts

@@ -0,0 +1,14 @@
+import { type TaskResult } from '@nx/devkit/internal';
+import type { LintExecutorSchema } from './schema.js';
+export interface LintTask {
+    taskId: string;
+    projectName: string;
+    projectRoot: string;
+    options: LintExecutorSchema;
+}
+/**
+ * Lints every task with a single Oxlint run and splits the report back per
+ * task. Oxlint takes one flag set per process, so the run uses the first
+ * task's flags and warns when another task resolves different ones.
+ */
+export declare function runLintTasks(tasks: LintTask[], workspaceRoot: string): Record<string, TaskResult>;

package/dist/src/executors/lint/run-lint-tasks.js

@@ -0,0 +1,88 @@
+import { logger } from '@nx/devkit';
+import { interpolate, isAiAgent, isCI, } from '@nx/devkit/internal';
+import { resolveLintOptions } from './options.js';
+import { excludedNestedRoots, nestedProjectIgnorePatterns, normalizeFilename, partitionDiagnostics, } from './partition.js';
+import { countBySeverity, renderDiagnostics } from './render/index.js';
+import { runOxlint } from './run-oxlint.js';
+/**
+ * Lints every task with a single Oxlint run and splits the report back per
+ * task. Oxlint takes one flag set per process, so the run uses the first
+ * task's flags and warns when another task resolves different ones.
+ */
+export function runLintTasks(tasks, workspaceRoot) {
+    const resolved = tasks.map((task) => {
+        const paths = (task.options.lintFilePatterns ?? ['{projectRoot}']).map((p) => normalizeFilename(interpolate(p, {
+            workspaceRoot: '',
+            projectRoot: task.projectRoot,
+            projectName: task.projectName,
+        }), workspaceRoot));
+        return {
+            ...task,
+            ...resolveLintOptions(task.options),
+            paths,
+            excludedRoots: excludedNestedRoots(paths, task.options.nestedProjectRoots ?? []),
+        };
+    });
+    const flags = resolved[0].flags;
+    const sharesRunFlags = (r) => r.flags.join('\u0000') === flags.join('\u0000');
+    const differing = resolved.find((r) => !sharesRunFlags(r));
+    if (differing) {
+        logger.warn(`[@nx/oxlint] ${differing.projectName} resolves different Oxlint options than ${resolved[0].projectName}. Oxlint runs once for the whole batch, using ${resolved[0].projectName}'s options.`);
+    }
+    const ignores = nestedProjectIgnorePatterns(resolved);
+    const paths = [...new Set(resolved.flatMap((r) => r.paths))];
+    const startTime = Date.now();
+    // A task whose files are all ignored is a clean task, not an error. The
+    // forwarded flags go after this executor's own, so a `--` among them cannot
+    // turn those into paths.
+    const run = runOxlint([
+        ...ignores,
+        '--no-error-on-unmatched-pattern',
+        ...flags,
+        ...paths.map((path) => (path.startsWith('-') ? `./${path}` : path)),
+    ], workspaceRoot);
+    const endTime = Date.now();
+    const results = {};
+    if (run.ok === false) {
+        for (const { taskId } of resolved) {
+            results[taskId] = {
+                success: false,
+                terminalOutput: run.output + '\n',
+                startTime,
+                endTime,
+            };
+        }
+        return results;
+    }
+    for (const diagnostic of run.report.diagnostics) {
+        diagnostic.filename = normalizeFilename(diagnostic.filename ?? '', workspaceRoot);
+    }
+    // The tasks whose flags the run uses also own the diagnostics outside every
+    // task's paths: those for a path in the forwarded flags or a config file,
+    // and those with no file.
+    const byTask = partitionDiagnostics(run.report.diagnostics, resolved, resolved.filter(sharesRunFlags).map((r) => r.taskId));
+    const agentMode = !!isCI() || isAiAgent();
+    for (const r of resolved) {
+        const diagnostics = byTask.get(r.taskId);
+        const { errors, warnings } = countBySeverity(diagnostics);
+        const success = errors === 0 &&
+            (!r.denyWarnings || warnings === 0) &&
+            (r.maxWarnings === undefined || warnings <= r.maxWarnings);
+        results[r.taskId] = {
+            success,
+            terminalOutput: r.silent
+                ? ''
+                : renderDiagnostics(r.format, diagnostics, {
+                    workspaceRoot,
+                    agentMode,
+                }),
+            startTime,
+            endTime,
+        };
+    }
+    if (resolved.some((r) => !r.silent)) {
+        const { number_of_files, threads_count, start_time } = run.report;
+        process.stdout.write(`Finished in ${Math.round(start_time * 1000)}ms on ${number_of_files} files using ${threads_count} threads.\n`);
+    }
+    return results;
+}

package/dist/src/executors/lint/run-oxlint.d.ts

@@ -0,0 +1,42 @@
+/** Offsets, lengths and columns count UTF-8 bytes. */
+export interface OxlintSpan {
+    offset: number;
+    length: number;
+    line: number;
+    column: number;
+}
+export interface OxlintLabel {
+    label?: string;
+    span: OxlintSpan;
+}
+export interface OxlintDiagnostic {
+    message: string;
+    /** Absent when no rule raised the diagnostic, as for an unreadable file. */
+    code?: string;
+    severity: 'error' | 'warning' | 'advice';
+    /** Empty or absent when the diagnostic has no source file. */
+    filename?: string;
+    labels: OxlintLabel[];
+    help?: string;
+    note?: string;
+    url?: string;
+}
+export interface OxlintReport {
+    diagnostics: OxlintDiagnostic[];
+    number_of_files: number;
+    threads_count: number;
+    start_time: number;
+}
+export type OxlintRun = {
+    ok: true;
+    report: OxlintReport;
+} | {
+    ok: false;
+    output: string;
+};
+/**
+ * One `oxlint --format=json` invocation from the workspace root. If Oxlint
+ * produces no JSON, its raw output is returned because that text is the only
+ * explanation Oxlint gives.
+ */
+export declare function runOxlint(args: string[], workspaceRoot: string): OxlintRun;

package/dist/src/executors/lint/run-oxlint.js

@@ -0,0 +1,40 @@
+import { spawnSync } from 'node:child_process';
+import { resolveOxlintBin } from '../../utils/oxlint-bin.js';
+/**
+ * One `oxlint --format=json` invocation from the workspace root. If Oxlint
+ * produces no JSON, its raw output is returned because that text is the only
+ * explanation Oxlint gives.
+ */
+export function runOxlint(args, workspaceRoot) {
+    const bin = resolveOxlintBin(workspaceRoot);
+    if (!bin) {
+        return {
+            ok: false,
+            output: `Unable to resolve "oxlint" from ${workspaceRoot}. Install it as a devDependency of the workspace.`,
+        };
+    }
+    const result = spawnSync(process.execPath, [bin, '--format=json', ...args], {
+        cwd: workspaceRoot,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        maxBuffer: 256 * 1024 * 1024,
+        windowsHide: true,
+    });
+    if (result.error) {
+        return { ok: false, output: result.error.message };
+    }
+    const report = parseReport(result.stdout);
+    if (!report) {
+        return { ok: false, output: `${result.stdout}${result.stderr}`.trim() };
+    }
+    return { ok: true, report };
+}
+function parseReport(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return Array.isArray(parsed?.diagnostics) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/executors/lint/schema.d.ts

@@ -0,0 +1,10 @@
+export type OxlintOutputFormat = 'default' | 'agent' | 'github' | 'json';
+
+export interface LintExecutorSchema {
+  lintFilePatterns?: string[];
+  nestedProjectRoots?: string[];
+  format?: OxlintOutputFormat;
+  args?: string | string[];
+  __unparsed__?: string[];
+  [forwarded: string]: unknown;
+}

package/dist/src/executors/lint/schema.json

@@ -0,0 +1,61 @@
+{
+  "version": 2,
+  "outputCapture": "direct-nodejs",
+  "$schema": "https://json-schema.org/schema",
+  "title": "Oxlint Lint Target",
+  "description": "Lints a project with Oxlint. Runs in batch mode by default, so one Oxlint process lints every project in the run, from the workspace root. Options not listed here are forwarded to Oxlint as CLI flags; paths in them are relative to the workspace root.",
+  "cli": "nx",
+  "type": "object",
+  "properties": {
+    "lintFilePatterns": {
+      "type": "array",
+      "description": "One or more files or directories to pass to Oxlint. Oxlint does not expand globs.",
+      "default": ["{projectRoot}"],
+      "items": {
+        "type": "string"
+      }
+    },
+    "nestedProjectRoots": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Workspace-relative roots of projects nested inside this one. The inferred target sets this.",
+      "hidden": true,
+      "x-priority": "internal"
+    },
+    "format": {
+      "type": "string",
+      "description": "Output format. Rendered by Nx from the Oxlint JSON report, so only these values are supported. `default` matches the Oxlint terminal output, and switches to `agent` in CI or under an AI agent, as Oxlint does.",
+      "enum": ["default", "agent", "github", "json"],
+      "default": "default"
+    },
+    "args": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Extra arguments appended to the Oxlint command. A string is split on whitespace outside quotes, with no shell escaping or expansion; an array passes each item as one argument. Paths are relative to the workspace root, which is where Oxlint runs. In a batch, Oxlint uses the first project's arguments, so list extra paths in `lintFilePatterns` instead."
+    },
+    "__unparsed__": {
+      "hidden": true,
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "$default": {
+        "$source": "unparsed"
+      },
+      "x-priority": "internal"
+    }
+  },
+  "additionalProperties": true,
+  "examplesFile": "../../../docs/lint-examples.md"
+}

package/dist/src/plugins/plugin.js

@@ -1,13 +1,13 @@
-import { buildPackageJsonPatterns, buildPackageJsonWorkspacesMatcher, calculateHashesForCreateNodes, combineGlobPatterns, globWithWorkspaceContext, hashObject, PluginCache, TargetProjectLocator, workspaceDataDirectory, quoteShellArg, } from '@nx/devkit/internal';
+import { buildPackageJsonPatterns, buildPackageJsonWorkspacesMatcher, calculateHashesForCreateNodes, combineGlobPatterns, globWithWorkspaceContext, hashObject, PluginCache, TargetProjectLocator, workspaceDataDirectory, } from '@nx/devkit/internal';
 import { createNodesFromFiles, DependencyType, detectPackageManager, getPackageManagerCommand, readJsonFile, validateDependency, } from '@nx/devkit';
 import { getLockFileName, getRootTsConfigFileName } from '@nx/js';
 import { walkTsconfigExtendsChain, } from '@nx/js/internal';
 import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname as nativeDirname, join as nativeJoin, relative as nativeRelative, sep as nativeSep, } from 'node:path';
+import { relative as nativeRelative, sep as nativeSep } from 'node:path';
 import { basename, dirname, join, normalize, sep } from 'node:path/posix';
 import { OXLINT_CONFIG_FILENAMES } from '../utils/config-file.js';
+import { resolveOxlintBin } from '../utils/oxlint-bin.js';
 /**
  * Source types Oxlint can parse. It does not lint JSON. Not configurable:
  * Oxlint picks the files it lints itself, so this only decides whether a
@@ -49,9 +49,8 @@ const internalCreateNodes = async (configFilePath, options, context, projectRoot
             return cached;
         }
         // Require something lintable, so docs-only projects get no target even
-        // when they own a config — a target there fails with "No files found to
-        // lint". This spans the whole workspace, so it stays behind the cache
-        // check and is memoized across configs.
+        // when they own a config. This spans the whole workspace, so it stays
+        // behind the cache check and is memoized across configs.
         const shouldInferTarget = ((await getLintableFilesPerProjectRoot()).get(projectRoot) ?? 0) > 0;
         if (!shouldInferTarget) {
             projectsCache.set(hash, {});
@@ -451,7 +450,6 @@ function collectTsconfigChainsByProjectRoot(projectRoots, workspaceRoot) {
     }
     return result;
 }
-const localRequire = createRequire(import.meta.url);
 /**
  * Asks Oxlint itself which files it would lint. A glob cannot answer this:
  * Oxlint honours `ignorePatterns`, `.eslintignore` and `.gitignore`, including
@@ -463,14 +461,8 @@ const localRequire = createRequire(import.meta.url);
  * rather than failing graph construction over another project's broken config.
  */
 function enumerateLintableFilesWithOxlint(workspaceRoot) {
-    let bin;
-    try {
-        bin = nativeJoin(nativeDirname(localRequire.resolve('oxlint/package.json', { paths: [workspaceRoot] })), 'bin', 'oxlint');
-    }
-    catch {
-        return null;
-    }
-    if (!existsSync(bin)) {
+    const bin = resolveOxlintBin(workspaceRoot);
+    if (!bin) {
         return null;
     }
     try {
@@ -540,23 +532,11 @@ function ancestorIgnorePaths(projectRoot) {
     }
     return result;
 }
-/**
- * Escape the gitignore metacharacters in a path so `--ignore-pattern` matches it
- * literally. The value crosses two languages and `quoteShellArg` only covers the
- * shell: to Oxlint's matcher `\`, `[`, `]`, `*` and `?` are pattern syntax, and a
- * trailing space is stripped unless escaped — so `/a[b]` excludes `ab` while
- * leaving `a[b]` walked, which is both a miss and a silent over-exclusion.
- */
-function escapeIgnorePattern(pattern) {
-    return pattern
-        .replace(/([\\[\]*?])/g, '\\$1')
-        .replace(/ +$/, (spaces) => spaces.replace(/ /g, '\\ '));
-}
 /**
  * Direct child project roots for each project root, keyed by the parent. A root
  * belongs to its NEAREST enclosing root, so a grandchild lands under the child
  * rather than the grandparent — which is what keeps an outer project from
- * emitting an exclusion that a shallower one already covers.
+ * carrying an exclusion that a shallower one already covers.
  *
  * Built once per run: resolving each root's parent by walking up is linear in
  * the workspace, where asking every project which roots sit below it is not.
@@ -584,24 +564,6 @@ function nestedRootsByParentRoot(projectRoots) {
     }
     return byParent;
 }
-/**
- * The project roots nested directly below `projectRoot`, relative to it and
- * limited to `lintDir` when the lint walk starts there. An excluded root either
- * has its own inferred target or owns nothing lintable, so pruning it drops no
- * lint coverage.
- *
- * Callers must emit each one anchored (`/dir`) and never as `dir/**`. A gitignore
- * pattern is anchored only when it contains a slash, so a bare single-segment
- * root would also match a same-named directory the outer project owns; and
- * `dir/**` matches only entries inside `dir`, leaving Oxlint free to descend and
- * read that directory's ignore files.
- */
-function nestedProjectRoots(projectRoot, nestedRootsByParent, lintDir) {
-    const prefix = projectRoot === '.' ? '' : `${projectRoot}/`;
-    return (nestedRootsByParent.get(projectRoot) ?? [])
-        .map((root) => root.slice(prefix.length))
-        .filter((rel) => !lintDir || rel === lintDir || rel.startsWith(`${lintDir}/`));
-}
 // Only the keys are read, so the value type is left open for all callers.
 function getRootForDirectory(directory, roots) {
     let currentPath = normalize(directory);
@@ -614,15 +576,15 @@ function getRootForDirectory(directory, roots) {
     return roots.has(currentPath) ? currentPath : null;
 }
 function getProjectUsingOxlintConfig(configFilePath, projectRoot, nestedRootsByParent, options, context, pmc, configChainsByConfig, jsPluginSpecifiersByConfig, tsconfigChainOutsideProjectRoot, rootConfig) {
+    // Linter-agnostic on purpose: a nested ESLint project's files are still
+    // its own.
+    const nestedProjectRoots = nestedRootsByParent.get(projectRoot) ?? [];
     let standaloneSrcPath;
     if (projectRoot === '.' &&
         existsSync(join(context.workspaceRoot, projectRoot, 'package.json'))) {
-        if (existsSync(join(context.workspaceRoot, projectRoot, 'src'))) {
-            standaloneSrcPath = 'src';
-        }
-        else if (existsSync(join(context.workspaceRoot, projectRoot, 'lib'))) {
-            standaloneSrcPath = 'lib';
-        }
+        // A directory that is itself a project belongs to that project.
+        standaloneSrcPath = ['src', 'lib'].find((dir) => existsSync(join(context.workspaceRoot, projectRoot, dir)) &&
+            !nestedProjectRoots.includes(dir));
     }
     if (projectRoot === '.' && !standaloneSrcPath) {
         return null;
@@ -638,20 +600,18 @@ function getProjectUsingOxlintConfig(configFilePath, projectRoot, nestedRootsByP
             ...(configChainsByConfig.get(config) ?? []),
         ])),
     ];
-    const isRootProject = projectRoot === '.';
-    const lintPath = isRootProject && standaloneSrcPath ? `./${standaloneSrcPath}` : '.';
-    const nestedIgnoreArgs = nestedProjectRoots(projectRoot, nestedRootsByParent, isRootProject && standaloneSrcPath ? standaloneSrcPath : '')
-        // `quoteShellArg` documents that it cannot keep `%` literal through cmd.exe,
-        // so on Windows such a root is left unexcluded rather than excluded wrongly:
-        // it gets linted twice, which is what happened before this exclusion existed.
-        .filter((relativeRoot) => process.platform !== 'win32' || !relativeRoot.includes('%'))
-        .map((relativeRoot) => `--ignore-pattern ${quoteShellArg(escapeIgnorePattern(`/${relativeRoot}`))}`);
     const jsPluginFiles = new Set(configInputs.flatMap((config) => localJsPluginFiles(config, jsPluginSpecifiersByConfig.get(config) ?? [])));
     const lintableFiles = `{projectRoot}/${LINTABLE_FILES_GLOB}`;
     const usesBoundariesBridge = configInputs.some((config) => (jsPluginSpecifiersByConfig.get(config) ?? []).includes(BOUNDARIES_PLUGIN_SPECIFIER));
     const targetConfig = {
-        command: `oxlint ${[lintPath, ...nestedIgnoreArgs].join(' ')}`,
-        options: { cwd: projectRoot },
+        executor: '@nx/oxlint:lint',
+        ...((standaloneSrcPath || nestedProjectRoots.length > 0) && {
+            options: {
+                // Every other project lints its root, the executor's default.
+                ...(standaloneSrcPath && { lintFilePatterns: [standaloneSrcPath] }),
+                ...(nestedProjectRoots.length > 0 && { nestedProjectRoots }),
+            },
+        }),
         cache: true,
         inputs: [
             // Only what Oxlint can lint, so a README or JSON edit is not a re-lint.

package/dist/src/utils/oxlint-bin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Absolute path of Oxlint's CLI entry as installed in the workspace, or null
+ * when `oxlint` cannot be resolved from there. Spawn it through
+ * `process.execPath` so nothing depends on a shell or on PATH.
+ */
+export declare function resolveOxlintBin(workspaceRoot: string): string | null;

package/dist/src/utils/oxlint-bin.js

@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+const localRequire = createRequire(import.meta.url);
+/**
+ * Absolute path of Oxlint's CLI entry as installed in the workspace, or null
+ * when `oxlint` cannot be resolved from there. Spawn it through
+ * `process.execPath` so nothing depends on a shell or on PATH.
+ */
+export function resolveOxlintBin(workspaceRoot) {
+    try {
+        const bin = join(dirname(localRequire.resolve('oxlint/package.json', { paths: [workspaceRoot] })), 'bin', 'oxlint');
+        return existsSync(bin) ? bin : null;
+    }
+    catch {
+        return null;
+    }
+}

package/executors.json

@@ -0,0 +1,11 @@
+{
+  "executors": {
+    "lint": {
+      "implementation": "./dist/src/executors/lint/lint.impl",
+      "batchImplementation": "./dist/src/executors/lint/lint.batch-impl",
+      "preferBatch": true,
+      "schema": "./dist/src/executors/lint/schema.json",
+      "description": "Lint a project with Oxlint. Batched by default: one Oxlint process lints every project in the run."
+    }
+  }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@nx/oxlint",
   "description": "Experimental. The Oxlint plugin for Nx contains generators and utilities used for linting JavaScript/TypeScript projects within an Nx workspace.",
-  "version": "23.3.0-pr.37068.f95e11e",
+  "version": "23.3.0-rc.0",
   "type": "module",
   "files": [
     "dist",
     "!dist/tsconfig.tsbuildinfo",
     "migrations.json",
-    "generators.json"
+    "generators.json",
+    "executors.json"
   ],
   "publishConfig": {
     "access": "public"
@@ -51,6 +52,7 @@
     "./package.json": "./package.json",
     "./migrations.json": "./migrations.json",
     "./generators.json": "./generators.json",
+    "./executors.json": "./executors.json",
     "./generators": {
       "@nx/nx-source": "./generators.ts",
       "types": "./dist/generators.d.ts",
@@ -67,11 +69,13 @@
     "supportsOptionalMigrations": true
   },
   "generators": "./generators.json",
+  "executors": "./executors.json",
   "dependencies": {
+    "@nx/devkit": "23.3.0-rc.0",
+    "@nx/eslint-plugin": "23.3.0-rc.0",
+    "@nx/js": "23.3.0-rc.0",
     "tslib": "^2.3.0",
-    "@nx/devkit": "23.3.0-pr.37068.f95e11e",
-    "@nx/eslint-plugin": "23.3.0-pr.37068.f95e11e",
-    "@nx/js": "23.3.0-pr.37068.f95e11e"
+    "picocolors": "^1.1.0"
   },
   "peerDependencies": {
     "oxlint": "^1.43.0"
@@ -85,6 +89,6 @@
     "node": "^20.19.0 || >=22.12.0"
   },
   "devDependencies": {
-    "nx": "23.3.0-pr.37068.f95e11e"
+    "nx": "23.3.0-rc.0"
   }
 }

package/readme-template.md

@@ -0,0 +1,18 @@
+<p style="text-align: center;">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-dark.svg">
+    <img alt="Nx - Smart Monorepos · Fast Builds" src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-light.svg" width="100%">
+  </picture>
+</p>
+
+{{links}}
+
+<hr>
+
+# Nx: Smart Monorepos · Fast Builds
+
+Get to green PRs in half the time. Nx optimizes your builds, scales your CI, and fixes failed PRs. Built for developers and AI agents.
+
+This package is an [Oxlint plugin for Nx](https://nx.dev/nx-api/oxlint).
+
+{{content}}