@drkmttr/adhere 0.9.5 → 0.11.0

package/src/config.ts

@@ -17,6 +17,28 @@ const RuleFields = Schema.Struct({
   should: Schema.optionalKey(Schema.String),
   shouldNot: Schema.optionalKey(Schema.String),
   threshold: Schema.optionalKey(Schema.Finite),
+  /**
+   * Test files, which a rule skips by default: `only` for a rule about tests,
+   * which judges nothing else, and `include` for one that holds in tests too.
+   */
+  tests: Schema.optionalKey(Schema.Literals(["only", "include"])),
+  /**
+   * How a finding under the rule is reported: an `error`, the default, which
+   * fails the run, or a `warning`, for a nit or a rule that errs toward false
+   * findings, which does not.
+   */
+  level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
+  /**
+   * Where the rule applies, each a description of code that breaks it: Jev is
+   * asked of each whether any code that breaks the rule is as it describes,
+   * and a finding stands only when it says yes to every one.
+   */
+  appliesTo: Schema.optionalKey(Schema.Array(Schema.String)),
+  /**
+   * Where the rule does not apply: Jev is asked of each whether all the code
+   * that breaks the rule is as it describes, and a yes to any drops the finding.
+   */
+  excludeIf: Schema.optionalKey(Schema.Array(Schema.String)),
 });
 
 /** Before 0.7, a rule's examples were `reference` and `avoid`: read as `must` and `never`. */
