oxlint-frontier-style 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Brand
+
+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,56 @@
+# `oxlint-frontier-style`
+
+This is an [oxlint](https://oxc.rs/docs/guide/usage/linter.html) plugin which enforces the code in the Frontier code style.
+
+## Rules
+
+Some conventions are cooler than the rules they run against. Rule escape hatches exist for a reason. Use `oxlint-ignore` where appropriate.
+
+### Module-level JSDoc required
+
+Each module-level entity must carry a JSDoc describing what it is and why it exists.
+
+### File JSDoc required
+
+Each file must start with a JSDoc block with a `@file` declaration describing what that file does and why it exists.
+
+### Preferred declaration order
+
+All declarations must follow the following order:
+
+1. `@file` JSDoc (see above)
+2. imports
+3. types
+4. interfaces
+5. constants
+6. functions
+7. file exports (the final `export {}`/`export default XYZ` block)
+
+This order apparently makes natural sense to some developers.
+
+### `SCREAMING_SNAKE_CASE` for module-level constants
+
+All module-level constants must be spelled in `SCREAMING_SNAKE_CASE`.
+
+_Configurable_:
+
+- `exceptions` match against literal names (e.g. `logger`, `formatter`, `rule`)
+- `exceptionPatterns` match against RegEx patterns (e.g. `__.*` to except names like `__unused`)
+
+### Exported entities after unexported ones
+
+Exported entities carry a heavier semantic weight (they're meant to be relied upon by consumers). This means they should be closer to the bottom within their category.
+
+### Block types must be separate
+
+Declarations of the same type (function calls, constants etc.) may be grouped together. Declarations of different types must be separated by an empty line.
+
+## Should I Use It?
+
+No.
+
+Unless you're of a particular aesthetic preference or are working on a specific set of packages, you don't need it. This is shared config for a narrow set of projects.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Entry point for the plugin.
+ */
+import type { Plugin } from "@oxlint/plugins";
+/**
+ * Exported plugin.
+ */
+declare const PLUGIN: Plugin;
+export default PLUGIN;

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * @file Entry point for the plugin.
+ */
+import blockTypeSpacing from "./rules/block-type-spacing.js";
+import exportedAfterLocal from "./rules/exported-after-local.js";
+import constScreamingSnake from "./rules/module-const-screaming-snake.js";
+import moduleStructureOrder from "./rules/module-structure-order.js";
+import requireFileJsdoc from "./rules/require-file-jsdoc.js";
+import requireJsdoc from "./rules/require-jsdoc.js";
+/**
+ * Exported plugin.
+ */
+const PLUGIN = {
+    // * `meta.name` defines rule prefix
+    // * e.g. `meta.name` `frontier-style` → rule `frontier-style/no-fucking-around`
+    meta: { name: "frontier-style" },
+    rules: {
+        "module-const-screaming-snake": constScreamingSnake,
+        "require-file-jsdoc": requireFileJsdoc,
+        "require-jsdoc": requireJsdoc,
+        "module-structure-order": moduleStructureOrder,
+        "exported-after-local": exportedAfterLocal,
+        "block-type-spacing": blockTypeSpacing,
+    },
+};
+export default PLUGIN;

package/dist/recommended.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Shareable preset bundling Frontier's built-in and custom rule configuration.
+ */
+import type { OxlintConfig } from "oxlint";
+/**
+ * The recommended config for the projects using the Frontier code style.
+ */
+declare const RECOMMENDED: OxlintConfig;
+export default RECOMMENDED;

package/dist/recommended.js

@@ -0,0 +1,36 @@
+/**
+ * @file Shareable preset bundling Frontier's built-in and custom rule configuration.
+ */
+/**
+ * The recommended config for the projects using the Frontier code style.
+ */
+const RECOMMENDED = {
+    plugins: ["eslint", "typescript", "import", "oxc", "promise", "unicorn"],
+    jsPlugins: ["oxlint-frontier-style"],
+    categories: { correctness: "warn" },
+    rules: {
+        "prefer-const": "error",
+        "id-length": [
+            "error",
+            { checkGeneric: false, exceptionPatterns: ["^_.*"] },
+        ],
+        "func-style": ["error", "declaration", { allowArrowFunctions: true }],
+        "typescript/consistent-type-imports": "error",
+        "typescript/consistent-type-definitions": ["error", "interface"],
+        "typescript/explicit-function-return-type": "error",
+        "typescript/no-explicit-any": "error",
+        "typescript/no-duplicate-type-constituents": "off",
+        "import/extensions": [
+            "error",
+            "always",
+            { ignorePackages: true, checkTypeImports: true },
+        ],
+        "frontier-style/block-type-spacing": "error",
+        "frontier-style/module-structure-order": "error",
+        "frontier-style/exported-after-local": "error",
+        "frontier-style/module-const-screaming-snake": "error",
+        "frontier-style/require-file-jsdoc": "error",
+        "frontier-style/require-jsdoc": "error",
+    },
+};
+export default RECOMMENDED;

package/dist/rules/block-type-spacing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Rule: separate adjacent statements of different block type with exactly one blank line.
+ */
+import type { Context, Visitor } from "@oxlint/plugins";
+declare const _default: {
+    meta: {
+        type: "layout";
+        docs: {
+            description: string;
+            recommended: boolean;
+        };
+        messages: {
+            missingBlankLine: string;
+        };
+    };
+    create(context: Context): Visitor;
+};
+export default _default;

package/dist/rules/block-type-spacing.js

@@ -0,0 +1,208 @@
+/**
+ * @file Rule: separate adjacent statements of different block type with exactly one blank line.
+ */
+import { asVariableDeclaration, unwrapExport } from "../shared/ast.js";
+/**
+ * Statement types treated as a `return` block.
+ */
+const RETURN_TYPES = new Set([
+    "ReturnStatement",
+    "ThrowStatement",
+    "ContinueStatement",
+    "BreakStatement",
+]);
+/**
+ * Narrows a node to an `ExpressionStatement`.
+ * Returns `null` if the node is not one.
+ */
+function asExpressionStatement(node) {
+    return node.type === "ExpressionStatement" ? node : null;
+}
+/**
+ * Narrows a node to an `IfStatement`.
+ * Returns `null` if the node is not one.
+ */
+function asIfStatement(node) {
+    return node.type === "IfStatement" ? node : null;
+}
+/**
+ * Counts the fully-blank lines between two nodes or comments.
+ */
+function blankLinesBetween(first, second) {
+    return second.loc.start.line - first.loc.end.line - 1;
+}
+/**
+ * Whether the node spans more than one line.
+ */
+function isMultiline(node) {
+    return node.loc.start.line !== node.loc.end.line;
+}
+/**
+ * Classifies a `const`/`let` declaration, including by whether is spans one line or multiple.
+ */
+function classifyVariable(node, kind) {
+    if (kind === "const")
+        return isMultiline(node) ? "const-multiline" : "const";
+    return isMultiline(node) ? "let-multiline" : "let";
+}
+/**
+ * Classifies an expression statement by its expression kind.
+ */
+function classifyExpression(expression) {
+    if (expression.type === "AssignmentExpression")
+        return "assign";
+    if (expression.type === "CallExpression")
+        return "call";
+    if (expression.type === "AwaitExpression")
+        return "call";
+    return "other";
+}
+/**
+ * Classifies an `if` statement as a `guard` (single early-exit, no `else`) or a general `conditional`.
+ */
+function classifyIf(consequent, alternate) {
+    const isGuard = alternate === null &&
+        consequent.type !== "BlockStatement" &&
+        RETURN_TYPES.has(consequent.type);
+    return isGuard ? "guard" : "conditional";
+}
+/**
+ * Classifies a statement node into its block type.
+ */
+function classifyStatement(node) {
+    const target = unwrapExport(node);
+    const declaration = asVariableDeclaration(target);
+    if (declaration !== null)
+        return classifyVariable(declaration, declaration.kind);
+    const expressionStatement = asExpressionStatement(target);
+    if (expressionStatement !== null)
+        return classifyExpression(expressionStatement.expression);
+    const ifStatement = asIfStatement(target);
+    if (ifStatement !== null)
+        return classifyIf(ifStatement.consequent, ifStatement.alternate);
+    if (target.type === "SwitchStatement")
+        return "conditional";
+    if (target.type === "TryStatement")
+        return "try";
+    if (RETURN_TYPES.has(target.type))
+        return "return";
+    return "other";
+}
+/**
+ * Splits a statement's leading comments into the run attached to it (no blank line between) and the standalone comments that precede that run.
+ */
+function splitAttachedComments(leading, statement) {
+    let attachedStartLine = statement.loc.start.line;
+    let cursorLine = statement.loc.start.line;
+    let splitIndex = leading.length;
+    for (let index = leading.length - 1; index >= 0; index--) {
+        const comment = leading[index];
+        if (comment === undefined)
+            break;
+        if (comment.loc.end.line !== cursorLine - 1)
+            break;
+        attachedStartLine = comment.loc.start.line;
+        cursorLine = comment.loc.start.line;
+        splitIndex = index;
+    }
+    return { attachedStartLine, standalone: leading.slice(0, splitIndex) };
+}
+/**
+ * Appends standalone comments to `items` as `comment` blocks, grouping runs separated by a blank line into distinct items.
+ */
+function pushCommentItems(items, comments) {
+    let group = [];
+    function flush() {
+        const first = group[0];
+        const last = group[group.length - 1];
+        if (first === undefined || last === undefined)
+            return;
+        items.push({
+            kind: "comment",
+            startLine: first.loc.start.line,
+            endLine: last.loc.end.line,
+            node: null,
+        });
+    }
+    for (const comment of comments) {
+        const previous = group[group.length - 1];
+        if (previous !== undefined &&
+            blankLinesBetween(previous, comment) > 0) {
+            flush();
+            group = [];
+        }
+        group.push(comment);
+    }
+    flush();
+}
+/**
+ * Builds the ordered list of spacing items for a statement body.
+ */
+function buildItems(context, body) {
+    const items = [];
+    for (const statement of body) {
+        const leading = context.sourceCode.getCommentsBefore(statement);
+        const { attachedStartLine, standalone } = splitAttachedComments(leading, statement);
+        pushCommentItems(items, standalone);
+        items.push({
+            kind: classifyStatement(statement),
+            startLine: attachedStartLine,
+            endLine: statement.loc.end.line,
+            node: statement,
+        });
+    }
+    return items;
+}
+/**
+ * Reports adjacent items of different block type that have no blank line between them.
+ */
+function checkBody(context, body) {
+    const items = buildItems(context, body);
+    for (let index = 1; index < items.length; index++) {
+        const previous = items[index - 1];
+        const current = items[index];
+        if (previous === undefined || current === undefined)
+            continue;
+        if (previous.kind === current.kind)
+            continue;
+        const gap = current.startLine - previous.endLine - 1;
+        if (gap !== 0)
+            continue;
+        const data = { before: previous.kind, after: current.kind };
+        if (current.node === null) {
+            context.report({
+                loc: { line: current.startLine, column: 0 },
+                messageId: "missingBlankLine",
+                data,
+            });
+            continue;
+        }
+        context.report({
+            node: current.node,
+            messageId: "missingBlankLine",
+            data,
+        });
+    }
+}
+export default {
+    meta: {
+        type: "layout",
+        docs: {
+            description: "Separate adjacent statements of different block type with exactly one blank line.",
+            recommended: true,
+        },
+        messages: {
+            missingBlankLine: "Expected a blank line between `{{before}}` and `{{after}}` blocks.",
+        },
+    },
+    create(context) {
+        return {
+            Program(node) {
+                checkBody(context, node.body);
+            },
+            BlockStatement(node) {
+                checkBody(context, node.body);
+            },
+        };
+    },
+};

package/dist/rules/exported-after-local.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Rule: within a group (`const`/`let`/functions), local declarations must precede exported ones.
+ */
+import type { Context, Visitor } from "@oxlint/plugins";
+declare const _default: {
+    meta: {
+        type: "suggestion";
+        docs: {
+            description: string;
+            recommended: boolean;
+        };
+        messages: {
+            exportBeforeLocal: string;
+        };
+    };
+    create(context: Context): Visitor;
+};
+export default _default;

package/dist/rules/exported-after-local.js

@@ -0,0 +1,58 @@
+/**
+ * @file Rule: within a group (`const`/`let`/functions), local declarations must precede exported ones.
+ */
+import { asVariableDeclaration, isExportStatement, unwrapExport, } from "../shared/ast.js";
+/**
+ * Returns the group key of a declaration (`function`/`const`/`let`), or `null` if it does not belong to a tracked group.
+ */
+function groupKeyOf(node) {
+    const inner = unwrapExport(node);
+    if (inner.type === "FunctionDeclaration")
+        return "function";
+    const declaration = asVariableDeclaration(inner);
+    if (declaration === null)
+        return null;
+    return declaration.kind === "const" ? "const" : "let";
+}
+/**
+ * Reports any local declaration that appears after an exported one within the same group.
+ */
+function checkProgram(context, node) {
+    const exportedGroups = new Set();
+    for (const statement of node.body) {
+        const group = groupKeyOf(statement);
+        if (group === null)
+            continue;
+        const exported = isExportStatement(statement);
+        if (exported) {
+            exportedGroups.add(group);
+            continue;
+        }
+        if (exportedGroups.has(group)) {
+            context.report({
+                node: statement,
+                messageId: "exportBeforeLocal",
+                data: { group },
+            });
+        }
+    }
+}
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Require local declarations to precede exported ones within each `const`/`let`/function group.",
+            recommended: true,
+        },
+        messages: {
+            exportBeforeLocal: "Non-exported `{{group}}` declarations must come before exported ones.",
+        },
+    },
+    create(context) {
+        return {
+            Program(node) {
+                checkProgram(context, node);
+            },
+        };
+    },
+};

