@pmelab/gtd 59.0.0 → 60.0.0

package/src/cli/Help.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest"
+import { closest, definition, wrap } from "./Help.js"
+
+describe("wrap", () => {
+  it("fills lines up to the width, never past it", () => {
+    expect(wrap("aaa bbb ccc ddd", 7)).toEqual(["aaa bbb", "ccc ddd"])
+  })
+
+  it("keeps a code span on one line", () => {
+    expect(wrap("run `gtd help land` now", 12)).toEqual(["run", "`gtd help land`", "now"])
+  })
+
+  it("keeps an indented example paragraph verbatim", () => {
+    expect(wrap('text\n\n  s=$(x) && sh -c "$s"', 4)).toEqual([
+      "text",
+      "",
+      '  s=$(x) && sh -c "$s"',
+    ])
+  })
+})
+
+describe("definition", () => {
+  it("puts a short term beside its description", () => {
+    expect(definition("next", "Print it", 10)).toEqual(["  next    Print it"])
+  })
+
+  it("gives a term too wide for the column a line of its own", () => {
+    expect(definition("a-very-long-term", "Text", 10)).toEqual([
+      "  a-very-long-term",
+      "          Text",
+    ])
+  })
+})
+
+describe("closest", () => {
+  const commands = ["next", "land", "history", "help"]
+
+  it("finds a dropped letter and a swapped pair", () => {
+    expect(closest("nxt", commands)).toBe("next")
+    expect(closest("lnad", commands)).toBe("land")
+    expect(closest("histroy", commands)).toBe("history")
+  })
+
+  it("suggests nothing for a word unlike every candidate", () => {
+    expect(closest("frobnicate", commands)).toBeUndefined()
+  })
+})

package/src/cli/Help.ts

