Lint.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Encode - Template output lint
 *
 * @package Italix\Encode
 * @license MPL-2.0
 */

declare(strict_types=1);

namespace Italix\Encode;

/**
 * Fails the build on any template output that is not encoded.
 *
 * The encoders in Html are only half a defence: an encoder that must be invoked
 * is not a default, and a template that forgot one renders correctly for every
 * value anyone tries by hand. This turns "we always encode" from a habit into
 * something CI can refuse to merge.
 *
 *     $lint = new Lint(['/^\$view->get\(/', '/^\$form_html->/']);
 *     foreach ($lint->check_paths(['src/Views', 'src/Themes']) as $finding) {
 *         printf("%s:%d: %s\n", $finding['file'], $finding['line'], $finding['expression']);
 *     }
 *
 * The check is deliberately shallow but exact about where it looks. It reads
 * PHP's own token stream rather than matching source text, because a regex
 * cannot tell `<?= $x ?>` from the same characters inside a string literal or a
 * comment. For every echo it splits the expression into the terms that actually
 * reach the page — through concatenation, comma lists, ?? and the branches of a
 * ternary, but not a ternary's condition, which is tested and discarded — and
 * requires each one to be a literal, a numeric cast, an Html encoder call, or a
 * match against the project's allow list.
 *
 * The encoder alias is resolved from the file's own `use` statements, so a file
 * that writes `H::e(...)` without importing Italix\Encode\Html is reported: the
 * lint accepts the encoder, not the letter H.
 *
 * What it cannot see is the limit worth stating plainly: it reads source text,
 * so a value assembled at runtime and emitted through an allow-listed
 * expression passes unexamined, and a template outside the paths it is given is
 * not checked at all. This is a static guarantee standing in for a guarantee
 * the template engine does not provide — good enough to keep a codebase honest,
 * not the same thing as escaping in the compiler.
 */
final class Lint
{
    /** Methods on Html that produce encoded output. */
    private const ENCODER_METHODS = ['e', 'raw', 'j', 'attribs', 'url'];

    /** The class an alias has to resolve to, lower-cased. */
    private const ENCODER_CLASS = 'italix\encode\html';

    /**
     * Other classes whose static methods return an already-encoded value.
     *
     * A project builds encoders of its own on top of this one — a translator
     * that returns `Html`, a money formatter, a markdown renderer that has run
     * a sanitiser. Their output is safe for the same reason `Html::e()`'s is,
     * and without a way to say so the lint reports every call and the report
     * becomes noise somebody learns to skip past. A lint nobody reads is worse
     * than no lint, because it looks like coverage.
     *
     * Registered by name, not by prefix, and still resolved through the file's
     * own `use` statements: the point stands that the lint accepts the class,
     * not the letter it was aliased to.
     *
     * @var array<string, string[]> lower-cased FQCN => methods it encodes with
     */
    private array $encoder_classes;

    /** @var string[] PCRE patterns matched against a term's source. */
    private array $allow;

    /** @var string[] */
    private array $extensions;

    /**
     * @param string[] $allow      PCRE patterns for expressions that are safe by other means
     * @param string[] $extensions File extensions to scan
     * @param array<int|string, string|string[]> $encoders Extra classes whose static
     *        methods return encoded values. Either a bare name, which takes the
     *        same method list as Html, or `name => ['method', …]` when the class
     *        encodes through methods of its own — a translator's `choice_e()`,
     *        say, which has no counterpart here.
     */
    public function __construct(array $allow = [], array $extensions = ['php'], array $encoders = [])
    {
        $this->allow      = $allow;
        $this->extensions = $extensions;

        $this->encoder_classes = [];

        foreach ($encoders as $key => $value) {
            $fqcn    = is_int($key) ? (string) $value : (string) $key;
            $methods = is_int($key) ? self::ENCODER_METHODS : (array) $value;

            $this->encoder_classes[strtolower(ltrim($fqcn, '\\'))] = $methods;
        }
    }

