diff --git a/docs/api_rule_contract.md b/docs/api_rule_contract.md new file mode 100644 index 000000000..51a1aceba --- /dev/null +++ b/docs/api_rule_contract.md @@ -0,0 +1,188 @@ +# The `api` rule's contract + +> Filed as [#2730](https://github.com/squid-protocol/gitgalaxy/issues/2730). This document is the +> stated contract the issue asked for, plus the audit of all 46 corpus languages against it. +> `gitgalaxy/standards/how_to_add_a_language.md` carries the one-line form next to the rule in the +> output schema; this file carries the reasoning, the fallback family, and the per-language verdicts. + +## The contract + +> **`api` matches a declaration that makes a named function or type visible outside the file it is +> declared in.** + +Three corollaries, each of which the audit below found a language violating: + +1. **A reference is not a declaration.** A call site, an import, a struct-literal field key, a + `switch` case on the keyword, a package segment that happens to be spelled `internal` — none of + these publish a name, they consume one. (`cobol` counted `CALL`; `go` counted `Protocol: + protocol,`; `kotlin` counted `import okhttp3.internal.X`; `powershell` counted `return (`.) +2. **A modifier counts where it modifies a declaration, not wherever it appears.** `\bpublic\b` + against a raw code stream is not a measurement of public surface; it is a measurement of how + often the word occurs, string literals included. The modifier must be anchored to the + declaration it applies to. (`java`, `csharp`, `kotlin`, `php`, `groovy`, `swift`, `typescript`.) +3. **Where the language makes things public by default, the declaration itself IS the marker.** + `python` has always read `def ` this way, and `lua`, `scala`, `livecode`, `fortran` and + `powershell` follow it. A language whose functions are public unless marked otherwise must count + the declaration, or it measures 0 forever. (`abap` `FORM`, `perl` `sub`, `matlab` `function`, + `dart`'s top-level function, `ada`'s library-level subprogram.) + +### The documented fallback family + +Some languages have no per-function visibility concept at all. For those, `api` counts the +**file-level declaration that exposes the file's surface**, and that substitution is deliberate, +not a defect: + +| language | stands in for a public function declaration | +|---|---| +| `dockerfile` | `EXPOSE ` | +| `yaml` | a workflow `on:` trigger block | +| `css` | `:root`, `@property`, a `--custom-property:` definition | +| `html` | `id=`/`name=`/`itemprop=`/``/`og:`/`twitter:` — the document's addressable surface | +| `yacc` | `%define`/`%code`/`%provides`/`%requires` | +| `m4` | `AC_SUBST`/`AC_DEFINE`/`AC_PROVIDE`/`m4_provide` | +| `cobol` | `ENTRY`, `LINKAGE SECTION` | +| `agc_assembly` | `