tcmts.records

records

The AT Protocol records tcm's libraries are announced and talked about with, as a library of its own: add it to a codebase with tcm lib add @tcm.codes/records (tcm.codes announces it), or by hash from any tcm server that has it. It's a tcm library, not an npm package: it holds everything its code uses, so a codebase that adds it has every definition named. Something that reads or writes these records (a hub of its own, a feed, a bot) uses it to agree with tcm on what they are.

import { parseReleaseRecord, parseAttestation, starOf, RELEASE_COLLECTION } from "#codebase/app/lib/records";

const release = parseReleaseRecord(record); // a ReleaseRecord, or undefined if it isn't one
const advisory = parseAttestation("codes.tcm.advisory", record); // its kind from its collection
const star = starOf(rkey, record); // { author, package, createdAt }, if it's at its own key

What it has

Releases (codes.tcm.release, one per version, keyed <package>:<version>): releaseLexicon, ReleaseRecord, recordKey, and parseReleaseRecord, which takes a record only if every field is there and of its type, the package an npm package name, the version a semver one and the namespace a hash; sources are kept only if they're http(s) URLs.
Attestations, a collection per kind (ATTESTATION_KINDS): a review, an advisory (with one of SEVERITIES, and the version that fixes it) or a yank, each about code by its namespace's whole hash. attestationLexicons, Attestation, parseAttestation, and attestationRecord to write one.
Stars (codes.tcm.star, one per person per library, keyed by the library): starLexicon, starKey, and starOf, which takes a star only at its own key.

lexicons is all five lexicon documents (Lexicon 1, each with its record key, field types, formats and limits). tcm.codes is their authority (_lexicon.tcm.codes): they're published as its com.atproto.lexicon.schema records by tcm's maintainers (developing tcm), not by the library. starRecord makes a star as the hub writes it.

Reading a record here checks what it says, not who said it: whether a record is its author's is the AT Protocol's part (fetch it with com.atproto.sync.getRecord and check its commit against the key in their DID document).

Its versions follow semver from its API, as any package's do (releases).

test/: 4 definitions

Types

Attestation type: An attestation, as written (its `$type` is its kind's collection).
AttestationKind type
AttestationSubject type: What an attestation is about: code, by its namespace's whole hash; the release and its author, for showing.
ReleaseRecord type: A release record, as written.
Severity type

Shared

ATTESTATION_KINDS { readonly review: "codes.tcm.review"; readonly advisory: "codes.tcm.advisory"; readonly yank: "cod…: The three kinds, and the collection each is kept in.
RELEASE_COLLECTION "codes.tcm.release": The release record's collection (its lexicon's NSID).
SEVERITIES readonly ["low", "moderate", "high", "critical"]: How bad an advisory says it is.
STAR_COLLECTION "codes.tcm.star": The collection a star is kept in.
attestationLexicons Record<"advisory" | "review" | "yank", Record<string, unknown>>: The lexicons of the three: each its own document, with the subject (the code it's about) a definition in it.
attestationRecord (a: Attestation) => Record<string, unknown>: An attestation as its record.
lexicons readonly Record<string, unknown>[]: Every lexicon tcm's records follow, as documents (what `com.atproto.lexicon.schema` records publish).
manifest { name: string; npm: boolean; }: The AT Protocol records tcm's libraries are announced and talked about with: `codes.tcm.release` (a release), the attestations about code (`codes.tcm.review`, `codes.tcm.advisory`, `codes.tcm.yank`) and `codes.tcm.star` (someone likes a library): their lexicons, their record keys, and each read from what a repository holds, checked field by field.
parseAttestation (collection: string, v: unknown) => Attestation | undefined: A record as an attestation, if it is one (of the collection it's in).
parseReleaseRecord (v: unknown) => ReleaseRecord | undefined: A release record as read: what it says, if it's one (every field of the lexicon, of its type; the package an npm package name, the version a semver one, the namespace a hash), else undefined.
recordKey (r: { package: string; version: string; }) => string: A release's record key: `<package>:<version>`, with what a record key can't hold (a scope's `@` and `/`) as `~`.
releaseLexicon { readonly lexicon: 1; readonly id: "codes.tcm.release"; readonly description: "A release of a tcm …: The `codes.tcm.release` lexicon.
starKey (author: string, pkg: string) => string: A star's record key: the library it's for, so one person stars one library once.
starLexicon { readonly lexicon: 1; readonly id: "codes.tcm.star"; readonly description: "A star on a tcm librar…: A star's lexicon: someone's word that they like a library, across its versions; one per person per library.
starOf (rkey: string, v: unknown) => { author: string; package: string; createdAt: string; } | undefined: A star record's subject, if it is one (and at its own key).
starRecord (author: string, pkg: string, createdAt?: string) => Record<string, unknown>: A star record: `author`'s library `pkg` (its key is `starKey(author, pkg)`).

Files

README file