@pmelab/gtd 23.2.0 → 24.1.0

package/src/workflow/compile.ts

@@ -0,0 +1,56 @@
+import { seededValidateCommand } from "./SteeringFormats.js"
+import { BUILT_IN_MODE_NAMES } from "../steering/index.js"
+import type { ModeDef } from "./Workflow.js"
+import { configProblems, type GtdConfig, type UiSettings } from "../flows/index.js"
+import type { Diagnostic } from "./Diagnostic.js"
+
+export interface CompiledConfig {
+  /** The built-in modes (qa/review, with gtd's own validators) merged with `config.modes`, per half. */
+  readonly modes: Record<string, ModeDef>
+  readonly ui?: UiSettings
+  readonly skills: Readonly<Record<string, readonly string[]>>
+  readonly access: GtdConfig["access"] & {}
+  readonly diagnostics: readonly Diagnostic[]
+}
+
+/**
+ * A `gtd.config.ts` `config` export (or its absence), checked and compiled. A
+ * malformed export compiles to nothing beyond the built-in modes, with every
+ * problem reported at `origin`.
+ */
+export const compileConfig = (value: unknown, origin: string): CompiledConfig => {
+  const seeded: Record<string, ModeDef> = Object.fromEntries(
+    BUILT_IN_MODE_NAMES.map((name) => [name, { validate: seededValidateCommand(name) }]),
+  )
+  const problems = value === undefined ? [] : configProblems(value)
+  if (problems.length > 0) {
+    return {
+      modes: seeded,
+      skills: {},
+      access: {},
+      diagnostics: problems.map(({ path, message }) => ({
+        severity: "error",
+        path: ["config", ...path],
+        message,
+        origin,
+      })),
+    }
+  }
+  const config = (value ?? {}) as GtdConfig
+  // Per half: a `format:` alone, or a half left `undefined` (an unset
+  // `process.env.X`), keeps a built-in mode's own validator.
+  const modes = { ...seeded }
+  for (const [name, entry] of Object.entries(config.modes ?? {}))
+    modes[name] = {
+      ...modes[name],
+      ...Object.fromEntries(Object.entries(entry).filter(([, command]) => command !== undefined)),
+    }
+  return {
+    modes,
+    ...(config.ui !== undefined ? { ui: config.ui } : {}),
+    // Null prototype: a `__proto__` key must stay an ordinary (reportable) entry.
+    skills: Object.assign(Object.create(null), config.skills),
+    access: Object.assign(Object.create(null), config.access),
+    diagnostics: [],
+  }
+}

