@goodbones/oxlint 0.1.0-beta.1

package/src/members-rule.ts

@@ -0,0 +1,205 @@
+import {
+  type CompiledMemberRule,
+  type DeclarationKind,
+  evaluateMemberSite,
+  formatMessage,
+  type LoadedPolicy,
+  memberRulesSelecting,
+} from "@goodbones/core";
+
+import {
+  type OxlintRule,
+  type ReportableNode,
+  type RuleContext,
+  toRepoRelative,
+} from "./oxlint-api.js";
+
+type NamedNode = ReportableNode & {
+  readonly type: string;
+  readonly name?: unknown;
+  readonly value?: unknown;
+};
+
+type MemberNode = ReportableNode & {
+  readonly type: string;
+  readonly key?: (NamedNode & { readonly type?: string }) | null;
+  readonly computed?: boolean;
+  // A class method's kind: `method`, `get`, `set` or `constructor`.
+  readonly kind?: string;
+};
+
+// A type, as far as this rule reads it: a literal with members, or an
+// intersection / union / parenthesised type wrapping others.
+type TypeNode = ReportableNode & {
+  readonly type: string;
+  readonly members?: ReadonlyArray<MemberNode>;
+  readonly types?: ReadonlyArray<TypeNode>;
+  readonly typeAnnotation?: TypeNode | null;
+};
+
+type TypeAliasNode = ReportableNode & {
+  readonly id?: NamedNode | null;
+  readonly typeAnnotation?: TypeNode | null;
+};
+
+// Every visitor takes the whole `Node` union, so `body` is typed to admit a
+// function body as readily as an interface's, and narrowed below.
+type InterfaceNode = ReportableNode & {
+  readonly id?: NamedNode | null;
+  readonly body?: { readonly type?: string; readonly body?: unknown } | null;
+};
+
+type ClassNode = InterfaceNode;
+
+const isMemberList = (value: unknown): value is ReadonlyArray<MemberNode> => Array.isArray(value);
+
+type CallNode = ReportableNode & {
+  readonly callee?:
+    | (ReportableNode & {
+        readonly type: string;
+        readonly name?: unknown;
+        readonly computed?: boolean;
+        readonly property?: (NamedNode & { readonly type: string }) | null;
+      })
+    | null;
+};
+
+// The member shapes that carry a name a vocabulary rule can speak about: a
+// property or method signature in a type, a property, method or accessor in a
+// class. Mirrors the CLI's `isNamedMember`.
+const DECLARED_MEMBER_TYPES = new Set([
+  "TSPropertySignature",
+  "TSMethodSignature",
+  "PropertyDefinition",
+  "MethodDefinition",
+  "TSAbstractPropertyDefinition",
+  "TSAbstractMethodDefinition",
+]);
+
+// The type literals written in a type, through intersections, unions and
+// parentheses. A reference is not followed: its members are declared where it
+// is, and reported there under its own name. Mirrors the CLI's `literalsOf`.
+const literalsOf = (node: TypeNode | null | undefined): ReadonlyArray<TypeNode> => {
+  if (node === null || node === undefined) return [];
+  switch (node.type) {
+    case "TSTypeLiteral":
+      return [node];
+    case "TSIntersectionType":
+    case "TSUnionType":
+      return (node.types ?? []).flatMap(literalsOf);
+    case "TSParenthesizedType":
+      return literalsOf(node.typeAnnotation);
+    default:
+      return [];
+  }
+};
+
+const nameOf = (node: NamedNode | null | undefined): string | null => {
+  if (node === null || node === undefined) return null;
+  if (typeof node.name === "string") return node.name;
+  return typeof node.value === "string" ? node.value : null;
+};
+
+// The name a call is made by: `f()` and `x.f()` are both `f`. `x[f]()` and
+// `x["f"]()` are not — a computed property is not a name a vocabulary rule can
+// speak about — and neither is a private `x.#f()`. The CLI reads the same
+// three cases out of TypeScript's tree; the parity suite keeps them agreeing.
+const calleeName = (node: CallNode): string | null => {
+  const callee = node.callee;
+  if (callee === null || callee === undefined) return null;
+  if (callee.type === "Identifier" && typeof callee.name === "string") return callee.name;
+  if (callee.type !== "MemberExpression" || callee.computed === true) return null;
+  const property = callee.property;
+  if (property?.type !== "Identifier") return null;
+  return nameOf(property);
+};
+
+export const makeMembersRule = (policy: LoadedPolicy): OxlintRule => ({
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "which names a file may declare or call — a port's method vocabulary, a tier's allowed hooks",
+    },
+    schema: [],
+  },
+
+  createOnce(context: RuleContext) {
+    let file = "";
+    let selected: ReadonlyArray<CompiledMemberRule> = [];
+
+    const report = (
+      node: ReportableNode,
+      name: string,
+      declaration?: { readonly name: string; readonly declares: DeclarationKind },
+    ): void => {
+      const violations = evaluateMemberSite(selected, {
+        file,
+        subject: declaration === undefined ? "calls" : "members",
+        name,
+        ...(declaration === undefined
+          ? {}
+          : { in: declaration.name, declares: declaration.declares }),
+      });
+      for (const violation of violations) {
+        if (policy.baseline.isBaselined(violation)) continue;
+        context.report({ node, message: formatMessage(violation) });
+      }
+    };
+
+    // The members written in a declaration, under that declaration's name and
+    // kind. A computed key is not a name a vocabulary rule can speak about;
+    // neither is a private `#name`, an index, call or construct signature, or
+    // a constructor.
+    const declared = (
+      declaration: string,
+      declares: DeclarationKind,
+      members: ReadonlyArray<MemberNode>,
+    ): void => {
+      for (const member of members) {
+        if (member.computed === true || !DECLARED_MEMBER_TYPES.has(member.type)) continue;
+        if (member.key?.type === "PrivateIdentifier" || member.kind === "constructor") continue;
+        const name = nameOf(member.key);
+        if (name !== null) report(member.key ?? member, name, { name: declaration, declares });
+      }
+    };
+
+    return {
+      before() {
+        file = toRepoRelative(policy.repoRoot, context.filename);
+        if (file.startsWith("..")) return false;
+        selected = memberRulesSelecting(policy.memberRules, file);
+        return selected.length > 0;
+      },
+
+      TSTypeAliasDeclaration(node: TypeAliasNode) {
+        const declaration = nameOf(node.id);
+        if (declaration === null) return;
+        for (const literal of literalsOf(node.typeAnnotation)) {
+          declared(declaration, "type", literal.members ?? []);
+        }
+      },
+
+      TSInterfaceDeclaration(node: InterfaceNode) {
+        const declaration = nameOf(node.id);
+        const members = node.body?.body;
+        if (declaration === null || !isMemberList(members)) return;
+        declared(declaration, "interface", members);
+      },
+
+      // A named class only, as the CLI reads it: an anonymous default class has
+      // no name for `in`, and a class expression is a value.
+      ClassDeclaration(node: ClassNode) {
+        const declaration = nameOf(node.id);
+        const members = node.body?.body;
+        if (declaration === null || !isMemberList(members)) return;
+        declared(declaration, "class", members);
+      },
+
+      CallExpression(node: CallNode) {
+        const name = calleeName(node);
+        if (name !== null) report(node, name);
+      },
+    };
+  },
+});

