@standards-kit/conform 0.1.0 → 0.1.3

package/dist/process/scan/validators.d.ts

@@ -0,0 +1,37 @@
+import { type Config } from "../../core/index.js";
+import { type Violation } from "../../core/index.js";
+/** GitHub Ruleset response types */
+interface RulesetBypassActor {
+    actor_id: number | null;
+    actor_type: string;
+    bypass_mode: string;
+}
+interface RulesetRule {
+    type: string;
+    parameters?: {
+        required_approving_review_count?: number;
+        dismiss_stale_reviews_on_push?: boolean;
+        require_code_owner_review?: boolean;
+        required_status_checks?: {
+            context: string;
+        }[];
+        strict_required_status_checks_policy?: boolean;
+    };
+}
+export interface RulesetResponse {
+    id: number;
+    name: string;
+    target: string;
+    enforcement: string;
+    conditions?: {
+        ref_name?: {
+            include?: string[];
+            exclude?: string[];
+        };
+    };
+    bypass_actors?: RulesetBypassActor[];
+    rules?: RulesetRule[];
+}
+/** Validate rulesets against config */
+export declare function validateRulesets(rulesets: RulesetResponse[], repoConfig: NonNullable<Config["process"]>["repo"]): Violation[];
+export {};

package/dist/process/sync/applier.d.ts

@@ -0,0 +1,10 @@
+import { type DesiredBranchProtection, type DesiredTagProtection, type RepoInfo, type SyncDiffResult, type SyncResult, type TagProtectionDiffResult } from "./types.js";
+/** Error thrown when applier encounters an issue */
+export declare class ApplierError extends Error {
+    readonly code: "NO_PERMISSION" | "API_ERROR";
+    constructor(message: string, code: "NO_PERMISSION" | "API_ERROR");
+}
+/** Apply branch protection ruleset to GitHub */
+export declare function applyBranchProtection(repoInfo: RepoInfo, branch: string, desired: DesiredBranchProtection, diffResult: SyncDiffResult): Promise<SyncResult>;
+/** Apply tag protection ruleset to GitHub */
+export declare function applyTagProtection(repoInfo: RepoInfo, desired: DesiredTagProtection, diffResult: TagProtectionDiffResult): Promise<SyncResult>;

package/dist/process/sync/differ.d.ts

@@ -0,0 +1,7 @@
+import { type BranchProtectionSettings, type DesiredBranchProtection, type DesiredTagProtection, type RepoInfo, type SyncDiffResult, type TagProtectionDiffResult, type TagProtectionSettings } from "./types.js";
+/** Compare current settings with desired and generate diffs */
+export declare function computeDiff(repoInfo: RepoInfo, current: BranchProtectionSettings, desired: DesiredBranchProtection): SyncDiffResult;
+/** Format a value for display */
+export declare function formatValue(value: unknown): string;
+/** Compare current tag protection with desired and generate diffs */
+export declare function computeTagDiff(repoInfo: RepoInfo, current: TagProtectionSettings, desired: DesiredTagProtection): TagProtectionDiffResult;

package/dist/process/sync/fetcher.d.ts

@@ -0,0 +1,14 @@
+import { type BranchProtectionSettings, type RepoInfo, type TagProtectionSettings } from "./types.js";
+/** Error thrown when fetcher encounters an issue */
+export declare class FetcherError extends Error {
+    readonly code: "NO_GH" | "NO_REPO" | "NO_PERMISSION" | "API_ERROR";
+    constructor(message: string, code: "NO_GH" | "NO_REPO" | "NO_PERMISSION" | "API_ERROR");
+}
+/** Check if gh CLI is available */
+export declare function isGhAvailable(): Promise<boolean>;
+/** Get repository info from git remote */
+export declare function getRepoInfo(projectRoot: string): Promise<RepoInfo>;
+/** Fetch current branch protection settings from GitHub Rulesets */
+export declare function fetchBranchProtection(repoInfo: RepoInfo, branch: string): Promise<BranchProtectionSettings>;
+/** Fetch current tag protection rulesets from GitHub */
+export declare function fetchTagProtection(repoInfo: RepoInfo): Promise<TagProtectionSettings>;