package/dist/rules/module-const-screaming-snake.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Rule: module-level `const` identifiers must be `SCREAMING_SNAKE_CASE`.
+ */
+import type { Context, Visitor } from "@oxlint/plugins";
+declare const _default: {
+    meta: {
+        type: "suggestion";
+        docs: {
+            description: string;
+            recommended: boolean;
+        };
+        messages: {
+            notScreamingSnake: string;
+        };
+        schema: {
+            type: "object";
+            properties: {
+                exceptions: {
+                    type: "array";
+                    items: {
+                        type: "string";
+                    };
+                };
+                exceptionPatterns: {
+                    type: "array";
+                    items: {
+                        type: "string";
+                    };
+                };
+            };
+            additionalProperties: false;
+        }[];
+    };
+    create(context: Context): Visitor;
+};
+export default _default;

package/dist/rules/module-const-screaming-snake.js

@@ -0,0 +1,144 @@
+/**
+ * @file Rule: module-level `const` identifiers must be `SCREAMING_SNAKE_CASE`.
+ */
+import { asVariableDeclaration, unwrapExport } from "../shared/ast.js";
+/**
+ * Rule identifier, used to prefix option-validation errors.
+ */
+const RULE_ID = "module-const-screaming-snake";
+/**
+ * Pattern an identifier must match to be considered `SCREAMING_SNAKE_CASE`.
+ */
+const SCREAMING_SNAKE = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/;
+/**
+ * Initializer node types that exempt a `const` from the naming requirement (components and the like).
+ */
+const EXEMPT_INIT_TYPES = new Set([
+    "ArrowFunctionExpression",
+    "FunctionExpression",
+    "ClassExpression",
+]);
+/**
+ * Narrows a node to an `Identifier`.
+ * Returns `null` if the node is not one.
+ */
+function asIdentifier(node) {
+    return node.type === "Identifier" ? node : null;
+}
+/**
+ * Whether the declarator's initializer exempts it from the naming requirement.
+ */
+function isExemptInitializer(init) {
+    return init !== null && EXEMPT_INIT_TYPES.has(init.type);
+}
+/**
+ * Whether a value is an array whose every element is a string.
+ */
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+/**
+ * Throws if `pattern` is not a valid regular expression source.
+ */
+function assertValidPattern(pattern) {
+    try {
+        new RegExp(pattern);
+    }
+    catch (error) {
+        throw new SyntaxError(`${RULE_ID}: invalid \`exceptionPatterns\` entry ${JSON.stringify(pattern)}: ${error.message}`);
+    }
+}
+/**
+ * Parses the raw first config element into typed options.
+ *
+ * The plugin interface types options as arbitrary JSON, so the shape declared by `meta.schema` is not guaranteed at runtime.
+ */
+function parseOptions(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw new TypeError(`${RULE_ID}: options must be an object, received ${Array.isArray(raw) ? "array" : typeof raw}.`);
+    const { exceptions, exceptionPatterns, ...rest } = raw;
+    const unknownKeys = Object.keys(rest);
+    if (unknownKeys.length > 0)
+        throw new TypeError(`${RULE_ID}: unknown option(s): ${unknownKeys.join(", ")}.`);
+    if (exceptions !== undefined && !isStringArray(exceptions))
+        throw new TypeError(`${RULE_ID}: \`exceptions\` must be an array of strings.`);
+    if (exceptionPatterns !== undefined && !isStringArray(exceptionPatterns))
+        throw new TypeError(`${RULE_ID}: \`exceptionPatterns\` must be an array of strings.`);
+    for (const pattern of exceptionPatterns ?? [])
+        assertValidPattern(pattern);
+    return { exceptions, exceptionPatterns };
+}
+/**
+ * Builds a predicate that reports whether a name is exempt by literal name or matching pattern.
+ */
+function makeIsExceptedName(options) {
+    const exceptions = new Set(options.exceptions ?? []);
+    const patterns = (options.exceptionPatterns ?? []).map((pattern) => new RegExp(pattern));
+    return function isExceptedName(name) {
+        return (exceptions.has(name) ||
+            patterns.some((pattern) => pattern.test(name)));
+    };
+}
+/**
+ * Reports any module-level `const` identifier that is neither exempt nor `SCREAMING_SNAKE_CASE`.
+ */
+function checkStatement(context, statement, isExceptedName) {
+    const declaration = asVariableDeclaration(unwrapExport(statement));
+    if (declaration === null)
+        return;
+    if (declaration.kind !== "const")
+        return;
+    for (const declarator of declaration.declarations) {
+        const id = asIdentifier(declarator.id);
+        if (id === null)
+            continue;
+        if (isExemptInitializer(declarator.init))
+            continue;
+        if (isExceptedName(id.name))
+            continue;
+        if (SCREAMING_SNAKE.test(id.name))
+            continue;
+        context.report({
+            node: id,
+            messageId: "notScreamingSnake",
+            data: { name: id.name },
+        });
+    }
+}
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Require module-level `const` identifiers to be SCREAMING_SNAKE_CASE.",
+            recommended: true,
+        },
+        messages: {
+            notScreamingSnake: "Module-level constant `{{name}}` must be SCREAMING_SNAKE_CASE.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    exceptions: { type: "array", items: { type: "string" } },
+                    exceptionPatterns: {
+                        type: "array",
+                        items: { type: "string" },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    create(context) {
+        const options = parseOptions(context.options[0]);
+        const isExceptedName = makeIsExceptedName(options);
+        return {
+            Program(node) {
+                for (const statement of node.body)
+                    checkStatement(context, statement, isExceptedName);
+            },
+        };
+    },
+};

package/dist/rules/module-structure-order.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Rule: enforce top-level declaration order.
+ */
+import type { Context, Visitor } from "@oxlint/plugins";
+declare const _default: {
+    meta: {
+        type: "suggestion";
+        docs: {
+            description: string;
+            recommended: boolean;
+        };
+        messages: {
+            outOfOrder: string;
+        };
+    };
+    create(context: Context): Visitor;
+};
+export default _default;

package/dist/rules/module-structure-order.js

@@ -0,0 +1,96 @@
+/**
+ * @file Rule: enforce top-level declaration order.
+ */
+import { asVariableDeclaration, isExportStatement, unwrapExport, } from "../shared/ast.js";
+/**
+ * Human-readable labels for each declaration rank, keyed by descending priority.
+ */
+const RANK_LABELS = {
+    1: "Imports",
+    2: "Type aliases",
+    3: "Interfaces",
+    4: "`const` declarations",
+    5: "`let` declarations",
+    6: "Functions",
+    7: "Exports",
+};
+/**
+ * Rank of the trailing exports group.
+ *
+ * TODO: unhardcode
+ */
+const RANK_EXPORTS = 7;
+/**
+ * Returns rank of a non-export declaration, or `null` if it is not a ranked declaration kind.
+ */
+function rankOfDeclaration(node) {
+    if (node.type === "ImportDeclaration")
+        return 1;
+    if (node.type === "TSTypeAliasDeclaration")
+        return 2;
+    if (node.type === "TSInterfaceDeclaration")
+        return 3;
+    if (node.type === "FunctionDeclaration")
+        return 6;
+    const declaration = asVariableDeclaration(node);
+    if (declaration === null)
+        return null;
+    return declaration.kind === "const" ? 4 : 5;
+}
+/**
+ * Returns rank of any top-level statement, including exports.
+ * Exports unwrap to the rank of their inner declaration, or the trailing exports rank when bare.
+ */
+function rankOf(node) {
+    if (node.type === "ExportDefaultDeclaration" ||
+        node.type === "ExportAllDeclaration")
+        return RANK_EXPORTS;
+    if (node.type === "ExportNamedDeclaration") {
+        const inner = unwrapExport(node);
+        // * bare `export { … }` has no inner declaration and is a trailing export
+        return inner === node ? RANK_EXPORTS : rankOfDeclaration(inner);
+    }
+    return rankOfDeclaration(node);
+}
+/**
+ * Walks the program body and reports any statement whose rank falls below a rank already seen.
+ */
+function checkProgram(context, node) {
+    let maxRank = 0;
+    for (const statement of node.body) {
+        const rank = rankOf(statement);
+        if (rank === null)
+            continue;
+        if (rank < maxRank) {
+            const label = isExportStatement(statement) && rank === RANK_EXPORTS
+                ? RANK_LABELS[7]
+                : RANK_LABELS[rank];
+            context.report({
+                node: statement,
+                messageId: "outOfOrder",
+                data: { kind: label ?? "Declaration" },
+            });
+            continue;
+        }
+        maxRank = rank;
+    }
+}
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Enforce top-level declaration order: imports, types, interfaces, constants, functions, exports.",
+            recommended: true,
+        },
+        messages: {
+            outOfOrder: "{{kind}} are out of order. Expected: imports, types, interfaces, const, let, functions, exports.",
+        },
+    },
+    create(context) {
+        return {
+            Program(node) {
+                checkProgram(context, node);
+            },
+        };
+    },
+};