    // -------------------------------------------------------------------------
    // Public
    // -------------------------------------------------------------------------

    /**
     * @param string[] $paths Files or directories
     * @return array<int,array{file:string,line:int,expression:string}>
     */
    public function check_paths(array $paths): array
    {
        $findings = [];

        foreach ($paths as $path) {
            foreach ($this->files_in($path) as $file) {
                foreach ($this->check_file($file) as $finding) {
                    $findings[] = $finding;
                }
            }
        }

        return $findings;
    }

    /**
     * @return array<int,array{file:string,line:int,expression:string}>
     */
    public function check_file(string $file): array
    {
        $code = file_get_contents($file);
        if ($code === false) {
            throw new \RuntimeException(sprintf('Lint: cannot read %s', $file));
        }

        $tokens  = token_get_all($code);
        $aliases = $this->encoder_aliases($tokens);
        $count   = count($tokens);

        $findings = [];

        for ($i = 0; $i < $count; $i++) {
            if (!$this->is_echo($tokens[$i])) {
                continue;
            }

            $line = $tokens[$i][2];
            $expr = $this->collect_expression($tokens, $i, $count);

            foreach ($this->output_terms($expr) as $term) {
                if ($this->term_is_safe($term, $aliases)) {
                    continue;
                }

                $findings[] = [
                    'file'       => $file,
                    'line'       => $line,
                    'expression' => $this->source($term),
                ];
            }
        }

        return $findings;
    }

    // -------------------------------------------------------------------------
    // Scanning
    // -------------------------------------------------------------------------

    /**
     * @return string[]
     */
    private function files_in(string $path): array
    {
        if (is_file($path)) {
            return [$path];
        }

        if (!is_dir($path)) {
            throw new \RuntimeException(sprintf('Lint: no such file or directory: %s', $path));
        }

        $files    = [];
        $iterator = new \RecursiveIteratorIterator(
            new \RecursiveDirectoryIterator($path, \FilesystemIterator::SKIP_DOTS)
        );

        foreach ($iterator as $entry) {
            /** @var \SplFileInfo $entry */
            if ($entry->isFile() && in_array($entry->getExtension(), $this->extensions, true)) {
                $files[] = $entry->getPathname();
            }
        }

        sort($files);

        return $files;
    }

    /**
     * @param array|string $token
     */
    private function is_echo($token): bool
    {
        return is_array($token)
            && in_array($token[0], [T_OPEN_TAG_WITH_ECHO, T_ECHO, T_PRINT], true);
    }

    /**
     * Everything between the echo and its terminating ; or ?>.
     *
     * @param array<int,array|string> $tokens
     * @return array<int,array|string>
     */
    private function collect_expression(array $tokens, int &$i, int $count): array
    {
        $expr  = [];
        $depth = 0;

        for ($i++; $i < $count; $i++) {
            $token = $tokens[$i];
            $delta = $this->depth_delta($token);

            if ($delta !== 0) {
                $depth += $delta;
            } elseif ($depth === 0) {
                if ($token === ';') {
                    break;
                }
                if (is_array($token) && $token[0] === T_CLOSE_TAG) {
                    break;
                }
            }

            $expr[] = $token;
        }

        return $expr;
    }

    /**
     * Nesting contributed by a token.
     *
     * The subtlety that makes a hand-rolled depth counter wrong: in `"{$a}"`
     * the opening brace arrives as the *array* token T_CURLY_OPEN while the
     * closing one is the plain string '}'. Counting only strings drives the
     * depth negative, and from there every separator looks top-level and the
     * expression never terminates.
     *
     * @param array|string $token
     */
    private function depth_delta($token): int
    {
        if (is_string($token)) {
            if (strpos('([{', $token) !== false) {
                return 1;
            }
            return strpos(')]}', $token) !== false ? -1 : 0;
        }

        return in_array($token[0], self::opening_tokens(), true) ? 1 : 0;
    }

