[Schema] Add schema parser package

projects/packages/schema/.gitattributes

@@ -0,0 +1,17 @@
+# Files not needed to be distributed in the package.
+.gitattributes    export-ignore
+.github/          export-ignore
+package.json      export-ignore
+
+# Files to include in the mirror repo, but excluded via gitignore
+# Remember to end all directories with `/**` to properly tag every file.
+# /src/js/example.min.js  production-include
+
+# Files to exclude from the mirror repo, but included in the monorepo.
+# Remember to end all directories with `/**` to properly tag every file.
+.gitignore        production-exclude
+changelog/**      production-exclude
+phpunit.xml.dist  production-exclude
+.phpcs.dir.xml    production-exclude
+tests/**          production-exclude
+.phpcsignore      production-exclude

projects/packages/schema/.gitignore

@@ -0,0 +1,3 @@
+vendor/
+node_modules/
+wordpress

projects/packages/schema/.phan/baseline.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * This is an automatically generated baseline for Phan issues.
+ * When Phan is invoked with --load-baseline=path/to/baseline.php,
+ * The pre-existing issues listed in this file won't be emitted.
+ *
+ * This file can be updated by invoking Phan with --save-baseline=path/to/baseline.php
+ * (can be combined with --load-baseline)
+ */
+return [
+    // # Issue statistics:
+    // PhanNonClassMethodCall : 10+ occurrences
+    // PhanParamTooFew : 5 occurrences
+    // PhanTypeMismatchArgumentProbablyReal : 2 occurrences
+    // PhanImpossibleCondition : 1 occurrence
+    // PhanImpossibleTypeComparison : 1 occurrence
+    // PhanParamTooMany : 1 occurrence
+    // PhanRedundantCondition : 1 occurrence
+    // PhanTypeMismatchArgumentNullable : 1 occurrence
+    // PhanTypeMismatchReturn : 1 occurrence
+
+    // Currently, file_suppressions and directory_suppressions are the only supported suppressions
+    'file_suppressions' => [
+        'src/class-schema.php' => ['PhanParamTooMany'],
+        'src/class-utils.php' => ['PhanImpossibleCondition', 'PhanRedundantCondition'],
+        'src/types/class-type-assoc-array.php' => ['PhanTypeMismatchArgumentNullable', 'PhanTypeMismatchReturn'],
+        'src/types/class-type-string.php' => ['PhanImpossibleTypeComparison'],
+        'tests/php/integration/test-integration-fallback-values.php' => ['PhanNonClassMethodCall'],
+        'tests/php/integration/test-integration-parsing-errors.php' => ['PhanNonClassMethodCall', 'PhanParamTooFew'],
+        'tests/php/type/test-type-assoc-array.php' => ['PhanTypeMismatchArgumentProbablyReal'],
+    ],
+    // 'directory_suppressions' => ['src/directory_name' => ['PhanIssueName1', 'PhanIssueName2']] can be manually added if needed.
+    // (directory_suppressions will currently be ignored by subsequent calls to --save-baseline, but may be preserved in future Phan releases)
+];

projects/packages/schema/.phan/config.php

@@ -0,0 +1,13 @@
+<?php
+/**
+ * This configuration will be read and overlaid on top of the
+ * default configuration. Command-line arguments will be applied
+ * after this file is read.
+ *
+ * @package automattic/jetpack-schema
+ */
+
+// Require base config.
+require __DIR__ . '/../../../../.phan/config.base.php';
+
+return make_phan_config( dirname( __DIR__ ) );

