untodo 0.0.1-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Base meta passed to {@link TODO}.
+ *
+ * Users can extend it via Declaration Merging — additional fields are additive,
+ * so `reason` is always required:
+ *
+ * ```ts
+ * declare module 'untodo' {
+ *   interface TodoMeta {
+ *     issue?: number | string;
+ *     assignee?: string;
+ *   }
+ * }
+ * ```
+ */
+interface TodoMeta {
+    /** Human-readable reason this code is unimplemented. Required. */
+    reason: string;
+}
+/**
+ * Base meta passed to {@link FIXME}.
+ *
+ * Extendable via Declaration Merging in the same way as {@link TodoMeta}.
+ */
+interface FixmeMeta {
+    /** Human-readable description of what is broken. Required. */
+    reason: string;
+}
+/**
+ * Base meta passed to {@link HACK}.
+ *
+ * Extendable via Declaration Merging in the same way as {@link TodoMeta}.
+ */
+interface HackMeta {
+    /** Human-readable description of the workaround. Required. */
+    reason: string;
+}
+/**
+ * Union of all meta shapes accepted by the untodo function family.
+ */
+type AnyUntodoMeta = TodoMeta | FixmeMeta | HackMeta;
+
+/**
+ * Base class for all errors thrown by user-supplied untodo callbacks.
+ *
+ * The library itself never throws; this hierarchy exists so that consumers
+ * who *want* to throw inside `onTodo` / `onFixme` / `onHack` can use a
+ * consistent type for catch blocks.
+ */
+declare class UntodoError extends Error {
+    /**
+     * @param message Human-readable error message.
+     */
+    constructor(message: string);
+}
+/**
+ * Error intended to be thrown from a {@link TODO} callback when the missing
+ * implementation must surface as a runtime failure.
+ */
+declare class NotImplementedError extends UntodoError {
+    /**
+     * @param message Human-readable error message.
+     */
+    constructor(message: string);
+}
+/**
+ * Error intended to be thrown from a {@link FIXME} callback.
+ */
+declare class FixmeError extends UntodoError {
+    /**
+     * @param message Human-readable error message.
+     */
+    constructor(message: string);
+}
+/**
+ * Error intended to be thrown from a {@link HACK} callback.
+ */
+declare class HackError extends UntodoError {
+    /**
+     * @param message Human-readable error message.
+     */
+    constructor(message: string);
+}
+
+/**
+ * Project-wide configuration consumed by {@link TODO}, {@link FIXME}
+ * and {@link HACK} when no per-call callback is supplied.
+ *
+ * Set this once from a setup file (e.g. `untodo.config.ts`) using
+ * {@link defineConfig}.
+ */
+interface UntodoConfig {
+    /**
+     * Repository in `org/repo` form. Used by tooling to expand the `issue`
+     * meta field into a full URL (e.g. `https://github.com/org/repo/issues/123`).
+     */
+    repo?: string;
+    /** Default handler invoked for {@link TODO} calls without a callback. */
+    onTodo?: (meta: TodoMeta) => void;
+    /** Default handler invoked for {@link FIXME} calls without a callback. */
+    onFixme?: (meta: FixmeMeta) => void;
+    /** Default handler invoked for {@link HACK} calls without a callback. */
+    onHack?: (meta: HackMeta) => void;
+}
+/**
+ * Register the project-wide untodo configuration and return it unchanged.
+ *
+ * Mirrors the `defineConfig` ergonomics used by Vite / Vitest. Per-call
+ * callbacks passed to {@link TODO}, {@link FIXME} or {@link HACK} take
+ * precedence over the handlers registered here.
+ *
+ * @param config The configuration object to register.
+ * @returns The same `config` object, for chaining or assignment.
+ */
+declare function defineConfig(config: UntodoConfig): UntodoConfig;
+/**
+ * Read the currently-registered {@link UntodoConfig}.
+ *
+ * Returns an empty object if {@link defineConfig} has not been called
+ * (or after {@link resetConfig}).
+ */
+declare function getConfig(): UntodoConfig;
+/**
+ * Clear the registered configuration. Primarily intended for tests.
+ */
+declare function resetConfig(): void;
+
+/**
+ * Marks a code path as not yet implemented.
+ *
+ * Returns `never`, so callers continue to type-check as if the value flowed
+ * through. Does **not** throw — runtime behaviour is delegated to the
+ * supplied callback (or the global `onTodo` from {@link defineConfig}).
+ *
+ * Lint enforcement is the responsibility of the `untodo/no-todo` ESLint /
+ * oxlint rule shipped from `untodo/eslint`.
+ *
+ * @example
+ * ```ts
+ * function fetchUser(): User {
+ *   return TODO({ reason: 'wire up the user repository' });
+ * }
+ * ```
+ *
+ * @param meta Structured description of the unimplemented work.
+ * @param cb Optional per-call handler; overrides the global `onTodo`.
+ * @returns Never — the function returns `undefined` typed as `never`.
+ */
+declare function TODO(meta: TodoMeta, cb?: (meta: TodoMeta) => void): never;
+/**
+ * Marks code that is known to be broken and must be repaired.
+ *
+ * Same semantics as {@link TODO}: returns `never`, never throws, and
+ * runtime behaviour is delegated to the supplied callback (or the global
+ * `onFixme` from {@link defineConfig}).
+ *
+ * @param meta Structured description of the defect.
+ * @param cb Optional per-call handler; overrides the global `onFixme`.
+ * @returns Never — the function returns `undefined` typed as `never`.
+ */
+declare function FIXME(meta: FixmeMeta, cb?: (meta: FixmeMeta) => void): never;
+/**
+ * Marks a deliberate workaround that should be revisited.
+ *
+ * Same semantics as {@link TODO}: returns `never`, never throws, and
+ * runtime behaviour is delegated to the supplied callback (or the global
+ * `onHack` from {@link defineConfig}).
+ *
+ * @param meta Structured description of the workaround.
+ * @param cb Optional per-call handler; overrides the global `onHack`.
+ * @returns Never — the function returns `undefined` typed as `never`.
+ */
+declare function HACK(meta: HackMeta, cb?: (meta: HackMeta) => void): never;
+
+export { FIXME, FixmeError, HACK, HackError, NotImplementedError, TODO, UntodoError, defineConfig, getConfig, resetConfig };
+export type { AnyUntodoMeta, FixmeMeta, HackMeta, TodoMeta, UntodoConfig };

