repopo 0.12.0 → 0.14.0

package/esm/policyDefiners/defineCargoPolicy.d.ts

@@ -1,9 +1,9 @@
 import { type Operation } from "effection";
-import type { PolicyArgs, PolicyHandlerResult, PolicyShape } from "../policy.js";
+import type { DefinedConfig, FilePolicyDefinition, PolicyArgs, PolicyResult } from "../policy.js";
 /**
  * A parsed Cargo.toml represented as a record of sections and values.
  *
- * @alpha
+ * @public
  */
 export type CargoToml = Record<string, unknown>;
 /**
@@ -12,13 +12,13 @@ export type CargoToml = Record<string, unknown>;
  * @remarks
  * Receives the parsed TOML content and the standard policy arguments.
  *
- * @alpha
+ * @public
  */
-export type CargoTomlHandler<C> = (toml: CargoToml, args: PolicyArgs<C>) => Operation<PolicyHandlerResult> | Promise<PolicyHandlerResult>;
+export type CargoTomlHandler<C> = (toml: CargoToml, args: PolicyArgs<C>) => Operation<PolicyResult> | Promise<PolicyResult>;
 /**
  * Input arguments for defining a Cargo.toml policy.
  *
- * @alpha
+ * @public
  */
 export interface DefineCargoPolicyArgs<C> {
     /**
@@ -37,6 +37,7 @@ export interface DefineCargoPolicyArgs<C> {
      * Optional default configuration for the policy.
      */
     defaultConfig?: C;
+    requiresConfig?: boolean;
 }
 /**
  * Define a repo policy for Cargo.toml files.
@@ -45,6 +46,9 @@ export interface DefineCargoPolicyArgs<C> {
  * This is a helper function that creates a policy pre-configured to match
  * Cargo.toml files. The handler receives the parsed TOML content.
  *
+ * @param args - Policy metadata, parsed-TOML handler, and optional defaults.
+ * @returns A file policy that reads and parses matching Cargo.toml files.
+ *
  * @example
  * ```typescript
  * const MyCargoPolicy = defineCargoPolicy({
@@ -53,14 +57,26 @@ export interface DefineCargoPolicyArgs<C> {
  *   handler: async (toml, { file }) => {
  *     const pkg = toml.package as Record<string, unknown> | undefined;
  *     if (!pkg?.name) {
- *       return { error: "Missing package name", fixable: false };
+ *       return [{ message: "Missing package name" }];
  *     }
- *     return true;
+ *     return [];
  *   },
  * });
  * ```
  *
- * @alpha
+ * @public
  */
-export declare function defineCargoPolicy<C = undefined>(args: DefineCargoPolicyArgs<C>): PolicyShape<C>;
+export declare function defineCargoPolicy<C = void>(args: DefineCargoPolicyArgs<C> & {
+    defaultConfig: DefinedConfig<C>;
+}): FilePolicyDefinition<C> & {
+    defaultConfig: DefinedConfig<C>;
+};
+/** Define a Cargo policy that requires explicit configuration. @public */
+export declare function defineCargoPolicy<C = void>(args: DefineCargoPolicyArgs<C> & {
+    requiresConfig: true;
+}): FilePolicyDefinition<C> & {
+    requiresConfig: true;
+};
+/** Define a Cargo policy with optional configuration. @public */
+export declare function defineCargoPolicy<C = void>(args: DefineCargoPolicyArgs<C>): FilePolicyDefinition<C>;
 //# sourceMappingURL=defineCargoPolicy.d.ts.map

package/esm/policyDefiners/defineCargoPolicy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineCargoPolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/defineCargoPolicy.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAGjD,OAAO,KAAK,EACX,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,MAAM,cAAc,CAAC;AAGtB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CACjC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KACf,SAAS,CAAC,mBAAmB,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAcnE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACvC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAE7B;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,SAAS,EAC9C,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC5B,WAAW,CAAC,CAAC,CAAC,CAuBhB"}
+{"version":3,"file":"defineCargoPolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/defineCargoPolicy.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAKjD,OAAO,KAAK,EACX,aAAa,EACb,oBAAoB,EACpB,UAAU,EACV,YAAY,EACZ,MAAM,cAAc,CAAC;AAItB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CACjC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KACf,SAAS,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAcrD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACvC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAE7B;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,IAAI,EACzC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG;IAAE,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,GAClE,oBAAoB,CAAC,CAAC,CAAC,GAAG;IAAE,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AACjE,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,IAAI,EACzC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG;IAAE,cAAc,EAAE,IAAI,CAAA;CAAE,GACvD,oBAAoB,CAAC,CAAC,CAAC,GAAG;IAAE,cAAc,EAAE,IAAI,CAAA;CAAE,CAAC;AACtD,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,IAAI,EACzC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC5B,oBAAoB,CAAC,CAAC,CAAC,CAAC"}

package/esm/policyDefiners/defineCargoPolicy.js

@@ -1,7 +1,10 @@
 import { readFile } from "node:fs/promises";
 import { call } from "effection";
 import { resolve } from "pathe";
+import { ExecutionContractError } from "../executionContractError.js";
+import { readParsedFile } from "../fileCache.js";
 import { CargoTomlRegexMatch } from "../policies/constants.js";