package/dist/process/sync/index.d.ts

@@ -0,0 +1,9 @@
+import { type SyncOptions } from "./types.js";
+/** Run diff command - show what would change */
+export declare function runDiff(options: SyncOptions): Promise<void>;
+/** Run sync command - apply changes (or preview if --apply not set) */
+export declare function runSync(options: SyncOptions): Promise<void>;
+/** Run tag protection diff command - show what would change */
+export declare function runTagDiff(options: SyncOptions): Promise<void>;
+/** Run tag protection sync command - apply changes (or preview if --apply not set) */
+export declare function runTagSync(options: SyncOptions): Promise<void>;

package/dist/process/sync/types.d.ts

@@ -0,0 +1,131 @@
+/** Bypass actor type for GitHub Rulesets */
+export type BypassActorType = "Integration" | "OrganizationAdmin" | "RepositoryRole" | "Team" | "DeployKey";
+/** Bypass mode - when the actor can bypass */
+export type BypassMode = "always" | "pull_request";
+/** Single bypass actor configuration */
+export interface BypassActor {
+    actor_type: BypassActorType;
+    actor_id?: number;
+    bypass_mode?: BypassMode;
+}
+/** Current branch protection settings from GitHub Ruleset */
+export interface BranchProtectionSettings {
+    branch: string;
+    requiredReviews: number | null;
+    dismissStaleReviews: boolean | null;
+    requireCodeOwnerReviews: boolean | null;
+    requiredStatusChecks: string[] | null;
+    requireBranchesUpToDate: boolean | null;
+    requireSignedCommits: boolean | null;
+    enforceAdmins: boolean | null;
+    bypassActors: BypassActor[] | null;
+    rulesetId: number | null;
+    rulesetName: string | null;
+}
+/** A single setting difference */
+export interface SettingDiff {
+    setting: string;
+    current: unknown;
+    desired: unknown;
+    action: "add" | "change";
+}
+/** Result of comparing current vs. desired settings */
+export interface SyncDiffResult {
+    repoInfo: {
+        owner: string;
+        repo: string;
+    };
+    branch: string;
+    diffs: SettingDiff[];
+    hasChanges: boolean;
+    currentRulesetId: number | null;
+}
+/** Result of applying sync changes */
+export interface SyncResult {
+    success: boolean;
+    applied: SettingDiff[];
+    failed: {
+        diff: SettingDiff;
+        error: string;
+    }[];
+}
+/** Options for sync/diff commands */
+export interface SyncOptions {
+    config?: string;
+    format: "text" | "json";
+    apply?: boolean;
+    validateActors?: boolean;
+}
+/** Repository info */
+export interface RepoInfo {
+    owner: string;
+    repo: string;
+}
+/** Desired branch protection settings from config */
+export interface DesiredBranchProtection {
+    branch?: string;
+    required_reviews?: number;
+    dismiss_stale_reviews?: boolean;
+    require_code_owner_reviews?: boolean;
+    require_status_checks?: string[];
+    require_branches_up_to_date?: boolean;
+    require_signed_commits?: boolean;
+    enforce_admins?: boolean;
+    bypass_actors?: BypassActor[];
+}
+/** GitHub Ruleset bypass actor from API */
+export interface GitHubRulesetBypassActor {
+    actor_id: number | null;
+    actor_type: BypassActorType;
+    bypass_mode: BypassMode;
+}
+/** GitHub Ruleset rule types */
+export type GitHubRulesetRuleType = "deletion" | "update" | "creation" | "pull_request" | "required_status_checks" | "required_signatures" | string;
+/** GitHub Ruleset response */
+export interface GitHubRuleset {
+    id: number;
+    name: string;
+    target: "branch" | "tag";
+    enforcement: "active" | "evaluate" | "disabled";
+    conditions?: {
+        ref_name?: {
+            include?: string[];
+            exclude?: string[];
+        };
+    };
+    bypass_actors?: GitHubRulesetBypassActor[];
+    rules?: {
+        type: GitHubRulesetRuleType;
+        parameters?: {
+            required_approving_review_count?: number;
+            dismiss_stale_reviews_on_push?: boolean;
+            require_code_owner_review?: boolean;
+            required_status_checks?: {
+                context: string;
+            }[];
+            strict_required_status_checks_policy?: boolean;
+            [key: string]: unknown;
+        };
+    }[];
+}
+/** Current tag protection settings from GitHub */
+export interface TagProtectionSettings {
+    patterns: string[];
+    preventDeletion: boolean;
+    preventUpdate: boolean;
+    rulesetId: number | null;
+    rulesetName: string | null;
+}
+/** Desired tag protection settings from config */
+export interface DesiredTagProtection {
+    patterns?: string[];
+    prevent_deletion?: boolean;
+    prevent_update?: boolean;
+}
+/** Tag protection diff result */
+export interface TagProtectionDiffResult {
+    repoInfo: RepoInfo;
+    diffs: SettingDiff[];
+    hasChanges: boolean;
+    currentRulesetId: number | null;
+}

