@avi2dg/checks 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.27.0
+
+Released 2026-09-27.
+
+### Breaking changes
+
+- **quality:** add data-shape oxlint plugin for readonly params and schema twins [#96](https://github.com/avi2d/checks/pull/96)
+- ship stricter type gates for any, optional keys, process.env and ts-reset [#94](https://github.com/avi2d/checks/pull/94)
+
+### Features
+
+- **docs:** check agent files, vanished names and reports about the past [#95](https://github.com/avi2d/checks/pull/95)
+
+### Fixes
+
+- describe the kit without naming its owner in the package description [#91](https://github.com/avi2d/checks/pull/91)
+
 ## 0.26.0
 
 Released 2026-09-27.

package/README.md

@@ -10,7 +10,6 @@ Each repository owns its workflows and native tool configs, as [Native settings]
 
 - A git repository, whose history the range gates read.
 - Bun 1.3.13, which runs every bin.
-- TypeScript 7.0.2, whose `tsc` the `typecheck` script runs.
 - The peer dependencies, at the exact versions the kit pins:
   - `@effect/tsgo` 0.45.0
   - `@swc/core` 1.16.2
@@ -19,6 +18,7 @@ Each repository owns its workflows and native tool configs, as [Native settings]
   - `jscpd` 5.3.2
   - `oxlint` 1.83.0
   - `oxlint-tsgolint` 7.0.2002
+  - `typescript` 7.0.2
 
 <!-- end generated prerequisites -->
 
@@ -108,9 +108,9 @@ Add a pull request title lint step in another workflow using `./node_modules/.bi
 
 ## What runs
 
-`checks-lint` runs these gates, each over the working tree or over the range it resolves, and names every one that fails.
-`checks-lint` runs every applicable gate, including the TypeScript gates once the repository tracks TypeScript.
-Each gate belongs to the vector it judges a repository on, and the table groups the gates by vector.
+`checks-lint` runs each of these gates that applies to the repository, and names every one that fails.
+A gate reads either the working tree or the range `checks-lint` resolves.
+The table groups the gates by vector, the part of a repository each one judges.
 
 <!-- generated gates: bun run build writes it from KIT_GATES in src/core/gates.ts and scripts/doc-blocks.ts -->
 
@@ -155,7 +155,6 @@ To move a repository to a newer release of the kit:
 
 The repository's lockfile pins the kit, so a repository moves only when it runs these steps.
 [CHANGELOG.md](CHANGELOG.md), shipped in the package, lists what each release changed.
-A repository that tracks `quality.json` moves its settings as [Native settings](docs/configs/native-settings.md#consumer-migration) maps.
 
 ## Where things are
 
@@ -175,7 +174,8 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | `dist/` | the compiled oxlint plugins and the doc templates, one template per kind of doc file |
 | `oxlintrc.json` | the oxlint base config `.oxlintrc.json` extends |
 | `stryker.preset.js` | the Stryker mutation-testing preset |
-| `tsconfig.effect.json` | the tsconfig fragment with the Effect language-service block |
+| `tsconfig.effect.json` | the tsconfig fragment with the shared compiler options and the Effect language-service block |
+| `ts-reset.d.ts` | the two ts-reset rules `tsconfig.effect.json` lists in `files` |
 
 <!-- end generated shipped -->
 

package/dist/data-shape/index.js

@@ -0,0 +1,428 @@
+// src/quality/data-shape/readonly-collection-param.ts
+var ARRAY_METHODS = new Set([
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+  "sort",
+  "reverse",
+  "fill",
+  "copyWithin"
+]);
+var COLLECTION_METHODS = new Set(["set", "delete", "clear", "add"]);
+var HANDOFF_PARENTS = new Set([
+  "ArrayExpression",
+  "ReturnStatement",
+  "YieldExpression",
+  "JSXExpressionContainer",
+  "JSXSpreadAttribute"
+]);
+var READONLY_NAMES = new Set(["ReadonlyArray", "ReadonlyMap", "ReadonlySet"]);
+function isArrayType(type) {
+  if (type === undefined)
+    return false;
+  if (type.type === "TSArrayType")
+    return true;
+  return type.type === "TSTypeReference" && type.typeName.type === "Identifier" && type.typeName.name === "Array";
+}
+function isMapOrSet(type) {
+  return type?.type === "TSTypeReference" && type.typeName.type === "Identifier" && (type.typeName.name === "Map" || type.typeName.name === "Set");
+}
+function namedOf(param) {
+  if (param.type === "Identifier")
+    return { name: param.name, type: param.typeAnnotation?.typeAnnotation };
+  if (param.type === "AssignmentPattern" && param.left.type === "Identifier") {
+    return { name: param.left.name, type: param.left.typeAnnotation?.typeAnnotation };
+  }
+  return;
+}
+function isReadonlyType(type) {
+  if (type?.type === "TSTypeOperator")
+    return type.operator === "readonly";
+  return type?.type === "TSTypeReference" && type.typeName.type === "Identifier" && READONLY_NAMES.has(type.typeName.name);
+}
+function declaredFunctions(program) {
+  const found = new Map;
+  for (const statement of program.body) {
+    const declaration = statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration" ? statement.declaration : statement;
+    if (declaration?.type === "FunctionDeclaration" && declaration.id !== null) {
+      found.set(declaration.id.name, declaration.params);
+    }
+  }
+  return found;
+}
+function isPassThrough(parent, child) {
+  if (parent === null)
+    return false;
+  if (parent.type === "ConditionalExpression")
+    return parent.test !== child;
+  return parent.type === "LogicalExpression" || parent.type === "AwaitExpression" || parent.type === "TSAsExpression" || parent.type === "TSTypeAssertion" || parent.type === "TSSatisfiesExpression" || parent.type === "TSNonNullExpression";
+}
+function valuePosition(node) {
+  let current = node;
+  while (isPassThrough(current.parent, current))
+    current = current.parent;
+  return current;
+}
+function writtenObjects(target) {
+  if (target === null)
+    return [];
+  if (target.type === "MemberExpression")
+    return target.object.type === "Identifier" ? [target.object.name] : [];
+  if (target.type === "ArrayPattern")
+    return target.elements.flatMap((element) => writtenObjects(element));
+  if (target.type === "ObjectPattern") {
+    return target.properties.flatMap((one) => writtenObjects(one.type === "Property" ? one.value : one));
+  }
+  if (target.type === "AssignmentPattern")
+    return writtenObjects(target.left);
+  if (target.type === "RestElement")
+    return writtenObjects(target.argument);
+  return [];
+}
+function calledMethod(callee) {
+  const { property } = callee;
+  if (!callee.computed && property.type === "Identifier")
+    return property.name;
+  if (property.type === "Literal" && typeof property.value === "string")
+    return property.value;
+  return;
+}
+function watch(params) {
+  const found = [];
+  for (const param of params) {
+    const named = namedOf(param);
+    if (named === undefined || named.type === undefined)
+      continue;
+    if (isArrayType(named.type))
+      found.push({ name: named.name, type: named.type, methods: ARRAY_METHODS });
+    else if (isMapOrSet(named.type))
+      found.push({ name: named.name, type: named.type, methods: COLLECTION_METHODS });
+  }
+  return found;
+}
+function fixOf(type, text) {
+  return type.type === "TSArrayType" ? `readonly ${text}` : `Readonly${text}`;
+}
+var rule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Type a collection parameter the function never mutates as readonly" }
+  },
+  create(context) {
+    const stack = [];
+    let functions = new Map;
+    const mark = (name, method) => {
+      for (let index = stack.length - 1;index >= 0; index--) {
+        const frame = stack[index];
+        if (frame === undefined)
+          continue;
+        const param = frame.watched.find((one) => one.name === name);
+        if (param === undefined)
+          continue;
+        if (method === undefined || param.methods.has(method))
+          frame.mutated.add(name);
+        return;
+      }
+    };
+    const enter = (node) => {
+      stack.push({ watched: watch(node.body === null ? [] : node.params), mutated: new Set });
+    };
+    const leave = () => {
+      const frame = stack.pop();
+      if (frame === undefined)
+        return;
+      for (const param of frame.watched) {
+        if (frame.mutated.has(param.name))
+          continue;
+        const text = context.sourceCode.getText(param.type);
+        context.report({
+          node: param.type,
+          message: `parameter \`${param.name}\` is typed \`${text}\` but this function never mutates it. Type it \`${fixOf(param.type, text)}\` instead.`
+        });
+      }
+    };
+    const call = (node) => {
+      const { callee } = node;
+      if (callee.type !== "MemberExpression")
+        return;
+      const { object } = callee;
+      if (object.type !== "Identifier")
+        return;
+      mark(object.name, calledMethod(callee));
+    };
+    const passedReadonly = (site, argument) => {
+      if (site.callee.type !== "Identifier")
+        return false;
+      const params = functions.get(site.callee.name);
+      const index = site.arguments.findIndex((one) => one === argument);
+      const param = params?.[index];
+      return param !== undefined && isReadonlyType(namedOf(param)?.type);
+    };
+    const escapes = (node) => {
+      const value = valuePosition(node);
+      const { parent } = value;
+      if (parent === null)
+        return false;
+      if (parent.type === "CallExpression" || parent.type === "NewExpression") {
+        return parent.callee !== value && !passedReadonly(parent, value);
+      }
+      if (parent.type === "VariableDeclarator")
+        return parent.init === value;
+      if (parent.type === "AssignmentExpression" || parent.type === "AssignmentPattern")
+        return parent.right === value;
+      if (parent.type === "Property" || parent.type === "PropertyDefinition")
+        return parent.value === value;
+      if (parent.type === "ArrowFunctionExpression")
+        return parent.body === value;
+      return HANDOFF_PARENTS.has(parent.type);
+    };
+    const written = (target) => {
+      for (const name of writtenObjects(target))
+        mark(name, undefined);
+    };
+    return {
+      Program: (node) => {
+        functions = declaredFunctions(node);
+      },
+      Identifier: (node) => {
+        if (escapes(node))
+          mark(node.name, undefined);
+      },
+      FunctionDeclaration: enter,
+      FunctionExpression: enter,
+      ArrowFunctionExpression: enter,
+      "FunctionDeclaration:exit": leave,
+      "FunctionExpression:exit": leave,
+      "ArrowFunctionExpression:exit": leave,
+      CallExpression: call,
+      AssignmentExpression: (node) => {
+        written(node.left);
+      },
+      UpdateExpression: (node) => {
+        written(node.argument);
+      },
+      UnaryExpression: (node) => {
+        if (node.operator === "delete" && node.argument.type === "MemberExpression")
+          written(node.argument);
+      },
+      ForOfStatement: (node) => {
+        written(node.left);
+      },
+      ForInStatement: (node) => {
+        written(node.left);
+      }
+    };
+  }
+};
+var readonly_collection_param_default = rule;
+
+// src/quality/data-shape/schema-twin.ts
+var STRUCTS = new Set(["Struct", "TaggedStruct", "Class"]);
+var REFINEMENTS = new Set(["check", "annotate"]);
+var SCHEMA_KINDS = {
+  String: "string",
+  NonEmptyString: "string",
+  Trimmed: "string",
+  Literal: "literal",
+  Literals: "literal",
+  Number: "number",
+  Finite: "number",
+  Int: "number",
+  NonNegativeInt: "number",
+  Boolean: "boolean",
+  Array: "array",
+  NonEmptyArray: "array",
+  Struct: "object",
+  TaggedStruct: "object",
+  Record: "record",
+  Unknown: "unknown"
+};
+function keyName(key) {
+  if (key.type === "Identifier")
+    return key.name;
+  if (key.type === "Literal" && typeof key.value === "string")
+    return key.value;
+  return;
+}
+function typeKind(type) {
+  const value = type?.type === "TSTypeOperator" ? type.typeAnnotation : type;
+  if (value === undefined)
+    return "wild";
+  if (value.type === "TSStringKeyword")
+    return "string";
+  if (value.type === "TSNumberKeyword")
+    return "number";
+  if (value.type === "TSBooleanKeyword")
+    return "boolean";
+  if (value.type === "TSArrayType")
+    return "array";
+  if (value.type === "TSTypeLiteral")
+    return "object";
+  if (value.type === "TSLiteralType")
+    return "literal";
+  if (value.type === "TSUnknownKeyword")
+    return "unknown";
+  if (value.type === "TSTypeReference")
+    return referenceKind(value);
+  if (value.type === "TSUnionType" && value.types.every((one) => one.type === "TSLiteralType"))
+    return "literal";
+  return "wild";
+}
+function referenceKind(value) {
+  if (value.typeName.type !== "Identifier")
+    return "wild";
+  if (value.typeName.name === "Array" || value.typeName.name === "ReadonlyArray")
+    return "array";
+  if (value.typeName.name === "Record" || value.typeName.name === "ReadonlyRecord")
+    return "record";
+  return "wild";
+}
+function schemaCallName(node) {
+  if (node === undefined)
+    return;
+  if (node.type === "CallExpression")
+    return schemaCallName(node.callee);
+  if (node.type !== "MemberExpression")
+    return;
+  const { object, property } = node;
+  if (object.type !== "Identifier" || object.name !== "Schema" || property.type !== "Identifier")
+    return;
+  return property.name;
+}
+function kindOf(name) {
+  return name === undefined ? "wild" : SCHEMA_KINDS[name] ?? "wild";
+}
+function refinedBase(value) {
+  const { callee } = value;
+  if (callee.type !== "MemberExpression" || callee.object.type === "Super")
+    return;
+  if (callee.property.type !== "Identifier" || !REFINEMENTS.has(callee.property.name))
+    return;
+  return callee.object;
+}
+function schemaKind(value) {
+  if (value !== undefined && value.type === "CallExpression") {
+    const name = schemaCallName(value.callee);
+    if (name === "optionalKey" || name === "optional") {
+      const first = value.arguments[0];
+      const inner = first === undefined || first.type === "SpreadElement" ? undefined : first;
+      return { optional: true, kind: schemaKind(inner).kind };
+    }
+    const base = refinedBase(value);
+    if (base !== undefined)
+      return schemaKind(base);
+    return { optional: false, kind: kindOf(name) };
+  }
+  return { optional: false, kind: kindOf(schemaCallName(value)) };
+}
+function shapeFields(node) {
+  const members = node.type === "TSTypeLiteral" ? node.members : node.body;
+  const found = [];
+  for (const member of members) {
+    if (member.type !== "TSPropertySignature")
+      continue;
+    const name = keyName(member.key);
+    if (name === undefined)
+      continue;
+    found.push({ name, optional: member.optional, kind: typeKind(member.typeAnnotation?.typeAnnotation) });
+  }
+  return found;
+}
+function schemaFields(call) {
+  const { callee } = call;
+  const inner = callee.type === "CallExpression" ? callee.callee : callee;
+  if (inner.type !== "MemberExpression")
+    return;
+  const { object, property } = inner;
+  if (object.type !== "Identifier" || object.name !== "Schema" || property.type !== "Identifier" || !STRUCTS.has(property.name)) {
+    return;
+  }
+  const fields = call.arguments.find((one) => one.type === "ObjectExpression");
+  if (fields === undefined)
+    return;
+  const found = property.name === "TaggedStruct" ? [{ name: "_tag", optional: false, kind: "literal" }] : [];
+  for (const prop of fields.properties) {
+    if (prop.type !== "Property" || prop.computed)
+      continue;
+    const name = keyName(prop.key);
+    if (name === undefined)
+      continue;
+    const { optional, kind } = schemaKind(prop.value);
+    found.push({ name, optional, kind });
+  }
+  return found.length >= 2 ? found : undefined;
+}
+function twins(typeFields, schema) {
+  return typeFields.length === schema.length && typeFields.every((field) => {
+    const match = schema.find((one) => one.name === field.name);
+    return match !== undefined && match.optional === field.optional && field.kind === match.kind;
+  });
+}
+function schemaName(call) {
+  const { parent } = call;
+  if (parent.type !== "VariableDeclarator" || parent.id.type !== "Identifier")
+    return;
+  return parent.id.name;
+}
+function shapeName(node) {
+  const { parent } = node;
+  if (parent.type !== "TSTypeAliasDeclaration" && parent.type !== "TSInterfaceDeclaration")
+    return;
+  return parent.id.name;
+}
+function describeTwin(type, schema) {
+  const subject = type === undefined ? "This object type" : `Type \`${type}\``;
+  if (schema === undefined)
+    return `${subject} repeats the fields of a Schema in this file. Derive it from the schema instead of writing both.`;
+  return `${subject} repeats the fields of schema \`${schema}\` in this file. Derive it as \`typeof ${schema}.Type\` instead of writing both.`;
+}
+var rule2 = {
+  meta: {
+    type: "problem",
+    docs: { description: "Derive an object type from the Schema it repeats instead of writing both" }
+  },
+  create(context) {
+    const shapes = [];
+    const schemas = [];
+    const collect = (node) => {
+      if (node.parent.type === "TSInterfaceDeclaration" && node.parent.extends.length > 0)
+        return;
+      const fields = shapeFields(node);
+      if (fields.length >= 2)
+        shapes.push({ node, fields });
+    };
+    return {
+      TSTypeLiteral: collect,
+      TSInterfaceBody: collect,
+      CallExpression(node) {
+        const fields = schemaFields(node);
+        if (fields !== undefined)
+          schemas.push({ name: schemaName(node), fields });
+      },
+      "Program:exit"() {
+        for (const shape of shapes) {
+          const twin = schemas.find((schema) => twins(shape.fields, schema.fields));
+          if (twin === undefined)
+            continue;
+          context.report({ node: shape.node, message: describeTwin(shapeName(shape.node), twin.name) });
+        }
+      }
+    };
+  }
+};
+var schema_twin_default = rule2;
+
+// src/quality/data-shape/index.ts
+var plugin = {
+  meta: { name: "data-shape" },
+  rules: {
+    "readonly-collection-param": readonly_collection_param_default,
+    "schema-twin": schema_twin_default
+  }
+};
+var data_shape_default = plugin;
+export {
+  data_shape_default as default
+};