package/dist/rules/require-file-jsdoc.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Rule: every file must open with a JSDoc block with a `@file` declaration before the first statement.
+ */
+import type { Context, Visitor } from "@oxlint/plugins";
+declare const _default: {
+    meta: {
+        type: "suggestion";
+        docs: {
+            description: string;
+            recommended: boolean;
+        };
+        messages: {
+            missingFileJsdoc: string;
+        };
+    };
+    create(context: Context): Visitor;
+};
+export default _default;

package/dist/rules/require-file-jsdoc.js

@@ -0,0 +1,50 @@
+/**
+ * @file Rule: every file must open with a JSDoc block with a `@file` declaration before the first statement.
+ */
+/**
+ * Whether the comment is a block JSDoc containing an `@file` tag.
+ */
+function isFileJsdoc(comment) {
+    return (comment.type === "Block" &&
+        comment.value.startsWith("*") &&
+        comment.value.includes("@file"));
+}
+/**
+ * Reports when the file does not open with a `@file` JSDoc block before the first statement.
+ */
+function checkProgram(context, node) {
+    const comments = context.sourceCode.getAllComments();
+    const firstComment = comments.find((comment) => comment.type !== "Shebang");
+    const firstStatement = node.body[0];
+    // * an empty file has nothing to document
+    if (firstStatement === undefined && comments.length === 0)
+        return;
+    const isBeforeBody = firstComment !== undefined &&
+        (firstStatement === undefined ||
+            firstComment.range[0] < firstStatement.range[0]);
+    if (firstComment !== undefined && isBeforeBody && isFileJsdoc(firstComment))
+        return;
+    context.report({
+        loc: { line: 1, column: 0 },
+        messageId: "missingFileJsdoc",
+    });
+}
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Require every file to open with a `@file` JSDoc block before the first statement.",
+            recommended: true,
+        },
+        messages: {
+            missingFileJsdoc: "File must begin with a `/** … @file … */` JSDoc block.",
+        },
+    },
+    create(context) {
+        return {
+            Program(node) {
+                checkProgram(context, node);
+            },
+        };
+    },
+};

