*/ /** * MIN_SHIPPED_PHP_FILES from ci/plugin.conf. Refuses rather than defaulting: * an unset floor parses to 0 and every comparison against it passes, which is * the same bug as a scan over zero files one level up. */ function shipped_php_floor() { $conf = dirname( __DIR__ ) . '/ci/plugin.conf'; if ( is_file( $conf ) && preg_match( '/^MIN_SHIPPED_PHP_FILES=([0-9]+)/m', (string) file_get_contents( $conf ), $m ) && (int) $m[1] > 0 ) { return (int) $m[1]; } fwrite( STDERR, "::error::No usable MIN_SHIPPED_PHP_FILES in ci/plugin.conf — refusing to run with no floor.\n" ); exit( 1 ); } /** * This plugin's own hook prefix, read from ci/plugin.conf. * * Refuses rather than guessing, and is deliberately NOT derived from * TEXT_DOMAIN: here the domain is wc-email-discount and the hooks are wc_edm_, * and in the tree this file came from the domain is nolimit-security and the * hooks are nlsec_. A checker that guessed would be wrong in both. */ function hook_prefix() { static $prefix = null; if ( null !== $prefix ) { return $prefix; } $conf = dirname( __DIR__ ) . '/ci/plugin.conf'; $prefix = ''; if ( is_file( $conf ) && preg_match( '/^HOOK_PREFIX=([A-Za-z0-9_]+)/m', (string) file_get_contents( $conf ), $m ) ) { $prefix = strtolower( $m[1] ); } if ( '' === $prefix ) { fwrite( STDERR, "::error::No HOOK_PREFIX in ci/plugin.conf — refusing to guess which hooks are ours.\n" ); exit( 1 ); } return $prefix; } /** * Is this hook part of a contract, or is it internal wiring? * * 🔴 A contract is a name SOMEBODY ELSE has to know. That is the whole rule, * and getting it wrong in either direction ruins the check. * * The first version required every hook in the tree, which meant 50 core and * WooCommerce names — `admin_menu`, `init`, `wp_login`, `woocommerce_login_form` * — that we merely listen to. Listening to `init` is not a promise to anyone; * WordPress documents `init`. Requiring them would have made CONTRACT.md a * transcript of our own `add_action` calls, and the first person to read it * would stop, which is worse than not having the check. * * So the test is the PREFIX, because the prefix is exactly "is this a name the * family owns": * * do_action / apply_filters on nlsec_* or wpmgr_* * we are the source, or we are asking the family. Document it. * * add_filter / add_action on wpmgr_* * we are answering a name another plugin defined. It crosses a * repository boundary, which is the class of value nobody's checks cover. * Document it. * * add_filter / add_action on nlsec_* * our own wiring. If it is also offered, the first rule already caught * it; if it is not, nobody outside needs to know. * * anything else * core, WooCommerce, a third party. Not ours to document. * * Narrowing it this way is not loosening it. It found three real gaps on the * first run that the noisy version had buried under fifty core hooks: * `wpmgr_ai_usage` (a family-wide hook this plugin EMITS and had never told * anybody about), `nlsec_public_rest_routes` (a genuine extension point a form * plugin needs when a shop locks REST down) and `nlsec_pending_wp_config`. * * @param string $call do_action | apply_filters | add_filter | add_action * @param string $hook The hook name. * @return bool */ function is_contract( $call, $hook ) { // 🔴 From ci/plugin.conf, never a literal. The version of this file // published as woo-security-manager 52dd99d asked plugin.conf for the // prefix on the DOCUMENTED side (and refuses without it, correctly) and // still tested the SOURCE side against a hardcoded 'nlsec_'. Ported here // verbatim that is not a green-over-nothing — it is worse. Measured on this // tree with docs/CONTRACT.md documenting no hook at all: // // 3 hook(s) in the shipped source and not in docs/CONTRACT.md: // wpmgr_dashboard_cards, wpmgr_menu_glyph, wpmgr_menu_title // // Red, specific, and blind to all six wc_edm_* hooks — because 'wpmgr_' is // the same string in every tree and 'nlsec_' is the one that is not. Fix // those three and the check goes green over six undocumented contract // hooks, with a red run behind you as evidence that it works. A partially // blind check that fails is more convincing than one that passes. // // Note which step disarmed the guard: the floor at 20 shipped PHP files // refused to run in this 14-file tree, which is the only thing that stopped // it, and the porting instructions were to add HOOK_PREFIX and fix the // floor. Doing as told is what removed the protection. Two wrongs // cancelling into a pass, in the documented order. $ours = 0 === strpos( $hook, hook_prefix() ); $family = 0 === strpos( $hook, 'wpmgr_' ); if ( ! $ours && ! $family ) { return false; } if ( 'do_action' === $call || 'apply_filters' === $call ) { return true; } // add_filter / add_action: only when the name is the family's, i.e. we are // answering somebody else. return $family; } $root = isset( $argv[1] ) ? rtrim( $argv[1], '/' ) : '.'; $docs = $root . '/docs'; $fails = 0; function fail( $message ) { global $fails; $fails++; printf( "::error::%s\n", $message ); } /* * 1. The set exists and is not a stub. * * A floor, not a mere existence test: an empty file passes `is_file()`, and a * heading with nothing under it passes any check written from the concept of * "is it documented". The numbers are per-file because the documents have * genuinely different jobs — README is one screen on purpose. */ $required = array( 'README.md' => 25, 'SETUP.md' => 40, 'ARCHITECTURE.md' => 60, 'CONTRACT.md' => 50, 'RELEASE.md' => 40, ); $lines_total = 0; foreach ( $required as $file => $floor ) { $path = $docs . '/' . $file; if ( ! is_file( $path ) ) { fail( sprintf( 'docs/%s is missing.', $file ) ); continue; } $lines = count( file( $path, FILE_IGNORE_NEW_LINES ) ); $lines_total += $lines; if ( $lines < $floor ) { fail( sprintf( 'docs/%s has %d lines, under the floor of %d — a stub is not documentation.', $file, $lines, $floor ) ); } } if ( $fails > 0 ) { printf( "\n%d problem(s) with the document set.\n", $fails ); exit( 1 ); } printf( " %d documents, %d lines.\n", count( $required ), $lines_total ); /* * 2. The version in the docs is this plugin's version. * * Named value, not "a version is mentioned": a check that merely finds a * version-shaped string passes on last year's. */ $mains = glob( $root . '/*.php' ); $version = ''; foreach ( (array) $mains as $main ) { if ( preg_match( '/^\s*\*\s*Version:\s*([0-9][^\s]*)/m', (string) file_get_contents( $main ), $m ) ) { $version = $m[1]; break; } } if ( '' === $version ) { fail( 'No Version: header found in the plugin main file — nothing to compare the docs against.' ); } else { $readme = (string) file_get_contents( $docs . '/README.md' ); if ( false === strpos( $readme, $version ) ) { fail( sprintf( 'docs/README.md does not mention version %s.', $version ) ); } else { printf( " docs/README.md names version %s, which is the header's.\n", $version ); } } /* * 3. CONTRACT.md against the source, both directions. */ $listing = $root . '/ci/dist-files.sh'; if ( ! is_file( $listing ) ) { fail( 'ci/dist-files.sh is missing — cannot tell which files ship.' ); exit( 1 ); } exec( escapeshellcmd( $listing ) . ' 2>/dev/null', $shipped, $rc ); if ( 0 !== $rc ) { fail( 'ci/dist-files.sh failed — refusing to guess which files ship.' ); exit( 1 ); } $php = array_values( array_filter( $shipped, static function ( $f ) { return '.php' === substr( $f, -4 ); } ) ); // The floor comes from ci/plugin.conf, not from a literal. It arrived here as // 20 — measured in the tree this file was written in — and refused to run in // this 14-file one. A second hardcoded number per plugin is a second thing to // re-measure on every port, and the conf already carries this one. // // The floor is not the fault: a copied kit that reads zero files prints a // plausible number and passes. Refuse instead of reporting a green over // nothing — and refuse rather than warn, because a warning next to a plausible // number is read as a plausible number. $min_php = shipped_php_floor(); if ( count( $php ) < $min_php ) { fail( sprintf( 'Only %d shipped PHP files found, under the floor of %d. That is too few to be this tree — check the prefix and the paths before lowering this.', count( $php ), $min_php ) ); exit( 1 ); } $in_code = array(); $anywhere = array(); foreach ( $php as $file ) { $path = $root . '/' . $file; if ( ! is_file( $path ) ) { continue; } $source = (string) file_get_contents( $path ); // 🔴 Strip comments. See the header: our own docblocks contain the exact // calls this check looks for, and reading them turns the file that // explains a fault into the file that reports it. $code = ''; foreach ( token_get_all( $source ) as $token ) { if ( is_array( $token ) ) { if ( T_COMMENT === $token[0] || T_DOC_COMMENT === $token[0] ) { continue; } $code .= $token[1]; continue; } $code .= $token; } if ( preg_match_all( '/(do_action|apply_filters|add_filter|add_action)\(\s*\x27([a-z0-9_]+)\x27/', $code, $m, PREG_SET_ORDER ) ) { foreach ( $m as $hit ) { if ( is_contract( $hit[1], $hit[2] ) ) { $in_code[ $hit[2] ] = true; } } } /* * 🔴 A second, wider set, and the two directions need different ones. * * "Must be documented" is the narrow question — contract hooks only. * "Has this row gone stale" is a different one, and asking it against the * narrow set is wrong: it reported `nlsec_request_reputation` as no longer * existing, which is this plugin's most important contract. The only * occurrence in shipped code is `add_filter()` — we ANSWER it, and the * consumer applies it — so the contract classifier correctly declines to * demand it and the staleness check then read that as absence. * * Same for the five cron hooks, which the document names under a heading * that says they are explicitly NOT a contract. * * So: a documented name is stale only when it appears NOWHERE in the * shipped source. Every string literal, not just the ones in hook calls. */ if ( preg_match_all( '/\x27([a-z0-9_]+)\x27/', $code, $m ) ) { foreach ( $m[1] as $literal ) { $anywhere[ $literal ] = true; } } } // WordPress core hooks, and our own scheduled jobs, are named in the document // under headings of their own rather than in the tables. Listing them here is // what stops the check reporting them as undocumented forever — which is how a // floor gets lowered until the check reads nothing. $contract = (string) file_get_contents( $docs . '/CONTRACT.md' ); $documented = array(); if ( preg_match_all( '/`([a-z0-9_]+)`/', $contract, $m ) ) { foreach ( $m[1] as $name ) { $documented[ $name ] = true; } } $core = array( 'plugins_api', 'rest_api_init' ); $undocumented = array(); foreach ( array_keys( $in_code ) as $hook ) { if ( ! isset( $documented[ $hook ] ) ) { $undocumented[] = $hook; } } sort( $undocumented ); // The other direction is narrower on purpose: CONTRACT.md legitimately names // things that are not hooks (fields, codes, functions), so only names carrying // this plugin's own prefix are held to existing in the source. // The prefix comes from ci/plugin.conf, which every plugin in the family has, // rather than from a pattern over the hook names — a copied kit that guesses // the prefix from its own contents is how a check ends up reading zero files // in the next tree and printing a plausible number. $prefix = ''; if ( is_file( $root . '/ci/plugin.conf' ) && preg_match( '/^HOOK_PREFIX=([A-Za-z0-9_]+)/m', (string) file_get_contents( $root . '/ci/plugin.conf' ), $m ) ) { $prefix = strtolower( $m[1] ); } if ( '' === $prefix ) { fail( 'No HOOK_PREFIX in ci/plugin.conf — refusing to guess which documented names are ours.' ); exit( 1 ); } $stale = array(); foreach ( array_keys( $documented ) as $name ) { // Long enough to be a hook rather than the bare prefix itself, which is // also a table-name literal in the source. if ( 0 !== strpos( $name, $prefix ) || strlen( $name ) <= strlen( $prefix ) + 3 ) { continue; } if ( isset( $anywhere[ $name ] ) ) { continue; } /* * 🔴 A dynamic hook is built by concatenation, so the source carries the * literal PREFIX and the document has to carry the full name a reader * needs — `update_option_{$option}`, `site_transient_{$transient}`, * `plugin_action_links_{$file}`. Compared literally, that row is correct * in both files and fails forever, and the fix somebody reaches for is * deleting the row rather than the rule. Found by Nolimit Cache, whose * run was 56/56 with exactly one such false positive. */ $dynamic = false; foreach ( array_keys( $anywhere ) as $literal ) { if ( strlen( $literal ) > strlen( $prefix ) && 0 === strpos( $name, $literal ) ) { $dynamic = true; break; } } if ( ! $dynamic ) { $stale[] = $name; } } sort( $stale ); if ( $undocumented ) { fail( sprintf( '%d hook(s) in the shipped source and not in docs/CONTRACT.md: %s', count( $undocumented ), implode( ', ', $undocumented ) ) ); } if ( $stale ) { fail( sprintf( '%d name(s) in docs/CONTRACT.md that no longer exist in the source: %s', count( $stale ), implode( ', ', $stale ) ) ); } if ( ! $undocumented && ! $stale ) { printf( " %d hooks in %d shipped PHP files, all %d in docs/CONTRACT.md (prefix %s, %d core).\n", count( $in_code ), count( $php ), count( $in_code ), '' !== $prefix ? $prefix . '*' : '?', count( $core ) ); } if ( $fails > 0 ) { printf( "\n%d documentation problem(s).\n", $fails ); exit( 1 ); } exit( 0 );