urtext 0.1.0

package/dist/analyze/index.js

@@ -0,0 +1,52 @@
+import { blastRadiusAnalyzer } from "./blast-radius.js";
+import { citationsAnalyzer } from "./citations.js";
+import { effectsAnalyzer } from "./effects.js";
+import { guardsAnalyzer } from "./guards.js";
+import { surfaceAnalyzer } from "./surface.js";
+export { detectEffects, effectsAnalyzer } from "./effects.js";
+export { collectGuards, guardsAnalyzer } from "./guards.js";
+export { exportedSignatures, surfaceAnalyzer } from "./surface.js";
+export { countReferences, blastRadiusAnalyzer } from "./blast-radius.js";
+export { citationsAnalyzer, makeCitationsAnalyzer } from "./citations.js";
+export { createProgramAt, listTypeScriptFilesAt } from "./program.js";
+export { makeFact } from "./fact.js";
+export const ANALYZERS = [
+    effectsAnalyzer,
+    guardsAnalyzer,
+    surfaceAnalyzer,
+    blastRadiusAnalyzer,
+    citationsAnalyzer,
+];
+/**
+ * Runs every analyzer and returns the facts from the ones that succeeded.
+ *
+ * `Promise.allSettled`, not `Promise.all`: one compiler-API or git failure
+ * used to discard every analyzer's facts and exit non-zero, so a single
+ * unreadable revision turned a review with three real findings into no
+ * review at all. A degraded review beats no review — but only if the
+ * degradation is visible, which is what `onFailure` is for. Callers that
+ * pass no handler get the facts and no indication anything was lost, so
+ * anything user-facing should pass one.
+ */
+export async function runAnalyzers(changeset, ctx, analyzers = ANALYZERS, onFailure) {
+    const results = await Promise.allSettled(analyzers.map((a) => a(changeset, ctx)));
+    const facts = [];
+    results.forEach((result, i) => {
+        if (result.status === "fulfilled") {
+            facts.push(...result.value);
+            return;
+        }
+        const reason = result.reason;
+        onFailure?.({
+            // An anonymous arrow assigned to a typed const takes the binding's
+            // name (NamedEvaluation of the variable declaration), so `.name` is
+            // "surfaceAnalyzer" rather than "" for every analyzer declared that
+            // way. The one a factory returns states its name outright instead,
+            // because a transform that renames shadowed bindings would otherwise
+            // rewrite it — see `makeCitationsAnalyzer` in `./citations.ts`.
+            analyzer: analyzers[i].name || `analyzer #${i + 1}`,
+            message: reason instanceof Error ? reason.message : String(reason),
+        });
+    });
+    return facts;
+}

package/dist/analyze/program.d.ts

@@ -0,0 +1,15 @@
+import ts from "typescript";
+/**
+ * Repo-relative TypeScript source paths at a revision. Declaration files are
+ * excluded: they contribute no analyzable implementation and inflate the
+ * program.
+ */
+export declare function listTypeScriptFilesAt(root: string, rev: string): Promise<string[]>;
+/**
+ * Build a program over a git revision. For WORKTREE this is equivalent to
+ * reading from disk; for a commit, file contents come from git, so a
+ * "before" side can be type-checked without touching the working tree.
+ */
+export declare function createProgramAt(root: string, rev: string): Promise<ts.Program>;
+/** Repo-relative path for a program source file. */
+export declare function relativePathOf(root: string, sf: ts.SourceFile): string;

package/dist/analyze/program.js

