@starci/eslint-canon-be 1.0.0

package/exceptions.mjs

@@ -0,0 +1,265 @@
+/**
+ * The rules that hold `exceptions.md`.
+ *
+ * FOUR RULES, AND THE PAIRING IS THE POINT. Two watch the throw site and two watch the declaration,
+ * because either half alone has a hole the other closes: a class that extends a framework base is
+ * thrown by its own house-shaped name, so a throw-site rule passes it, and one such class stayed
+ * live and thrown from four call sites while the gate stayed green.
+ *
+ * `throw-abstract-exception` is a heuristic and says so: a rule reading one file at a time cannot
+ * verify that a thrown class extends anything, so it matches `Error` and a named list of framework
+ * exceptions. `exception-extends-abstract` is what makes that heuristic sound - it guarantees the
+ * only `*Exception` classes in the tree are house ones.
+ */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** The house base every exception extends. */
+const EXCEPTION_BASE = "AbstractException"
+
+/** Anything named like an exception. */
+const EXCEPTION_NAME = /Exception$/
+
+/** Framework exceptions that carry an HTTP status and no identity. */
+const FRAMEWORK_EXCEPTIONS = new Set([
+  "BadRequestException",
+  "NotFoundException",
+  "UnauthorizedException",
+  "ForbiddenException",
+  "InternalServerErrorException",
+  "HttpException",
+  "ConflictException",
+  "NotAcceptableException",
+  "RequestTimeoutException",
+  "GoneException",
+  "PayloadTooLargeException",
+  "UnsupportedMediaTypeException",
+  "UnprocessableEntityException",
+  "NotImplementedException",
+  "BadGatewayException",
+  "ServiceUnavailableException",
+  "GatewayTimeoutException",
+])
+
+/** Where every exception is declared. */
+const ERRORS_FOLDER = /\/exceptions\/errors\//
+
+/**
+ * True when a file sits in an exceptions folder - ANY of them.
+ *
+ * THE PATH USED TO BE `/platform/exceptions/errors/`, WHICH WAS ONE REPOSITORY'S LAYOUT WRITTEN
+ * INTO A LAW. EXCEPTION-4 asks for one place per APPLICATION to look, not for one literal path: a
+ * repository with several apps has `apps/<name>/src/exceptions/errors/` per app and still satisfies
+ * it, because "what can this application throw" still has a single answer.
+ *
+ * Measured before changing: the narrow path reported 83 findings in a second back end, and the top
+ * offenders were files already sitting in an `exceptions/errors/` folder - just not that one. A rule
+ * that fires on correct code is worse than no rule, because the next author learns to scroll past it.
+ */
+const isInErrorsFolder = (filename) => ERRORS_FOLDER.test(normalizePath(filename))
+
+/** The base class's own file, which is the one class allowed to extend something else. */
+const isExceptionBaseFile = (filename) => /exceptions\/errors\/abstract\.ts$/.test(normalizePath(filename))
+
+/**
+ * The test lanes, where `throw new Error` is a test-runner assertion rather than a domain failure.
+ *
+ * THE CARVE-OUT WAS ALREADY GRANTED IN PROSE AND MISSING FROM THE RULE, which is the worst of the
+ * two places for them to disagree: canon said the lanes may throw, the artifact said they may not,
+ * and a repository adopting the rule inherited 69 findings its own canon had already excused.
+ *
+ * A flow that could not fail its own setup would have to invent a domain exception for "the fixture
+ * is missing", which is a failure of the test rather than of the business - and naming it as a
+ * domain failure would put it in the same vocabulary the product uses to describe real ones.
+ */
+const isTestLane = (filename) => {
+  const path = normalizePath(filename)
+  return /\.spec\.ts$/.test(path) || /-spec\.ts$/.test(path) || path.includes("/src/tests/")
+}
+
+/**
+ * A liveness or readiness probe, where the HTTP STATUS is the whole contract.
+ *
+ * THE RULE'S OWN REASON IS WHAT GRANTS THIS. A framework exception is refused because it "carries an
+ * HTTP status and no identity" - the status is not enough to tell two failures apart. A probe is the
+ * one endpoint where that sentence inverts: kubernetes reads the status code and NOTHING else, never
+ * the body, so the status is the entire identity and a domain exception carrying a rich code would
+ * arrive as a 500 and be read as "down" for the wrong reason.
+ *
+ * Narrow on purpose. Only a health controller qualifies, so this cannot become the place a service
+ * goes to avoid naming its failures.
+ */
+const isHealthProbe = (filename) => /\/health(?:z)?\.controller\.ts$|\/health\//.test(normalizePath(filename))
+
+// -- EXCEPTION-1 -----------------------------------------------------------------------------------
+
+/** Throw a house exception, never `Error` and never a framework built-in. */
+export const throwAbstractException = {
+  meta: {
+    type: "problem",
+    docs: { description: "Throw an `AbstractException` subclass, not `Error` or a framework exception." },
+    schema: [],
+    messages: {
+      bareError:
+        "`throw new Error(...)` carries a sentence and no code, so nothing downstream can group, match or retry on it without parsing English. Throw the exception class that NAMES this failure.",
+      framework:
+        "`throw new {{name}}(...)` carries an HTTP status and no identity - two unrelated failures arrive at a client indistinguishable, and the only thing telling them apart is the message, which is the part that gets reworded. Throw an `AbstractException` subclass.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    // the lanes canon already excuses - see `isTestLane`
+    if (isTestLane(filename)) return {}
+    const probe = isHealthProbe(filename)
+    return {
+      ThrowStatement(node) {
+        const thrown = node.argument
+        if (!thrown || thrown.type !== "NewExpression" || thrown.callee.type !== "Identifier") return
+        const name = thrown.callee.name
+        if (name === "Error") {
+          context.report({ node: thrown, messageId: "bareError" })
+          return
+        }
+        // a probe answers with a status code and nothing else - see `isHealthProbe`. `Error` above
+        // is still refused here: a probe's status is its contract, an unnamed crash is not.
+        if (probe) return
+        if (FRAMEWORK_EXCEPTIONS.has(name)) {
+          context.report({ node: thrown, messageId: "framework", data: { name } })
+        }
+      },
+    }
+  },
+}
+
+// -- EXCEPTION-2 -----------------------------------------------------------------------------------
+
+/** The constructor takes one metadata object, `{}` when there is nothing to say. */
+export const requireExceptionObjectArg = {
+  meta: {
+    type: "problem",
+    docs: { description: "`new XException(...)` passes exactly one object-literal argument." },
+    schema: [],
+    messages: {
+      zero:
+        "`new {{name}}()` - pass the metadata object even when it is empty: `new {{name}}({})`. One spelling for every throw means a reader never has to check whether THIS exception happens to take arguments.",
+      notObject:
+        "`new {{name}}(...)` takes a metadata OBJECT, not a positional value. A positional shape cannot grow: the day this failure needs a second field, every throw site is edited and the ones edited wrong still compile.",
+      extra:
+        "`new {{name}}(...)` takes exactly ONE metadata object, not several arguments.",
+    },
+  },
+  create(context) {
+    return {
+      ThrowStatement(node) {
+        const thrown = node.argument
+        if (!thrown || thrown.type !== "NewExpression" || thrown.callee.type !== "Identifier") return
+        const name = thrown.callee.name
+        if (name === EXCEPTION_BASE || !EXCEPTION_NAME.test(name)) return
+        /*
+         * A FRAMEWORK EXCEPTION IS NOT A HOUSE ONE, AND ITS SHAPE IS NOT OURS TO DICTATE.
+         *
+         * This rule says a house exception takes exactly one metadata object. `EXCEPTION_NAME`
+         * matches anything ending in `Exception`, so it was also demanding that shape from Nest's
+         * own classes - `new ServiceUnavailableException(body)` is the constructor Nest published,
+         * and rewriting it to satisfy a house convention would change what the framework sends.
+         *
+         * Whether a framework exception may be thrown at all is EXCEPTION-1's question, and it
+         * answers it. This rule only governs the ones we declare.
+         */
+        if (FRAMEWORK_EXCEPTIONS.has(name)) return
+
+        if (thrown.arguments.length === 0) {
+          context.report({ node: thrown, messageId: "zero", data: { name } })
+          return
+        }
+        if (thrown.arguments.length > 1) {
+          context.report({ node: thrown, messageId: "extra", data: { name } })
+        }
+        if (thrown.arguments[0].type !== "ObjectExpression") {
+          context.report({ node: thrown.arguments[0], messageId: "notObject", data: { name } })
+        }
+      },
+    }
+  },
+}
+
+// -- EXCEPTION-3 -----------------------------------------------------------------------------------
+
+/** The class extends the house base, so the throw site tells the truth about what is thrown. */
+export const exceptionExtendsAbstract = {
+  meta: {
+    type: "problem",
+    docs: { description: "An `*Exception` class extends `AbstractException`." },
+    schema: [],
+    messages: {
+      base:
+        "`{{name}}` extends `{{parent}}`. Every exception extends `{{expected}}` - a framework base slips past the throw-site rule, because the throw then READS as a house exception and nothing looks wrong at any call site.",
+    },
+  },
+  create(context) {
+    if (isExceptionBaseFile(context.filename || context.getFilename())) return {}
+    return {
+      ClassDeclaration(node) {
+        if (!node.id || !EXCEPTION_NAME.test(node.id.name)) return
+        const parent = node.superClass
+        if (!parent || parent.type !== "Identifier" || parent.name === EXCEPTION_BASE) return
+        context.report({
+          node: parent,
+          messageId: "base",
+          data: { name: node.id.name, parent: parent.name, expected: EXCEPTION_BASE },
+        })
+      },
+    }
+  },
+}
+
+// -- EXCEPTION-4 -----------------------------------------------------------------------------------
+
+/** Every exception is declared in one folder, so the set of failures is readable in one place. */
+export const exceptionInErrorsFolder = {
+  meta: {
+    type: "problem",
+    docs: { description: "An `*Exception` class is declared under the exceptions folder." },
+    schema: [],
+    messages: {
+      place:
+        "`{{name}}` is declared outside the exceptions folder. They all live in one place so \"what can this application throw?\" has one answer, and so a reviewer sees a new failure mode ARRIVE in a diff rather than discovering it in production.",
+    },
+  },
+  create(context) {
+    if (isInErrorsFolder(context.filename || context.getFilename())) return {}
+    return {
+      ClassDeclaration(node) {
+        if (!node.id || !EXCEPTION_NAME.test(node.id.name)) return
+        // an undecorated class with no base is a shape, not an exception - the declaration this
+        // rule is after always extends something
+        if (!node.superClass) return
+        context.report({ node: node.id, messageId: "place", data: { name: node.id.name } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "throw-abstract-exception": throwAbstractException,
+  "require-exception-object-arg": requireExceptionObjectArg,
+  "exception-extends-abstract": exceptionExtendsAbstract,
+  "exception-in-errors-folder": exceptionInErrorsFolder,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * All four measured at zero debt in the reference repository. The sanctioned exit is stated where it
+ * applies rather than carved into the rule: the spec family and the test tree may `throw new Error`,
+ * because there it means "the runner cannot continue" rather than naming a failure the product can
+ * produce. A consuming repository turns `throw-abstract-exception` off for those globs.
+ */
+export const recommended = {
+  "starci-be/throw-abstract-exception": "error",
+  "starci-be/require-exception-object-arg": "error",
+  "starci-be/exception-extends-abstract": "error",
+  "starci-be/exception-in-errors-folder": "error",
+}

package/index.mjs

@@ -0,0 +1,90 @@
+/**
+ * The back-end plugin: every law's rules, gathered once.
+ *
+ * A consuming repository imports THIS and nothing below it. Registering rules one by one in the
+ * target's own plugin file is how the two lists drift: a law gains a rule here, nobody adds it there,
+ * and the rule ships as a document. That is not hypothetical for this axis - the back end kept a
+ * hand-written plugin whose names had already diverged from canon's, so `no-nest-logger` and
+ * `no-framework-logger` were one law wearing two names and no build could say which had fired.
+ *
+ * The target's `eslint.config.mjs` stays the authority on what is switched on, at what level and
+ * over which globs. That is a different question from what EXISTS, and this file answers only the
+ * second.
+ *
+ * WHAT THIS FILE REFUSES TO DO. It does not rename anything. A rule's published name is part of the
+ * law that declares it, because that name is what appears in a build log, in a disable comment and in
+ * every conversation about the failure. Aliasing one here to match a target's older spelling would
+ * leave two names for one rule and no way to tell which a message came from.
+ */
+import { recommended as authorizationRecommended, rules as authorizationRules } from "./authorization.mjs"
+import { recommended as cdcRecommended, rules as cdcRules } from "./cdc.mjs"
+import { recommended as commentsRecommended, rules as commentsRules } from "./comments.mjs"
+import { recommended as cqrsRecommended, rules as cqrsRules } from "./cqrs.mjs"
+import { recommended as dataAccessRecommended, rules as dataAccessRules } from "./data-access.mjs"
+import { recommended as e2eFlowRecommended, rules as e2eFlowRules } from "./e2e-flow.mjs"
+import { recommended as eventDeliveryRecommended, rules as eventDeliveryRules } from "./event-delivery.mjs"
+import { recommended as exceptionIdentityRecommended, rules as exceptionIdentityRules } from "./exception-identity.mjs"
+import { recommended as exceptionsRecommended, rules as exceptionsRules } from "./exceptions.mjs"
+import { recommended as moduleLayeringRecommended, rules as moduleLayeringRules } from "./module-layering.mjs"
+import { recommended as namingRecommended, rules as namingRules } from "./naming.mjs"
+import { recommended as observabilityRecommended, rules as observabilityRules } from "./observability.mjs"
+import { recommended as testingRecommended, rules as testingRules } from "./testing.mjs"
+import { recommended as transportRecommended, rules as transportRules } from "./transport.mjs"
+import { recommended as typeSafetyRecommended, rules as typeSafetyRules } from "./type-safety.mjs"
+
+/** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
+const CONTRIBUTIONS = [
+    { law: "authorization", rules: authorizationRules, recommended: authorizationRecommended },
+    { law: "cdc", rules: cdcRules, recommended: cdcRecommended },
+    { law: "comments", rules: commentsRules, recommended: commentsRecommended },
+    { law: "cqrs", rules: cqrsRules, recommended: cqrsRecommended },
+    { law: "data-access", rules: dataAccessRules, recommended: dataAccessRecommended },
+    { law: "e2e-flow", rules: e2eFlowRules, recommended: e2eFlowRecommended },
+    { law: "event-delivery", rules: eventDeliveryRules, recommended: eventDeliveryRecommended },
+    { law: "exception-identity", rules: exceptionIdentityRules, recommended: exceptionIdentityRecommended },
+    { law: "exceptions", rules: exceptionsRules, recommended: exceptionsRecommended },
+    { law: "module-layering", rules: moduleLayeringRules, recommended: moduleLayeringRecommended },
+    { law: "naming", rules: namingRules, recommended: namingRecommended },
+    { law: "observability", rules: observabilityRules, recommended: observabilityRecommended },
+    { law: "testing", rules: testingRules, recommended: testingRecommended },
+    { law: "transport", rules: transportRules, recommended: transportRecommended },
+    { law: "type-safety", rules: typeSafetyRules, recommended: typeSafetyRecommended },
+]
+
+/** Every gathered law. */
+export const lawOwners = CONTRIBUTIONS.map((entry) => entry.law)
+
+/**
+ * Which law declares each rule.
+ *
+ * Exported because a failing rule is a question about a LAW, and the shortest path from a build log
+ * to the document that explains it is this map. It is also what the twin test walks to prove no two
+ * laws claim one name.
+ */
+export const ruleOwners = Object.fromEntries(
+    CONTRIBUTIONS.flatMap((entry) => Object.keys(entry.rules).map((name) => [name, entry.law])),
+)
+
+/** Every rule this canon publishes, keyed by its published name. */
+export const rules = Object.fromEntries(
+    CONTRIBUTIONS.flatMap((entry) => Object.entries(entry.rules)),
+)
+
+/**
+ * The levels this canon asks for, as the plugin's own opinion.
+ *
+ * Unlike the front end, this axis allows `warn`, and the allowance is the burn-down playbook rather
+ * than a softer standard: a rule measured with debt arrives at `warn` with a ledger entry naming the
+ * offenders, and flips to `error` the day that entry closes. Switching a rule on over existing
+ * offenders is what teaches an author to scroll past it, and a reader who has learned to scroll past
+ * one rule reads none of them.
+ */
+export const recommended = Object.fromEntries(
+    CONTRIBUTIONS.flatMap((entry) => Object.entries(entry.recommended)),
+)
+
+/** The plugin object, shaped the way a flat config expects it. */
+export default {
+    meta: { name: "eslint-plugin-starci-be" },
+    rules,
+}

package/module-layering.mjs

@@ -0,0 +1,171 @@
+/**
+ * The rules that hold `module-layering.mjs`'s law file, `module-layering.md`.
+ *
+ * Two rules, both reading import specifiers against the path of the file doing the importing. They
+ * are cheap and exact, which is the whole reason they can be `error`.
+ *
+ * LAYERING-3 (a capability module importing a sibling capability) is NOT here, and the omission is
+ * deliberate rather than an oversight: deciding whether an imported module is a sibling capability
+ * or a nested child needs the module graph, and a rule reading one file at a time cannot see it. In
+ * the reference repository that rule exists and is scoped by path glob; a repository adopting this
+ * law should port it as a gate that walks the tree, not as a per-file rule that guesses.
+ *
+ * THE META-ROOT IS THE TRAP IN BOTH RULES. Some capabilities sit behind a category folder
+ * (`platform/`, `lib/`, `integrations/`), so the capability name is the SECOND segment there and
+ * the first everywhere else. Get that wrong and `@modules/platform/exceptions` reads as a
+ * capability-with-file rather than as a barrel.
+ */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/**
+ * Category folders that hold capabilities rather than being one.
+ *
+ * Under these the capability name is the second segment: `@modules/platform/exceptions` names a
+ * capability and no file, so it is a barrel -- while `@modules/ai` names a capability directly.
+ */
+const META_ROOTS = new Set(["platform", "lib", "integrations"])
+
+/** The aliases a capability is reachable through. */
+const ALIASES = [
+  {
+    prefix: "@modules/",
+    root: "/src/modules/",
+    metaAware: true,
+  },
+  {
+    prefix: "@features/",
+    root: "/src/features/",
+    metaAware: false,
+  },
+  {
+    prefix: "@tests/",
+    root: "/src/tests/",
+    metaAware: false,
+  },
+]
+
+// -- LAYERING-1 ------------------------------------------------------------------------------------
+
+/** An import names the declaring file, never a folder that re-exports one. */
+export const mustDeepModuleImport = {
+  meta: {
+    type: "problem",
+    docs: { description: "Import the declaring file, never a capability barrel." },
+    schema: [],
+    messages: {
+      barrel:
+        "`{{specifier}}` names a capability and no file. A barrel pulls the whole folder's import graph in to get one symbol - which is how a unit spec ends up booting a database driver, and how two capabilities that never reference each other end up in a cycle through a third. Name the file that declares the symbol.",
+    },
+  },
+  create(context) {
+    const check = (node, specifier) => {
+      if (typeof specifier !== "string") return
+      const alias = ALIASES.find((candidate) => specifier.startsWith(candidate.prefix))
+      if (!alias) return
+
+      const rest = specifier.slice(alias.prefix.length)
+      if (!rest) {
+        context.report({ node, messageId: "barrel", data: { specifier } })
+        return
+      }
+      const parts = rest.split("/")
+      const barrelDepth = alias.metaAware && META_ROOTS.has(parts[0])
+        ? 2
+        : 1
+      if (parts.length <= barrelDepth) {
+        context.report({ node, messageId: "barrel", data: { specifier } })
+      }
+    }
+    return {
+      ImportDeclaration(node) {
+        check(node.source, node.source.value)
+      },
+      ExportNamedDeclaration(node) {
+        if (node.source) check(node.source, node.source.value)
+      },
+      ExportAllDeclaration(node) {
+        if (node.source) check(node.source, node.source.value)
+      },
+    }
+  },
+}
+
+// -- LAYERING-2 ------------------------------------------------------------------------------------
+
+/** The aliases a file's OWN capability is reachable through, or null when it is in none. */
+const selfAliases = (filename) => {
+  const file = normalizePath(filename)
+  for (const alias of ALIASES) {
+    const at = file.lastIndexOf(alias.root)
+    if (at === -1) continue
+    const parts = file.slice(at + alias.root.length).split("/")
+    if (!parts[0]) continue
+    if (alias.metaAware && META_ROOTS.has(parts[0]) && parts.length >= 2) {
+      // reachable long (`platform/exceptions`) and short (`exceptions`), so both are self
+      return {
+        prefix: alias.prefix,
+        keys: [`${parts[0]}/${parts[1]}`, parts[1]],
+      }
+    }
+    return {
+      prefix: alias.prefix,
+      keys: [parts[0]],
+    }
+  }
+  return null
+}
+
+/** Inside a capability, imports are relative -- never the capability's own public alias. */
+export const noSelfModuleAlias = {
+  meta: {
+    type: "problem",
+    docs: { description: "Inside a capability, import relatively rather than through its own alias." },
+    schema: [],
+    messages: {
+      self:
+        "`{{specifier}}` reaches this capability through its own public alias. That is the capability talking to itself through its front door: a cycle magnet, and a lie about the boundary - the alias exists to say \"this comes from elsewhere\", so using it for something that does not is exactly the signal that stops meaning anything. Use a relative import.",
+    },
+  },
+  create(context) {
+    const self = selfAliases(context.filename || context.getFilename())
+    if (!self) return {}
+
+    const check = (node, specifier) => {
+      if (typeof specifier !== "string" || !specifier.startsWith(self.prefix)) return
+      const rest = specifier.slice(self.prefix.length)
+      const hit = self.keys.some((key) => rest === key || rest.startsWith(`${key}/`))
+      if (hit) context.report({ node, messageId: "self", data: { specifier } })
+    }
+    return {
+      ImportDeclaration(node) {
+        check(node.source, node.source.value)
+      },
+      ExportNamedDeclaration(node) {
+        if (node.source) check(node.source, node.source.value)
+      },
+      ExportAllDeclaration(node) {
+        if (node.source) check(node.source, node.source.value)
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "must-deep-module-import": mustDeepModuleImport,
+  "no-self-module-alias": noSelfModuleAlias,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * Both measured at zero debt in the reference repository. A repository adopting them into an
+ * existing tree will not be at zero: barrels are the default in most codebases, so measure first
+ * and land above zero at `warn` with the count, exactly as the burn-down procedure says.
+ */
+export const recommended = {
+  "starci-be/must-deep-module-import": "error",
+  "starci-be/no-self-module-alias": "error",
+}

package/naming.mjs

@@ -0,0 +1,143 @@
+/**
+ * The rules that hold `naming.md`.
+ *
+ * Two rules, which are the only two parts of naming a parser can actually judge: whether a name
+ * encodes a schema VERSION, and whether an exported function is a bare verb.
+ *
+ * A THIRD RULE WAS WRITTEN AND DELETED, and the deletion is the useful part. It demanded that a
+ * file name spell out the class it declares, and measured 616 offenders in 4430 files -- because
+ * the convention is the opposite of what it assumed: the PATH carries the role and the scope
+ * (`parsers/content.service.ts` and `path/content.service.ts` declare `ContentParserService` and
+ * `ContentPathService`), and the file names only the subject. Fourteen percent of a tree is a
+ * convention, not debt. Canon records what the code does; a rule that disagrees with the code at
+ * that scale is the rule being wrong.
+ *
+ * The rest of the law is not enforced and should not be faked. Whether a name describes a folder
+ * (NAME-3), a mechanism (NAME-4) or its first caller (NAME-7) needs to know what the thing IS --
+ * `VolumeService` reads perfectly well until you know the folder was renamed, and no parser knows
+ * that. Those are read by a person, which is why the law states them with the scars attached.
+ */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** A schema generation baked into an identifier. */
+const VERSIONED_NAME = /(?:^|[a-z])V[0-9]+(?:$|[A-Z_])|_V[0-9]+/
+
+/** Bare verbs that say nothing about their object. */
+const BARE_VERBS = new Set([
+  "generate",
+  "parse",
+  "run",
+  "handle",
+  "process",
+  "build",
+  "create",
+  "load",
+  "resolve",
+  "check",
+  "convert",
+  "transform",
+  "send",
+  "fetch",
+  "get",
+  "set",
+  "update",
+  "apply",
+])
+
+// -- NAME-2 ----------------------------------------------------------------------------------------
+
+/** A name says what a thing is, never which schema generation it was built for. */
+export const noVersionInName = {
+  meta: {
+    type: "problem",
+    docs: { description: "Identifiers do not encode a schema version." },
+    schema: [],
+    messages: {
+      versioned:
+        "`{{name}}` bakes a schema generation into the name. It has to be renamed the day the next one arrives, and until then nobody can tell from the name whether it means the CURRENT shape or an old one -- so every reader goes and finds out. Name the property that generation introduced instead: `hasVerifiedMarker`, not `isV2`.",
+    },
+  },
+  create(context) {
+    const report = (node, name) => {
+      if (!name || !VERSIONED_NAME.test(name)) return
+      context.report({ node, messageId: "versioned", data: { name } })
+    }
+    return {
+      FunctionDeclaration(node) {
+        if (node.id) report(node.id, node.id.name)
+      },
+      ClassDeclaration(node) {
+        if (node.id) report(node.id, node.id.name)
+      },
+      TSInterfaceDeclaration(node) {
+        if (node.id) report(node.id, node.id.name)
+      },
+      TSTypeAliasDeclaration(node) {
+        if (node.id) report(node.id, node.id.name)
+      },
+      MethodDefinition(node) {
+        if (node.key && node.key.type === "Identifier") report(node.key, node.key.name)
+      },
+    }
+  },
+}
+
+// -- NAME-5 ----------------------------------------------------------------------------------------
+
+/** An exported function is a verb plus its object. */
+export const noBareVerbExport = {
+  meta: {
+    type: "problem",
+    docs: { description: "An exported function names its object, not just its verb." },
+    schema: [],
+    messages: {
+      bareVerb:
+        "`{{name}}` is a bare verb: {{name}} WHAT? At an import list it collides with every other module's `{{name}}`, so the reader falls back on reading the path to tell them apart -- and the path is the thing that moves. Give it its object.",
+    },
+  },
+  create(context) {
+    const check = (node, name) => {
+      if (!name || !BARE_VERBS.has(name)) return
+      context.report({ node, messageId: "bareVerb", data: { name } })
+    }
+    return {
+      ExportNamedDeclaration(node) {
+        const declaration = node.declaration
+        if (!declaration) return
+        if (declaration.type === "FunctionDeclaration" && declaration.id) {
+          check(declaration.id, declaration.id.name)
+          return
+        }
+        if (declaration.type !== "VariableDeclaration") return
+        for (const one of declaration.declarations) {
+          const init = one.init
+          const isFunction = init
+            && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")
+          if (isFunction && one.id && one.id.type === "Identifier") check(one.id, one.id.name)
+        }
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-version-in-name": noVersionInName,
+  "no-bare-verb-export": noBareVerbExport,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * MEASURE THESE BEFORE SWITCHING THEM ON. Unlike the other backend laws, naming rules land on a
+ * mature tree with real debt: a repository that has been running for a while will have file names
+ * that drifted from their exports and methods carrying a schema generation. Land above zero at
+ * `warn` with the count and burn it down -- a naming rule at `error` on day one blocks every commit
+ * that touches an old file, which teaches people to disable it.
+ */
+export const recommended = {
+  "starci-be/no-version-in-name": "warn",
+  "starci-be/no-bare-verb-export": "warn",
+}