+import { settlePolicyPromise } from "../settlePolicyPromise.js";
 import { parseToml } from "./tomlParser.js";
 /**
  * Type guard to check if a value is an Effection Operation (generator).
@@ -12,30 +15,6 @@ function isOperation(value) {
         "next" in value &&
         typeof value.next === "function");
 }
-/**
- * Define a repo policy for Cargo.toml files.
- *
- * @remarks
- * This is a helper function that creates a policy pre-configured to match
- * Cargo.toml files. The handler receives the parsed TOML content.
- *
- * @example
- * ```typescript
- * const MyCargoPolicy = defineCargoPolicy({
- *   name: "MyCargoPolicy",
- *   description: "Ensures Cargo.toml has required fields",
- *   handler: async (toml, { file }) => {
- *     const pkg = toml.package as Record<string, unknown> | undefined;
- *     if (!pkg?.name) {
- *       return { error: "Missing package name", fixable: false };
- *     }
- *     return true;
- *   },
- * });
- * ```
- *
- * @alpha
- */
 export function defineCargoPolicy(args) {
     const { name, description, handler: cargoHandler, defaultConfig } = args;
     return {
@@ -43,17 +22,20 @@ export function defineCargoPolicy(args) {
         description,
         match: CargoTomlRegexMatch,
         defaultConfig,
+        requiresConfig: args.requiresConfig,
         handler: function* (innerArgs) {
-            const content = yield* call(() => readFile(resolve(innerArgs.root, innerArgs.file), "utf-8"));
-            const toml = yield* call(() => parseToml(content));
+            const toml = yield* call(() => readParsedFile(innerArgs, "toml", async () => {
+                const content = await readFile(resolve(innerArgs.root, innerArgs.file), "utf-8");
+                return parseToml(content);
+            }));
             const result = cargoHandler(toml, innerArgs);
             if (result instanceof Promise) {
-                return yield* call(() => result);
+                return yield* settlePolicyPromise(result);
             }
             if (isOperation(result)) {
                 return yield* result;
             }
-            throw new Error(`Unexpected handler result type: ${typeof result}`);
+            throw new ExecutionContractError(`Unexpected handler result type: ${typeof result}`);
         },
     };
 }

package/esm/policyDefiners/defineCargoPolicy.js.map

@@ -1 +1 @@
-{"version":3,"file":"defineCargoPolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/defineCargoPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAkB,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM/D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAsB5C;;GAEG;AACH,SAAS,WAAW,CAAI,KAAc;IACrC,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAQ,KAA2B,CAAC,IAAI,KAAK,UAAU,CACvD,CAAC;AACH,CAAC;AA6BD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAChC,IAA8B;IAE9B,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IACzE,OAAO;QACN,IAAI;QACJ,WAAW;QACX,KAAK,EAAE,mBAAmB;QAC1B,aAAa;QACb,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS;YAC5B,MAAM,OAAO,GAAW,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CACxC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAC1D,CAAC;YACF,MAAM,IAAI,GAAc,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;YAC9D,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAE7C,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;gBAC/B,OAAO,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;YAClC,CAAC;YACD,IAAI,WAAW,CAAsB,MAAM,CAAC,EAAE,CAAC;gBAC9C,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC;YACtB,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,MAAM,EAAE,CAAC,CAAC;QACrE,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { call, type Operation } from \"effection\";\nimport { resolve } from \"pathe\";\nimport { CargoTomlRegexMatch } from \"../policies/constants.js\";\nimport type {\n\tPolicyArgs,\n\tPolicyHandlerResult,\n\tPolicyShape,\n} from \"../policy.js\";\nimport { parseToml } from \"./tomlParser.js\";\n\n/**\n * A parsed Cargo.toml represented as a record of sections and values.\n *\n * @alpha\n */\nexport type CargoToml = Record<string, unknown>;\n\n/**\n * A policy handler for Cargo.toml policies.\n *\n * @remarks\n * Receives the parsed TOML content and the standard policy arguments.\n *\n * @alpha\n */\nexport type CargoTomlHandler<C> = (\n\ttoml: CargoToml,\n\targs: PolicyArgs<C>,\n) => Operation<PolicyHandlerResult> | Promise<PolicyHandlerResult>;\n\n/**\n * Type guard to check if a value is an Effection Operation (generator).\n */\nfunction isOperation<T>(value: unknown): value is Operation<T> {\n\treturn (\n\t\ttypeof value === \"object\" &&\n\t\tvalue !== null &&\n\t\t\"next\" in value &&\n\t\ttypeof (value as { next: unknown }).next === \"function\"\n\t);\n}\n\n/**\n * Input arguments for defining a Cargo.toml policy.\n *\n * @alpha\n */\nexport interface DefineCargoPolicyArgs<C> {\n\t/**\n\t * The name of the policy.\n\t */\n\tname: string;\n\n\t/**\n\t * A description of the policy's purpose.\n\t */\n\tdescription: string;\n\n\t/**\n\t * The handler function that receives the parsed Cargo.toml and policy arguments.\n\t */\n\thandler: CargoTomlHandler<C>;\n\n\t/**\n\t * Optional default configuration for the policy.\n\t */\n\tdefaultConfig?: C;\n}\n\n/**\n * Define a repo policy for Cargo.toml files.\n *\n * @remarks\n * This is a helper function that creates a policy pre-configured to match\n * Cargo.toml files. The handler receives the parsed TOML content.\n *\n * @example\n * ```typescript\n * const MyCargoPolicy = defineCargoPolicy({\n *   name: \"MyCargoPolicy\",\n *   description: \"Ensures Cargo.toml has required fields\",\n *   handler: async (toml, { file }) => {\n *     const pkg = toml.package as Record<string, unknown> | undefined;\n *     if (!pkg?.name) {\n *       return { error: \"Missing package name\", fixable: false };\n *     }\n *     return true;\n *   },\n * });\n * ```\n *\n * @alpha\n */\nexport function defineCargoPolicy<C = undefined>(\n\targs: DefineCargoPolicyArgs<C>,\n): PolicyShape<C> {\n\tconst { name, description, handler: cargoHandler, defaultConfig } = args;\n\treturn {\n\t\tname,\n\t\tdescription,\n\t\tmatch: CargoTomlRegexMatch,\n\t\tdefaultConfig,\n\t\thandler: function* (innerArgs) {\n\t\t\tconst content: string = yield* call(() =>\n\t\t\t\treadFile(resolve(innerArgs.root, innerArgs.file), \"utf-8\"),\n\t\t\t);\n\t\t\tconst toml: CargoToml = yield* call(() => parseToml(content));\n\t\t\tconst result = cargoHandler(toml, innerArgs);\n\n\t\t\tif (result instanceof Promise) {\n\t\t\t\treturn yield* call(() => result);\n\t\t\t}\n\t\t\tif (isOperation<PolicyHandlerResult>(result)) {\n\t\t\t\treturn yield* result;\n\t\t\t}\n\t\t\tthrow new Error(`Unexpected handler result type: ${typeof result}`);\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"defineCargoPolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/defineCargoPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAkB,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAO/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAsB5C;;GAEG;AACH,SAAS,WAAW,CAAI,KAAc;IACrC,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAQ,KAA2B,CAAC,IAAI,KAAK,UAAU,CACvD,CAAC;AACH,CAAC;AAoED,MAAM,UAAU,iBAAiB,CAChC,IAA8B;IAE9B,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IACzE,OAAO;QACN,IAAI;QACJ,WAAW;QACX,KAAK,EAAE,mBAAmB;QAC1B,aAAa;QACb,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS;YAC5B,MAAM,IAAI,GAAc,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CACxC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE;gBAC5C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAC7B,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EACvC,OAAO,CACP,CAAC;gBACF,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC,CAAC,CACF,CAAC;YACF,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAE7C,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;gBAC/B,OAAO,KAAK,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;YACD,IAAI,WAAW,CAAe,MAAM,CAAC,EAAE,CAAC;gBACvC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC;YACtB,CAAC;YACD,MAAM,IAAI,sBAAsB,CAC/B,mCAAmC,OAAO,MAAM,EAAE,CAClD,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { call, type Operation } from \"effection\";\nimport { resolve } from \"pathe\";\nimport { ExecutionContractError } from \"../executionContractError.js\";\nimport { readParsedFile } from \"../fileCache.js\";\nimport { CargoTomlRegexMatch } from \"../policies/constants.js\";\nimport type {\n\tDefinedConfig,\n\tFilePolicyDefinition,\n\tPolicyArgs,\n\tPolicyResult,\n} from \"../policy.js\";\nimport { settlePolicyPromise } from \"../settlePolicyPromise.js\";\nimport { parseToml } from \"./tomlParser.js\";\n\n/**\n * A parsed Cargo.toml represented as a record of sections and values.\n *\n * @public\n */\nexport type CargoToml = Record<string, unknown>;\n\n/**\n * A policy handler for Cargo.toml policies.\n *\n * @remarks\n * Receives the parsed TOML content and the standard policy arguments.\n *\n * @public\n */\nexport type CargoTomlHandler<C> = (\n\ttoml: CargoToml,\n\targs: PolicyArgs<C>,\n) => Operation<PolicyResult> | Promise<PolicyResult>;\n\n/**\n * Type guard to check if a value is an Effection Operation (generator).\n */\nfunction isOperation<T>(value: unknown): value is Operation<T> {\n\treturn (\n\t\ttypeof value === \"object\" &&\n\t\tvalue !== null &&\n\t\t\"next\" in value &&\n\t\ttypeof (value as { next: unknown }).next === \"function\"\n\t);\n}\n\n/**\n * Input arguments for defining a Cargo.toml policy.\n *\n * @public\n */\nexport interface DefineCargoPolicyArgs<C> {\n\t/**\n\t * The name of the policy.\n\t */\n\tname: string;\n\n\t/**\n\t * A description of the policy's purpose.\n\t */\n\tdescription: string;\n\n\t/**\n\t * The handler function that receives the parsed Cargo.toml and policy arguments.\n\t */\n\thandler: CargoTomlHandler<C>;\n\n\t/**\n\t * Optional default configuration for the policy.\n\t */\n\tdefaultConfig?: C;\n\trequiresConfig?: boolean;\n}\n\n/**\n * Define a repo policy for Cargo.toml files.\n *\n * @remarks\n * This is a helper function that creates a policy pre-configured to match\n * Cargo.toml files. The handler receives the parsed TOML content.\n *\n * @param args - Policy metadata, parsed-TOML handler, and optional defaults.\n * @returns A file policy that reads and parses matching Cargo.toml files.\n *\n * @example\n * ```typescript\n * const MyCargoPolicy = defineCargoPolicy({\n *   name: \"MyCargoPolicy\",\n *   description: \"Ensures Cargo.toml has required fields\",\n *   handler: async (toml, { file }) => {\n *     const pkg = toml.package as Record<string, unknown> | undefined;\n *     if (!pkg?.name) {\n *       return [{ message: \"Missing package name\" }];\n *     }\n *     return [];\n *   },\n * });\n * ```\n *\n * @public\n */\nexport function defineCargoPolicy<C = void>(\n\targs: DefineCargoPolicyArgs<C> & { defaultConfig: DefinedConfig<C> },\n): FilePolicyDefinition<C> & { defaultConfig: DefinedConfig<C> };\n/** Define a Cargo policy that requires explicit configuration. @public */\nexport function defineCargoPolicy<C = void>(\n\targs: DefineCargoPolicyArgs<C> & { requiresConfig: true },\n): FilePolicyDefinition<C> & { requiresConfig: true };\n/** Define a Cargo policy with optional configuration. @public */\nexport function defineCargoPolicy<C = void>(\n\targs: DefineCargoPolicyArgs<C>,\n): FilePolicyDefinition<C>;\nexport function defineCargoPolicy<C = void>(\n\targs: DefineCargoPolicyArgs<C>,\n): FilePolicyDefinition<C> {\n\tconst { name, description, handler: cargoHandler, defaultConfig } = args;\n\treturn {\n\t\tname,\n\t\tdescription,\n\t\tmatch: CargoTomlRegexMatch,\n\t\tdefaultConfig,\n\t\trequiresConfig: args.requiresConfig,\n\t\thandler: function* (innerArgs) {\n\t\t\tconst toml: CargoToml = yield* call(() =>\n\t\t\t\treadParsedFile(innerArgs, \"toml\", async () => {\n\t\t\t\t\tconst content = await readFile(\n\t\t\t\t\t\tresolve(innerArgs.root, innerArgs.file),\n\t\t\t\t\t\t\"utf-8\",\n\t\t\t\t\t);\n\t\t\t\t\treturn parseToml(content);\n\t\t\t\t}),\n\t\t\t);\n\t\t\tconst result = cargoHandler(toml, innerArgs);\n\n\t\t\tif (result instanceof Promise) {\n\t\t\t\treturn yield* settlePolicyPromise(result);\n\t\t\t}\n\t\t\tif (isOperation<PolicyResult>(result)) {\n\t\t\t\treturn yield* result;\n\t\t\t}\n\t\t\tthrow new ExecutionContractError(\n\t\t\t\t`Unexpected handler result type: ${typeof result}`,\n\t\t\t);\n\t\t},\n\t};\n}\n"]}