@@ -0,0 +1,229 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import ts from "typescript";
+import { git, readAt } from "../extract/git.js";
+import { isTypeScriptFile } from "../extract/symbols.js";
+import { WORKTREE } from "../types.js";
+/**
+ * Any TypeScript file at all, declaration files included — the read-into-the-
+ * host filter, wider than `isTypeScriptFile` (which picks program *roots*):
+ * an ambient `.d.ts` is part of a revision's type surface and must stay
+ * readable and resolvable without being a root. All four implementation
+ * extensions and all three declaration flavours end in one of these.
+ */
+const TS_SOURCE = /\.(?:ts|tsx|mts|cts)$/;
+const CASE_SENSITIVE = ts.sys.useCaseSensitiveFileNames;
+/**
+ * Key for a path that is stable across separators and filesystem casing.
+ *
+ * TypeScript normalizes every path it hands the host to forward slashes, so
+ * a map keyed on Windows `join()` output would never be hit and every source
+ * file would come back undefined. One shared implementation, because the
+ * host and the map builder disagreeing is precisely the kind of silent miss
+ * that would leave the program empty rather than failing.
+ */
+function canonicalPath(root, fileName) {
+    const abs = isAbsolute(fileName) ? fileName : resolve(root, fileName);
+    const slashed = abs.split("\\").join("/").replace(/\/+$/, "");
+    return CASE_SENSITIVE ? slashed : slashed.toLowerCase();
+}
+/**
+ * Every repo-relative path tracked at a revision, minus anything under
+ * node_modules: an installed dependency is toolchain, is served from disk by
+ * the compiler host, and is not a function of the revision even on the rare
+ * repository that commits it.
+ */
+async function listPathsAt(root, rev) {
+    const out = rev === WORKTREE
+        ? await git(["ls-files", "--cached", "--others", "--exclude-standard"], root)
+        : await git(["ls-tree", "-r", "--name-only", rev], root);
+    const seen = new Set();
+    for (const line of out.split("\n")) {
+        const path = line.trim();
+        if (!path || path.split("/").includes("node_modules"))
+            continue;
+        seen.add(path);
+    }
+    return [...seen];
+}
+/**
+ * Repo-relative TypeScript source paths at a revision. Declaration files are
+ * excluded: they contribute no analyzable implementation and inflate the
+ * program.
+ */
+export async function listTypeScriptFilesAt(root, rev) {
+    return (await listPathsAt(root, rev)).filter(isTypeScriptFile);
+}
+/** The repo's compiler options, or defaults when it has no usable tsconfig. */
+function compilerOptions(root) {
+    const fallback = {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        strict: true,
+        skipLibCheck: true,
+        noEmit: true,
+        allowJs: false,
+    };
+    // Deliberately not ts.findConfigFile: that walks up past the repository
+    // root and would silently adopt an unrelated ancestor's tsconfig (a real
+    // hazard for repos created under a temp or home directory).
+    const configPath = join(root, "tsconfig.json");
+    if (!ts.sys.fileExists(configPath))
+        return fallback;
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error || !read.config)
+        return fallback;
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, root);
+    // We type-check, never build. Emit-shaped options are dropped rather than
+    // merely overridden so that `composite`/`incremental` cannot make the
+    // program try to write or read a build-info file.
+    const { composite: _composite, incremental: _incremental, tsBuildInfoFile: _tsBuildInfoFile, ...options } = parsed.options;
+    return { ...options, noEmit: true, skipLibCheck: true };
+}
+/**
+ * A CompilerHost whose repository files come from a git revision rather than
+ * disk. Library files (lib.es2022.d.ts and friends) and anything under
+ * node_modules still come from the filesystem — they are part of the
+ * toolchain, not the repository under review.
+ */
+function hostFor(root, contents, directories) {
+    const canonicalRoot = canonical(root);
+    return {
+        getSourceFile(fileName, languageVersion) {
+            const text = contents.get(canonical(fileName)) ?? readToolchainFile(fileName);
+            if (text === undefined)
+                return undefined;
+            return ts.createSourceFile(fileName, text, languageVersion, true);
+        },
+        getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+        writeFile: () => undefined,
+        getCurrentDirectory: () => root,
+        getCanonicalFileName: (f) => (CASE_SENSITIVE ? f : f.toLowerCase()),
+        useCaseSensitiveFileNames: () => CASE_SENSITIVE,
+        getNewLine: () => "\n",
+        fileExists(f) {
+            if (isSubject(f))
+                return contents.has(canonical(f));
+            return ts.sys.fileExists(f);
+        },
+        readFile(f) {
+            if (isSubject(f))
+                return contents.get(canonical(f));
+            return ts.sys.readFile(f);
+        },
+        directoryExists(d) {
+            if (isSubject(d))
+                return directories.has(canonical(d));
+            return ts.sys.directoryExists(d);
+        },
+        getDirectories(d) {
+            if (!isSubject(d))
+                return ts.sys.getDirectories(d);
+            const prefix = `${canonical(d)}/`;
+            const names = new Set();
+            for (const dir of directories) {
+                if (!dir.startsWith(prefix))
+                    continue;
+                const rest = dir.slice(prefix.length);
+                if (rest && !rest.includes("/"))
+                    names.add(rest);
+            }
+            return [...names];
+        },
+    };
+    function canonical(fileName) {
+        return canonicalPath(root, fileName);
+    }
+    /**
+     * True for paths that belong to the repository under review, i.e. whose
+     * content is a function of the revision. Dependencies are excluded: an
+     * installed package is toolchain, and its tree is not stored in git.
+     */
+    function isSubject(fileName) {
+        const path = canonical(fileName);
+        if (path === canonicalRoot)
+            return false; // the root itself always exists
+        if (!path.startsWith(`${canonicalRoot}/`))
+            return false;
+        return !path
+            .slice(canonicalRoot.length + 1)
+            .split("/")
+            .includes("node_modules");
+    }
+    /**
+     * Read a file that is *not* subject to the revision. A repository file
+     * absent from `contents` genuinely does not exist at this revision and must
+     * NOT be served from the working tree — that is exactly how a "before"
+     * program would silently type-check current code and report confident
+     * nonsense under a `verified` badge.
+     */
+    function readToolchainFile(fileName) {
+        if (isSubject(fileName))
+            return undefined;
+        const abs = isAbsolute(fileName) ? fileName : resolve(root, fileName);
+        try {
+            return readFileSync(abs, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * Build a program over a git revision. For WORKTREE this is equivalent to
+ * reading from disk; for a commit, file contents come from git, so a
+ * "before" side can be type-checked without touching the working tree.
+ */
+export async function createProgramAt(root, rev) {
+    const options = compilerOptions(root);
+    // Sources, plus the manifests module resolution consults. A package.json
+    // is what tells the compiler whether a directory is ESM or CommonJS under
+    // node16/nodenext; without it every relative import in such a repo is
+    // resolved under the wrong module format, which is the silent kind of
+    // wrongness this host exists to avoid. They come from the revision like
+    // any other repository file.
+    const paths = (await listPathsAt(root, rev)).filter((p) => TS_SOURCE.test(p) || p === "package.json" || p.endsWith("/package.json"));
+    // Reading a commit's files means one `git show` per file. Done serially
+    // that is a subprocess round-trip per file and dominates the build on any
+    // sizeable repository, so read a few at a time — but collect into a
+    // position-indexed array, because the program's root order must not depend
+    // on which read happened to finish first.
+    const texts = new Array(paths.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(8, paths.length) }, async () => {
+        while (cursor < paths.length) {
+            const i = cursor++;
+            texts[i] = await readAt(root, rev, paths[i]);
+        }
+    });
+    await Promise.all(workers);
+    const contents = new Map();
+    const directories = new Set();
+    const rootNames = [];
+    for (const [i, p] of paths.entries()) {
+        const text = texts[i];
+        if (text === null)
+            continue; // absent at this revision; not an error here
+        const abs = join(root, p);
+        const key = canonicalPath(root, abs);
+        contents.set(key, text);
+        // Only implementation sources are program roots. Declaration files and
+        // manifests stay readable and resolvable — an ambient .d.ts is part of
+        // the revision's type surface — without inflating the program.
+        if (isTypeScriptFile(p))
+            rootNames.push(abs);
+        const segments = key.split("/");
+        for (let i = segments.length - 1; i > 0; i--) {
+            const dir = segments.slice(0, i).join("/");
+            if (directories.has(dir))
+                break;
+            directories.add(dir);
+        }
+    }
+    return ts.createProgram(rootNames, options, hostFor(root, contents, directories));
+}
+/** Repo-relative path for a program source file. */
+export function relativePathOf(root, sf) {
+    return relative(root, sf.fileName).split("\\").join("/");
+}

package/dist/analyze/surface.d.ts

@@ -0,0 +1,48 @@
+import ts from "typescript";
+import type { Analyzer } from "../types.js";
+/**
+ * A stored signature beyond this length is truncated when a fact records
+ * it, so that one enormous type — a huge object literal, or a union with
+ * many members — cannot flood a fact with a single string. The marker
+ * makes the cut visible: a reader must be able to tell the text was cut,
+ * not mistake it for the whole type. Exported for
+ * `test/comment-contract.test.ts`, which derives part of its forbidden set
+ * from it.
+ *
+ * Applied at the fact-emission boundary, not inside `exportedSignatures`:
+ * the true, uncut text has to exist long enough for its code-point length
+ * to be recorded beside the capped text (`beforeChars`/`afterChars` in the
+ * fact's detail), because the renderer's own length marker states that
+ * true length — a length measured after this cap asserted a false size
+ * for exactly the long-literal class the marker exists for.
+ */
+export declare const MAX_SIGNATURE_LENGTH = 400;
+/**
+ * Matches the marker `truncateSignature` appends. Exported for the render
+ * layer (`../score/index.ts`), which drops the marker before applying its
+ * own, shorter middle-truncation — the render marker states the true
+ * length, and keeping both would leave this one's tail fragment inside
+ * the rendered text.
+ */
+export declare const SIGNATURE_TRUNCATION_MARKER: RegExp;
+/**
+ * Exported name → printed type, for one file in a program. `undefined` when
+ * the program has no such source file: that is an unreadable file, not a
+ * file with no exports, and the two must not be conflated. Returning an
+ * empty map for a missing before-side file would make every export of the
+ * after-side file read as `export_added` — absence treated as evidence,
+ * one level up from the file-read rule the other analyzers follow.
+ *
+ * The printed text is the *full* signature, uncapped: `surfaceAnalyzer`
+ * measures its true length and applies `truncateSignature` when it stores
+ * the text on a fact, and truncating here instead would destroy the length
+ * before anything could record it.
+ */
+export declare function exportedSignatures(program: ts.Program, root: string, path: string): Map<string, string> | undefined;
+/**
+ * Reports changes to a file's public contract: exports added, exports
+ * removed, and exports whose type signature changed. A changed signature is
+ * the class of change that breaks callers without breaking the build at the
+ * point of change, which is why it ranks above an added export.
+ */
+export declare const surfaceAnalyzer: Analyzer;