@drkmttr/adhere 0.17.5 → 0.18.1

package/skills/adhere-setup/SKILL.md

@@ -37,23 +37,30 @@ wherever this skill says `adhere`, run it the manager's way, as in
 
 With pnpm, at a workspace root, add `--ignore-workspace-root-check`.
 
-Default lint enables `workspacePackages`, `symbols`, and `references`, and
-starts native TypeScript only during execution, after confirmation, when
-pending judgments or cached findings needing location require context. It discovers each
-file's configured project, including package projects under solution roots,
-and falls back to inferred context for unconfigured or excluded files. No root
-`tsconfig.json` or literal root file-list membership is required; do not block
-setup on either. `.adhere/tsconfig.json` only types the config and rules.
-Planning, `--limit 0`, version, help, skills, and validate do not start the
-compiler.
+Default lint reads code and `workspacePackages` without starting a compiler.
+`typeAware` defaults to `false`; `typeAware: true` or `--type-aware` opts into
+both `symbols` and `references`, regardless of `reads`. `reads` now controls
+workspace context only, defaulting to `["workspacePackages"]`; legacy native
+reader entries alone do not opt in. Code alone uses `reads: []` with type
+awareness off. Explain the extra context/cost and **Ask** before opting in.
+
+With type awareness enabled, native TypeScript starts only during execution,
+after confirmation, when pending judgments or cached findings needing location
+require context. It discovers each file's configured project, including package
+projects under solution roots, and falls back to inferred context for
+unconfigured or excluded files. No root `tsconfig.json` or literal root file-list
+membership is required; do not block setup on either. `.adhere/tsconfig.json`
+only types the config and rules. Planning, `--limit 0`, version, help, skills,
+and validate do not start the compiler.
 
 In a repo without a `package.json`, inspect any `adhere` on PATH with
 `adhere --version`, then **Ask** whether to use the npm/Bun package launcher