package/esm/policyDefiners/defineFileHeaderPolicy.d.ts

@@ -1,6 +1,8 @@
-import type { PolicyShape } from "../policy.js";
+import type { FilePolicyDefinition } from "../policy.js";
 /**
- * @alpha
+ * Header text required by a file-header policy.
+ *
+ * @public
  */
 export interface FileHeaderPolicyConfig {
     /**
@@ -19,13 +21,13 @@ export interface FileHeaderPolicyConfig {
  * This interface extends FileHeaderPolicyConfig and adds formatting-specific
  * properties to control how headers are inserted into different file types.
  *
- * @alpha
+ * @public
  */
 export interface FileHeaderGeneratorConfig extends Partial<FileHeaderPolicyConfig> {
     /** Regular expression that matches files this header generator applies to */
     match: RegExp;
     /**
-     * Regex matching header prefix (e.g. `/*!\r?\n`)
+     * Regex matching the header prefix, such as a block-comment opener.
      */
     headerStart?: RegExp;
     /**
@@ -52,7 +54,7 @@ export interface FileHeaderGeneratorConfig extends Partial<FileHeaderPolicyConfi
 /**
  * Input arguments for defining a file header policy.
  *
- * @alpha
+ * @public
  */
 export interface DefineFileHeaderPolicyArgs {
     /**
@@ -67,10 +69,17 @@ export interface DefineFileHeaderPolicyArgs {
      * Configuration for how headers are detected and inserted.
      */
     config: FileHeaderGeneratorConfig;
+    /** Complete default instance configuration, if the policy is usable without an override. */
+    defaultConfig?: FileHeaderPolicyConfig;
 }
 /**
- * Given a {@link FileHeaderPolicyConfig}, produces a function that detects correct file headers
- * and returns an error string if the header is missing or incorrect.
+ * Creates a file-header policy that detects missing or incorrect headers and can replace them.
+ *
+ * Supply {@link FileHeaderPolicyConfig} when configuring the policy, unless
+ * the definition supplies a complete default.
+ *
+ * @param args - Policy metadata and header matching and replacement rules.
+ * @returns A file policy configured for the supplied file types.
  *
  * @example
  * ```typescript
@@ -81,12 +90,16 @@ export interface DefineFileHeaderPolicyArgs {
  * });
  * ```
  *
- * @alpha
- */
-export declare function defineFileHeaderPolicy(args: DefineFileHeaderPolicyArgs): PolicyShape<FileHeaderPolicyConfig>;
-/**
- * Alias for defineFileHeaderPolicy.
- * @alpha
+ * @public
  */
-export declare const fileHeaderPolicy: typeof defineFileHeaderPolicy;
+export declare function defineFileHeaderPolicy(args: DefineFileHeaderPolicyArgs & {
+    defaultConfig: FileHeaderPolicyConfig;
+}): FilePolicyDefinition<FileHeaderPolicyConfig> & {
+    requiresConfig: true;
+    defaultConfig: FileHeaderPolicyConfig;
+};
+/** Define a header policy that requires explicit header configuration. @public */
+export declare function defineFileHeaderPolicy(args: DefineFileHeaderPolicyArgs): FilePolicyDefinition<FileHeaderPolicyConfig> & {
+    requiresConfig: true;
+};
 //# sourceMappingURL=defineFileHeaderPolicy.d.ts.map

package/esm/policyDefiners/defineFileHeaderPolicy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineFileHeaderPolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/defineFileHeaderPolicy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAkC,WAAW,EAAE,MAAM,cAAc,CAAC;AAIhF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAChB,SAAQ,OAAO,CAAC,sBAAsB,CAAC;IACvC,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,KAAK,MAAM,CAAC;CACtE;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,yBAAyB,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,0BAA0B,GAC9B,WAAW,CAAC,sBAAsB,CAAC,CAqErC;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,+BAAyB,CAAC"}
+{"version":3,"file":"defineFileHeaderPolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/defineFileHeaderPolicy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAiB,MAAM,cAAc,CAAC;AAKxE;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAChB,SAAQ,OAAO,CAAC,sBAAsB,CAAC;IACvC,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,KAAK,MAAM,CAAC;CACtE;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,yBAAyB,CAAC;IAClC,4FAA4F;IAC5F,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,0BAA0B,GAAG;IAAE,aAAa,EAAE,sBAAsB,CAAA;CAAE,GAC1E,oBAAoB,CAAC,sBAAsB,CAAC,GAAG;IACjD,cAAc,EAAE,IAAI,CAAC;IACrB,aAAa,EAAE,sBAAsB,CAAC;CACtC,CAAC;AACF,kFAAkF;AAClF,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,0BAA0B,GAC9B,oBAAoB,CAAC,sBAAsB,CAAC,GAAG;IAAE,cAAc,EAAE,IAAI,CAAA;CAAE,CAAC"}

package/esm/policyDefiners/defineFileHeaderPolicy.js

@@ -1,23 +1,9 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { EOL as newline } from "node:os";
 import { call } from "effection";
-import { extname, resolve as resolvePath } from "pathe";
+import { extname } from "pathe";
+import { resolveRepoFilePath } from "../utils/safePaths.js";
 const trailingSpaces = /\s*\\r\?\\n/;
-/**
- * Given a {@link FileHeaderPolicyConfig}, produces a function that detects correct file headers
- * and returns an error string if the header is missing or incorrect.
- *
- * @example
- * ```typescript
- * const MyHeaderPolicy = defineFileHeaderPolicy({
- *   name: "MyHeaderPolicy",
- *   description: "Ensures files have required headers",
- *   config: { match: /\.ts$/, lineStart: /\/\/ /, lineEnd: /\r?\n/, replacer: ... },
- * });
- * ```
- *
- * @alpha
- */
 export function defineFileHeaderPolicy(args) {
     const { name, description, config } = args;
     const pre = config.headerStart?.source ?? "";
@@ -35,44 +21,39 @@ export function defineFileHeaderPolicy(args) {
         name,
         description,
         match: config.match,
+        requiresConfig: true,
+        defaultConfig: args.defaultConfig,
         handler: function* ({ file, root, resolve, config: policyConfig }) {
             if (policyConfig === undefined) {
-                return true;
+                throw new TypeError(`${name} requires config.`);
             }
             const regex = new RegExp(`^${pre}${toRegex(policyConfig.headerText)}(${toRegex(policyConfig.autoGenText ?? config.autoGenText ?? "")})?${post}`);
-            const failResult = {
-                name,
-                file,
-                autoFixable: true,
-                errorMessages: [],
-            };
+            const filePath = resolveRepoFilePath(root, file);
+            const failResult = [];
             // TODO: Consider reading only the first 512B or so since headers are typically
             // at the beginning of the file.
-            const filePath = resolvePath(root, file);
             const content = yield* call(() => readFile(filePath, { encoding: "utf8" }));
             const failed = !regex.test(content);
             if (failed) {
-                failResult.errorMessages.push(`${extname(file)} file missing header`);
+                failResult.push({
+                    message: `${extname(file)} file missing header`,
+                    fixStatus: "available",
+                });
             }
             if (failed) {
                 if (resolve) {
                     const newContent = config.replacer(content, policyConfig);
                     yield* call(() => writeFile(filePath, newContent));
-                    const fixResult = {
-                        ...failResult,
-                        resolved: true,
-                    };
+                    const fixResult = failResult.map((finding) => ({
+                        ...finding,
+                        fixStatus: "fixed",
+                    }));
                     return fixResult;
                 }
                 return failResult;
             }
-            return true;
+            return [];
         },
     };
 }
-/**
- * Alias for defineFileHeaderPolicy.
- * @alpha
- */
-export const fileHeaderPolicy = defineFileHeaderPolicy;
 //# sourceMappingURL=defineFileHeaderPolicy.js.map

package/esm/policyDefiners/defineFileHeaderPolicy.js.map

@@ -1 +1 @@
-{"version":3,"file":"defineFileHeaderPolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/defineFileHeaderPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile, writeFile } from \"node:fs/promises\";\nimport { EOL as newline } from \"node:os\";\nimport { call } from \"effection\";\nimport { extname, resolve as resolvePath } from \"pathe\";\nimport type { PolicyFailure, PolicyFixResult, PolicyShape } from \"../policy.js\";\n\nconst trailingSpaces = /\\s*\\\\r\\?\\\\n/;\n\n/**\n * @alpha\n */\nexport interface FileHeaderPolicyConfig {\n\t/**\n\t * The text to use as the header.\n\t */\n\theaderText: string;\n\n\t/**\n\t * An optional string that will be appended to the headerText.\n\t */\n\tautoGenText?: string;\n}\n\n/**\n * Configuration for generating file headers with specific formatting rules.\n *\n * @remarks\n * This interface extends FileHeaderPolicyConfig and adds formatting-specific\n * properties to control how headers are inserted into different file types.\n *\n * @alpha\n */\nexport interface FileHeaderGeneratorConfig\n\textends Partial<FileHeaderPolicyConfig> {\n\t/** Regular expression that matches files this header generator applies to */\n\tmatch: RegExp;\n\n\t/**\n\t * Regex matching header prefix (e.g. `/*!\\r?\\n`)\n\t */\n\theaderStart?: RegExp;\n\n\t/**\n\t * Regex matching beginning of each line (e.g. ' * ')\n\t */\n\tlineStart: RegExp;\n\n\t/**\n\t * Regex matching the end of each line (e.g., `\\r?\\n`)\n\t */\n\tlineEnd: RegExp;\n\n\t/**\n\t * Regex matching the header postfix.\n\t */\n\theaderEnd?: RegExp;\n\n\t/**\n\t * Function that generates the properly formatted header content for insertion into files.\n\t *\n\t * @param content - The original file content\n\t * @param config - The file header policy configuration\n\t * @returns The formatted header string to insert\n\t */\n\treplacer: (content: string, config: FileHeaderPolicyConfig) => string;\n}\n\n/**\n * Input arguments for defining a file header policy.\n *\n * @alpha\n */\nexport interface DefineFileHeaderPolicyArgs {\n\t/**\n\t * The name of the policy.\n\t */\n\tname: string;\n\n\t/**\n\t * A description of the policy's purpose.\n\t */\n\tdescription: string;\n\n\t/**\n\t * Configuration for how headers are detected and inserted.\n\t */\n\tconfig: FileHeaderGeneratorConfig;\n}\n\n/**\n * Given a {@link FileHeaderPolicyConfig}, produces a function that detects correct file headers\n * and returns an error string if the header is missing or incorrect.\n *\n * @example\n * ```typescript\n * const MyHeaderPolicy = defineFileHeaderPolicy({\n *   name: \"MyHeaderPolicy\",\n *   description: \"Ensures files have required headers\",\n *   config: { match: /\\.ts$/, lineStart: /\\/\\/ /, lineEnd: /\\r?\\n/, replacer: ... },\n * });\n * ```\n *\n * @alpha\n */\nexport function defineFileHeaderPolicy(\n\targs: DefineFileHeaderPolicyArgs,\n): PolicyShape<FileHeaderPolicyConfig> {\n\tconst { name, description, config } = args;\n\tconst pre = config.headerStart?.source ?? \"\";\n\tconst start = config.lineStart.source;\n\tconst end = config.lineEnd.source;\n\tconst post = config.headerEnd?.source ?? \"\";\n\n\t// Helper which constructs a matching RegExp from a given multiline string.\n\t// (See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping)\n\tconst toRegex = (text: string): string =>\n\t\ttext\n\t\t\t.split(newline)\n\t\t\t.map(\n\t\t\t\t(line) =>\n\t\t\t\t\t`${start}${line.replace(/[$()*+.?[\\\\\\]^{|}]/g, \"\\\\$&\")}${end}`,\n\t\t\t)\n\t\t\t.join(\"\")\n\t\t\t.replace(trailingSpaces, \"\\\\r?\\\\n\"); // Trim trailing spaces at end-of-line.\n\n\treturn {\n\t\tname,\n\t\tdescription,\n\t\tmatch: config.match,\n\t\thandler: function* ({ file, root, resolve, config: policyConfig }) {\n\t\t\tif (policyConfig === undefined) {\n\t\t\t\treturn true;\n\t\t\t}\n\n\t\t\tconst regex = new RegExp(\n\t\t\t\t`^${pre}${toRegex(policyConfig.headerText)}(${toRegex(policyConfig.autoGenText ?? config.autoGenText ?? \"\")})?${post}`,\n\t\t\t);\n\n\t\t\tconst failResult: PolicyFailure = {\n\t\t\t\tname,\n\t\t\t\tfile,\n\t\t\t\tautoFixable: true,\n\t\t\t\terrorMessages: [],\n\t\t\t};\n\n\t\t\t// TODO: Consider reading only the first 512B or so since headers are typically\n\t\t\t// at the beginning of the file.\n\t\t\tconst filePath = resolvePath(root, file);\n\t\t\tconst content = yield* call(() =>\n\t\t\t\treadFile(filePath, { encoding: \"utf8\" }),\n\t\t\t);\n\t\t\tconst failed = !regex.test(content);\n\n\t\t\tif (failed) {\n\t\t\t\tfailResult.errorMessages.push(`${extname(file)} file missing header`);\n\t\t\t}\n\n\t\t\tif (failed) {\n\t\t\t\tif (resolve) {\n\t\t\t\t\tconst newContent = config.replacer(content, policyConfig);\n\t\t\t\t\tyield* call(() => writeFile(filePath, newContent));\n\n\t\t\t\t\tconst fixResult: PolicyFixResult = {\n\t\t\t\t\t\t...failResult,\n\t\t\t\t\t\tresolved: true,\n\t\t\t\t\t};\n\n\t\t\t\t\treturn fixResult;\n\t\t\t\t}\n\t\t\t\treturn failResult;\n\t\t\t}\n\n\t\t\treturn true;\n\t\t},\n\t};\n}\n\n/**\n * Alias for defineFileHeaderPolicy.\n * @alpha\n */\nexport const fileHeaderPolicy = defineFileHeaderPolicy;\n"]}
+{"version":3,"file":"defineFileHeaderPolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/defineFileHeaderPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile, writeFile } from \"node:fs/promises\";\nimport { EOL as newline } from \"node:os\";\nimport { call } from \"effection\";\nimport { extname } from \"pathe\";\nimport type { FilePolicyDefinition, PolicyFinding } from \"../policy.js\";\nimport { resolveRepoFilePath } from \"../utils/safePaths.js\";\n\nconst trailingSpaces = /\\s*\\\\r\\?\\\\n/;\n\n/**\n * Header text required by a file-header policy.\n *\n * @public\n */\nexport interface FileHeaderPolicyConfig {\n\t/**\n\t * The text to use as the header.\n\t */\n\theaderText: string;\n\n\t/**\n\t * An optional string that will be appended to the headerText.\n\t */\n\tautoGenText?: string;\n}\n\n/**\n * Configuration for generating file headers with specific formatting rules.\n *\n * @remarks\n * This interface extends FileHeaderPolicyConfig and adds formatting-specific\n * properties to control how headers are inserted into different file types.\n *\n * @public\n */\nexport interface FileHeaderGeneratorConfig\n\textends Partial<FileHeaderPolicyConfig> {\n\t/** Regular expression that matches files this header generator applies to */\n\tmatch: RegExp;\n\n\t/**\n\t * Regex matching the header prefix, such as a block-comment opener.\n\t */\n\theaderStart?: RegExp;\n\n\t/**\n\t * Regex matching beginning of each line (e.g. ' * ')\n\t */\n\tlineStart: RegExp;\n\n\t/**\n\t * Regex matching the end of each line (e.g., `\\r?\\n`)\n\t */\n\tlineEnd: RegExp;\n\n\t/**\n\t * Regex matching the header postfix.\n\t */\n\theaderEnd?: RegExp;\n\n\t/**\n\t * Function that generates the properly formatted header content for insertion into files.\n\t *\n\t * @param content - The original file content\n\t * @param config - The file header policy configuration\n\t * @returns The formatted header string to insert\n\t */\n\treplacer: (content: string, config: FileHeaderPolicyConfig) => string;\n}\n\n/**\n * Input arguments for defining a file header policy.\n *\n * @public\n */\nexport interface DefineFileHeaderPolicyArgs {\n\t/**\n\t * The name of the policy.\n\t */\n\tname: string;\n\n\t/**\n\t * A description of the policy's purpose.\n\t */\n\tdescription: string;\n\n\t/**\n\t * Configuration for how headers are detected and inserted.\n\t */\n\tconfig: FileHeaderGeneratorConfig;\n\t/** Complete default instance configuration, if the policy is usable without an override. */\n\tdefaultConfig?: FileHeaderPolicyConfig;\n}\n\n/**\n * Creates a file-header policy that detects missing or incorrect headers and can replace them.\n *\n * Supply {@link FileHeaderPolicyConfig} when configuring the policy, unless\n * the definition supplies a complete default.\n *\n * @param args - Policy metadata and header matching and replacement rules.\n * @returns A file policy configured for the supplied file types.\n *\n * @example\n * ```typescript\n * const MyHeaderPolicy = defineFileHeaderPolicy({\n *   name: \"MyHeaderPolicy\",\n *   description: \"Ensures files have required headers\",\n *   config: { match: /\\.ts$/, lineStart: /\\/\\/ /, lineEnd: /\\r?\\n/, replacer: ... },\n * });\n * ```\n *\n * @public\n */\nexport function defineFileHeaderPolicy(\n\targs: DefineFileHeaderPolicyArgs & { defaultConfig: FileHeaderPolicyConfig },\n): FilePolicyDefinition<FileHeaderPolicyConfig> & {\n\trequiresConfig: true;\n\tdefaultConfig: FileHeaderPolicyConfig;\n};\n/** Define a header policy that requires explicit header configuration. @public */\nexport function defineFileHeaderPolicy(\n\targs: DefineFileHeaderPolicyArgs,\n): FilePolicyDefinition<FileHeaderPolicyConfig> & { requiresConfig: true };\nexport function defineFileHeaderPolicy(\n\targs: DefineFileHeaderPolicyArgs,\n): FilePolicyDefinition<FileHeaderPolicyConfig> & { requiresConfig: true } {\n\tconst { name, description, config } = args;\n\tconst pre = config.headerStart?.source ?? \"\";\n\tconst start = config.lineStart.source;\n\tconst end = config.lineEnd.source;\n\tconst post = config.headerEnd?.source ?? \"\";\n\n\t// Helper which constructs a matching RegExp from a given multiline string.\n\t// (See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping)\n\tconst toRegex = (text: string): string =>\n\t\ttext\n\t\t\t.split(newline)\n\t\t\t.map(\n\t\t\t\t(line) =>\n\t\t\t\t\t`${start}${line.replace(/[$()*+.?[\\\\\\]^{|}]/g, \"\\\\$&\")}${end}`,\n\t\t\t)\n\t\t\t.join(\"\")\n\t\t\t.replace(trailingSpaces, \"\\\\r?\\\\n\"); // Trim trailing spaces at end-of-line.\n\n\treturn {\n\t\tname,\n\t\tdescription,\n\t\tmatch: config.match,\n\t\trequiresConfig: true,\n\t\tdefaultConfig: args.defaultConfig,\n\t\thandler: function* ({ file, root, resolve, config: policyConfig }) {\n\t\t\tif (policyConfig === undefined) {\n\t\t\t\tthrow new TypeError(`${name} requires config.`);\n\t\t\t}\n\n\t\t\tconst regex = new RegExp(\n\t\t\t\t`^${pre}${toRegex(policyConfig.headerText)}(${toRegex(policyConfig.autoGenText ?? config.autoGenText ?? \"\")})?${post}`,\n\t\t\t);\n\t\t\tconst filePath = resolveRepoFilePath(root, file);\n\t\t\tconst failResult: PolicyFinding[] = [];\n\t\t\t// TODO: Consider reading only the first 512B or so since headers are typically\n\t\t\t// at the beginning of the file.\n\t\t\tconst content = yield* call(() =>\n\t\t\t\treadFile(filePath, { encoding: \"utf8\" }),\n\t\t\t);\n\t\t\tconst failed = !regex.test(content);\n\n\t\t\tif (failed) {\n\t\t\t\tfailResult.push({\n\t\t\t\t\tmessage: `${extname(file)} file missing header`,\n\t\t\t\t\tfixStatus: \"available\",\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (failed) {\n\t\t\t\tif (resolve) {\n\t\t\t\t\tconst newContent = config.replacer(content, policyConfig);\n\t\t\t\t\tyield* call(() => writeFile(filePath, newContent));\n\t\t\t\t\tconst fixResult: PolicyFinding[] = failResult.map((finding) => ({\n\t\t\t\t\t\t...finding,\n\t\t\t\t\t\tfixStatus: \"fixed\",\n\t\t\t\t\t}));\n\t\t\t\t\treturn fixResult;\n\t\t\t\t}\n\t\t\t\treturn failResult;\n\t\t\t}\n\t\t\treturn [];\n\t\t},\n\t};\n}\n"]}

