repopo 0.9.0 → 0.12.0

package/esm/policy.js

@@ -1,31 +1,11 @@
 import { NoJsFileExtensions } from "./policies/NoJsFileExtensions.js";
 import { PackageJsonRepoDirectoryProperty } from "./policies/PackageJsonRepoDirectoryProperty.js";
 import { PackageJsonSorted } from "./policies/PackageJsonSorted.js";
-import { PackageScripts } from "./policies/PackageScripts.js";
-// biome-ignore lint/suspicious/noExplicitAny: type guard
-export function isPolicyFixResult(toCheck) {
-    if (typeof toCheck !== "object" || toCheck === null) {
-        return false;
-    }
-    return "resolved" in toCheck;
-}
-/**
- * Default policies included with repopo.
- *
- * @alpha
- */
-// biome-ignore lint/suspicious/noExplicitAny: FIXME
-export const DefaultPolicies = [
-    NoJsFileExtensions,
-    PackageJsonRepoDirectoryProperty,
-    PackageJsonSorted,
-    PackageScripts,
-];
 /**
  * Abstract base class for creating policies with object-based construction.
  *
  * @remarks
- * This class accepts a {@link PolicyDefinition} object in its constructor,
+ * This class accepts a {@link PolicyShape} object in its constructor,
  * making it easier to add new optional properties in the future without breaking changes.
  *
  * @alpha
@@ -46,4 +26,106 @@ export class Policy {
         this.resolver = definition.resolver;
     }
 }
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard to check if a result is a {@link PolicyFixResult} (legacy).
+ *
+ * @deprecated Use {@link isPolicyError} instead when working with the new {@link PolicyError} format.
+ *
+ * @alpha
+ */
+// biome-ignore lint/suspicious/noExplicitAny: type guard
+export function isPolicyFixResult(toCheck) {
+    if (typeof toCheck !== "object" || toCheck === null) {
+        return false;
+    }
+    return "resolved" in toCheck;
+}
+/**
+ * Type guard to check if a result is a PolicyError (new format).
+ *
+ * @alpha
+ */
+// biome-ignore lint/suspicious/noExplicitAny: type guard
+export function isPolicyError(toCheck) {
+    if (typeof toCheck !== "object" || toCheck === null) {
+        return false;
+    }
+    return "error" in toCheck && typeof toCheck.error === "string";
+}
+/**
+ * Type guard to check if a result is a {@link PolicyFailure} (legacy format).
+ *
+ * @deprecated Use {@link isPolicyError} instead when working with the new {@link PolicyError} format.
+ *
+ * @alpha
+ */
+// biome-ignore lint/suspicious/noExplicitAny: type guard
+export function isPolicyFailure(toCheck) {
+    if (typeof toCheck !== "object" || toCheck === null) {
+        return false;
+    }
+    return "errorMessages" in toCheck && Array.isArray(toCheck.errorMessages);
+}
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+/**
+ * Converts a legacy PolicyFailure/PolicyFixResult to the new PolicyError format.
+ * @internal
+ */
+export function convertLegacyResult(result, _file) {
+    if (result === true) {
+        return true;
+    }
+    // Check if it's already the new format
+    if (isPolicyError(result)) {
+        return result;
+    }
+    // It's a legacy PolicyFailure or PolicyFixResult
+    const error = result.errorMessages?.join("; ") ?? "Policy violation";
+    const isFixResult = isPolicyFixResult(result);
+    return {
+        error,
+        fixable: result.autoFixable ?? false,
+        fixed: isFixResult ? result.resolved : undefined,
+        manualFix: result.manualFix,
+    };
+}
+/**
+ * Converts a new PolicyError to the legacy PolicyFailure format.
+ * @internal
+ */
+export function convertToLegacyResult(result, policyName, file) {
+    const base = {
+        name: policyName,
+        file,
+        autoFixable: result.fixable,
+        errorMessages: [result.error],
+        manualFix: result.manualFix,
+    };
+    if (result.fixed !== undefined) {
+        return {
+            ...base,
+            resolved: result.fixed,
+        };
+    }
+    return base;
+}
+// ============================================================================
+// Default Policies
+// ============================================================================
+/**
+ * Default policies included with repopo.
+ *
+ * @alpha
+ */
+// biome-ignore lint/suspicious/noExplicitAny: FIXME
+export const DefaultPolicies = [
+    NoJsFileExtensions,
+    PackageJsonRepoDirectoryProperty,
+    PackageJsonSorted,
+];
 //# sourceMappingURL=policy.js.map

