Update add missing param type from calls sniff to add missing doc blocks

phpcs-sniffs/Formidable/Sniffs/Commenting/AddMissingParamTypeFromCallsSniff.php

@@ -68,22 +68,22 @@ public function process( File $phpcsFile, $stackPtr ) {
 
 		$functionName = $tokens[ $functionNamePtr ]['content'];
 
-		// Check if function has a docblock.
-		$docblock = $this->findDocblock( $phpcsFile, $stackPtr );
-
-		if ( false === $docblock ) {
-			return;
-		}
-
 		// Get function parameters.
 		$params = $this->getParameters( $phpcsFile, $stackPtr );
 
 		if ( empty( $params ) ) {
 			return;
 		}
 
-		// Get existing @param tags with their types.
-		$existingParams = $this->getExistingParamTags( $phpcsFile, $docblock );
+		// Check if function has a docblock.
+		$docblock       = $this->findDocblock( $phpcsFile, $stackPtr );
+		$hasDocblock    = ( false !== $docblock );
+		$existingParams = array();
+
+		if ( $hasDocblock ) {
+			// Get existing @param tags with their types.
+			$existingParams = $this->getExistingParamTags( $phpcsFile, $docblock );
+		}
 
 		// Find parameters that are missing @param comments entirely.
 		$missingParamComments = array();
@@ -145,6 +145,21 @@ public function process( File $phpcsFile, $stackPtr ) {
 			return;
 		}
 
+		// If no docblock exists, create one with the detected @param tags.
+		if ( ! $hasDocblock ) {
+			$fix = $phpcsFile->addFixableError(
+				'Missing docblock with @param tags (detected types from call site literals)',
+				$stackPtr,
+				'MissingDocblockFromCalls'
+			);
+
+			if ( $fix ) {
+				$this->addDocblock( $phpcsFile, $stackPtr, $paramsToAdd );
+			}
+
+			return;
+		}
+
 		// Report and fix each missing @param.
 		foreach ( $paramsToAdd as $paramName => $info ) {
 			$typeString = implode( '|', $info['types'] );
@@ -513,4 +528,73 @@ private function addParamTag( File $phpcsFile, $docblock, $type, $paramName ) {
 		$phpcsFile->fixer->replaceToken( $lastParamEnd, $newContent );
 		$phpcsFile->fixer->endChangeset();
 	}
+
+	/**
+	 * Add a new docblock with @param tags.
+	 *
+	 * @param File  $phpcsFile   The file being scanned.
+	 * @param int   $stackPtr    The function token position.
+	 * @param array $paramsToAdd Array of param name => array('types' => array, 'index' => int).
+	 *
+	 * @return void
+	 */
+	private function addDocblock( File $phpcsFile, $stackPtr, $paramsToAdd ) {
+		$tokens = $phpcsFile->getTokens();
+
+		// Find the position to insert the docblock (before any modifiers or the function keyword).
+		$insertBefore = $stackPtr;
+
+		$prev = $phpcsFile->findPrevious(
+			array( T_WHITESPACE, T_STATIC, T_PUBLIC, T_PRIVATE, T_PROTECTED, T_ABSTRACT, T_FINAL ),
+			$stackPtr - 1,
+			null,
+			true
+		);
+
+		if ( false !== $prev ) {
+			// Find the first modifier/keyword after $prev.
+			$next = $phpcsFile->findNext( T_WHITESPACE, $prev + 1, $stackPtr, true );
+
+			if ( false !== $next ) {
+				$insertBefore = $next;
+			}
+		}
+
+		// Determine indentation from the function line.
+		$indent = '';
+
+		for ( $i = $insertBefore - 1; $i >= 0; $i-- ) {
+			if ( $tokens[ $i ]['code'] === T_WHITESPACE ) {
+				if ( strpos( $tokens[ $i ]['content'], "\n" ) !== false || strpos( $tokens[ $i ]['content'], "\r" ) !== false ) {
+					// Get the part after the newline.
+					$indent = preg_replace( '/^.*[\r\n]/', '', $tokens[ $i ]['content'] );
+					break;
+				}
+			} else {
+				break;
+			}
+		}
+
+		// Build the docblock.
+		$docblock = "/**\n";
+
+		// Sort params by index to maintain order.
+		uasort(
+			$paramsToAdd,
+			function ( $a, $b ) {
+				return $a['index'] - $b['index'];
+			}
+		);
+
+		foreach ( $paramsToAdd as $paramName => $info ) {
+			$typeString = implode( '|', $info['types'] );
+			$docblock  .= $indent . "\t * @param " . $typeString . ' ' . $paramName . "\n";
+		}
+
+		$docblock .= $indent . "\t */\n" . $indent . "\t";
+
+		$phpcsFile->fixer->beginChangeset();
+		$phpcsFile->fixer->addContentBefore( $insertBefore, $docblock );
+		$phpcsFile->fixer->endChangeset();
+	}
 }

tests/phpunit/emails/test_FrmEmail.php

@@ -428,6 +428,9 @@ public function test_trigger_email_six() {
 		$this->check_senders( $expected, $mock_email );
 	}
 
+	/**
+	 * @param string $subject
+	 */
 	protected function prepare_subject( $subject ) {
 		return wp_specialchars_decode( strip_tags( stripslashes( $subject ) ), ENT_QUOTES );
 	}
@@ -747,6 +750,10 @@ public function test_plain_text_message() {
 		}
 	}
 
