pr-narrator-mcp: Instructions file for GitHub Copilot

TypeScript Review Rules

Type Safety

• Strict null checks — no ! non-null assertions without a comment justifying why it is safe
• All function parameters must be explicitly typed (no implicit any)
• Use unknown instead of any — narrow with type guards
• Flag as any casts — use as Record<string, unknown> or proper types instead
• Async functions must have explicit Promise<T> return types on public APIs
• Use optional chaining (?.) and nullish coalescing (??) over manual null checks

// Avoid
const name = obj && obj.user && obj.user.name;

// Prefer
const name = obj?.user?.name;

Zod Type Derivation

• Use z.infer<typeof schema> for deriving types from Zod schemas — never duplicate types manually
• Tool input types must always be derived from the tool's Zod schema

// Avoid: manual type that duplicates the Zod schema
interface MyInput {
  repoPath?: string;
  summary?: string;
}

// Prefer: derive from Zod
export const mySchema = z.object({
  repoPath: z.string().optional().describe("Path to the git repository"),
  summary: z.string().optional().describe("Summary text"),
});
export type MyInput = z.infer<typeof mySchema>;

Interface vs Type

• Use interface for object shapes, especially tool result types
• Use type only for unions, intersections, or mapped types
• Tool results must use interface with Result suffix

// Prefer: interface for result objects
export interface GenerateCommitMessageResult {
  success: boolean;
  title: string;
  errors: string[];
}

// Acceptable: type for unions
type PrefixStyle = "capitalized" | "bracketed";

Error Handling in Tools

• Tool handlers must never throw — return structured error results
• Use try/catch internally and populate the errors array

// Avoid: throwing in a tool handler
export async function myTool(input: MyInput, config: Config) {
  const data = getSomething();
  if (!data) throw new Error("Not found");
  return data;
}

// Prefer: return structured error
export async function myTool(input: MyInput, config: Config): Promise<MyResult> {
  const data = getSomething();
  if (!data) {
    return { success: false, errors: ["Not found"], data: null };
  }
  return { success: true, data, errors: [] };
}