untodo 0.0.1-alpha.0

package/dist/eslint.mjs

@@ -0,0 +1,122 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+const createRule = ESLintUtils.RuleCreator(
+  (name) => `https://github.com/ysknsid25/untodo/blob/main/docs/rules/${name}.md`
+);
+
+const noTodo = createRule({
+  name: "no-todo",
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow leftover `TODO()` calls."
+    },
+    schema: [],
+    messages: {
+      noTodo: "Unresolved TODO: {{reason}}"
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== "Identifier" || node.callee.name !== "TODO") {
+          return;
+        }
+        const reason = extractReason(node.arguments[0]);
+        context.report({
+          node,
+          messageId: "noTodo",
+          data: { reason: reason ?? "(no reason)" }
+        });
+      }
+    };
+  }
+});
+function extractReason(arg) {
+  if (typeof arg !== "object" || arg === null || arg.type !== "ObjectExpression") {
+    return void 0;
+  }
+  const props = arg.properties;
+  for (const prop of props) {
+    const p = prop;
+    if (p.type !== "Property")
+      continue;
+    const keyName = p.key?.type === "Identifier" ? p.key.name : p.key?.type === "Literal" ? String(p.key.value) : void 0;
+    if (keyName === "reason" && p.value?.type === "Literal") {
+      return String(p.value.value);
+    }
+  }
+  return void 0;
+}
+
+const noFixme = createRule({
+  name: "no-fixme",
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow leftover `FIXME()` calls."
+    },
+    schema: [],
+    messages: {
+      noFixme: "Unresolved FIXME call."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type === "Identifier" && node.callee.name === "FIXME") {
+          context.report({ node, messageId: "noFixme" });
+        }
+      }
+    };
+  }
+});
+
+const noHack = createRule({
+  name: "no-hack",
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Warn on `HACK()` calls."
+    },
+    schema: [],
+    messages: {
+      noHack: "HACK call detected \u2014 please justify or remove."
+    }
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type === "Identifier" && node.callee.name === "HACK") {
+          context.report({ node, messageId: "noHack" });
+        }
+      }
+    };
+  }
+});
+
+const rules = {
+  "no-todo": noTodo,
+  "no-fixme": noFixme,
+  "no-hack": noHack
+};
+const configs = {
+  recommended: [
+    {
+      rules: {
+        "untodo/no-todo": "warn",
+        "untodo/no-fixme": "warn",
+        "untodo/no-hack": "warn"
+      }
+    }
+  ]
+};
+const untodoPlugin = {
+  rules,
+  configs
+};
+
+export { untodoPlugin as default };

package/dist/index.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+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;
+}
+
+exports.FIXME = FIXME;
+exports.FixmeError = FixmeError;
+exports.HACK = HACK;
+exports.HackError = HackError;
+exports.NotImplementedError = NotImplementedError;
+exports.TODO = TODO;
+exports.UntodoError = UntodoError;
+exports.defineConfig = defineConfig;
+exports.getConfig = getConfig;
+exports.resetConfig = resetConfig;

package/dist/index.d.cts

@@ -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.d.mts

@@ -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 };