package/dist/process/sync/validator.d.ts

@@ -0,0 +1,22 @@
+import { type RepoInfo } from "./types.js";
+/** Bypass actor configuration from standards.toml */
+export interface BypassActorConfig {
+    actor_type: "Integration" | "OrganizationAdmin" | "RepositoryRole" | "Team" | "DeployKey";
+    actor_id?: number;
+    bypass_mode?: "always" | "pull_request";
+}
+/** Validation error for a single actor */
+export interface ActorValidationError {
+    actor: BypassActorConfig;
+    error: string;
+}
+/** Result of validating bypass actors */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ActorValidationError[];
+    warnings: string[];
+}
+/** Validate bypass actors against GitHub API */
+export declare function validateBypassActors(repoInfo: RepoInfo, actors: BypassActorConfig[]): Promise<ValidationResult>;
+/** Format validation result for display */
+export declare function formatValidationResult(result: ValidationResult): string;

package/dist/process/tools/backups.d.ts

@@ -0,0 +1,32 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import { type CheckResult } from "../../core/index.js";
+import { BaseProcessToolRunner } from "./base.js";
+/** Backups configuration */
+interface BackupsConfig {
+    enabled?: boolean;
+    bucket?: string;
+    prefix?: string;
+    max_age_hours?: number;
+    region?: string;
+}
+/**
+ * Runner for S3 backup verification.
+ * Checks that backups exist in S3 and are recent.
+ */
+export declare class BackupsRunner extends BaseProcessToolRunner {
+    readonly name = "Backups";
+    readonly rule = "process.backups";
+    readonly toolId = "backups";
+    private config;
+    private s3Client;
+    setConfig(config: BackupsConfig): void;
+    /** Allow injecting S3 client for testing */
+    setS3Client(client: S3Client): void;
+    run(_projectRoot: string): Promise<CheckResult>;
+    private checkBackups;
+    private getS3Client;
+    private createExistsViolation;
+    private checkBackupRecency;
+    private findMostRecentBackup;
+}
+export {};

package/dist/process/tools/base.d.ts

@@ -0,0 +1,52 @@
+import { type CheckResult, type IToolRunner, type Violation } from "../../core/index.js";
+/**
+ * Abstract base class for process tool runners.
+ * Provides common functionality for checking files and directories.
+ */
+export declare abstract class BaseProcessToolRunner implements IToolRunner {
+    abstract readonly name: string;
+    abstract readonly rule: string;
+    abstract readonly toolId: string;
+    /** Process tools don't have config files in the same way code tools do */
+    readonly configFiles: string[];
+    /**
+     * Check if a directory exists
+     */
+    protected directoryExists(projectRoot: string, dirPath: string): boolean;
+    /**
+     * Check if a file exists
+     */
+    protected fileExists(projectRoot: string, filePath: string): boolean;
+    /**
+     * Read file contents
+     */
+    protected readFile(projectRoot: string, filePath: string): string | null;
+    /**
+     * Check if a file contains a specific string/pattern
+     */
+    protected fileContains(projectRoot: string, filePath: string, pattern: string): boolean;
+    /**
+     * Create a pass result
+     */
+    protected pass(duration: number): CheckResult;
+    /**
+     * Create a fail result from violations
+     */
+    protected fail(violations: Violation[], duration: number): CheckResult;
+    /**
+     * Create a result from violations (pass if empty, fail otherwise)
+     */
+    protected fromViolations(violations: Violation[], duration: number): CheckResult;
+    /**
+     * Create a skip result
+     */
+    protected skip(reason: string, duration: number): CheckResult;
+    /**
+     * Run the tool - must be implemented by subclasses
+     */
+    abstract run(projectRoot: string): Promise<CheckResult>;
+    /**
+     * Audit the tool - by default same as run for process tools
+     */
+    audit(projectRoot: string): Promise<CheckResult>;
+}