@@ -0,0 +1,70 @@
+const HELP_WIDTH = 80
+
+/**
+ * Word-wraps prose to `width` columns, every line prefixed by `indent`.
+ * Paragraphs are separated by a blank line; a paragraph whose lines start
+ * with two spaces is an example and is kept verbatim (indented, not wrapped).
+ */
+const wrapParagraph = (paragraph: string, width: number, indent: string): string[] => {
+  const lines: string[] = []
+  let line = ""
+  // A `code span` is one word: a command split across lines can't be copied.
+  for (const word of paragraph.match(/\S*`[^`]*`\S*|\S+/g) ?? []) {
+    if (line !== "" && indent.length + line.length + 1 + word.length > width) {
+      lines.push(indent + line)
+      line = word
+    } else {
+      line = line === "" ? word : `${line} ${word}`
+    }
+  }
+  if (line !== "") lines.push(indent + line)
+  return lines
+}
+
+export const wrap = (text: string, width = HELP_WIDTH, indent = ""): string[] =>
+  text
+    .split("\n\n")
+    .flatMap((paragraph, i) => [
+      ...(i > 0 ? [""] : []),
+      ...(paragraph.startsWith("  ")
+        ? paragraph.split("\n").map((l) => indent + l)
+        : wrapParagraph(paragraph, width, indent)),
+    ])
+
+/** `term` and `description` side by side, the description wrapped into the column after `column`; a term too wide for it gets a line of its own. */
+export const definition = (term: string, description: string, column: number): string[] => {
+  const cell = `  ${term}`
+  const body = wrap(description, HELP_WIDTH, " ".repeat(column))
+  if (cell.length + 1 >= column) return [cell, ...body]
+  const [first = "", ...rest] = body
+  return [cell.padEnd(column) + first.trimStart(), ...rest]
+}
+
+/** Optimal-string-alignment distance: Levenshtein plus adjacent transpositions, so `nxet` is one edit from `next`. */
+const distance = (a: string, b: string): number => {
+  const d: number[][] = Array.from({ length: a.length + 1 }, (_, i) =>
+    Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+  )
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      let best = Math.min(d[i - 1]![j]! + 1, d[i]![j - 1]! + 1, d[i - 1]![j - 1]! + cost)
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        best = Math.min(best, d[i - 2]![j - 2]! + 1)
+      }
+      d[i]![j] = best
+    }
+  }
+  return d[a.length]![b.length]!
+}
+
+/** The candidate closest to `word`, when it is a plausible typo of it: at most one edit per three characters, and at least one. */
+export const closest = (word: string, candidates: readonly string[]): string | undefined => {
+  const limit = Math.max(1, Math.floor(word.length / 3))
+  let best: { readonly name: string; readonly d: number } | undefined
+  for (const name of candidates) {
+    const d = distance(word, name)
+    if (d <= limit && (best === undefined || d < best.d)) best = { name, d }
+  }
+  return best?.name
+}

package/src/cli/History.ts

@@ -3,7 +3,13 @@ import { historyTrail } from "../edge/index.js"
 import { combinedScript, fetchHistoryRefs } from "../emit/index.js"
 import { GitService, Narrator, PROCESS_HISTORY_PREFIX } from "../platform/index.js"
 import { parseCommitMessage } from "../replay/index.js"
-import { writeJson, type ArtifactOut, type CommandRequirements, type JsonMode } from "./Output.js"
+import {
+  writeJson,
+  writeScript,
+  type ArtifactOut,
+  type CommandRequirements,
+  type JsonMode,
+} from "./Output.js"
 
 export interface HistoryEntry {
   readonly ref: string
@@ -138,8 +144,7 @@ export const runHistoryShowCommand = (
 /** Prints the script and never runs git: gtd's promise that it only decides and prints. */
 export const runHistoryFetchCommand = (
   remote: string,
+  json: JsonMode,
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> =>
-  Effect.sync(() => {
-    out.write(`${combinedScript(fetchHistoryRefs(remote), "")}\n`)
-  })
+  writeScript(json, out, `${combinedScript(fetchHistoryRefs(remote), "")}\n`)

package/src/cli/Judges.ts

@@ -2,7 +2,7 @@ import { Effect, Option } from "effect"
 import { answered, numeric } from "../flows/index.js"
 import { GitService } from "../platform/index.js"
 import { parseCommitMessage, type JudgeVerdict } from "../replay/index.js"
-import { headingSectionBodies } from "../steering/index.js"
+import { headingSectionBodies } from "../steering/internal.js"
 import { selectHistoryEntries, type HistoryEntry } from "./History.js"
 import { printable } from "./Metrics.js"
 import { writeJson, type ArtifactOut, type CommandRequirements, type JsonMode } from "./Output.js"

package/src/cli/Output.test.ts

@@ -0,0 +1,35 @@
+import { Effect, Exit } from "effect"
+import { describe, expect, it } from "vitest"
+import { WIRE_SCHEMA } from "../wire/index.js"
+import { writeScript, type JsonMode } from "./Output.js"
+
+const run = (json: JsonMode, script: string, plain?: string) => {
+  let written = ""
+  const out = { write: (chunk: string) => (written += chunk), flush: () => {} }
+  const exit = Effect.runSyncExit(writeScript(json, out, script, plain))
+  return { exit, written }
+}
+
+describe("writeScript", () => {
+  it("plain prints the script, or the plain text when given", () => {
+    expect(run({ kind: "off" }, "git reset\n").written).toBe("git reset\n")
+    expect(run({ kind: "off" }, "", "nothing to do\n").written).toBe("nothing to do\n")
+  })
+
+  it("--json prints { schema, script }, the script ending in exactly one newline", () => {
+    expect(JSON.parse(run({ kind: "document" }, "git reset\n\n").written)).toEqual({
+      schema: WIRE_SCHEMA,
+      script: "git reset\n",
+    })
+    expect(JSON.parse(run({ kind: "document" }, "", "nothing\n").written)).toEqual({
+      schema: WIRE_SCHEMA,
+      script: "",
+    })
+  })
+
+  it("--json=script prints the script alone; an unknown path fails", () => {
+    expect(run({ kind: "select", path: "script" }, "git reset").written).toBe("git reset\n\n")
+    expect(run({ kind: "select", path: "schema" }, "x").written).toBe(`${WIRE_SCHEMA}\n`)
+    expect(Exit.isFailure(run({ kind: "select", path: "nope" }, "x").exit)).toBe(true)
+  })
+})

package/src/cli/Output.ts

@@ -1,6 +1,12 @@
 import { Effect } from "effect"
 import { CommandRunner, GitService, Host, Narrator, Workspace } from "../platform/index.js"
-import { selectPath, type EXIT_OK, type EXIT_STRAYS_FOUND } from "../wire/index.js"
+import {
+  renderScriptJson,
+  scriptFields,
+  selectPath,
+  type EXIT_OK,
+  type EXIT_STRAYS_FOUND,
+} from "../wire/index.js"
 import { ConfigDiscovery, ConfigService } from "../workflow/index.js"
 import type { ToolCommands } from "./ToolCommands.js"
 
@@ -81,3 +87,27 @@ export const writeJson = (
     else yield* writeSelection(out, document, json.path)
     return true
   })
+
+/** Exactly one trailing newline: a script embedded in a `--json` document is never re-normalized at its tail. */
+export const normalizeScriptNewline = (script: string): string =>
+  script.length === 0 ? script : `${script.replace(/\n+$/, "")}\n`
+
+/**
+ * A script-printing command's output: the script itself (or `plain`, when
+ * there is none to run), `{ schema, script }` under `--json`, or one field.
+ */
+export const writeScript = (
+  json: JsonMode,
+  out: ArtifactOut,
+  script: string,
+  plain: string = script,
+): Effect.Effect<void, Error> =>
+  Effect.gen(function* () {
+    if (json.kind === "off") {
+      out.write(plain)
+      return
+    }
+    const fields = scriptFields(normalizeScriptNewline(script))
+    if (json.kind === "document") out.write(renderScriptJson(fields))
+    else yield* writeSelection(out, fields, json.path)
+  })