Merge feature/package-type-api-surface: package-type-aware API-surface enforcement

Author: LTSCommerce

.gitignore

@@ -7,6 +7,7 @@
 !/bin/infection
 !/bin/managed-source
 !/bin/mdlinks
+!/bin/package-type-check
 !/bin/php-cs-fixer
 !/bin/phpstan
 !/bin/phpunit-check-annotation

bin/package-type-check

@@ -0,0 +1,24 @@
+#!/usr/bin/env php
+<?php declare(strict_types=1);
+$files = [
+    __DIR__.'/../../../autoload.php',
+    __DIR__.'/../vendor/autoload.php',
+];
+
+$autoloadFileFound = false;
+foreach ($files as $file) {
+    if (file_exists($file)) {
+        require $file;
+        $autoloadFileFound = true;
+        break;
+    }
+}
+
+if (!$autoloadFileFound) {
+    echo 'You need to set up the project dependencies using the following commands:'.PHP_EOL.
+         'curl -s http://getcomposer.org/installer | php'.PHP_EOL.
+         'php composer.phar install'.PHP_EOL;
+    die(1);
+}
+
+die(\LTS\PHPQA\PackageType\ExplicitPackageTypeCheck::main());

composer.json

@@ -52,6 +52,9 @@
       "LTS\\PHPQA\\Tests\\": [
         "tests/"
       ],
+      "LTS\\PHPQA\\Tests\\Assets\\PHPStan\\ApiOrInternal\\": [
+        "tests/assets/PHPStan/ApiOrInternal/"
+      ],
       "LTS\\PHPQA\\Tests\\Assets\\PHPStan\\DeprecatedPhpunit\\": [
         "tests/assets/PHPStan/DeprecatedPhpunit/"
       ],
@@ -67,6 +70,7 @@
     "bin/composer-require-checker",
     "bin/infection",
     "bin/mdlinks",
+    "bin/package-type-check",
     "bin/php-cs-fixer",
     "bin/phpstan",
     "bin/phpunit-check-annotation",

composer.lock

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+use Arkitect\Expression\ForClasses\NotDependsOnTheseNamespaces;
+use Arkitect\Expression\ForClasses\NotResideInTheseNamespaces;
+use Arkitect\Rules\Rule;
+
+/**
+ * Reusable CONSUMER API-boundary rule factory.
+ *
+ * Returns PHPArkitect rules a *consumer* of a `type: library` package applies to
+ * its OWN `src/` to enforce that it reaches the library only through the
+ * library's public `@api` namespace — never its `@internal` ones. This is the
+ * hard, shipped counterpart to the per-class `@api`/`@internal` classification
+ * (see docs/tools/requireApiOrInternal.md): the library declares its surface,
+ * the consumer's CI forbids crossing it.
+ *
+ * Loaded the same way as the shipped rule tiers — via an env var the pipeline
+ * exports — from a consumer's `qaConfig/phparkitect.php`:
+ *
+ *     $consumerMustOnlyDependOn = require getenv('PHPQACI_ARKITECT_CONSUMER_API_BOUNDARY');
+ *     $config->add(
+ *         ClassSet::fromDir(__DIR__ . '/../src'),
+ *         ...$consumerMustOnlyDependOn(
+ *             'Ballicom\AccountsIq\Facade',          // the library's public @api namespace
+ *             'Ballicom\AccountsIq\Gateway',         // its @internal namespaces …
+ *             'Ballicom\AccountsIq\Api',
+ *         ),
+ *     );
+ *
+ * The rule applies to every class that is NOT itself part of the library's
+ * namespaces (i.e. the consumer's own code) and forbids it from depending on any
+ * listed internal namespace. The public namespace stays allowed.
+ *
+ * @return callable(string, string...): list<Rule>
+ */
+return static function (string $publicNamespace, string ...$internalNamespaces): array {
+    if ([] === $internalNamespaces) {
+        throw new InvalidArgumentException(
+            'consumerMustOnlyDependOn() requires at least one internal namespace to forbid '
+            . '(the library namespaces consumers must not reach into).',
+        );
+    }
+
+    return [
+        Rule::allClasses()
+            ->that(new NotResideInTheseNamespaces($publicNamespace, ...$internalNamespaces))
+            ->should(new NotDependsOnTheseNamespaces($internalNamespaces))
+            ->because(\sprintf(
+                'consumers must reach this library only through its public @api namespace %s; '
+                . '%s are @internal and may change without notice',
+                $publicNamespace,
+                implode(', ', $internalNamespaces),
+            )),
+    ];
+};

