TypeScript SDK Reference

npm install @adversarylabs/sdk@^0.1.5

import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { pathToFileURL } from "node:url";
import { Adversary, Severity } from "@adversarylabs/sdk";

const app = new Adversary({
  name: "adversarylabs/comment-sentences",
  review: { minimumConfidence: "medium" },
});

app.defineRule({
  id: "comments.complete-sentence",
  category: "code-style",
  defaultSeverity: Severity.Info,
  defaultConfidence: "high",
  groupBy: ["ruleId", "subject"],
  aggregate(observations) {
    return {
      title: observations.length === 1
        ? "Comment is a complete sentence"
        : "Comments contain complete sentences",
      summary: observations.length + " comments are written as complete sentences.",
      recommendation:
        "Keep complete-sentence comments only when they explain non-obvious intent.",
    };
  },
});

app.rule("comments.complete-sentence", async (ctx) => {
  for (const file of await ctx.rglob("*.ts")) {
    const content = await readFile(join(ctx.repoPath, file), "utf8");
    content.split(/\r?\n/).forEach((line, index) => {
      const comment = line.match(/^\s*\/\/\s+(.+)/)?.[1];
      if (comment && /^[A-Z][^.!?]*[.!?]$/.test(comment)) {
        ctx.observe({
          ruleId: "comments.complete-sentence",
          subject: file,
          title: "Comment is a complete sentence",
          location: { file, line: index + 1 },
          evidence: { comment },
        });
      }
    });
  }
});

export default app;

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  await app.runFromEnvironment();
}

const app = new Adversary({
  name: "adversarylabs/example",
  version: "0.1.0",
  review: {
    minimumConfidence: "medium",
    maximumFindings: 10,
    includeInformational: false,
  },
});

ctx.repoPath
ctx.summary.files_scanned
ctx.cache
ctx.relpath(path)
ctx.glob(pattern)
ctx.rglob(pattern)
ctx.observe(observation)
ctx.finding(finding)
ctx.review.assessment(assessment)
ctx.review.positive(note)
ctx.review.observe(note)
ctx.review.score(score)
ctx.review.opinion(opinion)

ctx.observe({
  ruleId: "comments.complete-sentence",
  subject: "src/index.ts",
  groupKey: "complete-sentence-comments",
  title: "Comment is a complete sentence",
  confidence: 0.95,
  location: { file: "src/index.ts", line: 3 },
  evidence: { comment: "This comment explains intent." },
  recommendation: {
    summary: "Keep comments only when they explain non-obvious intent.",
  },
});

ctx.finding({
  ruleId: "comments.complete-sentence",
  title: "Comments contain complete sentences",
  category: "code-style",
  severity: "low",
  confidence: "high",
  summary: "Three comments are written as complete sentences.",
  evidence: [
    {
      location: { file: "src/index.ts", line: 3 },
      message: "Explains parser intent.",
      data: { parser: "line-comment" },
    },
  ],
  recommendation:
    "Keep complete-sentence comments only when they explain non-obvious intent.",
  remediation: { complexity: "trivial" },
});

ctx.review.assessment({
  risk: "low",
  summary: "The code is easy to follow. One small style issue remains.",
});

ctx.review.positive({
  key: "intentional-comments",
  summary: "Several comments explain intent rather than restating code.",
  evidence: [{ location: { file: "src/index.ts", line: 3 } }],
});

ctx.review.opinion({
  ship: true,
  summary: "I would ship this as-is.",
});

// Programmatic: explicit input, no environment overrides or file writes.
const result = await app.run({
  input: { source: { path: "/repo" } },
  includeSuppressed: true,
});

// CLI/container: reads runtime environment and writes the run envelope.
await app.runFromEnvironment();

const result = await app.run({
  input: { source: { path: "/repo" } },
});

await new TerminalRenderer().render(result);
await new JsonRenderer().render(result);

name: comment-sentences
version: 0.1.0
description: Reports complete-sentence TypeScript comments.

triggers:
  manual: true
  files_changed:
    - "*.ts"
    - "**/*.ts"

runtime:
  name: node
  version: "22"
  command:
    - dist/index.js

permissions:
  enforcement: advisory
  filesystem:
    read:
      - .
    write: []
  network: false
  model: false
  environment:
    allow: []

findings:
  format: adversary.review.v1

name: lang/go
version: 0.0.7
description: Go language pack — specialists under one entrypoint.

# Composition: CLI expands uses transitively when you run this package.
uses:
  - name: go/concurrency
  - name: go/security
    version: "0.0.13"   # optional exact tag (no ^/~ ranges yet)
  - path: ../local-leaf # package-relative; exclusive with name

runtime:
  name: node
  version: "22"
  command: [dist/index.js]

findings:
  format: adversary.review.v1

# Persona entrypoint: voice here, depth from uses
name: local/torvalds-adversary
uses:
  - name: lang/go                 # may expand further
  - name: review/engineering
  - name: review/complexity
  - name: security/secrets
# agent/voice.md (+ section banks) own GitHub rewrite voice for this entry

# Review voice: blunt maintainer

## Core voice
- Lead with the defect; explain the mechanism.
- Short declarative sentences. No praise sandwiches.

## Length
- 2–5 tight sentences. Stay under ~1,200 characters.

## Example maintainer comments (style only)
These are style few-shots only — re-ground in current evidence; never emit a quote unchanged.

### Ship / OK
> Looks all reasonable to me

### Defects / correctness
> This looks wrong to me. The length is just mb.len.

## Output
Return only the GitHub PR comment body in Markdown.

{
  "protocolVersion": 1,
  "result": {
    "schemaVersion": "adversary.review.v1",
    "adversary": { "name": "adversarylabs/comment-sentences" },
    "target": { "repository": "/repo", "filesScanned": 4 },
    "positives": [],
    "observations": [],
    "findings": [],
    "suppressed": { "findings": 0 }
  }
}