projects/packages/schema/.phpcs.dir.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0"?>
+<ruleset>
+
+	<rule ref="WordPress.WP.I18n">
+		<properties>
+			<property name="text_domain" type="array">
+				<element value="jetpack-schema" />
+			</property>
+		</properties>
+	</rule>
+	<rule ref="Jetpack.Functions.I18n">
+		<properties>
+			<property name="text_domain" value="jetpack-schema" />
+		</properties>
+	</rule>
+
+	<rule ref="WordPress.Utils.I18nTextDomainFixer">
+		<properties>
+			<property name="old_text_domain" type="array" />
+			<property name="new_text_domain" value="jetpack-schema" />
+		</properties>
+	</rule>
+
+	<rule ref="VariableAnalysis.CodeAnalysis.VariableAnalysis">
+		<properties>
+			<property name="ignoreUnusedRegexp" value="/^_/"/>
+		</properties>
+	</rule>
+
+	<rule ref="MediaWiki.Usage.ForbiddenFunctions">
+		<exclude name="MediaWiki.Usage.ForbiddenFunctions.isset"/>
+	</rule>
+
+	<rule ref="Squiz.Commenting.FunctionComment">
+		<exclude name="Squiz.Commenting.FunctionComment.MissingParamComment"/>
+		<exclude name="Squiz.Commenting.FunctionComment.MissingParamName"/>
+		<exclude name="Squiz.Commenting.FunctionComment.MissingParamTag"/>
+		<exclude name="Squiz.Commenting.FunctionComment.MissingReturn"/>
+		<exclude name="Squiz.Commenting.FunctionComment.ParamCommentFullStop"/>
+	</rule>
+	<rule ref="Generic.Commenting.DocComment">
+		<exclude name="Generic.Commenting.DocComment.MissingShort"/>
+	</rule>
+	<rule ref="Squiz.Commenting.FunctionComment">
+		<exclude name="Squiz.Commenting.FunctionComment.Missing"/>
+	</rule>
+	<rule ref="Squiz.Commenting.ClassComment">
+		<exclude name="Squiz.Commenting.ClassComment.Missing"/>
+	</rule>
+	<rule ref="Squiz.Commenting.FileComment">
+		<exclude name="Squiz.Commenting.FileComment.Missing"/>
+	</rule>
+	<rule ref="Squiz.Commenting.VariableComment">
+		<exclude name="Squiz.Commenting.VariableComment.Missing"/>
+	</rule>
+
+</ruleset>

projects/packages/schema/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+

projects/packages/schema/README.md