-for the full default or a raw executable with deliberately reduced context.
-The raw release (`adhere-Windows-x86_64.exe` on Windows) needs no Node or
-package manager, but its lint requires explicit config `reads: []` or
-`reads: ["workspacePackages"]`. Do not silently disable readers to make it
-work. Only fetch it after the user chooses that alternative:
+or a raw executable for the same default compiler-free audit. The raw release
+(`adhere-Windows-x86_64.exe` on Windows) needs no Node or package manager and
+runs with workspace context without special configuration. It cannot run a
+type-aware audit: use the package launcher or a checkout if the user opts in.
+Do not silently turn off an explicitly chosen `typeAware` setting. Only fetch
+the raw release after the user chooses that alternative:
 
 ```sh
 curl -fsSL --create-dirs -o ~/.local/bin/adhere \
@@ -139,10 +146,11 @@ the wording of any. Revise drafts the user wants changed and show them again.
 - Copy each chosen draft to `.adhere/rules/<topic>/<slug>/RULE.md`.
 - Add chosen presets, or topics, to `presets` in `.adhere/config.ts`. Presets
   use the audit-wide readers; they do not own or override `reads`.
-- Leave `reads` omitted for the full default. Do not add `reads: []` to the
-  normal setup recommendation or as a workaround for missing compiler
-  resources. Only set an explicit replacement array if the user chooses to
-  disable or limit readers.
+- Leave `reads` omitted for default workspace context and `typeAware` off
+  unless the user explicitly chooses type-aware execution. `reads: []` omits
+  workspace context, not native maps. Only replace `reads` if the user chooses
+  to limit workspace context. If requested type awareness lacks compiler resources,
+  use the package launcher or a checkout; do not silently turn it off.
 - Install chosen shared rules: `adhere install org/repo/<id>` for each, or
   `adhere install org/repo` for all of them. They land in `.adhere/rules/org/repo/`.
 - Add `exclude` globs for generated or vendored code the default skips miss.
@@ -177,19 +185,21 @@ cost, and request splits may be higher. Source reload/hash work is bounded to
 for execution; if normalized code or ignore
 directives changed since planning, rerun rather than using the old plan.
 
-Tell the user that compiler type/docs strings and outgoing declaration snippets add
-source/documentation sharing and token cost by default, including complete
-scopes from files outside the audit filter. Whole declaration bodies can use more
-tokens than fixed-line excerpts; budget overflow skips the file instead of
-capping bodies to seven lines or silently truncating them. Compiler-provided
-documentation and JSDoc tags can remain even when ordinary code comments are
-stripped; omitting `symbols` disables type/docs context and omitting
-`references` disables snippets. The global workspace catalog is not sent: only
-this file's matched literal imports appear under canonical package keys.
-Offer an explicit reader subset or code-only opt-out if they want less context;
-never apply one silently. Neither reader selection nor dependency/shared-context
-changes invalidate cached judgments. If they want fresh answers under changed
-context, **Ask** before clearing `.adhere/cache/`; do not clear it automatically.
+If the user opts into type awareness, explain that both compiler type/docs
+strings and outgoing declaration snippets add source/documentation sharing and
+token cost, including complete scopes from files outside the audit filter.
+Whole declaration bodies can use more tokens than fixed-line excerpts. Context
+overflow gets one retry without `references`, keeping target code and `symbols`
+intact; it can still overflow and skip the file. Declaration bodies are not
+shortened to fit. Compiler documentation and JSDoc tags can remain even when
+ordinary code comments are stripped, subject to the configured symbol limits.
+The global workspace catalog is not sent: only this file's matched literal
+imports appear under canonical package keys.
+Offer type awareness only as an explicit opt-in, or `reads: []` with type
+awareness off for code alone; never apply either silently. Neither `reads`,
+`typeAware`, nor dependency/shared-context changes invalidate cached judgments.
+If they want fresh answers under changed context, **Ask** before clearing
+`.adhere/cache/`; do not clear it automatically.
 
 On a large repo, offer a subtree such as `--filter 'src/**'`, or a file cap
 such as `--limit 100`: the first 100 files needing requests in path order, with
@@ -201,7 +211,9 @@ or HTTP-size skips after selection consume a slot without runtime refill.
 
 Explain that a file cap is not an HTTP-request or token/cost cap: each file can
 produce judge, locate, split-batch, and private hook requests. **Ask** before
-sending, then run the command below with only the user's chosen filter/file cap:
+sending, then run the command below with only the user's chosen filter/file cap
+and `--type-aware` if they explicitly opted in, or retain `typeAware: true` in
+their config:
 
 ```sh
 adhere lint --yes
@@ -209,11 +221,14 @@ adhere lint --yes
 
 `SourceReads.prepare(paths)` registers eligible-path metadata only, with no
 file I/O, compiler/SDK import, spawn, snapshot, or semantic query, even for a large list.
-Only after confirmation do pending judgments or cached findings still needing
-location trigger actual per-file native reads just before judge/locate. Native
+Only with type awareness enabled, and after confirmation, do pending judgments
+or cached findings still needing location trigger actual per-file native reads
+just before judge/locate. Native
 transactions are serial through one permit; HTTP execution remains concurrent
 at 8. Returned context is reused locally and full budgets are enforced before
-HTTP, with oversized files skipped and no silent truncation. Shared state plus
+HTTP. Oversized context gets one retry without references when present, then
+skips the file if it still does not fit; code and declaration bodies are not
+shortened to fit. Shared state plus
 one question must fit 32k tokens and state plus all questions must fit 64k per
 request, with 1k reserved for overhead. The SDK may still parse a full selected
 project, and additional monorepo programs may increase startup time and memory.
@@ -223,9 +238,13 @@ blocks for same-name binding/narrowing contexts, with compiler documentation
 and JSDoc tags once per canonical symbol per file. It does not promise literal
 IDE labels or selected-call overload presentation. Symbol/type queries are
 batched, and independent SDK requests are chunked to at most 8 within the single