    /**
     * @return int[]
     */
    private static function opening_tokens(): array
    {
        static $tokens = null;

        if ($tokens === null) {
            $tokens = [T_CURLY_OPEN, T_DOLLAR_OPEN_CURLY_BRACES];
            if (defined('T_ATTRIBUTE')) {
                $tokens[] = T_ATTRIBUTE;                       // #[ … ] — PHP 8
            }
        }

        return $tokens;
    }

    // -------------------------------------------------------------------------
    // Expression analysis
    // -------------------------------------------------------------------------

    /**
     * The terms that actually reach the page.
     *
     * Splits on concatenation, comma lists and ??; for a ternary, drops the
     * condition and keeps both branches, since only those are printed.
     *
     * @param array<int,array|string> $expr
     * @return array<int,array<int,array|string>>
     */
    private function output_terms(array $expr): array
    {
        $expr = $this->strip_ternary_condition($expr);

        $terms   = [];
        $current = [];
        $depth   = 0;

        foreach ($expr as $token) {
            $delta = $this->depth_delta($token);

            if ($delta !== 0) {
                $depth += $delta;
            } elseif ($depth === 0 && $this->is_term_separator($token)) {
                $terms[] = $current;
                $current = [];
                continue;
            }

            $current[] = $token;
        }

        $terms[] = $current;

        return array_values(array_filter($terms, fn(array $t): bool => $this->source($t) !== ''));
    }

    /**
     * @param array|string $token
     */
    private function is_term_separator($token): bool
    {
        if (is_string($token)) {
            return $token === '.' || $token === ',' || $token === ':';
        }

        return $token[0] === T_COALESCE;
    }

    /**
     * A ternary's condition is tested, not printed. `?:` has no condition to
     * drop — both sides can reach the page — so it is left alone.
     *
     * @param array<int,array|string> $expr
     * @return array<int,array|string>
     */
    private function strip_ternary_condition(array $expr): array
    {
        $depth = 0;

        foreach ($expr as $index => $token) {
            $delta = $this->depth_delta($token);

            if ($delta !== 0) {
                $depth += $delta;
            } elseif ($token === '?' && $depth === 0) {
                $rest = array_slice($expr, $index + 1);

                // `?:` — the left operand is printed when truthy, so keep it.
                foreach ($rest as $next) {
                    if (is_array($next) && $next[0] === T_WHITESPACE) {
                        continue;
                    }
                    return ($next === ':') ? $expr : $rest;
                }

                return $rest;
            }
        }

        return $expr;
    }

    /**
     * @param array<int,array|string> $term
     * @param string[]                $aliases
     */
    private function term_is_safe(array $term, array $aliases): bool
    {
        $significant = array_values(array_filter($term, static function ($token): bool {
            return !is_array($token)
                || !in_array($token[0], [T_WHITESPACE, T_COMMENT, T_DOC_COMMENT], true);
        }));

        if ($significant === []) {
            return true;
        }

        // A literal cannot carry markup it did not already contain.
        $literal = true;
        foreach ($significant as $token) {
            if (!is_array($token)
                || !in_array($token[0], [T_CONSTANT_ENCAPSED_STRING, T_LNUMBER, T_DNUMBER], true)) {
                $literal = false;
                break;
            }
        }
        if ($literal) {
            return true;
        }

        // (int) $x and friends cannot produce a tag.
        $first = $significant[0];
        if (is_array($first) && in_array($first[0], [T_INT_CAST, T_DOUBLE_CAST, T_BOOL_CAST], true)) {
            return true;
        }

        $source = $this->source($term);

        if ($this->is_encoder_call($source, $aliases)) {
            return true;
        }

        foreach ($this->allow as $pattern) {
            if (preg_match($pattern, $source) === 1) {
                return true;
            }
        }

        return false;
    }