package/dist/index.mjs

@@ -0,0 +1,66 @@
+class UntodoError extends Error {
+  /**
+   * @param message Human-readable error message.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "UntodoError";
+  }
+}
+class NotImplementedError extends UntodoError {
+  /**
+   * @param message Human-readable error message.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "NotImplementedError";
+  }
+}
+class FixmeError extends UntodoError {
+  /**
+   * @param message Human-readable error message.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "FixmeError";
+  }
+}
+class HackError extends UntodoError {
+  /**
+   * @param message Human-readable error message.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "HackError";
+  }
+}
+
+let currentConfig = {};
+function defineConfig(config) {
+  currentConfig = config;
+  return config;
+}
+function getConfig() {
+  return currentConfig;
+}
+function resetConfig() {
+  currentConfig = {};
+}
+
+function TODO(meta, cb) {
+  const handler = cb ?? getConfig().onTodo;
+  handler?.(meta);
+  return void 0;
+}
+function FIXME(meta, cb) {
+  const handler = cb ?? getConfig().onFixme;
+  handler?.(meta);
+  return void 0;
+}
+function HACK(meta, cb) {
+  const handler = cb ?? getConfig().onHack;
+  handler?.(meta);
+  return void 0;
+}
+
+export { FIXME, FixmeError, HACK, HackError, NotImplementedError, TODO, UntodoError, defineConfig, getConfig, resetConfig };

package/package.json

@@ -0,0 +1,76 @@
+{
+    "name": "untodo",
+    "version": "0.0.1-alpha.0",
+    "description": "Type-safe replacement for TODO/FIXME/HACK comments — trackable in IDE, enforceable by lint and the type system.",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.cjs"
+        },
+        "./eslint": {
+            "types": "./dist/eslint.d.ts",
+            "import": "./dist/eslint.mjs",
+            "require": "./dist/eslint.cjs"
+        }
+    },
+    "bin": {
+        "untodo": "./dist/cli.mjs"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "unbuild",
+        "test": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix"
+    },
+    "keywords": [
+        "todo",
+        "fixme",
+        "hack",
+        "type-safe",
+        "eslint",
+        "eslint-plugin",
+        "oxlint",
+        "oxlint-plugin",
+        "unjs"
+    ],
+    "author": "Kanon",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/ysknsid25/untodo.git"
+    },
+    "license": "MIT",
+    "devDependencies": {
+        "@eslint/js": "^9.39.2",
+        "@stylistic/eslint-plugin": "^5.6.1",
+        "@types/node": "^22.10.1",
+        "@typescript-eslint/rule-tester": "^8.17.0",
+        "@typescript-eslint/utils": "^8.17.0",
+        "@vitest/coverage-v8": "^2.1.8",
+        "eslint": "^9.16.0",
+        "eslint-define-config": "^2.1.0",
+        "globals": "^16.5.0",
+        "typescript": "^5.7.2",
+        "typescript-eslint": "^8.49.0",
+        "unbuild": "^2.0.0",
+        "vitest": "^2.1.8"
+    },
+    "peerDependencies": {
+        "eslint": "^8.0.0 || ^9.0.0"
+    },
+    "peerDependenciesMeta": {
+        "eslint": {
+            "optional": true
+        }
+    }
+}