package/dist/templates/reference.md

@@ -1,6 +1,6 @@
 # <The thing this page describes, as a noun>
 
-<What the thing is, in one sentence, and when a reader looks it up.>
+<What the thing is, in one sentence.>
 
 ## <One part of it, as a noun>
 

package/docs/configs/commit-messages.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # The commit message lint
 
-The shared commitlint config holds each pull request title to conventional commits, and a reader looks it up to wire the lint into a repository's CI.
+The shared commitlint config holds each pull request title to the conventional commit format.
 
 ## Config
 

package/docs/configs/dependency-rules.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # The dependency rules
 
-The shared dependency-cruiser base holds a repository's imports to a set of rules every repository shares, and a reader looks it up to add a boundary of its own.
+The shared dependency-cruiser base holds a repository's imports to a set of rules, and a repository adds its own boundaries on top.
 
 ## Base rules
 
@@ -19,6 +19,12 @@ The shared dependency-cruiser base holds a repository's imports to a set of rule
 
 The base parses with swc, so it needs `@swc/core` installed, and without it the cruise silently skips every `.ts` file.
 
+`no-deep-imports` judges the import specifier, never the file it resolves to.
+The base honours `exports` maps, so a subpath the map publishes resolves and passes, and a subpath it omits fails to resolve and is reported.
+A package without an `exports` map publishes every file.
+A bare import always passes, whatever file its entry lives in.
+A repository that sets its own `options.enhancedResolveOptions` replaces the base's, and restates `exportsFields` and `conditionNames` in it.
+
 ## Boundaries
 
 A repository appends a named rule per boundary it owns:

