@drkmttr/adhere 0.17.5 → 0.18.0

package/src/services/Jev.reads.test.ts

@@ -1,5 +1,7 @@
 import {
   type AppendState,
+  DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH,
+  DEFAULT_MAX_SYMBOL_LENGTH,
   type JevState,
   type ReadState,
   type ResolvedConfig,
@@ -10,6 +12,7 @@ import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { Credentials } from "#services/Credentials.ts";
 import { JevLive } from "#services/Jev.http.ts";
 import {
+  describeState,
   fits,
   Jev,
   judgeBody,
@@ -28,11 +31,11 @@ import { FetchHttpClient } from "effect/http";
 import { describe, expect, it } from "vite-plus/test";
 
 const plain: Rule = { description: "Ports must be named.", must: "const port = PORT;" };
-const lines = ["const port = 3000;"];
+const lines = ["const port = 3000;"] as const;
 const codeState = { code: { "1": lines[0] } };
 const file = { path: "/repo/src/server.ts", contents: lines.join("\n") };
 const symbols = { port: "```typescript\nconst port: number\n```" };
-const references = { PORT: { "src/config.ts": "export const PORT = 3000;\r\n" } };
+const references = { "PORT:src/config.ts": "export const PORT = 3000;\r\n" };
 const codeSufficiency = {
   type: "noul",
   instructions: {
@@ -76,6 +79,8 @@ const recordedJev = (
         model: "jev-latest",
         threshold: 0.8,
         sufficiencyThreshold: 0.6,
+        maxSymbolDocumentationLength: DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH,
+        maxSymbolLength: DEFAULT_MAX_SYMBOL_LENGTH,
         reads,
         rules: {},
         workspacePackages,
@@ -153,7 +158,19 @@ describe("prepared shared Jev reads", () => {
       project: { language: "typescript" },
       code: { "1": "replaced" },
     };
-    const enriched = { ...readState, ...codeState };
+    const enriched = describeState({ ...readState, ...codeState });
+    expect(enriched.__comment).toMatch(/only.*code|code.*only/i);
+    expect(enriched.__comment).toMatch(/context/i);
+    expect(enriched.symbols).toEqual({ ...symbols, __comment: expect.stringMatching(/symbol/i) });
+    expect(enriched.references).toEqual({
+      ...references,
+      __comment: expect.stringMatching(/symbol.*path|symbol.*file/i),
+    });
+    expect(enriched.workspacePackages).toEqual({
+      orders: "packages/orders",
+      __comment: expect.stringMatching(/package/i),
+    });
+    expect(Object.keys(enriched.code)).toEqual(["1"]);
     expect(judgeBody("", lines, rules, [], readState).state).toEqual(enriched);
     expect(locateBody("", lines, rules, readState).state).toEqual(enriched);
     const groups = requestGroups(rules);
@@ -166,8 +183,8 @@ describe("prepared shared Jev reads", () => {
       expect(judgeBody("", lines, group, [], readState).state).toEqual(enriched);
       const body = locateBody("", lines, group, readState);
       expect(body.state).toEqual(enriched);
-      expect(body.state.symbols).toBe(symbols);
-      expect(body.state.references).toBe(references);
+      expect(body.state.symbols).toEqual({ ...symbols, __comment: expect.any(String) });
+      expect(body.state.references).toEqual({ ...references, __comment: expect.any(String) });
       for (const id of Object.keys(group)) {
         expect(body.questions[`sufficient:${id}`]).toEqual(sufficiencyQuestion(plain, readState));
       }
@@ -176,9 +193,56 @@ describe("prepared shared Jev reads", () => {
     expect(locateRequests(lines, rules, readState)).toBe(3);
   });
 
+  it("preserves caller comments and raw context through judge, locate, and appended maps", async () => {
+    const readState = {
+      __comment: "User context: only target code is audited.",
+      symbols: { ...symbols, __comment: "User symbol description." },
+      references: { ...references, __comment: "User reference description." },
+      workspacePackages: { orders: "packages/orders", __comment: "User package description." },
+    };
+    const original = JSON.stringify(readState);
+    const hooked = {
+      ...plain,
+      appendState: () => ({ references: { "port:src/caller.ts": "\tuse(port);\r\n" } }),
+    };
+    const { sent, layer } = recordedJev();
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const jev = yield* Jev;
+        yield* jev.judge(lines, { plain, hooked }, [], file, readState);
+        yield* jev.locate(lines, { plain, hooked }, file, readState);
+      }).pipe(Effect.provide(layer)),
+    );
+    expect(sent).toHaveLength(4);
+    for (const body of sent) {
+      expect(body.state.code).toEqual(codeState.code);
+      expect(body.state.__comment).toBe(readState.__comment);
+      expect(body.state.symbols).toEqual(readState.symbols);
+      expect(body.state.workspacePackages).toEqual(readState.workspacePackages);
+    }
+    expect(sent[0]?.state.references).toEqual(readState.references);
+    expect(sent[2]?.state.references).toEqual(readState.references);
+    for (const index of [1, 3]) {
+      expect(sent[index]?.state.references).toEqual({
+        "port:src/caller.ts": "\tuse(port);\r\n",
+        __comment: expect.stringMatching(/symbol.*path|symbol.*file/i),
+      });
+    }
+    expect(JSON.stringify(readState)).toBe(original);
+    expect(
+      sent
+        .slice(2)
+        .flatMap(({ questions }) => Object.values(questions))
+        .filter(({ type }) => type === "noul")
+        .every(({ instructions }) => !instructions.question.includes("__comment")),
+    ).toBe(true);
+  });
+
   it("names actual shared keys in sufficiency, including packages but excluding duplicate code", () => {
     expect(sufficiencyQuestion(plain)).toEqual(codeSufficiency);
-    expect(sufficiencyQuestion(plain, { code: {} })).toEqual(codeSufficiency);
+    expect(sufficiencyQuestion(plain, { code: {}, __comment: "context description" })).toEqual(
+      codeSufficiency,
+    );
     expect(sufficiencyQuestion({ ...plain, appendState: () => ({ private: true }) })).toEqual(
       codeSufficiency,
     );
@@ -186,22 +250,32 @@ describe("prepared shared Jev reads", () => {
       { workspacePackages: {} },
       { symbols },
       { references },
-      { workspacePackages: {}, symbols, references, project: true, code: {} },
+      {
+        workspacePackages: {},
+        symbols,
+        references,
+        project: true,
+        code: {},
+        __comment: "context description",
+      },
     ]) {
       const question = sufficiencyQuestion(plain, readState);
       expect(question.instructions.question).not.toContain("`code` alone");
-      for (const key of Object.keys(readState).filter((key) => key !== "code")) {
+      for (const key of Object.keys(readState).filter(
+        (key) => key !== "code" && key !== "__comment",
+      )) {
         expect(question.instructions.question).toContain(`\`${key}\``);
         expect(question.criteria.true).toContain(`\`${key}\``);
         expect(question.criteria.false).toContain(`\`${key}\``);
       }
       expect(question.instructions.question.match(/`code`/g)).toHaveLength(2);
+      expect(JSON.stringify(question)).not.toContain("__comment");
     }
   });
 
   it("budgets all shared context beside every rule's questions", () => {
     const source = "export const value = 1;\n".repeat(2200);
-    const readState = { references: { value: { "src/related.ts": source } } };
+    const readState = { references: { "value:src/related.ts": source } };
     const large = { ...plain, must: "x".repeat(60_000) };
     const hooked = { ...plain, appendState: () => ({ private: "x".repeat(120_000) }) };
     expect(fits(lines, { large, hooked })).toBe(true);
@@ -295,7 +369,7 @@ describe("prepared shared Jev reads", () => {
     };
     const rules = { plain, native };
     const readState = {
-      references: { files: { "src/related.ts": "export const value = 1;\n".repeat(1500) } },
+      references: { "value:src/related.ts": "export const value = 1;\n".repeat(1500) },
     };
     const sampled = ["native"];
     expect(fits(long, rules, readState)).toBe(true);
@@ -338,7 +412,7 @@ describe("prepared shared Jev reads", () => {
 
   it("sends shared context once for non-hook rules and inherits it in private hook groups", async () => {
     const seen: Array<JevState> = [];
-    const privateSymbols = [{ name: "private", section: 1, usages: 0 }];
+    const privateSymbols = { private: "const private: number" };
     const appendState: AppendState = (state, receivedFile) => {
       expect(receivedFile).toBe(file);
       seen.push(state);
@@ -373,16 +447,19 @@ describe("prepared shared Jev reads", () => {
     });
     expect(result.judged.linter).toEqual({ plain: 0.9, hooked: 0.9 });
     expect(Object.keys(result.located)).toEqual(Object.keys(rules));
-    const enriched = { ...readState, ...codeState };
+    const enriched = describeState({ ...readState, ...codeState });
     expect(seen).toEqual([enriched, enriched, enriched, enriched]);
     for (const state of seen) {
-      expect(state.symbols).toBe(symbols);
-      expect(state.references).toBe(references);
-      expect(state.workspacePackages).toBe(workspacePackages);
+      expect(state.symbols).toEqual({ ...symbols, __comment: expect.any(String) });
+      expect(state.references).toEqual({ ...references, __comment: expect.any(String) });
+      expect(state.workspacePackages).toEqual({
+        ...workspacePackages,
+        __comment: expect.any(String),
+      });
     }
     const expectedStates = [
       enriched,
-      { ...enriched, private: "first", symbols: privateSymbols },
+      describeState({ ...enriched, private: "first", symbols: privateSymbols }),
       { ...enriched, private: "second" },
     ];
     expect(sent.map((body) => body.state)).toEqual([...expectedStates, ...expectedStates]);
@@ -432,8 +509,8 @@ describe("prepared shared Jev reads", () => {
     expect(sent.map((body) => body.state)).toEqual([
       codeState,
       codeState,
-      { symbols, ...codeState },
-      { symbols, ...codeState },
+      describeState({ symbols, ...codeState }),
+      describeState({ symbols, ...codeState }),
     ]);
   });
 });

package/src/services/Jev.ts

@@ -9,8 +9,8 @@ import {
   type Rules,
 } from "#config.ts";
 import { type Range, sectionsOf } from "#excerpt.ts";
-import type { SystemOneRequest } from "#providers/systemOne.ts";
-import { Context, type Effect, Record, Schema } from "effect";
+import type { SystemOneQuestion, SystemOneRequest } from "#providers/systemOne.ts";
+import { Context, Effect, LogLevel, Record, References, Schema } from "effect";
 
 export type { Rules };
 export type Lines = ReadonlyArray<string>;
@@ -139,6 +139,32 @@ const bytesOf = (value: unknown): number => encoder.encode(JSON.stringify(value)
  */
 export const tokensOf = (value: unknown): number => Math.ceil(bytesOf(value) / 3);
 
+const READ_COMMENTS: Readonly<Record<string, string>> = {
+  symbols:
+    "Compiler-inferred types, documentation, and JSDoc for symbols in `code`; keys are symbol names.",
+  references:
+    "Declarations of symbols used in `code`. Each key is `symbol:pathname`: the symbol name as used in `code` followed by its repository-relative declaration path. Each value is a complete declaration excerpt.",
+  workspacePackages:
+    "Workspace packages imported by `code`; keys are package names and values are repository-relative package directories. Only packages imported by this file are listed.",
+};
+
+/** Explain the known context maps while preserving caller-provided descriptions and target code. */
+export const describeState = (state: JevState): JevState => {
+  const described = { ...state };
+  for (const [name, comment] of Object.entries(READ_COMMENTS)) {
+    const value = state[name];
+    if (value !== null && typeof value === "object" && !Array.isArray(value))
+      described[name] = { __comment: comment, ...value };
+  }
+  if (
+    described.__comment === undefined &&
+    Object.keys(state).some((name) => name !== "code" && name !== "__comment")
+  )
+    described.__comment =
+      "Only `code` is the audit target; it is split into numbered sections. All other state entries provide context, not additional code to audit.";
+  return described;
+};
+
 /**
  * The file as Jev reads it: its sections, by `sectionsOf`, under their
  * numbers from 1, so the locate question can name one. Prepared context is
@@ -149,15 +175,16 @@ const stateOf = (
   lines: Lines,
   readState: ReadState = {},
   sections: ReadonlyArray<Range> = sectionsOf(lines),
-): JevState => ({
-  ...readState,
-  code: Object.fromEntries(
-    sections.map((section, index) => [
-      String(index + 1),
-      lines.slice(section.first - 1, section.last).join("\n"),
-    ]),
-  ),
-});
+): JevState =>
+  describeState({
+    ...readState,
+    code: Object.fromEntries(
+      sections.map((section, index) => [
+        String(index + 1),
+        lines.slice(section.first - 1, section.last).join("\n"),
+      ]),
+    ),
+  });
 
 /** The field an example goes under in a question: its word, with `should not` as `should_not`. */
 const fieldOf = (example: Example): string => example.word.replace(" ", "_");
@@ -361,7 +388,7 @@ export const judgeBody = (
  * it scored below 0.6, 62% were false, where 22% of all were.
  */
 const sufficiencyQuestionWith = (fields: ReturnType<typeof ruleFields>, readState: ReadState) => {
-  const keys = Object.keys(readState).filter((key) => key !== "code");
+  const keys = Object.keys(readState).filter((key) => key !== "code" && key !== "__comment");
   const context =
     keys.length === 0 ? undefined : ["`code`", ...keys.map((key) => `\`${key}\``)].join(" and ");
   return {
@@ -547,6 +574,43 @@ export const fits = (lines: Lines, rules: Rules, readState: ReadState = {}): boo
 /** A request to Jev, its questions typed as `Q`: `Question`, as adhere asks them, or anything an eval arm asks. */
 export type Body<Q = unknown> = SystemOneRequest<Q>;
 
+type RequestPayload =
+  | Body<SystemOneQuestion>
+  | { readonly judge: Body<SystemOneQuestion>; readonly locate: Body<SystemOneQuestion> };
+
+const traceBody = (body: Body<SystemOneQuestion>) => ({
+  ...body,
+  state: { code: body.state.code, ...body.state },
+  questions: Record.map(body.questions, (question, id) =>
+    question.type === "choice" && /^(start|end):/.test(id)
+      ? { ...question, criteria: undefined }
+      : question,
+  ),
+});
+
+/** Debug/Trace put target code first and omit line-option copies; All retains the complete request. */
+export const logRequestPayload = (
+  message: string,
+  payload: () => RequestPayload,
+  level: "Debug" | "Trace" = "Trace",
+): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const minimum = yield* References.MinimumLogLevel;
+    if (LogLevel.isGreaterThan(minimum, level)) return;
+    const full = payload();
+    const visible =
+      minimum === "All"
+        ? full
+        : "questions" in full
+          ? traceBody(full)
+          : { judge: traceBody(full.judge), locate: traceBody(full.locate) };
+    // Consume escaped backslashes first so source literals such as "\\n" remain literals.
+    const text = JSON.stringify(visible, null, 2).replace(/\\\\|\\[nt]/g, (escaped) =>
+      escaped === "\\n" ? "\n" : escaped === "\\t" ? "\t" : escaped,
+    );
+    yield* (level === "Debug" ? Effect.logDebug : Effect.logTrace)(`${message}\n${text}`);
+  });
+
 /**
  * A body as requests Jev can take: its questions in order, with a new
  * request whenever the next question would not fit beside the state and