@terpjs/spec 0.14.0

package/corpus/backend/session_imported_from_sqlmodel/compliant-01/modules/notes/service.py

@@ -0,0 +1,5 @@
+from sqlmodel import Session
+
+
+def note_count(session: Session) -> int:
+    return len(session.exec(query).all())

package/corpus/backend/session_imported_from_sqlmodel/violation-01/modules/notes/service.py

@@ -0,0 +1,5 @@
+from sqlalchemy.orm import Session
+
+
+def note_count(session: Session) -> int:
+    return len(session.exec(query).all())

package/corpus/backend/table_models_use_base_table/compliant-01/modules/notes/models.py

@@ -0,0 +1,6 @@
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class Note(BaseTable, table=True):
+    title: str = Field(max_length=200)

package/corpus/backend/table_models_use_base_table/violation-01/modules/notes/models.py

@@ -0,0 +1,5 @@
+from sqlmodel import Field, SQLModel
+
+
+class Note(SQLModel, table=True):
+    title: str = Field(max_length=200)

package/corpus/backend/tables_have_migrations/compliant-01/modules/notes/migrations/versions/0a1b2c3d4e5f_create_notes_tables.py

@@ -0,0 +1,22 @@
+"""create notes tables
+
+Revision ID: 0a1b2c3d4e5f
+Revises:
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0a1b2c3d4e5f"
+down_revision = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "note",
+        sa.Column("id", sa.Uuid(), primary_key=True),
+        sa.Column("title", sa.String(length=200), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("note")

package/corpus/backend/tables_have_migrations/compliant-01/modules/notes/models.py

@@ -0,0 +1,6 @@
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class Note(BaseTable, table=True):
+    title: str = Field(max_length=200)

package/corpus/backend/tables_have_migrations/compliant-02/capabilities/ledger/models.py

@@ -0,0 +1,6 @@
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class LedgerEntry(BaseTable, table=True):
+    amount_cents: int = Field(default=0)

package/corpus/backend/tables_have_migrations/violation-01/expected-findings.json

@@ -0,0 +1,7 @@
+[
+  {
+    "rule": "backend/tables_have_migrations",
+    "path": "modules/notes/models.py",
+    "line": 5
+  }
+]

package/corpus/backend/tables_have_migrations/violation-01/modules/notes/models.py

@@ -0,0 +1,6 @@
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class Note(BaseTable, table=True):
+    title: str = Field(max_length=200)

package/corpus/backend/tables_have_migrations/violation-02/expected-findings.json

@@ -0,0 +1,7 @@
+[
+  {
+    "rule": "backend/tables_have_migrations",
+    "path": "modules/notes/models.py",
+    "line": 5
+  }
+]

package/corpus/backend/tables_have_migrations/violation-02/modules/notes/models.py

@@ -0,0 +1,10 @@
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class NoteTag(BaseTable, table=True):
+    label: str = Field(max_length=40)
+
+
+class Note(BaseTable, table=True):
+    title: str = Field(max_length=200)

package/corpus/backend/tenant_scoped_models_use_scoped_service/compliant-01/modules/projects/models.py

@@ -0,0 +1,6 @@
+from sqlmodel import Field
+from terp.core import BaseTable, TenantScopedMixin
+
+
+class Project(BaseTable, TenantScopedMixin, table=True):
+    name: str = Field(max_length=200)

package/corpus/backend/tenant_scoped_models_use_scoped_service/compliant-01/modules/projects/service.py

@@ -0,0 +1,5 @@
+from terp.core import TenantScopedService
+
+
+class ProjectService(TenantScopedService):
+    model = Project

package/corpus/backend/tenant_scoped_models_use_scoped_service/compliant-02/modules/projects/models.py

@@ -0,0 +1,8 @@
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class Attachment(BaseTable, table=True):
+    """Not tenant-scoped (no TenantScopedMixin) — a plain BaseService is fine."""
+
+    name: str = Field(max_length=200)

package/corpus/backend/tenant_scoped_models_use_scoped_service/compliant-02/modules/projects/service.py

@@ -0,0 +1,5 @@
+from terp.core import BaseService
+
+
+class AttachmentService(BaseService):
+    model = Attachment

package/corpus/backend/tenant_scoped_models_use_scoped_service/violation-01/modules/projects/models.py

@@ -0,0 +1,6 @@
+from sqlmodel import Field
+from terp.core import BaseTable, TenantScopedMixin
+
+
+class Project(BaseTable, TenantScopedMixin, table=True):
+    name: str = Field(max_length=200)

package/corpus/backend/tenant_scoped_models_use_scoped_service/violation-01/modules/projects/service.py

@@ -0,0 +1,5 @@
+from terp.core import BaseService
+
+
+class ProjectService(BaseService):
+    model = Project

package/corpus/backend/ungoverned_escape_hatch/compliant-01/modules/notes/service.py

@@ -0,0 +1,5 @@
+from terp.core import BaseService
+
+
+class NoteService(BaseService):
+    model = Note

package/corpus/backend/ungoverned_escape_hatch/compliant-02/modules/notes/service.py

@@ -0,0 +1,4 @@
+def render_help():
+    # Marker-shaped text inside a string is not an opt-out marker: it is neither
+    # honoured nor counted, so this file carries no ungoverned marker.
+    return "suppress with '# arch-allow-no-dynamic-sql: <reason>' after review"

package/corpus/backend/ungoverned_escape_hatch/violation-01/modules/notes/service.py

@@ -0,0 +1,2 @@
+def legacy_report(session, sql):
+    return session.execute(text(sql))  # arch-allow-no-dynamic-sql: legacy reporting query, parameterised upstream

package/corpus/backend/update_schemas_inherit_base_update_schema/compliant-01/modules/notes/schemas.py

@@ -0,0 +1,2 @@
+class NoteUpdate(BaseUpdateSchema):
+    title: str

package/corpus/backend/update_schemas_inherit_base_update_schema/violation-01/modules/notes/schemas.py

@@ -0,0 +1,2 @@
+class NoteUpdate(BaseSchema):
+    title: str

package/corpus/backend/update_schemas_inherit_base_update_schema/violation-02/modules/notes/schemas.py

@@ -0,0 +1,5 @@
+class NotePatch(BaseSchema):
+    title: str
+
+
+router = build_crud_router(update_schema=NotePatch)

package/corpus/frontend/escape-hatch/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+export function Widget() {
+  // terp-allow-token-styled-elements: native button needed for a browser extension host
+  return <button>save</button>;
+}

package/corpus/frontend/escape-hatch/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+// terp-allow-token-styled-elements
+export function Widget() {
+  return <button>save</button>;
+}

package/corpus/frontend/escape-hatch/violation-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,7 @@
+export function Widget() {
+  // A marker that names no rule with a governed opt-out (a typo, a stale name,
+  // or the governance rule's own name) is itself a violation - it can never be
+  // budgeted into legitimacy.
+  // terp-allow-made-up-rule: stale name
+  return null;
+}

package/corpus/frontend/escape-hatch/violation-03/src/modules/widgets/Widget.tsx

@@ -0,0 +1,7 @@
+export function Widget() {
+  // A marker spelled with a RETIRED tool-internal rule id (the pre-0.6.0
+  // core-id spelling) names no catalog rule, so it waives nothing: the
+  // violation underneath still fires and the stale marker is itself reported.
+  // terp-allow-no-restricted-syntax: pre-0.6.0 spelling (migrate to the catalog rule name)
+  return <button>x</button>;
+}

package/corpus/frontend/generated-client-only/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,6 @@
+import { useTerpClient } from "@terp/react-core";
+export function Widget() {
+  const client = useTerpClient();
+  void client;
+  return null;
+}

package/corpus/frontend/generated-client-only/compliant-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,21 @@
+import { useTerpClient } from "@terp/react-core";
+
+const repository = {
+  fetch(id: string): string {
+    return id;
+  },
+  sendBeacon(payload: string): number {
+    return payload.length;
+  },
+};
+
+export function Widget() {
+  const client = useTerpClient();
+  void client;
+  // fetch("/api/notes") would be refused; the typed client is the one egress path.
+  const doc = "WebSocket / XMLHttpRequest / EventSource / fetch are refused in app modules";
+  void doc;
+  void repository.fetch("1");
+  void repository.sendBeacon("x");
+  return null;
+}

package/corpus/frontend/generated-client-only/compliant-03/src/modules/widgets/Widget.tsx

@@ -0,0 +1,7 @@
+export function Widget() {
+  // One catalog rule, one marker: it covers every detection path of the egress
+  // family (bare and window-qualified alike).
+  // terp-allow-generated-client-only: sanctioned probe for a health widget
+  void window.fetch("/healthz");
+  return null;
+}

package/corpus/frontend/generated-client-only/compliant-04/src/modules/widgets/Widget.tsx

@@ -0,0 +1,17 @@
+import { useRealtimeChannel } from "@terp/react-core";
+
+type Notice = { sequence: number; text: string };
+
+function isNotice(value: unknown): value is Notice {
+  if (typeof value !== "object" || value === null) return false;
+  const item = value as Record<string, unknown>;
+  return typeof item.sequence === "number" && typeof item.text === "string";
+}
+
+export function Widget() {
+  const notices = useRealtimeChannel({
+    channel: "system.notices",
+    validate: isNotice,
+  });
+  return <p>{notices.lastMessage?.text ?? "Waiting"}</p>;
+}

package/corpus/frontend/generated-client-only/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export async function load() {
+  return fetch("/api/notes");
+}

package/corpus/frontend/generated-client-only/violation-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,9 @@
+export async function load(path: string) {
+  return globalThis.fetch(path);
+}
+
+export async function loadComputed(path: string) {
+  return window["fetch"](path);
+}
+
+export const transport = fetch;

package/corpus/frontend/generated-client-only/violation-03/src/modules/widgets/Widget.tsx

@@ -0,0 +1,14 @@
+export function connect(url: string) {
+  return new WebSocket(
+    url,
+    ["v1"],
+  );
+}
+
+export function subscribe(url: string) {
+  return new window.EventSource(url);
+}
+
+export function flush(url: string, data: string) {
+  navigator.sendBeacon(url, data);
+}

package/corpus/frontend/generated-client-only/violation-04/src/modules/widgets/Widget.tsx

@@ -0,0 +1,6 @@
+export function transportFactory() {
+  const Ctor = XMLHttpRequest;
+  return Ctor;
+}
+
+export const events = EventSource;

package/corpus/frontend/layout-contract/compliant-01/layout-contract.json

@@ -0,0 +1,3 @@
+{
+  "contract": "standard"
+}

package/corpus/frontend/layout-contract/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,8 @@
+import { HubCard, HubPage } from "@terp/react-core";
+export function Widget() {
+  return (
+    <HubPage title="Notes">
+      <HubCard title="All notes" to="/notes" />
+    </HubPage>
+  );
+}

package/corpus/frontend/layout-contract/violation-01/layout-contract.json

@@ -0,0 +1,3 @@
+{
+  "contract": "standard"
+}

package/corpus/frontend/layout-contract/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,8 @@
+import { DetailList, HubPage } from "@terp/react-core";
+export function Widget() {
+  return (
+    <HubPage title="Notes">
+      <DetailList items={[]} />
+    </HubPage>
+  );
+}

package/corpus/frontend/no-cross-module-imports/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+import { Button } from "@terp/react-core";
+export function Widget() {
+  return <Button>ok</Button>;
+}

package/corpus/frontend/no-cross-module-imports/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+import { x } from "../other/thing";
+export const Widget = () => null;
+void x;

package/corpus/frontend/no-deep-imports/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+import { Button } from "@terp/react-core";
+export function Widget() {
+  return <Button>ok</Button>;
+}

package/corpus/frontend/no-deep-imports/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,2 @@
+import Button from "@terp/react-core/src/Button";
+export const Widget = () => <Button>x</Button>;

package/corpus/frontend/no-dom-html-injection/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+import { Button } from "@terp/react-core";
+export function Widget() {
+  return <Button>ok</Button>;
+}

package/corpus/frontend/no-dom-html-injection/compliant-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,11 @@
+export function show(el: HTMLElement, message: string) {
+  // el.innerHTML = message would be refused; assign text, never markup.
+  el.innerText = message;
+  el.textContent = message;
+}
+
+export function preview(box: { innerHTMLPreview: string }, markup: string) {
+  box.innerHTMLPreview = markup;
+}
+
+export const HINT = "innerHTML / outerHTML / insertAdjacentHTML are refused in app modules";

package/corpus/frontend/no-dom-html-injection/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export function write(el: HTMLElement, html: string) {
+  el.innerHTML = html;
+}

package/corpus/frontend/no-dom-html-injection/violation-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,7 @@
+export function writeHeader(header: string) {
+  document.write(header);
+}
+
+export function writeFooter(footer: string) {
+  window.document.writeln(footer);
+}

package/corpus/frontend/no-dom-html-injection/violation-03/src/modules/widgets/Widget.tsx

@@ -0,0 +1,12 @@
+export function append(el: HTMLElement | null, markup: string) {
+  el?.insertAdjacentHTML(
+    "beforeend",
+    markup,
+  );
+}
+
+export function replace(el: HTMLElement, title: string) {
+  el.outerHTML = `
+    <section>${title}</section>
+  `;
+}

package/corpus/frontend/no-eval/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+import { Button } from "@terp/react-core";
+export function Widget() {
+  return <Button>ok</Button>;
+}

package/corpus/frontend/no-eval/compliant-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,11 @@
+const interpreter = {
+  eval(expression: string): number {
+    return expression.length;
+  },
+};
+
+export function describeExpression(expression: string) {
+  // eval(expression) would be refused here; this is a member call on a local object.
+  const hint = "eval() and new Function() are refused in app modules";
+  return `${interpreter.eval(expression)} ${hint}`;
+}

package/corpus/frontend/no-eval/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export function run(code: string) {
+  return eval(code);
+}

package/corpus/frontend/no-eval/violation-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,7 @@
+export function run(code: string) {
+  return globalThis.eval(code);
+}
+
+export function runQualified(code: string) {
+  return window.eval(code);
+}

package/corpus/frontend/no-eval/violation-03/src/modules/widgets/Widget.tsx

@@ -0,0 +1,10 @@
+export function compile(body: string) {
+  return new Function(
+    "input",
+    body,
+  );
+}
+
+export function compileQualified(body: string) {
+  return new window.Function("input", body);
+}

package/corpus/frontend/no-eval/violation-04/src/modules/widgets/Widget.tsx

@@ -0,0 +1,6 @@
+export function Widget() {
+  // Markers live in real comments only: marker-shaped text inside a string
+  // neither suppresses the next line nor its own line.
+  const doc = "// terp-allow-no-eval: not a comment";
+  return eval(doc);
+}

package/corpus/frontend/no-inline-styling/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+import { Button } from "@terp/react-core";
+export function Widget() {
+  return <Button>ok</Button>;
+}

package/corpus/frontend/no-inline-styling/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export function Widget() {
+  return <div style={{ color: "red" }}>x</div>;
+}

package/corpus/frontend/no-inline-styling/violation-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,6 @@
+export function Widget() {
+  // A justified marker for a SIBLING catalog rule sharing the same core lint id
+  // never waives this one: the marker names the catalog rule, not the tool rule.
+  // terp-allow-token-styled-elements: wrong rule - must not suppress the style attribute
+  return <div style={{ color: "#ff0000" }}>save</div>;
+}

package/corpus/frontend/no-style-imports/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+import { Button } from "@terp/react-core";
+export function Widget() {
+  return <Button>ok</Button>;
+}

package/corpus/frontend/no-style-imports/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,2 @@
+import "./widget.css";
+export const Widget = () => null;

package/corpus/frontend/no-unsafe-href/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export function Widget() {
+  return <a href="https://example.com" rel="noopener">docs</a>;
+}

package/corpus/frontend/no-unsafe-href/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export function Widget() {
+  return <a href="javascript:alert(1)">go</a>;
+}

package/corpus/frontend/no-unsafe-target-blank/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export function Widget() {
+  return <a href="https://example.com" target="_blank" rel="noopener">docs</a>;
+}

package/corpus/frontend/no-unsafe-target-blank/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export function Widget() {
+  return <a href="https://example.com" target="_blank">docs</a>;
+}

package/corpus/frontend/router-links/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+import { Link } from "@terp/react-core";
+export function Widget() {
+  return <Link to="/notes">notes</Link>;
+}

package/corpus/frontend/router-links/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export function Widget() {
+  return <a href="/notes">notes</a>;
+}

package/corpus/frontend/token-styled-elements/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+import { Button } from "@terp/react-core";
+export function Widget() {
+  return <Button>ok</Button>;
+}

package/corpus/frontend/token-styled-elements/compliant-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,4 @@
+export function Widget() {
+  // terp-allow-token-styled-elements: native button needed for a browser extension host
+  return <button>save</button>;
+}

package/corpus/frontend/token-styled-elements/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,3 @@
+export function Widget() {
+  return <button>save</button>;
+}

package/findings.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terp.dev/spec/findings.schema.json",
+  "title": "Terp Standard finding",
+  "description": "The machine-readable finding a conformant checker emits: an array of these objects per checked tree. The corpus contract is stated over this shape — for a rule under test, every violation-* case yields at least one finding whose `rule` is the catalog id, and every compliant-* case yields none for that rule. Findings are attributed to the stack-neutral catalog id, never a tool-internal rule id.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["rule", "path"],
+    "additionalProperties": false,
+    "properties": {
+      "rule": {
+        "type": "string",
+        "description": "The Terp Standard catalog id the finding realises (catalog/<surface>/<rule>.json).",
+        "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
+      },
+      "path": {
+        "type": "string",
+        "description": "File path relative to the checked tree's root (the corpus case root, or the app root), with forward slashes."
+      },
+      "line": {
+        "type": "integer",
+        "description": "1-based line of the violation, when the checker can locate it.",
+        "minimum": 1
+      },
+      "message": {
+        "type": "string",
+        "description": "Human-readable explanation; ideally directive (states the compliant fix)."
+      },
+      "fix_hint": {
+        "type": "string",
+        "description": "Agent-oriented remediation metadata: the compliant construct that replaces the violating one, sourced from the catalog entry's non-normative `reference` field (or the checker's own knowledge of the sanctioned pattern). Optional — a consumer must not require it."
+      },
+      "fingerprint": {
+        "type": "string",
+        "description": "A stable, checker-chosen identifier for THIS violation instance (e.g. a hash over rule + path + violating source construct), so consumers can track a finding across line-shifting edits. Optional; the fingerprint scheme is checker-internal — only stability across reformatting is expected."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@terpjs/spec",
+  "version": "0.14.0",
+  "description": "The Terp Standard — stack-neutral rule catalog, violation corpus, finding format, and refused-surface declaration (ADRs 0080/0081; packaged per ADR 0082, published per ADR 0086). Data only: consumers resolve the spec root via require.resolve('@terpjs/spec/package.json').",
+  "files": [
+    "VERSION",
+    "findings.schema.json",
+    "app-check-report.schema.json",
+    "scorecard.schema.json",
+    "assurance-profile.schema.json",
+    "restricted-surface.json",
+    "catalog",
+    "corpus"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AITT-NL/terp-spec.git"
+  }
+}

package/restricted-surface.json

@@ -0,0 +1,10 @@
+{
+  "title": "Terp Standard - the refused raw frontend surface",
+  "description": "The normative, stack-neutral declaration of the raw browser primitives an app module must not author directly. The prohibition is the portable part of the rules that cite this file (token-styled-elements, no-inline-styling, generated-client-only, no-style-imports, no-deep-imports); which sanctioned component or helper answers each primitive is per-stack configuration, recorded non-normatively in the catalog entry's 'reference' field. A checker realises this file for its language; the reference adapter's BOUNDARY_SPEC is parity-tested against it.",
+  "restrictedElements": ["button", "dialog", "form", "input", "select", "table", "textarea"],
+  "restrictedAttributes": ["className", "style"],
+  "restrictedGlobals": ["EventSource", "WebSocket", "XMLHttpRequest", "fetch"],
+  "restrictedMemberCalls": ["navigator.sendBeacon"],
+  "styleImportExtensions": [".css", ".less", ".sass", ".scss", ".styl"],
+  "deepImportPathSegments": ["dist", "src"]
+}