    /**
     * @param string[] $aliases
     */
    private function is_encoder_call(string $source, array $aliases): bool
    {
        $matched = preg_match(
            '/^\\\\?((?:[A-Za-z_][A-Za-z0-9_]*\\\\)*[A-Za-z_][A-Za-z0-9_]*)::([A-Za-z_]+)\s*\(/',
            trim($source),
            $m
        );

        if ($matched !== 1) {
            return false;
        }

        $alias = strtolower($m[1]);

        return isset($aliases[$alias]) && in_array($m[2], $aliases[$alias], true);
    }

    // -------------------------------------------------------------------------
    // Alias resolution
    // -------------------------------------------------------------------------

    /**
     * Names that refer to an encoder inside this file, lower-cased, each mapped
     * to the methods it encodes with.
     *
     * Always includes the fully qualified names; anything shorter has to be
     * earned by a `use` statement, so `H::e(...)` in a file that never imported
     * the class is reported rather than trusted.
     *
     * @param array<int,array|string> $tokens
     * @return array<string, string[]>
     */
    private function encoder_aliases(array $tokens): array
    {
        $known   = [self::ENCODER_CLASS => self::ENCODER_METHODS] + $this->encoder_classes;
        $aliases = $known;

        foreach ($this->use_clauses($tokens) as $clause) {
            if (stripos($clause, 'function ') === 0 || stripos($clause, 'const ') === 0) {
                continue;
            }

            foreach ($this->expand_group_use($clause) as $import) {
                if (preg_match('/^(.+?)\s+as\s+(\S+)$/i', $import, $m) === 1) {
                    $fqcn  = ltrim($m[1], '\\');
                    $alias = $m[2];
                } else {
                    $fqcn  = ltrim($import, '\\');
                    $parts = explode('\\', $fqcn);
                    $alias = end($parts);
                }

                if (isset($known[strtolower($fqcn)])) {
                    $aliases[strtolower($alias)] = $known[strtolower($fqcn)];
                }
            }
        }

        return $aliases;
    }

    /**
     * The source of every import `use`, read from the token stream.
     *
     * A regex would need an anchor, and every anchor is wrong for some real
     * file: `^use` misses `<?php use … ?>` on one line, and an unanchored match
     * hits the word inside comments. Tokens have no such ambiguity. Closure
     * `use (…)` is excluded by looking at what precedes the keyword.
     *
     * @param array<int,array|string> $tokens
     * @return string[]
     */
    private function use_clauses(array $tokens): array
    {
        $clauses  = [];
        $count    = count($tokens);
        $previous = null;

        for ($i = 0; $i < $count; $i++) {
            $token = $tokens[$i];

            if (is_array($token) && in_array($token[0], [T_WHITESPACE, T_COMMENT, T_DOC_COMMENT], true)) {
                continue;
            }

            if (is_array($token) && $token[0] === T_USE && $previous !== ')') {
                $clause = '';
                for ($i++; $i < $count && $tokens[$i] !== ';'; $i++) {
                    $clause .= is_array($tokens[$i]) ? $tokens[$i][1] : $tokens[$i];
                }
                $clauses[] = trim(preg_replace('/\s+/', ' ', $clause) ?? '');
                $previous  = ';';
                continue;
            }

            $previous = is_array($token) ? $token[1] : $token;
        }

        return $clauses;
    }

    /**
     * `A\B\{C, D as E}` → ['A\B\C', 'A\B\D as E'].
     *
     * @return string[]
     */
    private function expand_group_use(string $clause): array
    {
        if (preg_match('/^(.*?)\\\\\{(.+)\}$/', $clause, $m) !== 1) {
            return [$clause];
        }

        $prefix  = $m[1];
        $imports = [];

        foreach (explode(',', $m[2]) as $item) {
            $item = trim($item);
            if ($item !== '') {
                $imports[] = $prefix . '\\' . $item;
            }
        }

        return $imports;
    }

    // -------------------------------------------------------------------------
    // Helpers
    // -------------------------------------------------------------------------

    /**
     * @param array<int,array|string> $tokens
     */
    private function source(array $tokens): string
    {
        $out = '';

        foreach ($tokens as $token) {
            $out .= is_array($token) ? $token[1] : $token;
        }

        return trim($out);
    }
}