/**
 * Explicit type definitions for ContractSpec configuration.
 *
 * These interfaces mirror the Zod schemas in `contractsrc-schema.ts` but are
 * statically defined to reduce compiler inference cost and memory usage.
 */
import type { ContractSpecType } from '../types';
import type { AgentTarget as VersioningAgentTarget, ReleaseEnforceOn as VersioningReleaseEnforceOn } from '../versioning/release-types';
export type AgentTarget = VersioningAgentTarget;
export type ReleaseEnforceOn = VersioningReleaseEnforceOn;
export type SchemaFormat = 'contractspec' | 'zod' | 'json-schema' | 'graphql';
export type GroupingStrategy = 'by-tag' | 'by-owner' | 'by-domain' | 'by-url-path-single' | 'by-url-path-multi' | 'by-feature' | 'none';
export type FormatterType = 'biome' | 'dprint' | 'custom';
export type BumpStrategy = 'impact' | 'conventional';
export type ChangelogFormat = 'keep-a-changelog' | 'conventional' | 'custom';
export type ChangelogTier = 'spec' | 'library' | 'monorepo';
export type RuleSyncTarget = 'cursor' | 'windsurf' | 'cline' | 'claude-code' | 'copilot' | 'subagent' | 'skill';
export type RuleSeverity = 'off' | 'warn' | 'error';
export type SpecKind = ContractSpecType;
export type TestLinkingStrategy = 'target-first' | 'convention-only' | 'both';
export type AgentProvider = 'claude' | 'openai' | 'ollama' | 'mistral' | 'custom';
export type AgentMode = 'simple' | 'cursor' | 'claude-code' | 'openai-codex' | 'claude-agent-sdk' | 'opencode' | 'opencode-sdk';
export interface OpenApiSourceConfig {
    /** Friendly name for the source */
    name: string;
    /** Remote URL to fetch OpenAPI spec from */
    url?: string;
    /** Local file path to OpenAPI spec */
    file?: string;
    /** Sync mode: import (one-time), sync (update), validate (check only) */
    syncMode?: 'import' | 'sync' | 'validate';
    /** Only import operations with these tags */
    tags?: string[];
    /** Exclude operations with these operationIds */
    exclude?: string[];
    /** Include operations with these operationIds (overrides exclude) */
    include?: string[];
    /** Prefix for generated spec names */
    prefix?: string;
    /** Default stability for imported specs */
    defaultStability?: 'experimental' | 'beta' | 'stable' | 'deprecated';
    /** Default auth level for imported specs */
    defaultAuth?: 'anonymous' | 'user' | 'admin';
    /** Default owners for imported specs */
    defaultOwners?: string[];
    /** Output schema format for generated models */
    schemaFormat?: SchemaFormat;
}
export interface OpenApiExportConfig {
    /** Output path for exported OpenAPI document */
    outputPath?: string;
    /** Output format */
    format?: 'json' | 'yaml';
    /** API title for export */
    title?: string;
    /** API version for export */
    version?: string;
    /** API description for export */
    description?: string;
    /** Server URLs to include in export */
    servers?: {
        url: string;
        description?: string;
    }[];
}
export interface OpenApiConfig {
    /** External OpenAPI sources to import/sync from */
    sources?: OpenApiSourceConfig[];
    /** Export configuration */
    export?: OpenApiExportConfig;
}
export interface GroupingRule {
    /** Grouping strategy to apply */
    strategy: GroupingStrategy;
    /** For url-path strategies, the level depth (default: 1) */
    urlPathLevel?: number;
    /** Custom key extraction pattern (regex or glob) */
    pattern?: string;
}
export interface FolderConventions {
    models?: string;
    operations?: string;
    events?: string;
    presentations?: string;
    forms?: string;
    capabilities?: string;
    policies?: string;
    tests?: string;
    translations?: string;
    /** Enable feature/module folder grouping (default: true) */
    groupByFeature?: boolean;
    /** Grouping rule for operations */
    operationsGrouping?: GroupingRule;
    /** Grouping rule for models */
    modelsGrouping?: GroupingRule;
    /** Grouping rule for events */
    eventsGrouping?: GroupingRule;
}
export interface PrCommentConfig {
    /** Enable PR comments */
    enabled?: boolean;
    /** Comment template: 'minimal' | 'detailed' */
    template?: 'minimal' | 'detailed';
    /** Update existing comment instead of creating new */
    updateExisting?: boolean;
}
export interface CheckRunConfig {
    /** Enable GitHub check run creation */
    enabled?: boolean;
    /** Check run name */
    name?: string;
    /** Fail check on breaking changes */
    failOnBreaking?: boolean;
    /** Fail check on any contract changes */
    failOnChanges?: boolean;
}
export interface ImpactConfig {
    /** Baseline for comparison: 'default-branch' | 'base-ref' | 'tag:v*' */
    baseline?: string;
    /** Paths to include in impact detection (glob patterns) */
    include?: string[];
    /** Paths to exclude from impact detection (glob patterns) */
    exclude?: string[];
}
export type PackageDeclarationRollout = 'off' | 'warning' | 'error';
export type PackageDeclarationTarget = 'feature' | 'integration' | 'app-config' | 'module-bundle' | 'example';
export interface PackageDeclarationRequiredByKind {
    libs?: PackageDeclarationTarget;
    modules?: PackageDeclarationTarget;
    integrations?: PackageDeclarationTarget;
    bundles?: PackageDeclarationTarget;
    apps?: PackageDeclarationTarget;
    appsRegistry?: PackageDeclarationTarget;
    examples?: PackageDeclarationTarget;
}
export interface PackageDeclarationConfig {
    /** Staged rollout severity for missing package declarations. */
    severity?: PackageDeclarationRollout;
    /** Required declaration target for each top-level workspace package family. */
    requiredByKind?: PackageDeclarationRequiredByKind;
    /** Package roots or package names temporarily exempted from hard failure. */
    allowMissing?: string[];
}
export interface CiConfig {
    /** Default checks to run */
    checks?: string[];
    /** Checks to skip */
    skipChecks?: string[];
    /** Fail CI on warnings */
    failOnWarnings?: boolean;
    /** Upload SARIF to GitHub Code Scanning */
    uploadSarif?: boolean;
    /** PR comment configuration */
    prComment?: PrCommentConfig;
    /** GitHub check run configuration */
    checkRun?: CheckRunConfig;
    /** Impact detection configuration */
    impact?: ImpactConfig;
    /** Package-level declaration coverage policy. */
    packageDeclarations?: PackageDeclarationConfig;
}
export interface ExternalWorkspace {
    /** Alias for referencing this workspace (e.g., 'core', 'internal') */
    alias: string;
    /** Submodule name or relative path from meta-repo root */
    submodule: string;
    /** Package patterns to include from this workspace */
    packages?: string[];
    /** Whether to auto-resolve internal dependencies */
    autoResolve?: boolean;
}
export interface MetaRepoConfig {
    /** Active submodule scope (defaults to auto-detected) */
    activeScope?: string;
    /** External workspace references for cross-workspace dependencies */
    externalWorkspaces?: ExternalWorkspace[];
    /** Whether to search for specs across all submodules */
    crossWorkspaceSearch?: boolean;
}
export interface FormatterConfig {
    /** Enable/disable formatting (default: true if formatter detected) */
    enabled?: boolean;
    /** Formatter to use (auto-detected if not specified) */
    type?: FormatterType;
    /** Custom command for 'custom' type (e.g., "bunx @biomejs/biome format --write") */
    command?: string;
    /** Extra arguments to pass to formatter */
    args?: string[];
    /** Timeout in milliseconds (default: 30000) */
    timeout?: number;
}
export interface VersioningConfig {
    /** Enable automated version bumping in CI */
    autoBump?: boolean;
    /** Strategy for determining version bumps */
    bumpStrategy?: BumpStrategy;
    /** Integrate with Changesets (generate .changeset files) */
    integrateWithChangesets?: boolean;
    /** Changelog tiers to generate */
    changelogTiers?: ChangelogTier[];
    /** Changelog format template */
    format?: ChangelogFormat;
    /** Commit changes after version bump (CI mode) */
    commitChanges?: boolean;
    /** Commit message template (supports {version}, {specs}) */
    commitMessage?: string;
    /** Create git tags for versions */
    createTags?: boolean;
    /** Tag prefix (e.g., "v" -> v1.0.0, "spec-" -> spec-1.0.0) */
    tagPrefix?: string;
    /** Paths to include for version analysis (glob patterns) */
    include?: string[];
    /** Paths to exclude from version analysis (glob patterns) */
    exclude?: string[];
}
export interface ReleaseConfig {
    /** When to enforce release communication requirements */
    enforceOn?: ReleaseEnforceOn;
    /** Require a changeset when published packages change */
    requireChangesetForPublished?: boolean;
    /** Require a companion release capsule for published releases */
    requireReleaseCapsule?: boolean;
    /** Generated release artifacts to publish or upload */
    publishArtifacts?: string[];
    /** Agent prompt targets to emit during release build */
    agentTargets?: AgentTarget[];
}
export interface UpgradeConfig {
    /** Candidate upgrade manifest locations */
    manifestPaths?: string[];
    /** Default agent target for prompt export */
    defaultAgentTarget?: AgentTarget;
    /** Enable guided interactive upgrade flows */
    enableInteractiveGuidance?: boolean;
    /** Allow deterministic codemods during upgrade apply */
    applyCodemods?: boolean;
}
export interface RuleSyncConfig {
    /** Enable automated rule synchronization */
    enabled?: boolean;
    /** Root directory for source rule files */
    rulesDir?: string;
    /** Source rule files (glob patterns) */
    rules?: string[];
    /** Synchronization targets (tools to generate rules for) */
    targets?: RuleSyncTarget[];
    /** Automatically synchronize rules on workspace changes or builds */
    autoSync?: boolean;
    /** Whether to eject/copy source rules instead of generating from Unified Rules */
    ejectMode?: boolean;
}
export interface ClaudeAgentSDKConfig {
    /** Enable Claude Agent SDK provider */
    enabled?: boolean;
    /** API key (defaults to ANTHROPIC_API_KEY env var) */
    apiKey?: string;
    /** Model to use (defaults to claude-sonnet-4-6) */
    model?: string;
    /** Enable computer use capabilities */
    computerUse?: boolean;
    /** Enable extended thinking mode */
    extendedThinking?: boolean;
}
export interface OpenCodeSDKConfig {
    /** Enable OpenCode SDK provider */
    enabled?: boolean;
    /** Server URL (defaults to http://127.0.0.1:4096) */
    serverUrl?: string;
    /** Server port (alternative to full URL) */
    port?: number;
    /** Agent type to use */
    agentType?: 'build' | 'plan' | 'general' | 'explore';
    /** Model to use */
    model?: string;
}
export interface ExternalAgentsConfig {
    /** Claude Agent SDK configuration */
    claudeAgent?: ClaudeAgentSDKConfig;
    /** OpenCode SDK configuration */
    openCode?: OpenCodeSDKConfig;
}
export type BuilderRuntimeMode = 'managed' | 'local' | 'hybrid';
export type BuilderBootstrapPreset = 'managed_mvp' | 'local_daemon_mvp' | 'hybrid_mvp';
export interface BuilderApiConfig {
    /** Base URL for the Builder/control-plane API. */
    baseUrl?: string;
    /** Environment variable that carries the control-plane token. */
    controlPlaneTokenEnvVar?: string;
}
export interface BuilderLocalRuntimeConfig {
    /** Default local runtime target identifier. */
    runtimeId?: string;
    /** Default actor or lease target for local runtime registration. */
    grantedTo?: string;
    /** Default local-capable provider identifiers. */
    providerIds?: string[];
}
export interface BuilderConfig {
    /** Enable Builder initialization for this workspace. */
    enabled?: boolean;
    /** Default runtime mode for Builder flows. */
    runtimeMode?: BuilderRuntimeMode;
    /** Canonical Builder bootstrap preset to use after setup. */
    bootstrapPreset?: BuilderBootstrapPreset;
    /** Remote API/control-plane settings for managed or hybrid modes. */
    api?: BuilderApiConfig;
    /** Local runtime registration defaults for local or hybrid modes. */
    localRuntime?: BuilderLocalRuntimeConfig;
}
export type ConnectVerdict = 'permit' | 'rewrite' | 'require_review' | 'deny';
export type ConnectAdapterMode = 'plugin' | 'rule' | 'wrapper';
export interface ConnectAdapterConfig {
    /** Enable this adapter integration. */
    enabled?: boolean;
    /** Preferred delivery strategy for this adapter. */
    mode?: ConnectAdapterMode;
    /** Optional plugin, package, or registry reference. */
    packageRef?: string;
}
export interface ConnectStorageConfig {
    /** Root directory for generated Connect artifacts. */
    root?: string;
    /** Path for the current context pack artifact. */
    contextPack?: string;
    /** Path for the current plan packet artifact. */
    planPacket?: string;
    /** Path for the current patch verdict artifact. */
    patchVerdict?: string;
    /** Append-only local audit file. */
    auditFile?: string;
    /** Directory for local review packets. */
    reviewPacketsDir?: string;
}
export interface ConnectReviewThresholds {
    /** Verdict to apply when a protected path is mutated. */
    protectedPathWrite?: ConnectVerdict;
    /** Verdict to apply when impact cannot be resolved. */
    unknownImpact?: ConnectVerdict;
    /** Verdict to apply when contract drift is detected. */
    contractDrift?: ConnectVerdict;
    /** Verdict to apply when a breaking change is detected. */
    breakingChange?: ConnectVerdict;
    /** Verdict to apply for destructive commands. */
    destructiveCommand?: ConnectVerdict;
}
export interface ConnectPolicyConfig {
    /** Files or directories that require stronger review or denial. */
    protectedPaths?: string[];
    /** Paths that should be treated as immutable. */
    immutablePaths?: string[];
    /** Generated paths treated as derived outputs. */
    generatedPaths?: string[];
    /** Bun-first smoke checks adapters may suggest or run. */
    smokeChecks?: string[];
    /** Threshold model for Connect adapter verdicts. */
    reviewThresholds?: ConnectReviewThresholds;
}
export interface ConnectCommandPolicy {
    /** Commands that are considered safe defaults. */
    allow?: string[];
    /** Commands that require review before execution. */
    review?: string[];
    /** Commands that must be denied. */
    deny?: string[];
}
export interface ConnectCanonPackRef {
    /** Immutable reference to a canon pack. */
    ref: string;
    /** Whether the pack is enforced as read-only locally. */
    readOnly?: boolean;
}
export interface ConnectStudioConfig {
    /** Enable Studio transport for review packets. */
    enabled?: boolean;
    /** Integration mode for Studio handoff. */
    mode?: 'off' | 'review-bridge';
    /** Optional Studio endpoint when sync is enabled. */
    endpoint?: string;
    /** Optional Studio queue name for synced review packets. */
    queue?: string;
}
export type ConnectAdoptionFamily = 'ui' | 'contracts' | 'integrations' | 'runtime' | 'sharedLibs' | 'solutions';
export interface ConnectAdoptionCatalogConfig {
    /** Path to the mirrored ContractSpec adoption catalog. */
    indexPath?: string;
    /** Optional customer-authored overrides file for catalog entries. */
    overrideManifestPath?: string;
}
export interface ConnectAdoptionWorkspaceScanConfig {
    /** Files or directories to scan for workspace-local reusable surfaces. */
    include?: string[];
    /** Files or directories to exclude from workspace-local scanning. */
    exclude?: string[];
}
export interface ConnectAdoptionFamiliesConfig {
    ui?: boolean;
    contracts?: boolean;
    integrations?: boolean;
    runtime?: boolean;
    sharedLibs?: boolean;
    solutions?: boolean;
}
export interface ConnectAdoptionThresholds {
    /** Verdict to apply when a reusable workspace-local surface exists. */
    workspaceReuse?: ConnectVerdict;
    /** Verdict to apply when a ContractSpec OSS package is preferred. */
    contractspecReuse?: ConnectVerdict;
    /** Verdict to apply when multiple candidates are equally plausible. */
    ambiguous?: ConnectVerdict;
    /** Verdict to apply when only an external ecosystem dependency fits. */
    newExternalDependency?: ConnectVerdict;
    /** Verdict to apply when implementation must be created locally. */
    newImplementation?: ConnectVerdict;
}
export interface ConnectAdoptionConfig {
    /** Enable adoption-aware reuse guidance and gating. */
    enabled?: boolean;
    /** Catalog storage and overrides. */
    catalog?: ConnectAdoptionCatalogConfig;
    /** Workspace scanning configuration. */
    workspaceScan?: ConnectAdoptionWorkspaceScanConfig;
    /** Family-specific feature flags. */
    families?: ConnectAdoptionFamiliesConfig;
    /** Threshold model for adoption verdicts. */
    thresholds?: ConnectAdoptionThresholds;
}
export interface ConnectConfig {
    /** Enable ContractSpec Connect for this workspace. */
    enabled?: boolean;
    /** Adapter integrations keyed by host environment. */
    adapters?: {
        cursor?: ConnectAdapterConfig;
        codex?: ConnectAdapterConfig;
        'claude-code'?: ConnectAdapterConfig;
    };
    /** Local artifact storage configuration. */
    storage?: ConnectStorageConfig;
    /** Policy and threshold configuration. */
    policy?: ConnectPolicyConfig;
    /** Command allow/review/deny policy. */
    commands?: ConnectCommandPolicy;
    /** Shared canon packs consumed read-only by adapters. */
    canonPacks?: ConnectCanonPackRef[];
    /** Optional Studio bridge configuration. */
    studio?: ConnectStudioConfig;
    /** ContractSpec adoption and reuse guidance configuration. */
    adoption?: ConnectAdoptionConfig;
}
export interface LintRules {
    /** Require acceptance scenarios for operations */
    'require-acceptance'?: RuleSeverity;
    /** Require examples for operations */
    'require-examples'?: RuleSeverity;
    /** Require stability field */
    'require-stability'?: RuleSeverity;
    /** Require owners to follow proper format (@team or Enum) */
    'require-owners-format'?: RuleSeverity;
    /** Require event names to use past tense */
    'event-past-tense'?: RuleSeverity;
    /** Warn on placeholder comments */
    'no-todo'?: RuleSeverity;
    /** Require workflow transitions */
    'workflow-transitions'?: RuleSeverity;
    /** Require privacy classification for telemetry */
    'telemetry-privacy'?: RuleSeverity;
    /** Require allocation config for experiments */
    'experiment-allocation'?: RuleSeverity;
    /** Require appId for app blueprints */
    'app-config-appid'?: RuleSeverity;
    /** Require capabilities for app blueprints */
    'app-config-capabilities'?: RuleSeverity;
    /** Require fields for data views */
    'data-view-fields'?: RuleSeverity;
}
export interface TestLinkingConfig {
    /** Strategy for linking tests to specs */
    strategy?: TestLinkingStrategy;
    /** Warn when tests only use naming convention (no TestSpec.target) */
    warnOnConvention?: boolean;
}
export interface TestingConfig {
    /** Test runner to use */
    runner?: 'internal' | 'jest' | 'vitest' | 'bun';
    /** Glob patterns for matching test files */
    testMatch?: string[];
    /** Enable automatic test generation */
    autoGenerate?: boolean;
    /** Integrity requirements for testing */
    integrity?: {
        /** Spec types that require test coverage */
        requireTestsFor?: SpecKind[];
        /** Minimum coverage percentage (if supported) */
        minCoverage?: number;
    };
    /** Test linking configuration for contract-first test discovery */
    testLinking?: TestLinkingConfig;
    /** Harness verification configuration for browser, visual, and full-app runs */
    harness?: TestingHarnessConfig;
}
export type TestingHarnessBrowserEngine = 'playwright' | 'agent-browser' | 'both';
export interface TestingHarnessTargetUrls {
    preview?: string;
    task?: string;
    shared?: string;
    sandbox?: string;
}
export interface TestingHarnessVisualConfig {
    maxDiffBytes?: number;
    maxDiffRatio?: number;
    updateBaselines?: boolean;
}
export interface TestingHarnessAuthProfileConfig {
    kind: 'storage-state' | 'browser-profile' | 'session-name' | 'headers-env';
    ref: string;
}
export interface TestingHarnessConfig {
    /** Root directory for generated harness evidence and replay bundles. */
    artifactRoot?: string;
    /** Browser backend preference for harness browser scenarios. */
    browserEngine?: TestingHarnessBrowserEngine;
    /** Runtime target URLs used by local and CI harness runs. */
    targetBaseUrls?: TestingHarnessTargetUrls;
    /** Navigation domains allowed for browser harness runs. */
    allowlistedDomains?: string[];
    /** Visual comparison defaults. */
    visual?: TestingHarnessVisualConfig;
    /** Named auth state/profile/header refs. Values must not embed raw secrets. */
    authProfiles?: Record<string, TestingHarnessAuthProfileConfig>;
}
export interface RulesConfig {
    /** Global default rule severities */
    defaults?: LintRules;
    /** Per-kind rule severity overrides */
    overrides?: Partial<Record<SpecKind, LintRules>>;
}
export type HooksConfig = Record<string, string[]>;
/**
 * Full ContractSpec configuration (.contractsrc.json).
 * All fields are optional as they come from user configuration.
 */