package/docs/configs/effect-rules.md

@@ -40,6 +40,16 @@ Each config in an oxlint `extends` chain sets `plugins` explicitly, because an o
 The repository's `tsconfig.json` holds its Effect override under `compilerOptions.plugins`.
 The override includes the same source paths and excludes the same exempt paths as oxlint.
 The kit ships severity values in `src/quality/presets/effect.language-service.json` for the override's `options`.
+The preset turns these diagnostics to errors:
+
+- `nodeBuiltinImport` refuses an import of a Node built-in module that has an Effect counterpart.
+- `asyncFunction` refuses an `async` function.
+- `newPromise` refuses `new Promise`.
+- `extendsNativeError` refuses a class that extends the native `Error` directly.
+- `processEnv` refuses a read of `process.env` outside an Effect generator.
+- `processEnvInEffect` refuses a read of `process.env` inside an Effect generator.
+
+Effect's `Config` reads the environment in place of `process.env`.
 The kit's `tsconfig.effect.json` keeps the shared language service diagnostics.
 
 ## Related topics

package/docs/configs/native-settings.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # Native settings
 
-A consuming repository puts each setting in the file its tool reads.
+A consuming repository puts each setting in the file its tool reads, and no manifest of the kit gathers them.
 
 ## Settings by file
 