package/esm/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gCAAgC,EAAE,MAAM,gDAAgD,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAyM9D,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,OAAY;IAC7C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,UAAU,IAAI,OAAO,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AAEH,oDAAoD;AACpD,MAAM,CAAC,MAAM,eAAe,GAA4B;IACvD,kBAAkB;IAClB,gCAAgC;IAChC,iBAAiB;IACjB,cAAc;CACL,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,OAAgB,MAAM;IACX,IAAI,CAAS;IACb,WAAW,CAAS;IACpB,KAAK,CAAS;IACd,OAAO,CAAmB;IAC1B,aAAa,CAAiB;IAC9B,QAAQ,CAA2C;IAEnE,YAAmB,UAA+B;QACjD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAC1C,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC;QAClC,IAAI,CAAC,aAAa,GAAG,UAAU,CAAC,aAAa,CAAC;QAC9C,IAAI,CAAC,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC;IACrC,CAAC;CACD","sourcesContent":["import type { Operation } from \"effection\";\nimport type { RequireExactlyOne } from \"type-fest\";\nimport { NoJsFileExtensions } from \"./policies/NoJsFileExtensions.js\";\nimport { PackageJsonRepoDirectoryProperty } from \"./policies/PackageJsonRepoDirectoryProperty.js\";\nimport { PackageJsonSorted } from \"./policies/PackageJsonSorted.js\";\nimport { PackageScripts } from \"./policies/PackageScripts.js\";\n\n/**\n * A type representing a policy name.\n *\n * @alpha\n */\nexport type PolicyName = string;\n\n/**\n * Arguments passed to policy functions.\n *\n * @alpha\n */\n\nexport interface PolicyFunctionArguments<C> {\n\t/**\n\t * Path to the file, relative to the repo root.\n\t */\n\tfile: string;\n\n\t/**\n\t * Absolute path to the root of the repo.\n\t */\n\troot: string;\n\n\t/**\n\t * If true, the handler should resolve any violations automatically if possible.\n\t */\n\tresolve: boolean;\n\n\t/**\n\t * @remarks\n\t *\n\t * Note that the handler function receives the config as an argument.\n\t */\n\tconfig?: C | undefined;\n}\n\n/**\n * A policy handler function that is called to check policy against a file.\n *\n * @remarks\n * Policy handlers can be implemented in two ways:\n * - As an async function returning a Promise\n * - As an Effection generator function returning an Operation\n *\n * Both styles are supported to allow gradual migration and flexibility.\n *\n * @alpha\n */\nexport type PolicyHandler<C = unknown | undefined> =\n\t| ((args: PolicyFunctionArguments<C>) => Promise<PolicyHandlerResult>)\n\t| ((args: PolicyFunctionArguments<C>) => Operation<PolicyHandlerResult>);\n\n/**\n * A standalone function that can be called to resolve a policy failure.\n *\n * @remarks\n * Resolvers can be implemented in two ways:\n * - As an async function returning a Promise\n * - As an Effection generator function returning an Operation\n *\n * Both styles are supported to allow gradual migration and flexibility.\n *\n * @alpha\n */\nexport type PolicyStandaloneResolver<C = undefined> = (\n\targs: Omit<PolicyFunctionArguments<C>, \"resolve\">,\n) => Promise<PolicyFixResult> | Operation<PolicyFixResult>;\n\n/**\n * A RepoPolicyDefinition checks and applies policies to files in the repository.\n *\n * Each policy has a name and a match regex for matching which files it should apply to. Every file in th repo is\n * enumerated and if it matches the regex for a policy, that policy is applied.\n *\n * Each policy includes a handler function that checks a file against the policy and can optionally resolve any problems\n * (automated resolutions depend on the policy implementation).\n *\n * @typeParam C - type of configuration object used by the policy\n *\n * @alpha\n */\nexport interface PolicyDefinition<C = undefined> {\n\t/**\n\t * The name of the policy; displayed in UI and used in settings.\n\t */\n\tname: PolicyName;\n\n\t/**\n\t * A more detailed description of the policy and its intended function.\n\t */\n\tdescription: string;\n\n\t/**\n\t * A regular expression that is used to match files in the repo.\n\t */\n\tmatch: RegExp;\n\n\t/**\n\t * A handler function that checks if a file is compliant with the policy.\n\t *\n\t * @param file - Repo-relative path to the file to check.\n\t * @param root - Absolute path to the root of the repo.\n\t * @param resolve - If true, automated policy fixes will be applied. Not all policies support automated fixes.\n\t * @returns True if the file passed the policy; otherwise a PolicyFailure object will be returned.\n\t */\n\n\thandler: PolicyHandler<C>;\n\n\t/**\n\t * A resolver function that can be used to automatically address the policy violation.\n\t *\n\t * @param file - Repo-relative path to the file to check.\n\t * @param root - Absolute path to the root of the repo.\n\t * @returns true if the file passed the policy; otherwise a PolicyFailure object will be returned.\n\t */\n\tresolver?: PolicyStandaloneResolver<C> | undefined;\n\n\t/**\n\t * A default config that will be used if none is provided.\n\t */\n\tdefaultConfig?: C | undefined;\n}\n\n/**\n * @alpha\n */\nexport interface PolicyInstanceSettings<C> {\n\t/**\n\t * An array of strings/regular expressions. File paths that match any of these expressions will be completely excluded\n\t * from policy.\n\t *\n\t * Paths will be matched relative to the root of the repo.\n\t */\n\texcludeFiles?: (string | RegExp)[];\n\n\t/**\n\t * The config that is applied to the policy instance.\n\t */\n\tconfig?: C | undefined;\n}\n\n/**\n * @alpha\n */\nexport type PolicyInstance<C = undefined> = RequireExactlyOne<\n\tPolicyDefinition<C> & PolicyInstanceSettings<C>,\n\t\"handler\"\n>;\n\n/**\n * A policy failure.\n *\n * @alpha\n */\nexport interface PolicyFailure {\n\t/**\n\t * Name of the policy that failed.\n\t */\n\tname: PolicyName;\n\n\t/**\n\t * Path to the file that failed the policy.\n\t */\n\tfile: string;\n\n\t/**\n\t * Set to `true` if the policy can be fixed automatically.\n\t */\n\tautoFixable?: boolean | undefined;\n\n\t/**\n\t * An optional error message accompanying the failure.\n\t */\n\terrorMessages: string[];\n\n\t/**\n\t * An optional string that tells the user how to fix the failure(s).\n\t */\n\tmanualFix?: string;\n}\n\n/**\n * The result of an automatic fix for a failing policy.\n *\n * @alpha\n */\nexport interface PolicyFixResult extends PolicyFailure {\n\t/**\n\t * Set to true if the failure was resolved by the automated fixer.\n\t */\n\tresolved: boolean;\n}\n\n/**\n * @alpha\n */\nexport type PolicyHandlerResult = true | PolicyFailure | PolicyFixResult;\n\n// biome-ignore lint/suspicious/noExplicitAny: type guard\nexport function isPolicyFixResult(toCheck: any): toCheck is PolicyFixResult {\n\tif (typeof toCheck !== \"object\" || toCheck === null) {\n\t\treturn false;\n\t}\n\treturn \"resolved\" in toCheck;\n}\n\n/**\n * Default policies included with repopo.\n *\n * @alpha\n */\n\n// biome-ignore lint/suspicious/noExplicitAny: FIXME\nexport const DefaultPolicies: PolicyDefinition<any>[] = [\n\tNoJsFileExtensions,\n\tPackageJsonRepoDirectoryProperty,\n\tPackageJsonSorted,\n\tPackageScripts,\n] as const;\n\n/**\n * Abstract base class for creating policies with object-based construction.\n *\n * @remarks\n * This class accepts a {@link PolicyDefinition} object in its constructor,\n * making it easier to add new optional properties in the future without breaking changes.\n *\n * @alpha\n */\nexport abstract class Policy<C> implements PolicyDefinition<C> {\n\tpublic readonly name: string;\n\tpublic readonly description: string;\n\tpublic readonly match: RegExp;\n\tpublic readonly handler: PolicyHandler<C>;\n\tpublic readonly defaultConfig?: C | undefined;\n\tpublic readonly resolver?: PolicyStandaloneResolver<C> | undefined;\n\n\tpublic constructor(definition: PolicyDefinition<C>) {\n\t\tthis.name = definition.name;\n\t\tthis.description = definition.description;\n\t\tthis.match = definition.match;\n\t\tthis.handler = definition.handler;\n\t\tthis.defaultConfig = definition.defaultConfig;\n\t\tthis.resolver = definition.resolver;\n\t}\n}\n"]}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Operation } from \"effection\";\nimport { NoJsFileExtensions } from \"./policies/NoJsFileExtensions.js\";\nimport { PackageJsonRepoDirectoryProperty } from \"./policies/PackageJsonRepoDirectoryProperty.js\";\nimport { PackageJsonSorted } from \"./policies/PackageJsonSorted.js\";\n\n/**\n * A type representing a policy name.\n *\n * @alpha\n */\nexport type PolicyName = string;\n\n/**\n * A stable identifier for a configured policy instance.\n *\n * @alpha\n */\nexport type PolicyInstanceId = string;\n\n/**\n * Arguments passed to policy handler functions.\n *\n * @alpha\n */\nexport interface PolicyArgs<C = void> {\n\t/**\n\t * Path to the file, relative to the repo root.\n\t */\n\tfile: string;\n\n\t/**\n\t * Absolute path to the root of the repo.\n\t */\n\troot: string;\n\n\t/**\n\t * If true, the handler should resolve any violations automatically if possible.\n\t */\n\tresolve: boolean;\n\n\t/**\n\t * Optional configuration for the policy.\n\t */\n\tconfig?: C | undefined;\n}\n\n/**\n * @deprecated Use {@link PolicyArgs} instead.\n * @alpha\n */\nexport type PolicyFunctionArguments<C> = PolicyArgs<C>;\n\n// ============================================================================\n// New Result Types\n// ============================================================================\n\n/**\n * A policy error returned when a file fails a policy check.\n *\n * @alpha\n */\nexport interface PolicyError {\n\t/**\n\t * The error message describing what failed.\n\t */\n\terror: string;\n\n\t/**\n\t * Set to `true` if the policy violation can be fixed automatically.\n\t */\n\tfixable?: boolean | undefined;\n\n\t/**\n\t * Set to `true` if the violation was successfully fixed (only set when resolve=true).\n\t */\n\tfixed?: boolean | undefined;\n\n\t/**\n\t * An optional string that tells the user how to manually fix the failure.\n\t */\n\tmanualFix?: string | undefined;\n}\n\n/**\n * The result of a policy handler.\n * Returns `true` if the file passes the policy, or a {@link PolicyError} if it fails.\n *\n * @alpha\n */\nexport type PolicyResult = true | PolicyError;\n\n// ============================================================================\n// Legacy Result Types (Still supported for backward compatibility)\n// ============================================================================\n\n/**\n * A policy failure (legacy format).\n *\n * @deprecated Use {@link PolicyError} instead, which has a simpler API.\n *\n * @alpha\n */\nexport interface PolicyFailure {\n\t/**\n\t * Name of the policy that failed.\n\t */\n\tname: PolicyName;\n\n\t/**\n\t * Path to the file that failed the policy.\n\t */\n\tfile: string;\n\n\t/**\n\t * Set to `true` if the policy can be fixed automatically.\n\t */\n\tautoFixable?: boolean | undefined;\n\n\t/**\n\t * An optional error message accompanying the failure.\n\t */\n\terrorMessages: string[];\n\n\t/**\n\t * An optional string that tells the user how to fix the failure(s).\n\t */\n\tmanualFix?: string | undefined;\n}\n\n/**\n * The result of an automatic fix for a failing policy (legacy format).\n *\n * @deprecated Use {@link PolicyError} with `fixed: boolean` instead.\n *\n * @alpha\n */\nexport interface PolicyFixResult extends PolicyFailure {\n\t/**\n\t * Set to true if the failure was resolved by the automated fixer.\n\t */\n\tresolved: boolean;\n}\n\n/**\n * Result type that accepts both legacy and new formats.\n *\n * @alpha\n */\nexport type PolicyHandlerResult =\n\t| true\n\t| PolicyFailure\n\t| PolicyFixResult\n\t| PolicyError;\n\n// ============================================================================\n// Handler Types\n// ============================================================================\n\n/**\n * A policy handler function that checks a file against a policy.\n *\n * @remarks\n * Policy handlers can be implemented in two ways:\n * - As an async function returning a Promise\n * - As an Effection generator function returning an Operation\n *\n * Both styles are supported. Async handlers are automatically wrapped for Effection.\n *\n * Handlers can return either the legacy format ({@link PolicyFailure}) or\n * the new format ({@link PolicyError}). The new format is simpler and recommended\n * for new policies.\n *\n * @alpha\n */\nexport type PolicyHandler<C = unknown | undefined> =\n\t| ((args: PolicyArgs<C>) => Promise<PolicyHandlerResult>)\n\t| ((args: PolicyArgs<C>) => Operation<PolicyHandlerResult>);\n\n/**\n * A standalone resolver function that can fix policy violations (legacy format).\n *\n * @deprecated Use {@link PolicyResolver} instead, which uses {@link PolicyError}.\n *\n * @alpha\n */\nexport type PolicyStandaloneResolver<C = undefined> = (\n\targs: Omit<PolicyArgs<C>, \"resolve\">,\n) => Promise<PolicyFixResult> | Operation<PolicyFixResult>;\n\n/**\n * A standalone resolver function using the new format.\n *\n * @alpha\n */\nexport type PolicyResolver<C = void> = (\n\targs: Omit<PolicyArgs<C>, \"resolve\">,\n) => Promise<PolicyError> | Operation<PolicyError>;\n\n// ============================================================================\n// Policy Definition Types\n// ============================================================================\n\n/**\n * Interface describing the shape of a policy definition.\n *\n * @typeParam C - Type of configuration object used by the policy\n *\n * @alpha\n */\nexport interface PolicyShape<C = void> {\n\t/**\n\t * The name of the policy; displayed in UI and used in settings.\n\t */\n\tname: PolicyName;\n\n\t/**\n\t * A detailed description of the policy and its purpose.\n\t */\n\tdescription: string;\n\n\t/**\n\t * A regular expression that matches files this policy applies to.\n\t */\n\tmatch: RegExp;\n\n\t/**\n\t * The handler function that checks if a file complies with the policy.\n\t */\n\thandler: PolicyHandler<C>;\n\n\t/**\n\t * An optional resolver function that can automatically fix violations.\n\t */\n\tresolver?: PolicyStandaloneResolver<C> | undefined;\n\n\t/**\n\t * A default configuration that will be used if none is provided.\n\t */\n\tdefaultConfig?: C | undefined;\n}\n\n/**\n * Abstract base class for creating policies with object-based construction.\n *\n * @remarks\n * This class accepts a {@link PolicyShape} object in its constructor,\n * making it easier to add new optional properties in the future without breaking changes.\n *\n * @alpha\n */\nexport abstract class Policy<C = void> implements PolicyShape<C> {\n\tpublic readonly name: string;\n\tpublic readonly description: string;\n\tpublic readonly match: RegExp;\n\tpublic readonly handler: PolicyHandler<C>;\n\tpublic readonly defaultConfig?: C | undefined;\n\tpublic readonly resolver?: PolicyStandaloneResolver<C> | undefined;\n\n\tpublic constructor(definition: PolicyShape<C>) {\n\t\tthis.name = definition.name;\n\t\tthis.description = definition.description;\n\t\tthis.match = definition.match;\n\t\tthis.handler = definition.handler;\n\t\tthis.defaultConfig = definition.defaultConfig;\n\t\tthis.resolver = definition.resolver;\n\t}\n}\n\n/**\n * @deprecated Use {@link PolicyShape} instead.\n * @alpha\n */\nexport type PolicyDefinition<C = undefined> = PolicyShape<C>;\n\n/**\n * A policy instance with configuration and exclusion settings applied.\n *\n * @typeParam C - Type of configuration object used by the policy\n *\n * @alpha\n */\nexport interface ConfiguredPolicy<C = void> extends PolicyShape<C> {\n\t/**\n\t * An optional stable identifier for this configured policy instance.\n\t *\n\t * This is required when the same policy definition is configured more than once.\n\t */\n\tinstanceId?: PolicyInstanceId | undefined;\n\n\t/**\n\t * The configuration applied to this policy instance.\n\t */\n\tconfig?: C | undefined;\n\n\t/**\n\t * File paths matching these patterns will be excluded from this policy.\n\t * @deprecated Use `excludeFiles` instead for backward compatibility.\n\t */\n\texclude?: (string | RegExp)[] | undefined;\n\n\t/**\n\t * File paths matching these patterns will be excluded from this policy.\n\t */\n\texcludeFiles?: (string | RegExp)[] | undefined;\n\n\t/**\n\t * Internal normalized handler (always an Effection Operation).\n\t * This is set by the policy() function and used by the execution engine.\n\t * @internal\n\t */\n\t_internalHandler?: (args: PolicyArgs<C>) => Operation<PolicyHandlerResult>;\n}\n\n/**\n * Settings for configuring a policy instance.\n * @alpha\n */\nexport interface PolicyInstanceSettings<C> {\n\t/**\n\t * A stable identifier for this configured policy instance.\n\t */\n\tinstanceId?: PolicyInstanceId | undefined;\n\n\t/**\n\t * An array of strings/regular expressions. File paths that match any of these expressions will be completely excluded\n\t * from policy.\n\t *\n\t * Paths will be matched relative to the root of the repo.\n\t */\n\texcludeFiles?: (string | RegExp)[];\n\n\t/**\n\t * The config that is applied to the policy instance.\n\t */\n\tconfig?: C | undefined;\n}\n\n/**\n * @deprecated Use {@link ConfiguredPolicy} instead.\n * @alpha\n */\nexport type PolicyInstance<C = undefined> = ConfiguredPolicy<C>;\n\n/**\n * A configured policy instance with its runtime identity assigned.\n *\n * @alpha\n */\nexport type IdentifiedPolicy<C = undefined> = ConfiguredPolicy<C> & {\n\tinstanceId: PolicyInstanceId;\n};\n\n// ============================================================================\n// Type Guards\n// ============================================================================\n\n/**\n * Type guard to check if a result is a {@link PolicyFixResult} (legacy).\n *\n * @deprecated Use {@link isPolicyError} instead when working with the new {@link PolicyError} format.\n *\n * @alpha\n */\n// biome-ignore lint/suspicious/noExplicitAny: type guard\nexport function isPolicyFixResult(toCheck: any): toCheck is PolicyFixResult {\n\tif (typeof toCheck !== \"object\" || toCheck === null) {\n\t\treturn false;\n\t}\n\treturn \"resolved\" in toCheck;\n}\n\n/**\n * Type guard to check if a result is a PolicyError (new format).\n *\n * @alpha\n */\n// biome-ignore lint/suspicious/noExplicitAny: type guard\nexport function isPolicyError(toCheck: any): toCheck is PolicyError {\n\tif (typeof toCheck !== \"object\" || toCheck === null) {\n\t\treturn false;\n\t}\n\treturn \"error\" in toCheck && typeof toCheck.error === \"string\";\n}\n\n/**\n * Type guard to check if a result is a {@link PolicyFailure} (legacy format).\n *\n * @deprecated Use {@link isPolicyError} instead when working with the new {@link PolicyError} format.\n *\n * @alpha\n */\n// biome-ignore lint/suspicious/noExplicitAny: type guard\nexport function isPolicyFailure(toCheck: any): toCheck is PolicyFailure {\n\tif (typeof toCheck !== \"object\" || toCheck === null) {\n\t\treturn false;\n\t}\n\treturn \"errorMessages\" in toCheck && Array.isArray(toCheck.errorMessages);\n}\n\n// ============================================================================\n// Conversion Functions\n// ============================================================================\n\n/**\n * Converts a legacy PolicyFailure/PolicyFixResult to the new PolicyError format.\n * @internal\n */\nexport function convertLegacyResult(\n\tresult: PolicyHandlerResult,\n\t_file: string,\n): PolicyResult {\n\tif (result === true) {\n\t\treturn true;\n\t}\n\n\t// Check if it's already the new format\n\tif (isPolicyError(result)) {\n\t\treturn result;\n\t}\n\n\t// It's a legacy PolicyFailure or PolicyFixResult\n\tconst error = result.errorMessages?.join(\"; \") ?? \"Policy violation\";\n\tconst isFixResult = isPolicyFixResult(result);\n\n\treturn {\n\t\terror,\n\t\tfixable: result.autoFixable ?? false,\n\t\tfixed: isFixResult ? result.resolved : undefined,\n\t\tmanualFix: result.manualFix,\n\t};\n}\n\n/**\n * Converts a new PolicyError to the legacy PolicyFailure format.\n * @internal\n */\nexport function convertToLegacyResult(\n\tresult: PolicyError,\n\tpolicyName: string,\n\tfile: string,\n): PolicyFailure | PolicyFixResult {\n\tconst base: PolicyFailure = {\n\t\tname: policyName,\n\t\tfile,\n\t\tautoFixable: result.fixable,\n\t\terrorMessages: [result.error],\n\t\tmanualFix: result.manualFix,\n\t};\n\n\tif (result.fixed !== undefined) {\n\t\treturn {\n\t\t\t...base,\n\t\t\tresolved: result.fixed,\n\t\t} satisfies PolicyFixResult;\n\t}\n\n\treturn base;\n}\n\n// ============================================================================\n// Default Policies\n// ============================================================================\n\n/**\n * Default policies included with repopo.\n *\n * @alpha\n */\n// biome-ignore lint/suspicious/noExplicitAny: FIXME\nexport const DefaultPolicies: Policy<any>[] = [\n\tNoJsFileExtensions,\n\tPackageJsonRepoDirectoryProperty,\n\tPackageJsonSorted,\n] as const;\n"]}