@@ -51,6 +73,9 @@ export const Rule = Schema.Struct({
   );
 export interface Rule extends Schema.Schema.Type<typeof Rule> {}
 
+/** How a finding is reported: an error fails the run, a warning does not. */
+export type Level = NonNullable<Rule["level"]>;
+
 /** One of a rule's examples, under the word it is written with. */
 export interface Example {
   readonly word: "must" | "never" | "should" | "should not";
@@ -79,9 +104,35 @@ export type Rules = Readonly<Record<RuleId, Rule>>;
 /** Rules inline, or a directory of Markdown rule files (see `markdown.ts`). */
 export type RuleSource = Rules | string | URL;
 
+/** A rule's setting in a config's `overrides`: `off`, a level, or a level and a threshold. */
+const Override = Schema.Union([
+  Schema.Literals(["off", "error", "warning"]),
+  Schema.Struct({
+    level: Schema.optionalKey(Schema.Literals(["off", "error", "warning"])),
+    threshold: Schema.optionalKey(Schema.Finite),
+  }),
+]);
+export type Override = typeof Override.Type;
+
 export const AdhereConfig = Schema.Struct({
+  /**
+   * The model id sent to typesafe. Defaults to "jev-latest"
+   */
   model: Schema.optionalKey(Schema.String),
+  /**
+   * The minimum confidence threshold for a positive match. Defaults to 0.8
+   */
   threshold: Schema.optionalKey(Schema.Finite),
+  /**
+   * Below this, Jev's probability that a file shows enough to decide a
+   * finding's rule adds a warning to the finding: check what the code relies
+   * on outside the file. Defaults to 0.6
+   */
+  sufficiencyThreshold: Schema.optionalKey(Schema.Finite),
+  /**
+   * The presets to use for rule matching. Defaults to an empty array. Current presets
+   * include "effect" and "alchemy". Subcategories can be expanded by appending `/<subcategory>`.
+   */
   presets: Schema.Array(Schema.Literals(presetNames)).pipe(
     Schema.withDecodingDefaultKey(Effect.succeed([])),
   ),
@@ -90,6 +141,24 @@ export const AdhereConfig = Schema.Struct({
    * Unset: `.adhere/` when that directory exists, otherwise no rules.
    */
   rules: Schema.optionalKey(Schema.Union([Schema.Record(Schema.String, Rule), Schema.String])),
+  /**
+   * Globs, relative to the working directory, of files no rule judges: what
+   * `--filter '!<glob>'` leaves out of one run, left out of every run.
+   */
+  exclude: Schema.optionalKey(Schema.Array(Schema.String)),
+  /**
+   * Settings for rules by the id a report names them with, a preset's with
+   * its preset first, as in `alchemy/providers/idempotent-delete`: `off`, a
+   * level, or `{ level, threshold }`. A preset's rule changes without its text
+   * being copied into `rules`.
+   */
+  overrides: Schema.optionalKey(Schema.Record(Schema.String, Override)),
+  /**
+   * Whether Jev reads every comment, for rules about comments. By default
+   * comments are taken out, since a comment changes nothing a file does, but
+   * for the notes that say `@adhere`.
+   */
+  includeComments: Schema.optionalKey(Schema.Boolean),
 });
 
 /** Where a repo keeps its rule files by default. The cache lives under it. */
@@ -120,17 +189,40 @@ export const SKIPPED_DIRECTORIES: ReadonlySet<string> = new Set([
   "vendor",
   "e2e",
 ]);
-export interface AdhereConfig extends Schema.Schema.Type<typeof AdhereConfig> {}
+/**
+ * Directories whose files are tests, matched as whole path segments below the
+ * working directory, as skipped directories are. Only a rule that says `tests`
+ * judges them, or a `.test` or `.spec` file, such as `a.test.tsx`, anywhere.
+ */
+export const TEST_DIRECTORIES: ReadonlySet<string> = new Set([
+  "test",
+  "tests",
+  "__tests__",
+  "testing",
+  "fixtures",
+  "fixture",
+  "__fixtures__",
+  "__mocks__",
+]);
 
-/** The shape a config file default-exports. */
+/** The shape a config file default-exports: the schema's input, where `presets` is optional. */
 export type Config = typeof AdhereConfig.Encoded;
 
 export const defineConfig = (config: Config) => config;
 
 /** A built-in rule set. Same shape as a config, minus `presets`. */
 export interface Preset {
+  /**
+   * Override the model id used. Defaults to "jev-latest"
+   */
   readonly model?: string;
+  /**
+   * Override the threshold that determines a positive match. Defaults to 0.8
+   */
   readonly threshold?: number;
+  /**
+   * Per-rule overrides.
+   */
   readonly rules: RuleSource;
 }
 
@@ -141,24 +233,33 @@ export type Loaded<T extends { readonly rules?: unknown }> = Omit<T, "rules"> &
 
 export const DEFAULT_MODEL = "jev-latest";
 export const DEFAULT_THRESHOLD = 0.8;
+export const DEFAULT_SUFFICIENCY_THRESHOLD = 0.6;
 
 /** A config with its presets folded in and every default applied. */
 export interface ResolvedConfig {
   readonly model: string;
   readonly threshold: number;
+  /** Below this, a finding's sufficiency adds a warning to it. */
+  readonly sufficiencyThreshold: number;
   readonly rules: Rules;
   readonly scopedRules?: RuleSet;
   /** Requests to Jev a minute, at most. Unset, requests go out as fast as they are made. */
   readonly rpm?: number;
+  /** The config's globs of files no rule judges. */
+  readonly exclude?: ReadonlyArray<string>;
+  /** Whether Jev reads every comment; unset, only the `@adhere` notes. */
+  readonly includeComments?: boolean;
 }
 
 /** Command-line values that apply on top of the config file. */
-export interface Overrides {
+export interface Flags {
   readonly presets?: ReadonlyArray<PresetName>;
   /** Replaces the config's global threshold. Per-rule thresholds still win. */
-  readonly threshold?: number;
+  readonly threshold?: number | undefined;
+  /** Replaces the config's sufficiency threshold. */
+  readonly sufficiencyThreshold?: number | undefined;
   /** Throttles requests to Jev to at most this many a minute. */
-  readonly rpm?: number;
+  readonly rpm?: number | undefined;
 }
 
 /**
@@ -167,10 +268,10 @@ export interface Overrides {
  * the whole preset already holds its rules.
  */
 export const presetsOf = (
-  config: Pick<AdhereConfig, "presets">,
-  overrides: Overrides,
+  config: Pick<typeof AdhereConfig.Type, "presets">,
+  flags: Flags,
 ): ReadonlyArray<PresetName> => {
-  const named = [...new Set([...(overrides.presets ?? []), ...config.presets])];
+  const named = [...new Set([...(flags.presets ?? []), ...config.presets])];
   return named.filter((name) => {
     const [whole] = name.split("/");
     return whole === name || !named.some((other) => other === whole);
@@ -183,11 +284,11 @@ export const presetsOf = (
  * rule with the same id.
  */
 export const resolveConfig = (
-  config: Loaded<AdhereConfig>,
-  overrides: Overrides = {},
+  config: Loaded<typeof AdhereConfig.Type>,
+  flags: Flags = {},
   registry: Readonly<Partial<Record<PresetName, Loaded<Preset>>>> = {},
 ): ResolvedConfig => {
-  const applied = presetsOf(config, overrides).flatMap((name) => {
+  const applied = presetsOf(config, flags).flatMap((name) => {
     const preset = registry[name];
     return preset === undefined ? [] : [preset];
   });
@@ -195,9 +296,13 @@ export const resolveConfig = (
     applied.map((preset) => preset[key]).findLast((value) => value !== undefined);
   return {
     model: config.model ?? last("model") ?? DEFAULT_MODEL,
-    threshold: overrides.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
+    threshold: flags.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
+    sufficiencyThreshold:
+      flags.sufficiencyThreshold ?? config.sufficiencyThreshold ?? DEFAULT_SUFFICIENCY_THRESHOLD,
     rules: Object.assign({}, ...applied.map((preset) => preset.rules), config.rules),
-    ...(overrides.rpm === undefined ? {} : { rpm: overrides.rpm }),
+    ...(flags.rpm === undefined ? {} : { rpm: flags.rpm }),
+    ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
+    ...(config.includeComments === undefined ? {} : { includeComments: config.includeComments }),
   };
 };
 
@@ -206,7 +311,14 @@ export class ConfigUnavailable extends Schema.TaggedError<ConfigUnavailable>()(
   { message: Schema.String },
 ) {}
 
-export const decodeConfig = (value: unknown): Effect.Effect<AdhereConfig, ConfigUnavailable> =>
+/**
+ * Decodes an in-memory value. @adhere The file-reading caller loadConfigFile
+ * in services/AdhereConfig.ts prefixes these errors with the config path;
+ * verified in its source and by CLI probes at all three config paths, 2026-09-26.
+ */
+export const decodeConfig = (
+  value: unknown,
+): Effect.Effect<typeof AdhereConfig.Type, ConfigUnavailable> =>
   Schema.decodeUnknownEffect(AdhereConfig)(value).pipe(
     Effect.mapError((problem) =>
       ConfigUnavailable.make({

package/src/contradictions.ts

@@ -1,4 +1,5 @@
-import { type RuleEntry, shownId } from "#rules.ts";
+import type { Rule } from "#config.ts";
+import { judgesFile, type RuleEntry, shownId } from "#rules.ts";
 import { Jev, type Pair } from "#services/Jev.ts";
 import { Effect } from "effect";
 
@@ -17,6 +18,10 @@ const scopesOverlap = (a: string, b: string): boolean => {
   return first === second || first.startsWith(`${second}/`) || second.startsWith(`${first}/`);
 };
 
+/** Whether two rules judge any of the same kind of file: a rule on tests only shares none with one that skips them. */
+const judgeSameKind = (a: Rule, b: Rule): boolean =>
+  (judgesFile(a, true) && judgesFile(b, true)) || (judgesFile(a, false) && judgesFile(b, false));
+
 /**
  * Per rule, the rules that apply to some of the same files. A rule with the
  * same id is left out: a nested rule that shares an id shadows the other on
@@ -25,7 +30,10 @@ const scopesOverlap = (a: string, b: string): boolean => {
 const partnersOf = (entries: ReadonlyArray<RuleEntry>): ReadonlyArray<ReadonlyArray<number>> =>
   entries.map((first, index) =>
     entries.flatMap((second, other) =>
-      other !== index && first.id !== second.id && scopesOverlap(first.scope, second.scope)
+      other !== index &&
+      first.id !== second.id &&
+      scopesOverlap(first.scope, second.scope) &&
+      judgeSameKind(first.rule, second.rule)
         ? [other]
         : [],
     ),

package/src/excerpt.ts

@@ -1,22 +1,14 @@
 import { scan } from "#highlight.ts";
 
-/**
- * The lines a finding shows: the statement its line is in, such as the
- * function around it, and a few lines on either side of the line.
- */
+/** The lines a finding shows: the section of the file it is in. */
 export interface Excerpt {
   /** The number of the first line, counting from 1. */
   readonly start: number;
   readonly lines: ReadonlyArray<string>;
 }
 
-/** How far an excerpt reaches on either side of the finding's line, in whole statements. */
-const AROUND = 3;
-/** The most lines a statement can have and still be shown whole. */
-const WHOLE = 30;
-
 /** Lines of the code, first to last, counting from 1. */
-interface Range {
+export interface Range {
   readonly first: number;
   readonly last: number;
 }
@@ -48,19 +40,13 @@ const ROLES: Readonly<Record<string, Piece["role"]>> = {
   ",": "separator",
 };
 
-/**
- * The code as pieces, without whitespace and comments, and the comments and
- * literals that span lines: a line that starts inside one does not read as
- * code on its own.
- */
+/** The code as pieces, without whitespace and comments. */
 const piecesOf = (code: string) => {
   const pieces: Array<Piece> = [];
-  const spans: Array<Range> = [];
   let line = 1;
   let spaced = true;
   for (const { text, kind } of scan(code)) {
     const end = line + text.split("\n").length - 1;
-    if (kind !== undefined && end > line) spans.push({ first: line, last: end });
     if (kind === "comment" || text.trim().length === 0) {
       spaced = true;
     } else if (kind !== undefined || /^[\w$]/.test(text)) {
@@ -75,7 +61,7 @@ const piecesOf = (code: string) => {
     }
     line = end;
   }
-  return { pieces, spans };
+  return { pieces };
 };
 
 /**
@@ -209,47 +195,81 @@ const statementsAround = (
   ];
 };
 
+/** The most lines a section holds, unless one statement with no group to split is longer. */
+const SECTION = 30;
+
 /**
- * The excerpt for a finding on `line`: the outermost statement around it
- * with at most `WHOLE` lines, such as the function it is in, and up to
- * `AROUND` lines on either side of `line`. A comment or template literal
- * that spans lines counts as a statement inside the one it is in.
- *
- * Around `line`, the excerpt shows only whole statements, never the end of
- * the one above or the start of the one below, so it cannot start partway
- * through a comment, whose lines do not read as code on their own. What
- * `line` itself is in can show in part: a long function's first line, above
- * the statement of its body. It ends at code, since a comment at the end
- * would be about code the excerpt leaves out.
+ * The file in sections, each ending where a statement does: its top-level
+ * statements, such as its imports, constants, and functions, packed in
+ * order into sections of at most `SECTION` lines, a decorator with what it
+ * decorates. A statement longer than that splits into the statements of its
+ * largest group, such as a class's methods or a component's body, the lines
+ * around that group going with the first and last of them. Every line is in
+ * one section: the comments and blank lines above a statement go with it,
+ * and the last section runs to the end.
  */
-export const excerptOf = (lines: ReadonlyArray<string>, line: number): Excerpt => {
-  const { pieces, spans } = piecesOf(lines.join("\n"));
+export const sectionsOf = (lines: ReadonlyArray<string>): ReadonlyArray<Range> => {
+  const { pieces } = piecesOf(lines.join("\n"));
   const closes = closesOf(pieces);
-  /** What a line is in, outermost first. */
-  const around = (at: number): ReadonlyArray<Range> => [
-    ...statementsAround(pieces, closes, at),
-    ...spans.filter((span) => holds(span, at)),
-  ];
-  const scope = around(line).find((range) => range.last - range.first < WHOLE);
-  const top = Math.max(1, Math.min(scope?.first ?? line, line - AROUND));
-  const bottom = Math.min(lines.length, Math.max(scope?.last ?? line, line + AROUND));
-  /** What a line is in that `line` is not, which an edge shows whole or not at all. */
-  const beside = (at: number) => around(at).filter((range) => !holds(range, line));
-  let first = Math.max(
-    top,
-    ...beside(top)
-      .filter((range) => range.first < top)
-      .map((range) => range.last + 1),
-  );
-  let last = Math.min(
-    bottom,
-    ...beside(bottom)
-      .filter((range) => range.last > bottom)
-      .map((range) => range.first - 1),
-  );
-  const isBlank = (at: number) => (lines[at - 1] ?? "").trim().length === 0;
-  const hasCode = (at: number) => pieces.some((piece) => piece.line <= at && at <= piece.end);
-  while (first < line && isBlank(first)) first += 1;
-  while (last > line && !hasCode(last)) last -= 1;
-  return { start: first, lines: lines.slice(first - 1, last) };
+  const lineOf = (index: number) => pieces[index]?.line ?? 0;
+  /** Statements as ranges of at most `SECTION` lines where they can be split. */
+  const units = (statements: ReadonlyArray<Statement>): ReadonlyArray<Range> =>
+    statements.flatMap((statement): ReadonlyArray<Range> => {
+      if (statement.last - statement.first < SECTION) return [statement];
+      const largest = statement.groups.reduce<readonly [number, number] | undefined>(
+        (best, group) =>
+          best === undefined ||
+          lineOf(group[1]) - lineOf(group[0]) > lineOf(best[1]) - lineOf(best[0])
+            ? group
+            : best,
+        undefined,
+      );
+      const inner =
+        largest === undefined
+          ? []
+          : units(statementsIn(pieces, closes, largest[0] + 1, largest[1]));
+      const [head, tail] = [inner[0], inner.at(-1)];
+      if (head === undefined || tail === undefined || inner.length < 2) return [statement];
+      return [
+        { first: statement.first, last: head.last },
+        ...inner.slice(1, -1),
+        { first: tail.first, last: statement.last },
+      ];
+    });
+  const sections: Array<Range> = [];
+  /** A decorator, such as `@Command({…})`, waiting for the declaration it decorates. */
+  let decorator: Range | undefined;
+  for (const found of units(statementsIn(pieces, closes, 0, pieces.length))) {
+    if ((lines[found.first - 1] ?? "").trimStart().startsWith("@")) {
+      decorator = { first: decorator?.first ?? found.first, last: found.last };
+      continue;
+    }
+    const unit = { first: decorator?.first ?? found.first, last: found.last };
+    decorator = undefined;
+    const previous = sections.at(-1);
+    if (previous !== undefined && unit.last - previous.first < SECTION) {
+      sections[sections.length - 1] = { first: previous.first, last: unit.last };
+    } else {
+      sections.push({ first: unit.first, last: unit.last });
+    }
+  }
+  if (decorator !== undefined) sections.push(decorator);
+  // A file of comments alone, with no statement, is one section.
+  if (sections.length === 0) return lines.length === 0 ? [] : [{ first: 1, last: lines.length }];
+  // Each section starts where the one before it ends, and the last one ends with the file.
+  return sections.flatMap((section, index): ReadonlyArray<Range> => {
+    const first = (sections[index - 1]?.last ?? 0) + 1;
+    const last = index === sections.length - 1 ? lines.length : section.last;
+    return last < first ? [] : [{ first, last }];
+  });
+};
+
+/**
+ * The statement that starts on `line`, such as a property, a function, or a
+ * call that opens there: the outermost statement around `line` whose first
+ * line it is. None when no statement starts on `line`.
+ */
+export const statementFrom = (lines: ReadonlyArray<string>, line: number): Range | undefined => {
+  const { pieces } = piecesOf(lines.join("\n"));
+  return statementsAround(pieces, closesOf(pieces), line).find((range) => range.first === line);
 };

package/src/highlight.ts

@@ -30,6 +30,8 @@ const CLASSES = ["comment", "string", "constant"] as const;
 /** One group per token class, tried in order at each position. A template literal is read apart. */
 const TOKEN = new RegExp(
   [
+    // A URL outside a string is JSX text, as in `<a>https://example.com</a>`, and its `//` no comment.
+    /(?<url>[a-z][\w+.-]*:\/\/[^\s<>{}"'`]*)/,
     /(?<comment>\/\/[^\n]*|\/\*[\s\S]*?(?:\*\/|$))/,
     /(?<string>"(?:[^"\\\n]|\\.)*"?|'(?:[^'\\\n]|\\.)*'?)/,
     /(?<constant>0[box][\da-f_]+n?|\d[\d_]*(?:\.\d[\d_]*)?(?:e[+-]?\d+)?n?)/,

package/src/index.ts

@@ -10,7 +10,7 @@ export {
   type RuleSource,
 } from "#config.ts";
 export { findContradictions, formatContradictions, type Contradiction } from "#contradictions.ts";
-export { initProject, type InitOptions, type InitResult } from "#init.ts";
+export { initProject, type InitOptions, type InitResult, type Install } from "#init.ts";
 export { parseRuleMarkdown } from "#markdown.ts";
 export { type PresetName, presetNames } from "#presets.ts";
 export {

package/src/init.ts

@@ -1,4 +1,5 @@
-import { access, mkdir, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { CONFIG_FILES } from "#config.ts";
 import { Effect } from "effect";
@@ -6,17 +7,45 @@ import { Effect } from "effect";
 export interface InitResult {
   readonly created: ReadonlyArray<string>;
   readonly skipped: ReadonlyArray<string>;
+  /** The package manager that added adhere, or why none did. */
+  readonly install: Install;
 }
 
+export type Install =
+  | { readonly status: "installed"; readonly packageManager: PackageManager }
+  | { readonly status: "listed" }
+  | { readonly status: "no-package-json" };
+
 export interface InitOptions {
   readonly force?: boolean;
 }
 
-const CONFIG = `import type { Config } from "@drkmttr/adhere";
+// adhere-ignore-file rules/import-written-files -- src/index.ts exports initProject, so a Bun text import here breaks loading the package on Node and in Vitest (checked 2026-09-26), and the compiled executable has no files beside it to read.
+const CONFIG = `import { defineConfig } from "@drkmttr/adhere";
 
-export default {
+export default defineConfig({
   threshold: 0.8,
-} satisfies Config;
+});
+`;
+
+/**
+ * A project for the config alone. A tsconfig's globs skip dot directories, so
+ * without it the editor opens `.adhere/config.ts` outside any project, where
+ * it cannot resolve `@drkmttr/adhere`, whose types only `bundler`, `node16`,
+ * and `nodenext` resolution reach.
+ */
+const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["config.ts"]
+}
 `;
 
 const SMALL_FILES = `---
@@ -24,16 +53,20 @@ description: A file should be small and focused, with one primary responsibility
 threshold: 0.8
 ---
 
-A guideline, so its description and its code say should and should not. A
+A guideline, so its description and its headings say should and should not. A
 rule that must hold says must and never instead, as name-domain-actions does.
 Use this rule as a template for repository-specific conventions.
 
-\`\`\`ts should
+## Should
+
+\`\`\`ts
 export const parsePort = (value: string) =>
   Port.make(Number.parseInt(value, 10));
 \`\`\`
 
-\`\`\`ts should not
+## Should not
+
+\`\`\`ts
 export const parsePort = (value: string) => Port.make(Number.parseInt(value, 10));
 export const sendWelcomeEmail = (to: Email) => Mailer.send(to, welcomeTemplate);
 export const renderInvoice = (invoice: Invoice) => Html.table(invoice.lines);
@@ -45,17 +78,21 @@ description: A function must be named after the domain action it performs, never
 threshold: 0.8
 ---
 
-\`\`\`ts must
+## Must
+
+\`\`\`ts
 export const loadCustomerProfile = (customerId: CustomerId) =>
   Effect.gen(function* () {
     return yield* CustomerStore.find(customerId);
   });
 \`\`\`
 
-A fence tagged \`never\` shows what a violation looks like. It is optional, and
-a rule can have one without the block above.
+## Never
 
-\`\`\`ts never
+The code under Never shows what a violation looks like. It is optional, and a
+rule can have it without the code under Must.
+
+\`\`\`ts
 export const handle = (id: string) =>
   Effect.gen(function* () {
     return yield* CustomerStore.find(id);
@@ -65,8 +102,12 @@ export const handle = (id: string) =>
 
 const CONFIG_PATH = CONFIG_FILES[0];
 
+/** The config's own project, which only a config at `.adhere/config.ts` needs. */
+const CONFIG_PROJECT = ".adhere/tsconfig.json";
+
 const files = [
   [CONFIG_PATH, CONFIG],
+  [CONFIG_PROJECT, TSCONFIG],
   [".adhere/style/prefer-small-files.md", SMALL_FILES],
   [".adhere/style/name-domain-actions.md", NAME_EFFECTS],
 ] as const;
@@ -102,6 +143,69 @@ const writeScaffoldFile = (root: string, path: string, contents: string, options
       ),
   });
 
+const PACKAGE = "@drkmttr/adhere";
+
+type PackageManager = "bun" | "pnpm" | "yarn" | "npm";
+
+/** The first lockfile at the root names the package manager; npm when there is none. */
+const lockfiles: ReadonlyArray<readonly [string, PackageManager]> = [
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"],
+];
+
+const packageManagerAt = async (root: string): Promise<PackageManager> => {
+  for (const [file, manager] of lockfiles) {
+    if (await exists(join(root, file))) return manager;
+  }
+  return "npm";
+};
+
+/**
+ * pnpm refuses to add to a workspace root without a flag. `-w` fails outside a
+ * workspace, so the first one, which works in both, stands in for it. pnpm 11
+ * also fails on msgpackr-extract's unapproved build script. It comes with
+ * effect, and adhere never calls msgpackr, so the second flag lets pnpm skip
+ * the build with a warning.
+ */
+const addFlags: Record<PackageManager, ReadonlyArray<string>> = {
+  bun: [],
+  pnpm: ["--ignore-workspace-root-check", "--config.strict-dep-builds=false"],
+  yarn: [],
+  npm: [],
+};
+
+/** Adds adhere to devDependencies, so the config's `import type` resolves. */
+const installAdhere = (root: string) =>
+  Effect.tryPromise({
+    try: async (): Promise<Install> => {
+      const manifest = await readFile(join(root, "package.json"), "utf8").catch(() => undefined);
+      if (manifest === undefined) return { status: "no-package-json" };
+      const { dependencies, devDependencies } = JSON.parse(manifest);
+      if (dependencies?.[PACKAGE] !== undefined || devDependencies?.[PACKAGE] !== undefined) {
+        return { status: "listed" };
+      }
+      const packageManager = await packageManagerAt(root);
+      await new Promise<void>((resolve, reject) => {
+        spawn(packageManager, ["add", "-D", PACKAGE, ...addFlags[packageManager]], {
+          cwd: root,
+          stdio: "inherit",
+        })
+          .on("error", reject)
+          .on("exit", (code) =>
+            code === 0 ? resolve() : reject(new Error(`${packageManager} exited with ${code}`)),
+          );
+      });
+      return { status: "installed", packageManager };
+    },
+    catch: (cause) =>
+      new Error(
+        `Could not add ${PACKAGE} to package.json: ${cause instanceof Error ? cause.message : String(cause)}`,
+      ),
+  });
+
 export const initProject = (
   root: string,
   options: InitOptions = {},
@@ -115,6 +219,8 @@ export const initProject = (
         skipped.push(existing);
         continue;
       }
+      // A config at another path is in the project's own tsconfig, or not ours to place.
+      if (path === CONFIG_PROJECT && existing !== undefined) continue;
       const status = yield* writeScaffoldFile(root, path, contents, options);
       if (status === "created") {
         created.push(relative(root, join(root, path)));
@@ -122,5 +228,6 @@ export const initProject = (
         skipped.push(relative(root, join(root, path)));
       }
     }
-    return { created, skipped };
+    const install = yield* installAdhere(root);
+    return { created, skipped, install };
   });