package/src/oxlint-api.ts

@@ -0,0 +1,66 @@
+import * as path from "node:path";
+
+import type { RuleTester } from "oxlint/plugins-dev";
+
+// oxlint publishes no plugin types, so the exact `Context`, node and fixer shapes
+// are recovered from `RuleTester`'s own signature — the one public surface that
+// names them. Hand-rolling them drifts silently against an alpha API.
+export type OxlintRule = Parameters<RuleTester["run"]>[1];
+export type RuleContext = Parameters<Extract<OxlintRule, { createOnce: unknown }>["createOnce"]>[0];
+
+type Diagnostic = Parameters<RuleContext["report"]>[0];
+export type ReportableNode = Extract<Diagnostic, { node: unknown }>["node"];
+export type Fixer = Parameters<NonNullable<Diagnostic["fix"]>>[0];
+
+export type SourceNode = ReportableNode & {
+  readonly source?: { readonly value?: unknown } | null;
+};
+
+export const toRepoRelative = (repoRoot: string, filename: string): string =>
+  path.relative(repoRoot, filename).replaceAll(path.sep, "/");
+
+export const specifierOf = (node: SourceNode): string | null => {
+  const value = node.source?.value;
+  return typeof value === "string" ? value : null;
+};
+
+// The three forms that name a module without an `import … from`. Each is an
+// edge for the import rule and a whole-module binding for the export rule, so
+// both read them through these.
+
+// `require("m")` — a CallExpression whose callee is the bare identifier.
+export type CallNode = ReportableNode & {
+  readonly callee?: { readonly type: string; readonly name?: unknown } | null;
+  readonly arguments?: ReadonlyArray<{ readonly type: string; readonly value?: unknown }> | null;
+};
+
+// `import("m")` — `source` is any expression; only a string literal is an edge.
+export type ImportExpressionNode = ReportableNode & {
+  readonly source?: { readonly type?: string; readonly value?: unknown } | null;
+};
+
+// `import x = require("m")` — the module is under `moduleReference`, not `source`.
+export type ImportEqualsNode = ReportableNode & {
+  readonly moduleReference?: {
+    readonly type: string;
+    readonly expression?: { readonly value?: unknown } | null;
+  } | null;
+};
+
+export const requireSpecifierOf = (node: CallNode): string | null => {
+  if (node.callee?.type !== "Identifier" || node.callee.name !== "require") return null;
+  const [first] = node.arguments ?? [];
+  return first?.type === "Literal" && typeof first.value === "string" ? first.value : null;
+};
+
+export const importExpressionSpecifierOf = (node: ImportExpressionNode): string | null => {
+  const source = node.source;
+  return source?.type === "Literal" && typeof source.value === "string" ? source.value : null;
+};
+
+export const importEqualsSpecifierOf = (node: ImportEqualsNode): string | null => {
+  const reference = node.moduleReference;
+  if (reference?.type !== "TSExternalModuleReference") return null;
+  const value = reference.expression?.value;
+  return typeof value === "string" ? value : null;
+};