@@ -0,0 +1,24 @@
+# schema
+
+Define a schema to validate or sanitize data in php
+
+## How to install schema
+
+### Installation From Git Repo
+
+## Contribute
+
+## Get Help
+
+## Using this package in your WordPress plugin
+
+If you plan on using this package in your WordPress plugin, we would recommend that you use [Jetpack Autoloader](https://packagist.org/packages/automattic/jetpack-autoloader) as your autoloader. This will allow for maximum interoperability with other plugins that use this package as well.
+
+## Security
+
+Need to report a security vulnerability? Go to [https://automattic.com/security/](https://automattic.com/security/) or directly to our security bug bounty site [https://hackerone.com/automattic](https://hackerone.com/automattic).
+
+## License
+
+schema is licensed under [GNU General Public License v2 (or later)](./LICENSE.txt)
+

projects/packages/schema/changelog/initial-version

@@ -0,0 +1,4 @@
+Significance: patch
+Type: added
+
+Initial version.

projects/packages/schema/composer.json

@@ -0,0 +1,64 @@
+{
+	"name": "automattic/jetpack-schema",
+	"description": "Define a schema to validate or sanitize data in php",
+	"type": "jetpack-library",
+	"license": "GPL-2.0-or-later",
+	"require": {
+		"php": ">=7.0"
+	},
+	"require-dev": {
+		"yoast/phpunit-polyfills": "1.1.0",
+		"automattic/jetpack-changelogger": "@dev",
+		"automattic/wordbless": "dev-master"
+	},
+	"autoload": {
+		"classmap": [
+			"src/"
+		]
+	},
+	"scripts": {
+		"build-development": "echo 'Add your build step to composer.json, please!'",
+		"build-production": "echo 'Add your build step to composer.json, please!'",
+		"phpunit": [
+			"./vendor/phpunit/phpunit/phpunit --colors=always"
+		],
+		"test-php": [
+			"@composer phpunit"
+		],
+		"post-install-cmd": "WorDBless\\Composer\\InstallDropin::copy",
+		"post-update-cmd": "WorDBless\\Composer\\InstallDropin::copy"
+	},
+	"repositories": [
+		{
+			"type": "path",
+			"url": "../../packages/*",
+			"options": {
+				"monorepo": true
+			}
+		}
+	],
+	"minimum-stability": "dev",
+	"prefer-stable": true,
+	"extra": {
+		"autotagger": true,
+		"branch-alias": {
+			"dev-trunk": "0.1.x-dev"
+		},
+		"changelogger": {
+			"link-template": "https://github.com/Automattic/jetpack-schema/compare/v${old}...v${new}"
+		},
+		"mirror-repo": "Automattic/jetpack-schema",
+		"textdomain": "jetpack-schema",
+		"version-constants": {
+			"::PACKAGE_VERSION": "src/class-schema.php"
+		}
+	},
+	"suggest": {
+		"automattic/jetpack-autoloader": "Allow for better interoperability with other plugins that use this package."
+	},
+	"config": {
+		"allow-plugins": {
+			"roots/wordpress-core-installer": true
+		}
+	}
+}

projects/packages/schema/phpunit.xml.dist

@@ -0,0 +1,14 @@
+<phpunit bootstrap="tests/php/bootstrap.php" backupGlobals="false" colors="true" convertDeprecationsToExceptions="true">
+	<testsuites>
+		<testsuite name="main">
+			<directory prefix="test" suffix=".php">tests/php</directory>
+		</testsuite>
+	</testsuites>
+	<filter>
+		<whitelist processUncoveredFilesFromWhitelist="false">
+			<!-- Better to only include "src" than to add "." and then exclude "tests", "vendor", and so on, as PHPUnit still scans the excluded directories. -->
+			<!-- Add additional lines for any files or directories outside of src/ that need coverage. -->
+			<directory suffix=".php">src</directory>
+		</whitelist>
+	</filter>
+</phpunit>

projects/packages/schema/src/class-schema-context.php

@@ -0,0 +1,119 @@
+<?php
+
+namespace Automattic\Jetpack\Schema;
+
+class Schema_Context {
+
+	private $name;
+	private $data;
+	private $path = array();
+
+	/**
+	 * @var array $log Log of notable actions taken during parsing.
+	 */
+	private $log = array();
+
+	/**
+	 * @param string $name
+	 */
+	public function __construct( $name ) {
+		$this->name = $name;
+	}
+
+	public function add_to_path( $key ) {
+		$this->path[] = $key;
+	}
+
+	private function trace( $depth_limit = 15 ) {
+
+		if ( ! Utils::is_debug() ) {
+			return;
+		}
+
+		$trace = array();
+		// This is fine, it's guarded by `SCHEMA_TRACE` constant.
+		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_debug_backtrace
+		foreach ( debug_backtrace() as $stack_frame ) {
+			if ( isset( $stack_frame['line'], $stack_frame['file'] ) ) {
+				$filename_pieces = explode( '.', basename( $stack_frame['file'] ), 2 );
+				$trace[]         = $filename_pieces[0] . ':' . $stack_frame['line'];
+			} elseif ( isset( $stack_frame['class'], $stack_frame['function'] ) ) {
+				$trace[] = $stack_frame['class'] . '::' . $stack_frame['function'];
+			}
+
+			--$depth_limit;
+			if ( $depth_limit <= 0 ) {
+				break;
+			}
+		}
+		return $trace;
+	}
+
+	public function log( $message, $data, $error = null ) {
+		if ( ! Utils::is_debug() ) {
+			return;
+		}
+
+		$meta = array(
+			'name' => $this->get_name(),
+			'path' => $this->get_path(),
+		);
+
+		$trace = defined( 'SCHEMA_TRACE' ) && \SCHEMA_TRACE > 0 ? $this->trace( \SCHEMA_TRACE ) : null;
+		if ( $trace ) {
+			$meta['trace'] = $trace;
+		}
+
+		if ( $error instanceof Schema_Error ) {
+			$meta['error_message'] = $error->getMessage();
+			$meta['value']         = $error->get_value();
+		}
+
+		$this->log[] = array(
+			'message' => $message,
+			'meta'    => $meta,
+		);
+	}
+
+	public function verbose_log( $message, $data ) {
+		if ( ! Utils::is_verbose() ) {
+			return;
+		}
+		$this->log( $message, $data );
+	}
+
+	public function get_log() {
+		return $this->log;
+	}
+
+	public function get_path() {
+		$path = $this->name;
+		if ( ! empty( $this->path ) ) {
+			$path .= '.' . implode( '.', $this->path );
+		}
+		return $path;
+	}
+
+	public function remove_path( $key ) {
+		$index = array_search( $key, $this->path, true );
+		if ( $index !== false ) {
+			unset( $this->path[ $index ] );
+		}
+		// Reindex the array.
+		$this->path = array_values( $this->path );
+	}
+
+	public function get_name() {
+		return $this->name;
+	}
+
+	public function set_data( $data ) {
+		if ( ! isset( $this->data ) ) {
+			$this->data = $data;
+		}
+	}
+
+	public function get_data() {
+		return $this->data;
+	}
+}

projects/packages/schema/src/class-schema-error.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Automattic\Jetpack\Schema;
+
+class Schema_Error extends \RuntimeException {
+	private $value;
+	private $context;
+
+	public function __construct( $message, $value, $context = null ) {
+		$this->value   = $value;
+		$this->context = $context;
+		parent::__construct( $message );
+	}
+
+	public function get_value() {
+		return $this->value;
+	}
+
+	public function get_context() {
+		return $this->context;
+	}
+}