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 execution. The available fields depend on the report's scope.

Method-scope context

Present when scope: "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).

Workflow-scope context

Present when scope: "workflow". Includes the method-scope fields above plus the following:

Field	Type	Description
`workflowId`	`string`	The workflow definition ID.
`workflowRunId`	`string`	The run ID for this execution.
`workflowName`	`string`	The workflow name.
`workflowStatus`	`"succeeded" \| "failed"`	Final status of the workflow run.
`inputs`	`Record<string, unknown>`	The workflow invocation inputs.
`stepExecutions`	`StepExecution[]`	Per-step execution details (see below).

`StepExecution`

Field	Type	Description
`stepName`	`string`	Name of the step within the workflow.
`modelName`	`string`	The model instance the step executed against.
`methodName`	`string`	The method that ran for this step.
`status`	`string`	Step outcome (e.g. `"succeeded"`, `"failed"`).

`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`.

Examples

Method-scope report

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 },
    };
  },
};

Workflow-scope report

A report that summarizes step outcomes after a workflow run:

export const report = {
  name: "@mycollective/step-summary",
  description: "Summarize workflow step outcomes",
  scope: "workflow" as const,
  labels: ["summary"],

  async execute(context) {
    const steps = context.stepExecutions;
    const succeeded = steps.filter((s) => s.status === "succeeded").length;
    const failed = steps.filter((s) => s.status === "failed").length;

    const rows = steps
      .map(
        (s) =>
          `| ${s.stepName} | ${s.modelName} → ${s.methodName} | ${s.status} |`,
      )
      .join("\n");

    return {
      markdown: [
        `## ${context.workflowName} — ${context.workflowStatus}`,
        "",
        `${succeeded} succeeded, ${failed} failed out of ${steps.length} steps.`,
        "",
        "| Step | Model | Status |",
        "| ---- | ----- | ------ |",
        rows,
      ].join("\n"),
      json: {
        workflowName: context.workflowName,
        status: context.workflowStatus,
        inputs: context.inputs,
        totalSteps: steps.length,
        succeeded,
        failed,
      },
    };
  },
};

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.