package/esm/policyDefiners/defineGleamPolicy.d.ts

@@ -1,9 +1,9 @@
 import { type Operation } from "effection";
-import type { PolicyArgs, PolicyHandlerResult, PolicyShape } from "../policy.js";
+import type { DefinedConfig, FilePolicyDefinition, PolicyArgs, PolicyResult } from "../policy.js";
 /**
  * A parsed gleam.toml represented as a record of sections and values.
  *
- * @alpha
+ * @public
  */
 export type GleamToml = Record<string, unknown>;
 /**
@@ -12,13 +12,13 @@ export type GleamToml = Record<string, unknown>;
  * @remarks
  * Receives the parsed TOML content and the standard policy arguments.
  *
- * @alpha
+ * @public
  */
-export type GleamTomlHandler<C> = (toml: GleamToml, args: PolicyArgs<C>) => Operation<PolicyHandlerResult> | Promise<PolicyHandlerResult>;
+export type GleamTomlHandler<C> = (toml: GleamToml, args: PolicyArgs<C>) => Operation<PolicyResult> | Promise<PolicyResult>;
 /**
  * Input arguments for defining a gleam.toml policy.
  *
- * @alpha
+ * @public
  */
 export interface DefineGleamPolicyArgs<C> {
     /**
@@ -37,6 +37,7 @@ export interface DefineGleamPolicyArgs<C> {
      * Optional default configuration for the policy.
      */
     defaultConfig?: C;
+    requiresConfig?: boolean;
 }
 /**
  * Define a repo policy for gleam.toml files.
@@ -45,6 +46,9 @@ export interface DefineGleamPolicyArgs<C> {
  * This is a helper function that creates a policy pre-configured to match
  * gleam.toml files. The handler receives the parsed TOML content.
  *
+ * @param args - Policy metadata, parsed-TOML handler, and optional defaults.
+ * @returns A file policy that reads and parses matching gleam.toml files.
+ *
  * @example
  * ```typescript
  * const MyGleamPolicy = defineGleamPolicy({
@@ -52,14 +56,26 @@ export interface DefineGleamPolicyArgs<C> {
  *   description: "Ensures gleam.toml has required fields",
  *   handler: async (toml, { file }) => {
  *     if (!toml.name) {
- *       return { error: "Missing name field", fixable: false };
+ *       return [{ message: "Missing name field" }];
  *     }
- *     return true;
+ *     return [];
  *   },
  * });
  * ```
  *
- * @alpha
+ * @public
  */