package/src/plugin.ts

@@ -0,0 +1,44 @@
+import { DEFAULT_CONFIG_FILENAME, loadPolicyFromFile } from "./config-loader.js";
+import { makeExportsRule } from "./exports-rule.js";
+import { makeImportsRule } from "./imports-rule.js";
+import { makeMembersRule } from "./members-rule.js";
+import type { OxlintRule } from "./oxlint-api.js";
+import { makeStructureRule } from "./structure-rule.js";
+import { makeSurfaceRule } from "./surface-rule.js";
+
+// oxlint imports this module once per lint run and reads `rules` synchronously,
+// so the policy is loaded here rather than inside a rule. A load failure throws
+// out of the import and fails the run — which is the point: a plugin that came
+// up with no policy would report nothing and be indistinguishable from a clean
+// codebase.
+const policy = await loadPolicyFromFile(
+  process.env.ARCHITECTURE_ROOT ?? process.cwd(),
+  process.env.ARCHITECTURE_CONFIG ?? DEFAULT_CONFIG_FILENAME,
+);
+
+// A manifest written in a shape on its way out still loads; it says so once,
+// here, rather than on every file.
+for (const notice of policy.notices) {
+  process.stderr.write(`[architecture] deprecated: ${notice}\n`);
+}
+
+export const rules: {
+  readonly imports: OxlintRule;
+  readonly exports: OxlintRule;
+  readonly members: OxlintRule;
+  readonly structure: OxlintRule;
+  readonly surface: OxlintRule;
+} = {
+  imports: makeImportsRule(policy),
+  exports: makeExportsRule(policy),
+  members: makeMembersRule(policy),
+  structure: makeStructureRule(policy),
+  surface: makeSurfaceRule(policy),
+};
+
+const plugin: { readonly meta: { readonly name: string }; readonly rules: typeof rules } = {
+  meta: { name: "architecture" },
+  rules,
+};
+
+export default plugin;

package/src/structure-rule.ts

@@ -0,0 +1,38 @@
+import { evaluateStructure, formatMessage, type LoadedPolicy } from "@goodbones/core";
+
+import { type OxlintRule, type RuleContext, toRepoRelative } from "./oxlint-api.js";
+
+export const makeStructureRule = (policy: LoadedPolicy): OxlintRule => ({
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "the file taxonomy: which file kinds a folder admits, and which siblings a file owes",
+    },
+    schema: [],
+  },
+
+  createOnce(context: RuleContext) {
+    // The taxonomy is a property of the path, not of the syntax, so the whole
+    // check runs once in `before` and the visitor exists only because oxlint
+    // does not run hooks for a rule with no visitor keys.
+    return {
+      before() {
+        const file = toRepoRelative(policy.repoRoot, context.filename);
+        if (file.startsWith("..")) return false;
+
+        for (const violation of evaluateStructure(policy.structure, policy.fileSystem, file)) {
+          if (policy.baseline.isBaselined(violation)) continue;
+          context.report({
+            message: formatMessage(violation),
+            loc: { line: 1, column: 0 },
+          });
+        }
+        return false;
+      },
+      Program() {
+        return undefined;
+      },
+    };
+  },
+});