package/src/workflow/discovery.ts

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { Context, Effect, Layer } from "effect"
+
+/** The workflow module found on the cwd→home walk, with its source. */
+export interface WorkflowModule {
+  readonly filepath: string
+  readonly source: string
+}
+
+/** A leftover rc file, and whether the user running gtd owns it — and so can delete it. */
+interface LegacyRcFile {
+  readonly path: string
+  readonly owned: boolean
+}
+
+interface ConfigDiscoveryOps {
+  /** Every removed `.gtdrc`-family file on the `root`→`home` walk and in `home` itself, innermost first. */
+  readonly legacyRcFiles: (
+    root: string,
+    home: string,
+  ) => Effect.Effect<readonly LegacyRcFile[], Error>
+  /** The innermost `gtd.config.ts` walking `root` up through `home`, if any. */
+  readonly workflowModule: (
+    root: string,
+    home: string,
+  ) => Effect.Effect<WorkflowModule | undefined, Error>
+}
+
+export const WORKFLOW_MODULE = "gtd.config.ts"
+
+/**
+ * The file names gtd read repository settings from before `gtd.config.ts` took
+ * them over. Still looked for, only to refuse them: a leftover one would
+ * otherwise be silently ignored. Shared with the in-memory counterpart in
+ * `src/testkit/Layers.ts`, so both tiers refuse the same names.
+ */
+export const LEGACY_RC_FILES = [
+  ".gtdrc",
+  ".gtdrc.json",
+  ".gtdrc.yaml",
+  ".gtdrc.yml",
+  "gtd.config.json",
+  "gtd.config.yaml",
+]
+
+/** The directories searched for a leftover rc file: the walk, plus `home` when the walk misses it. */
+export const legacyRcDirs = (root: string, home: string): readonly string[] => {
+  const chain = walkUp(root, home)
+  return chain.includes(home) ? chain : [...chain, home]
+}
+
+const legacyRcFileAt = (path: string): LegacyRcFile | undefined => {
+  try {
+    const stat = statSync(path)
+    if (!stat.isFile()) return undefined
+    // Above home, a shared directory (`/tmp`) can hold another user's file.
+    return { path, owned: process.getuid === undefined || stat.uid === process.getuid() }
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Enumerate the directory chain from `from` walking UP. Stops after including
+ * the user's home dir (inclusive, when it is an ancestor) or after reaching the
+ * filesystem root — whichever comes first. Returned innermost→outermost.
+ * Exported (via the barrel) for the same reason `SEARCH_PLACES` is — one
+ * shared implementation, not a second copy in `src/testkit/Layers.ts` that
+ * could silently diverge.
+ */
+export const walkUp = (from: string, home: string): ReadonlyArray<string> => {
+  const chain: Array<string> = []
+  let dir = from
+  while (true) {
+    chain.push(dir)
+    if (dir === home) break
+    const parent = dirname(dir)
+    if (parent === dir) break // filesystem root
+    dir = parent
+  }
+  return chain
+}
+
+const legacyRcFiles = (root: string, home: string): Effect.Effect<readonly LegacyRcFile[], Error> =>
+  Effect.sync(() =>
+    legacyRcDirs(root, home).flatMap((dir) =>
+      LEGACY_RC_FILES.flatMap((name) => legacyRcFileAt(join(dir, name)) ?? []),
+    ),
+  )
+
+const workflowModule = (
+  root: string,
+  home: string,
+): Effect.Effect<WorkflowModule | undefined, Error> =>
+  Effect.try({
+    try: () => {
+      for (const dir of walkUp(root, home)) {
+        const filepath = join(dir, WORKFLOW_MODULE)
+        if (existsSync(filepath)) return { filepath, source: readFileSync(filepath, "utf8") }
+      }
+      return undefined
+    },
+    catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+  })
+
+/**
+ * The discovery seam — a `Context.Tag`, not part of `WorkflowFiles` (that
+ * port is a plain sync record for `compileWorkflow`'s own content-file-ref
+ * reads; discovery is effectful and environment-dependent: `.Live` reads
+ * REAL disk, so an `@inmem` scenario's fake
+ * `Workspace` — a pure in-memory `Map`, no real files anywhere on disk —
+ * cannot back it. `src/testkit/Layers.ts` provides the in-memory
+ * counterpart instead, mirroring how `Workspace`/`Host`/`GitService` already
+ * each have a production and a fake layer behind one Tag.
+ */
+export class ConfigDiscovery extends Context.Tag("ConfigDiscovery")<
+  ConfigDiscovery,
+  ConfigDiscoveryOps
+>() {
+  static Live = Layer.succeed(ConfigDiscovery, { legacyRcFiles, workflowModule })
+}

package/src/workflow/fingerprint.test.ts

@@ -0,0 +1,52 @@
+import { mkdirSync, mkdtempSync, realpathSync, symlinkSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+import { changedConfigFiles, configFingerprint } from "./fingerprint.js"
+
+describe("the config fingerprint", () => {
+  it("hashes each file under its root-relative path, skipping one that cannot be read", () => {
+    const root = mkdtempSync(join(tmpdir(), "gtd-fingerprint-"))
+    mkdirSync(join(root, "lib"))
+    writeFileSync(join(root, "gtd.config.ts"), "export default 1\n")
+    writeFileSync(join(root, "lib", "flow.ts"), "export const a = 1\n")
+
+    const fingerprint = configFingerprint(
+      [join(root, "gtd.config.ts"), join(root, "lib", "flow.ts"), join(root, "gone.ts")],
+      root,
+    )
+
+    expect(Object.keys(fingerprint).sort()).toEqual(["gtd.config.ts", "lib/flow.ts"])
+    expect(fingerprint["gtd.config.ts"]).toMatch(/^[0-9a-f]{16}$/)
+    writeFileSync(join(root, "lib", "flow.ts"), "export const a = 2\n")
+    expect(
+      changedConfigFiles(
+        fingerprint,
+        configFingerprint([join(root, "gtd.config.ts"), join(root, "lib", "flow.ts")], root),
+      ),
+    ).toEqual(["lib/flow.ts"])
+  })
+
+  it("relates a file reported by its real path to a root reached through a symlink", () => {
+    const real = mkdtempSync(join(tmpdir(), "gtd-fingerprint-"))
+    writeFileSync(join(real, "gtd.config.ts"), "export default 1\n")
+    const link = join(mkdtempSync(join(tmpdir(), "gtd-fingerprint-link-")), "repo")
+    symlinkSync(real, link)
+
+    expect(
+      Object.keys(configFingerprint([join(realpathSync(real), "gtd.config.ts")], link)),
+    ).toEqual(["gtd.config.ts"])
+  })
+
+  it("never records a path with a control character", () => {
+    const root = mkdtempSync(join(tmpdir(), "gtd-fingerprint-"))
+    writeFileSync(join(root, "a\x1b.ts"), "export const a = 1\n")
+
+    expect(configFingerprint([join(root, "a\x1b.ts")], root)).toEqual({})
+  })
+
+  it("names a file only one side has as changed", () => {
+    expect(changedConfigFiles({ a: "1", b: "2" }, { a: "1", c: "3" })).toEqual(["b", "c"])
+    expect(changedConfigFiles({ a: "1" }, { a: "1" })).toEqual([])
+  })
+})

package/src/workflow/fingerprint.ts

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto"
+import { readFileSync, realpathSync } from "node:fs"
+import { relative, sep } from "node:path"
+
+/** Path (relative to `root`) → content hash of every file a config load touched. */
+export type ConfigFingerprint = Readonly<Record<string, string>>
+
+const HASH_LENGTH = 16
+
+// A path the trailer cannot carry printably is never recorded, so it can never
+// reach a terminal from history.
+// eslint-disable-next-line no-control-regex -- the control range IS the point
+const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f]/
+
+export const contentHash = (content: string | Buffer): string =>
+  createHash("sha256").update(content).digest("hex").slice(0, HASH_LENGTH)
+
+const realOr = (path: string): string => {
+  try {
+    return realpathSync(path)
+  } catch {
+    return path
+  }
+}
+
+// An unreadable file is left out rather than failing: the fingerprint only
+// feeds a warning, and the load that listed the file already read it.
+// Paths are real paths: a loader may report `/private/var/…` for a root
+// reached through the `/var` symlink, and the two must still relate.
+export const configFingerprint = (files: readonly string[], root: string): ConfigFingerprint => {
+  const fingerprint: Record<string, string> = {}
+  const realRoot = realOr(root)
+  for (const file of files) {
+    const path = relative(realRoot, realOr(file)).split(sep).join("/")
+    if (CONTROL_CHARACTER.test(path)) continue
+    let content: Buffer
+    try {
+      content = readFileSync(file)
+    } catch {
+      continue
+    }
+    fingerprint[path] = contentHash(content)
+  }
+  return fingerprint
+}
+
+export const changedConfigFiles = (
+  recorded: ConfigFingerprint,
+  current: ConfigFingerprint,
+): readonly string[] =>
+  [...new Set([...Object.keys(recorded), ...Object.keys(current)])]
+    .filter((path) => recorded[path] !== current[path])
+    .sort()

package/src/workflow/index.ts

@@ -0,0 +1,33 @@
+export {
+  load,
+  refuseLegacyRc,
+  ConfigService,
+  type ConfigOperations,
+  type ResolvedWorkflow,
+} from "./load.js"
+export {
+  ConfigDiscovery,
+  LEGACY_RC_FILES,
+  legacyRcDirs,
+  WORKFLOW_MODULE,
+  walkUp,
+} from "./discovery.js"
+export { formatDiagnostic } from "./Diagnostic.js"
+export { resolveVars, multilineSetting, isSettingName, SETTING_NAME_RULE } from "./vars.js"
+export { resolveScopeAccess, resolveScopeSkills } from "./skills.js"
+export { seededValidateCommand, isSeededValidateCommand } from "./SteeringFormats.js"
+export {
+  type ChangeStatus,
+  type PendingChange,
+  type StepDef,
+  type WorkflowDefinition,
+  knownModes,
+  type StateMode,
+  type StateName,
+} from "./Workflow.js"
+export {
+  changedConfigFiles,
+  configFingerprint,
+  contentHash,
+  type ConfigFingerprint,
+} from "./fingerprint.js"