-export declare function defineGleamPolicy<C = undefined>(args: DefineGleamPolicyArgs<C>): PolicyShape<C>;
+export declare function defineGleamPolicy<C = void>(args: DefineGleamPolicyArgs<C> & {
+    defaultConfig: DefinedConfig<C>;
+}): FilePolicyDefinition<C> & {
+    defaultConfig: DefinedConfig<C>;
+};
+/** Define a Gleam policy that requires explicit configuration. @public */
+export declare function defineGleamPolicy<C = void>(args: DefineGleamPolicyArgs<C> & {
+    requiresConfig: true;
+}): FilePolicyDefinition<C> & {
+    requiresConfig: true;
+};
+/** Define a Gleam policy with optional configuration. @public */
+export declare function defineGleamPolicy<C = void>(args: DefineGleamPolicyArgs<C>): FilePolicyDefinition<C>;
 //# sourceMappingURL=defineGleamPolicy.d.ts.map

package/esm/policyDefiners/defineGleamPolicy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineGleamPolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/defineGleamPolicy.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAGjD,OAAO,KAAK,EACX,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,MAAM,cAAc,CAAC;AAGtB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CACjC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KACf,SAAS,CAAC,mBAAmB,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAcnE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACvC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAE7B;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,SAAS,EAC9C,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC5B,WAAW,CAAC,CAAC,CAAC,CAuBhB"}
+{"version":3,"file":"defineGleamPolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/defineGleamPolicy.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAKjD,OAAO,KAAK,EACX,aAAa,EACb,oBAAoB,EACpB,UAAU,EACV,YAAY,EACZ,MAAM,cAAc,CAAC;AAItB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CACjC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KACf,SAAS,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAcrD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACvC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAE7B;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,IAAI,EACzC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG;IAAE,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,GAClE,oBAAoB,CAAC,CAAC,CAAC,GAAG;IAAE,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AACjE,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,IAAI,EACzC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG;IAAE,cAAc,EAAE,IAAI,CAAA;CAAE,GACvD,oBAAoB,CAAC,CAAC,CAAC,GAAG;IAAE,cAAc,EAAE,IAAI,CAAA;CAAE,CAAC;AACtD,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,IAAI,EACzC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC5B,oBAAoB,CAAC,CAAC,CAAC,CAAC"}

