refactor(errors): neverthrow Results with typed problems across validation, config, fold, flows, and the library

.github/scripts/changed-sections.ts

@@ -77,6 +77,7 @@ export const ALL_SELECTING_PREFIXES = [
   "src/plain-data.ts",
   "src/private-open.ts",
   "src/private.ts",
+  "src/problem.ts",
   "src/schema.ts",
   "src/types.ts",
   "test/e2e/",

.github/scripts/gen-action-docs.ts

@@ -6,9 +6,9 @@
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, posix } from "node:path";
-import type { InputDecl } from "../../src/action/inputs.js";
-import { INPUT_DECLS } from "../../src/action/inputs.js";
 import { OUTPUT_DECLS } from "../../src/action/io.js";
+import type { InputDecl } from "../../src/flows/inputs.js";
+import { INPUT_DECLS } from "../../src/flows/inputs.js";
 import { UNDECLARED_POLICY_SECTIONS, type UndeclaredPolicySection } from "../../src/schema.js";
 import { overrideAdviceLevel } from "../../src/sections/contract/errors.js";
 import type { SectionMeta } from "../../src/sections/contract/module.js";

action.yml

@@ -6,7 +6,7 @@ branding:
   color: blue
 
 inputs:
-  # BEGIN GENERATED: action-inputs (bun run build:action-docs; edit src/action/inputs.ts)
+  # BEGIN GENERATED: action-inputs (bun run build:action-docs; edit src/flows/inputs.ts)
   token:
     description: >-
       Token used for the API calls. Most sections need a fine-grained PAT with

architecture.yml

@@ -18,6 +18,7 @@ layers:
   report: [src/report/]
   schema: [src/schema.ts]
   io: [src/io.ts]
+  problem: [src/problem.ts]
   types: [src/types.ts]
   plain-data: [src/plain-data.ts]
   private: [src/private.ts, src/private-open.ts]
@@ -34,12 +35,13 @@ exclude:
 edges:
   main: [action]
   action: [library]
-  library: [discovery, engine, flows, github, io, report, schema, sections, types]
-  flows: [discovery, engine, github, io, private, report, schema]
-  engine: [discovery, github, io, plain-data, schema, sections, types]
+  library: [discovery, engine, flows, github, io, problem, report, schema, sections, types]
+  flows: [discovery, engine, github, io, plain-data, private, problem, report, schema, types]
+  engine: [discovery, github, io, plain-data, problem, schema, sections, types]
   sections: [discovery, engine, github, schema, types, upstream-gaps]
   github: [io, plain-data]
-  discovery: [github, private]
-  report: [discovery, engine, github, io, private, schema, sections, types]
+  discovery: [github, private, problem]
+  report: [discovery, engine, github, io, private, problem, schema, sections, types]
+  problem: [plain-data, schema]
   schema: [sections, types]
   upstream-gaps: [types]

docs/reference/architecture.md

@@ -239,6 +239,7 @@ graph TD
   report["src/report/"]
   schema["src/schema.ts"]
   io["src/io.ts"]
+  problem["src/problem.ts"]
   types["src/types.ts"]
   plain_data["src/plain-data.ts"]
   private["src/private.ts<br>src/private-open.ts"]
@@ -250,6 +251,7 @@ graph TD
   library --> flows
   library --> github
   library --> io
+  library --> problem
   library --> report
   library --> schema
   library --> sections
@@ -258,13 +260,17 @@ graph TD
   flows --> engine
   flows --> github
   flows --> io
+  flows --> plain_data
   flows --> private
+  flows --> problem
   flows --> report
   flows --> schema
+  flows --> types
   engine --> discovery
   engine --> github
   engine --> io
   engine --> plain_data
+  engine --> problem
   engine --> schema
   engine --> sections
   engine --> types
@@ -278,14 +284,18 @@ graph TD
   github --> plain_data
   discovery --> github
   discovery --> private
+  discovery --> problem
   report --> discovery
   report --> engine
   report --> github
   report --> io
   report --> private
+  report --> problem
   report --> schema
   report --> sections
   report --> types
+  problem --> plain_data
+  problem --> schema
   schema --> sections
   schema --> types
   upstream_gaps --> types

docs/reference/inputs.md

@@ -8,7 +8,7 @@ Every `with:` input the action accepts, and the outputs it sets for the steps af
 
 ## Inputs
 
-<!-- BEGIN GENERATED: inputs-table (bun run build:action-docs; edit src/action/inputs.ts) -->
+<!-- BEGIN GENERATED: inputs-table (bun run build:action-docs; edit src/flows/inputs.ts) -->
 | Input | Default | Meaning |
 |---|---|---|
 | `token` | `github.token` | Token for the API calls (see [Token permissions](permissions.md)) |

package.json

@@ -35,6 +35,7 @@
     "@octokit/plugin-throttling": "11.0.5",
     "age-encryption": "0.3.1",
     "bottleneck": "2.19.5",
+    "neverthrow": "8.2.0",
     "yaml": "2.9.0",
     "zod": "4.5.4"
   },