package/dist/process/tools/branches.d.ts

@@ -0,0 +1,41 @@
+import { type CheckResult } from "../../core/index.js";
+import { BaseProcessToolRunner } from "./base.js";
+/** Branches configuration from standards.toml */
+interface BranchesConfig {
+    enabled?: boolean;
+    pattern?: string;
+    exclude?: string[];
+    require_issue?: boolean;
+    issue_pattern?: string;
+}
+/**
+ * Branch naming validation runner.
+ * Checks that the current git branch name matches a required pattern.
+ */
+export declare class BranchesRunner extends BaseProcessToolRunner {
+    readonly name = "Branches";
+    readonly rule = "process.branches";
+    readonly toolId = "branches";
+    private config;
+    /**
+     * Set configuration from standards.toml
+     */
+    setConfig(config: BranchesConfig): void;
+    /** Get the current git branch name */
+    private getCurrentBranch;
+    /** Check if branch is excluded from validation */
+    private isExcluded;
+    /** Validate branch name against pattern */
+    private validateBranchPattern;
+    /** Extract issue number from branch name */
+    private extractIssueNumber;
+    /** Validate that branch contains issue reference */
+    private validateIssueReference;
+    /** Check if any validation is configured */
+    private hasValidationConfigured;
+    /** Collect violations from all validations */
+    private collectViolations;
+    /** Run branch naming validation */
+    run(projectRoot: string): Promise<CheckResult>;
+}
+export {};

package/dist/process/tools/changesets.d.ts

@@ -0,0 +1,53 @@
+import { type CheckResult } from "../../core/index.js";
+import { BaseProcessToolRunner } from "./base.js";
+/** Valid changeset bump types */
+type BumpType = "patch" | "minor" | "major";
+/** Changesets configuration from standards.toml */
+interface ChangesetsConfig {
+    enabled?: boolean;
+    require_for_paths?: string[];
+    exclude_paths?: string[];
+    validate_format?: boolean;
+    allowed_bump_types?: BumpType[];
+    require_description?: boolean;
+    min_description_length?: number;
+}
+/**
+ * Changeset validation runner.
+ * Validates that changeset files exist and are properly formatted.
+ */
+export declare class ChangesetsRunner extends BaseProcessToolRunner {
+    readonly name = "Changesets";
+    readonly rule = "process.changesets";
+    readonly toolId = "changesets";
+    private config;
+    /**
+     * Set configuration from standards.toml
+     */
+    setConfig(config: ChangesetsConfig): void;
+    /** Get list of changeset files (excluding config.json) */
+    private getChangesetFiles;
+    /** Parse a changeset file and extract frontmatter and description */
+    private parseChangesetFile;
+    /** Parse changeset content and populate result */
+    private parseChangesetContent;
+    /** Get files changed in current branch vs main/master */
+    private getChangedFiles;
+    /** Check if any changed files match the require_for_paths patterns */
+    private hasChangesRequiringChangeset;
+    /** Validate changeset format (packages in frontmatter) */
+    private validateFormat;
+    /** Validate bump types against allowed list */
+    private validateBumpTypes;
+    /** Validate description requirements */
+    private validateDescription;
+    /** Validate a single changeset file */
+    private validateChangeset;
+    /** Check if changeset directory exists */
+    private checkDirectoryExists;
+    /** Check if changes require a changeset */
+    private checkChangesRequireChangeset;
+    /** Run changeset validation */
+    run(projectRoot: string): Promise<CheckResult>;
+}
+export {};