package/esm/policyDefiners/defineGleamPolicy.js

@@ -1,7 +1,10 @@
 import { readFile } from "node:fs/promises";
 import { call } from "effection";
 import { resolve } from "pathe";
+import { ExecutionContractError } from "../executionContractError.js";
+import { readParsedFile } from "../fileCache.js";
 import { GleamTomlRegexMatch } from "../policies/constants.js";
+import { settlePolicyPromise } from "../settlePolicyPromise.js";
 import { parseToml } from "./tomlParser.js";
 /**
  * Type guard to check if a value is an Effection Operation (generator).
@@ -12,29 +15,6 @@ function isOperation(value) {
         "next" in value &&
         typeof value.next === "function");
 }
-/**
- * Define a repo policy for gleam.toml files.
- *
- * @remarks
- * This is a helper function that creates a policy pre-configured to match
- * gleam.toml files. The handler receives the parsed TOML content.
- *
- * @example
- * ```typescript
- * const MyGleamPolicy = defineGleamPolicy({
- *   name: "MyGleamPolicy",
- *   description: "Ensures gleam.toml has required fields",
- *   handler: async (toml, { file }) => {
- *     if (!toml.name) {
- *       return { error: "Missing name field", fixable: false };
- *     }
- *     return true;
- *   },
- * });
- * ```
- *
- * @alpha
- */
 export function defineGleamPolicy(args) {
     const { name, description, handler: gleamHandler, defaultConfig } = args;
     return {
@@ -42,17 +22,20 @@ export function defineGleamPolicy(args) {
         description,
         match: GleamTomlRegexMatch,
         defaultConfig,
+        requiresConfig: args.requiresConfig,
         handler: function* (innerArgs) {
-            const content = yield* call(() => readFile(resolve(innerArgs.root, innerArgs.file), "utf-8"));
-            const toml = yield* call(() => parseToml(content));
+            const toml = yield* call(() => readParsedFile(innerArgs, "toml", async () => {
+                const content = await readFile(resolve(innerArgs.root, innerArgs.file), "utf-8");
+                return parseToml(content);
+            }));
             const result = gleamHandler(toml, innerArgs);
             if (result instanceof Promise) {
-                return yield* call(() => result);
+                return yield* settlePolicyPromise(result);
             }
             if (isOperation(result)) {
                 return yield* result;
             }
-            throw new Error(`Unexpected handler result type: ${typeof result}`);
+            throw new ExecutionContractError(`Unexpected handler result type: ${typeof result}`);
         },
     };
 }

package/esm/policyDefiners/defineGleamPolicy.js.map

@@ -1 +1 @@
-{"version":3,"file":"defineGleamPolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/defineGleamPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAkB,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM/D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAsB5C;;GAEG;AACH,SAAS,WAAW,CAAI,KAAc;IACrC,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAQ,KAA2B,CAAC,IAAI,KAAK,UAAU,CACvD,CAAC;AACH,CAAC;AA6BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,iBAAiB,CAChC,IAA8B;IAE9B,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IACzE,OAAO;QACN,IAAI;QACJ,WAAW;QACX,KAAK,EAAE,mBAAmB;QAC1B,aAAa;QACb,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS;YAC5B,MAAM,OAAO,GAAW,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CACxC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAC1D,CAAC;YACF,MAAM,IAAI,GAAc,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;YAC9D,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAE7C,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;gBAC/B,OAAO,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;YAClC,CAAC;YACD,IAAI,WAAW,CAAsB,MAAM,CAAC,EAAE,CAAC;gBAC9C,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC;YACtB,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,MAAM,EAAE,CAAC,CAAC;QACrE,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { call, type Operation } from \"effection\";\nimport { resolve } from \"pathe\";\nimport { GleamTomlRegexMatch } from \"../policies/constants.js\";\nimport type {\n\tPolicyArgs,\n\tPolicyHandlerResult,\n\tPolicyShape,\n} from \"../policy.js\";\nimport { parseToml } from \"./tomlParser.js\";\n\n/**\n * A parsed gleam.toml represented as a record of sections and values.\n *\n * @alpha\n */\nexport type GleamToml = Record<string, unknown>;\n\n/**\n * A policy handler for gleam.toml policies.\n *\n * @remarks\n * Receives the parsed TOML content and the standard policy arguments.\n *\n * @alpha\n */\nexport type GleamTomlHandler<C> = (\n\ttoml: GleamToml,\n\targs: PolicyArgs<C>,\n) => Operation<PolicyHandlerResult> | Promise<PolicyHandlerResult>;\n\n/**\n * Type guard to check if a value is an Effection Operation (generator).\n */\nfunction isOperation<T>(value: unknown): value is Operation<T> {\n\treturn (\n\t\ttypeof value === \"object\" &&\n\t\tvalue !== null &&\n\t\t\"next\" in value &&\n\t\ttypeof (value as { next: unknown }).next === \"function\"\n\t);\n}\n\n/**\n * Input arguments for defining a gleam.toml policy.\n *\n * @alpha\n */\nexport interface DefineGleamPolicyArgs<C> {\n\t/**\n\t * The name of the policy.\n\t */\n\tname: string;\n\n\t/**\n\t * A description of the policy's purpose.\n\t */\n\tdescription: string;\n\n\t/**\n\t * The handler function that receives the parsed gleam.toml and policy arguments.\n\t */\n\thandler: GleamTomlHandler<C>;\n\n\t/**\n\t * Optional default configuration for the policy.\n\t */\n\tdefaultConfig?: C;\n}\n\n/**\n * Define a repo policy for gleam.toml files.\n *\n * @remarks\n * This is a helper function that creates a policy pre-configured to match\n * gleam.toml files. The handler receives the parsed TOML content.\n *\n * @example\n * ```typescript\n * const MyGleamPolicy = defineGleamPolicy({\n *   name: \"MyGleamPolicy\",\n *   description: \"Ensures gleam.toml has required fields\",\n *   handler: async (toml, { file }) => {\n *     if (!toml.name) {\n *       return { error: \"Missing name field\", fixable: false };\n *     }\n *     return true;\n *   },\n * });\n * ```\n *\n * @alpha\n */\nexport function defineGleamPolicy<C = undefined>(\n\targs: DefineGleamPolicyArgs<C>,\n): PolicyShape<C> {\n\tconst { name, description, handler: gleamHandler, defaultConfig } = args;\n\treturn {\n\t\tname,\n\t\tdescription,\n\t\tmatch: GleamTomlRegexMatch,\n\t\tdefaultConfig,\n\t\thandler: function* (innerArgs) {\n\t\t\tconst content: string = yield* call(() =>\n\t\t\t\treadFile(resolve(innerArgs.root, innerArgs.file), \"utf-8\"),\n\t\t\t);\n\t\t\tconst toml: GleamToml = yield* call(() => parseToml(content));\n\t\t\tconst result = gleamHandler(toml, innerArgs);\n\n\t\t\tif (result instanceof Promise) {\n\t\t\t\treturn yield* call(() => result);\n\t\t\t}\n\t\t\tif (isOperation<PolicyHandlerResult>(result)) {\n\t\t\t\treturn yield* result;\n\t\t\t}\n\t\t\tthrow new Error(`Unexpected handler result type: ${typeof result}`);\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"defineGleamPolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/defineGleamPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAkB,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAO/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAsB5C;;GAEG;AACH,SAAS,WAAW,CAAI,KAAc;IACrC,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAQ,KAA2B,CAAC,IAAI,KAAK,UAAU,CACvD,CAAC;AACH,CAAC;AAmED,MAAM,UAAU,iBAAiB,CAChC,IAA8B;IAE9B,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IACzE,OAAO;QACN,IAAI;QACJ,WAAW;QACX,KAAK,EAAE,mBAAmB;QAC1B,aAAa;QACb,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS;YAC5B,MAAM,IAAI,GAAc,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CACxC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE;gBAC5C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAC7B,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EACvC,OAAO,CACP,CAAC;gBACF,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;YAC3B,CAAC,CAAC,CACF,CAAC;YACF,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAE7C,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;gBAC/B,OAAO,KAAK,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;YACD,IAAI,WAAW,CAAe,MAAM,CAAC,EAAE,CAAC;gBACvC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC;YACtB,CAAC;YACD,MAAM,IAAI,sBAAsB,CAC/B,mCAAmC,OAAO,MAAM,EAAE,CAClD,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { call, type Operation } from \"effection\";\nimport { resolve } from \"pathe\";\nimport { ExecutionContractError } from \"../executionContractError.js\";\nimport { readParsedFile } from \"../fileCache.js\";\nimport { GleamTomlRegexMatch } from \"../policies/constants.js\";\nimport type {\n\tDefinedConfig,\n\tFilePolicyDefinition,\n\tPolicyArgs,\n\tPolicyResult,\n} from \"../policy.js\";\nimport { settlePolicyPromise } from \"../settlePolicyPromise.js\";\nimport { parseToml } from \"./tomlParser.js\";\n\n/**\n * A parsed gleam.toml represented as a record of sections and values.\n *\n * @public\n */\nexport type GleamToml = Record<string, unknown>;\n\n/**\n * A policy handler for gleam.toml policies.\n *\n * @remarks\n * Receives the parsed TOML content and the standard policy arguments.\n *\n * @public\n */\nexport type GleamTomlHandler<C> = (\n\ttoml: GleamToml,\n\targs: PolicyArgs<C>,\n) => Operation<PolicyResult> | Promise<PolicyResult>;\n\n/**\n * Type guard to check if a value is an Effection Operation (generator).\n */\nfunction isOperation<T>(value: unknown): value is Operation<T> {\n\treturn (\n\t\ttypeof value === \"object\" &&\n\t\tvalue !== null &&\n\t\t\"next\" in value &&\n\t\ttypeof (value as { next: unknown }).next === \"function\"\n\t);\n}\n\n/**\n * Input arguments for defining a gleam.toml policy.\n *\n * @public\n */\nexport interface DefineGleamPolicyArgs<C> {\n\t/**\n\t * The name of the policy.\n\t */\n\tname: string;\n\n\t/**\n\t * A description of the policy's purpose.\n\t */\n\tdescription: string;\n\n\t/**\n\t * The handler function that receives the parsed gleam.toml and policy arguments.\n\t */\n\thandler: GleamTomlHandler<C>;\n\n\t/**\n\t * Optional default configuration for the policy.\n\t */\n\tdefaultConfig?: C;\n\trequiresConfig?: boolean;\n}\n\n/**\n * Define a repo policy for gleam.toml files.\n *\n * @remarks\n * This is a helper function that creates a policy pre-configured to match\n * gleam.toml files. The handler receives the parsed TOML content.\n *\n * @param args - Policy metadata, parsed-TOML handler, and optional defaults.\n * @returns A file policy that reads and parses matching gleam.toml files.\n *\n * @example\n * ```typescript\n * const MyGleamPolicy = defineGleamPolicy({\n *   name: \"MyGleamPolicy\",\n *   description: \"Ensures gleam.toml has required fields\",\n *   handler: async (toml, { file }) => {\n *     if (!toml.name) {\n *       return [{ message: \"Missing name field\" }];\n *     }\n *     return [];\n *   },\n * });\n * ```\n *\n * @public\n */\nexport function defineGleamPolicy<C = void>(\n\targs: DefineGleamPolicyArgs<C> & { defaultConfig: DefinedConfig<C> },\n): FilePolicyDefinition<C> & { defaultConfig: DefinedConfig<C> };\n/** Define a Gleam policy that requires explicit configuration. @public */\nexport function defineGleamPolicy<C = void>(\n\targs: DefineGleamPolicyArgs<C> & { requiresConfig: true },\n): FilePolicyDefinition<C> & { requiresConfig: true };\n/** Define a Gleam policy with optional configuration. @public */\nexport function defineGleamPolicy<C = void>(\n\targs: DefineGleamPolicyArgs<C>,\n): FilePolicyDefinition<C>;\nexport function defineGleamPolicy<C = void>(\n\targs: DefineGleamPolicyArgs<C>,\n): FilePolicyDefinition<C> {\n\tconst { name, description, handler: gleamHandler, defaultConfig } = args;\n\treturn {\n\t\tname,\n\t\tdescription,\n\t\tmatch: GleamTomlRegexMatch,\n\t\tdefaultConfig,\n\t\trequiresConfig: args.requiresConfig,\n\t\thandler: function* (innerArgs) {\n\t\t\tconst toml: GleamToml = yield* call(() =>\n\t\t\t\treadParsedFile(innerArgs, \"toml\", async () => {\n\t\t\t\t\tconst content = await readFile(\n\t\t\t\t\t\tresolve(innerArgs.root, innerArgs.file),\n\t\t\t\t\t\t\"utf-8\",\n\t\t\t\t\t);\n\t\t\t\t\treturn parseToml(content);\n\t\t\t\t}),\n\t\t\t);\n\t\t\tconst result = gleamHandler(toml, innerArgs);\n\n\t\t\tif (result instanceof Promise) {\n\t\t\t\treturn yield* settlePolicyPromise(result);\n\t\t\t}\n\t\t\tif (isOperation<PolicyResult>(result)) {\n\t\t\t\treturn yield* result;\n\t\t\t}\n\t\t\tthrow new ExecutionContractError(\n\t\t\t\t`Unexpected handler result type: ${typeof result}`,\n\t\t\t);\n\t\t},\n\t};\n}\n"]}