agent-simple-english 0.1.0 → 0.2.0

package/src/cli/hook.ts

@@ -6,12 +6,18 @@ import { blankCommitMetadata, findCommitInvocations } from "../adapter/commit-me
 import { formatViolations } from "../adapter/feedback.ts"
 import { ruleSummary } from "../adapter/rule-summary.ts"
 import { loadConfig } from "../config/load.ts"
-import { loadDictionary } from "../dictionary/load.ts"
+import { loadConfiguredDictionary } from "../dictionary/configured.ts"
+import { loadRuleData } from "../dictionary/load.ts"
 import { classifyPath } from "../engine/kinds.ts"
 import { lint } from "../engine/lint.ts"
 import type { Tagger } from "../engine/tagger.ts"
-import type { LintOptions, Violation } from "../engine/types.ts"
+import type { LintKind, LintOptions, ReportViolation } from "../engine/types.ts"
 import { TaggerService } from "../tagger/wink.ts"
+import {
+  type ObservationDraft,
+  type ObservationEvent,
+  appendObservation,
+} from "./observation-log.ts"
 import {
   consumePendingFeedback,
   getSessionControl,
@@ -209,12 +215,12 @@ function addContext(
 function nonBlockingError(message: string): HookError {
   return {
     continue: true,
-    systemMessage: `STE hook error: ${message}. The event is allowed.`,
+    systemMessage: `Writing-rule hook error: ${message}. The event is allowed.`,
   }
 }
 
 function nonBlockingWarning(message: string): HookDecision {
-  return allow([`STE hook warning: ${message}. The event is allowed.`])
+  return allow([`Writing-rule hook warning: ${message}. The event is allowed.`])
 }
 
 export function hookInternalFailure(cause: Cause.Cause<unknown>): HookOutput {
@@ -511,19 +517,24 @@ const readSessionControl = (sessionId: string) =>
     catch: (cause) => new Error(`cannot read session state: ${cause}`),
   })
 
-const loadLintOptions = (cwd: string, tagger: Tagger) => {
-  const dictionaryPath = process.env.SIMPLE_ENGLISH_DICTIONARY
-  return Effect.all({
-    config: loadConfig(undefined, cwd),
-    dictionary: loadDictionary(
-      dictionaryPath === undefined ? undefined : resolve(cwd, dictionaryPath),
-    ),
-  }).pipe(Effect.map(({ config, dictionary }): LintOptions => ({ ...config, dictionary, tagger })))
-}
+const loadLintOptions = (cwd: string, tagger: Tagger) =>
+  Effect.gen(function* () {
+    const config = yield* loadConfig(undefined, cwd)
+    const dictionaryPath = process.env.SIMPLE_ENGLISH_DICTIONARY
+    const { dictionary, ruleData } = yield* Effect.all({
+      dictionary: loadConfiguredDictionary(
+        config,
+        cwd,
+        dictionaryPath === undefined ? undefined : resolve(cwd, dictionaryPath),
+      ),
+      ruleData: loadRuleData(config.ruleDataExtensions, cwd),
+    })
+    return { ...config, dictionary, ruleData, tagger } satisfies LintOptions
+  })
 
-function splitViolations(violations: readonly Violation[]): {
-  readonly hard: Violation[]
-  readonly soft: Violation[]
+function splitViolations(violations: readonly ReportViolation[]): {
+  readonly hard: ReportViolation[]
+  readonly soft: ReportViolation[]
 } {
   return {
     hard: violations.filter((violation) => violation.severity === "hard"),
@@ -531,13 +542,48 @@ function splitViolations(violations: readonly Violation[]): {
   }
 }
 
+type EvaluationObservation = Omit<ObservationDraft, "sessionId" | "cwd">
+
+interface HookEvaluation {
+  readonly output: HookOutput
+  readonly observation?: EvaluationObservation
+}
+
+function evaluated(
+  output: HookOutput,
+  event: ObservationEvent,
+  kind: LintKind,
+  text: string,
+  violations: readonly ReportViolation[],
+  path?: string,
+): HookEvaluation {
+  const preToolDenied =
+    "hookSpecificOutput" in output &&
+    output.hookSpecificOutput !== undefined &&
+    "permissionDecision" in output.hookSpecificOutput &&
+    output.hookSpecificOutput.permissionDecision === "deny"
+  const decision =
+    ("decision" in output && output.decision === "block") || preToolDenied ? "deny" : "allow"
+  return {
+    output,
+    observation: {
+      event,
+      kind,
+      text,
+      violations,
+      decision,
+      ...(path === undefined ? {} : { path }),
+    },
+  }
+}
+
 function textDecision(
   operation: "write" | "edit",
   path: string,
   text: string,
   options: LintOptions,
   previousText?: string,
-): HookDecision {
+): HookEvaluation {
   const classification = classifyPath(path)
   const report = lint(classification.kind, text, {
     ...options,
@@ -545,68 +591,99 @@ function textDecision(
     previousText,
   })
   const { hard, soft } = splitViolations(report.violations)
-  if (hard.length > 0) {
-    return deny(formatViolations(path, `STE blocked ${operation} for`, hard))
-  }
-  return allow(soft.length === 0 ? [] : [formatViolations(path, "STE warnings for", soft)])
+  const output =
+    hard.length > 0
+      ? deny(formatViolations(path, `Writing rules blocked ${operation} for`, hard))
+      : allow(soft.length === 0 ? [] : [formatViolations(path, "Writing-rule warnings for", soft)])
+  return evaluated(output, operation, classification.kind, text, report.violations, path)
 }
 
-function evaluateReply(event: StopEvent, tagger: Tagger): Effect.Effect<HookOutput, Error> {
+function evaluateReply(event: StopEvent, tagger: Tagger): Effect.Effect<HookEvaluation, Error> {
   return Effect.gen(function* () {
     const reply = yield* event.lastAssistantMessage === undefined
       ? readAssistantReply(event.transcriptPath)
       : readEventAssistantReply(event.lastAssistantMessage, event.transcriptPath)
     if (yield* replyWasProcessed(event.sessionId, reply.identity)) {
-      return {} as Record<string, never>
+      return { output: {} as Record<string, never> }
     }
     const options = yield* loadLintOptions(event.cwd, tagger)
-    const hard = lint("prose-file", reply.text, options).violations.filter(
-      (violation) => violation.severity === "hard",
-    )
+    const violations = lint("prose-file", reply.text, options).violations
+    const hard = violations.filter((violation) => violation.severity === "hard")
     const feedback =
       hard.length === 0
         ? undefined
-        : formatViolations("assistant reply", "STE reply feedback for", hard)
+        : formatViolations("assistant reply", "Writing-rule reply feedback for", hard)
     const currentControl = yield* updateReplyFeedback(event.sessionId, reply.identity, feedback)
-    if (
+    const output: HookOutput =
       currentControl === undefined ||
       !currentControl.strict ||
       event.stopHookActive ||
       hard.length === 0
-    ) {
-      return {} as Record<string, never>
-    }
-    return {
-      decision: "block",
-      reason: formatViolations("assistant reply", "STE blocked reply for", hard),
-    }
+        ? ({} as Record<string, never>)
+        : {
+            decision: "block",
+            reason: formatViolations("assistant reply", "Writing rules blocked reply for", hard),
+          }
+    return evaluated(output, "reply", "prose-file", reply.text, violations)
+  })
+}
+
+function restoreCommitSnippets(
+  message: string,
+  prepared: string,
+  violations: readonly ReportViolation[],
+): ReportViolation[] {
+  return violations.map((violation) => {
+    const offset = prepared.indexOf(violation.snippet)
+    return offset === -1
+      ? violation
+      : { ...violation, snippet: message.slice(offset, offset + violation.snippet.length) }
   })
 }
 
-function evaluateEvent(event: PreToolUseEvent, tagger: Tagger): Effect.Effect<HookDecision, Error> {
+function evaluateEvent(
+  event: PreToolUseEvent,
+  tagger: Tagger,
+): Effect.Effect<HookEvaluation, Error> {
   if (event.toolName === "Bash") {
     const invocations = findCommitInvocations(event.command)
-    if (invocations.length === 0) return Effect.succeed(allow())
+    if (invocations.length === 0) return Effect.succeed({ output: allow() })
     if (invocations.some((invocation) => invocation.requiresExplicitMessage)) {
-      return Effect.succeed(
-        deny(
-          "STE could not check the git commit message. Use git commit with a static -m or --message argument.",
+      return Effect.succeed({
+        output: deny(
+          "Writing rules could not check the git commit message. Use git commit with a static -m or --message argument.",
         ),
-      )
+      })
     }
     return Effect.gen(function* () {
       const options = yield* loadLintOptions(event.cwd, tagger)
-      const violations = invocations.flatMap((invocation) =>
-        invocation.requiresExplicitMessage
-          ? []
-          : lint("commit-message", blankCommitMetadata(invocation.message), options).violations,
+      const messages = invocations.flatMap((invocation) =>
+        invocation.requiresExplicitMessage ? [] : [invocation.message],
       )
+      const violations = messages.flatMap((message) => {
+        const prepared = blankCommitMetadata(message)
+        return restoreCommitSnippets(
+          message,
+          prepared,
+          lint("commit-message", prepared, options).violations,
+        )
+      })
       const { hard, soft } = splitViolations(violations)
-      if (hard.length > 0) {
-        return deny(formatViolations("commit message", "STE blocked commit for", hard))
-      }
-      return allow(
-        soft.length === 0 ? [] : [formatViolations("commit message", "STE warnings for", soft)],
+      const output =
+        hard.length > 0
+          ? deny(formatViolations("commit message", "Writing rules blocked commit for", hard))
+          : allow(
+              soft.length === 0
+                ? []
+                : [formatViolations("commit message", "Writing-rule warnings for", soft)],
+            )
+      return evaluated(
+        output,
+        "commit-message",
+        "commit-message",
+        messages.join("\n\n"),
+        violations,
+        event.cwd,
       )
     })
   }
@@ -623,6 +700,23 @@ function evaluateEvent(event: PreToolUseEvent, tagger: Tagger): Effect.Effect<Ho
   })
 }
 
+function recordEvaluation(event: HookEvent, evaluation: HookEvaluation): Effect.Effect<HookOutput> {
+  const observation = evaluation.observation
+  if (observation === undefined) return Effect.succeed(evaluation.output)
+  return Effect.tryPromise({
+    try: () =>
+      appendObservation({
+        ...observation,
+        sessionId: event.sessionId,
+        cwd: event.cwd,
+      }),
+    catch: () => undefined,
+  }).pipe(
+    Effect.catchAll(() => Effect.void),
+    Effect.as(evaluation.output),
+  )
+}
+
 export function runHookMode(raw: string): Effect.Effect<HookOutput, never, TaggerService> {
   return Effect.try({
     try: () => decodeEvent(raw),
@@ -653,12 +747,14 @@ export function runHookMode(raw: string): Effect.Effect<HookOutput, never, Tagge
             if (event.hookEventName === "Stop") {
               return Effect.gen(function* () {
                 const tagger = yield* TaggerService
-                return yield* evaluateReply(event, tagger)
+                const evaluation = yield* evaluateReply(event, tagger)
+                return yield* recordEvaluation(event, evaluation)
               })
             }
             return Effect.gen(function* () {
               const tagger = yield* TaggerService
-              return yield* evaluateEvent(event, tagger)
+              const evaluation = yield* evaluateEvent(event, tagger)
+              return yield* recordEvaluation(event, evaluation)
             })
           }),
           Effect.catchAll((error) =>

package/src/cli/main.ts

@@ -1,22 +1,38 @@
 #!/usr/bin/env bun
 import { readFile } from "node:fs/promises"
 import { Effect, Either } from "effect"
+import packageManifest from "../../package.json" with { type: "json" }
 import { loadConfig } from "../config/load.ts"
-import { loadDictionary } from "../dictionary/load.ts"
+import { loadConfiguredDictionary } from "../dictionary/configured.ts"
+import { loadRuleData } from "../dictionary/load.ts"
 import { classifyPath } from "../engine/kinds.ts"
 import { lint } from "../engine/lint.ts"
 import type { LintKind, LintReport } from "../engine/types.ts"
 import { TaggerService, WinkTaggerLive } from "../tagger/wink.ts"
 import { hookInternalFailure, runHookMode } from "./hook.ts"
+import { observationStats, reviewObservations } from "./observation-log.ts"
 import { runSessionCommand } from "./session-command.ts"
 
 const KINDS: readonly LintKind[] = ["prose-file", "slash-source", "hash-source", "commit-message"]
 
+const USAGE = `Usage: simple-english [options] [paths...]
+       simple-english observe review
+       simple-english observe stats
+
+Options:
+  --json           Write a JSON report.
+  --config <path>  Use one config file.
+  --kind <kind>    Use one content kind.
+  --help           Print this help.
+  --version        Print the package version.`
+
 interface CliArgs {
   readonly json: boolean
   readonly configPath: string | undefined
   readonly kind: string | undefined
   readonly kindMissingValue: boolean
+  readonly help: boolean
+  readonly version: boolean
   readonly paths: readonly string[]
 }
 
@@ -26,16 +42,20 @@ const parseArgs = (args: readonly string[]): Effect.Effect<CliArgs, Error> =>
     let configPath: string | undefined
     let kind: string | undefined
     let kindMissingValue = false
+    let help = false
+    let version = false
     const paths: string[] = []
     for (let i = 0; i < args.length; i++) {
       const arg = args[i] as string
       if (arg === "--json") {
         json = true
       } else if (arg === "--config") {
-        configPath = args[++i]
-        if (configPath === undefined) {
+        const value = args[i + 1]
+        if (value === undefined || value.startsWith("--")) {
           yield* Effect.fail(new Error("--config requires a file path"))
         }
+        configPath = value
+        i++
       } else if (arg === "--kind") {
         const value = args[i + 1]
         if (value === undefined || value.startsWith("--")) {
@@ -46,13 +66,24 @@ const parseArgs = (args: readonly string[]): Effect.Effect<CliArgs, Error> =>
         }
       } else if (arg.startsWith("--kind=")) {
         kind = arg.slice("--kind=".length)
+      } else if (arg === "--help") {
+        help = true
+      } else if (arg === "--version") {
+        version = true
+      } else if (arg.startsWith("--")) {
+        yield* Effect.fail(new Error(`unknown flag "${arg}"`))
       } else {
         paths.push(arg)
       }
     }
-    return { json, configPath, kind, kindMissingValue, paths }
+    return { json, configPath, kind, kindMissingValue, help, version, paths }
   })
 
+const rejectUnknownFlags = (args: readonly string[]): Effect.Effect<void, Error> => {
+  const flag = args.find((arg) => arg.startsWith("--"))
+  return flag === undefined ? Effect.void : Effect.fail(new Error(`unknown flag "${flag}"`))
+}
+
 const isLintKind = (value: string): value is LintKind =>
   (KINDS as readonly string[]).includes(value)
 
@@ -61,6 +92,7 @@ interface FileViolation {
   readonly ruleId: string
   readonly severity: string
   readonly message: string
+  readonly snippet: string
   readonly suggestions?: readonly string[]
   readonly line: number
   readonly column: number
@@ -130,9 +162,38 @@ const sessionProgram = Effect.gen(function* () {
   return 0
 })
 
+const observeProgram = Effect.gen(function* () {
+  const command = args[1]
+  if (args.length !== 2 || (command !== "review" && command !== "stats")) {
+    return yield* Effect.fail(new Error("Usage: simple-english observe <review|stats>"))
+  }
+  if (command === "review") {
+    yield* Effect.tryPromise({
+      try: () => reviewObservations(),
+      catch: (cause) => new Error(`cannot review observations: ${cause}`),
+    })
+  } else {
+    console.log(
+      yield* Effect.tryPromise({
+        try: () => observationStats(),
+        catch: (cause) => new Error(`cannot read observation stats: ${cause}`),
+      }),
+    )
+  }
+  return 0
+})
+
 const lintProgram = Effect.gen(function* () {
   const tagger = yield* TaggerService
-  const { json, configPath, kind, kindMissingValue, paths } = yield* parseArgs(args)
+  const { json, configPath, kind, kindMissingValue, help, version, paths } = yield* parseArgs(args)
+  if (help) {
+    console.log(USAGE)
+    return 0
+  }
+  if (version) {
+    console.log(packageManifest.version)
+    return 0
+  }
   if (kindMissingValue) {
     return yield* Effect.fail(
       new Error(`--kind requires a value; expected one of: ${KINDS.join(", ")}`),
@@ -145,12 +206,20 @@ const lintProgram = Effect.gen(function* () {
   }
   const config = yield* loadConfig(configPath)
   const loadedDictionary = yield* Effect.either(
-    loadDictionary(process.env.SIMPLE_ENGLISH_DICTIONARY),
+    loadConfiguredDictionary(config, process.cwd(), process.env.SIMPLE_ENGLISH_DICTIONARY),
   )
+  const loadedRuleData = yield* Effect.either(loadRuleData(config.ruleDataExtensions))
+  if (Either.isLeft(loadedDictionary) && config.approvedWordsPath !== undefined) {
+    return yield* Effect.fail(loadedDictionary.left)
+  }
   const dictionary = Either.getOrUndefined(loadedDictionary)
+  const ruleData = Either.getOrUndefined(loadedRuleData)
   if (Either.isLeft(loadedDictionary)) {
     yield* Effect.sync(() => console.error(loadedDictionary.left.message))
   }
+  if (Either.isLeft(loadedRuleData)) {
+    yield* Effect.sync(() => console.error(loadedRuleData.left.message))
+  }
   const inputs =
     paths.length === 0
       ? [{ path: "<stdin>", text: yield* readStdin }]
@@ -164,6 +233,7 @@ const lintProgram = Effect.gen(function* () {
         report: lint(kind ?? classification.kind, text, {
           ...config,
           dictionary,
+          ruleData,
           tagger,
           sourceDialect: classification.sourceDialect,
         }),
@@ -180,10 +250,12 @@ const lintProgram = Effect.gen(function* () {
 
 const program: Effect.Effect<number, Error> =
   args[0] === "hook"
-    ? hookProgram
+    ? rejectUnknownFlags(args.slice(1)).pipe(Effect.andThen(hookProgram))
     : args[0] === "session"
-      ? sessionProgram
-      : lintProgram.pipe(Effect.provide(WinkTaggerLive))
+      ? rejectUnknownFlags(args.slice(1)).pipe(Effect.andThen(sessionProgram))
+      : args[0] === "observe"
+        ? observeProgram
+        : lintProgram.pipe(Effect.provide(WinkTaggerLive))
 
 const handled = program.pipe(
   Effect.catchAll((error) =>