package/src/surface-rule.ts

@@ -0,0 +1,237 @@
+import {
+  type CompiledSurfaceRule,
+  type DeclarationKind,
+  evaluateSurface,
+  type ExportSite,
+  formatMessage,
+  type LoadedPolicy,
+  surfaceRulesSelecting,
+} from "@goodbones/core";
+
+import {
+  type OxlintRule,
+  type ReportableNode,
+  type RuleContext,
+  toRepoRelative,
+} from "./oxlint-api.js";
+
+type NamedNode = ReportableNode & {
+  readonly type?: string;
+  readonly name?: unknown;
+  readonly value?: unknown;
+};
+
+// A top-level statement, as far as this rule reads one. Every field is
+// optional because the visitor takes the whole `Node` union; each is checked
+// before use.
+type StatementNode = ReportableNode & {
+  readonly type: string;
+  readonly id?: NamedNode | null;
+  readonly declaration?: StatementNode | null;
+  readonly declarations?: ReadonlyArray<{ readonly id?: PatternNode | null }> | null;
+  readonly specifiers?: ReadonlyArray<SpecifierNode> | null;
+  readonly source?: { readonly value?: unknown } | null;
+  readonly exported?: NamedNode | null;
+};
+
+type PatternNode = ReportableNode & {
+  readonly type: string;
+  readonly name?: unknown;
+  readonly properties?: ReadonlyArray<{
+    readonly value?: PatternNode | null;
+    readonly argument?: PatternNode | null;
+  }> | null;
+  readonly elements?: ReadonlyArray<PatternNode | null> | null;
+  readonly left?: PatternNode | null;
+  readonly argument?: PatternNode | null;
+};
+
+type SpecifierNode = ReportableNode & {
+  readonly exported?: NamedNode | null;
+  readonly local?: NamedNode | null;
+};
+
+type ProgramNode = ReportableNode & { readonly body?: unknown };
+
+const isStatementList = (value: unknown): value is ReadonlyArray<StatementNode> =>
+  Array.isArray(value);
+
+const nameOf = (node: NamedNode | null | undefined): string | null => {
+  if (node === null || node === undefined) return null;
+  if (typeof node.name === "string") return node.name;
+  return typeof node.value === "string" ? node.value : null;
+};
+
+// The identifiers a binding pattern introduces.
+const patternNames = (pattern: PatternNode | null | undefined): ReadonlyArray<string> => {
+  if (pattern === null || pattern === undefined) return [];
+  switch (pattern.type) {
+    case "Identifier":
+      return typeof pattern.name === "string" ? [pattern.name] : [];
+    case "ObjectPattern":
+      return (pattern.properties ?? []).flatMap((property) =>
+        patternNames(property.value ?? property.argument),
+      );
+    case "ArrayPattern":
+      return (pattern.elements ?? []).flatMap(patternNames);
+    case "AssignmentPattern":
+      return patternNames(pattern.left);
+    case "RestElement":
+      return patternNames(pattern.argument);
+    default:
+      return [];
+  }
+};
+
+// The names a declaration statement introduces, with what it declares them as.
+const declaredNamesOf = (
+  statement: StatementNode,
+): ReadonlyArray<readonly [string, DeclarationKind]> => {
+  const named = (declares: DeclarationKind): ReadonlyArray<readonly [string, DeclarationKind]> => {
+    const name = nameOf(statement.id);
+    return name === null ? [] : [[name, declares]];
+  };
+  switch (statement.type) {
+    case "FunctionDeclaration":
+      return named("function");
+    case "ClassDeclaration":
+      return named("class");
+    case "VariableDeclaration":
+      return (statement.declarations ?? []).flatMap((declaration) =>
+        patternNames(declaration.id).map((name) => [name, "variable"] as const),
+      );
+    case "TSTypeAliasDeclaration":
+      return named("type");
+    case "TSInterfaceDeclaration":
+      return named("interface");
+    case "TSEnumDeclaration":
+      return named("enum");
+    case "TSModuleDeclaration":
+      return named("other");
+    default:
+      return [];
+  }
+};
+
+type Found = { readonly site: ExportSite; readonly node: ReportableNode };
+
+// A file's surface, read off the program body rather than by visiting export
+// nodes: an `export` inside a namespace body is that namespace's, not the
+// module's, and reading the top level directly is what says so without a
+// parent pointer. Mirrors the CLI's `exportSitesOf`.
+const surfaceOf = (file: string, body: ReadonlyArray<StatementNode>): ReadonlyArray<Found> => {
+  const locals = new Map<string, DeclarationKind>();
+  for (const statement of body) {
+    const declaration =
+      statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration"
+        ? statement.declaration
+        : statement;
+    if (declaration === null || declaration === undefined) continue;
+    for (const [name, declares] of declaredNamesOf(declaration)) locals.set(name, declares);
+  }
+
+  const found: Array<Found> = [];
+  const site = (
+    node: ReportableNode,
+    name: string,
+    kind: ExportSite["kind"],
+    declares: DeclarationKind,
+    reexport: boolean,
+  ): void => {
+    found.push({ node, site: { file, name, kind, declares, reexport } });
+  };
+
+  for (const statement of body) {
+    switch (statement.type) {
+      case "ExportNamedDeclaration": {
+        const declaration = statement.declaration;
+        if (declaration !== null && declaration !== undefined) {
+          for (const [name, declares] of declaredNamesOf(declaration)) {
+            site(declaration, name, "named", declares, false);
+          }
+          break;
+        }
+        const reexport = typeof statement.source?.value === "string";
+        for (const specifier of statement.specifiers ?? []) {
+          const name = nameOf(specifier.exported);
+          if (name === null) continue;
+          const local = nameOf(specifier.local) ?? name;
+          const declares = reexport ? "other" : (locals.get(local) ?? "other");
+          site(specifier, name, name === "default" ? "default" : "named", declares, reexport);
+        }
+        break;
+      }
+      case "ExportDefaultDeclaration": {
+        const declaration = statement.declaration;
+        const declares: DeclarationKind =
+          declaration === null || declaration === undefined
+            ? "expression"
+            : declaration.type === "FunctionDeclaration"
+              ? "function"
+              : declaration.type === "ClassDeclaration"
+                ? "class"
+                : declaration.type === "TSInterfaceDeclaration"
+                  ? "interface"
+                  : declaration.type === "Identifier"
+                    ? (locals.get(nameOf(declaration) ?? "") ?? "expression")
+                    : "expression";
+        site(statement, "default", "default", declares, false);
+        break;
+      }
+      case "ExportAllDeclaration":
+        site(statement, nameOf(statement.exported) ?? "*", "namespace", "other", true);
+        break;
+      default:
+        break;
+    }
+  }
+  return found;
+};
+
+export const makeSurfaceRule = (policy: LoadedPolicy): OxlintRule => ({
+  meta: {
+    type: "problem" as const,
+    docs: {
+      description:
+        "what a file may export — no default exports, a barrel that only re-exports, a handler that exports one function",
+    },
+    schema: [],
+  },
+
+  createOnce(context: RuleContext) {
+    let file = "";
+    let selected: ReadonlyArray<CompiledSurfaceRule> = [];
+
+    return {
+      before() {
+        file = toRepoRelative(policy.repoRoot, context.filename);
+        if (file.startsWith("..")) return false;
+        selected = surfaceRulesSelecting(policy.surfaceRules, file);
+        return selected.length > 0;
+      },
+
+      Program(node: ProgramNode) {
+        if (!isStatementList(node.body)) return;
+        const found = surfaceOf(file, node.body);
+        const violations = evaluateSurface(
+          selected,
+          file,
+          found.map((one) => one.site),
+        );
+
+        // A per-site violation lands on the site's own node; a `count` one, on
+        // the program — it is about the file.
+        const used = new Set<Found>();
+        for (const violation of violations) {
+          if (policy.baseline.isBaselined(violation)) continue;
+          const at =
+            violation.subject === null
+              ? undefined
+              : found.find((one) => one.site.name === violation.subject && !used.has(one));
+          if (at !== undefined) used.add(at);
+          context.report({ node: at?.node ?? node, message: formatMessage(violation) });
+        }
+      },
+    };
+  },
+});