@alint-js/plugin-simplicity 0.0.22

package/README.md

@@ -0,0 +1,301 @@
+# `@alint-js/plugin-simplicity`
+
+Tell your code to **DRY — Don't Repeat Yourself**.  
+Finds small helper functions that are defined twice, or that should not exist at all.
+
+Both rules work on **helpers**: anything with a name and a body. A function declaration,
+a method, and, in TypeScript, TSX and JavaScript, an arrow function or function
+expression bound to a name (`const parse = (text: string) => JSON.parse(text)`). That
+last shape is how most tiny helpers are actually written, so leaving it out would hide
+exactly the code these rules look for.
+
+Languages: TypeScript, TSX, JavaScript, Rust, Go and Python.
+
+## How it works
+
+One index of the whole workspace, built once per run and shared by both rules. Everything
+a hash can settle is settled by code. Only what is left reaches a model.
+
+```mermaid
+flowchart TB
+  subgraph idx ["Repo index — Once per run, no token cost"]
+    direction TB
+    files["Every parseable file in the workspace"]
+    files --> parse["Parse and query by tree-sitter"]
+    parse --> keep{"Small helper?<br/>within maxLines, at least minTokens"}
+    keep -->|no| skip["Not indexed"]
+    keep -->|yes| helpers["Indexed with its facts:<br/>exact fingerprint, alpha fingerprint,<br/>usage count, whether exported"]
+  end
+
+  helpers --> lint["Files to lint"]
+  lint --> dup
+  lint --> needless
+
+  subgraph dup ["no-duplicated-helper"]
+    direction TB
+    d1{"Identical body<br/>somewhere else?"}
+    d1 -->|yes| dr1["Report: also defined at ..."]
+    d1 -->|no| d2{"Same body, renamed?<br/>alpha-equivalent"}
+    d2 -->|yes| dr2["Report: renamed copy of ..."]
+    d2 -->|no| d3["Agent, holding the index as tools:<br/>search bodies, rank similar, read in full"]
+    d3 --> dr3["Report: duplicates ..., and why"]
+  end
+
+  subgraph needless ["no-needless-helper"]
+    direction TB
+    n1{"Whole body is<br/>one expression?"}
+    n1 -->|no| nx["Never asked about"]
+    n1 -->|yes| n2["One model call per file.<br/>Usage count and exported go in<br/>as facts, not filters"]
+    n2 --> nr["Report: does not earn its existence"]
+  end
+
+  cache[("Cache in .alint/simplicity/<br/>a run that changed nothing costs nothing")]
+  d3 <--> cache
+  n2 <--> cache
+
+  classDef free fill:#e8f5e9,stroke:#43a047,color:#1b5e20
+  classDef paid fill:#fff3e0,stroke:#fb8c00,color:#e65100
+  class files,parse,keep,skip,helpers,d1,d2,dr1,dr2,n1,nx free
+  class d3,dr3,n2,nr paid
+```
+
+Green spends nothing. Orange spends model tokens, and only ever sees the helpers the
+green half could not settle.
+
+### The two fingerprints
+
+Every indexed helper is hashed twice. Both hashes drop comments and collapse whitespace
+first, so reformatting a copy or rewording its documentation changes neither.
+
+**The exact fingerprint** hashes what is left, verbatim. Two helpers that share it are the
+same code, character for character, once layout and comments are set aside.
+
+**The alpha fingerprint** goes one step further: every name the helper *declares* — its own
+name, its parameters, its locals — is replaced by a placeholder, in order of first
+appearance. Everything the helper merely *refers to* stays as written: the functions it
+calls, the types it names, the properties it reads.
+
+That split is the whole design. A copy can rename what it declares; it cannot rename what
+it refers to and still be a copy. So these two match:
+
+```ts
+function hasErrorCode(failure: unknown): failure is NodeJS.ErrnoException {
+  return failure instanceof Error && 'code' in failure
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error
+}
+```
+
+Both normalize to the same thing, so the second is reported as a renamed copy of the first:
+
+```
+function $0($1: unknown): $1 is NodeJS.ErrnoException { return $1 instanceof Error && 'code' in $1 }
+```
+
+`Error` and `NodeJS.ErrnoException` survive, because the helper only refers to them. And
+these two do **not** match:
+
+```ts
+export function readName(entry: Entry): string {
+  return entry.name
+}
+
+export function readSize(entry: Entry): number {
+  return entry.size
+}
+```
+
+`entry` is declared, so it is blinded; `name` and `size` are properties the helpers read,
+so they survive the hash and tell the two apart. A detector that blinded every identifier
+instead — NiCad's blind renaming, PMD's `--ignore-identifiers` — collapses this pair and
+reports two unrelated accessors as copies.
+
+Matching alpha fingerprints mean the helpers are **alpha-equivalent**: identical up to
+renaming. It is an equivalence, not a similarity score, so there is no threshold to tune
+and no false-positive rate to trade off. Everything it cannot decide is the agent's
+question.
+
+## Rules
+
+- **`simplicity/no-duplicated-helper`**: a small helper is defined in two or more places.
+- **`simplicity/no-needless-helper`**: a one-line helper that does not earn its existence.
+
+Rule ids carry the prefix you give the plugin in `plugins`, which is `simplicity/` in
+every example here.
+
+## `no-duplicated-helper`
+
+Two approaches, and the AST one spends nothing.
+
+The **AST approach** hashes. An **identical** helper is reported by code alone, and so is a
+**renamed** one: a copy that changed its own name, its parameters and its locals, but not the
+functions it calls, the types it names or the properties it reads. Those are the names a copy
+cannot change and stay a copy, so they are left in the hash, and they are also what keeps
+`return this.name` and `return this.size` from being mistaken for each other. This is
+alpha-equivalence, and because it is an equivalence rather than a score there is no
+threshold to tune.
+
+Everything a hash cannot settle goes to the **agentic approach**. The agent is not handed a
+shortlist: it gets the index as tools and searches the way a reviewer would, saying what a
+helper does, searching other bodies for that behaviour (`search_helper_bodies` looks for
+`instanceof Error`, not for names), reading the candidates in full, and deciding.
+
+A finding names the twin and the responsibility they share, and stops there:
+
+```
+Helper "isNodeErrorCode" duplicates "isNodeError" at ts/store.ts:16:
+  Both ask whether an error has a specific Node error code.
+```
+
+It does not suggest where the shared copy should live. That decision depends on
+ownership, layering and dependency direction, none of which this rule looks at; see
+`docs/simplicity-architecture.md` for the version that tried and what it produced.
+
+## `no-needless-helper`
+
+A helper earns its existence when its interface is simpler than its implementation, when
+the name tells a reader something the body would not. This rule reports the ones that do
+not: a body of a single expression that says what the name says, so a reader jumps to the
+declaration to learn nothing.
+
+```
+Helper "parse" does not earn its existence: Forwards to JSON.parse unchanged.
+```
+
+**It has no AST approach, and cannot have one.** A hash can prove a duplicate, because two
+identical bodies are a fact. Nothing can prove a helper *should not exist*, because that
+is a judgement about a reader. So the deterministic half finds the helpers worth asking
+about (one expression, no more) and gathers the facts a judgement needs: how often the
+helper is called, and whether it is somebody's public API. Those go to the model as
+**facts, not filters**. A helper called forty times is not disqualified by code; the model
+is told the number and left to weigh it.
+
+What it must *not* report matters as much as what it must:
+
+- **`clamp(value, low, high)`** is short, and earns it. The name is the documentation;
+  `Math.min(Math.max(x, 0), 1)` is not.
+- **`isNodeError(error): error is ErrnoException`** is a one-line type guard. Inlined, the
+  check still runs but the call site loses the type it narrowed to.
+
+That second case is the sharpest in the plugin: `no-duplicated-helper` must report
+`isNodeError`, because it is copied, and `no-needless-helper` must not, because it earns
+its keep. The same three lines, two rules, opposite decisions.
+
+It costs one model call per file rather than an agent loop, because everything the
+judgement needs is already in hand and there is nothing to search for.
+
+## Usage
+
+The rules read whole files and parse them internally, so they take plain-text targets:
+
+```js
+import simplicityPlugin from '@alint-js/plugin-simplicity'
+
+import { createApeiraAdapter } from '@alint-js/agent-apeira'
+import { defineConfig } from '@alint-js/cli'
+
+export default defineConfig([
+  {
+    // `no-duplicated-helper`'s agentic approach needs this. Without it, the AST approach
+    // still runs.
+    agent: createApeiraAdapter(),
+    files: ['**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts,rs,go,py}'],
+    language: 'text/plain',
+    plugins: {
+      simplicity: simplicityPlugin,
+    },
+    rules: {
+      'simplicity/no-duplicated-helper': 'warn',
+      'simplicity/no-needless-helper': 'warn',
+    },
+    settings: {
+      simplicity: {
+        // Test and fixture globs to leave alone.
+        ignores: ['**/*.test.ts'],
+        // False keeps the AST approach and spends no tokens at all.
+        judge: true,
+        // The small-helper threshold, in lines. Note that it *selects* small functions;
+        // every copy-paste detector uses its threshold to exclude them.
+        maxLines: 10,
+        // Content tokens a helper needs before it is worth a word. An empty function is
+        // 3 in any language; the smallest real helper is 6.
+        minTokens: 5,
+      },
+    },
+  },
+])
+```
+
+`simplicityPlugin.configs.recommended` ships the same rules and file globs, if you would
+rather not spell them out.
+
+alint rule entries carry a severity and nothing else, which is why the options live under
+`settings.simplicity` rather than beside the rule.
+
+### Cost
+
+The agentic approach is **on by default and spends model tokens**. Identical and renamed
+copies never reach it, and a file whose helpers were all settled by a hash costs nothing at
+all, because no agent is started for it. `settings.simplicity.judge: false` turns the plugin
+into a deterministic, zero-token duplicate detector for small helpers.
+
+Two things keep the agentic approach affordable.
+
+**A review is cached under a fingerprint of every helper in the workspace**, so a run that
+changed nothing costs nothing. A helper added, edited, moved or deleted anywhere throws
+the whole cache away, because a helper added anywhere could be the twin of a helper here,
+and a decision decided against one workspace means nothing against another. The
+invalidation is coarse on purpose and cheap in practice: the index holds only helpers of
+ten lines or fewer, and most commits do not touch one. Turn it off with
+`settings.simplicity.cache: false`.
+
+The cache is written to `.alint/simplicity/`. Add it to your `.gitignore`: what a model
+decided is not project configuration.
+
+**Only the files you lint are reviewed.** The index always covers the whole workspace, so
+a twin is found wherever it lives, but only the files you pass are handed to an agent.
+That makes the cost proportional to your diff rather than to the repository:
+
+```sh
+alint $(git diff --name-only origin/main...)
+```
+
+Agent tokens are metered and reported, so a run says what it cost.
+
+### Evaluating a change to a prompt
+
+`fixtures/` is a graded corpus: every helper in it is either a finding a run must produce
+or one it must not. The unit tests assert the parts a fingerprint decides, which cost
+nothing. The parts a model decides are measured by a harness that spends real tokens, so
+it is kept outside this repository and CI never runs it. See
+[the architecture notes](./docs/simplicity-architecture.md) for what it measures and why a
+prompt cannot be changed without it.
+
+## When to use
+
+- A codebase where several people, or several agents, open branches in parallel and the
+  same tiny helper keeps being re-invented in each of them. This is the case the plugin
+  was built from: the duplication in #28 and #31 entered through parallel branches and was
+  found by a human afterwards.
+- Reviews where "search for an existing implementation first" is written down as guidance
+  and is not, on its own, working.
+- Codebases that already run a copy-paste detector and want the band it cannot see:
+  helpers below its minimum-token floor.
+
+## When not to use
+
+- **Not a general code-quality plugin.** The scope is function-level simplification smells
+  and nothing more. If a check does not answer "does this helper exist twice" or "should
+  this helper exist at all", it belongs elsewhere.
+- **Not a cross-language dedupe tool.** Helpers are compared within one language only. A
+  Go twin of a TypeScript helper is not shareable code, so reporting it would be advice
+  nobody could take, and the tool that records findings refuses a cross-language pair
+  outright.
+- **Not a replacement for token-based copy-paste detectors.** jscpd, PMD's CPD and their
+  peers cover large duplicated blocks (roughly 50 tokens and up) well, cheaply, and across
+  150+ languages. Keep using them, and run this plugin for the small helpers they are
+  configured to ignore.
+- **Not free, unless you ask it to be.** The judge spends tokens. `judge: false` keeps the
+  AST approach and costs nothing.

