@descent-vtt/spec-brief 0.1.0

package/dist/git.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Git, read-only.
+ *
+ * spec-brief never stages, commits or rewrites history. It reads the commit a
+ * round landed as, the files that commit touched, and whether the working tree
+ * holds work the commit does not. What goes into a commit stays the decision
+ * of whoever makes it, and archival is atomic over the files it writes rather
+ * than over a repository state it would have to reverse.
+ */
+export interface CommitInfo {
+    readonly sha: string;
+    readonly author: string;
+    /** ISO 8601 author date. */
+    readonly date: string;
+}
+export interface FileChange {
+    readonly path: string;
+    /** `null` for a binary file, which has no line counts. */
+    readonly insertions: number | null;
+    readonly deletions: number | null;
+}
+export interface Git {
+    /** The commit a revision names, or `null` when it names none. */
+    commit(revision: string): Promise<CommitInfo | null>;
+    mergeBase(a: string, b: string): Promise<string | null>;
+    /** Files changed from `from` to `to`; with no `from`, the files `to` changed against its first parent. */
+    changes(from: string | null, to: string): Promise<FileChange[]>;
+    /** Paths with uncommitted changes, untracked files included. */
+    dirty(): Promise<string[]>;
+    /** Every path git sees: tracked, or untracked and not ignored. A file a round just created counts. */
+    files(): Promise<string[]>;
+    remoteUrl(name: string): Promise<string | null>;
+}
+/** Parses `--numstat -z` output with renames off: `added<TAB>deleted<TAB>path<NUL>`. */
+export declare function parseNumstat(output: string): FileChange[];
+/** Parses `status --porcelain=v1 -z`, where a rename's original path is a record of its own. */
+export declare function parsePorcelain(output: string): string[];
+/**
+ * Git reports paths from the top of the work tree; spec-brief's paths start at
+ * the root, which may be a directory below it. Every path that crosses this
+ * boundary is made relative to the root.
+ */
+export declare class NodeGit implements Git {
+    readonly cwd: string;
+    private prefix;
+    constructor(cwd: string);
+    /** The root's path from the top of the work tree, `sub/dir/` or empty. */
+    private rootPrefix;
+    /** The working tree's top directory, canonical, or `null` outside a repository. */
+    static toplevel(cwd: string): Promise<string | null>;
+    commit(revision: string): Promise<CommitInfo | null>;
+    mergeBase(a: string, b: string): Promise<string | null>;
+    changes(from: string | null, to: string): Promise<FileChange[]>;
+    dirty(): Promise<string[]>;
+    files(): Promise<string[]>;
+    remoteUrl(name: string): Promise<string | null>;
+}
+/** The web address of a pull request, for remotes on github.com. */
+export declare function pullRequestUrl(remote: string | null, number: number): string | null;

package/dist/git.js

