Upload lint

What is checked before a release is written, and how to fix a finding.

The lint reads every file of a release before anything is written. The rules are Respira's own, written from the public descriptions of WordPress Plugin Check and the WordPress coding standards. Nothing is copied from either. There are 66 rules: 45 errors, 16 warnings and 5 notices. The numbers and the table below are generated from the add-on's rule table, Respira_Code_Lint::RULES, so they change when the lint does.

Errors, warnings, notices

An error refuses the upload with a 422 respira_code_lint_failed and lists every error as file:line [rule] message, with a fix. The respira CLI exits with 15 and nothing is written. Warnings and notices do not block. They come back in the deploy answer, at most 100 of them and at most 40 per rule, and the answer says how many it left out.

A finding, as the site answers it:

{
  "rule": "no-eval",
  "severity": "error",
  "file": "includes/Cart.php",
  "line": 40,
  "message": "eval() runs text as code.",
  "fix": "Remove eval(). Write the logic as code in the release; if a value drives behaviour, use a switch on a fixed list."
}

A finding never prints a secret in full. It shows 4 characters and a length.

What cannot be suppressed

28 rules can be turned off for one line, with a reason. The other 38 are fixed.

// respira-lint: allow no-extract because the keys are a fixed list of three settings
  • The comment goes on the line of the finding or the line above. The reason must be at least 12 characters, and every suppression is listed in the answer.
  • There is no global switch. A comment with no reason, an unknown rule, all or * is ignored and reported as suppression-invalid, which is a warning. So is a comment that names a rule no comment can switch off.
  • Never suppressible, errors: parse-error, abspath-guard, rest-permission, no-eval, no-obfuscation, no-closure-bind, no-reflection-forge, no-cron-override, no-internal-call, no-set-current-user, no-internal-string, no-option-filter, no-query-filter, no-wpdb-replace, no-sql-session, no-sql-protected-table, no-wpdb-reconfigure, no-core-internal, no-kit-shadow, no-extract, no-shell, hardcoded-secret, lint-budget-exceeded, manifest-json, manifest-route-public, manifest-abilities, manifest-ability-name, manifest-ability-route, manifest-ability-text, manifest-ability-schema, no-app-abilities, manifest-ability-annotations.
  • Never suppressible, warnings: manifest-ability-no-input-schema, suppression-invalid.
  • Never suppressible, notices: deprecated-index-missing, manifest-assets-unused, skipped-file, too-many.

Fix the code instead. These rules protect the site, not the style.

What an app may not touch

An app may not hook WordPress's query filter, replace $wpdb, filter Respira Code's own options, switch the current user, or call Respira's internal auth and state classes. An upload that does is refused, because each of these could change what Respira Code reads about which keys have developer access. The rules are no-query-filter, no-wpdb-replace, no-option-filter, no-set-current-user, no-internal-call, no-core-internal and no-internal-string, and no comment can switch any of them off. The lint is one guard among several: the safety rules say what it does not catch.

Size and time limits

  • Time. The lint gives each file 300 milliseconds and each release 2 seconds. When it runs out it stops and reports the error lint-budget-exceeded. A release the lint could not finish reading is not a release it approved.
  • PHP files over 256 KB are not read, and the release fails with lint-budget-exceeded. The limit can be lower on a host with little free memory, and the message gives the size it used. Split the file, or remove generated code from it.
  • Files over 2 MB, of any kind, are skipped, and the answer lists them in a skipped-file notice.
  • JavaScript over 256 KB is treated as a vendored bundle and its JavaScript rules are skipped.

Run respira app lint on your machine first. It runs php -l, PHPStan at level 5 with WordPress stubs, WordPress-Extra for PHP_CodeSniffer and tsc, each when it is installed, and it names any tool it skipped with the command to install it. Add --site or --server to also run the site's own lint on an uploaded release. The site reads GET /apps/<slug>/lint?release=<id>.

Every rule, with its fix

The family names help you read a finding. The table lists every rule in the order the lint declares them.