+	/**
+	 * @param string $setting_name
+	 * @param string $property
+	 */
 	private function check_private_properties( $settings, $setting_name, $property = '' ) {
 		if ( ! $property ) {
 			$property = $setting_name;

tests/phpunit/entries/test_FrmEntriesController.php

@@ -34,6 +34,9 @@ public function test_delete_entry_after_save() {
 		$this->assertEquals( 'publish', $post->post_status );
 	}
 
+	/**
+	 * @param array $options
+	 */
 	private function create_form( $options = array() ) {
 		return $this->factory->form->create_and_get(
 			array(

tests/phpunit/entries/test_FrmShowEntryShortcode.php

@@ -700,6 +700,9 @@ public function test_json_format() {
 		$this->assertSame( $expected_json, $actual_json );
 	}
 
+	/**
+	 * @param bool $include_meta
+	 */
 	protected function get_test_entry( $include_meta ) {
 		$new_entry = array(
 			'form_id'     => FrmForm::get_id_by_key( 'free_field_types' ),
@@ -1025,10 +1028,16 @@ protected function get_field_value( $entry, $field, $atts ) {
 		return $field_value;
 	}
 
+	/**
+	 * @param string $type
+	 */
 	protected function set_included_fields( $type ) {
 		$this->include_fields = $this->set_field_array( $type );
 	}
 
+	/**
+	 * @param string $type
+	 */
 	protected function set_excluded_fields( $type ) {
 		$this->exclude_fields = $this->set_field_array( $type );
 	}
@@ -1043,6 +1052,9 @@ protected function set_field_array( $type ) {
 		return $fields;
 	}
 
+	/**
+	 * @param string $type
+	 */
 	protected function get_single_included_field( $type ) {
 		$include_fields = array(
 			'free-text-field' => 'free-text-field',

tests/phpunit/fields/test_FrmFieldGridHelper.php.php

@@ -27,6 +27,9 @@ public function test_get_size_of_class() {
 		$this->assertEquals( 12, $this->get_size_of_class( 'frm_full' ) );
 	}
 
+	/**
+	 * @param string $class
+	 */
 	private function get_size_of_class( $class ) {
 		return $this->run_private_method( array( 'FrmFieldGridHelper', 'get_size_of_class' ), array( $class ) );
 	}
@@ -57,6 +60,10 @@ public function test_basic_grouping() {
 		ob_end_clean();
 	}
 
+	/**
+	 * @param false|int $assert_size
+	 * @param string $assert_message
+	 */
 	private function sync_current_field_once( $assert_size = false, $assert_message = '' ) {
 		$this->helper->maybe_begin_field_wrapper();
 		$this->helper->sync_list_size();
@@ -70,6 +77,10 @@ private function assert_current_list_size( $expected, $message = '' ) {
 		$this->assertEquals( $expected, $this->get_private_property( $this->helper, 'current_list_size' ), $message );
 	}
 
+	/**
+	 * @param string $type
+	 * @param string $classes
+	 */
 	private function create_field_with_classes( $type, $classes = '' ) {
 		return $this->factory->field->create_and_get(
 			array(
@@ -129,6 +140,9 @@ public function test_with_sections() {
 		ob_end_clean();
 	}
 
+	/**
+	 * @param int $expected
+	 */
 	private function assert_section_helper_size( $expected ) {
 		$this->assertEquals( $expected, $this->get_private_property( $this->section_helper, 'current_list_size' ) );
 	}

tests/phpunit/fields/test_FrmFieldValidate.php

@@ -253,10 +253,16 @@ protected function set_required_field( $field ) {
 		}
 	}
 
+	/**
+	 * @param string $field_type
+	 */
 	protected function get_field_key( $field_type ) {
 		return $field_type . '-form' . $this->form->id;
 	}
 
+	/**
+	 * @param array $item_meta
+	 */
 	protected function check_single_value( $item_meta ) {
 		$_POST = array(
 			'form_id'   => $this->form->id,

tests/phpunit/forms/test_FrmForm.php

@@ -169,12 +169,20 @@ public function test_sanitize_field_opt() {
 		$this->assert_sanitize_field_opt_calc( $original_value, $original_value );
 	}
 
+	/**
+	 * @param string $expected
+	 * @param string $original_value
+	 * @param string $message
+	 */
 	private function assert_sanitize_field_opt_calc( $expected, $original_value, $message = '' ) {
 		$value = $original_value;
 		$this->sanitize_field_opt( 'calc', $value );
 		$this->assertEquals( $expected, $value, $message );
 	}
 
+	/**
+	 * @param string $opt
+	 */
 	private function sanitize_field_opt( $opt, &$value ) {
 		return $this->run_private_method(
 			array( 'FrmForm', 'sanitize_field_opt' ),
@@ -196,6 +204,9 @@ public function test_normalize_calc_spaces() {
 		$this->assertEquals( '1 <= 2 && 3 <= 4 && 5 <= 6', $this->normalize_calc_spaces( '1<=2 && 3<=4 && 5<=6' ) );
 	}
 
+	/**
+	 * @param string $calc
+	 */
 	private function normalize_calc_spaces( $calc ) {
 		return $this->run_private_method( array( 'FrmForm', 'normalize_calc_spaces' ), array( $calc ) );
 	}

tests/phpunit/forms/test_FrmFormsController.php

@@ -152,6 +152,9 @@ public function test_front_head() {
 		$this->assertEquals( FrmAppHelper::plugin_url() . '/js/' . $file, $formidable_js->src, $file . ' was not loaded' );
 	}
 
+	/**
+	 * @param array $post_content
+	 */
 	private function create_on_submit_action( $form_id, $post_content ) {
 		$post_data = array(
 			'post_type'    => FrmFormActionsController::$action_post_type,
@@ -306,6 +309,9 @@ public function test_message_with_form_after_create() {
 		$this->run_message_after_create( 1 );
 	}
 
+	/**
+	 * @param int $show_form
+	 */
 	public function run_message_after_create( $show_form = 0 ) {
 		$form = $this->factory->form->create_and_get(
 			array(

tests/phpunit/forms/test_FrmFormsHelper.php

@@ -64,6 +64,11 @@ public function test_maybe_add_sanitize_url_attr() {
 		);
 	}
 
+	/**
+	 * @param string $expected
+	 * @param string $url
+	 * @param string $message
+	 */
 	private function assert_maybe_add_sanitize_url_attr( $expected, $url, $message = '' ) {
 		$this->assertEquals( $expected, FrmFormsHelper::maybe_add_sanitize_url_attr( $url, (int) $this->form->id ), $message );
 	}
@@ -78,6 +83,10 @@ public function test_get_plan_required() {
 		$this->assert_get_plan_required( 'Plus', array( 'Plus', 'Category2' ) );
 	}
 
+	/**
+	 * @param string $expected
+	 * @param array $categories
+	 */
 	private function assert_get_plan_required( $expected, $categories ) {
 		$link = compact( 'categories' );
 		$this->assertEquals( $expected, FrmFormsHelper::get_plan_required( $link ) );
@@ -125,6 +134,9 @@ public function test_get_form_style() {
 		$this->assertEquals( '0', FrmFormsHelper::get_form_style( $form ) );
 	}
 
+	/**
+	 * @param string $custom_style
+	 */
 	private function create_form_with_custom_style_value( $custom_style ) {
 		return $this->factory->form->create_and_get(
 			array(

tests/phpunit/misc/test_FrmAppController.php

@@ -38,6 +38,9 @@ public function test_block_menu() {
 		$this->check_menu( 'block' );
 	}
 
+	/**
+	 * @param string $allow
+	 */
 	private function check_menu( $allow = 'allow' ) {
 		$url = get_option( 'siteurl', true );
 		do_action( 'admin_menu' );

tests/phpunit/misc/test_FrmAppHelper.php

@@ -382,6 +382,9 @@ public function test_is_a_valid_color() {
 		$this->assertFalse( $this->is_a_valid_color( 'Not a color' ) );
 	}
 
+	/**
+	 * @param string $value
+	 */
 	private function is_a_valid_color( $value ) {
 		return $this->run_private_method( array( 'FrmAppHelper', 'is_a_valid_color' ), array( $value ) );
 	}

tests/phpunit/misc/test_FrmInbox.php

@@ -23,6 +23,10 @@ public function test_add_message() {
 		$this->assert_message_count( $initial_count + 1, 'Message count should not go up after an invalid message is added.' );
 	}
 
+	/**
+	 * @param int $count
+	 * @param string $message
+	 */
 	private function assert_message_count( $count, $message ) {
 		$this->assertEquals( $count, $this->get_message_count(), $message );
 	}

tests/phpunit/misc/test_FrmSpamCheckDenylist.php

@@ -90,6 +90,9 @@ public function setUp(): void {
 		);
 	}
 
+	/**
+	 * @param array $denylist_data
+	 */
 	private function set_denylist_data( $denylist_data ) {
 		$this->set_private_property( $this->spam_check, 'denylist', $denylist_data );
 	}

tests/phpunit/stripe/test_FrmStripeLiteAuth.php

@@ -38,6 +38,9 @@ public function test_maybe_add_statement_descriptor() {
 		);
 	}
 
+	/**
+	 * @param array $intent_data
+	 */
 	private function maybe_add_statement_descriptor( $intent_data ) {
 		return $this->run_private_method( array( 'FrmStrpLiteAuth', 'maybe_add_statement_descriptor' ), array( $intent_data ) );
 	}

tests/phpunit/styles/test_FrmStyle.php

@@ -107,6 +107,9 @@ public function test_strip_invalid_characters() {
 		$this->assertEquals( 'calc(100%/6)', $this->strip_invalid_characters( 'calc(100%/6)' ) );
 	}
 
+	/**
+	 * @param string $input
+	 */
 	private function strip_invalid_characters( $input ) {
 		$frm_style = new FrmStyle();
 		return $this->run_private_method( array( $frm_style, 'strip_invalid_characters' ), array( $input ) );