@@ -0,0 +1,131 @@
+/**
+ * Git, read-only.
+ *
+ * spec-brief never stages, commits or rewrites history. It reads the commit a
+ * round landed as, the files that commit touched, and whether the working tree
+ * holds work the commit does not. What goes into a commit stays the decision
+ * of whoever makes it, and archival is atomic over the files it writes rather
+ * than over a repository state it would have to reverse.
+ */
+import { execFile } from 'node:child_process';
+import { resolve } from 'node:path';
+import { canonicalPath } from './fs.js';
+import { relativePath } from './links.js';
+function run(cwd, args) {
+    return new Promise((done) => {
+        execFile('git', ['-c', 'core.quotepath=off', ...args], { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => done({ ok: error === null, stdout, stderr }));
+    });
+}
+/** A revision that starts with "-" would be read as an option. */
+function safeRevision(revision) {
+    if (revision.startsWith('-') || revision.trim() === '')
+        throw new Error(`"${revision}" is not a revision`);
+    return revision;
+}
+function records(output) {
+    return output.split('\0').filter((r) => r !== '');
+}
+/** Parses `--numstat -z` output with renames off: `added<TAB>deleted<TAB>path<NUL>`. */
+export function parseNumstat(output) {
+    // `show --format=` leaves the empty header's newline in front of the first record.
+    return records(output.replace(/^\n+/, '')).map((record) => {
+        const [added = '-', deleted = '-', ...path] = record.split('\t');
+        return {
+            path: path.join('\t'),
+            insertions: added === '-' ? null : Number(added),
+            deletions: deleted === '-' ? null : Number(deleted),
+        };
+    });
+}
+/** Parses `status --porcelain=v1 -z`, where a rename's original path is a record of its own. */
+export function parsePorcelain(output) {
+    const fields = records(output);
+    const paths = [];
+    for (let i = 0; i < fields.length; i += 1) {
+        const field = fields[i];
+        paths.push(field.slice(3));
+        const x = field.charAt(0);
+        if (x === 'R' || x === 'C')
+            i += 1;
+    }
+    return paths;
+}
+/**
+ * Git reports paths from the top of the work tree; spec-brief's paths start at
+ * the root, which may be a directory below it. Every path that crosses this
+ * boundary is made relative to the root.
+ */
+export class NodeGit {
+    cwd;
+    prefix;
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    /** The root's path from the top of the work tree, `sub/dir/` or empty. */
+    async rootPrefix() {
+        // Asked only after a status that succeeded, so the repository exists.
+        this.prefix ??= run(this.cwd, ['rev-parse', '--show-prefix']).then((r) => r.stdout.trim());
+        return this.prefix;
+    }
+    /** The working tree's top directory, canonical, or `null` outside a repository. */
+    static async toplevel(cwd) {
+        const result = await run(cwd, ['rev-parse', '--show-toplevel']);
+        return result.ok ? canonicalPath(resolve(result.stdout.trim())) : null;
+    }
+    async commit(revision) {
+        const sha = await run(this.cwd, ['rev-parse', '--verify', '--quiet', `${safeRevision(revision)}^{commit}`]);
+        if (!sha.ok)
+            return null;
+        const hash = sha.stdout.trim();
+        const show = await run(this.cwd, ['show', '-s', '--format=%an%x00%aI', hash]);
+        const [author = '', date = ''] = show.stdout.trim().split('\0');
+        return { sha: hash, author, date };
+    }
+    async mergeBase(a, b) {
+        const result = await run(this.cwd, ['merge-base', safeRevision(a), safeRevision(b)]);
+        return result.ok ? result.stdout.trim() : null;
+    }
+    async changes(from, to) {
+        const target = safeRevision(to);
+        let result;
+        if (from !== null) {
+            result = await run(this.cwd, ['diff', '--numstat', '-z', '--no-renames', '--relative', safeRevision(from), target]);
+        }
+        else {
+            const parent = await run(this.cwd, ['rev-parse', '--verify', '--quiet', `${target}^`]);
+            result = parent.ok
+                ? await run(this.cwd, ['diff', '--numstat', '-z', '--no-renames', '--relative', `${target}^`, target])
+                : await run(this.cwd, ['show', '--numstat', '-z', '--no-renames', '--relative', '--format=', target]);
+        }
+        if (!result.ok)
+            throw new Error(`git could not diff ${from ?? `${to}^`}..${to}: ${result.stderr.trim()}`);
+        return parseNumstat(result.stdout);
+    }
+    async dirty() {
+        const result = await run(this.cwd, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
+        if (!result.ok)
+            throw new Error(`git status failed: ${result.stderr.trim()}`);
+        const prefix = await this.rootPrefix();
+        return parsePorcelain(result.stdout).map((path) => (prefix === '' ? path : relativePath(prefix, path)));
+    }
+    async files() {
+        const result = await run(this.cwd, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+        if (!result.ok)
+            throw new Error(`git ls-files failed: ${result.stderr.trim()}`);
+        return records(result.stdout).sort();
+    }
+    async remoteUrl(name) {
+        const result = await run(this.cwd, ['remote', 'get-url', safeRevision(name)]);
+        return result.ok ? result.stdout.trim() : null;
+    }
+}
+/** The web address of a pull request, for remotes on github.com. */
+export function pullRequestUrl(remote, number) {
+    if (remote === null)
+        return null;
+    const match = /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(remote);
+    if (!match)
+        return null;
+    return `https://github.com/${match[1]}/${match[2]}/pull/${number}`;
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Git, read-only.\n *\n * spec-brief never stages, commits or rewrites history. It reads the commit a\n * round landed as, the files that commit touched, and whether the working tree\n * holds work the commit does not. What goes into a commit stays the decision\n * of whoever makes it, and archival is atomic over the files it writes rather\n * than over a repository state it would have to reverse.\n */\n\nimport { execFile } from 'node:child_process';\nimport { resolve } from 'node:path';\n\nimport { canonicalPath } from './fs.js';\nimport { relativePath } from './links.js';\n\nexport interface CommitInfo {\n  readonly sha: string;\n  readonly author: string;\n  /** ISO 8601 author date. */\n  readonly date: string;\n}\n\nexport interface FileChange {\n  readonly path: string;\n  /** `null` for a binary file, which has no line counts. */\n  readonly insertions: number | null;\n  readonly deletions: number | null;\n}\n\nexport interface Git {\n  /** The commit a revision names, or `null` when it names none. */\n  commit(revision: string): Promise<CommitInfo | null>;\n  mergeBase(a: string, b: string): Promise<string | null>;\n  /** Files changed from `from` to `to`; with no `from`, the files `to` changed against its first parent. */\n  changes(from: string | null, to: string): Promise<FileChange[]>;\n  /** Paths with uncommitted changes, untracked files included. */\n  dirty(): Promise<string[]>;\n  /** Every path git sees: tracked, or untracked and not ignored. A file a round just created counts. */\n  files(): Promise<string[]>;\n  remoteUrl(name: string): Promise<string | null>;\n}\n\ninterface Run {\n  readonly ok: boolean;\n  readonly stdout: string;\n  readonly stderr: string;\n}\n\nfunction run(cwd: string, args: readonly string[]): Promise<Run> {\n  return new Promise((done) => {\n    execFile(\n      'git',\n      ['-c', 'core.quotepath=off', ...args],\n      { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, windowsHide: true },\n      (error, stdout, stderr) => done({ ok: error === null, stdout, stderr }),\n    );\n  });\n}\n\n/** A revision that starts with \"-\" would be read as an option. */\nfunction safeRevision(revision: string): string {\n  if (revision.startsWith('-') || revision.trim() === '') throw new Error(`\"${revision}\" is not a revision`);\n  return revision;\n}\n\nfunction records(output: string): string[] {\n  return output.split('\\0').filter((r) => r !== '');\n}\n\n/** Parses `--numstat -z` output with renames off: `added<TAB>deleted<TAB>path<NUL>`. */\nexport function parseNumstat(output: string): FileChange[] {\n  // `show --format=` leaves the empty header's newline in front of the first record.\n  return records(output.replace(/^\\n+/, '')).map((record) => {\n    const [added = '-', deleted = '-', ...path] = record.split('\\t');\n    return {\n      path: path.join('\\t'),\n      insertions: added === '-' ? null : Number(added),\n      deletions: deleted === '-' ? null : Number(deleted),\n    };\n  });\n}\n\n/** Parses `status --porcelain=v1 -z`, where a rename's original path is a record of its own. */\nexport function parsePorcelain(output: string): string[] {\n  const fields = records(output);\n  const paths: string[] = [];\n  for (let i = 0; i < fields.length; i += 1) {\n    const field = fields[i] as string;\n    paths.push(field.slice(3));\n    const x = field.charAt(0);\n    if (x === 'R' || x === 'C') i += 1;\n  }\n  return paths;\n}\n\n/**\n * Git reports paths from the top of the work tree; spec-brief's paths start at\n * the root, which may be a directory below it. Every path that crosses this\n * boundary is made relative to the root.\n */\nexport class NodeGit implements Git {\n  readonly cwd: string;\n  private prefix: Promise<string> | undefined;\n\n  constructor(cwd: string) {\n    this.cwd = cwd;\n  }\n\n  /** The root's path from the top of the work tree, `sub/dir/` or empty. */\n  private async rootPrefix(): Promise<string> {\n    // Asked only after a status that succeeded, so the repository exists.\n    this.prefix ??= run(this.cwd, ['rev-parse', '--show-prefix']).then((r) => r.stdout.trim());\n    return this.prefix;\n  }\n\n  /** The working tree's top directory, canonical, or `null` outside a repository. */\n  static async toplevel(cwd: string): Promise<string | null> {\n    const result = await run(cwd, ['rev-parse', '--show-toplevel']);\n    return result.ok ? canonicalPath(resolve(result.stdout.trim())) : null;\n  }\n\n  async commit(revision: string): Promise<CommitInfo | null> {\n    const sha = await run(this.cwd, ['rev-parse', '--verify', '--quiet', `${safeRevision(revision)}^{commit}`]);\n    if (!sha.ok) return null;\n    const hash = sha.stdout.trim();\n    const show = await run(this.cwd, ['show', '-s', '--format=%an%x00%aI', hash]);\n    const [author = '', date = ''] = show.stdout.trim().split('\\0');\n    return { sha: hash, author, date };\n  }\n\n  async mergeBase(a: string, b: string): Promise<string | null> {\n    const result = await run(this.cwd, ['merge-base', safeRevision(a), safeRevision(b)]);\n    return result.ok ? result.stdout.trim() : null;\n  }\n\n  async changes(from: string | null, to: string): Promise<FileChange[]> {\n    const target = safeRevision(to);\n    let result: Run;\n    if (from !== null) {\n      result = await run(this.cwd, ['diff', '--numstat', '-z', '--no-renames', '--relative', safeRevision(from), target]);\n    } else {\n      const parent = await run(this.cwd, ['rev-parse', '--verify', '--quiet', `${target}^`]);\n      result = parent.ok\n        ? await run(this.cwd, ['diff', '--numstat', '-z', '--no-renames', '--relative', `${target}^`, target])\n        : await run(this.cwd, ['show', '--numstat', '-z', '--no-renames', '--relative', '--format=', target]);\n    }\n    if (!result.ok) throw new Error(`git could not diff ${from ?? `${to}^`}..${to}: ${result.stderr.trim()}`);\n    return parseNumstat(result.stdout);\n  }\n\n  async dirty(): Promise<string[]> {\n    const result = await run(this.cwd, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);\n    if (!result.ok) throw new Error(`git status failed: ${result.stderr.trim()}`);\n    const prefix = await this.rootPrefix();\n    return parsePorcelain(result.stdout).map((path) => (prefix === '' ? path : relativePath(prefix, path)));\n  }\n\n  async files(): Promise<string[]> {\n    const result = await run(this.cwd, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);\n    if (!result.ok) throw new Error(`git ls-files failed: ${result.stderr.trim()}`);\n    return records(result.stdout).sort();\n  }\n\n  async remoteUrl(name: string): Promise<string | null> {\n    const result = await run(this.cwd, ['remote', 'get-url', safeRevision(name)]);\n    return result.ok ? result.stdout.trim() : null;\n  }\n}\n\n/** The web address of a pull request, for remotes on github.com. */\nexport function pullRequestUrl(remote: string | null, number: number): string | null {\n  if (remote === null) return null;\n  const match = /github\\.com[:/]([^/\\s]+)\\/([^/\\s]+?)(?:\\.git)?\\/?$/.exec(remote);\n  if (!match) return null;\n  return `https://github.com/${match[1] as string}/${match[2] as string}/pull/${number}`;\n}\n"]}

package/dist/glob.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Globs: parsing, matching, and deciding whether two globs can name the same file.
+ *
+ * The dialect is the one people type: `**`, `*`, `?`, `[abc]`, `[!a-z]`,
+ * `{a,b}` and `\` to escape. A pattern with no glob syntax at all names a
+ * directory and everything beneath it, so `src/auth` covers
+ * `src/auth/login.ts` - unless it names a file, one the tree holds or one with
+ * an extension, which matches only itself. A trailing `/` always means a
+ * directory. Paths
+ * are repository-relative and POSIX, and matching is case-sensitive on every
+ * host, because git's paths are and a result should not depend on who ran it.
+ * `*` matches a leading dot; a scope that forgot its dotfiles is not a scope
+ * that excludes them.
+ *
+ * Nothing here compiles to a `RegExp`. Matching and intersection are dynamic
+ * programmes over the pattern and the subject, so a pattern of `*a*a*a*a*b`
+ * against a long name costs the product of their lengths and cannot backtrack
+ * into an exponent. The same property is why the sibling tools match their own
+ * globs this way.
+ */
+export type CharToken = {
+    readonly kind: 'literal';
+    readonly char: string;
+} | {
+    readonly kind: 'any';
+} | {
+    readonly kind: 'star';
+} | {
+    readonly kind: 'class';
+    readonly negated: boolean;
+    readonly ranges: readonly (readonly [number, number])[];
+};
+export type Segment = {
+    readonly kind: 'globstar';
+} | {
+    readonly kind: 'pattern';
+    readonly tokens: readonly CharToken[];
+    readonly literal: boolean;
+};
+export interface Glob {
+    readonly source: string;
+    /** One sequence of segments per brace alternative; a path matches when any does. */
+    readonly alternatives: readonly (readonly Segment[])[];
+}
+export type GlobParse = {
+    readonly ok: true;
+    readonly glob: Glob;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** More alternatives than this is a pattern nobody meant. */
+export declare const MAX_ALTERNATIVES = 256;
+export interface ParseOptions {
+    /** Whether a literal path is a file, from the tree when it is known. */
+    readonly isFile?: ((path: string) => boolean) | undefined;
+}
+export declare function parseGlob(source: string, options?: ParseOptions): GlobParse;
+export declare function matchGlob(glob: Glob, path: string): boolean;
+/**
+ * A path both globs match, or `null` when there is none. The answer is exact
+ * for the dialect above: a `null` means no file can be in both scopes, and a
+ * path is a witness a reader can check by eye.
+ */
+export declare function intersectGlobs(a: Glob, b: Glob): string | null;
+/**
+ * A non-empty string both token sequences match, or `null`.
+ *
+ * Complete by a shortest-witness argument: in a shortest common string, no
+ * character is absorbed by a star on both sides at once (dropping it would
+ * leave a shorter one), so every character advances at least one sequence,
+ * and the five moves below are all the ways that can happen.
+ */
+export declare function intersectTokens(x: readonly CharToken[], y: readonly CharToken[]): string | null;
+/**
+ * The directory a glob is rooted in: its leading literal segments. A pattern
+ * that names a file is rooted in that file's directory.
+ */
+export declare function globBase(glob: Glob): string;