{ "reviewed": "2026-09-12", "organization": "mathematic-inc", "repositories": [ { "name": "ts-japi", "sha": "32bb6dafbae83942c964347c13151fcf2a46431e", "language": "TypeScript", "description": "Zero-dependency TypeScript library for serializing data to the JSON:API specification with full type safety, relationships, links, and pagination", "license": "Apache-2.0" }, { "name": "vscode-latex", "sha": "b9e17e6532c97bd384f7ce4ac56dd31406ec146b", "language": "TypeScript", "description": "VS Code extension providing LaTeX syntax highlighting, formatting via latexindent, linting via ChkTeX, and snippets for developer-focused LaTeX editing", "license": "Apache-2.0" }, { "name": "vscode-pdf", "sha": "1153346694f457bc7b4c73c9b0e95b629f02dc03", "language": "JavaScript", "description": "Lightweight, up-to-date PDF viewer extension for VS Code powered by the latest pdf.js with no memory leaks or debouncing issues", "license": "Apache-2.0" }, { "name": "vscode-api-linter", "sha": "894c5eb96337fec3f1e2186e083451910696e80d", "language": "Pkl", "description": "VS Code extension that lints Protobuf API files using Google's API Linter (api-linter) with full configuration support", "license": "Apache-2.0" }, { "name": "addr-spec-rs", "sha": "5555b28ba5407c68654dbadcb442411ec55255cc", "language": "Rust", "description": "A wicked fast UTF-8 email address parser and serializer conforming to RFC 5322 and RFC 6532", "license": "Apache-2.0" }, { "name": "unfmt", "sha": "4e951d6c118b0d4e437c27e81ecd07e892ce1a31", "language": "Rust", "description": "Compile-time string pattern matching that reverses format! interpolation — a lightweight regex alternative with no runtime compilation cost", "license": "Apache-2.0" }, { "name": "if-changed", "sha": "09319355c2ffc2684c38313f01f7a1b6983aada0", "language": "Rust", "description": "CLI tool that enforces synchronized changes across files using if-changed/then-change comment annotations in diffs", "license": "Apache-2.0" }, { "name": "claude-tools-mcp", "sha": "6f7937964f46739fd61b582625b0da509353d21f", "language": "Go", "description": "MCP server that exposes Claude Code's file and shell tools (bash, read, write, edit, glob, grep) over HTTP for remote use by any MCP client", "license": "Apache-2.0" }, { "name": "mcpr", "sha": "af29f67f340412b28a9c53bd611422e80575517f", "language": "Go", "description": "CLI tool to manage and sync Model Context Protocol server configs across AI editors — Claude Desktop, Cursor, VS Code, Windsurf, Zed, and more", "license": "Apache-2.0" }, { "name": "noop", "sha": "d36254281d8e9c128db53678c47f76de5c7d7ad9", "language": "Pkl", "description": "A no-operation placeholder repository", "license": null }, { "name": "earl", "sha": "fc9204117745c4c3510012400e7b22b5a3355b8f", "language": "Rust", "description": "Secure CLI proxy for AI agents — HCL-defined operation templates with OS keychain secrets, MCP integration, and prompt injection protection", "license": "Apache-2.0" }, { "name": "alyt", "sha": "b0499500c30d801c697d22101acb2e6943dd8cd8", "language": "TypeScript", "description": "All-in-one analytics SDK for TypeScript — unified API for GA, PostHog, Mixpanel, Amplitude, Plausible, and Vercel Analytics with YAML codegen and React bindings", "license": "Apache-2.0" }, { "name": "smapped-traces", "sha": "b811c4ad0195c66fec31e0851fed78881366e955", "language": "TypeScript", "description": "Source map resolution for OpenTelemetry — automatically resolves minified stack traces back to original source locations using debug IDs", "license": "Apache-2.0" }, { "name": "sqlc-gen-sqlx", "sha": "a1c7e5e844467eeb793fd67934526e3916e391aa", "language": "Rust", "description": null, "license": null }, { "name": "protovalidate-buffa", "sha": "490ac4201b8226c4412c4fec30ad971e86a78121", "language": "Rust", "description": "Static-codegen protovalidate for the buffa Rust protobuf runtime", "license": "Apache-2.0" }, { "name": "connectrpc-tauri", "sha": "e742f770abe89707e7add73257673ccf495a8434", "language": "Rust", "description": "Connect RPC transport over Tauri IPC", "license": "Apache-2.0" }, { "name": "connectrpc-sdk", "sha": "ba0ad915eb6e6697b98cb41bfc926008c5828494", "language": "TypeScript", "description": "Generates idiomatic, namespaced client SDKs from ConnectRPC schemas, for TypeScript and Rust", "license": "Apache-2.0" }, { "name": "tauri-plugin-ui-inspector", "sha": "73a5457c3b0dfd7ba6d7e50a23f0558c8ceea308", "language": "Rust", "description": "Inspect, capture, and reference Tauri UI elements for coding agents", "license": "Apache-2.0" }, { "name": "bucket-cache-action", "sha": "714dccf2713411d847f1919303d78bbd5c342f32", "language": "TypeScript", "description": "S3 and GCS caching for GitHub Actions with configurable post-job saves and renewable workload identity credentials", "license": "MIT" }, { "name": "site", "sha": "main", "language": "HTML", "description": "Mathematic Inc. research notes and repository catalog", "license": "Apache-2.0" } ], "projects": [ { "slug": "earl", "order": 1, "category": "agents", "title": "A defined boundary between agents and services", "summary": "Give an agent named operations while keeping request templates and credentials under operator control.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "Rust", "CLI", "MCP" ], "abstract": "An agent that can assemble arbitrary authenticated requests can also assemble requests its operator never intended. Earl separates the operation definition from the arguments an agent supplies. Versioned HCL templates describe the request; Earl resolves secrets when it executes that request. The useful boundary is the set of permitted operations and parameters. [1]", "problem": [ "Consider an agent that needs to search issues in one repository. Giving it a general HTTP tool and a token requires another layer to constrain the destination, method, and credential use. Instructions alone do not impose those constraints on the executable request. Earl's documented motivation is to move that definition into reviewed templates. [1][2]", "The template author decides which values the agent may supply. A fixed search endpoint with a query argument is a narrower capability than a parameter that accepts an arbitrary URL. That difference determines the authority of the tool; hiding a template from an MCP description does not, by itself, establish an operating-system access boundary. [2]" ], "design": [ "Earl loads an HCL operation, validates its parameters, resolves secret references from the OS credential store, renders the request, and executes it. Output rendering has no secrets namespace, and the redactor checks returned output for several representations of the secrets used by the call. HTTP, GraphQL, gRPC, Bash, and SQL operations share the template model. [1][2]", "Operators can constrain network destinations, use bound SQL parameters, and configure Bash limits. The HTTP deployment adds a policy engine for caller-specific access. These controls need deliberate configuration: an argument interpolated into SQL text is different from a bound SQL parameter, and write confirmation can be bypassed by the caller's explicit yes option. [2][3]" ], "comparisons": [ { "alternative": "curl and an agent shell", "constraint": "curl deliberately accepts caller-selected URLs, headers, and methods. If the agent constructs the complete command, the command surface alone does not express a repository-specific operation policy. [4]", "response": "Earl supplies the request structure from an operator-owned template and exposes only its declared arguments. Secret lookup stays in the execution layer. [1]", "tradeoff": "curl is the simpler fit for a trusted human making an ad hoc request. Earl adds template authorship and policy maintenance." }, { "alternative": "A custom MCP server", "constraint": "MCP standardizes how clients discover and call tools; the server still has to implement its authorization and secret handling. An unrestricted tool remains unrestricted when exposed through MCP. [5]", "response": "Earl provides reusable template, credential, and policy machinery, reducing how much of that behavior a team has to implement for each integration. [2][3]", "tradeoff": "A bespoke server remains useful for complex stateful workflows or domain logic that a template cannot express clearly." } ], "boundaries": [ "Earl does not make an agent immune to prompt injection. Untrusted responses can still influence the agent's next call. Templates with broad parameters, write access to template files, or access to other unrestricted tools can defeat the intended boundary. Apply host permissions and review template changes as executable policy. [2]", "Use it when the operation set is stable enough to review and constrain. Evaluate the actual protocols, credential backends, and policies you deploy; this note does not claim a universal security guarantee or an independent security audit." ], "related": [ "claude-tools-mcp", "mcpr" ], "sources": [ { "label": "Earl: purpose, template execution, and quick start", "path": "README.md", "url": "https://github.com/mathematic-inc/earl/blob/fc9204117745c4c3510012400e7b22b5a3355b8f/README.md" }, { "label": "Earl: security architecture and trust assumptions", "path": "site/content/docs/how-earl-works.mdx", "url": "https://github.com/mathematic-inc/earl/blob/fc9204117745c4c3510012400e7b22b5a3355b8f/site/content/docs/how-earl-works.mdx" }, { "label": "Earl: hardening and parameter handling", "path": "site/content/docs/hardening.mdx", "url": "https://github.com/mathematic-inc/earl/blob/fc9204117745c4c3510012400e7b22b5a3355b8f/site/content/docs/hardening.mdx" }, { "label": "curl: command-line request options", "url": "https://curl.se/docs/manpage.html" }, { "label": "MCP: transport and server responsibilities", "url": "https://modelcontextprotocol.io/specification/2025-06-18/basic/transports" } ], "repository": { "name": "earl", "sha": "fc9204117745c4c3510012400e7b22b5a3355b8f", "language": "Rust", "description": "Secure CLI proxy for AI agents — HCL-defined operation templates with OS keychain secrets, MCP integration, and prompt injection protection", "license": "Apache-2.0" }, "categoryInfo": { "id": "agents", "label": "Agents & interfaces", "short": "Agents", "description": "Control the operations an agent can perform and the context it can inspect." } }, { "slug": "mcpr", "order": 2, "category": "agents", "title": "One registry for several MCP clients", "summary": "Maintain MCP server definitions once and translate them into each editor's native configuration.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "Go", "CLI", "MCP" ], "abstract": "MCP standardizes communication with tools, but applications still store server configuration in different places and formats. MCPR keeps a central set of server definitions and writes the corresponding configuration for selected clients. Its purpose is to make a change to a command, endpoint, or argument a single maintenance operation. [1]", "problem": [ "A developer using several AI editors can end up maintaining several copies of the same server command and environment. Updating one copy leaves another editor running an older command or endpoint. Project settings add a second dimension: a server may belong to one checkout rather than every editor session on the machine. [1]", "This is a configuration distribution problem. The protocol's stdio and HTTP transport definitions do not prescribe a common on-disk editor settings file. For example, VS Code documents its own MCP configuration and management workflow. [2][3]" ], "design": [ "MCPR records stdio servers as commands, arguments, and environment values, and HTTP servers as URLs and headers. It stores global definitions in its configuration directory and can discover a project-local mcpr.json. A sync records the destination client and the selected subset of servers. Later additions or removals resynchronize those registered destinations. [1]", "Client adapters translate the registry into native settings. The documented sync behavior preserves unrelated client settings. Client support is explicit, including Claude Desktop, Cursor, VS Code, Windsurf, and Zed; project-local support differs between them. A registry entry cannot grant a client a transport capability that the client itself lacks. [1]" ], "comparisons": [ { "alternative": "Each editor's MCP settings", "constraint": "Native settings provide useful client-specific controls, but editing separate files makes the operator responsible for keeping duplicated server definitions in agreement. [3]", "response": "MCPR gives the shared definition one owner and translates it to the clients selected for synchronization. [1]", "tradeoff": "Use native settings alone for one client or when you need a setting the MCPR adapter does not represent." }, { "alternative": "A shared configuration file or dotfile symlink", "constraint": "Sharing one file only works when every consumer expects compatible keys and file structure. MCP transports do not impose that compatibility on editor configuration. [2][3]", "response": "MCPR performs a format conversion instead of assuming each application can read the same file. It can also synchronize a subset of servers. [1]", "tradeoff": "For clients with identical formats, a plain shared file may require less machinery." } ], "boundaries": [ "MCPR distributes configuration; it does not operate the servers or prove they are trustworthy. Its documented configuration includes environment and header values, so treat the registry and generated client files according to the sensitivity of those values. [1]", "Check the supported-client table and the generated settings when adopting a new editor version. Configuration schemas and transport support evolve independently. Keep client-specific settings under the ownership of the native application when they do not belong to the shared registry." ], "related": [ "earl", "claude-tools-mcp" ], "sources": [ { "label": "MCPR: registry, adapters, sync, and client support", "path": "README.md", "url": "https://github.com/mathematic-inc/mcpr/blob/af29f67f340412b28a9c53bd611422e80575517f/README.md" }, { "label": "MCP: stdio and Streamable HTTP transports", "url": "https://modelcontextprotocol.io/specification/2025-06-18/basic/transports" }, { "label": "VS Code: adding and managing MCP servers", "url": "https://code.visualstudio.com/docs/agent-customization/mcp-servers" } ], "repository": { "name": "mcpr", "sha": "af29f67f340412b28a9c53bd611422e80575517f", "language": "Go", "description": "CLI tool to manage and sync Model Context Protocol server configs across AI editors — Claude Desktop, Cursor, VS Code, Windsurf, Zed, and more", "license": "Apache-2.0" }, "categoryInfo": { "id": "agents", "label": "Agents & interfaces", "short": "Agents", "description": "Control the operations an agent can perform and the context it can inspect." } }, { "slug": "claude-tools-mcp", "order": 3, "category": "agents", "title": "File and shell tools at an HTTP endpoint", "summary": "Expose file editing, search, and background shell operations to MCP clients through a Go server.", "kind": "Implementation note", "rationale": "Engineering rationale", "tags": [ "Go", "MCP", "HTTP" ], "abstract": "An MCP client may need to work on files and processes in a different execution environment. claude-tools-mcp offers a familiar file-and-shell tool surface through Streamable HTTP. It implements those operations in a Go server, so clients can share an execution endpoint without depending on one editor's built-in tool implementation. [1][2]", "problem": [ "A local stdio server normally starts as a child process of the client. That is a poor match when the working directory, installed commands, or long-running processes belong to a separate host or container. MCP's HTTP transport makes an independently hosted server possible, but a transport alone does not implement file editing or process management. [3]", "The repository fills that operational gap with concrete read, write, exact-edit, glob, grep, and shell tools. The engineering rationale is portability of the tool surface across MCP clients. Its name describes the familiar operations it offers; it is a separate implementation, not a mechanism for inheriting Claude Code's permission system. [1][2]" ], "design": [ "The server registers typed tools through the MCP Go SDK. Search delegates to ripgrep. Shell operations support timeouts and background execution, with separate operations for reading output, listing shells, and terminating a process. The file tools impose size and result limits and require absolute paths. [1][2]", "The HTTP handler runs in stateless protocol mode, but the application still keeps file-modification tracking and background-shell state. A deployment that distributes requests between replicas therefore needs to account for which process owns a shell; protocol statelessness does not make a running process portable between hosts. [1][2]" ], "comparisons": [ { "alternative": "A local stdio MCP server", "constraint": "In the standard stdio arrangement, the client launches the server process. Its filesystem and toolchain follow that launch environment. [3]", "response": "The HTTP server runs independently, allowing the operator to choose the execution host or container. [1]", "tradeoff": "A local stdio server avoids exposing a network service and is sufficient when the client and workspace belong on the same machine." }, { "alternative": "An SSH shell", "constraint": "SSH gives a remote command session. A client needing distinct read, edit, search, and background-output operations must add its own structured adapter around that session.", "response": "This server supplies those operations as MCP tools with defined inputs and result limits. [1][2]", "tradeoff": "SSH already provides transport authentication and interactive administration. This server's entry point does not add an equivalent authentication layer. [2]" } ], "boundaries": [ "The checked entry point binds to localhost by default and configures HTTP timeouts and graceful shutdown. It does not install application authentication middleware. Absolute paths and file-size limits are not filesystem isolation. Network access must be controlled by the deployment, and the process should have only the host permissions its callers are meant to exercise. [2][3]", "Choose it for a controlled execution environment where structured remote tools are useful. Use Earl when the intended interface is a restricted operation catalog; these two projects expose materially different levels of authority." ], "related": [ "earl", "mcpr" ], "sources": [ { "label": "claude-tools-mcp: tools, state, and requirements", "path": "README.md", "url": "https://github.com/mathematic-inc/claude-tools-mcp/blob/6f7937964f46739fd61b582625b0da509353d21f/README.md" }, { "label": "Server entry point and registered tool surface", "path": "cmd/claude-tools-mcp/main.go", "url": "https://github.com/mathematic-inc/claude-tools-mcp/blob/6f7937964f46739fd61b582625b0da509353d21f/cmd/claude-tools-mcp/main.go" }, { "label": "MCP: process model and HTTP transport requirements", "url": "https://modelcontextprotocol.io/specification/2025-06-18/basic/transports" } ], "repository": { "name": "claude-tools-mcp", "sha": "6f7937964f46739fd61b582625b0da509353d21f", "language": "Go", "description": "MCP server that exposes Claude Code's file and shell tools (bash, read, write, edit, glob, grep) over HTTP for remote use by any MCP client", "license": "Apache-2.0" }, "categoryInfo": { "id": "agents", "label": "Agents & interfaces", "short": "Agents", "description": "Control the operations an agent can perform and the context it can inspect." } }, { "slug": "tauri-plugin-ui-inspector", "order": 4, "category": "agents", "title": "A durable reference to a running interface", "summary": "Capture native pixels, DOM semantics, and optional source metadata in a reference a coding agent can resolve.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "Rust", "TypeScript", "Tauri" ], "abstract": "A screenshot tells a coding agent what an interface looks like, but it does not identify the element's role, locator, or source file. tauri-plugin-ui-inspector packages that context with an actual native-window capture and gives the selection a durable reference. The reference can be inspected later and checked against the running interface. [1]", "problem": [ "An instruction such as 'fix this button' loses precision when a page has several similar buttons. A coordinate can move after a resize. A CSS selector can match a different node after a render. An image alone requires the agent to infer both the element's identity and the code that produced it.", "The plugin addresses this by recording evidence at selection time: accessibility semantics, ranked locators with uniqueness information, nearby DOM context, and optional framework source metadata. The reference names a particular observation, not just a string that happens to match something now. [1]" ], "design": [ "The frontend picker chooses an element and gathers its semantics. The Rust backend captures the desktop compositor's native window output, computes the element rectangle in that bitmap's coordinate space, and stores the reference with window and element images. Svelte, React, and Vue adapters can add development source information without making a framework mandatory. [1]", "The CLI uses a local socket or named pipe to request selections and resolve stored references. Resolution tries previously unique locators, then checks the original tag, role, and accessible name. An ambiguous or missing match produces a failure instead of selecting a nearby element. [1]" ], "comparisons": [ { "alternative": "html2canvas", "constraint": "html2canvas reconstructs a rendering from the DOM and the CSS features it supports. Its documentation says the result may differ from the actual display. [2]", "response": "The inspector crops the native capture, so the selected pixels come from the same bitmap as the window, including rendered canvas and WebGL content. [1]", "tradeoff": "Native capture needs platform support and permissions. A DOM renderer can run in an ordinary browser without a native plugin." }, { "alternative": "A screenshot plus a hand-written selector", "constraint": "The screenshot has no semantic identity, while the selector alone records no evidence that it uniquely identified the intended element.", "response": "A reference retains both the visual observation and locator evidence, with a strict later resolution step. Source metadata can take the agent to the component. [1]", "tradeoff": "A manually supplied screenshot remains enough for broad visual feedback. The plugin earns its integration cost when agents need repeatable element-level references." } ], "boundaries": [ "Source locations depend on development metadata and may be absent in production. Closed shadow roots remain opaque. Native capture can fail because of screen-recording permissions, protected windows, or compositor restrictions; the repository documents different levels of platform verification. [1]", "Text and attribute redaction do not erase a secret already painted into screenshot pixels. Treat stored captures as sensitive. The reference is an aid to inspection and source navigation, not a replacement for an application's behavior tests." ], "related": [ "connectrpc-tauri", "connectrpc-sdk" ], "sources": [ { "label": "UI inspector: reference model, capture, resolution, and platform support", "path": "README.md", "url": "https://github.com/mathematic-inc/tauri-plugin-ui-inspector/blob/73a5457c3b0dfd7ba6d7e50a23f0558c8ceea308/README.md" }, { "label": "html2canvas: rendering method and limitations", "url": "https://html2canvas.hertzen.com/documentation" } ], "repository": { "name": "tauri-plugin-ui-inspector", "sha": "73a5457c3b0dfd7ba6d7e50a23f0558c8ceea308", "language": "Rust", "description": "Inspect, capture, and reference Tauri UI elements for coding agents", "license": "Apache-2.0" }, "categoryInfo": { "id": "agents", "label": "Agents & interfaces", "short": "Agents", "description": "Control the operations an agent can perform and the context it can inspect." } }, { "slug": "ts-japi", "order": 5, "category": "schemas", "title": "A serialization model for JSON:API documents", "summary": "Describe resources and relationships in TypeScript without tying the response format to a web framework.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "TypeScript", "JSON:API" ], "abstract": "JSON:API requires more than a JSON-shaped response. Resource identity, relationship linkage, included resources, and links have distinct meanings. ts-japi represents these concerns with composable TypeScript serializers so an API can share document construction across handlers and data sources. Its published package has no runtime dependencies. [1][2]", "problem": [ "A controller that constructs a response by hand has to preserve the same rules every time it includes another resource. JSON:API compound documents require linkage to primary data and restrict duplicate resource objects. A nested JavaScript object and a valid compound document are not interchangeable. [3]", "The maintenance problem grows when several endpoints return the same resource with different includes, links, or metadata. Repeating serialization logic in handlers makes each endpoint another place to update when a resource's representation changes. ts-japi puts that representation beside a reusable resource serializer. [1]" ], "design": [ "Serializer handles the primary resource. Relator connects a resource to an asynchronously fetched related value and its serializer; Linker, Metaizer, and Paginator define the corresponding document elements. Include paths or a bounded depth control traversal into related resources. A serializer getter can break circular construction dependencies. [1]", "The API uses generics for resource data and relationship callbacks. Separate error and polymorphic serializers cover error documents and mixed resource types. These facilities organize response construction; the application still owns authorization, data fetching, and the cost of fetching a relationship. [1]" ], "comparisons": [ { "alternative": "Hand-written JSON:API responses", "constraint": "Every endpoint must preserve identity, linkage, and inclusion rules while constructing its own objects. A missing relationship can make an otherwise valid JSON response an invalid compound document. [3]", "response": "Reusable serializers and relators centralize document construction and resource traversal. [1]", "tradeoff": "For a small endpoint with a fixed response, a hand-written object and focused specification tests may be easier to maintain." }, { "alternative": "jsonapi-serializer", "constraint": "jsonapi-serializer already supports relationships, included resources, links, and metadata. Its documented interface organizes those through nested option objects; it is not missing the JSON:API relationship model. [4]", "response": "ts-japi offers a different composition model: resource-typed serializers and explicit asynchronous Relator callbacks, with separate link and metadata objects. [1]", "tradeoff": "jsonapi-serializer also supplies deserialization. ts-japi explicitly does not, so it is not a substitute for that part of an application. [1][4]" } ], "boundaries": [ "Deep relationship traversal can multiply database work. Set inclusion rules deliberately and arrange batching or caching in the data layer where needed. A serializer is not an ORM or a query optimizer. [1]", "The default declared JSON:API version is 1.0. Do not infer complete support for every JSON:API 1.1 extension from the project name. Use the options and behavior of the pinned implementation, and test the contract your API promises. This note makes no exclusivity claim about TypeScript or recursive inclusion." ], "related": [ "connectrpc-sdk", "vscode-api-linter" ], "sources": [ { "label": "ts-japi: serialization, composition, includes, and scope", "path": "README.md", "url": "https://github.com/mathematic-inc/ts-japi/blob/32bb6dafbae83942c964347c13151fcf2a46431e/README.md" }, { "label": "ts-japi: package manifest", "path": "package.json", "url": "https://github.com/mathematic-inc/ts-japi/blob/32bb6dafbae83942c964347c13151fcf2a46431e/package.json" }, { "label": "JSON:API: compound document requirements", "url": "https://jsonapi.org/format/#document-compound-documents" }, { "label": "jsonapi-serializer: supported serialization and deserialization", "url": "https://github.com/SeyZ/jsonapi-serializer" } ], "repository": { "name": "ts-japi", "sha": "32bb6dafbae83942c964347c13151fcf2a46431e", "language": "TypeScript", "description": "Zero-dependency TypeScript library for serializing data to the JSON:API specification with full type safety, relationships, links, and pagination", "license": "Apache-2.0" }, "categoryInfo": { "id": "schemas", "label": "Schemas & protocols", "short": "Schemas", "description": "Carry a contract through serialization, validation, and client generation." } }, { "slug": "sqlc-gen-sqlx", "order": 6, "category": "schemas", "title": "SQL files as the source of a Rust query API", "summary": "Generate SQLx query functions, row types, and parameter types from sqlc's analysis of PostgreSQL.", "kind": "Implementation note", "rationale": "Engineering rationale", "tags": [ "Rust", "PostgreSQL", "Code generation" ], "abstract": "Teams that keep reviewed SQL in dedicated files still need Rust types and callable query functions. sqlc-gen-sqlx connects sqlc's SQL analysis to SQLx execution. It generates ordinary Rust functions and row structures so the query text and the corresponding application API can be regenerated together. [1]", "problem": [ "Writing a query function by hand duplicates information that already exists in the SQL: parameter order, selected columns, nullability, and the intended result cardinality. A schema or query change can leave the handwritten wrapper behind. The useful automation is to derive that wrapper from the analyzed query.", "SQLx's checked macros solve a related problem by asking a database about a query, or by using previously prepared offline metadata. A sqlc-based workflow chooses a separate generation step that consumes the schema and SQL files. That is a different source of type information with different maintenance costs. [2]" ], "design": [ "For annotated PostgreSQL queries, the plugin emits SQL constants, typed row structs, optional parameter structs, and query functions. It handles sqlc cardinality annotations, arrays and nullable columns, type overrides, and PostgreSQL enum and composite types. Native and WebAssembly plugin distributions support sqlc's process and WASM execution modes. [1]", "Generated functions accept a pool, connection, or transaction through a generated executor interface. Borrowed parameter overrides can keep input strings borrowed while output rows remain owned. Batch annotations produce streams; copy operations expose chunked bulk insertion. These are explicit generated APIs that can be reviewed with the SQL. [1]" ], "comparisons": [ { "alternative": "SQLx query! and query_file!", "constraint": "Checked macros need a compatible database during expansion or current .sqlx metadata prepared earlier. Offline mode removes the live build-time connection, but the prepared data still needs maintenance. [2]", "response": "The plugin generates SQLx code from sqlc's query and schema analysis, making generation a separate, reviewable build step. [1]", "tradeoff": "SQLx checks against the database's own interpretation. sqlc's analyzer has its own supported SQL surface; the two validation methods are not identical." }, { "alternative": "Hand-written SQLx wrappers", "constraint": "A query and its Rust wrapper can disagree about parameter ordering or result types after an edit. The compiler cannot derive the intended SQL schema from an unchecked string alone.", "response": "Regeneration updates the row types and calling interface with the query. Type overrides record deliberate application mappings in the generator configuration. [1]", "tradeoff": "Hand-written wrappers are appropriate for dynamic queries or PostgreSQL behavior the generator does not support." } ], "boundaries": [ "The documented target is PostgreSQL. Do not assume the plugin generates MySQL or SQLite code because SQLx supports those databases. Consumers also need the SQLx features and companion crates required by their generated types. [1]", "Keep migrations, the schema supplied to sqlc, and the deployed database in agreement. Generation does not perform migrations or prove production schema compatibility. Validate representative generated queries against the database, especially after changing nullability, custom types, or type overrides." ], "related": [ "protovalidate-buffa", "connectrpc-sdk" ], "sources": [ { "label": "sqlc-gen-sqlx: generated API, types, annotations, and overrides", "path": "README.md", "url": "https://github.com/mathematic-inc/sqlc-gen-sqlx/blob/a1c7e5e844467eeb793fd67934526e3916e391aa/README.md" }, { "label": "SQLx query macros: requirements and offline mode", "url": "https://docs.rs/sqlx/latest/sqlx/macro.query.html" } ], "repository": { "name": "sqlc-gen-sqlx", "sha": "a1c7e5e844467eeb793fd67934526e3916e391aa", "language": "Rust", "description": null, "license": null }, "categoryInfo": { "id": "schemas", "label": "Schemas & protocols", "short": "Schemas", "description": "Carry a contract through serialization, validation, and client generation." } }, { "slug": "protovalidate-buffa", "order": 7, "category": "schemas", "title": "Validation compiled for Buffa message types", "summary": "Turn buf.validate annotations and CEL rules into Rust validators for owned messages and borrowed views.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "Rust", "Protobuf", "Code generation" ], "abstract": "A protobuf validation rule is only useful if it can run against the application's actual message types. protovalidate-buffa compiles buf.validate annotations into Validate implementations for Buffa's owned and borrowed representations. CEL rules become native Rust during generation, keeping a CEL interpreter out of the validation path. [1]", "problem": [ "The repository documents an original compatibility gap: the Rust validators considered at its creation targeted Prost, while Buffa uses a different generated representation with borrowed views. Converting each request to a separate model solely to validate it undermines the reason for using that representation. [1]", "Runtime rules also move some failures later in the lifecycle. A malformed expression or a reference to a nonexistent field should be found while generating the application if the schema is already known. Static generation gives the compiler a concrete validation program to check. [1]" ], "design": [ "The plugin reads buf.validate extensions from descriptors and emits direct field walks for Buffa messages and views. A runtime crate provides the Validate trait, rule helpers, and structured violations. An optional Connect integration inserts request validation at handler entry without first converting a borrowed request into an owned message. [1]", "The repository reports 2,872 passing cases in the upstream conformance harness, including proto2, proto3, and editions 2023. That is the maintainer's recorded result at the cited revision, not a new conformance run performed for this catalog. Generator and Buffa versions must remain compatible because generated field and view shapes are part of the integration. [1]" ], "comparisons": [ { "alternative": "Descriptor-driven prost-protovalidate", "constraint": "The runtime Validator reads descriptors and compiles rules, then caches them for reuse. That is useful for dynamic schemas but adds runtime rule machinery when the schema is fixed. [2]", "response": "This project's documented path emits field-specific Rust, including CEL expressions, before the application runs. [1]", "tradeoff": "Current prost-protovalidate also documents a generated validation path. Static validation is therefore not an exclusive capability; compare the specific backend, rule coverage, and integration you need. [2]" }, { "alternative": "prost-protovalidate-build with Buffa", "constraint": "Version 0.6.0 documents a Buffa backend that generates direct checks for standard rules. Messages with CEL use a configured skip, build error, or embedded runtime bridge; the native path does not compile those CEL rules into direct checks. [3]", "response": "protovalidate-buffa transpiles CEL into Rust during generation and emits validators for the owned and borrowed Buffa representations. [1]", "tradeoff": "The distinction is the CEL execution path and integration model, not the mere existence of Buffa support. Evaluate the rule set your schema uses and the dependency cost of each chosen configuration. [1][3]" }, { "alternative": "Validation written in handlers", "constraint": "The protobuf contract and the handler checks become separate definitions. A rule added to the schema has no effect on a handler that does not implement it.", "response": "The plugin derives validators from the annotations, and the Connect macro can apply them at entry. [1]", "tradeoff": "Authorization, database-dependent checks, and business invariants still belong in application code; schema validation cannot replace them." } ], "boundaries": [ "The original motivation is historical context. Current prost-protovalidate-build supports Buffa and static standard-rule validation. For schemas that use CEL, compare native transpilation here against the alternative's documented runtime-bridge path. [1][3]", "The cited repository targets Buffa 0.9.1 and ConnectRPC 0.9. Keep message generation and validator generation in step, including field-naming options. Passing a finite conformance suite is evidence of behavior for those cases; it is not a proof for all future schema revisions." ], "related": [ "connectrpc-tauri", "connectrpc-sdk", "vscode-api-linter" ], "sources": [ { "label": "protovalidate-buffa: motivation, generated validation, compatibility, and reported conformance", "path": "README.md", "url": "https://github.com/mathematic-inc/protovalidate-buffa/blob/490ac4201b8226c4412c4fec30ad971e86a78121/README.md" }, { "label": "prost-protovalidate: runtime and generated validation interfaces", "url": "https://docs.rs/prost-protovalidate/latest/prost_protovalidate/" }, { "label": "prost-protovalidate-build 0.6.0: Buffa backend and CEL handling", "url": "https://docs.rs/prost-protovalidate-build/latest/prost_protovalidate_build/" } ], "repository": { "name": "protovalidate-buffa", "sha": "490ac4201b8226c4412c4fec30ad971e86a78121", "language": "Rust", "description": "Static-codegen protovalidate for the buffa Rust protobuf runtime", "license": "Apache-2.0" }, "categoryInfo": { "id": "schemas", "label": "Schemas & protocols", "short": "Schemas", "description": "Carry a contract through serialization, validation, and client generation." } }, { "slug": "connectrpc-sdk", "order": 8, "category": "schemas", "title": "Resource-oriented clients from service-oriented schemas", "summary": "Generate a consistent client vocabulary without reimplementing the Connect runtime.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "TypeScript", "Rust", "ConnectRPC" ], "abstract": "RPC names need enough context to stand on their own. The same names become repetitive when a client already groups them by resource. connectrpc-sdk generates a naming layer over existing Connect clients, turning service-shaped calls into a resource-oriented SDK while retaining the underlying protocol implementation. [1]", "problem": [ "A schema might expose WorkspaceService.CreateWorkspace. Repeating both nouns in a client call gives the caller workspaceService.createWorkspace(request). The repository's motivating example instead exposes workspaces.create(request): the namespace carries the resource and the method carries the action. [1]", "Writing that layer by hand introduces another contract to maintain. Renamed methods, added services, or changes to streaming signatures can leave a facade stale even though the underlying generated client is correct. Generating the naming layer keeps it coupled to the same schema." ], "design": [ "The generator derives namespaces from service names and pluralizes resource words. It removes only the relevant leading resource occurrence in a method name, matching whole words. Explicit namespace and method annotations handle cases where product terminology differs from the schema. Naming collisions fail generation rather than silently overwriting a method. [1]", "TypeScript signatures follow the generated service descriptors. The Rust target builds a client with borrowed resource groups. Existing generated clients still own serialization, transport, cancellation, streaming, and error mapping. The facade changes the shape of the calling API without introducing another wire protocol. [1]" ], "comparisons": [ { "alternative": "The standard Connect client", "constraint": "Connect already creates typed clients from service descriptors. Its direct service-level API is sufficient for calling an RPC, but does not by itself choose a product's resource-oriented aggregate vocabulary. [2]", "response": "connectrpc-sdk derives that vocabulary and groups services behind a client for the protobuf package. [1]", "tradeoff": "Use the direct client when schema names are already clear or when exact service-level correspondence is more useful than an aggregate SDK." }, { "alternative": "A hand-written SDK facade", "constraint": "Every wrapper signature and rename becomes another place to update after a schema change. Cross-service naming collisions also require a convention.", "response": "Generation derives names, carries types through, and rejects ambiguous results. Annotations preserve deliberate exceptions in the schema. [1]", "tradeoff": "Handwritten code remains the right place for multi-call workflows, caching policies, or business operations that are not a direct RPC facade." } ], "boundaries": [ "English pluralization and naming conventions are assumptions, so inspect the generated public API and annotate exceptions. A stable protobuf service does not automatically imply a stable derived SDK name after a naming-rule change. [1]", "The Rust facade returns the response message for unary calls; callers that need transport headers or trailers can use the underlying generated client. Keep the generator compatible with the Connect and message generators documented for the target language." ], "related": [ "connectrpc-tauri", "protovalidate-buffa", "ts-japi" ], "sources": [ { "label": "Connect SDK: motivating example, derivation, collision rules, and target APIs", "path": "README.md", "url": "https://github.com/mathematic-inc/connectrpc-sdk/blob/ba0ad915eb6e6697b98cb41bfc926008c5828494/README.md" }, { "label": "Connect: typed clients from service descriptors", "url": "https://connectrpc.com/docs/web/getting-started/" } ], "repository": { "name": "connectrpc-sdk", "sha": "ba0ad915eb6e6697b98cb41bfc926008c5828494", "language": "TypeScript", "description": "Generates idiomatic, namespaced client SDKs from ConnectRPC schemas, for TypeScript and Rust", "license": "Apache-2.0" }, "categoryInfo": { "id": "schemas", "label": "Schemas & protocols", "short": "Schemas", "description": "Carry a contract through serialization, validation, and client generation." } }, { "slug": "connectrpc-tauri", "order": 9, "category": "schemas", "title": "Connect services inside a Tauri application", "summary": "Carry Connect calls between the webview and Rust without running a loopback HTTP server.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "Rust", "TypeScript", "Tauri" ], "abstract": "A Tauri frontend and its Rust backend already share an application boundary. connectrpc-tauri carries Connect protocol traffic across that boundary, reusing Connect's serialization and streaming machinery while removing the need to host a local HTTP listener. Unary and streaming calls take different transport paths. [1]", "problem": [ "A desktop application can expose Rust services over loopback HTTP, but then it must manage a listener, address selection, and access to that listener. Replacing RPC with unrelated Tauri commands avoids the listener while making the application responsible for rebuilding its service contract and streaming behavior.", "The repository takes a third route: adapt the byte-level interfaces already offered by the Connect runtimes. This preserves a shared schema and protocol behavior while changing how a request reaches the Rust service. [1]" ], "design": [ "Unary requests use a custom ipc-connect URI scheme and invoke the Rust service through a synthetic HTTP request. Streaming calls use commands and a channel, with binary protobuf envelopes. The request pump coalesces already-produced chunks and applies backpressure; cancellation propagates from the client's AbortSignal. [1]", "Connect still performs message serialization, envelope framing, trailers, and error mapping. The TypeScript adapter uses the protocol-level transport seam, enabling unary, server-streaming, client-streaming, and bidirectional methods without routing those streams through an ordinary browser HTTP transport. [1]" ], "comparisons": [ { "alternative": "A local HTTP Connect server", "constraint": "A loopback deployment requires an actual listener and a policy for which callers may reach it. Those concerns exist even though the frontend and service ship together.", "response": "The custom scheme and command/channel paths reach the in-process Rust service without reserving a port. [1]", "tradeoff": "HTTP is appropriate when other applications or remote clients must call the same server. This adapter serves webview-to-Rust calls." }, { "alternative": "Hand-written Tauri commands and events", "constraint": "Tauri gives applications commands and channels, but the application must define payload contracts and streaming semantics. Binary RPC data encoded inside JSON arguments also requires a less direct representation. [1][2]", "response": "The adapter retains Connect's wire semantics and sends binary buffers across the bridge, with a shared schema and a per-call channel. [1]", "tradeoff": "A few simple commands may need no RPC layer. Tauri's native command permission model is also different from the adapter's custom-scheme unary path." } ], "boundaries": [ "The unary custom-scheme path bypasses Tauri command ACL dispatch. Do not assume granting or denying a command permission authorizes every unary RPC; enforce the application's service and caller policy at the appropriate boundary. [1]", "The repository reports macOS verification for the unary path and documents Android streaming's JSON-array fallback. Its published timing table describes one M-series Mac run, not a universal speed comparison. Evaluate your platform and payload sizes, and keep the distinction between protocol reuse and transport-specific behavior explicit." ], "related": [ "connectrpc-sdk", "tauri-plugin-ui-inspector", "protovalidate-buffa" ], "sources": [ { "label": "ConnectRPC over Tauri: architecture, transport paths, benchmarks, and limitations", "path": "README.md", "url": "https://github.com/mathematic-inc/connectrpc-tauri/blob/e742f770abe89707e7add73257673ccf495a8434/README.md" }, { "label": "Tauri: calling Rust from the frontend", "url": "https://v2.tauri.app/develop/calling-rust/" } ], "repository": { "name": "connectrpc-tauri", "sha": "e742f770abe89707e7add73257673ccf495a8434", "language": "Rust", "description": "Connect RPC transport over Tauri IPC", "license": "Apache-2.0" }, "categoryInfo": { "id": "schemas", "label": "Schemas & protocols", "short": "Schemas", "description": "Carry a contract through serialization, validation, and client generation." } }, { "slug": "addr-spec-rs", "order": 10, "category": "tools", "title": "Parse an address as syntax, not just a string", "summary": "Parse and serialize UTF-8 email addr-spec values with optional normalization and precise errors.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "Rust", "Parsing", "Email" ], "abstract": "Applications often need more than a boolean answer to whether an email address looks plausible. addr-spec-rs parses the local part and domain according to the addr-spec grammar and can serialize the resulting representation. Optional Unicode normalization and grammar features make those decisions explicit. [1]", "problem": [ "An email address can contain quoted syntax, international characters, and optional grammar that a simple split at the at-sign does not describe. An application that wants structured values and useful parse errors needs a parser with a defined acceptance policy, rather than a pattern chosen from a few familiar addresses. [1][3]", "Validation and representation are also different tasks. A string wrapper can confirm accepted syntax while retaining the original spelling. An application comparing or serializing addresses may instead want parsed parts and a normalization policy. That policy must remain separate from provider-specific mailbox identity." ], "design": [ "The crate exposes parsing and serialization for RFC 5322 addr-spec with RFC 6532 UTF-8 extensions. NFC normalization is enabled by default. Comments, domain literals, and whitespace are separate features, and the crate supports no_std use. Errors identify positions in the input. [1]", "The representation deliberately does not preserve every presentation detail. With the corresponding features enabled, the parser can accept comments and folding whitespace, but serialization does not reproduce comments or transport-dependent folding. Applications can retrieve serialized local and domain parts when they need to control folding themselves. [1]" ], "comparisons": [ { "alternative": "email_address", "constraint": "The current crate supports ASCII and UTF-8, including quoted local parts. Its documented scope does not include all header productions such as folding whitespace and comments. A claim that it lacks Unicode support would be wrong. [2]", "response": "addr-spec provides optional parsing of comments and whitespace, NFC normalization, and a parsed serialization model. [1]", "tradeoff": "email_address is a reasonable fit when an application needs a validated string and its documented grammar is sufficient." }, { "alternative": "A custom email regex", "constraint": "A pattern's accepted language depends on what its author encoded. A short pattern for common addresses omits parts of the RFC grammar; adding cases also makes diagnostics harder to localize. [3]", "response": "A dedicated parser gives the application explicit feature switches and position-based parse failures. [1]", "tradeoff": "A deliberately narrow product input policy can still use a simple check, provided the application describes that policy rather than calling it complete email validation." } ], "boundaries": [ "Successful parsing does not prove that a mailbox exists, can receive mail, or belongs to a user. Nor does Unicode normalization establish that two addresses route to the same inbox. Provider-specific aliasing and delivery verification are separate concerns.", "Do not discard comments or normalize input if the application requires exact archival round trips. Choose feature flags from the grammar you need to consume. This catalog makes no general speed or uniqueness claim across mail providers." ], "related": [ "unfmt", "ts-japi" ], "sources": [ { "label": "addr-spec: supported grammar, features, and serialization caveats", "path": "README.md", "url": "https://github.com/mathematic-inc/addr-spec-rs/blob/5555b28ba5407c68654dbadcb442411ec55255cc/README.md" }, { "label": "email_address: current accepted syntax and wrapper model", "url": "https://docs.rs/email_address/latest/email_address/" }, { "label": "RFC 5322: addr-spec grammar", "url": "https://www.rfc-editor.org/rfc/rfc5322#section-3.4.1" } ], "repository": { "name": "addr-spec-rs", "sha": "5555b28ba5407c68654dbadcb442411ec55255cc", "language": "Rust", "description": "A wicked fast UTF-8 email address parser and serializer conforming to RFC 5322 and RFC 6532", "license": "Apache-2.0" }, "categoryInfo": { "id": "tools", "label": "Developer tools", "short": "Tools", "description": "Make a small, recurring part of the editing and development workflow explicit." } }, { "slug": "unfmt", "order": 11, "category": "tools", "title": "Match the structure of a formatted string", "summary": "Compile literal-and-capture patterns into Rust code without compiling a pattern at runtime.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "Rust", "Parsing", "Macros" ], "abstract": "Many parsing jobs consist of fixed text with a few variable fields: the shape of a format string in reverse. unfmt provides that narrower pattern language as a compile-time macro. It is useful when a general regular expression carries more syntax and runtime setup than the input format requires. [1]", "problem": [ "A parser for a predictable log line often needs to verify a delimiter and return the text between two literals. Repeated splitting distributes the format across several operations. A regular expression centralizes the shape, but its pattern still needs compilation when the program runs unless another mechanism has already done that work. [2]", "unfmt keeps the expected text and captures in a single pattern. Its purpose is a convenient static parser for this particular class of input, rather than a general-purpose replacement for regular expressions or a parser for recursive grammars. [1]" ], "design": [ "The unformat macro accepts literal text with unnamed, indexed, or named captures. Captures can use a FromStr type to convert the extracted text. An optional whole-input match mode rejects surrounding unmatched input. The pattern is processed at compile time, while matching and any captured-value conversion happen at runtime. [1]", "The language excludes ambiguous consecutive captures and does not backtrack. Those constraints make the intended decomposition visible: a capture needs enough literal structure around it to define a useful boundary. [1]" ], "comparisons": [ { "alternative": "The regex crate", "constraint": "Regex::new compiles a pattern at runtime. The crate documents avoiding repeated compilation, and current versions also provide a macro that caches the compiled regex. It is inaccurate to say every regex match recompiles its pattern. [2]", "response": "unfmt generates the literal/capture matching structure at compile time, avoiding runtime pattern compilation for its smaller language. [1]", "tradeoff": "regex supports richer matching, including alternation and character classes. Cached regexes are often the right answer when those features are needed." }, { "alternative": "Manual split and strip operations", "constraint": "Several independent operations can obscure which delimiters define the complete input format and which captures should be typed.", "response": "A single pattern records the literals, capture order, and optional conversions together. Whole-input mode makes full consumption explicit. [1]", "tradeoff": "One split_once can be clearer for a two-part input. A macro is useful only when it makes the format easier to read and maintain." } ], "boundaries": [ "Use explicit whole-input matching when trailing or leading input must be rejected. Choose patterns with unambiguous delimiters, and test failures as well as successful examples. The absence of backtracking is a semantic restriction, not a claim that every possible parsing workload becomes faster. [1]", "Patterns known only at runtime need a different tool. Recursive or context-sensitive input belongs in a parser designed for that grammar. This note claims elimination of runtime pattern compilation, not elimination of runtime parsing work." ], "related": [ "addr-spec-rs", "if-changed" ], "sources": [ { "label": "unfmt: captures, typed conversion, whole-input matching, and restrictions", "path": "README.md", "url": "https://github.com/mathematic-inc/unfmt/blob/4e951d6c118b0d4e437c27e81ecd07e892ce1a31/README.md" }, { "label": "regex: compilation, caching, and pattern capabilities", "url": "https://docs.rs/regex/latest/regex/" } ], "repository": { "name": "unfmt", "sha": "4e951d6c118b0d4e437c27e81ecd07e892ce1a31", "language": "Rust", "description": "Compile-time string pattern matching that reverses format! interpolation — a lightweight regex alternative with no runtime compilation cost", "license": "Apache-2.0" }, "categoryInfo": { "id": "tools", "label": "Developer tools", "short": "Tools", "description": "Make a small, recurring part of the editing and development workflow explicit." } }, { "slug": "if-changed", "order": 12, "category": "tools", "title": "Make a dependency between edits executable", "summary": "Require dependent files or named regions to change together when a diff touches an annotated block.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "Rust", "CLI", "CI" ], "abstract": "Some relationships between files are too small to justify a generator, yet too easy to forget during an edit. if-changed lets maintainers declare those relationships beside the code. It checks a diff and fails when a changed region's declared counterpart has not also changed. [1]", "problem": [ "The motivating example is an error-code enum represented in both Rust and TypeScript. Editing one definition without the other introduces drift. A shared schema and generator can eliminate that duplication, but installing a generation pipeline for a small, isolated pair of definitions can cost more than it saves. [1]", "A comment asking the next author to update another file expresses intent without enforcing it. The tool turns the instruction into a check that can run before a commit or against a pair of revisions in CI." ], "design": [ "An if-changed annotation opens a named region and a then-change annotation points to a file or named region that must also change. The command reads the diff between selected revisions, or between HEAD and the working tree by default, and reports unsatisfied dependencies. Reciprocal annotations can express a two-way relationship. [1]", "Dependencies can include path lists and patterns. Naming a whole file accepts any change in that file; naming a region narrows the requirement. The tool integrates with pre-commit and offers an explicit commit-footer escape mechanism for cases where a dependent edit is intentionally unnecessary. [1]" ], "comparisons": [ { "alternative": "A shared schema and code generation", "constraint": "Generating both definitions removes manual synchronization, but requires a generator, generated-file ownership, and build integration for the representations involved. The repository identifies that setup cost in its motivating example. [1]", "response": "Annotations add a diff-time reminder at the existing definitions, with no new source language to maintain. [1]", "tradeoff": "Generation is stronger when feasible: it derives consistent values. if-changed only proves that a corresponding region was edited, not that its new meaning is correct." }, { "alternative": "pre-commit by itself", "constraint": "pre-commit installs and runs hooks. It does not infer the semantic relationship between an enum, documentation, and a corresponding definition in another language. [2]", "response": "if-changed supplies a hook with explicit cross-file edit dependencies. [1]", "tradeoff": "The tools compose: pre-commit can run if-changed, while CI should check the revisions that matter for the team's merge process." } ], "boundaries": [ "A meaningless change to the dependent block can satisfy the diff requirement. Keep semantic tests for contracts that must agree, and prefer generation when one representation can be derived reliably from another. [1]", "Pick comparison revisions deliberately in CI. Annotations only help if the command sees the relevant changes, and suppressions deserve review because they bypass a declared dependency. Use named blocks when a whole-file change would be too weak a signal." ], "related": [ "sqlc-gen-sqlx", "connectrpc-sdk", "unfmt" ], "sources": [ { "label": "if-changed: motivating example, annotations, diff selection, and suppression", "path": "README.md", "url": "https://github.com/mathematic-inc/if-changed/blob/09319355c2ffc2684c38313f01f7a1b6983aada0/README.md" }, { "label": "pre-commit: hook installation and execution", "url": "https://pre-commit.com/" } ], "repository": { "name": "if-changed", "sha": "09319355c2ffc2684c38313f01f7a1b6983aada0", "language": "Rust", "description": "CLI tool that enforces synchronized changes across files using if-changed/then-change comment annotations in diffs", "license": "Apache-2.0" }, "categoryInfo": { "id": "tools", "label": "Developer tools", "short": "Tools", "description": "Make a small, recurring part of the editing and development workflow explicit." } }, { "slug": "vscode-latex", "order": 13, "category": "tools", "title": "LaTeX as a source-editing workflow", "summary": "Keep highlighting, formatting, linting, and snippets available without taking ownership of the build.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "TypeScript", "VS Code", "LaTeX" ], "abstract": "Some LaTeX users already have a build system and a preferred viewer. They need source-editing support in VS Code without adopting another build orchestration workflow. vscode-latex documents that narrower purpose and integrates established formatters and ChkTeX with the editor. [1]", "problem": [ "An integrated LaTeX environment often combines editing, compilation, preview, and document navigation. That is useful when the extension owns the document workflow. A developer who already runs a build through another system may instead want the usual source-editor services to coexist with that system. [1]", "Formatting and linting also need the configuration that belongs to the project. A per-editor default can conflict with a formatter's native configuration, particularly when a developer opens a file outside a workspace or works remotely." ], "design": [ "The extension supplies syntax highlighting and snippets, delegates linting to ChkTeX, and supports latexindent or tex-fmt for formatting. Remote and unsaved files are included in the documented editing workflow. Executable paths, timeouts, and lint delay are configurable. [1]", "Configuration lookup walks the file's ancestors and supports explicit paths. When it finds a native formatter configuration, that configuration takes precedence over editor column-limit and indentation settings. Keeping that precedence explicit prevents two competing definitions of formatting policy. [1]" ], "comparisons": [ { "alternative": "LaTeX Workshop", "constraint": "LaTeX Workshop deliberately provides an integrated environment with compilation, preview, completion, and more. A user whose build already lives elsewhere may not need that integrated workflow. [2]", "response": "vscode-latex confines its purpose to source editing and delegates formatting and linting to external tools. [1]", "tradeoff": "Choose LaTeX Workshop when integrated compilation, viewing, citations, or its broader IDE features are the desired experience." }, { "alternative": "Running latexindent and ChkTeX in a terminal", "constraint": "The tools can process files directly, but a terminal invocation does not itself register VS Code formatting actions, snippets, or inline editor diagnostics.", "response": "The extension adapts the tools to editor actions and applies a documented configuration lookup policy. [1]", "tradeoff": "Direct CLI use remains useful in CI and scripts. The extension does not replace those checks or the external executables." } ], "boundaries": [ "Install a supported formatter and ChkTeX, or use the extension's documented installation assistance. Native tool configuration can override editor defaults, so diagnose the discovered configuration before changing an editor setting. [1]", "This project does not compile or preview a TeX document. Pair it with an existing build and viewer workflow. That scope is the reason to choose it; it is not evidence that integrated LaTeX environments are defective." ], "related": [ "vscode-pdf", "vscode-api-linter" ], "sources": [ { "label": "vscode-latex: purpose, tools, configuration, and scope", "path": "README.md", "url": "https://github.com/mathematic-inc/vscode-latex/blob/b9e17e6532c97bd384f7ce4ac56dd31406ec146b/README.md" }, { "label": "LaTeX Workshop: integrated feature set", "url": "https://github.com/James-Yu/LaTeX-Workshop" } ], "repository": { "name": "vscode-latex", "sha": "b9e17e6532c97bd384f7ce4ac56dd31406ec146b", "language": "TypeScript", "description": "VS Code extension providing LaTeX syntax highlighting, formatting via latexindent, linting via ChkTeX, and snippets for developer-focused LaTeX editing", "license": "Apache-2.0" }, "categoryInfo": { "id": "tools", "label": "Developer tools", "short": "Tools", "description": "Make a small, recurring part of the editing and development workflow explicit." } }, { "slug": "vscode-pdf", "order": 14, "category": "tools", "title": "PDF viewing within the editor", "summary": "Host Mozilla PDF.js in a VS Code custom editor with an explicit document and webview lifecycle.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "TypeScript", "VS Code", "PDF.js" ], "abstract": "A generated PDF is often part of the same workspace as the source that produced it. vscode-pdf integrates Mozilla PDF.js into VS Code as a read-only custom editor. The project keeps the integration focused on viewing, with the renderer and the editor adapter carrying separate responsibilities. [1][2]", "problem": [ "Opening a PDF in a separate viewer breaks the editor's tab-level context. Embedding a renderer solves that workflow problem, but introduces integration work: resource URLs, document lifetime, webview configuration, and cleanup when a document closes.", "The README describes concerns with older marketplace viewers, including dependency age and lifecycle problems. It does not name affected extensions or provide a comparative test report. The defensible case for this project is its focused integration and inspectable implementation, rather than a blanket claim that competing viewers leak memory. [1]" ], "design": [ "The extension registers a VS Code read-only custom editor and hosts a bundled PDF.js viewer. It translates local resource paths into webview URLs, passes viewer settings through escaped configuration, and limits local resource roots. A content security policy specifies the resources the embedded viewer can use. [2]", "Document events and a webview collection connect document lifetime to the viewer. The provider disposes registered document listeners when the document is deleted. These are concrete lifecycle mechanisms; their presence does not prove the absence of every leak or refresh defect. [2]" ], "comparisons": [ { "alternative": "The standalone PDF.js viewer", "constraint": "PDF.js provides rendering and a browser viewer. It does not by itself register a VS Code custom editor or manage the surrounding editor document lifecycle. [3]", "response": "vscode-pdf supplies that integration and reuses the PDF.js rendering implementation. [1][2]", "tradeoff": "A standalone browser viewer is sufficient when editor integration is unnecessary and avoids installing a VS Code extension." }, { "alternative": "The viewer in a full LaTeX environment", "constraint": "An integrated LaTeX workflow couples PDF viewing with TeX-oriented build and navigation features. That is a broader installation than a user opening arbitrary PDFs may need. [4]", "response": "This extension's documented purpose is PDF viewing independent of the tool that produced the document. [1]", "tradeoff": "Use a LaTeX-specific environment when synchronized source navigation and integrated compilation are part of the task." } ], "boundaries": [ "The documented current viewer requires VS Code 1.95 or later. PDF.js compatibility and security maintenance remain ongoing dependencies, so use the renderer bundled with the extension version being evaluated. [1]", "This note does not certify the viewer as leak-free or faster than another extension. Repeated open/close behavior and document refresh need workload-specific testing. PDF content editing and TeX compilation fall outside the documented purpose." ], "related": [ "vscode-latex", "vscode-api-linter" ], "sources": [ { "label": "vscode-pdf: purpose, installation, and requirements", "path": "README.md", "url": "https://github.com/mathematic-inc/vscode-pdf/blob/1153346694f457bc7b4c73c9b0e95b629f02dc03/README.md" }, { "label": "PDF custom editor provider: resources, CSP, and lifecycle", "path": "src/pdf-viewer-provider.ts", "url": "https://github.com/mathematic-inc/vscode-pdf/blob/1153346694f457bc7b4c73c9b0e95b629f02dc03/src/pdf-viewer-provider.ts" }, { "label": "Mozilla PDF.js: project and browser viewer", "url": "https://mozilla.github.io/pdf.js/" }, { "label": "LaTeX Workshop: integrated PDF workflow", "url": "https://github.com/James-Yu/LaTeX-Workshop" } ], "repository": { "name": "vscode-pdf", "sha": "1153346694f457bc7b4c73c9b0e95b629f02dc03", "language": "JavaScript", "description": "Lightweight, up-to-date PDF viewer extension for VS Code powered by the latest pdf.js with no memory leaks or debouncing issues", "license": "Apache-2.0" }, "categoryInfo": { "id": "tools", "label": "Developer tools", "short": "Tools", "description": "Make a small, recurring part of the editing and development workflow explicit." } }, { "slug": "vscode-api-linter", "order": 15, "category": "tools", "title": "API design feedback where the schema is edited", "summary": "Run Google's API Linter on protobuf files and turn AIP violations into VS Code diagnostics.", "kind": "Implementation note", "rationale": "Engineering rationale", "tags": [ "TypeScript", "VS Code", "Protobuf" ], "abstract": "A protobuf file can compile while violating an API design convention. Google's API Linter checks Google API Improvement Proposals; vscode-api-linter brings those checks into the editing loop. The extension adapts the linter's output to inline diagnostics rather than defining a second set of API rules. [1][2]", "problem": [ "API design constraints extend beyond protobuf syntax. Teams following AIPs need feedback on the shape and conventions of their APIs, and a failure found only in CI arrives after the author has moved away from the edit. The useful intervention is to run the same rule engine near the source change. [2]", "A linter invoked outside the project's build environment can also fail to resolve imports or use the wrong configuration. An editor adapter needs a way to reach the project's command and include paths instead of assuming one global executable layout." ], "design": [ "The extension activates for proto and proto3 files, runs the linter on save, and offers a manual command. Diagnostics appear in the editor and the Problems panel. The rule implementation stays in the separately installed api-linter tool. [1]", "Configuration accepts a command array, so a project can invoke a wrapper such as a Bazel target. It also exposes the linter configuration file and proto import paths. This lets the editor invoke the project's chosen linter environment without embedding a build system into the extension. [1]" ], "comparisons": [ { "alternative": "api-linter in CI or a terminal", "constraint": "The CLI checks the right AIP rules, but a separate invocation requires the author to translate its output back to the editor and may delay feedback until the next check. [2]", "response": "The extension runs that engine on save and presents file-position diagnostics in VS Code. [1]", "tradeoff": "Keep CI checks for enforcement across all contributors. An editor extension only helps the developers who install and configure it." }, { "alternative": "Buf lint", "constraint": "Buf lint has its own rule sets for protobuf consistency. A team requiring Google's specific AIP rules needs the corresponding rule engine; generic protobuf linting is not a guarantee of AIP conformance. [2][3]", "response": "This adapter invokes Google's API Linter with its native configuration and import paths. [1]", "tradeoff": "Buf lint remains useful for its own checks. The tools can coexist; this extension does not replace Buf's schema tooling." } ], "boundaries": [ "The extension requires api-linter or a working custom command. Its save-triggered workflow should not be described as a complete check of every unsaved keystroke. Match import paths and configuration to CI to avoid contradictory diagnostics. [1]", "Use it when AIPs are an intentional API policy. A team using different conventions should choose rules that fit its contract rather than treating Google's style as a universal requirement." ], "related": [ "protovalidate-buffa", "connectrpc-sdk", "vscode-latex" ], "sources": [ { "label": "VS Code API Linter: triggers, diagnostics, and configuration", "path": "README.md", "url": "https://github.com/mathematic-inc/vscode-api-linter/blob/894c5eb96337fec3f1e2186e083451910696e80d/README.md" }, { "label": "Google API Linter: AIP rule engine", "url": "https://linter.aip.dev/" }, { "label": "Buf: protobuf lint rules and categories", "url": "https://buf.build/docs/lint/" } ], "repository": { "name": "vscode-api-linter", "sha": "894c5eb96337fec3f1e2186e083451910696e80d", "language": "Pkl", "description": "VS Code extension that lints Protobuf API files using Google's API Linter (api-linter) with full configuration support", "license": "Apache-2.0" }, "categoryInfo": { "id": "tools", "label": "Developer tools", "short": "Tools", "description": "Make a small, recurring part of the editing and development workflow explicit." } }, { "slug": "alyt", "order": 16, "category": "telemetry", "title": "One event contract across analytics providers", "summary": "Generate typed event methods from a schema and dispatch them through interchangeable provider plugins.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "TypeScript", "Analytics", "Code generation" ], "abstract": "An application event should retain its meaning when the team changes analytics providers. alyt separates the event contract from provider-specific calls. A YAML schema can generate typed tracking methods, while plugins send those calls to the analytics services selected by the application. [1]", "problem": [ "Calling provider SDKs throughout an application distributes vendor choices across product code. A migration then touches each call site. Event names and property names also become an informal contract: a misspelled event can silently create a second series instead of failing the build.", "A shared dispatcher solves the vendor coupling, but does not by itself define the application's event vocabulary. alyt combines the dispatcher with schema-driven TypeScript generation so product events have named methods and required argument types. [1]" ], "design": [ "The core client exposes track, identify, page, and reset operations and dispatches to registered plugins. Built-in adapters cover Google Analytics, PostHog, Mixpanel, Amplitude, Plausible, and Vercel Analytics. React and Svelte bindings pass a client through component context. Providers that do not implement a method are skipped. [1]", "The generator emits an event-name union, a parameter map, and tracker methods from YAML. Optional string hashing replaces the exact input with a SHA-256 digest before dispatch. Plugins can be added or removed at runtime, and individual calls can target selected providers. Events sent with no active plugins are dropped. [1]" ], "comparisons": [ { "alternative": "Direct provider SDK calls", "constraint": "Each call site chooses a vendor API and can spell events and properties independently. Switching vendors requires an adapter or a call-site migration.", "response": "The application calls generated event methods and chooses providers at client construction or through plugin changes. [1]", "tradeoff": "Direct SDK access is appropriate for provider-specific features that the shared interface does not express." }, { "alternative": "The analytics library by David Wells", "constraint": "analytics already provides a plugin architecture and track, page, and identify methods. A common dispatcher is therefore not a unique feature of alyt. The application still needs to choose how it defines its own event contract. [2]", "response": "alyt packages YAML-driven typed tracker generation with its provider adapters and framework bindings. [1]", "tradeoff": "Existing analytics installations may already have suitable event typing and plugins. Migration is worthwhile only if the schema and integration reduce actual maintenance work." } ], "boundaries": [ "Removing a plugin changes future dispatch through alyt; it is not a complete consent or data-deletion system for an independently loaded vendor SDK. Provider capabilities also differ, so the same call does not imply identical downstream semantics. [1]", "Unsalted SHA-256 hashing is deterministic and is not a claim of anonymization. The documented implementation does not trim, lowercase, or salt inputs. Treat that option as a defined transformation, and decide whether it satisfies the application's data policy. [1]" ], "related": [ "smapped-traces", "connectrpc-sdk" ], "sources": [ { "label": "alyt: event generation, dispatch, plugins, hashing, and lifecycle", "path": "README.md", "url": "https://github.com/mathematic-inc/alyt/blob/b0499500c30d801c697d22101acb2e6943dd8cd8/README.md" }, { "label": "analytics: plugin architecture and tracking API", "url": "https://github.com/DavidWells/analytics" } ], "repository": { "name": "alyt", "sha": "b0499500c30d801c697d22101acb2e6943dd8cd8", "language": "TypeScript", "description": "All-in-one analytics SDK for TypeScript — unified API for GA, PostHog, Mixpanel, Amplitude, Plausible, and Vercel Analytics with YAML codegen and React bindings", "license": "Apache-2.0" }, "categoryInfo": { "id": "telemetry", "label": "Telemetry", "short": "Telemetry", "description": "Preserve the meaning of events and errors across application boundaries." } }, { "slug": "smapped-traces", "order": 17, "category": "telemetry", "title": "Readable source locations in an OpenTelemetry pipeline", "summary": "Resolve minified exception stacks using build artifacts and debug IDs before exporting traces.", "kind": "Implementation note", "rationale": "Engineering rationale", "tags": [ "TypeScript", "OpenTelemetry", "Source maps" ], "abstract": "A minified stack trace identifies deployed JavaScript, not necessarily the source a developer needs to edit. smapped-traces adds source-map resolution to an OpenTelemetry pipeline. It connects build-time map collection, client-side debug IDs, and server-side resolution before forwarding the trace to a collector. [1]", "problem": [ "A browser exception may report a line and column in a compressed bundle. Keeping that string in telemetry preserves what the browser emitted, but does not reconstruct the original module location. The resolver needs the map corresponding to the exact deployed artifact.", "A URL alone can be an unreliable artifact identity when assets move or a path is reused between releases. The project uses debug IDs supplied by the build to associate stack frames with stored maps. Both the build and the trace-processing service must agree on that store and identity. [1]" ], "design": [ "Build integrations collect maps into a SourceMapStore. The client exporter enriches exception stacks from bundler debug-ID globals. A server handler reads the corresponding maps, resolves source locations, and forwards the resulting spans through the chosen OpenTelemetry exporter. Next.js and Vite integrations cover collection at build time. [1]", "Storage is an explicit interface, with local SQLite, an HTTP store adapter, and S3-compatible storage options. The handler uses standard Request and Response objects so it can run separately from the application framework. This makes symbolication a deployable part of the telemetry path instead of a responsibility left to the final dashboard. [1]" ], "comparisons": [ { "alternative": "Forwarding the original exception.stacktrace", "constraint": "OpenTelemetry defines a stacktrace attribute, but recording its string value does not itself load build artifacts or apply a JavaScript source map. [2]", "response": "smapped-traces adds artifact lookup and mapping before the selected exporter sends spans onward. [1]", "tradeoff": "Raw stacks remain useful when code is unminified or the downstream backend already performs the required resolution." }, { "alternative": "Sentry source-map uploads", "constraint": "Sentry already supports debug-ID-based source-map resolution. Its documented build integration uploads the artifacts for Sentry's processing pipeline. [3]", "response": "smapped-traces makes the resolver and store part of an application's OpenTelemetry path, allowing it to forward resolved traces to its chosen collector. [1]", "tradeoff": "A team already using Sentry's complete error workflow may have no reason to operate a separate resolver and artifact store." } ], "boundaries": [ "The map must exist and match the debug ID. Instrumentation cannot recover original source that was never collected or retained. Plan artifact retention around the releases that can still emit telemetry, and verify the build actually injects a supported debug-ID mapping. [1]", "The documented Next.js integration requires Next.js 16+, and the core targets OpenTelemetry SDK v2+. Treat map storage and any ingestion endpoint as application infrastructure with deliberate access controls. This library supplies resolution, not an entire observability backend." ], "related": [ "alyt", "bucket-cache-action" ], "sources": [ { "label": "smapped-traces: pipeline, packages, stores, debug IDs, and requirements", "path": "README.md", "url": "https://github.com/mathematic-inc/smapped-traces/blob/b811c4ad0195c66fec31e0851fed78881366e955/README.md" }, { "label": "OpenTelemetry: exception semantic conventions", "url": "https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/" }, { "label": "Sentry: debug-ID injection and source-map support", "url": "https://sentry.io/changelog/sentrys-release-github-action-has-improved-sourcemaps-support/" } ], "repository": { "name": "smapped-traces", "sha": "b811c4ad0195c66fec31e0851fed78881366e955", "language": "TypeScript", "description": "Source map resolution for OpenTelemetry — automatically resolves minified stack traces back to original source locations using debug IDs", "license": "Apache-2.0" }, "categoryInfo": { "id": "telemetry", "label": "Telemetry", "short": "Telemetry", "description": "Preserve the meaning of events and errors across application boundaries." } }, { "slug": "bucket-cache-action", "order": 18, "category": "infrastructure", "title": "Build caches with an explicit storage and save policy", "summary": "Restore from S3 or GCS, renew workload credentials, and decide whether to save using the job's final state.", "kind": "Implementation note", "rationale": "Documented motivation", "tags": [ "TypeScript", "GitHub Actions", "S3 / GCS" ], "abstract": "A build cache spans two moments: restore near the start of a job and save during cleanup. bucket-cache-action makes storage, credentials, and that final save decision explicit. It supports S3 and native Google Cloud Storage, including workload-identity renewal in each phase, while keeping the bucket's access and retention policies under the operator's control. [1]", "problem": [ "A job can restore dependencies with one cloud role, switch to a deployment role, and reach cleanup after the original credentials have expired or been removed. A cache implementation that relies only on the environment left behind at save time then depends on unrelated actions and their cleanup order. [1]", "A useful cache may also deserve saving even when a later, unrelated step fails. Conversely, an unsuccessful dependency installation should not populate the cache just because a broad cleanup condition runs. The action lets the operator express the relevant final outcome through save-if, including the result of a step that runs after restore. [1][2]" ], "design": [ "The main phase restores an exact key or the newest match under an ordered fallback prefix. It records the storage configuration for cleanup. The post phase reads the final save-if value but reuses the original provider, paths, and key. Exact hits, lookup-only requests, failed restores, and empty file sets do not trigger automatic uploads. Separate restore and save entry points support explicit workflow composition. [1][2]", "With native S3 OIDC or GCS Workload Identity Federation configured, each phase obtains its own credentials and the provider can refresh them during transfers. The action does not put credentials in restore-to-post state. Standard AWS and Google credential sources are also supported, but those sources must remain available during cleanup. [1]", "Writes are immutable: S3 uses conditional writes and GCS uses a generation precondition. Downloads pin their ranges to an object version and verify the full digest before extraction. Archives use the JavaScript tar package and Node 24's zstd implementation, avoiding a system tar or compression executable. [1]" ], "comparisons": [ { "alternative": "runs-on/cache", "constraint": "RunsOn's action already supports S3. Its documented behavior includes GitHub-cache fallback when no bucket is configured and discarding existing AWS environment credentials when RUNS_ON_RUNNER_NAME is set. Operators must account for those runner-specific choices. [3]", "response": "This project derives its layout from RunsOn but implements storage independently, requires an explicit bucket, and avoids runner discovery and environment-credential overrides. It also offers native GCS federation. [1]", "tradeoff": "RunsOn's automatic discovery and fallback are useful inside that ecosystem. This action deliberately requires more explicit provider and identity configuration." }, { "alternative": "actions/cache", "constraint": "The hosted cache applies GitHub's documented branch access rules, key lookup, and eviction policy. It does not expose an operator-selected S3 or GCS bucket as its storage backend. [4]", "response": "The action stores immutable objects in the selected bucket and lets the operator configure retention and namespace access through cloud policy. [1]", "tradeoff": "GitHub's managed cache handles its own trust scopes. Bucket users must enforce writer isolation with IAM; matching key names alone do not recreate those protections." }, { "alternative": "Separate cloud upload and download scripts", "constraint": "A file-transfer script leaves archive integrity, fallback lookup, post-job state, and credential lifetime to each workflow author.", "response": "The shared action supplies these mechanisms and evaluates the final save condition in its cleanup entry point. [1][2]", "tradeoff": "A simple script remains adequate for a small, fixed artifact with different lifecycle semantics. This action is for reusable cache objects, not general artifact publishing." } ], "boundaries": [ "An archive digest detects corruption, not a malicious authorized writer. Anyone who can populate a cache may influence executable dependencies read by a later job. Separate untrusted pull-request writers from trusted build or deployment caches through bucket and identity policy. [1]", "Buckets must already exist. Configure retention and abandoned-upload cleanup, and account for transfer cost and storage location. The action's cache format differs from RunsOn's, so a migration starts cold. Transfer timeouts do not cover local archive creation or extraction. The repository's emulator and workflow tests are described in its documentation; this catalog does not claim an independent cloud benchmark. [1]" ], "related": [ "if-changed", "smapped-traces" ], "sources": [ { "label": "Bucket cache: lifecycle, identity, storage, trust model, and origin", "path": "README.md", "url": "https://github.com/mathematic-inc/bucket-cache-action/blob/714dccf2713411d847f1919303d78bbd5c342f32/README.md" }, { "label": "Action manifest: inputs and post-job entry point", "path": "action.yml", "url": "https://github.com/mathematic-inc/bucket-cache-action/blob/714dccf2713411d847f1919303d78bbd5c342f32/action.yml" }, { "label": "runs-on/cache: S3 configuration, fallback, and credential behavior", "url": "https://github.com/runs-on/cache" }, { "label": "GitHub: cache access, key matching, and eviction", "url": "https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching" } ], "repository": { "name": "bucket-cache-action", "sha": "714dccf2713411d847f1919303d78bbd5c342f32", "language": "TypeScript", "description": "S3 and GCS caching for GitHub Actions with configurable post-job saves and renewable workload identity credentials", "license": "MIT" }, "categoryInfo": { "id": "infrastructure", "label": "Infrastructure & records", "short": "Infrastructure", "description": "The publication itself, repository infrastructure, and work at its earliest public stage." } }, { "slug": "noop", "order": 19, "category": "infrastructure", "title": "An intentionally minimal repository", "summary": "A no-operation repository with development configuration and no application implementation.", "kind": "Repository record", "rationale": "Scope record", "tags": [ "Pkl", "Repository" ], "abstract": "noop is an intentionally minimal entry in the organization. Its public description calls it a no-operation repository, and its README contains only the name. The reviewed tree includes development configuration and contribution machinery, but no application or library implementation. [1][2]", "problem": [ "A catalog can make an empty or administrative repository look like a product if every entry receives the same feature template. This record keeps the distinction explicit. The source does not document a user problem, adoption workflow, or substantive design motivation for noop. [2]", "The repository belongs in a complete organization index, but its existence is not evidence that Mathematic has shipped another tool. No additional origin story is inferred from its name." ], "design": [ "The reviewed tree contains a README, contribution guidance, mise and hk configuration, and GitHub maintenance workflows. These files describe repository maintenance; they do not expose an application API. [2]", "There is consequently no install command, runtime architecture, or performance result to report. Readers can inspect the pinned tree to see the exact scope of this record." ], "comparisons": [ { "alternative": "An implemented utility", "constraint": "An executable, library interface, or documented behavior is needed to compare functionality. This repository provides none at the reviewed revision. [2]", "response": "The catalog identifies it as a repository record and includes the source tree for inspection.", "tradeoff": "There is no supported capability claim on which to base an adoption decision." } ], "boundaries": [ "The project name does not imply a no-op package for a particular language, a reusable template, or a test fixture. Those roles would need documentation or code before this note could describe them.", "If the repository acquires an implementation, its scope record should be replaced with an explanation grounded in that implementation." ], "related": [ "site", "bucket-cache-action" ], "sources": [ { "label": "noop: public description", "url": "https://github.com/mathematic-inc/noop" }, { "label": "noop: reviewed repository tree", "tree": true, "url": "https://github.com/mathematic-inc/noop/tree/d36254281d8e9c128db53678c47f76de5c7d7ad9" } ], "repository": { "name": "noop", "sha": "d36254281d8e9c128db53678c47f76de5c7d7ad9", "language": "Pkl", "description": "A no-operation placeholder repository", "license": null }, "categoryInfo": { "id": "infrastructure", "label": "Infrastructure & records", "short": "Infrastructure", "description": "The publication itself, repository infrastructure, and work at its earliest public stage." } }, { "slug": "site", "order": 20, "category": "infrastructure", "title": "A catalog that publishes its reasoning", "summary": "A static, source-backed index of Mathematic's public repositories and the decisions behind them.", "kind": "Repository record", "rationale": "Documented motivation", "tags": [ "HTML", "CSS", "JavaScript" ], "abstract": "A repository list shows what an organization has published, but rarely explains how the projects relate or when one is worth adopting. This site collects those explanations in a consistent reading format. Each project note states a problem, describes the mechanism, compares relevant alternatives, and records the boundary of its claims.", "problem": [ "GitHub organizes each repository around its own code and README. A reader comparing projects must first find the repositories, then reconstruct their purposes and alternatives from documents written at different times. A short organization description cannot carry that analysis for every project.", "This catalog gives readers a second entry point: search by the problem, technology, or alternative, then follow a note into its primary sources. It includes the small repository records so the public inventory remains complete without presenting setup files as implemented products." ], "design": [ "The site generates static HTML from one structured document per repository. The index and article pages exist before browser JavaScript runs. Search and category filters progressively enhance the index; article sections, source references, and related-project links remain ordinary links. [1]", "The build validates repository coverage, unique identifiers, references, and related-project destinations. Article references to Mathematic source use recorded commits, except this living site record. An explicit inventory check reports new or removed public repositories so a maintainer can review their content rather than publishing generated claims automatically. [1]" ], "comparisons": [ { "alternative": "The GitHub organization repository list", "constraint": "The native list is authoritative for current repositories, but short descriptions cannot provide a consistent problem, mechanism, alternative, and tradeoff analysis for each one.", "response": "The catalog adds authored notes and citations while linking back to the original repositories.", "tradeoff": "The catalog is a reviewed edition, not a live substitute for GitHub's inventory. It needs content review as projects and alternatives change." }, { "alternative": "A database-backed content site", "constraint": "A runtime service adds hosting and operational requirements to a publication whose main content is versioned text.", "response": "The site compiles that text into static pages and deploys them through GitHub Pages. [1][2]", "tradeoff": "GitHub Pages serves static assets. Features that require private data, authentication, or server-side processing need a different architecture." } ], "boundaries": [ "These are engineering notes, not peer-reviewed papers. The visual format supports careful reading; it does not imply external academic endorsement. Documented historical motivations and engineering interpretations are labelled separately.", "A named alternative is compared for a particular requirement, not ranked as universally better or worse. Numerical results are attributed to their source and context. Claims should change when the evidence changes." ], "related": [ "noop", "if-changed" ], "sources": [ { "label": "This site: source, maintenance, and verification", "path": "README.md", "url": "https://github.com/mathematic-inc/site/blob/main/README.md" }, { "label": "GitHub Pages: static publishing with custom workflows", "url": "https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages" } ], "repository": { "name": "site", "sha": "main", "language": "HTML", "description": "Mathematic Inc. research notes and repository catalog", "license": "Apache-2.0" }, "categoryInfo": { "id": "infrastructure", "label": "Infrastructure & records", "short": "Infrastructure", "description": "The publication itself, repository infrastructure, and work at its earliest public stage." } } ] }