package/dist/process/tools/ci.d.ts

@@ -0,0 +1,57 @@
+import { type CheckResult } from "../../core/index.js";
+import { BaseProcessToolRunner } from "./base.js";
+/** Commands configuration value - workflow-level or job-level */
+type CommandsValue = string[] | Record<string, string[]>;
+/** CI configuration from standards.toml */
+interface CiConfig {
+    enabled?: boolean;
+    require_workflows?: string[];
+    jobs?: Record<string, string[]>;
+    actions?: Record<string, string[]>;
+    commands?: Record<string, CommandsValue>;
+}
+/**
+ * CI/CD workflow validation runner.
+ * Checks that GitHub Actions workflows exist and contain required jobs/actions/commands.
+ */
+export declare class CiRunner extends BaseProcessToolRunner {
+    readonly name = "CI";
+    readonly rule = "process.ci";
+    readonly toolId = "ci";
+    private config;
+    setConfig(config: CiConfig): void;
+    private checkWorkflowsDirectory;
+    private checkRequiredWorkflows;
+    private parseWorkflow;
+    private triggersPRToMain;
+    private isUnconditionalExpression;
+    private extractRunCommands;
+    private commandMatches;
+    /** Check if run content has a commented version of the command */
+    private hasCommentedCommand;
+    /** Search for a command in a single step */
+    private searchCommandInStep;
+    private searchCommandInJob;
+    private searchCommandInWorkflow;
+    private cmdViolation;
+    private workflowCmdViolation;
+    private jobCmdViolation;
+    private checkWorkflowLevelCommands;
+    private checkJobLevelCommands;
+    private yamlErrorViolation;
+    private checkWorkflowCommands;
+    private checkRequiredJobs;
+    /**
+     * Parse a GitHub Actions reference to extract the action name.
+     * Handles:
+     * - Standard refs: "actions/checkout@v4" -> "actions/checkout"
+     * - SHA refs: "actions/checkout@abc123" -> "actions/checkout"
+     * - Local actions: "./path/to/action" -> "./path/to/action"
+     * - Docker actions: "docker://image:tag" -> null (excluded)
+     */
+    private parseActionReference;
+    private extractUsedActions;
+    private checkRequiredActions;
+    run(projectRoot: string): Promise<CheckResult>;
+}
+export {};

package/dist/process/tools/codeowners.d.ts

@@ -0,0 +1,68 @@
+import { type CheckResult } from "../../core/index.js";
+import { BaseProcessToolRunner } from "./base.js";
+/** Single CODEOWNERS rule from config */
+interface CodeownersRule {
+    pattern: string;
+    owners: string[];
+}
+/** CODEOWNERS configuration */
+interface CodeownersConfig {
+    enabled?: boolean;
+    rules?: CodeownersRule[];
+}
+/**
+ * Runner for CODEOWNERS file validation.
+ * Validates that CODEOWNERS file exists and contains all required rules.
+ */
+export declare class CodeownersRunner extends BaseProcessToolRunner {
+    readonly name = "CODEOWNERS";
+    readonly rule = "process.codeowners";
+    readonly toolId = "codeowners";
+    private config;
+    setConfig(config: CodeownersConfig): void;
+    /**
+     * Run check - validates CODEOWNERS content matches config
+     */
+    run(projectRoot: string): Promise<CheckResult>;
+    /**
+     * Audit - just checks that CODEOWNERS file exists
+     */
+    audit(projectRoot: string): Promise<CheckResult>;
+    /**
+     * Find CODEOWNERS file in one of the standard locations
+     */
+    private findCodeownersFile;
+    /**
+     * Parse result including both valid rules and malformed line violations
+     */
+    private parseCodeowners;
+    /**
+     * Parse a single CODEOWNERS line into pattern and owners
+     */
+    private parseCodeownersLine;
+    /**
+     * Validate rules against config
+     */
+    private validateRules;
+    /**
+     * Build a map of parsed rules for quick lookup
+     */
+    private buildParsedRuleMap;
+    /**
+     * Check that all configured rules exist with correct owners
+     */
+    private checkMissingRules;
+    /**
+     * Validate a single config rule against parsed rule
+     */
+    private validateConfigRule;
+    /**
+     * Check for rules in CODEOWNERS that aren't in config
+     */
+    private checkExtraRules;
+    /**
+     * Check if two owner arrays match exactly (order-sensitive)
+     */
+    private ownersMatch;
+}
+export {};