package/dist/rules/require-jsdoc.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Rule: top-level functions, types, interfaces, and `const`s require a preceding block JSDoc.
+ */
+import type { Context, Visitor } from "@oxlint/plugins";
+declare const _default: {
+    meta: {
+        type: "suggestion";
+        docs: {
+            description: string;
+            recommended: boolean;
+        };
+        messages: {
+            missingJsdoc: string;
+        };
+    };
+    create(context: Context): Visitor;
+};
+export default _default;

package/dist/rules/require-jsdoc.js

@@ -0,0 +1,79 @@
+/**
+ * @file Rule: top-level functions, types, interfaces, and `const`s require a preceding block JSDoc.
+ */
+import { asVariableDeclaration, unwrapExport } from "../shared/ast.js";
+/**
+ * Node types that require a preceding block JSDoc.
+ */
+const DOCUMENTABLE_TYPES = new Set([
+    "FunctionDeclaration",
+    "TSTypeAliasDeclaration",
+    "TSInterfaceDeclaration",
+]);
+/**
+ * Whether the node is a kind that must carry a block JSDoc.
+ */
+function isDocumentable(node) {
+    if (DOCUMENTABLE_TYPES.has(node.type))
+        return true;
+    const declaration = asVariableDeclaration(node);
+    return declaration !== null && declaration.kind === "const";
+}
+/**
+ * Whether the comment immediately preceding the statement is a JSDoc.
+ */
+function hasBlockJsdoc(context, statement) {
+    const comments = context.sourceCode.getCommentsBefore(statement);
+    const last = comments[comments.length - 1];
+    return (last !== undefined &&
+        last.type === "Block" &&
+        last.value.startsWith("*"));
+}
+/**
+ * Returns a human-readable label for the declaration kind.
+ */
+function labelFor(node) {
+    if (node.type === "FunctionDeclaration")
+        return "Function";
+    if (node.type === "TSTypeAliasDeclaration")
+        return "Type";
+    if (node.type === "TSInterfaceDeclaration")
+        return "Interface";
+    return "Constant";
+}
+/**
+ * Reports a documentable statement that lacks a preceding block JSDoc.
+ */
+function checkStatement(context, statement) {
+    const target = unwrapExport(statement);
+    if (!isDocumentable(target))
+        return;
+    if (hasBlockJsdoc(context, statement))
+        return;
+    context.report({
+        node: target,
+        messageId: "missingJsdoc",
+        data: { kind: labelFor(target) },
+    });
+}
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Require a preceding block JSDoc on top-level functions, types, interfaces, and `const`s.",
+            recommended: true,
+        },
+        messages: {
+            missingJsdoc: "{{kind}} declaration must have a preceding block JSDoc (`/** … */`).",
+        },
+    },
+    create(context) {
+        return {
+            Program(node) {
+                for (const statement of node.body) {
+                    checkStatement(context, statement);
+                }
+            },
+        };
+    },
+};