export interface ContractsrcFileConfig {
    $schema?: string;
    aiProvider?: AgentProvider;
    aiModel?: string;
    agentMode?: AgentMode;
    customEndpoint?: string | null;
    customApiKey?: string | null;
    outputDir?: string;
    conventions?: FolderConventions;
    defaultOwners?: string[];
    defaultTags?: string[];
    packages?: string[];
    excludePackages?: string[];
    recursive?: boolean;
    openapi?: OpenApiConfig;
    ci?: CiConfig;
    metaRepo?: MetaRepoConfig;
    rules?: RulesConfig;
    testing?: TestingConfig;
    hooks?: HooksConfig;
    schemaFormat?: SchemaFormat;
    formatter?: FormatterConfig;
    versioning?: VersioningConfig;
    release?: ReleaseConfig;
    upgrade?: UpgradeConfig;
    ruleSync?: RuleSyncConfig;
    externalAgents?: ExternalAgentsConfig;
    builder?: BuilderConfig;
    connect?: ConnectConfig;
}
/**
 * Resolved configuration with guaranteed defaults.
 * This is what the application uses at runtime.
 */
export interface ResolvedContractsrcConfig extends ContractsrcFileConfig {
    aiProvider: 'claude' | 'openai' | 'ollama' | 'mistral' | 'custom';
    agentMode: 'simple' | 'cursor' | 'claude-code' | 'openai-codex' | 'claude-agent-sdk' | 'opencode' | 'opencode-sdk';
    outputDir: string;
    conventions: {
        models: string;
        operations: string;
        events: string;
        presentations: string;
        forms: string;
        capabilities: string;
        policies: string;
        tests: string;
        translations: string;
        groupByFeature: boolean;
        operationsGrouping?: GroupingRule;
        modelsGrouping?: GroupingRule;
        eventsGrouping?: GroupingRule;
    };
    defaultOwners: string[];
    defaultTags: string[];
    schemaFormat: SchemaFormat;
}
/**
 * @deprecated Use ContractsrcFileConfig for file inputs or ResolvedContractsrcConfig for app usage.
 */
export type ContractsrcConfig = ContractsrcFileConfig;