package/esm/policyDefiners/defineCargoPolicy.d.ts

@@ -0,0 +1,66 @@
+import { type Operation } from "effection";
+import type { PolicyArgs, PolicyHandlerResult, PolicyShape } from "../policy.js";
+/**
+ * A parsed Cargo.toml represented as a record of sections and values.
+ *
+ * @alpha
+ */
+export type CargoToml = Record<string, unknown>;
+/**
+ * A policy handler for Cargo.toml policies.
+ *
+ * @remarks
+ * Receives the parsed TOML content and the standard policy arguments.
+ *
+ * @alpha
+ */
+export type CargoTomlHandler<C> = (toml: CargoToml, args: PolicyArgs<C>) => Operation<PolicyHandlerResult> | Promise<PolicyHandlerResult>;
+/**
+ * Input arguments for defining a Cargo.toml policy.
+ *
+ * @alpha
+ */
+export interface DefineCargoPolicyArgs<C> {
+    /**
+     * The name of the policy.
+     */
+    name: string;
+    /**
+     * A description of the policy's purpose.
+     */
+    description: string;
+    /**
+     * The handler function that receives the parsed Cargo.toml and policy arguments.
+     */
+    handler: CargoTomlHandler<C>;
+    /**
+     * Optional default configuration for the policy.
+     */
+    defaultConfig?: C;
+}
+/**
+ * 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 declare function defineCargoPolicy<C = undefined>(args: DefineCargoPolicyArgs<C>): PolicyShape<C>;
+//# sourceMappingURL=defineCargoPolicy.d.ts.map

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

@@ -0,0 +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"}

package/esm/policyDefiners/defineCargoPolicy.js

@@ -0,0 +1,60 @@
+import { readFile } from "node:fs/promises";
+import { call } from "effection";
+import { resolve } from "pathe";
+import { CargoTomlRegexMatch } from "../policies/constants.js";
+import { parseToml } from "./tomlParser.js";
+/**
+ * Type guard to check if a value is an Effection Operation (generator).
+ */
+function isOperation(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "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 {
+        name,
+        description,
+        match: CargoTomlRegexMatch,
+        defaultConfig,
+        handler: function* (innerArgs) {
+            const content = yield* call(() => readFile(resolve(innerArgs.root, innerArgs.file), "utf-8"));
+            const toml = yield* call(() => parseToml(content));
+            const result = cargoHandler(toml, innerArgs);
+            if (result instanceof Promise) {
+                return yield* call(() => result);
+            }
+            if (isOperation(result)) {
+                return yield* result;
+            }
+            throw new Error(`Unexpected handler result type: ${typeof result}`);
+        },
+    };
+}
+//# sourceMappingURL=defineCargoPolicy.js.map

