@doki-land/nifty 0.0.0

package/src/gitmoji.ts

@@ -0,0 +1,77 @@
+import type { CommitRecord, GithubAuthor, ParsedSubject, RangeInfo, ReleaseSection, TagInfo } from "./types.js";
+import { loadNiftyNative, type GitmojiExports } from "./native.js";
+
+/**
+ * Nifty default convention: every commit subject starts with a gitmoji followed by a space.
+ */
+export class Gitmoji {
+    constructor(
+        private readonly wasm: GitmojiExports,
+        private readonly defaultAuthorMapJson = "{}",
+    ) {}
+
+    static open(authorMapJson = "{}"): Gitmoji {
+        const native = loadNiftyNative();
+        return new Gitmoji(native.gitmoji, authorMapJson);
+    }
+
+    knownGitmojis(): string[] {
+        return this.wasm["known-gitmojis"]();
+    }
+
+    validateSubject(subject: string): boolean {
+        return this.wasm["validate-subject"](subject);
+    }
+
+    parseSubject(subject: string): ParsedSubject {
+        return this.wasm["parse-subject"](subject);
+    }
+
+    formatSubject(gitmoji: string, body: string): string {
+        return this.wasm["format-subject"](gitmoji, body);
+    }
+
+    stripGitmoji(subject: string): string {
+        return this.wasm["strip-gitmoji"](subject);
+    }
+
+    leadingGitmoji(subject: string): string | undefined {
+        return this.wasm["leading-gitmoji"](subject);
+    }
+
+    sectionForGitmoji(gitmoji?: string): ReleaseSection {
+        return this.wasm["section-for-gitmoji"](gitmoji);
+    }
+
+    parseNoreplyEmail(email: string): GithubAuthor | undefined {
+        return this.wasm["parse-noreply-email"](email);
+    }
+
+    resolveGithubAuthor(email: string, authorMapJson = this.defaultAuthorMapJson): GithubAuthor | undefined {
+        return this.wasm["resolve-github-author"](email, authorMapJson);
+    }
+
+    displayLogin(author: GithubAuthor): string {
+        return this.wasm["display-login"](author);
+    }
+
+    profileUrl(author: GithubAuthor): string {
+        return this.wasm["profile-url"](author);
+    }
+
+    avatarUrl(author: GithubAuthor): string {
+        return this.wasm["avatar-url"](author);
+    }
+
+    authorMention(email: string, authorName: string, authorMapJson = this.defaultAuthorMapJson): string {
+        return this.wasm["author-mention"](email, authorName, authorMapJson);
+    }
+
+    commitBullet(body: string, email: string, authorName: string, authorMapJson = this.defaultAuthorMapJson): string {
+        return this.wasm["commit-bullet"](body, email, authorName, authorMapJson);
+    }
+}
+
+export function createGitmoji(): Gitmoji {
+    return Gitmoji.open();
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @doki-land/nifty — gitmoji-first commit conventions and gix-backed git helpers.
+ *
+ * Build native bindings first: `npm run build:napi` at the repo root.
+ * CLI (`nifty update`, `nifty lint`, `nifty upload`) is provided via the `nifty` bin.
+ */
+
+export type {
+    CommitRecord,
+    GithubAuthor,
+    ParsedSubject,
+    RangeInfo,
+    ReleaseSection,
+    TagInfo,
+} from "./types.js";
+export { Git, createGit, type ResolveRangeOptions } from "./git.js";
+export { Github, createGithub, type LookupUserOptions } from "./github.js";
+export { Gitmoji, createGitmoji } from "./gitmoji.js";
+export { Nifty, createNifty, type NiftyOpenOptions } from "./nifty.js";
+export {
+    defineConfig,
+    loadConfig,
+    findConfigFile,
+    authorMapToJson,
+    detectProjectLayout,
+    discoverPackageDirs,
+    findCargoManifest,
+    findPackageManifest,
+    type LoadConfigOptions,
+    type LoadedNiftyConfig,
+    type NiftyAuthorEntry,
+    type NiftyConfig,
+    type NiftyConfigEnv,
+    type ProjectKind,
+    type ProjectLayout,
+} from "./config/index.js";

package/src/native.ts

@@ -0,0 +1,277 @@
+import { createRequire } from "node:module";
+import type {
+    CommitRecord,
+    GithubAuthor,
+    ParsedSubject,
+    RangeInfo,
+    ReleaseSection,
+    TagInfo,
+} from "./types.js";
+
+export type GitmojiExports = {
+    "known-gitmojis": () => string[];
+    "validate-subject": (subject: string) => boolean;
+    "parse-subject": (subject: string) => ParsedSubject;
+    "format-subject": (gitmoji: string, body: string) => string;
+    "strip-gitmoji": (subject: string) => string;
+    "leading-gitmoji": (subject: string) => string | undefined;
+    "section-for-gitmoji": (gitmoji: string | undefined) => ReleaseSection;
+    "parse-noreply-email": (email: string) => GithubAuthor | undefined;
+    "resolve-github-author": (email: string, authorMapJson: string) => GithubAuthor | undefined;
+    "display-login": (author: GithubAuthor) => string;
+    "profile-url": (author: GithubAuthor) => string;
+    "avatar-url": (author: GithubAuthor) => string;
+    "author-mention": (email: string, authorName: string, authorMapJson: string) => string;
+    "commit-bullet": (body: string, email: string, authorName: string, authorMapJson: string) => string;
+};
+
+export type GitExports = {
+    "discover-root": (startPath: string) => string;
+    "list-version-tags": (repoRoot: string) => string[];
+    "list-tag-infos": (repoRoot: string) => Array<{ name: string; "short-hash": string }>;
+    "format-tag-list": (repoRoot: string) => string;
+    "resolve-range": (
+        repoRoot: string,
+        version: string | undefined,
+        fromRef: string | undefined,
+        toRef: string | undefined,
+    ) => { version: string; "from-ref"?: string; "to-ref": string };
+    "collect-commits": (
+        repoRoot: string,
+        fromRef: string | undefined,
+        toRef: string,
+    ) => Array<{
+        hash: string;
+        email: string;
+        author: string;
+        subject: string;
+        body: string;
+        gitmoji?: string;
+        section: string;
+    }>;
+    "detect-github-repo": (repoRoot: string) => string | undefined;
+    "parse-github-remote": (url: string) => string | undefined;
+};
+
+export type PublishReport = {
+    root: string;
+    order: string[];
+    published: string[];
+    skipped: string[];
+};
+
+export type TrustReport = {
+    root: string;
+    configured: string[];
+    skipped: string[];
+    failed: string[];
+};
+
+export type PublisherExports = {
+    "publish-workspace": (options: {
+        cwd?: string;
+        dryRun?: boolean;
+        tag?: string;
+        access?: string;
+        npm?: string;
+        otp?: string;
+        totpSecret?: string;
+        token?: string;
+    }) => PublishReport;
+    "trust-workspace": (options: {
+        cwd?: string;
+        dryRun?: boolean;
+        only?: string;
+        npm?: string;
+        otp?: string;
+        totpSecret?: string;
+        token?: string;
+    }) => TrustReport;
+};
+
+export type NiftyNative = {
+    gitmoji: GitmojiExports;
+    git: GitExports;
+    publisher: PublisherExports;
+};
+
+type NativeBinding = {
+    gitmojiKnownGitmojis: () => string[];
+    gitmojiValidateSubject: (subject: string) => boolean;
+    gitmojiParseSubject: (subject: string) => ParsedSubject;
+    gitmojiFormatSubject: (gitmoji: string, body: string) => string;
+    gitmojiStripGitmoji: (subject: string) => string;
+    gitmojiLeadingGitmoji: (subject: string) => string | null;
+    gitmojiSectionForGitmoji: (gitmoji?: string | null) => string;
+    gitmojiParseNoreplyEmail: (email: string) => GithubAuthor | null;
+    gitmojiResolveGithubAuthor: (email: string, authorMapJson: string) => GithubAuthor | null;
+    gitmojiDisplayLogin: (author: GithubAuthor) => string;
+    gitmojiProfileUrl: (author: GithubAuthor) => string;
+    gitmojiAvatarUrl: (author: GithubAuthor) => string;
+    gitmojiAuthorMention: (email: string, authorName: string, authorMapJson: string) => string;
+    gitmojiCommitBullet: (body: string, email: string, authorName: string, authorMapJson: string) => string;
+    gitDiscoverRoot: (startPath: string) => string;
+    gitListVersionTags: (repoRoot: string) => string[];
+    gitListTagInfos: (repoRoot: string) => Array<{ name: string; shortHash: string }>;
+    gitFormatTagList: (repoRoot: string) => string;
+    gitResolveRange: (
+        repoRoot: string,
+        version?: string | null,
+        fromRef?: string | null,
+        toRef?: string | null,
+    ) => { version: string; fromRef?: string; toRef: string };
+    gitCollectCommits: (
+        repoRoot: string,
+        fromRef: string | null | undefined,
+        toRef: string,
+    ) => CommitRecord[];
+    gitDetectGithubRepo: (repoRoot: string) => string | null;
+    gitParseGithubRemote: (url: string) => string | null;
+    publisherPublishWorkspace: (options: {
+        cwd?: string | null;
+        dryRun?: boolean | null;
+        tag?: string | null;
+        access?: string | null;
+        npm?: string | null;
+        otp?: string | null;
+        totpSecret?: string | null;
+        token?: string | null;
+    }) => PublishReport;
+    publisherTrustWorkspace: (options: {
+        cwd?: string | null;
+        dryRun?: boolean | null;
+        only?: string | null;
+        npm?: string | null;
+        otp?: string | null;
+        totpSecret?: string | null;
+        token?: string | null;
+    }) => TrustReport;
+};
+
+const PLATFORM_PACKAGES: Record<string, string> = {
+    "win32-x64": "@doki-land/nifty-win32-x64",
+    "linux-x64": "@doki-land/nifty-linux-x64",
+    "linux-arm64": "@doki-land/nifty-linux-arm64",
+    "darwin-x64": "@doki-land/nifty-darwin-x64",
+    "darwin-arm64": "@doki-land/nifty-darwin-arm64",
+};
+
+function mapAuthor(raw: GithubAuthor | null | undefined): GithubAuthor | undefined {
+    if (!raw) {
+        return undefined;
+    }
+    return {
+        id: raw.id !== undefined && raw.id !== null ? BigInt(raw.id) : undefined,
+        login: raw.login ?? undefined,
+    };
+}
+
+function wrapBinding(binding: NativeBinding): NiftyNative {
+    return {
+        gitmoji: {
+            "known-gitmojis": () => binding.gitmojiKnownGitmojis(),
+            "validate-subject": (subject) => binding.gitmojiValidateSubject(subject),
+            "parse-subject": (subject) => binding.gitmojiParseSubject(subject),
+            "format-subject": (gitmoji, body) => binding.gitmojiFormatSubject(gitmoji, body),
+            "strip-gitmoji": (subject) => binding.gitmojiStripGitmoji(subject),
+            "leading-gitmoji": (subject) => binding.gitmojiLeadingGitmoji(subject) ?? undefined,
+            "section-for-gitmoji": (gitmoji) => binding.gitmojiSectionForGitmoji(gitmoji) as ReleaseSection,
+            "parse-noreply-email": (email) => mapAuthor(binding.gitmojiParseNoreplyEmail(email)),
+            "resolve-github-author": (email, authorMapJson) =>
+                mapAuthor(binding.gitmojiResolveGithubAuthor(email, authorMapJson)),
+            "display-login": (author) => binding.gitmojiDisplayLogin(author),
+            "profile-url": (author) => binding.gitmojiProfileUrl(author),
+            "avatar-url": (author) => binding.gitmojiAvatarUrl(author),
+            "author-mention": (email, authorName, authorMapJson) =>
+                binding.gitmojiAuthorMention(email, authorName, authorMapJson),
+            "commit-bullet": (body, email, authorName, authorMapJson) =>
+                binding.gitmojiCommitBullet(body, email, authorName, authorMapJson),
+        },
+        git: {
+            "discover-root": (startPath) => binding.gitDiscoverRoot(startPath),
+            "list-version-tags": (repoRoot) => binding.gitListVersionTags(repoRoot),
+            "list-tag-infos": (repoRoot) =>
+                binding.gitListTagInfos(repoRoot).map((tag) => ({
+                    name: tag.name,
+                    "short-hash": tag.shortHash,
+                })),
+            "format-tag-list": (repoRoot) => binding.gitFormatTagList(repoRoot),
+            "resolve-range": (repoRoot, version, fromRef, toRef) => {
+                const range = binding.gitResolveRange(repoRoot, version, fromRef, toRef);
+                return {
+                    version: range.version,
+                    "from-ref": range.fromRef,
+                    "to-ref": range.toRef,
+                };
+            },
+            "collect-commits": (repoRoot, fromRef, toRef) => binding.gitCollectCommits(repoRoot, fromRef, toRef),
+            "detect-github-repo": (repoRoot) => binding.gitDetectGithubRepo(repoRoot) ?? undefined,
+            "parse-github-remote": (url) => binding.gitParseGithubRemote(url) ?? undefined,
+        },
+        publisher: {
+            "publish-workspace": (options) =>
+                binding.publisherPublishWorkspace({
+                    ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+                    ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
+                    ...(options.tag !== undefined ? { tag: options.tag } : {}),
+                    ...(options.access !== undefined ? { access: options.access } : {}),
+                    ...(options.npm !== undefined ? { npm: options.npm } : {}),
+                    ...(options.otp !== undefined ? { otp: options.otp } : {}),
+                    ...(options.totpSecret !== undefined ? { totpSecret: options.totpSecret } : {}),
+                    ...(options.token !== undefined ? { token: options.token } : {}),
+                }),
+            "trust-workspace": (options) =>
+                binding.publisherTrustWorkspace({
+                    ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+                    ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
+                    ...(options.only !== undefined ? { only: options.only } : {}),
+                    ...(options.npm !== undefined ? { npm: options.npm } : {}),
+                    ...(options.otp !== undefined ? { otp: options.otp } : {}),
+                    ...(options.totpSecret !== undefined ? { totpSecret: options.totpSecret } : {}),
+                    ...(options.token !== undefined ? { token: options.token } : {}),
+                }),
+        },
+    };
+}
+
+let cached: NiftyNative | undefined;
+
+/** Load the platform-specific Node-API binary from `@doki-land/nifty-<platform>`. */
+export function loadNiftyNative(): NiftyNative {
+    if (cached) {
+        return cached;
+    }
+    const key = `${process.platform}-${process.arch}`;
+    const pkg = PLATFORM_PACKAGES[key];
+    if (!pkg) {
+        throw new Error(`Unsupported platform for Nifty native bindings: ${key}`);
+    }
+    const require = createRequire(import.meta.url);
+    const binding = require(pkg).default as NativeBinding;
+    cached = wrapBinding(binding);
+    return cached;
+}
+
+export function mapTagInfo(raw: { name: string; "short-hash": string }): TagInfo {
+    return { name: raw.name, shortHash: raw["short-hash"] };
+}
+
+export function mapRangeInfo(raw: { version: string; "from-ref"?: string; "to-ref": string }): RangeInfo {
+    return {
+        version: raw.version,
+        fromRef: raw["from-ref"],
+        toRef: raw["to-ref"],
+    };
+}
+
+export function mapCommitRecord(raw: CommitRecord): CommitRecord {
+    return {
+        hash: raw.hash,
+        email: raw.email,
+        author: raw.author,
+        subject: raw.subject,
+        body: raw.body,
+        gitmoji: raw.gitmoji,
+        section: raw.section as ReleaseSection,
+    };
+}

package/src/nifty.ts

@@ -0,0 +1,95 @@
+import {
+    authorMapToJson,
+    detectProjectLayout,
+    loadConfig,
+    type LoadConfigOptions,
+    type NiftyConfig,
+    type ProjectLayout,
+} from "./config/index.js";
+
+import { Git } from "./git.js";
+import { Github } from "./github.js";
+import { Gitmoji } from "./gitmoji.js";
+import { loadNiftyNative } from "./native.js";
+
+export type NiftyOpenOptions = NiftyConfig &
+    LoadConfigOptions & {
+        /** When `false`, skip loading `nifty.config.ts/js`. Inline options still apply. */
+        config?: false;
+    };
+
+function resolveRoots(config: NiftyConfig, layout: ProjectLayout): NiftyConfig {
+    return {
+        ...config,
+        repoRoot: config.repoRoot ?? layout.root,
+        cargoRoot:
+            config.cargoRoot ??
+            layout.cargoWorkspaceRoot ??
+            (layout.cargoManifest ? layout.cargoManifest.replace(/[/\\]Cargo\.toml$/, "") : undefined),
+        npmRoot:
+            config.npmRoot ??
+            layout.npmWorkspaceRoot ??
+            (layout.packageManifest ? layout.packageManifest.replace(/[/\\]package\.json$/, "") : undefined),
+    };
+}
+
+/** Combined Nifty engine: gitmoji conventions + gix repository reads + GitHub API. */
+export class Nifty {
+    readonly gitmoji: Gitmoji;
+    readonly git: Git;
+    readonly github: Github;
+    readonly config: NiftyConfig;
+    readonly layout: ProjectLayout;
+    readonly configFile?: string;
+
+    private constructor(
+        gitmoji: Gitmoji,
+        git: Git,
+        github: Github,
+        config: NiftyConfig,
+        layout: ProjectLayout,
+        configFile?: string,
+    ) {
+        this.gitmoji = gitmoji;
+        this.git = git;
+        this.github = github;
+        this.config = config;
+        this.layout = layout;
+        this.configFile = configFile;
+    }
+
+    static async open(options: NiftyOpenOptions = {}): Promise<Nifty> {
+        const cwd = options.cwd ?? process.cwd();
+        const layout = detectProjectLayout(cwd);
+        const { config: skipConfig, configFile, env, githubToken, authorMap, repoRoot, cargoRoot, npmRoot } = options;
+        const loaded =
+            skipConfig === false
+                ? { config: {} as NiftyConfig }
+                : await loadConfig({ cwd, configFile, env: { layout, ...env } });
+        const merged = resolveRoots(
+            {
+                ...loaded.config,
+                ...(githubToken !== undefined ? { githubToken } : {}),
+                ...(authorMap !== undefined ? { authorMap } : {}),
+                ...(repoRoot !== undefined ? { repoRoot } : {}),
+                ...(cargoRoot !== undefined ? { cargoRoot } : {}),
+                ...(npmRoot !== undefined ? { npmRoot } : {}),
+            },
+            layout,
+        );
+
+        const native = loadNiftyNative();
+        return new Nifty(
+            new Gitmoji(native.gitmoji, authorMapToJson(merged.authorMap)),
+            new Git(native.git),
+            Github.open(merged.githubToken),
+            merged,
+            layout,
+            loaded.configFile,
+        );
+    }
+}
+
+export async function createNifty(options: NiftyOpenOptions = {}): Promise<Nifty> {
+    return Nifty.open(options);
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+/** GitHub author resolved from noreply email or `author-github.json`. */
+export type GithubAuthor = {
+    id?: bigint;
+    login?: string;
+};
+
+/** Nifty gitmoji-parsed commit subject. */
+export type ParsedSubject = {
+    gitmoji?: string;
+    body: string;
+    /** `features` | `fixes` | `breaking` | `other` */
+    section: string;
+};
+
+/** Release note section keys (Nifty gitmoji grouping). */
+export type ReleaseSection = "features" | "fixes" | "breaking" | "other";
+
+/** Semver tag with short hash. */
+export type TagInfo = {
+    name: string;
+    shortHash: string;
+};
+
+/** Resolved release tag range. */
+export type RangeInfo = {
+    version: string;
+    fromRef?: string;
+    toRef: string;
+};
+
+/** Commit from repository history with Nifty gitmoji fields. */
+export type CommitRecord = {
+    hash: string;
+    email: string;
+    author: string;
+    subject: string;
+    body: string;
+    gitmoji?: string;
+    section: ReleaseSection;
+};