package/dist/process/tools/commits.d.ts

@@ -0,0 +1,39 @@
+import { type CheckResult } from "../../core/index.js";
+import { BaseProcessToolRunner } from "./base.js";
+/** Commits configuration from standards.toml */
+interface CommitsConfig {
+    enabled?: boolean;
+    pattern?: string;
+    types?: string[];
+    require_scope?: boolean;
+    max_subject_length?: number;
+}
+/**
+ * Commit message format validation runner.
+ * Validates that commit messages follow conventional commit format or custom patterns.
+ */
+export declare class CommitsRunner extends BaseProcessToolRunner {
+    readonly name = "Commits";
+    readonly rule = "process.commits";
+    readonly toolId = "commits";
+    private config;
+    /**
+     * Set configuration from standards.toml
+     */
+    setConfig(config: CommitsConfig): void;
+    /** Get the HEAD commit message (subject line only) */
+    private getHeadCommitSubject;
+    /** Build conventional commits pattern from config */
+    private buildConventionalPattern;
+    /** Check if text matches a pattern */
+    private matchesPattern;
+    /** Validate the regex pattern is valid */
+    private isValidPattern;
+    /** Check configuration validity */
+    private hasValidConfig;
+    /** Validate commit message format */
+    private validateCommitFormat;
+    /** Run commit message validation */
+    run(projectRoot: string): Promise<CheckResult>;
+}
+export {};

package/dist/process/tools/coverage.d.ts

@@ -0,0 +1,57 @@
+import { type CheckResult } from "../../core/index.js";
+import { BaseProcessToolRunner } from "./base.js";
+/** Coverage configuration from standards.toml */
+interface CoverageConfig {
+    enabled?: boolean;
+    min_threshold?: number;
+    enforce_in?: "ci" | "config" | "both";
+    ci_workflow?: string;
+    ci_job?: string;
+}
+/**
+ * Coverage enforcement runner.
+ * Checks that coverage thresholds are configured in CI workflows and/or config files.
+ */
+export declare class CoverageRunner extends BaseProcessToolRunner {
+    readonly name = "Coverage";
+    readonly rule = "process.coverage";
+    readonly toolId = "coverage";
+    private config;
+    /**
+     * Set configuration from standards.toml
+     */
+    setConfig(config: CoverageConfig): void;
+    /** Check for vitest coverage config */
+    private checkVitestConfig;
+    /** Check jest config file */
+    private checkJestConfigFile;
+    /** Check jest config in package.json */
+    private checkJestPackageJson;
+    /** Check for jest coverage config */
+    private checkJestConfig;
+    /** Check a single nyc config file and return result */
+    private checkSingleNycConfig;
+    /** Check nyc config file */
+    private checkNycConfigFile;
+    /** Check nyc config in package.json */
+    private checkNycPackageJson;
+    /** Check for nyc coverage config */
+    private checkNycConfig;
+    /** Check for coverage config in any supported tool */
+    private checkConfigCoverage;
+    /** Check if a step has coverage enforcement */
+    private stepHasCoverage;
+    /** Check a single job for coverage enforcement */
+    private checkJobForCoverage;
+    /** Check workflow jobs for coverage */
+    private checkWorkflowJobs;
+    /** Check for coverage enforcement in CI workflow */
+    private checkCiCoverage;
+    /** Validate config coverage and add violations if needed */
+    private validateConfigCoverage;
+    /** Validate CI coverage and add violations if needed */
+    private validateCiCoverage;
+    /** Run coverage validation */
+    run(projectRoot: string): Promise<CheckResult>;
+}
+export {};