-active native document/snapshot; HTTP work remains concurrent at 8. `references` maps used names to canonical outgoing declarations
-by pathname, selecting the smallest complete AST scope without extra surrounding
-lines. Functions include full bodies; arrow/object initializer variables include
+active native document/snapshot; HTTP work remains concurrent at 8. Standard-library
+and Node/Bun built-ins are omitted, but project and third-party names remain.
+`references` is a flat `Record<string, string>` keyed by
+`symbol:repository-relative pathname`, retaining import alias names and original
+pathname casing. Values are declarations of symbols used by the target code,
+not incoming call sites, selecting the smallest complete AST scope without extra
+surrounding lines. Functions include full bodies; arrow/object initializer variables include
 whole variable statements with `export const` and semicolons. Methods, getters,
 and setters include their whole member, not the entire class; classes,
 interfaces, and type aliases include the whole declaration. Repeated/overlapping
@@ -235,7 +254,10 @@ not automatically expanded. Scopes preserve indentation and the comment/directiv
 policy, including associated JSDoc when `includeComments` is true; compiler
 docs/tags in `symbols` remain available regardless. Current-file, declaration-file, `node_modules`, and
 outside-root exclusions are unchanged. There are no incoming callers, counts, structured locations,
-unresolved lists, full-file collection, or completeness markers.
+unresolved lists, full-file collection, or completeness markers. Enabled context
+maps include a self-describing `__comment`; top-level guidance identifies only
+`code` as the audit target. Both native maps require the same type-awareness
+opt-in; `reads` cannot select or disable them individually.
 
 The first actual read lazily starts one native TypeScript LSP process with its
 public SDK API pipe; both are pinned to exactly `7.1.0-dev.20261009.1` and must
@@ -332,15 +354,16 @@ jobs:
 Pin the versions the repo already uses: bun's `bun-version`, Node's
 `node-version` from `.nvmrc` or `engines`, and pnpm's from `packageManager`,
 which `pnpm/action-setup` reads. Keep optional dependencies enabled so adhere's
