@eddacraft/anvil-core 0.1.0

package/dist/antipattern/types.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Anti-pattern detection types
+ *
+ * Defines the Warning schema and related types for anti-pattern detection
+ * and architecture boundary violations. Follows Zod-first approach per ADR-0001.
+ */
+import { z } from 'zod';
+/**
+ * Source code location for a warning
+ */
+export declare const LocationSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+    endColumn: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type Location = z.infer<typeof LocationSchema>;
+/**
+ * Drift context for boundary violations
+ */
+export declare const DriftSchema: z.ZodObject<{
+    isNew: z.ZodBoolean;
+    existingCount: z.ZodOptional<z.ZodNumber>;
+    baselineId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Drift = z.infer<typeof DriftSchema>;
+/**
+ * Suppression metadata when a warning is suppressed via @anvil-ignore
+ */
+export declare const SuppressionSchema: z.ZodObject<{
+    reason: z.ZodString;
+    author: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodString>;
+    scope: z.ZodEnum<{
+        file: "file";
+        line: "line";
+        statement: "statement";
+        import: "import";
+    }>;
+}, z.core.$strip>;
+export type Suppression = z.infer<typeof SuppressionSchema>;
+/**
+ * Warning categories
+ */
+export declare const WarningCategorySchema: z.ZodEnum<{
+    "anti-pattern": "anti-pattern";
+    boundary: "boundary";
+    architecture: "architecture";
+}>;
+export type WarningCategory = z.infer<typeof WarningCategorySchema>;
+/**
+ * Warning severity levels
+ */
+export declare const WarningSeveritySchema: z.ZodEnum<{
+    warning: "warning";
+    error: "error";
+    info: "info";
+}>;
+export type WarningSeverity = z.infer<typeof WarningSeveritySchema>;
+/**
+ * Confidence levels for detection
+ */
+export declare const ConfidenceSchema: z.ZodEnum<{
+    high: "high";
+    medium: "medium";
+    low: "low";
+}>;
+export type Confidence = z.infer<typeof ConfidenceSchema>;
+/**
+ * Core Warning schema - the primary output of anti-pattern and boundary detection
+ */
+export declare const WarningSchema: z.ZodObject<{
+    id: z.ZodString;
+    fingerprint: z.ZodOptional<z.ZodString>;
+    category: z.ZodEnum<{
+        "anti-pattern": "anti-pattern";
+        boundary: "boundary";
+        architecture: "architecture";
+    }>;
+    severity: z.ZodEnum<{
+        warning: "warning";
+        error: "error";
+        info: "info";
+    }>;
+    confidence: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    title: z.ZodString;
+    message: z.ZodString;
+    explanation: z.ZodString;
+    suggestion: z.ZodString;
+    nudge: z.ZodOptional<z.ZodString>;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        column: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    pattern: z.ZodOptional<z.ZodString>;
+    drift: z.ZodOptional<z.ZodObject<{
+        isNew: z.ZodBoolean;
+        existingCount: z.ZodOptional<z.ZodNumber>;
+        baselineId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    suppressed: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodString;
+        author: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodString>;
+        scope: z.ZodEnum<{
+            file: "file";
+            line: "line";
+            statement: "statement";
+            import: "import";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Warning = z.infer<typeof WarningSchema>;
+/**
+ * Regex-based detection configuration
+ */
+export declare const RegexDetectionConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"regex">;
+    pattern: z.ZodString;
+}, z.core.$strip>;
+/**
+ * AST-based detection configuration
+ */
+export declare const AstDetectionConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ast">;
+    astQuery: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Detection method configuration - discriminated union ensures
+ * regex type requires pattern, ast type requires astQuery
+ */
+export declare const DetectionConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"regex">;
+    pattern: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ast">;
+    astQuery: z.ZodString;
+}, z.core.$strip>], "type">;
+export type DetectionConfig = z.infer<typeof DetectionConfigSchema>;
+export type RegexDetectionConfig = z.infer<typeof RegexDetectionConfigSchema>;
+export type AstDetectionConfig = z.infer<typeof AstDetectionConfigSchema>;
+/**
+ * Anti-pattern definition - defines a detectable pattern
+ */
+export declare const AntiPatternSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    category: z.ZodEnum<{
+        "escape-hatch": "escape-hatch";
+        "error-handling": "error-handling";
+        "code-quality": "code-quality";
+        "type-safety": "type-safety";
+        html: "html";
+        css: "css";
+    }>;
+    severity: z.ZodEnum<{
+        warning: "warning";
+        error: "error";
+        info: "info";
+    }>;
+    confidence: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    detection: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"regex">;
+        pattern: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"ast">;
+        astQuery: z.ZodString;
+    }, z.core.$strip>], "type">;
+    title: z.ZodString;
+    explanation: z.ZodString;
+    suggestion: z.ZodString;
+    nudge: z.ZodOptional<z.ZodString>;
+    fileExtensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allFileTypes: z.ZodOptional<z.ZodBoolean>;
+    allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    optIn: z.ZodDefault<z.ZodBoolean>;
+    documentation: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AntiPattern = z.infer<typeof AntiPatternSchema>;
+/**
+ * Collection of warnings from a check run - embeds in GateResult.details
+ */
+export declare const WarningResultSchema: z.ZodObject<{
+    warnings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        fingerprint: z.ZodOptional<z.ZodString>;
+        category: z.ZodEnum<{
+            "anti-pattern": "anti-pattern";
+            boundary: "boundary";
+            architecture: "architecture";
+        }>;
+        severity: z.ZodEnum<{
+            warning: "warning";
+            error: "error";
+            info: "info";
+        }>;
+        confidence: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>;
+        title: z.ZodString;
+        message: z.ZodString;
+        explanation: z.ZodString;
+        suggestion: z.ZodString;
+        nudge: z.ZodOptional<z.ZodString>;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            column: z.ZodOptional<z.ZodNumber>;
+            endLine: z.ZodOptional<z.ZodNumber>;
+            endColumn: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        pattern: z.ZodOptional<z.ZodString>;
+        drift: z.ZodOptional<z.ZodObject<{
+            isNew: z.ZodBoolean;
+            existingCount: z.ZodOptional<z.ZodNumber>;
+            baselineId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        suppressed: z.ZodOptional<z.ZodObject<{
+            reason: z.ZodString;
+            author: z.ZodOptional<z.ZodString>;
+            timestamp: z.ZodOptional<z.ZodString>;
+            scope: z.ZodEnum<{
+                file: "file";
+                line: "line";
+                statement: "statement";
+                import: "import";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    summary: z.ZodObject<{
+        total: z.ZodNumber;
+        errors: z.ZodNumber;
+        warnings: z.ZodNumber;
+        info: z.ZodNumber;
+        suppressed: z.ZodNumber;
+    }, z.core.$strip>;
+    patterns_checked: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type WarningResult = z.infer<typeof WarningResultSchema>;
+/**
+ * Suppression record for provenance tracking
+ */
+export declare const SuppressionRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    pattern_id: z.ZodString;
+    file: z.ZodString;
+    line: z.ZodNumber;
+    reason: z.ZodString;
+    author: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+    commit: z.ZodOptional<z.ZodString>;
+    scope: z.ZodEnum<{
+        file: "file";
+        line: "line";
+        statement: "statement";
+        import: "import";
+    }>;
+    expires_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SuppressionRecord = z.infer<typeof SuppressionRecordSchema>;
+/**
+ * Create a warning fingerprint for deduplication
+ */
+export declare function createWarningFingerprint(warning: Omit<Warning, 'fingerprint'>): string;
+/**
+ * Check if a warning should be considered an error for gate purposes
+ */
+export declare function isBlockingWarning(warning: Warning): boolean;
+/**
+ * Warning summary type matching WarningResultSchema.summary
+ */
+export interface WarningSummary {
+    total: number;
+    errors: number;
+    warnings: number;
+    info: number;
+    suppressed: number;
+}
+/**
+ * Count warnings by severity, including total count.
+ * Note: A warning can be both suppressed AND have a severity,
+ * so suppressed warnings are counted separately and not in their severity bucket.
+ */
+export declare function countBySeverity(warnings: Warning[]): WarningSummary;
+/**
+ * Create a complete WarningResult summary from a list of warnings.
+ * Ensures consistency between warnings array and summary counts.
+ *
+ * @param warnings - Array of warnings
+ * @param patternsChecked - Array of pattern IDs that were checked
+ * @returns Complete WarningResult object
+ */
+export declare function createWarningResult(warnings: Warning[], patternsChecked: string[]): WarningResult;
+/**
+ * Validate that a WarningResult's summary matches its warnings array.
+ * Useful for catching inconsistencies in manually constructed results.
+ *
+ * @param result - WarningResult to validate
+ * @returns true if summary matches warnings, false otherwise
+ */
+export declare function validateWarningResultConsistency(result: WarningResult): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/antipattern/types.d.ts.map

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

package/dist/antipattern/types.js

@@ -0,0 +1,278 @@
+/**
+ * Anti-pattern detection types
+ *
+ * Defines the Warning schema and related types for anti-pattern detection
+ * and architecture boundary violations. Follows Zod-first approach per ADR-0001.
+ */
+import { z } from 'zod';
+// =============================================================================
+// Location Schema
+// =============================================================================
+/**
+ * Source code location for a warning
+ */
+export const LocationSchema = z.object({
+    file: z.string().describe('File path relative to workspace root'),
+    line: z.number().int().positive().describe('Line number (1-based)'),
+    column: z.number().int().nonnegative().optional().describe('Column number (0-based)'),
+    endLine: z.number().int().positive().optional().describe('End line for multi-line spans'),
+    endColumn: z.number().int().nonnegative().optional().describe('End column for multi-line spans'),
+});
+// =============================================================================
+// Drift Schema
+// =============================================================================
+/**
+ * Drift context for boundary violations
+ */
+export const DriftSchema = z.object({
+    isNew: z.boolean().describe('Whether this is a NEW violation vs existing'),
+    existingCount: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Number of existing violations of this type'),
+    baselineId: z.string().optional().describe('ID of the baseline violation if existing'),
+});
+// =============================================================================
+// Suppression Schema
+// =============================================================================
+/**
+ * Suppression metadata when a warning is suppressed via @anvil-ignore
+ */
+export const SuppressionSchema = z.object({
+    reason: z.string().min(1).describe('Human-provided reason for suppression'),
+    author: z.string().optional().describe('Author who added the suppression (e.g., @jane)'),
+    timestamp: z.string().datetime().optional().describe('When the suppression was added'),
+    scope: z.enum(['statement', 'import', 'file', 'line']).describe('Scope of the suppression'),
+});
+// =============================================================================
+// Warning Schema (Core)
+// =============================================================================
+/**
+ * Warning categories
+ */
+export const WarningCategorySchema = z.enum(['anti-pattern', 'boundary', 'architecture']);
+/**
+ * Warning severity levels
+ */
+export const WarningSeveritySchema = z.enum(['error', 'warning', 'info']);
+/**
+ * Confidence levels for detection
+ */
+export const ConfidenceSchema = z.enum(['high', 'medium', 'low']);
+/**
+ * Core Warning schema - the primary output of anti-pattern and boundary detection
+ */
+export const WarningSchema = z.object({
+    // Identification
+    id: z
+        .string()
+        .regex(/^(AP|ARCH|BOUND)-\d{3}$/)
+        .describe('Warning ID (e.g., AP-001, ARCH-001, BOUND-001)'),
+    fingerprint: z
+        .string()
+        .optional()
+        .describe('Unique fingerprint for deduplication (hash of location + pattern)'),
+    // Classification
+    category: WarningCategorySchema.describe('Warning category'),
+    severity: WarningSeveritySchema.describe('Severity level'),
+    confidence: ConfidenceSchema.describe('Detection confidence'),
+    // Display
+    title: z.string().describe('Short title (e.g., "Broad eslint-disable added")'),
+    message: z.string().describe('Primary message - what happened'),
+    explanation: z.string().describe('Why this matters'),
+    suggestion: z.string().describe('What to do instead'),
+    nudge: z.string().optional().describe('Imperative coaching prompt from the pattern'),
+    // Location
+    location: LocationSchema.describe('Source code location'),
+    // Context
+    pattern: z.string().optional().describe('Named pattern or rule that triggered this'),
+    drift: DriftSchema.optional().describe('Drift context for boundary violations'),
+    // Suppression
+    suppressed: SuppressionSchema.optional().describe('Suppression metadata if suppressed'),
+});
+// =============================================================================
+// Anti-Pattern Definition Schema
+// =============================================================================
+/**
+ * Regex-based detection configuration
+ */
+export const RegexDetectionConfigSchema = z.object({
+    type: z.literal('regex').describe('Regex-based detection'),
+    pattern: z.string().min(1).describe('Regex pattern string'),
+});
+/**
+ * AST-based detection configuration
+ */
+export const AstDetectionConfigSchema = z.object({
+    type: z.literal('ast').describe('AST-based detection'),
+    astQuery: z.string().min(1).describe('AST query description'),
+});
+/**
+ * Detection method configuration - discriminated union ensures
+ * regex type requires pattern, ast type requires astQuery
+ */
+export const DetectionConfigSchema = z.discriminatedUnion('type', [
+    RegexDetectionConfigSchema,
+    AstDetectionConfigSchema,
+]);
+/**
+ * Anti-pattern definition - defines a detectable pattern
+ */
+export const AntiPatternSchema = z.object({
+    // Identification
+    id: z
+        .string()
+        .regex(/^AP-\d{3}$/)
+        .describe('Pattern ID (e.g., AP-001)'),
+    name: z.string().describe('Human-readable name'),
+    // Classification
+    category: z
+        .enum(['escape-hatch', 'error-handling', 'code-quality', 'type-safety', 'html', 'css'])
+        .describe('Pattern category'),
+    severity: WarningSeveritySchema.describe('Default severity'),
+    confidence: ConfidenceSchema.describe('Detection confidence'),
+    // Detection
+    detection: DetectionConfigSchema.describe('How to detect this pattern'),
+    // Messaging
+    title: z.string().describe('Warning title template'),
+    explanation: z.string().describe('Why this pattern is problematic'),
+    suggestion: z.string().describe('Recommended alternative'),
+    nudge: z.string().optional().describe('Imperative coaching prompt for AI agents and developers'),
+    // File targeting
+    fileExtensions: z
+        .array(z.string())
+        .optional()
+        .describe('File extensions this pattern applies to (e.g., [".html", ".htm"])'),
+    allFileTypes: z
+        .boolean()
+        .optional()
+        .describe('If true, pattern applies to all scanned file types regardless of extension'),
+    // Customisation
+    allowlist: z.array(z.string()).optional().describe('File patterns to skip (glob patterns)'),
+    threshold: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Count threshold for triggering (e.g., >3 per file)'),
+    // Enablement
+    enabled: z.boolean().default(true).describe('Whether enabled by default'),
+    optIn: z.boolean().default(false).describe('If true, disabled by default (noisy patterns)'),
+    // Documentation
+    documentation: z.string().url().optional().describe('Link to detailed documentation'),
+});
+// =============================================================================
+// Warning Result Schema (for GateResult integration)
+// =============================================================================
+/**
+ * Collection of warnings from a check run - embeds in GateResult.details
+ */
+export const WarningResultSchema = z.object({
+    warnings: z.array(WarningSchema).describe('All warnings found'),
+    summary: z.object({
+        total: z.number().int().nonnegative(),
+        errors: z.number().int().nonnegative(),
+        warnings: z.number().int().nonnegative(),
+        info: z.number().int().nonnegative(),
+        suppressed: z.number().int().nonnegative(),
+    }),
+    patterns_checked: z.array(z.string()).describe('Pattern IDs that were checked'),
+});
+// =============================================================================
+// Suppression Record Schema (for provenance)
+// =============================================================================
+/**
+ * Suppression record for provenance tracking
+ */
+export const SuppressionRecordSchema = z.object({
+    id: z.string().describe('Unique suppression ID'),
+    pattern_id: z.string().describe('Pattern ID being suppressed'),
+    file: z.string().describe('File containing the suppression'),
+    line: z.number().int().positive().describe('Line number of suppression comment'),
+    reason: z.string().describe('Reason provided'),
+    author: z.string().optional().describe('Author if specified'),
+    timestamp: z.string().datetime().describe('When recorded'),
+    commit: z.string().optional().describe('Git commit SHA when added'),
+    scope: z.enum(['statement', 'import', 'file', 'line']).describe('Suppression scope'),
+    expires_at: z.string().datetime().optional().describe('Expiry date for time-boxed suppressions'),
+});
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Create a warning fingerprint for deduplication
+ */
+export function createWarningFingerprint(warning) {
+    const parts = [
+        warning.id,
+        warning.location.file,
+        warning.location.line.toString(),
+        warning.pattern ?? '',
+    ];
+    // Simple hash - in production would use crypto
+    return parts.join(':');
+}
+/**
+ * Check if a warning should be considered an error for gate purposes
+ */
+export function isBlockingWarning(warning) {
+    return warning.severity === 'error' && !warning.suppressed;
+}
+/**
+ * Count warnings by severity, including total count.
+ * Note: A warning can be both suppressed AND have a severity,
+ * so suppressed warnings are counted separately and not in their severity bucket.
+ */
+export function countBySeverity(warnings) {
+    const counts = warnings.reduce((acc, w) => {
+        if (w.suppressed) {
+            acc.suppressed++;
+        }
+        else if (w.severity === 'error') {
+            acc.errors++;
+        }
+        else if (w.severity === 'warning') {
+            acc.warnings++;
+        }
+        else {
+            acc.info++;
+        }
+        return acc;
+    }, { errors: 0, warnings: 0, info: 0, suppressed: 0 });
+    return {
+        total: warnings.length,
+        ...counts,
+    };
+}
+/**
+ * Create a complete WarningResult summary from a list of warnings.
+ * Ensures consistency between warnings array and summary counts.
+ *
+ * @param warnings - Array of warnings
+ * @param patternsChecked - Array of pattern IDs that were checked
+ * @returns Complete WarningResult object
+ */
+export function createWarningResult(warnings, patternsChecked) {
+    return {
+        warnings,
+        summary: countBySeverity(warnings),
+        patterns_checked: patternsChecked,
+    };
+}
+/**
+ * Validate that a WarningResult's summary matches its warnings array.
+ * Useful for catching inconsistencies in manually constructed results.
+ *
+ * @param result - WarningResult to validate
+ * @returns true if summary matches warnings, false otherwise
+ */
+export function validateWarningResultConsistency(result) {
+    const computed = countBySeverity(result.warnings);
+    return (result.summary.total === computed.total &&
+        result.summary.errors === computed.errors &&
+        result.summary.warnings === computed.warnings &&
+        result.summary.info === computed.info &&
+        result.summary.suppressed === computed.suppressed);
+}