repopo 0.8.0 → 0.10.0

package/esm/policy.d.ts

@@ -1,3 +1,4 @@
+import type { Operation } from "effection";
 /**
  * A type representing a policy name.
  *
@@ -5,11 +6,11 @@
  */
 export type PolicyName = string;
 /**
- * Arguments passed to policy functions.
+ * Arguments passed to policy handler functions.
  *
  * @alpha
  */
-export interface PolicyFunctionArguments<C> {
+export interface PolicyArgs<C = void> {
     /**
      * Path to the file, relative to the repo root.
      */
@@ -23,148 +24,266 @@ export interface PolicyFunctionArguments<C> {
      */
     resolve: boolean;
     /**
-     * @remarks
-     *
-     * Note that the handler function receives the config as an argument.
+     * Optional configuration for the policy.
      */
     config?: C | undefined;
 }
 /**
- * A policy handler is a function that is called to check policy against a file.
+ * @deprecated Use {@link PolicyArgs} instead.
+ * @alpha
+ */
+export type PolicyFunctionArguments<C> = PolicyArgs<C>;
+/**
+ * A policy error returned when a file fails a policy check.
  *
  * @alpha
  */
-export type PolicyHandler<C = unknown | undefined> = (args: PolicyFunctionArguments<C>) => Promise<PolicyHandlerResult>;
+export interface PolicyError {
+    /**
+     * The error message describing what failed.
+     */
+    error: string;
+    /**
+     * Set to `true` if the policy violation can be fixed automatically.
+     */
+    fixable?: boolean | undefined;
+    /**
+     * Set to `true` if the violation was successfully fixed (only set when resolve=true).
+     */
+    fixed?: boolean | undefined;
+    /**
+     * An optional string that tells the user how to manually fix the failure.
+     */
+    manualFix?: string | undefined;
+}
 /**
- * A standalone function that can be called to resolve a policy failure.
+ * The result of a policy handler.
+ * Returns `true` if the file passes the policy, or a {@link PolicyError} if it fails.
  *
  * @alpha
  */
-export type PolicyStandaloneResolver<C = undefined> = (args: Omit<PolicyFunctionArguments<C>, "resolve">) => Promise<PolicyFixResult>;
+export type PolicyResult = true | PolicyError;
 /**
- * A RepoPolicyDefinition checks and applies policies to files in the repository.
+ * A policy failure (legacy format).
  *
- * Each policy has a name and a match regex for matching which files it should apply to. Every file in th repo is
- * enumerated and if it matches the regex for a policy, that policy is applied.
+ * @deprecated Use {@link PolicyError} instead, which has a simpler API.
  *
- * Each policy includes a handler function that checks a file against the policy and can optionally resolve any problems
- * (automated resolutions depend on the policy implementation).
+ * @alpha
+ */
+export interface PolicyFailure {
+    /**
+     * Name of the policy that failed.
+     */
+    name: PolicyName;
+    /**
+     * Path to the file that failed the policy.
+     */
+    file: string;
+    /**
+     * Set to `true` if the policy can be fixed automatically.
+     */
+    autoFixable?: boolean | undefined;
+    /**
+     * An optional error message accompanying the failure.
+     */
+    errorMessages: string[];
+    /**
+     * An optional string that tells the user how to fix the failure(s).
+     */
+    manualFix?: string | undefined;
+}
+/**
+ * The result of an automatic fix for a failing policy (legacy format).
  *
- * @typeParam C - type of configuration object used by the policy
+ * @deprecated Use {@link PolicyError} with `fixed: boolean` instead.
  *
  * @alpha
  */
-export interface PolicyDefinition<C = undefined> {
+export interface PolicyFixResult extends PolicyFailure {
+    /**
+     * Set to true if the failure was resolved by the automated fixer.
+     */
+    resolved: boolean;
+}
+/**
+ * Result type that accepts both legacy and new formats.
+ *
+ * @alpha
+ */
+export type PolicyHandlerResult = true | PolicyFailure | PolicyFixResult | PolicyError;
+/**
+ * A policy handler function that checks a file against a policy.
+ *
+ * @remarks
+ * Policy handlers can be implemented in two ways:
+ * - As an async function returning a Promise
+ * - As an Effection generator function returning an Operation
+ *
+ * Both styles are supported. Async handlers are automatically wrapped for Effection.
+ *
+ * Handlers can return either the legacy format ({@link PolicyFailure}) or
+ * the new format ({@link PolicyError}). The new format is simpler and recommended
+ * for new policies.
+ *
+ * @alpha
+ */
+export type PolicyHandler<C = unknown | undefined> = ((args: PolicyArgs<C>) => Promise<PolicyHandlerResult>) | ((args: PolicyArgs<C>) => Operation<PolicyHandlerResult>);
+/**
+ * A standalone resolver function that can fix policy violations (legacy format).
+ *
+ * @deprecated Use {@link PolicyResolver} instead, which uses {@link PolicyError}.
+ *
+ * @alpha
+ */
+export type PolicyStandaloneResolver<C = undefined> = (args: Omit<PolicyArgs<C>, "resolve">) => Promise<PolicyFixResult> | Operation<PolicyFixResult>;
+/**
+ * A standalone resolver function using the new format.
+ *
+ * @alpha
+ */
+export type PolicyResolver<C = void> = (args: Omit<PolicyArgs<C>, "resolve">) => Promise<PolicyError> | Operation<PolicyError>;
+/**
+ * Interface describing the shape of a policy definition.
+ *
+ * @typeParam C - Type of configuration object used by the policy
+ *
+ * @alpha
+ */
+export interface PolicyShape<C = void> {
     /**
      * The name of the policy; displayed in UI and used in settings.
      */
     name: PolicyName;
     /**
-     * A more detailed description of the policy and its intended function.
+     * A detailed description of the policy and its purpose.
      */
-    description?: string | undefined;
+    description: string;
     /**
-     * A regular expression that is used to match files in the repo.
+     * A regular expression that matches files this policy applies to.
      */
     match: RegExp;
     /**
-     * A handler function that checks if a file is compliant with the policy.
-     *
-     * @param file - Repo-relative path to the file to check.
-     * @param root - Absolute path to the root of the repo.
-     * @param resolve - If true, automated policy fixes will be applied. Not all policies support automated fixes.
-     * @returns True if the file passed the policy; otherwise a PolicyFailure object will be returned.
+     * The handler function that checks if a file complies with the policy.
      */
     handler: PolicyHandler<C>;
     /**
-     * A resolver function that can be used to automatically address the policy violation.
-     *
-     * @param file - Repo-relative path to the file to check.
-     * @param root - Absolute path to the root of the repo.
-     * @returns true if the file passed the policy; otherwise a PolicyFailure object will be returned.
+     * An optional resolver function that can automatically fix violations.
      */
     resolver?: PolicyStandaloneResolver<C> | undefined;
     /**
-     * A default config that will be used if none is provided.
+     * A default configuration that will be used if none is provided.
      */
     defaultConfig?: C | undefined;
 }
 /**
+ * Abstract base class for creating policies with object-based construction.
+ *
+ * @remarks
+ * 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
  */
-export interface PolicyInstanceSettings<C> {
-    /**
-     * An array of strings/regular expressions. File paths that match any of these expressions will be completely excluded
-     * from policy.
-     *
-     * Paths will be matched relative to the root of the repo.
-     */
-    excludeFiles?: (string | RegExp)[];
-    /**
-     * The config that is applied to the policy instance.
-     */
-    config?: C | undefined;
+export declare abstract class Policy<C = void> implements PolicyShape<C> {
+    readonly name: string;
+    readonly description: string;
+    readonly match: RegExp;
+    readonly handler: PolicyHandler<C>;
+    readonly defaultConfig?: C | undefined;
+    readonly resolver?: PolicyStandaloneResolver<C> | undefined;
+    constructor(definition: PolicyShape<C>);
 }
 /**
+ * @deprecated Use {@link PolicyShape} instead.
  * @alpha
  */
-export type PolicyInstance<C = undefined> = PolicyDefinition<C> & PolicyInstanceSettings<C>;
+export type PolicyDefinition<C = undefined> = PolicyShape<C>;
 /**
- * A policy failure.
+ * A policy instance with configuration and exclusion settings applied.
+ *
+ * @typeParam C - Type of configuration object used by the policy
  *
  * @alpha
  */
-export interface PolicyFailure {
+export interface ConfiguredPolicy<C = void> extends PolicyShape<C> {
     /**
-     * Name of the policy that failed.
+     * The configuration applied to this policy instance.
      */
-    name: PolicyName;
+    config?: C | undefined;
     /**
-     * Path to the file that failed the policy.
+     * File paths matching these patterns will be excluded from this policy.
+     * @deprecated Use `excludeFiles` instead for backward compatibility.
      */
-    file: string;
+    exclude?: (string | RegExp)[] | undefined;
     /**
-     * Set to `true` if the policy can be fixed automatically.
+     * File paths matching these patterns will be excluded from this policy.
      */
-    autoFixable?: boolean | undefined;
+    excludeFiles?: (string | RegExp)[] | undefined;
     /**
-     * An optional error message accompanying the failure.
-     */
-    errorMessages: string[];
-    /**
-     * An optional string that tells the user how to fix the failure(s).
+     * Internal normalized handler (always an Effection Operation).
+     * This is set by the policy() function and used by the execution engine.
+     * @internal
      */
-    manualFix?: string;
+    _internalHandler?: (args: PolicyArgs<C>) => Operation<PolicyHandlerResult>;
 }
 /**
- * The result of an automatic fix for a failing policy.
- *
+ * Settings for configuring a policy instance.
  * @alpha
  */
-export interface PolicyFixResult extends PolicyFailure {
+export interface PolicyInstanceSettings<C> {
     /**
-     * Set to true if the failure was resolved by the automated fixer.
+     * An array of strings/regular expressions. File paths that match any of these expressions will be completely excluded
+     * from policy.
+     *
+     * Paths will be matched relative to the root of the repo.
      */
-    resolved: boolean;
+    excludeFiles?: (string | RegExp)[];
+    /**
+     * The config that is applied to the policy instance.
+     */
+    config?: C | undefined;
 }
 /**
+ * @deprecated Use {@link ConfiguredPolicy} instead.
+ * @alpha
+ */
+export type PolicyInstance<C = undefined> = ConfiguredPolicy<C>;
+/**
+ * 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
  */
-export type PolicyHandlerResult = true | PolicyFailure | PolicyFixResult;
 export declare function isPolicyFixResult(toCheck: any): toCheck is PolicyFixResult;
+/**
+ * Type guard to check if a result is a PolicyError (new format).
+ *
+ * @alpha
+ */
+export declare function isPolicyError(toCheck: any): toCheck is PolicyError;
+/**
+ * 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
+ */
+export declare function isPolicyFailure(toCheck: any): toCheck is PolicyFailure;
+/**
+ * Converts a legacy PolicyFailure/PolicyFixResult to the new PolicyError format.
+ * @internal
+ */
+export declare function convertLegacyResult(result: PolicyHandlerResult, _file: string): PolicyResult;
+/**
+ * Converts a new PolicyError to the legacy PolicyFailure format.
+ * @internal
+ */
+export declare function convertToLegacyResult(result: PolicyError, policyName: string, file: string): PolicyFailure | PolicyFixResult;
 /**
  * Default policies included with repopo.
  *
  * @alpha
  */
-export declare const DefaultPolicies: PolicyDefinition<any>[];
-export declare abstract class Policy<C> implements PolicyDefinition<C> {
-    readonly name: string;
-    readonly match: RegExp;
-    readonly handler: PolicyHandler<C>;
-    readonly description?: string | undefined;
-    readonly defaultConfig?: C | undefined;
-    readonly resolver?: PolicyStandaloneResolver<C> | undefined;
-    constructor(name: string, match: RegExp, handler: PolicyHandler<C>, description?: string | undefined, defaultConfig?: C | undefined, resolver?: PolicyStandaloneResolver<C> | undefined);
-}
+export declare const DefaultPolicies: Policy<any>[];
 //# sourceMappingURL=policy.d.ts.map

package/esm/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/esm/policy.js

@@ -1,14 +1,122 @@
 import { NoJsFileExtensions } from "./policies/NoJsFileExtensions.js";
 import { PackageJsonRepoDirectoryProperty } from "./policies/PackageJsonRepoDirectoryProperty.js";
 import { PackageJsonSorted } from "./policies/PackageJsonSorted.js";
-import { PackageScripts } from "./policies/PackageScripts.js";
+/**
+ * Abstract base class for creating policies with object-based construction.
+ *
+ * @remarks
+ * 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
+ */
+export class Policy {
+    name;
+    description;
+    match;
+    handler;
+    defaultConfig;
+    resolver;
+    constructor(definition) {
+        this.name = definition.name;
+        this.description = definition.description;
+        this.match = definition.match;
+        this.handler = definition.handler;
+        this.defaultConfig = definition.defaultConfig;
+        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") {
+    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.
  *
@@ -19,22 +127,5 @@ export const DefaultPolicies = [
     NoJsFileExtensions,
     PackageJsonRepoDirectoryProperty,
     PackageJsonSorted,
-    PackageScripts,
 ];
-export class Policy {
-    name;
-    match;
-    handler;
-    description;
-    defaultConfig;
-    resolver;
-    constructor(name, match, handler, description, defaultConfig, resolver) {
-        this.name = name;
-        this.match = match;
-        this.handler = handler;
-        this.description = description;
-        this.defaultConfig = defaultConfig;
-        this.resolver = resolver;
-    }
-}
 //# sourceMappingURL=policy.js.map

package/esm/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA,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;AAiM9D,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,OAAY;IAC7C,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACjC,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,MAAM,OAAgB,MAAM;IAEV;IACA;IACA;IACA;IACA;IACA;IANjB,YACiB,IAAY,EACZ,KAAa,EACb,OAAyB,EACzB,WAAoB,EACpB,aAAiB,EACjB,QAAsC;QALtC,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAQ;QACb,YAAO,GAAP,OAAO,CAAkB;QACzB,gBAAW,GAAX,WAAW,CAAS;QACpB,kBAAa,GAAb,aAAa,CAAI;QACjB,aAAQ,GAAR,QAAQ,CAA8B;IACpD,CAAC;CACJ","sourcesContent":["import { 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 is a function that is called to check policy against a file.\n *\n * @alpha\n */\n\nexport type PolicyHandler<C = unknown | undefined> = (\n\targs: PolicyFunctionArguments<C>,\n) => Promise<PolicyHandlerResult>;\n\n// export type PolicyCheckOnly = (\n// \tfile: string,\n// \troot: string,\n// ) => Promise<PolicyHandlerResult>;\n\n/**\n * A standalone function that can be called to resolve a policy failure.\n *\n * @alpha\n */\nexport type PolicyStandaloneResolver<C = undefined> = (\n\targs: Omit<PolicyFunctionArguments<C>, \"resolve\">,\n) => Promise<PolicyFixResult>;\n\n// function isPolicyHandler(input: PolicyHandler | PolicyCheckOnly): input is PolicyHandler\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 | undefined;\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> = PolicyDefinition<C> &\n\tPolicyInstanceSettings<C>;\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\") {\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\nexport abstract class Policy<C> implements PolicyDefinition<C> {\n\tpublic constructor(\n\t\tpublic readonly name: string,\n\t\tpublic readonly match: RegExp,\n\t\tpublic readonly handler: PolicyHandler<C>,\n\t\tpublic readonly description?: string,\n\t\tpublic readonly defaultConfig?: C,\n\t\tpublic readonly resolver?: PolicyStandaloneResolver<C>,\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 * 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 * 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 * 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// 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/defineFileHeaderPolicy.d.ts

@@ -1,4 +1,4 @@
-import type { PolicyDefinition } from "../policy.js";
+import type { PolicyShape } from "../policy.js";
 /**
  * @alpha
  */
@@ -13,9 +13,16 @@ export interface FileHeaderPolicyConfig {
     autoGenText?: string;
 }
 /**
+ * Configuration for generating file headers with specific formatting rules.
+ *
+ * @remarks
+ * This interface extends FileHeaderPolicyConfig and adds formatting-specific
+ * properties to control how headers are inserted into different file types.
+ *
  * @alpha
  */
 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`)
@@ -33,13 +40,53 @@ export interface FileHeaderGeneratorConfig extends Partial<FileHeaderPolicyConfi
      * Regex matching the header postfix.
      */
     headerEnd?: RegExp;
+    /**
+     * Function that generates the properly formatted header content for insertion into files.
+     *
+     * @param content - The original file content
+     * @param config - The file header policy configuration
+     * @returns The formatted header string to insert
+     */
     replacer: (content: string, config: FileHeaderPolicyConfig) => string;
 }
+/**
+ * Input arguments for defining a file header policy.
+ *
+ * @alpha
+ */
+export interface DefineFileHeaderPolicyArgs {
+    /**
+     * The name of the policy.
+     */
+    name: string;
+    /**
+     * A description of the policy's purpose.
+     */
+    description: string;
+    /**
+     * Configuration for how headers are detected and inserted.
+     */
+    config: FileHeaderGeneratorConfig;
+}
 /**
  * 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 declare function defineFileHeaderPolicy(args: DefineFileHeaderPolicyArgs): PolicyShape<FileHeaderPolicyConfig>;
+/**
+ * Alias for defineFileHeaderPolicy.
  * @alpha
  */
-export declare function defineFileHeaderPolicy(name: string, config: FileHeaderGeneratorConfig): PolicyDefinition<FileHeaderPolicyConfig>;
+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":"AAGA,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;;GAEG;AACH,MAAM,WAAW,yBAChB,SAAQ,OAAO,CAAC,sBAAsB,CAAC;IACvC,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,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,KAAK,MAAM,CAAC;CACtE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,yBAAyB,GAC/B,gBAAgB,CAAC,sBAAsB,CAAC,CAkE1C"}
+{"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,CAoErC;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,+BAAyB,CAAC"}