-platform package and its compiler dependency are installed. Existing project
-configs and dependencies supply configured context when available; files with
-no configured project or excluded from one use inferred context. Do not require
-or generate a root `tsconfig.json` merely to make default lint run. In a repo
-without a `package.json`, use the package launcher for the full default.
-Only skip setup/install and fetch the raw executable if the user explicitly
-chose and committed `reads: []` or `reads: ["workspacePackages"]` locally.
-That is a reduced-context alternative, not an equivalent default installation.
-Fetch the executable at the version the user ran:
+platform package and its compiler dependency are installed. For type-aware audits,
+existing project configs and dependencies supply configured context when available;
+files with no configured project or excluded from one use inferred context. Do not
+require or generate a root `tsconfig.json` merely to make default lint run. Both
+package launchers and raw executables support the default compiler-free audit,
+including in repos without a `package.json`; no `reads` override is required.
+If the user explicitly chose type-aware execution, use the package launcher or a
+checkout; do not silently turn it off. For the default compiler-free audit, you can
+instead skip runtime setup/install and fetch the raw executable at the version
+the user ran:
 
 ```yaml
 - run: |

package/src/cli.ts

@@ -59,6 +59,10 @@ import skill from "../skills/adhere/SKILL.md" with { type: "text" };
 import fixSkill from "../skills/adhere-fix/SKILL.md" with { type: "text" };
 import setupSkill from "../skills/adhere-setup/SKILL.md" with { type: "text" };
 
+// @adhere This file owns CLI flags, progress output, and command wiring. Audit execution,
+// scaffolding, rule installation, credential storage, and rule checks are implemented in
+// their own modules imported above; the commands here connect them to the CLI.
+
 class FindingsReported extends Schema.TaggedError<FindingsReported>()("FindingsReported", {
   count: Schema.Finite,
 }) {
@@ -114,6 +118,13 @@ const sufficiencyThreshold = Flag.Finite("sufficiency-threshold").pipe(
   ),
 );
 
+const typeAware = Flag.Boolean("type-aware").pipe(
+  Flag.optional,
+  Flag.withDescription(
+    "Include compiler-resolved symbols and declaration excerpts. Off by default.",
+  ),
+);
+
 const limit = Flag.Int("limit").pipe(
   Flag.filter(
     (files) => files >= 0,
@@ -235,7 +246,7 @@ export const auditLayer = (flags: Flags, filter: ReadonlyArray<string> = []) =>
 /** `adhere lint`: the audit. */
 export const lintCommand = Command.make(
   "lint",
-  { preset, threshold, sufficiencyThreshold, yes, limit, rpm, filter, denyWarnings },
+  { preset, threshold, sufficiencyThreshold, typeAware, yes, limit, rpm, filter, denyWarnings },
   (input) =>
     Effect.gen(function* () {
       const stdio = yield* Stdio.Stdio;
@@ -298,6 +309,7 @@ export const lintCommand = Command.make(
         presets: input.preset,
         threshold: Option.getOrUndefined(input.threshold),
         sufficiencyThreshold: Option.getOrUndefined(input.sufficiencyThreshold),
+        typeAware: Option.getOrUndefined(input.typeAware),
         rpm: Option.getOrUndefined(input.rpm),
       },
       input.filter,

package/src/config.ts

@@ -220,8 +220,14 @@ export const AdhereConfig = Schema.Struct({
   presets: Schema.Array(Schema.Literals(presetNames)).pipe(
     Schema.withDecodingDefaultKey(Effect.succeed([])),
   ),
-  /** Shared context for every audited file and all its rules. Unset: all built-in reads; []: code only. */
+  /** Workspace context shared by every rule. Defaults to workspacePackages; [] disables it. Native read names do not enable type awareness. */
   reads: Schema.optionalKey(Reads),
+  /** Include both compiler-resolved symbols and declaration excerpts. Defaults to false. */
+  typeAware: Schema.optionalKey(Schema.Boolean),
+  /** Maximum characters of each symbol's complete resolved content. Defaults to 256. */
+  maxSymbolLength: Schema.optionalKey(Schema.Natural),
+  /** Maximum characters of documentation and JSDoc tags per symbol. Defaults to 256; 0 omits them. */
+  maxSymbolDocumentationLength: Schema.optionalKey(Schema.Natural),
   /**
    * A record of rules, or a directory path relative to the config file,
    * which holds its rules as `.adhere/rules/` does. Unset: the rules in
@@ -329,7 +335,9 @@ 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;
-export const DEFAULT_READS: typeof Reads.Type = ["workspacePackages", "symbols", "references"];
+export const DEFAULT_READS: typeof Reads.Type = ["workspacePackages"];
+export const DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH = 256;
+export const DEFAULT_MAX_SYMBOL_LENGTH = 256;
 
 /** A config with its presets folded in and every default applied. */
 export interface ResolvedConfig {
@@ -349,6 +357,12 @@ export interface ResolvedConfig {
   readonly includeComments?: boolean;
   /** Built-in context shared by every rule, with the default applied. */
   readonly reads: typeof Reads.Type;
+  /** Whether both native symbol and declaration context are enabled. */
+  readonly typeAware: boolean;
+  /** Maximum characters of each symbol's complete resolved content. */
+  readonly maxSymbolLength: number;
+  /** Maximum characters of documentation and JSDoc tags before the complete symbol limit applies. */
+  readonly maxSymbolDocumentationLength: number;
   /**
    * The workspace's packages, each name with its directory from the working
    * directory, read from its manifests on every run when the config's reads
@@ -366,6 +380,8 @@ export interface Flags {
   readonly sufficiencyThreshold?: number | undefined;
   /** Throttles requests to Jev to at most this many a minute. */
   readonly rpm?: number | undefined;
+  /** Replaces the config's native-context opt-in. */
+  readonly typeAware?: boolean | undefined;
 }
 
 /**
@@ -400,6 +416,7 @@ export const resolveConfig = (
   });
   const last = <K extends "model" | "threshold">(key: K) =>
     applied.map((preset) => preset[key]).findLast((value) => value !== undefined);
+  const typeAware = flags.typeAware ?? config.typeAware ?? false;
   return {
     model: config.provider?.model ?? config.model ?? last("model") ?? DEFAULT_MODEL,
     ...(config.provider === undefined ? {} : { provider: config.provider }),
@@ -410,7 +427,14 @@ export const resolveConfig = (
     ...(flags.rpm === undefined ? {} : { rpm: flags.rpm }),
     ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
     ...(config.includeComments === undefined ? {} : { includeComments: config.includeComments }),
-    reads: config.reads ?? DEFAULT_READS,
+    typeAware,
+    reads: [
+      ...(config.reads ?? DEFAULT_READS).filter((read) => read === "workspacePackages"),
+      ...(typeAware ? (["symbols", "references"] as const) : []),
+    ],
+    maxSymbolLength: config.maxSymbolLength ?? DEFAULT_MAX_SYMBOL_LENGTH,
+    maxSymbolDocumentationLength:
+      config.maxSymbolDocumentationLength ?? DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH,
   };
 };
 

package/src/init.ts

@@ -2,7 +2,7 @@ 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";
+import { Effect, Schema } from "effect";
 
 export interface InitResult {
   readonly created: ReadonlyArray<string>;
@@ -305,6 +305,13 @@ const writeScaffoldFile = (root: string, path: string, contents: string, options
 
 const PACKAGE = "@drkmttr/adhere";
 
+const PackageManifest = Schema.fromJsonString(
+  Schema.Struct({
+    dependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+    devDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+  }),
+);
+
 type PackageManager = "bun" | "pnpm" | "yarn" | "npm";
 
 /** The first lockfile at the root names the package manager; npm when there is none. */
@@ -342,9 +349,21 @@ const addFlags: Record<PackageManager, ReadonlyArray<string>> = {
 const installPackages = (root: string, shared: boolean) =>
   Effect.tryPromise({
     try: async (): Promise<Install> => {
-      const manifest = await readFile(join(root, "package.json"), "utf8").catch(() => undefined);
+      const manifest = await readFile(join(root, "package.json"), "utf8").catch(
+        (cause: unknown) => {
+          if (
+            typeof cause === "object" &&
+            cause !== null &&
+            "code" in cause &&
+            cause.code === "ENOENT"
+          ) {
+            return undefined;
+          }
+          throw cause;
+        },
+      );
       if (manifest === undefined) return { status: "no-package-json" };
-      const { dependencies, devDependencies } = JSON.parse(manifest);
+      const { dependencies, devDependencies } = Schema.decodeUnknownSync(PackageManifest)(manifest);
       if (
         !shared &&
         (dependencies?.[PACKAGE] !== undefined || devDependencies?.[PACKAGE] !== undefined)

package/src/install.ts

@@ -37,30 +37,35 @@ const failed = (what: string) => (cause: unknown) =>
 const cloned = (source: Source) =>
   Effect.acquireRelease(
     Effect.tryPromise({
-      try: async () => {
-        const directory = await mkdtemp(join(tmpdir(), "adhere-install-"));
-        const branch = source.ref === undefined ? [] : ["--branch", source.ref];
-        const url = `https://github.com/${source.repo}.git`;
-        await new Promise<void>((resolve, reject) => {
-          let stderr = "";
-          spawn("git", ["clone", "--quiet", "--depth", "1", ...branch, url, directory], {
-            stdio: ["inherit", "ignore", "pipe"],
-          })
-            .on("error", reject)
-            .on("exit", (code) =>
-              code === 0
-                ? resolve()
-                : reject(new Error(stderr.trim() || `git exited with ${code}`)),
-            )
-            .stderr?.on("data", (chunk) => {
-              stderr += chunk;
-            });
-        });
-        return directory;
-      },
-      catch: failed(`Could not clone ${source.repo}`),
+      try: () => mkdtemp(join(tmpdir(), "adhere-install-")),
+      catch: failed(`Could not create a temporary directory for ${source.repo}`),
     }),
     (directory) => Effect.promise(() => rm(directory, { recursive: true, force: true })),
