Skip to main content

REPORT

A report is a TypeScript module that analyzes the output of a model method and produces a markdown summary with structured JSON data. Reports run automatically after method execution (or on demand) and their output is stored alongside the method's data. The file lives in extensions/reports/ and exports a report object.

Export Shape

export const report = {
  name: "@mycollective/my-report",
  description: "Analyze method output for compliance",
  scope: "method",
  labels: ["compliance", "audit"],
  async execute(context: ReportContext): Promise<ReportOutput> {
    // analyze data, return report
  },
};

Fields

Field Type Required Description
name string Yes Unique identifier in @collective/name format.
description string Yes What the report analyzes.
scope "method" | "workflow" | "model" Yes When the report runs (see Scoping below).
labels string[] No Tags for filtering which reports to run.
execute (context: ReportContext) => Promise<ReportOutput> Yes Implementation function.

ReportContext

Passed to execute with the data produced by the preceding method.

Field Type Description
modelType string The model's type identifier.
modelId string Instance ID of the model definition.
methodName string Name of the method that produced the data.
dataHandles DataHandle[] Handles to the outputs produced by the method.
dataRepository DataRepository Read access to output content (see below).

DataHandle

Field Type Description
specName string Name of the resource or file spec.
name string Instance name of the output.
version string Version identifier.
tags Record<string, string> (optional) Output tags.

DataRepository

Method Signature Description
getContent (type, modelId, dataName, version) => Promise<Uint8Array | null> Read the raw content of a data output. Returns null if not found.

ReportOutput

Returned by execute.

Field Type Description
markdown string Markdown-formatted report text for display.
json Record<string, unknown> Structured data for programmatic consumption.

Scoping

The scope field controls when a report executes:

Scope Runs after
method Each individual method execution.
workflow Each workflow run completion.
model On-demand via swamp report run.

Example

A report that scans resource output for deprecated API versions:

export const report = {
  name: "@mycollective/api-deprecation",
  description: "Flag resources using deprecated API versions",
  scope: "method",
  labels: ["compliance"],

  async execute(context) {
    const deprecated: string[] = [];

    for (const handle of context.dataHandles) {
      const content = await context.dataRepository.getContent(
        context.modelType,
        context.modelId,
        handle.name,
        handle.version,
      );
      if (!content) continue;

      const data = JSON.parse(new TextDecoder().decode(content));
      if (data.apiVersion && data.apiVersion.startsWith("v1")) {
        deprecated.push(`${handle.name}: uses ${data.apiVersion}`);
      }
    }

    const pass = deprecated.length === 0;

    return {
      markdown: pass
        ? "No deprecated API versions found."
        : `## Deprecated APIs\n\n${deprecated.map((d) => `- ${d}`).join("\n")}`,
      json: { pass, deprecated },
    };
  },
};

Packaging

Declare the report in your extension's manifest:

reports:
  - api_deprecation.ts

The file path is relative to the extensions/reports/ directory within the extension root.

← PreviousModelNext →Data Querying