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,
allor*is ignored and reported assuppression-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-filenotice. - 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.
| Rule | Level | Comment can switch it off | What it checks | Fix |
|---|---|---|---|---|
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.