untodo 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# untodo
+
+Type-safe replacement for `// TODO:` comments.
+Trackable in your IDE, enforceable by lint, surfaced by the type system.
+
+> Status: **scaffold** — APIs are placeholders. See `Project Planning` in the repo for the design.
+
+## Why
+
+| Problem | Solution |
+|---|---|
+| `// TODO:` comments are easy to ignore | Function calls — lint can fail the build |
+| Comments don't reach the type system | Returns `never` so callers detect it |
+| No structure | Pass an object with `reason`, `issue`, etc. |
+| Hard to track in an IDE | "Find references" works on a function |
+
+Inspired by [Kotlin's `TODO()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-t-o-d-o.html).
+
+## Install
+
+```bash
+npm install untodo
+```
+
+## Usage
+
+```ts
+import { TODO, FIXME, HACK, defineConfig } from "untodo";
+
+function fetchUser(): User {
+  return TODO({ reason: "未実装" });
+}
+```
+
+`untodo.config.ts`:
+
+```ts
+import { defineConfig } from "untodo";
+
+export default defineConfig({
+  repo: "org/repo",
+  onTodo: (meta) => console.warn(`TODO: ${meta.reason}`),
+});
+```
+
+## ESLint plugin
+
+```ts
+// eslint.config.ts
+import untodoPlugin from "untodo/eslint";
+
+export default [
+  {
+    plugins: { untodo: untodoPlugin },
+    rules: {
+      "untodo/no-todo": "error",
+      "untodo/no-fixme": "error",
+      "untodo/no-hack": "warn",
+    },
+  },
+];
+```
+
+The same plugin works with [oxlint](https://oxc.rs/docs/guide/usage/linter.html)'s JS plugin support.
+
+## Scripts
+
+```bash
+npm run build          # unbuild
+npm test               # vitest run
+npm run test:coverage  # vitest run --coverage
+npm run lint           # eslint .
+npm run lint:fix       # eslint . --fix
+```
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+'use strict';
+
+const node_fs = require('node:fs');
+const node_path = require('node:path');
+
+const untodoConfigTemplate = `import { defineConfig } from 'untodo';
+
+export default defineConfig({
+  // repo: 'org/repo',
+  // onTodo: (meta) => console.warn(\`TODO: \${meta.reason}\`),
+  // onFixme: (meta) => console.error(\`FIXME: \${meta.reason}\`),
+  // onHack: (meta) => console.warn(\`HACK: \${meta.reason}\`),
+});
+`;
+const globalDtsTemplate = `declare module 'untodo' {
+  interface TodoMeta {
+    // issue?: number | string;
+    // assignee?: string;
+  }
+  interface FixmeMeta {
+    // issue?: number | string;
+  }
+  interface HackMeta {
+    // issue?: number | string;
+  }
+}
+
+export {};
+`;
+const eslintGuidance = `Add the plugin to your eslint.config.ts:
+
+  import untodoPlugin from 'untodo/eslint';
+
+  export default [
+    {
+      plugins: { untodo: untodoPlugin },
+      rules: {
+        'untodo/no-todo': 'error',
+        'untodo/no-fixme': 'error',
+        'untodo/no-hack': 'warn',
+      },
+    },
+  ];
+`;
+
+function runInit(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const log = options.log ?? console.log;
+  writeIfMissing(
+    node_path.resolve(cwd, "untodo.config.ts"),
+    untodoConfigTemplate,
+    options.force,
+    log
+  );
+  writeIfMissing(
+    node_path.resolve(cwd, "global.d.ts"),
+    globalDtsTemplate,
+    options.force,
+    log
+  );
+  log("");
+  log(eslintGuidance);
+}
+function writeIfMissing(path, content, force, log) {
+  if (!force && node_fs.existsSync(path)) {
+    log(`skip: ${path} (already exists)`);
+    return;
+  }
+  node_fs.writeFileSync(path, content, "utf8");
+  log(`wrote: ${path}`);
+}
+
+const [, , command, ...rest] = process.argv;
+if (command === "init") {
+  const force = rest.includes("--force") || rest.includes("-f");
+  runInit({ force });
+  process.exit(0);
+}
+console.log("Usage: untodo init [--force]");
+process.exit(command ? 1 : 0);

package/dist/cli.d.cts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/cli.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/cli.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const untodoConfigTemplate = `import { defineConfig } from 'untodo';
+
+export default defineConfig({
+  // repo: 'org/repo',
+  // onTodo: (meta) => console.warn(\`TODO: \${meta.reason}\`),
+  // onFixme: (meta) => console.error(\`FIXME: \${meta.reason}\`),
+  // onHack: (meta) => console.warn(\`HACK: \${meta.reason}\`),
+});
+`;
+const globalDtsTemplate = `declare module 'untodo' {
+  interface TodoMeta {
+    // issue?: number | string;
+    // assignee?: string;
+  }
+  interface FixmeMeta {
+    // issue?: number | string;
+  }
+  interface HackMeta {
+    // issue?: number | string;
+  }
+}
+
+export {};
+`;
+const eslintGuidance = `Add the plugin to your eslint.config.ts:
+
+  import untodoPlugin from 'untodo/eslint';
+
+  export default [
+    {
+      plugins: { untodo: untodoPlugin },
+      rules: {
+        'untodo/no-todo': 'error',
+        'untodo/no-fixme': 'error',
+        'untodo/no-hack': 'warn',
+      },
+    },
+  ];
+`;
+
+function runInit(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const log = options.log ?? console.log;
+  writeIfMissing(
+    resolve(cwd, "untodo.config.ts"),
+    untodoConfigTemplate,
+    options.force,
+    log
+  );
+  writeIfMissing(
+    resolve(cwd, "global.d.ts"),
+    globalDtsTemplate,
+    options.force,
+    log
+  );
+  log("");
+  log(eslintGuidance);
+}
+function writeIfMissing(path, content, force, log) {
+  if (!force && existsSync(path)) {
+    log(`skip: ${path} (already exists)`);
+    return;
+  }
+  writeFileSync(path, content, "utf8");
+  log(`wrote: ${path}`);
+}
+
+const [, , command, ...rest] = process.argv;
+if (command === "init") {
+  const force = rest.includes("--force") || rest.includes("-f");
+  runInit({ force });
+  process.exit(0);
+}
+console.log("Usage: untodo init [--force]");
+process.exit(command ? 1 : 0);

package/dist/eslint.cjs

@@ -0,0 +1,124 @@
+'use strict';
+
+const utils = require('@typescript-eslint/utils');
+
+const createRule = utils.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
+};
+
+module.exports = untodoPlugin;

package/dist/eslint.d.cts

@@ -0,0 +1,101 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+/**
+ * Rule factory used by every untodo lint rule.
+ *
+ * Wraps `ESLintUtils.RuleCreator` so each rule's `meta.docs.url` resolves to
+ * `https://github.com/ysknsid25/untodo/blob/main/docs/rules/<name>.md`.
+ */
+declare const createRule: ReturnType<typeof ESLintUtils.RuleCreator>;
+
+type Options$2 = [];
+type MessageIds$2 = 'noTodo';
+/**
+ * `untodo/no-todo` — flags every call to the `TODO()` function exported by
+ * `untodo`. Intended to fail CI once an unimplemented code path is in main.
+ *
+ * @example
+ * ```ts
+ * // Reported:
+ * function fetchUser() { return TODO({ reason: 'unimplemented' }); }
+ * ```
+ */
+declare const noTodo: ReturnType<typeof createRule<Options$2, MessageIds$2>>;
+
+type Options$1 = [];
+type MessageIds$1 = 'noFixme';
+/**
+ * `untodo/no-fixme` — flags every call to the `FIXME()` function exported by
+ * `untodo`. Intended to surface known defects that have escaped main.
+ */
+declare const noFixme: ReturnType<typeof createRule<Options$1, MessageIds$1>>;
+
+type Options = [];
+type MessageIds = 'noHack';
+/**
+ * `untodo/no-hack` — flags every call to the `HACK()` function exported by
+ * `untodo`. Typically configured as a `warn` to nudge revisits without
+ * blocking merges.
+ */
+declare const noHack: ReturnType<typeof createRule<Options, MessageIds>>;
+
+/**
+ * untodo ESLint / oxlint plugin.
+ *
+ * Ships three rules that flag leftover `TODO()`, `FIXME()` and `HACK()`
+ * calls from the `untodo` runtime. Compatible with ESLint v9 flat config
+ * and oxlint's JS plugin support.
+ *
+ * @example ESLint flat config
+ * ```ts
+ * import untodoPlugin from 'untodo/eslint';
+ *
+ * export default [
+ *     {
+ *         plugins: { untodo: untodoPlugin },
+ *         rules: {
+ *             'untodo/no-todo': 'error',
+ *             'untodo/no-fixme': 'error',
+ *             'untodo/no-hack': 'warn',
+ *         },
+ *     },
+ * ];
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * Map of rule name → rule definition exposed by the plugin.
+ */
+interface UntodoPluginRules {
+    'no-todo': typeof noTodo;
+    'no-fixme': typeof noFixme;
+    'no-hack': typeof noHack;
+}
+/**
+ * Single entry inside `configs.recommended` — an ESLint flat config block
+ * containing only rule severities.
+ */
+interface UntodoRecommendedConfig {
+    rules: Record<string, 'off' | 'warn' | 'error'>;
+}
+/**
+ * Shape of the default-exported plugin object.
+ */
+interface UntodoPlugin {
+    rules: UntodoPluginRules;
+    configs: {
+        recommended: UntodoRecommendedConfig[];
+    };
+}
+/**
+ * The plugin object consumed by ESLint / oxlint.
+ *
+ * Register it under the `untodo` namespace so rule IDs resolve to
+ * `untodo/no-todo`, `untodo/no-fixme`, `untodo/no-hack`.
+ */
+declare const untodoPlugin: UntodoPlugin;
+
+export { untodoPlugin as default };
+export type { UntodoPlugin, UntodoPluginRules, UntodoRecommendedConfig };

package/dist/eslint.d.mts

@@ -0,0 +1,101 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+/**
+ * Rule factory used by every untodo lint rule.
+ *
+ * Wraps `ESLintUtils.RuleCreator` so each rule's `meta.docs.url` resolves to
+ * `https://github.com/ysknsid25/untodo/blob/main/docs/rules/<name>.md`.
+ */
+declare const createRule: ReturnType<typeof ESLintUtils.RuleCreator>;
+
+type Options$2 = [];
+type MessageIds$2 = 'noTodo';
+/**
+ * `untodo/no-todo` — flags every call to the `TODO()` function exported by
+ * `untodo`. Intended to fail CI once an unimplemented code path is in main.
+ *
+ * @example
+ * ```ts
+ * // Reported:
+ * function fetchUser() { return TODO({ reason: 'unimplemented' }); }
+ * ```
+ */
+declare const noTodo: ReturnType<typeof createRule<Options$2, MessageIds$2>>;
+
+type Options$1 = [];
+type MessageIds$1 = 'noFixme';
+/**
+ * `untodo/no-fixme` — flags every call to the `FIXME()` function exported by
+ * `untodo`. Intended to surface known defects that have escaped main.
+ */
+declare const noFixme: ReturnType<typeof createRule<Options$1, MessageIds$1>>;
+
+type Options = [];
+type MessageIds = 'noHack';
+/**
+ * `untodo/no-hack` — flags every call to the `HACK()` function exported by
+ * `untodo`. Typically configured as a `warn` to nudge revisits without
+ * blocking merges.
+ */
+declare const noHack: ReturnType<typeof createRule<Options, MessageIds>>;
+
+/**
+ * untodo ESLint / oxlint plugin.
+ *
+ * Ships three rules that flag leftover `TODO()`, `FIXME()` and `HACK()`
+ * calls from the `untodo` runtime. Compatible with ESLint v9 flat config
+ * and oxlint's JS plugin support.
+ *
+ * @example ESLint flat config
+ * ```ts
+ * import untodoPlugin from 'untodo/eslint';
+ *
+ * export default [
+ *     {
+ *         plugins: { untodo: untodoPlugin },
+ *         rules: {
+ *             'untodo/no-todo': 'error',
+ *             'untodo/no-fixme': 'error',
+ *             'untodo/no-hack': 'warn',
+ *         },
+ *     },
+ * ];
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * Map of rule name → rule definition exposed by the plugin.
+ */
+interface UntodoPluginRules {
+    'no-todo': typeof noTodo;
+    'no-fixme': typeof noFixme;
+    'no-hack': typeof noHack;
+}
+/**
+ * Single entry inside `configs.recommended` — an ESLint flat config block
+ * containing only rule severities.
+ */
+interface UntodoRecommendedConfig {
+    rules: Record<string, 'off' | 'warn' | 'error'>;
+}
+/**
+ * Shape of the default-exported plugin object.
+ */
+interface UntodoPlugin {
+    rules: UntodoPluginRules;
+    configs: {
+        recommended: UntodoRecommendedConfig[];
+    };
+}
+/**
+ * The plugin object consumed by ESLint / oxlint.
+ *
+ * Register it under the `untodo` namespace so rule IDs resolve to
+ * `untodo/no-todo`, `untodo/no-fixme`, `untodo/no-hack`.
+ */
+declare const untodoPlugin: UntodoPlugin;
+
+export { untodoPlugin as default };
+export type { UntodoPlugin, UntodoPluginRules, UntodoRecommendedConfig };

package/dist/eslint.d.ts

@@ -0,0 +1,101 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+/**
+ * Rule factory used by every untodo lint rule.
+ *
+ * Wraps `ESLintUtils.RuleCreator` so each rule's `meta.docs.url` resolves to
+ * `https://github.com/ysknsid25/untodo/blob/main/docs/rules/<name>.md`.
+ */
+declare const createRule: ReturnType<typeof ESLintUtils.RuleCreator>;
+
+type Options$2 = [];
+type MessageIds$2 = 'noTodo';
+/**
+ * `untodo/no-todo` — flags every call to the `TODO()` function exported by
+ * `untodo`. Intended to fail CI once an unimplemented code path is in main.
+ *
+ * @example
+ * ```ts
+ * // Reported:
+ * function fetchUser() { return TODO({ reason: 'unimplemented' }); }
+ * ```
+ */
+declare const noTodo: ReturnType<typeof createRule<Options$2, MessageIds$2>>;
+
+type Options$1 = [];
+type MessageIds$1 = 'noFixme';
+/**
+ * `untodo/no-fixme` — flags every call to the `FIXME()` function exported by
+ * `untodo`. Intended to surface known defects that have escaped main.
+ */
+declare const noFixme: ReturnType<typeof createRule<Options$1, MessageIds$1>>;
+
+type Options = [];
+type MessageIds = 'noHack';
+/**
+ * `untodo/no-hack` — flags every call to the `HACK()` function exported by
+ * `untodo`. Typically configured as a `warn` to nudge revisits without
+ * blocking merges.
+ */
+declare const noHack: ReturnType<typeof createRule<Options, MessageIds>>;
+
+/**
+ * untodo ESLint / oxlint plugin.
+ *
+ * Ships three rules that flag leftover `TODO()`, `FIXME()` and `HACK()`
+ * calls from the `untodo` runtime. Compatible with ESLint v9 flat config
+ * and oxlint's JS plugin support.
+ *
+ * @example ESLint flat config
+ * ```ts
+ * import untodoPlugin from 'untodo/eslint';
+ *
+ * export default [
+ *     {
+ *         plugins: { untodo: untodoPlugin },
+ *         rules: {
+ *             'untodo/no-todo': 'error',
+ *             'untodo/no-fixme': 'error',
+ *             'untodo/no-hack': 'warn',
+ *         },
+ *     },
+ * ];
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * Map of rule name → rule definition exposed by the plugin.
+ */
+interface UntodoPluginRules {
+    'no-todo': typeof noTodo;
+    'no-fixme': typeof noFixme;
+    'no-hack': typeof noHack;
+}
+/**
+ * Single entry inside `configs.recommended` — an ESLint flat config block
+ * containing only rule severities.
+ */
+interface UntodoRecommendedConfig {
+    rules: Record<string, 'off' | 'warn' | 'error'>;
+}
+/**
+ * Shape of the default-exported plugin object.
+ */
+interface UntodoPlugin {
+    rules: UntodoPluginRules;
+    configs: {
+        recommended: UntodoRecommendedConfig[];
+    };
+}
+/**
+ * The plugin object consumed by ESLint / oxlint.
+ *
+ * Register it under the `untodo` namespace so rule IDs resolve to
+ * `untodo/no-todo`, `untodo/no-fixme`, `untodo/no-hack`.
+ */
+declare const untodoPlugin: UntodoPlugin;
+
+export { untodoPlugin as default };
+export type { UntodoPlugin, UntodoPluginRules, UntodoRecommendedConfig };