+  ).pipe(
+    Effect.tap((directory) =>
+      Effect.tryPromise({
+        try: async () => {
+          const branch = source.ref === undefined ? [] : ["--branch", source.ref];
+          const url = `https://github.com/${source.repo}.git`;
+          await new Promise<void>((resolve, reject) => {
+            let stderr = "";
+            spawn("git", ["clone", "--quiet", "--depth", "1", ...branch, url, directory], {
+              stdio: ["inherit", "ignore", "pipe"],
+            })
+              .on("error", reject)
+              .on("exit", (code) =>
+                code === 0
+                  ? resolve()
+                  : reject(new Error(stderr.trim() || `git exited with ${code}`)),
+              )
+              .stderr?.on("data", (chunk) => {
+                stderr += chunk;
+              });
+          });
+        },
+        catch: failed(`Could not clone ${source.repo}`),
+      }),
+    ),
   );
 
 /**
@@ -103,7 +108,8 @@ export const listRules = (source: Source) =>
       const rules = yield* rulesIn(source, yield* cloned(source));
       return yield* Effect.forEach(rules, ({ id, name, directory }) =>
         Effect.gen(function* () {
-          if (name === "RULE.ts") return { id, description: "(TypeScript, which list does not run)" };
+          if (name === "RULE.ts")
+            return { id, description: "(TypeScript, which list does not run)" };
           const text = yield* Effect.tryPromise({
             try: () => readFile(join(directory, name), "utf8"),
             catch: failed(`Could not read ${id}`),

package/src/services/Jev.http.ts

@@ -14,6 +14,7 @@ import { Credentials } from "#services/Credentials.ts";
 import {
   type Body,
   type ComparedRule,
+  describeState,
   edgeKey,
   conflictBody,
   contradictBody,
@@ -36,6 +37,7 @@ import {
   type Rules,
   sufficiencyKey,
   tokensOf,
+  logRequestPayload,
 } from "#services/Jev.ts";
 import {
   Duration,
@@ -87,7 +89,7 @@ const hooked = (
   return Effect.tryPromise({
     try: async () => ({
       ...body,
-      state: { ...body.state, ...(await appendState(body.state, file, bun)) },
+      state: describeState({ ...body.state, ...(await appendState(body.state, file, bun)) }),
     }),
     catch: (cause) => refused(`the appendState of ${id} failed: ${messageOf(cause)}`),
   });
@@ -190,6 +192,7 @@ export const JevLive = Layer.effect(Jev)(
     const limiter = yield* RateLimiter.RateLimiter;
 
     const provider: Provider = config.provider ?? jev({ model: config.model, fetch });
+    const previewed = new Set<string>();
     // The key it asks with, when it names one `adhere login` saves. Read when
     // a request needs it, not in the layer: a run with nothing pending needs none.
     const apiKey: Effect.Effect<string | undefined, JevUnavailable> =
@@ -226,8 +229,23 @@ export const JevLive = Layer.effect(Jev)(
         yield* Effect.logDebug(
           `${kind}: asking ${provider.model} ${questions} ${questions === 1 ? "question" : "questions"}, about ${tokensOf(body)} tokens`,
         );
+        if ((kind === "judge" || kind === "locate") && !previewed.has(kind)) {
+          previewed.add(kind);
+          yield* logRequestPayload(
+            `${kind}: first ${kind === "locate" ? "match-to-lines " : ""}request payload`,
+            () => body,
+            "Debug",
+          );
+        }
         const [elapsed, answered] = yield* Effect.timed(
-          askProvider(provider, body.state, questionsOf(body.questions), Answers, key, pace),
+          askProvider(provider, body.state, questionsOf(body.questions), Answers, key, pace).pipe(
+            Effect.tapErrorTag("JevOverflow", () =>
+              logRequestPayload(
+                `${kind}: too long request payload (provider overflow)`,
+                () => body,
+              ),
+            ),
+          ),
         );
         yield* Effect.logDebug(
           `${kind}: ${provider.model} answered in ${Math.round(Duration.toMillis(elapsed))} ms`,