package/dist/shared/ast.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Shared AST helpers used by multiple rules.
+ */
+import type { ESTree } from "@oxlint/plugins";
+/**
+ * Narrows a node to a `VariableDeclaration`, or `null` if it is not one.
+ */
+export declare function asVariableDeclaration(node: ESTree.Node): ESTree.VariableDeclaration | null;
+/**
+ * `true` if the node is any `export …` statement.
+ */
+export declare function isExportStatement(node: ESTree.Node): boolean;
+/**
+ * Unwrap an `export const`/`export function`/etc. to its inner declaration.
+ *
+ * Returns the node unchanged if it is not an inline-exported declaration.
+ */
+export declare function unwrapExport(node: ESTree.Node): ESTree.Node;

package/dist/shared/ast.js

@@ -0,0 +1,25 @@
+/**
+ * @file Shared AST helpers used by multiple rules.
+ */
+/**
+ * Narrows a node to a `VariableDeclaration`, or `null` if it is not one.
+ */
+export function asVariableDeclaration(node) {
+    return node.type === "VariableDeclaration" ? node : null;
+}
+/**
+ * `true` if the node is any `export …` statement.
+ */
+export function isExportStatement(node) {
+    return node.type.startsWith("Export");
+}
+/**
+ * Unwrap an `export const`/`export function`/etc. to its inner declaration.
+ *
+ * Returns the node unchanged if it is not an inline-exported declaration.
+ */
+export function unwrapExport(node) {
+    if (node.type !== "ExportNamedDeclaration")
+        return node;
+    return node.declaration ?? node;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "oxlint-frontier-style",
+	"version": "1.0.0",
+	"description": "oxlint plugin enforcing the Frontier code style",
+	"keywords": [
+		"oxlint",
+		"plugin"
+	],
+	"homepage": "https://github.com/Hyperseeker/oxlint-frontier-style",
+	"bugs": {
+		"url": "https://github.com/Hyperseeker/oxlint-frontier-style/issues"
+	},
+	"license": "MIT",
+	"repository": "github:Hyperseeker/oxlint-frontier-style",
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"main": "dist/index.js",
+	"exports": {
+		".": "./dist/index.js",
+		"./recommended": "./dist/recommended.js"
+	},
+	"scripts": {
+		"build": "tsgo -b",
+		"typecheck": "tsgo --noEmit",
+		"lint": "oxlint",
+		"format": "oxfmt",
+		"format:check": "oxfmt --check",
+		"ci": "bun run typecheck && bun run lint && bun run format:check",
+		"clean": "rm -rf dist tsconfig.tsbuildinfo",
+		"prepublishOnly": "bun run ci && bun run clean && bun run build"
+	},
+	"devDependencies": {
+		"@oxlint/plugins": "^1.48.0",
+		"@types/node": "^25.9.1",
+		"oxfmt": "^0.54.0",
+		"oxlint": "^1.48.0",
+		"oxlint-tsgolint": "^0.23.0"
+	}
+}