configDefaults/generic/phparkitect-consumer-api-boundary.php

@@ -0,0 +1,75 @@
+# Package Type Declaration Check
+
+An **always-on** php-qa-ci pipeline tool that fails the build unless the
+project's `composer.json` declares its `type` **explicitly**.
+
+Composer silently defaults an omitted `type` to `library`. That default quietly
+makes a real architectural decision — *is this an installable dependency or an
+application?* — without anyone choosing it. This check rejects the silent default
+so the decision is **conscious**: the file must say `library`, `project`, or any
+other explicit Composer type.
+
+## Why it matters
+
+The declared type drives php-qa-ci's API-surface discipline:
+
+- **`type: library`** — an installable dependency. Its public surface is a
+  consumer contract, so the
+  [`RequireApiOrInternalTagRule`](requireApiOrInternal.md) PHPStan rule then
+  requires every public class-like to be classified `@api` / `@internal`.
+- **`type: project`** — an application. No consumers, so the classification rule
+  no-ops.
+- **other explicit types** (`metapackage`, `composer-plugin`, …) — accepted as a
+  conscious declaration; treated as non-library for classification.
+
+If the type were left to Composer's default, a library could ship an
+unclassified, accidental public surface. Forcing the declaration is the forcing
+function that makes the rest of the discipline reliable.
+
+## How it runs
+
+- **Part of the full pipeline**: runs automatically in the **linting phase** of a
+  plain `bin/qa`, right after the Composer checks.
+- **Standalone**: `vendor/bin/qa -t packageType` (aliases: `-t pt`, `-t packagetype`).
+- **Binary**: `bin/package-type-check` (delegates to
+  `LTS\PHPQA\PackageType\ExplicitPackageTypeCheck::main()`).
+
+The tool reads `{projectRoot}/composer.json` and:
+
+- **passes (exit 0)** when `type` is a non-blank string; or
+- **fails (exit 1)** when `type` is absent, blank, or not a string — printing the
+  guidance to declare it.
+
+## No opt-out
+
+Unlike most baseline checks this one has **no escape hatch**: declaring one
+`composer.json` line is trivial, and the app-vs-library decision must always be
+made. Every consumer's `composer.json` must carry an explicit `type`.
+
+## How to fix a failure
+
+Add an explicit `type` to `composer.json`:
+
+```json
+{
+    "name": "acme/widget",
+    "type": "library"
+}
+```
+
+Choose:
+
+- **`library`** if this package is installed as a dependency by other projects
+  (then classify its public surface — see
+  [requireApiOrInternal.md](requireApiOrInternal.md)).
+- **`project`** if this is a deployable application with no consumers.
+
+## Design / implementation notes
+
+- Pure decision core:
+  [`ExplicitPackageTypeDetector`](./../../src/PackageType/ExplicitPackageTypeDetector.php)
+  — `check(decoded composer.json): ?string` (null = OK, else the guidance
+  message); exhaustively unit-tested.
+- Thin I/O runner:
+  [`ExplicitPackageTypeCheck`](./../../src/PackageType/ExplicitPackageTypeCheck.php)
+  — maps the verdict to stdout + exit code.

docs/tools/packageType.md

@@ -53,6 +53,7 @@ PHP-QA-CI ships custom PHPStan rules that are auto-loaded via the extension inst
 - **ForbidEmptyCatchBlockRule** -- Requires catch blocks to have a body
 - **RequireDeclareStrictTypesRule** -- Requires `declare(strict_types=1)` in all PHP files
 - **RequireSensitiveParameterAttributeRule** -- Requires `#[\SensitiveParameter]` on plaintext credential parameters (configurable name patterns / ignore substrings via the `phpqaciSensitiveParameter` parameters block)
