Adding a source language

​

The contract

interface SourceLanguage {
  id: string;
  handles(path: string): boolean;
  ecosystems?: string[];
  create(locale: Locale, ctx?: { dependencies?: (path: string) => Dependencies }): FileNarrator;
}

interface FileNarrator {
  narrate(src: string, path: string): FileNarration;
  units(src: string, path: string): Unit[];
  problems?(): NarrationProblem[];
}

type FileNarration = { lines: Line[]; errors: number; stats: NarrationStats; problems?: NarrationProblem[] };
type NarrationStats = { nodes: number; fallbacks: number; fallbackTypes: Record<string, number>; ruleErrors?: RuleError[] };
type RuleError = { plugin: string; rule: string; message: string; count: number; line?: number };
type Unit = { key: string; title: string; start: number; end: number; lines: Line[] };

• handles decides by path. createNarrator uses the first language that handles a file, and narrator.diff skips files no language handles.
• ecosystems names the dependency registries this language imports from, such as ["npm"] for TypeScript or ["crates"] for Rust. The narrator uses it to pick which manifests apply. See Dependency detection.
• create is called once per file, so the file narrator it returns can keep per-file state, such as which imports the file has. When the narrator was given a dependency index, ctx.dependencies(path) returns the package dependencies (name to version range) for a file in this language’s ecosystems.
• narrate returns lines, the number of parse errors, and stats. Count a fallback each time you show raw code instead of English, so tools like bun stress can measure coverage.
• problems is optional. Return syntax errors and failed rules from narrate as problems, and from the latest units call through problems(), so diffs can report them. You don’t need to catch your own crashes: the narrator turns an exception into a narrator problem for that file and carries on with the others.
• units splits the file into matchable pieces for diffs. Use the declaration name as the key and keep it stable across edits. See Units and diffs.

​

Lines

type LineKind = "head" | "stmt" | "note" | "bullet" | "raw" | "blank";
type Line = { d: number; text: string; start: number; end: number; kind: LineKind };

​

Phrases

​

Registering it

const narrator = createNarrator({
  languages: [typescript({ parser: oxcParser }), python()],
  locale: en,
});