@@ -24,37 +24,14 @@ A consuming repository puts each setting in the file its tool reads.
 | Each page under `docs/` | Diátaxis mode in `kind` front matter, and `audience: consumers` on a page that speaks to a consuming repository | `checks-docs` |
 
 Every page under `docs/` names its mode in `kind` front matter, whatever directory holds it.
-A page whose front matter sets `audience: consumers` names commands a consuming repository runs, so `checks-docs` does not hold them to this `package.json`.
-Every other living doc names commands this repository runs, and `checks-docs` holds each one to its `package.json`.
-
-## Consumer migration
-
-The following table maps the former fields to their owners.
-
-| Former field | New owner |
-| --- | --- |
-| `defaultBranch` | Git's `refs/remotes/origin/HEAD`, or the pull request base or event repository in CI |
-| `runsOn`, `gates.ci`, `gates.scheduled` | `runs-on` and `run` steps in `.github/workflows/*.yml` |
-| `gates.lint` | `checks-lint` runs every kit gate |
-| `commitIdentity.authors` | `author` and `contributors` in `package.json` |
-| `sources.production` | `path` and `ignore` in `.jscpd.json` |
-| `size.production`, `size.tests` | File overrides and native size rules in `.oxlintrc.json` |
-| `sources.effect.paths`, `sources.effect.exempt` | Overrides in `.oxlintrc.json` and `tsconfig.json` |
-| `sources.libraries` | `checks-vendor` arguments in the `prepare` script of `package.json` |
-| `docs.pages` | `kind` front matter on each page |
-| `docs.forConsumers` | `audience: consumers` front matter on each page |
-| `features`, `changeSignal`, `agentRules` | No active declarations used these fields |
-
-The kit has no general configuration manifest or generated workflow.
-`checks-ci-wiring` requires title lint on opened and synchronized pull requests.
-It also requires lint, build, typecheck and test for each of those scripts that `package.json` defines, and a clean git diff after a build.
-`checks-repetition` runs jscpd with the repository's own `.jscpd.json`, so its `path` and `ignore` globs decide which files are measured.
+A page whose front matter sets `audience: consumers` names commands that a consuming repository runs.
+`checks-docs` skips the `bun run` commands on such a page, and resolves those in every other living doc or agent file as [Paths, links and commands](../gates/checks-docs.md#paths-links-and-commands) says.
 
 ## Size limits
 
-The size rules are plain oxlint rules at `error` in `.oxlintrc.json`, and `bun run lint` enforces them on the whole tree.
+The size rules are oxlint's own rules at `error` in `.oxlintrc.json`, so `bun run lint` fails on any file over them.
 A repository records its existing violations with `oxlint --suppress-all`, which writes them to `oxlint-suppressions.json`.
-`checks-suppressions-ratchet` refuses any count in that file that rises, so the recorded debt only falls.
+`checks-suppressions-ratchet` refuses any count in that file that rises.
 The kit's own `.oxlintrc.json` sets these limits for each size override, and a repository may copy them:
 
 <!-- generated size-limits: bun run build writes it from .oxlintrc.json, SIZE_RULES in src/complexity/size-rules.ts and scripts/doc-blocks.ts -->
@@ -72,5 +49,6 @@ The kit's own `.oxlintrc.json` sets these limits for each size override, and a r
 ## Related topics
 
 - [The Effect rules](effect-rules.md)
-- [The CI wiring check](../gates/checks-ci-wiring.md)
-- [The suppressions ratchet](../gates/checks-suppressions-ratchet.md)
+- [checks-ci-wiring](../gates/checks-ci-wiring.md)
+- [checks-suppressions-ratchet](../gates/checks-suppressions-ratchet.md)
+- [checks-docs](../gates/checks-docs.md)

package/docs/configs/typescript-rules.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # The TypeScript rules
 
-The oxlint base config holds a repository's TypeScript to a set of rules, and a reader looks it up to learn what each rule refuses and which rules need type information.
+The oxlint base config and the tsconfig fragment hold a repository's TypeScript to a set of rules, and some of them need type information.
 
 ## Syntax rules
 
@@ -33,6 +33,48 @@ Without the flag, oxlint skips them and reports nothing about them.
 - `typescript/no-unsafe-type-assertion` refuses an `as` that narrows a value to a type the compiler cannot prove.
 - `typescript/no-deprecated` refuses a use of a symbol whose declaration carries a `@deprecated` tag, in the repository's own code or in a package's types, and repeats the tag's text.
 
+## Data-shape rules
+
+The base loads the kit's `data-shape` plugin from `dist/` with one rule for every TypeScript file and one for production files.
+
+- `data-shape/readonly-collection-param` refuses a parameter typed `T[]`, `Array<T>`, `Map` or `Set` that the function never mutates, stores, returns or passes on, and passing it to a readonly parameter of a function declared in the same file does not count as passing it on.
+- Type such a parameter `readonly T[]`, `ReadonlyArray<T>`, `ReadonlyMap` or `ReadonlySet`.
+- `data-shape/schema-twin` refuses an object type whose fields match a `Schema.Struct`, `TaggedStruct` or `Class` in the same file by name, count, optionality and kind.
+- Derive such a type from the schema with `typeof Name.Type` instead of writing both.
+- The twin rule runs on production files only, so a test that declares its own schema as an oracle stays green.
+
+## Rules outside tests
+
+An override in `oxlintrc.json` turns on these type-aware rules in each `.ts` and `.tsx` file outside `tests/`:
+
+- `typescript/no-unsafe-assignment` refuses assigning an `any` value to a variable, a property or a destructured name.
+- `typescript/no-unsafe-member-access` refuses reading a member of an `any` value.
+- `typescript/no-unsafe-argument` refuses passing an `any` value to a parameter of another type.
+- `typescript/no-unsafe-return` refuses returning an `any` value from a function, unless the function returns `unknown`.
+- `typescript/no-unsafe-call` refuses calling an `any` value.
+
+A consumer inherits the override through `extends`, and a file under `tests/` answers to none of the five.
+
+## Compiler options
+
+`tsconfig.effect.json` sets these compiler options in each repository whose `tsconfig.json` extends it:
+
+- `erasableSyntaxOnly` refuses TypeScript syntax that does not erase to JavaScript, such as an `enum` or a parameter property.
+- `exactOptionalPropertyTypes` refuses `undefined` as the value of an optional property whose type does not name `undefined`, so a type derived from a `Schema.optionalKey` field accepts only a missing key, as the schema does.
+
+## ts-reset rules
+
+`tsconfig.effect.json` lists the kit's `ts-reset.d.ts` in `files`, and that file loads two rules of `@total-typescript/ts-reset`, a dependency of the kit:
+
+- `is-array` types the array `Array.isArray` narrows a value to as `unknown[]` rather than `any[]`.
+- `json-parse` types the value `JSON.parse` returns as `unknown` rather than `any`.
+
+tsc then refuses code that uses either value as a type it has not checked.
+The fragment also sets `include` to every file under the directory of the repository's `tsconfig.json` and to `ts-reset.d.ts`.
+A repository whose `tsconfig.json` sets `include` or `files` but not both keeps both rules.
+A repository that sets only `files` also gets every file under that directory in its program.
+A repository that sets both `files` and `include` drops both rules, and `checks-lint-coverage` fails it.
+
 ## Related topics
 
 - [The Effect rules](effect-rules.md)