+- **RequireApiOrInternalTagRule** -- Package-type-aware: for a `type: library` project, every public class-like must be classified as exactly one of `@api` / `@internal`; no-ops for other package types. Generated/managed namespaces are exempt via the `phpqaciApiOrInternal.ignoredNamespacePrefixes` parameter. Full guidance (incl. the deliberate `@api`-vs-`@internal` judgement): [tools/requireApiOrInternal.md](requireApiOrInternal.md)
 
 See the README "Configuring RequireSensitiveParameterAttributeRule" section for the full config keys and defaults.
 

docs/tools/phpstan.md

@@ -0,0 +1,132 @@
+# RequireApiOrInternalTagRule — package-type-aware API-surface classification
+
+A **default-on** PHPStan rule (`phpqaci.requireApiOrInternalTag`) that makes a
+library declare its public contract explicitly: when the consuming project's
+Composer `type` is **`library`**, every public class-like must be classified as
+exactly one of `@api` or `@internal`.
+
+It ships in [`rules-default.neon`](./../../rules-default.neon), so it runs for any
+project that includes php-qa-ci's default rule set — no opt-in.
+
+## What it enforces
+
+For a `type: library` package (an installable dependency — **and Composer's silent
+default when `type` is omitted**), each public class-like (`class`, `interface`,
+`enum`, `trait`) must carry exactly one classifying tag in its docblock:
+
+| Docblock                        | Verdict     | Result                          |
+| ------------------------------- | ----------- | ------------------------------- |
+| `@api` only                     | classified  | ✅ pass                         |
+| `@internal` only                | classified  | ✅ pass                         |
+| neither `@api` nor `@internal`  | **Missing** | ❌ "classify it"                |
+| **both** `@api` and `@internal` | **Both**    | ❌ "contradiction — choose one" |
+
+For any other package type (`project` application, `metapackage`,
+`composer-plugin`, …) there is no consumer-facing surface, so the rule **no-ops**.
+
+Anonymous classes are skipped (no name to classify, no public contract).
+
+> **Why per-class classification?** `@internal` is the ecosystem-standard,
+> tool-enforced marker (PHPStan/Psalm/PhpStorm all treat a root-namespace
+> `@internal` symbol as off-limits to consumers), but **no tool infers the
+> inverse** — "this isn't `@api`, therefore it's internal". So the only
+> enforceable model is to require an explicit, per-class choice. The rule forces
+> the choice to be *made*; making it *correctly* is the author's job (below).
+
+## The `@api` vs `@internal` judgement (read this before tagging)
+
+This rule is a **quality ratchet**: it does not decide for you, it makes you
+decide deliberately. The choice is genuinely two-sided:
+
+- **`@internal`** — not part of the supported contract; the library may change or
+  remove it in any release. Marking something `@internal` that consumers
+  legitimately need **over-restricts** them (or pushes them to depend on internals
+  anyway).
+- **`@api`** — a supported public contract. Changing its signature/behaviour later
+  is a **breaking change** for every consumer. Marking something `@api`
+  prematurely **commits the library** to maintaining it.
+
+**Safe default: tag `@internal`.** Promote a class to `@api` only when consumers
+genuinely need it *and* the library is willing to support it long-term. A small,
+deliberate `@api` surface (often a single facade) is the goal; everything behind
+it stays `@internal` and free to evolve.
+
+## Exempting generated / managed code
+
+Generated and managed trees cannot carry hand-authored tags. Exempt them by
+fully-qualified namespace **prefix** in your `qaConfig/phpstan.neon`:
+
+```neon
+parameters:
+    phpqaciApiOrInternal:
+        ignoredNamespacePrefixes:
+            - App\Generated
+            - App\PhpQaCi
+```
+
+The default is an empty list (nothing exempt).
+
+## How to fix a violation
+
+- **Missing** — add one tag to the class docblock. Default to `@internal`:
+
+  ```php
+  /**
+   * @internal
+   */
+  final class OrderMapper { /* … */ }
+  ```
+
+  Promote to `@api` only for the deliberate public surface.
+
+- **Both** — remove the wrong one. A class is either supported (`@api`) or not
+  (`@internal`), never both.
+
+## Relationship to the explicit-`type` requirement
+
+This rule treats an **undeclared** `type` as `library` (the safe side — keep the
+surface discipline on). Separately, the always-on
+[Package Type Declaration Check](packageType.md) **hard-fails** a `composer.json`
+that does not declare `type` explicitly, so the app-vs-library decision is
+conscious rather than inherited from Composer's silent default. A package that is
+really an application sets `type: project` (and this rule then no-ops); a real
+library sets `type: library` and classifies its surface.
+
+## Enforcing the boundary in consumers
+
+Classifying the surface declares the contract; it does not stop a *consumer* from
+reaching into `@internal` code anyway. php-qa-ci ships a reusable PHPArkitect
+**consumer API-boundary factory** for that hard half — a consumer applies it to
+its own `src/` to forbid depending on a library's internal namespaces (only the
+public `@api` namespace is allowed).
+
+It is loaded the same way as the shipped rule tiers — via an env var the pipeline
+exports (`PHPQACI_ARKITECT_CONSUMER_API_BOUNDARY`) — from the consumer's
+`qaConfig/phparkitect.php`:
+
+```php
+$consumerMustOnlyDependOn = require getenv('PHPQACI_ARKITECT_CONSUMER_API_BOUNDARY');
+
+$config->add(
+    ClassSet::fromDir(__DIR__ . '/../src'),
+    ...$consumerMustOnlyDependOn(
+        'Ballicom\AccountsIq\Facade',   // the library's public @api namespace
+        'Ballicom\AccountsIq\Gateway',  // its @internal namespaces, off-limits …
+        'Ballicom\AccountsIq\Api',
+    ),
+);
+```
+
+Any consumer class that depends on a listed internal namespace then fails
+`bin/qa -t arch`, naming the offending class. The factory lives at
+[`configDefaults/generic/phparkitect-consumer-api-boundary.php`](./../../configDefaults/generic/phparkitect-consumer-api-boundary.php).
+
+## Design / implementation notes
+
+- Pure decision core: [`ApiOrInternalTagDetector`](./../../src/PHPStan/Rules/ApiOrInternalTagDetector.php)
+  (+ `ApiOrInternalTagVerdict`) — unit-tested exhaustively, no PHPStan Scope needed.
+- Rule: [`RequireApiOrInternalTagRule`](./../../src/PHPStan/Rules/RequireApiOrInternalTagRule.php)
+  (hooks `InClassNode`; reads the class docblock for a standalone `@api`/`@internal`
+  tag).
+- Package kind: [`ProjectComposerTypeReader`](./../../src/PackageType/ProjectComposerTypeReader.php)
+  — injectable seam over the project `composer.json` (mockable in tests).