package/esm/policyDefiners/defineCargoPolicy.js.map

@@ -0,0 +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"]}

package/esm/policyDefiners/defineFileHeaderPolicy.d.ts

@@ -1,4 +1,4 @@
-import type { PolicyDefinition } from "../policy.js";
+import type { PolicyShape } from "../policy.js";
 /**
  * @alpha
  */
@@ -83,5 +83,10 @@ export interface DefineFileHeaderPolicyArgs {
  *
  * @alpha
  */
-export declare function defineFileHeaderPolicy(args: DefineFileHeaderPolicyArgs): PolicyDefinition<FileHeaderPolicyConfig>;
+export declare function defineFileHeaderPolicy(args: DefineFileHeaderPolicyArgs): PolicyShape<FileHeaderPolicyConfig>;
+/**
+ * Alias for defineFileHeaderPolicy.
+ * @alpha
+ */
+export declare const fileHeaderPolicy: typeof defineFileHeaderPolicy;
 //# 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,EACX,gBAAgB,EAGhB,MAAM,cAAc,CAAC;AAItB;;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,gBAAgB,CAAC,sBAAsB,CAAC,CAoE1C"}
+{"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"}

package/esm/policyDefiners/defineFileHeaderPolicy.js

@@ -1,7 +1,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { EOL as newline } from "node:os";
 import { call } from "effection";
-import { extname } from "pathe";
+import { extname, resolve as resolvePath } from "pathe";
 const trailingSpaces = /\s*\\r\?\\n/;
 /**
  * Given a {@link FileHeaderPolicyConfig}, produces a function that detects correct file headers
@@ -31,17 +31,15 @@ export function defineFileHeaderPolicy(args) {
         .map((line) => `${start}${line.replace(/[$()*+.?[\\\]^{|}]/g, "\\$&")}${end}`)
         .join("")
         .replace(trailingSpaces, "\\r?\\n"); // Trim trailing spaces at end-of-line.
-    // Detection regex matches the header start (if any), followed by lines in 'headerText',
-    // optionally followed by lines in the 'autoGenText', and finally the header end (if any).
-    const regex = new RegExp(`^${pre}${toRegex(config.headerText ?? "")}(${toRegex(config.autoGenText ?? "")})?${post}`);
     return {
         name,
         description,
         match: config.match,
-        handler: function* ({ file, resolve, config: policyConfig }) {
+        handler: function* ({ file, root, resolve, config: policyConfig }) {
             if (policyConfig === undefined) {
                 return true;
             }
+            const regex = new RegExp(`^${pre}${toRegex(policyConfig.headerText)}(${toRegex(policyConfig.autoGenText ?? config.autoGenText ?? "")})?${post}`);
             const failResult = {
                 name,
                 file,
@@ -50,7 +48,8 @@ export function defineFileHeaderPolicy(args) {
             };
             // TODO: Consider reading only the first 512B or so since headers are typically
             // at the beginning of the file.
-            const content = yield* call(() => readFile(file, { encoding: "utf8" }));
+            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`);
@@ -58,7 +57,7 @@ export function defineFileHeaderPolicy(args) {
             if (failed) {
                 if (resolve) {
                     const newContent = config.replacer(content, policyConfig);
-                    yield* call(() => writeFile(file, newContent));
+                    yield* call(() => writeFile(filePath, newContent));
                     const fixResult = {
                         ...failResult,
                         resolved: true,
@@ -71,4 +70,9 @@ export function defineFileHeaderPolicy(args) {
         },
     };
 }
+/**
+ * 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 } from \"pathe\";\nimport type {\n\tPolicyDefinition,\n\tPolicyFailure,\n\tPolicyFixResult,\n} 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): PolicyDefinition<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\t// Detection regex matches the header start (if any), followed by lines in 'headerText',\n\t// optionally followed by lines in the 'autoGenText', and finally the header end (if any).\n\tconst regex = new RegExp(\n\t\t`^${pre}${toRegex(config.headerText ?? \"\")}(${toRegex(config.autoGenText ?? \"\")})?${post}`,\n\t);\n\n\treturn {\n\t\tname,\n\t\tdescription,\n\t\tmatch: config.match,\n\t\thandler: function* ({ file, resolve, config: policyConfig }) {\n\t\t\tif (policyConfig === undefined) {\n\t\t\t\treturn true;\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 content = yield* call(() => readFile(file, { encoding: \"utf8\" }));\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(file, 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"]}
+{"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"]}

package/esm/policyDefiners/defineGleamPolicy.d.ts

@@ -0,0 +1,65 @@
+import { type Operation } from "effection";
+import type { PolicyArgs, PolicyHandlerResult, PolicyShape } from "../policy.js";
+/**
+ * A parsed gleam.toml represented as a record of sections and values.
+ *
+ * @alpha
+ */
+export type GleamToml = Record<string, unknown>;
+/**
+ * A policy handler for gleam.toml policies.
+ *
+ * @remarks
+ * Receives the parsed TOML content and the standard policy arguments.
+ *
+ * @alpha
+ */
+export type GleamTomlHandler<C> = (toml: GleamToml, args: PolicyArgs<C>) => Operation<PolicyHandlerResult> | Promise<PolicyHandlerResult>;
+/**
+ * Input arguments for defining a gleam.toml policy.
+ *
+ * @alpha
+ */
+export interface DefineGleamPolicyArgs<C> {
+    /**
+     * The name of the policy.
+     */
+    name: string;
+    /**
+     * A description of the policy's purpose.
+     */
+    description: string;
+    /**
+     * The handler function that receives the parsed gleam.toml and policy arguments.
+     */
+    handler: GleamTomlHandler<C>;
+    /**
+     * Optional default configuration for the policy.
+     */
+    defaultConfig?: C;
+}
+/**
+ * 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 declare function defineGleamPolicy<C = undefined>(args: DefineGleamPolicyArgs<C>): PolicyShape<C>;
+//# sourceMappingURL=defineGleamPolicy.d.ts.map

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

@@ -0,0 +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"}

package/esm/policyDefiners/defineGleamPolicy.js

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import { call } from "effection";
+import { resolve } from "pathe";
+import { GleamTomlRegexMatch } from "../policies/constants.js";
+import { parseToml } from "./tomlParser.js";
+/**
+ * Type guard to check if a value is an Effection Operation (generator).
+ */
+function isOperation(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "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 {
+        name,
+        description,
+        match: GleamTomlRegexMatch,
+        defaultConfig,
+        handler: function* (innerArgs) {
+            const content = yield* call(() => readFile(resolve(innerArgs.root, innerArgs.file), "utf-8"));
+            const toml = yield* call(() => parseToml(content));
+            const result = gleamHandler(toml, innerArgs);
+            if (result instanceof Promise) {
+                return yield* call(() => result);
+            }
+            if (isOperation(result)) {
+                return yield* result;
+            }
+            throw new Error(`Unexpected handler result type: ${typeof result}`);
+        },
+    };
+}
+//# sourceMappingURL=defineGleamPolicy.js.map

package/esm/policyDefiners/defineGleamPolicy.js.map

@@ -0,0 +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"]}