package/dist/index.d.mts

@@ -0,0 +1,193 @@
+import { RuleContext, SourceLocation, SourceRange } from "@alint-js/core";
+import { AgentTool } from "@alint-js/core/agent";
+import { InferOutput } from "valibot";
+
+//#region src/extract/types.d.ts
+interface CallSite {
+  /** The last segment only: `a.b.helper()` and `helper()` both yield `helper`. */
+  name: string;
+  range: SourceRange;
+}
+interface ExtractedFunction {
+  /** The names this function declares. Everything else stays verbatim in the alpha fingerprint; see `queries.ts`. */
+  binderNames: string[];
+  /** Stricter than one statement: a body that is one `if` and its two returns is one statement and not one expression. */
+  bodyIsSingleExpression: boolean;
+  bodyStatements: number;
+  /** Relative to `text`, not to the source. */
+  commentRanges: SourceRange[];
+  exported: boolean;
+  /** Relative to `text`. Property, field and type names are not here: replacing them would collapse `entry.name` and `entry.size`. */
+  identifierRanges: SourceRange[];
+  /** Absolute. Lines are 1-based, columns 0-based. */
+  loc: SourceLocation;
+  name: string;
+  /** Absolute offsets into the source. */
+  range: SourceRange;
+  text: string;
+}
+type ExtractLanguage = 'go' | 'javascript' | 'python' | 'rust' | 'tsx' | 'typescript';
+interface SourceExtract {
+  /** Every call in the source, including calls made outside any function. */
+  calls: CallSite[];
+  functions: ExtractedFunction[];
+}
+//#endregion
+//#region src/extract/extract.d.ts
+declare function extractSource(source: string, language: ExtractLanguage): Promise<SourceExtract>;
+//#endregion
+//#region src/extract/language.d.ts
+declare function resolveExtractLanguage(filePath: string): ExtractLanguage | undefined;
+//#endregion
+//#region src/fingerprint/fingerprint.d.ts
+/**
+ * Hashes a function with the names it declares (own name, parameters, locals) replaced by
+ * placeholders. Same alpha fingerprint means the same function, renamed.
+ *
+ * `identifierRanges` must hold renameable identifiers only. Replacing property, field or type
+ * names is the mistake this fingerprint exists to avoid.
+ */
+declare function alphaFingerprint(text: string, commentRanges: readonly SourceRange[], identifierRanges: readonly SourceRange[], binderNames: readonly string[]): string;
+/** Hashes a function with comments and formatting removed, so layout and docs do not count. */
+declare function exactFingerprint(text: string, commentRanges: readonly SourceRange[]): string;
+/** Comments and formatting removed, names left alone, so `search_helper_bodies` can search real code. */
+declare function normalizedBody(text: string, commentRanges: readonly SourceRange[]): string;
+/** Content tokens, alpha-normalized. Punctuation is dropped: every function has braces. */
+declare function tokenize(text: string, commentRanges: readonly SourceRange[], identifierRanges: readonly SourceRange[], binderNames: readonly string[]): string[];
+/** Shared token fraction of the larger bag. Ranks candidates, decides nothing. */
+declare function tokenOverlap(left: readonly string[], right: readonly string[]): number;
+//#endregion
+//#region src/rules/no-duplicated-helper/tools.d.ts
+interface AgentFinding {
+  helperId: string;
+  reason: string;
+  twinId: string;
+}
+interface DuplicateToolsOptions {
+  /** Mutated by `report_duplicate`; the caller reads it once the agent stops. */
+  findings: AgentFinding[];
+  index: RepoIndex;
+  /** Helpers of the file under review: the only ones the agent may report on. */
+  reviewing: readonly IndexedHelper[];
+}
+declare function createDuplicateTools(options: DuplicateToolsOptions): AgentTool[];
+//#endregion
+//#region src/repo/cache.d.ts
+interface ReviewCache {
+  /** A review is returned only to a run whose `fingerprint` matches the one it was decided against. */
+  get: (filePath: string) => AgentFinding[] | undefined;
+  set: (filePath: string, findings: AgentFinding[]) => Promise<void>;
+}
+declare function reviewCacheFor(ctx: RuleContext, options: {
+  cwd: string;
+  enabled: boolean;
+  fingerprint: string;
+}): Promise<ReviewCache>;
+//#endregion
+//#region src/repo/index.d.ts
+interface IndexedHelper {
+  alphaFingerprint: string;
+  /** Comments and formatting removed, names left alone, so `search_helper_bodies` searches real code. */
+  body: string;
+  bodyIsSingleExpression: boolean;
+  /** Statements in the body, not counting comments. */
+  bodyStatements: number;
+  exactFingerprint: string;
+  exported: boolean;
+  filePath: string;
+  /** `packages/cli/src/lint.ts:57`. Unique, and a model can quote it back. */
+  id: string;
+  language: ExtractLanguage;
+  line: number;
+  lines: number;
+  name: string;
+  text: string;
+  tokens: string[];
+  /**
+   * How often a function of this name is called across the workspace.
+   *
+   * Counted by NAME, not by binding, so two `isEmpty` helpers share a count and `x.isEmpty()` counts too.
+   * Only ever handed to the judge as an approximate fact.
+   */
+  usageCount: number;
+}
+interface RepoIndex {
+  byAlpha: Map<string, IndexedHelper[]>;
+  byExact: Map<string, IndexedHelper[]>;
+  byId: Map<string, IndexedHelper>;
+  /** Every helper in the workspace, in one hash. What a cached review is stamped with. */
+  fingerprint: string;
+  helpers: IndexedHelper[];
+}
+interface RepoIndexOptions {
+  cwd: string;
+  ignores: readonly string[];
+  maxLines: number;
+  minTokens: number;
+}
+/** Helpers of one file, in source order. */
+declare function helpersIn(index: RepoIndex, filePath: string): IndexedHelper[];
+declare function repoIndexFor(ctx: RuleContext, options: RepoIndexOptions): Promise<RepoIndex>;
+/** Every other helper sharing a fingerprint. A helper is never its own twin. */
+declare function twinsOf(index: RepoIndex, helper: IndexedHelper, kind: 'alpha' | 'exact'): IndexedHelper[];
+//#endregion
+//#region src/rules/no-duplicated-helper/prompt.d.ts
+declare const duplicatedHelperInstructions: string;
+/**
+ * The nearest helpers are pasted in rather than fetched: measured, the agent spent three of its four steps discovering what to read,
+ * and every step re-sends the system prompt and every tool schema.
+ */
+declare function buildDuplicatedHelperPrompt(options: {
+  candidates: readonly IndexedHelper[];
+  filePath: string;
+  helpers: readonly IndexedHelper[];
+}): string;
+//#endregion
+//#region src/rules/no-duplicated-helper/rule.d.ts
+/**
+ * Reports a small helper already implemented somewhere else in the workspace.
+ *
+ * Identical bodies and renamed-only copies are settled by AST fingerprints, with no model. What
+ * a fingerprint cannot settle goes to an agent holding the whole index as tools.
+ */
+declare const duplicatedHelperRule: import("@alint-js/core").RuleDefinition;
+//#endregion
+//#region src/rules/no-needless-helper/prompt.d.ts
+declare const needlessHelperPrompt: string;
+declare function buildNeedlessHelperPrompt(helpers: readonly IndexedHelper[]): string;
+//#endregion
+//#region src/rules/no-needless-helper/rule.d.ts
+declare const needlessHelperResponseSchema: import("valibot").ObjectSchema<{
+  readonly findings: import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+    readonly helper: import("valibot").SchemaWithPipe<readonly [import("valibot").NumberSchema<undefined>, import("valibot").DescriptionAction<number, "The number shown beside the helper, exactly as given.">]>;
+    readonly name: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "The helper's name, exactly as shown.">]>;
+    readonly reason: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "At most twelve words, naming what the body already says.">]>;
+  }, undefined>, undefined>;
+}, undefined>;
+/**
+ * Reports a helper whose interface is no simpler than its implementation.
+ *
+ * No AST approach is possible: a hash can prove a duplicate, but nothing can prove a helper
+ * should not exist. The deterministic half only finds candidates and gathers facts (usage
+ * count, exported), which are given to the model rather than applied as filters.
+ */
+declare const needlessHelperRule: import("@alint-js/core").RuleDefinition;
+//#endregion
+//#region src/rules/shared/settings.d.ts
+declare const settingsSchema: import("valibot").ObjectSchema<{
+  readonly cache: import("valibot").OptionalSchema<import("valibot").BooleanSchema<undefined>, true>; /** Globs matched against the repository-relative file path. */
+  readonly ignores: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").StringSchema<undefined>, undefined>, readonly []>;
+  /**
+   * When false, no model is called: `no-duplicated-helper` still reports what a fingerprint settles,
+   * `no-needless-helper` reports nothing.
+   */
+  readonly judge: import("valibot").OptionalSchema<import("valibot").BooleanSchema<undefined>, true>;
+  readonly maxLines: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").NumberSchema<undefined>, import("valibot").IntegerAction<number, undefined>, import("valibot").MinValueAction<number, 1, undefined>]>, 10>;
+  readonly minTokens: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").NumberSchema<undefined>, import("valibot").IntegerAction<number, undefined>, import("valibot").MinValueAction<number, 1, undefined>]>, 5>;
+}, undefined>;
+type SimplicitySettings = InferOutput<typeof settingsSchema>;
+//#endregion
+//#region src/index.d.ts
+declare const simplicityPlugin: import("@alint-js/core").PluginDefinition;
+//#endregion
+export { type AgentFinding, type CallSite, type DuplicateToolsOptions, type ExtractLanguage, type ExtractedFunction, type IndexedHelper, type RepoIndex, type RepoIndexOptions, type ReviewCache, type SimplicitySettings, type SourceExtract, alphaFingerprint, buildDuplicatedHelperPrompt, buildNeedlessHelperPrompt, createDuplicateTools, simplicityPlugin as default, simplicityPlugin, duplicatedHelperInstructions, duplicatedHelperRule, exactFingerprint, extractSource, helpersIn, needlessHelperPrompt, needlessHelperResponseSchema, needlessHelperRule, normalizedBody, repoIndexFor, resolveExtractLanguage, reviewCacheFor, tokenOverlap, tokenize, twinsOf };