docs/tools/requireApiOrInternal.md

@@ -14,6 +14,14 @@ Checking for Composer Issues
 
 runToolGuarded composerChecks
 
+echo "
+
+Checking Package Type Is Declared
+---------------------------------
+"
+
+runTool packageType
+
 echo "
 Setting Strict Types If It's Missing
 -------------------------------------

includes/generic/allLintingTools.inc.bash

@@ -0,0 +1,28 @@
+###############################################################################
+# packageType — always-on check: composer.json MUST declare `type` explicitly.
+#
+# Composer silently defaults an omitted `type` to `library`, quietly deciding
+# app-vs-library for you. This check rejects the silent default so the decision
+# is conscious: the file must say `library` (an installable dependency — whose
+# public surface is then @api/@internal-classified by RequireApiOrInternalTagRule)
+# or `project` (an application), or any other explicit Composer type.
+#
+# Default-on, no opt-out: declaring one composer.json line is trivial and the
+# app-vs-library decision must always be made.
+#
+# Runs in the linting phase, right after composerChecks. The PHP entrypoint is
+# bin/package-type-check (delegates to
+# LTS\PHPQA\PackageType\ExplicitPackageTypeCheck::main()).
+###############################################################################
+
+packageTypeExitCode=99
+while ((packageTypeExitCode > 0)); do
+  # Run inside an `if` so a non-zero exit is captured without aborting under the
+  # pipeline's `set -e` — the failure is handled explicitly by the abort branch.
+  if phpNoXdebug -f "$binDir"/package-type-check; then
+    packageTypeExitCode=0
+  else
+    packageTypeExitCode=$?
+    tryAgainOrAbort "Package Type Declaration Check"
+  fi
+done