@usenarrator/node

import { changedFilesFromGit, createNodeNarrator, findRepoRoot, gitAttributeSkips, listRepoFiles, loadDependencyIndex } from "@usenarrator/node";

This package wires @usenarrator/core, @usenarrator/lang-ts with the native oxc parser, and @usenarrator/locale-en together for server-side use. It depends on oxc-parser, so it isn’t meant for browsers. See Embedding in your app for the browser setup.

createNodeNarrator

function createNodeNarrator(options?: {
  plugins?: (TsPlugin | TsPlugin[])[];
  locale?: Locale;
  dependencies?: false | DependencyIndex;
}): Narrator;

(TsPlugin | TsPlugin[])[]

Library and codebase plugins, as for typescript().

Locale

The output language. Defaults to English.

false | DependencyIndex

Defaults to loadDependencyIndex({ root: findRepoRoot(process.cwd()) }), the manifests of the git checkout around the working directory. Pass your own index for another repository, or false to rely on imports alone.

changedFilesFromGit

function changedFilesFromGit(options: {
  root: string;
  range: string;
  includeGenerated?: boolean;
  accepts?: (path: string) => boolean;
}): ChangedFile[];

The files changed in a git range, with both sides’ sources, ready for narrator.diffFiles or narrator.diff. This is what narrator diff uses.

string

required

base..head compares two revisions, base...head compares head with its merge base, and base alone compares a revision with the working tree. An unknown revision throws an error that names it.

boolean

By default, files that .gitattributes marks linguist-generated or linguist-vendored, and files whose path shows they are build output, dependencies or lockfiles, come back with skipped set and empty sources, so they are never read. Minified content is caught later by the narrator. Pass true to read everything.

(path: string) => boolean

Drops other paths before anything is read, for example narrator.canNarrate.

All sources are read through one git cat-file --batch process, so large ranges stay fast.

import { renderDiffText } from "@usenarrator/core";
import { changedFilesFromGit, createNodeNarrator, findRepoRoot } from "@usenarrator/node";

const narrator = createNodeNarrator();
const root = findRepoRoot(process.cwd());
const files = changedFilesFromGit({ root, range: "main...HEAD", accepts: narrator.canNarrate });
console.log(renderDiffText({ files: narrator.diffFiles(files) }));

gitAttributeSkips

function gitAttributeSkips(options: { root: string; paths: string[] }): Map<string, SkipReason>;

The paths that .gitattributes marks linguist-generated (reason generated) or linguist-vendored (reason vendored). Paths are relative to root. Outside git, the map is empty.

loadDependencyIndex

function loadDependencyIndex(options: { root: string; readers?: ManifestReader[] }): DependencyIndex;

A dependency index over every manifest in the repository at root. Files are listed with listRepoFiles, and manifests are read the first time the index is used. File paths passed to forFile may be absolute or relative to root.

findRepoRoot

function findRepoRoot(dir: string, readers?: ManifestReader[]): string;

The nearest enclosing directory with a .git folder. Outside git, the outermost ancestor that holds a manifest, or dir itself.

listRepoFiles

function listRepoFiles(root: string): string[];

Every file in the repository, relative to root. It uses git ls-files, which respects .gitignore and includes untracked files. Outside git it falls back to a directory walk four levels deep that skips node_modules, dist, hidden folders and similar.

Packages

Tools

@usenarrator/node

createNodeNarrator

changedFilesFromGit

gitAttributeSkips

loadDependencyIndex

findRepoRoot

listRepoFiles

​createNodeNarrator

​changedFilesFromGit

​gitAttributeSkips

​loadDependencyIndex

​findRepoRoot

​listRepoFiles

createNodeNarrator

changedFilesFromGit

gitAttributeSkips

loadDependencyIndex

findRepoRoot

listRepoFiles