RuleLevelComment can switch it offWhat it checksFix
parse-error Error No PHP cannot read the file. Fix the syntax error on the line named.
abspath-guard Error No A PHP file does not start with the ABSPATH guard. Make it the first statement: if ( ! \defined( 'ABSPATH' ) ) { exit; }, with the backslash inside a namespace.
redeclare Error Yes A function or class sits outside the app namespace. Put the file in namespace RespiraApp\<App> and keep every function and class inside it.
namespace-segment Warning Yes The namespace is not the one made from the app slug. Use the namespace the scaffold writes, RespiraApp\ followed by the slug in StudlyCase.
unescaped-output Error Yes A value is printed without escaping. Escape at the echo: esc_html(), esc_attr(), esc_url() or wp_kses_post().
unprepared-sql Error Yes A query has a value written into its text. Use $wpdb->prepare() with %s, %d or %f, and pass the value as an argument.
unsanitized-input Error Yes A request value is read without sanitising it. Wrap it where you read it: sanitize_text_field( wp_unslash( $_POST['x'] ) ), absint() or sanitize_email().
rest-permission Error No A REST route has no permission_callback, or a public write route is not declared. Add a real permission_callback; for a public write route declare it in app.json and call \respira_app_rate_limit() first.
rest-capability-only Warning Yes A write route checks a capability and nothing about API credentials. For an owner-only act call \respira_app_owner_request() in the permission_callback.
rest-args-unreadable Warning Yes The lint cannot read the arguments of a route. Write the array out inside the register_rest_route() call, permission_callback included.
handler-nonce Error Yes An admin-post or AJAX handler never checks a nonce. Call check_admin_referer() or check_ajax_referer() first, and print the nonce in the form.
handler-capability Error Yes An admin-post or AJAX handler never checks a capability. Call current_user_can() before the handler changes anything, and stop when it fails.
handler-unresolved Error Yes The lint cannot find a handler by the name it was registered under. Register a closure, or a function or method of this release by its full name.
no-eval Error No eval(), create_function() or a string callback runs text as code. Remove it and write the logic as code in the release.
no-obfuscation Error No Decoded text feeds code that runs. Ship readable PHP.
no-closure-bind Error No Closure::bind, bindTo or fromCallable points at a Respira_Code_ class or respira_code_ function. Remove it. Bind closures to the app's own classes only.
no-reflection-forge Error No Reflection points at Respira Code, or newInstanceWithoutConstructor is used. Remove it. An app uses the respira_app_* functions only.
no-cron-override Error No wp_doing_cron, pre_option_cron or DOING_CRON is touched from app code. Remove it. Declare the job in app.json and let WordPress cron run it.
no-internal-call Error No App code uses a Respira_Code_ class, a respira_code_ function or a respira_code_ hook. Use the respira_app_* functions only.
no-set-current-user Error No App code calls or names wp_set_current_user(). Remove it. An app acts as the visitor it serves.
no-internal-string Error No A string names a respira_code_ option, table or hook that only the add-on may use. Keep the app's data in its own tables and options, and use the respira_app_* functions.
no-option-filter Error No App code hooks an option filter of a respira_code_ option, or a filter that can change how any option reads. Remove the hook. An app that needs a value keeps it in its own option.
no-query-filter Error No App code hooks the WordPress query filter, or writes to $wp_filter by hand. Remove it. Change what the app reads in its own queries.
no-wpdb-replace Error No App code assigns to $wpdb or $GLOBALS['wpdb'], or extends wpdb. Use the global $wpdb as it is.
no-sql-session Error No App SQL runs USE, makes a temporary table named like a WordPress or Respira table, or controls transactions (START TRANSACTION, BEGIN, SET autocommit, COMMIT, ROLLBACK, SAVEPOINT). Run plain queries on the app's own tables. Give a temporary table a name of the app's own.
no-sql-protected-table Error No App SQL writes to a table with respira in its name, or to users or usermeta (INSERT, UPDATE, DELETE, REPLACE, ALTER, RENAME, DROP or TRUNCATE). Reads are allowed. Use the WordPress user functions, and keep the app's data in its own tables.
no-wpdb-reconfigure Error No App code writes a $wpdb property such as prefix, options, a table name or dbh, or calls set_prefix(), select(), db_connect(), set_blog_id() or close(). Leave $wpdb as WordPress set it up. Read table names, never change them.
no-core-internal Error No App code names Respira_Auth, Respira_Managers or Respira_Keys_Rest, which make keys and decide who manages Respira. Remove it. An app runs as the visitor it serves.
no-kit-shadow Error No The app declares a name starting with respira_app_, respira_code_ or Respira_Code_. Rename it. Nothing an app declares may start with those.
no-extract Error No extract() turns array keys into variables. Read the keys by name: $name = $data['name'] ?? '';
no-shell Error No A shell call, a backtick string or a program-running callback. Remove it. An app cannot run programs on the host.
http-timeout Warning Yes A request is made with no timeout. Pass a timeout to wp_remote_get() or wp_remote_post().
file-write Error Yes A file is written outside the app state folder. Write only below respira_app_state_dir().
hardcoded-secret Error No A secret-shaped value is written into the code. Declare the name under secrets in app.json and read it with respira_secret(). Rotate the one you uploaded.
text-domain Warning Yes A translation function has no text domain. Pass the app slug as the text domain.
enqueue-version Warning Yes A script or style is enqueued with no version. Pass the app version as the fourth argument.
inline-asset Warning Yes A script or style is written straight into the page. Enqueue it, and use wp_add_inline_script() for the few lines that must be inline.
inline-handler Warning Yes Markup has an onclick or similar attribute. Attach the handler with addEventListener() in an enqueued script.
date-function Notice Yes date() ignores the site time zone. Use wp_date() to format and current_time() to read.
deprecated-function Warning Yes A function the site's WordPress marks deprecated. Replace it with the function the message names.
deprecated-index-missing Notice No The site has not built its WordPress API index yet, so deprecations were not checked. Nothing to change. Lint again once the index is built.
lint-budget-exceeded Error No The lint could not finish reading a file or the release in its time or memory budget. Split big files and remove generated code, then upload again.
js-inline-handler Warning Yes JavaScript writes markup with an inline event handler. Create the element and attach the handler with addEventListener().
manifest-json Error No app.json is not a JSON object. Fix the JSON. Everything else in the lint reads it.
manifest-route-public Error No A public route is not declared with public, a reason and a rate limit. Declare "auth": "public", "public": true, a "reason" of 1 to 200 characters, and a rate_limit.
manifest-route-auth Error Yes A route does not say who may call it. Add "auth": "public", "logged_in", "nonce" or "capability:<cap>".
manifest-route-rate-limit Error Yes A route has no rate limit. Add "rate_limit": "60/min", or what the route can take.
manifest-cron-interval Error Yes A job does not say how often it runs. Add "schedule": "hourly", "twicedaily", "daily" or "weekly".
manifest-retention Error Yes Personal data has no retention rule, or the rule is malformed. Add a rule with after.column and after.days, and a where when the table has a status column.
manifest-unsubscribe Error Yes An email for many people has no unsubscribe link. Put {{respira.unsubscribe_link}} in every language of the template.
manifest-abilities Error No The abilities list is not well formed, or its text is too long together. Write at most 16 abilities, each with name, label, description and route, under 32 KB of text in all.
manifest-assets-unused Notice No app.json has an assets key, which nothing reads. Remove the key. Files in assets/ are served without it.
manifest-ability-name Error No An ability is not named respira-app-<slug>/<what>. Name it under the app's own prefix, lowercase, up to 64 characters after the slash.
manifest-ability-route Error No An ability points at a route the manifest does not declare, or an owner-only route. Point route at a declared endpoint that agents may call.
manifest-ability-text Error No A label or description is empty, too long or holds invisible characters. Write a label up to 80 and a description up to 600 characters, in plain text.
manifest-ability-schema Error No An input or output schema is invalid or too big. Write a JSON Schema object under 8 KB and 6 levels, with no input name starting with an underscore.
no-app-abilities Error No App code calls the Abilities API itself. Declare the ability under abilities in app.json instead.
manifest-ability-no-input-schema Warning No An ability has no input_schema, so it takes no input. Declare input_schema.
manifest-ability-annotations Error No Annotations do not fit the route method. readonly only on a GET route; a DELETE route says destructive; never both.
js-innerhtml Warning Yes innerHTML or similar is set from something other than a fixed string. Set textContent, or build elements with createElement().
js-eval Warning Yes JavaScript calls eval or builds code from a string. Remove it. Parse data with JSON.parse().
js-document-write Warning Yes document.write() is used. Create the element and append it.
js-fetch-credentials Warning Yes fetch() calls another origin without saying whether cookies go along. Pass { credentials: 'omit' } for a public API.
skipped-file Notice No A file was not read in full, for example one over the size limit. Nothing to do unless it is your own code. Then split it.
too-many Notice No A rule hit more often than the answer lists. Fix the ones listed and lint again.
suppression-invalid Warning No A respira-lint comment has no real reason, names an unknown rule, or names a rule no comment can switch off. Write: // respira-lint: allow <rule> because <why it is safe here>, for a rule that can be suppressed.

The lint also reads the code samples in these docs. Each one was run through it, and none has an error or a warning. The two samples that show a refusal on purpose produce exactly the rule they show.