nalloc 0.4.0 → 0.5.1

package/src/__tests__/codemod.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect } from 'vitest';
+import { migrateSource, renderReport } from '../codemod.js';
+
+function migrate(source: string): ReturnType<typeof migrateSource> {
+  return migrateSource(source, 'fixture.ts');
+}
+
+describe('codemod', () => {
+  it('leaves files without neverthrow imports untouched', () => {
+    const source = `const xs = [1, 2].map(x => x * 2);\n`;
+    const result = migrate(source);
+    expect(result.changed).toBe(false);
+    expect(result.output).toBe(source);
+    expect(result.skipped).toEqual([]);
+  });
+
+  it('rewrites the import and converts provenant single-method calls', () => {
+    const source = [
+      `import { ok, err } from 'neverthrow';`,
+      `const r = ok(1);`,
+      `const d = r.map(x => x + 1);`,
+      `const e = d.andThen(x => x > 0 ? ok(x) : err('neg'));`,
+    ].join('\n');
+    const result = migrate(source);
+    expect(result.changed).toBe(true);
+    expect(result.output).toContain(`import { ok, err, Result } from 'nalloc';`);
+    expect(result.output).toContain(`const d = Result.map(r, x => x + 1);`);
+    expect(result.output).toContain(`const e = Result.flatMap(d, x => x > 0 ? ok(x) : err('neg'));`);
+    expect(result.output).not.toContain('neverthrow');
+    expect(result.skipped).toEqual([]);
+  });
+
+  it('preserves import aliases', () => {
+    const source = [`import { ok as okay } from 'neverthrow';`, `const r = okay(1);`, `const d = r.map(x => x + 1);`].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`import { ok as okay, Result } from 'nalloc';`);
+    expect(result.output).toContain(`Result.map(r, x => x + 1)`);
+  });
+
+  it('folds chains of two or more methods into pipe', () => {
+    const source = [`import { ok } from 'neverthrow';`, `const out = ok(1).map(a => a + 1).mapErr(String).unwrapOr(0);`].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`import { ok, Result, pipe } from 'nalloc';`);
+    expect(result.output).toContain(
+      `const out = pipe(ok(1), ($r) => Result.map($r, a => a + 1), ($r) => Result.mapErr($r, String), ($r) => Result.unwrapOr($r, 0));`,
+    );
+  });
+
+  it('does not touch bare .map calls without provenance', () => {
+    const source = [
+      `import { ok } from 'neverthrow';`,
+      `const xs = [1, 2].map(x => x * 2);`,
+      `declare const unknownValue: { map(fn: (x: number) => number): number[] };`,
+      `unknownValue.map(x => x);`,
+    ].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`[1, 2].map(x => x * 2)`);
+    expect(result.output).toContain(`unknownValue.map(x => x)`);
+  });
+
+  it('converts neverthrow-exclusive methods without provenance', () => {
+    const source = [`import { ok } from 'neverthrow';`, `declare const foreign: any;`, `const r = foreign.andThen((x: number) => ok(x));`].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`Result.flatMap(foreign, (x: number) => ok(x))`);
+  });
+
+  it('uses type annotations from neverthrow imports as provenance and renames the Result type', () => {
+    const source = [
+      `import { ok, Result } from 'neverthrow';`,
+      `const t: Result<number, string> = ok(2);`,
+      `const u = t.map(x => x * 2);`,
+      `function f(input: Result<number, string>): Result<number, string> { return input.mapErr(e => e); }`,
+    ].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`import { ok, Result, type ResultType } from 'nalloc';`);
+    expect(result.output).toContain(`const t: ResultType<number, string> = ok(2);`);
+    expect(result.output).toContain(`Result.map(t, x => x * 2)`);
+    expect(result.output).toContain(`function f(input: ResultType<number, string>): ResultType<number, string> { return Result.mapErr(input, e => e); }`);
+  });
+
+  it('converts fromThrowable to Result.wrap and tracks wrapped functions as provenance', () => {
+    const source = [
+      `import { fromThrowable } from 'neverthrow';`,
+      `const safeParse = fromThrowable(JSON.parse);`,
+      `const p = safeParse('{}');`,
+      `const q = p.map(v => v);`,
+    ].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`const safeParse = Result.wrap(JSON.parse);`);
+    expect(result.output).toContain(`Result.map(p, v => v)`);
+    expect(result.output).not.toContain('neverthrow');
+  });
+
+  it('converts combine and combineWithAllErrors including Result statics', () => {
+    const source = [
+      `import { ok, combine, Result } from 'neverthrow';`,
+      `const a = combine([ok(1), ok(2)]);`,
+      `const b = Result.combineWithAllErrors([ok(1)]);`,
+      `const c = Result.fromThrowable(JSON.parse);`,
+    ].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`const a = Result.all([ok(1), ok(2)]);`);
+    expect(result.output).toContain(`const b = Result.collectAll([ok(1)]);`);
+    expect(result.output).toContain(`const c = Result.wrap(JSON.parse);`);
+  });
+
+  it('converts directly-awaited fromPromise and treats its result as migrated', () => {
+    const source = [
+      `import { fromPromise } from 'neverthrow';`,
+      `async function run(p: Promise<number>) {`,
+      `  const r = await fromPromise(p, e => String(e));`,
+      `  return r.map(x => x + 1);`,
+      `}`,
+    ].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`await Result.fromPromise(p, e => String(e))`);
+    expect(result.output).toContain(`Result.map(r, x => x + 1)`);
+    expect(result.skipped).toEqual([]);
+    expect(result.output).not.toContain('neverthrow');
+  });
+
+  it('reports chained fromPromise as result-async and keeps the neverthrow import', () => {
+    const source = [`import { fromPromise } from 'neverthrow';`, `const ra = fromPromise(Promise.resolve(1), e => e).map(x => x);`].join('\n');
+    const result = migrate(source);
+    expect(result.skipped.map((s) => s.reason)).toContain('result-async');
+    expect(result.output).toContain(`import { fromPromise } from 'neverthrow';`);
+    expect(result.output).toContain(`fromPromise(Promise.resolve(1), e => e).map(x => x)`);
+  });
+
+  it('reports ResultAsync values and never converts methods on them', () => {
+    const source = [
+      `import { okAsync } from 'neverthrow';`,
+      `const ra = okAsync(1);`,
+      `const rb = ra.map(x => x + 1);`,
+      `async function f() { const r = await ra; return r.mapErr(e => e); }`,
+    ].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`const rb = ra.map(x => x + 1);`);
+    expect(result.output).toContain(`return r.mapErr(e => e);`);
+    expect(result.output).toContain(`import { okAsync } from 'neverthrow';`);
+    expect(result.skipped.some((s) => s.reason === 'result-async')).toBe(true);
+  });
+
+  it('reports safeTry for manual gen migration', () => {
+    const source = [`import { ok, safeTry } from 'neverthrow';`, `const r = safeTry(function* () { return ok(1); });`].join('\n');
+    const result = migrate(source);
+    expect(result.skipped.map((s) => s.reason)).toContain('safe-try');
+    expect(result.output).toContain(`import { safeTry } from 'neverthrow';`);
+  });
+
+  it('refuses whole chains containing unsupported methods', () => {
+    const source = [`import { ok } from 'neverthrow';`, `const r = ok(1).andThrough(x => ok(x)).map(x => x + 1);`].join('\n');
+    const result = migrate(source);
+    expect(result.skipped.map((s) => s.reason)).toContain('unsupported');
+    expect(result.output).toContain(`ok(1).andThrough(x => ok(x)).map(x => x + 1)`);
+  });
+
+  it('skips namespace imports entirely', () => {
+    const source = [`import * as nt from 'neverthrow';`, `const r = nt.ok(1);`].join('\n');
+    const result = migrate(source);
+    expect(result.changed).toBe(false);
+    expect(result.skipped.map((s) => s.reason)).toEqual(['namespace-import']);
+  });
+
+  it('converts nested chains inside chain arguments', () => {
+    const source = [`import { ok, err } from 'neverthrow';`, `const inner = ok(2);`, `const r = ok(1).andThen(x => inner.mapErr(e => e)).map(x => x);`].join(
+      '\n',
+    );
+    const result = migrate(source);
+    expect(result.output).toContain(`pipe(ok(1), ($r) => Result.flatMap($r, x => Result.mapErr(inner, e => e)), ($r) => Result.map($r, x => x))`);
+  });
+
+  it('converts match and unwrap accessors', () => {
+    const source = [
+      `import { ok } from 'neverthrow';`,
+      `const r = ok(1);`,
+      `const m = r.match(x => x, e => 0);`,
+      `const v = r._unsafeUnwrap();`,
+      `const o = r.isOk();`,
+    ].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`const m = Result.match(r, x => x, e => 0);`);
+    expect(result.output).toContain(`const v = Result.unwrap(r);`);
+    expect(result.output).toContain(`const o = Result.isOk(r);`);
+  });
+
+  it('drops provenance for conflicting bindings', () => {
+    const source = [
+      `import { ok } from 'neverthrow';`,
+      `function a() { const v = ok(1); return v; }`,
+      `function b() { const v = [1, 2]; return v.map(x => x); }`,
+    ].join('\n');
+    const result = migrate(source);
+    expect(result.output).toContain(`return v.map(x => x);`);
+  });
+
+  it('renders a grouped markdown report', () => {
+    const report = renderReport({
+      filesChanged: 1,
+      converted: 3,
+      skipped: [
+        { file: 'a.ts', line: 2, reason: 'result-async', text: 'okAsync(1)' },
+        { file: 'a.ts', line: 5, reason: 'safe-try', text: 'safeTry(fn)' },
+      ],
+    });
+    expect(report).toContain('# nalloc migration report');
+    expect(report).toContain('Files changed: 1. Sites converted: 3. Sites needing manual review: 2.');
+    expect(report).toContain('## a.ts');
+    expect(report).toContain('- line 2 [result-async]: `okAsync(1)`');
+  });
+});

package/src/__tests__/eslint.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import * as path from 'node:path';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import plugin, { rules, mustUse, noUnwrap } from '../eslint.js';
+
+describe('eslint plugin', () => {
+  it('exposes both rules with create + meta', () => {
+    for (const name of ['must-use', 'no-unwrap'] as const) {
+      expect(typeof rules[name].create).toBe('function');
+      expect(rules[name].meta.messages).toBeTypeOf('object');
+    }
+  });
+
+  it('wires the recommended config', () => {
+    expect(plugin.meta.name).toBe('nalloc');
+    const recommended = plugin.configs.recommended as { plugins: Record<string, unknown>; rules: Record<string, string> };
+    expect(recommended.plugins.nalloc).toBe(plugin);
+    expect(recommended.rules['nalloc/must-use']).toBe('error');
+    expect(recommended.rules['nalloc/no-unwrap']).toBe('error');
+  });
+});
+
+const typedTester = new RuleTester({
+  languageOptions: {
+    parserOptions: {
+      projectService: { allowDefaultProject: ['*.ts*'] },
+      tsconfigRootDir: path.join(import.meta.dirname, 'fixtures'),
+    },
+  },
+});
+
+typedTester.run('must-use', mustUse, {
+  valid: [
+    `type Result<T, E> = readonly [T] | { error: E }; declare function f(): Result<number, string>; const r = f();`,
+    `declare function g(): number; g();`,
+    `type Foo<T> = readonly [T]; declare function f(): Foo<number>; f();`,
+    {
+      code: `type Result<T, E> = readonly [T] | { error: E }; declare function f(): Result<number, string>; f();`,
+      options: [{ typeNames: ['Option'] }],
+    },
+  ],
+  invalid: [
+    {
+      code: `type Result<T, E> = readonly [T] | { error: E }; declare function f(): Result<number, string>; f();`,
+      errors: [{ messageId: 'mustUse', data: { name: 'Result' } }],
+    },
+    {
+      code: `type Option<T> = T | undefined; declare function f(): Option<number>; f();`,
+      errors: [{ messageId: 'mustUse', data: { name: 'Option' } }],
+    },
+    {
+      code: `type Result<T, E> = readonly [T] | { error: E }; declare function f(): Promise<Result<number, string>>; async function run() { await f(); }`,
+      errors: [{ messageId: 'mustUse', data: { name: 'Result' } }],
+    },
+    {
+      code: `type Mine<T> = readonly [T]; declare function f(): Mine<number>; f();`,
+      options: [{ typeNames: ['Mine'] }],
+      errors: [{ messageId: 'mustUse', data: { name: 'Mine' } }],
+    },
+  ],
+});
+
+const tester = new RuleTester({ languageOptions: { parserOptions: { sourceType: 'module' } } });
+
+tester.run('no-unwrap', noUnwrap, {
+  valid: [
+    `import { unwrap } from 'other-lib'; declare const r: unknown; unwrap(r);`,
+    `import { Result } from 'nalloc'; declare const r: unknown; Result.unwrapOr(r, 0);`,
+    `const Result = { unwrap(x: unknown) { return x; } }; Result.unwrap(1);`,
+    `function unwrap(x: unknown) { return x; } unwrap(1);`,
+  ],
+  invalid: [
+    {
+      code: `import { unwrap } from 'nalloc'; declare const r: unknown; unwrap(r);`,
+      errors: [{ messageId: 'noUnwrap', data: { name: 'unwrap' } }],
+    },
+    {
+      code: `import { Result } from 'nalloc'; declare const r: unknown; Result.unwrap(r);`,
+      errors: [{ messageId: 'noUnwrap', data: { name: 'unwrap' } }],
+    },
+    {
+      code: `import { Option } from 'nalloc'; declare const o: unknown; Option.expect(o, 'm');`,
+      errors: [{ messageId: 'noUnwrap', data: { name: 'expect' } }],
+    },
+    {
+      code: `import { Result } from 'nalloc'; declare const r: unknown; Result.unwrapErr(r);`,
+      errors: [{ messageId: 'noUnwrap', data: { name: 'unwrapErr' } }],
+    },
+    {
+      code: `import { unwrap as uw } from 'nalloc'; declare const r: unknown; uw(r);`,
+      errors: [{ messageId: 'noUnwrap', data: { name: 'unwrap' } }],
+    },
+    {
+      code: `import { unwrap } from '@me/x'; declare const r: unknown; unwrap(r);`,
+      options: [{ modules: ['@me/x'] }],
+      errors: [{ messageId: 'noUnwrap', data: { name: 'unwrap' } }],
+    },
+  ],
+});

package/src/__tests__/fixtures/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "esnext",
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "skipLibCheck": true,
+    "noEmit": true
+  }
+}

package/src/__tests__/http.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { fromResponse, fromFetch } from '../http.js';
+import { isOk, isErr } from '../types.js';
+
+describe('http', () => {
+  describe('fromResponse', () => {
+    it('returns Ok carrying the response for a 2xx status', () => {
+      const response = new Response('ok', { status: 200 });
+      const result = fromResponse(response);
+      expect(isOk(result)).toBe(true);
+      expect(result).toBe(response);
+    });
+
+    it('returns Err carrying the response for a non-2xx status', () => {
+      const response = new Response('nope', { status: 404 });
+      const result = fromResponse(response);
+      expect(isErr(result)).toBe(true);
+      expect((result as { error: Response }).error).toBe(response);
+    });
+  });
+
+  describe('fromFetch', () => {
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    it('returns Ok carrying the response for a 2xx status', async () => {
+      const response = new Response('ok', { status: 200 });
+      const fetchMock = vi.fn().mockResolvedValue(response);
+      vi.stubGlobal('fetch', fetchMock);
+      const init = { method: 'POST' };
+      const result = await fromFetch('https://example.test', init);
+      expect(isOk(result)).toBe(true);
+      expect(result).toBe(response);
+      expect(fetchMock).toHaveBeenCalledWith('https://example.test', init);
+    });
+
+    it('returns Err carrying the response for a non-2xx status', async () => {
+      const response = new Response('nope', { status: 500 });
+      vi.stubGlobal('fetch', vi.fn().mockResolvedValue(response));
+      const result = await fromFetch('https://example.test');
+      expect(isErr(result)).toBe(true);
+      expect((result as { error: Response }).error).toBe(response);
+    });
+
+    it('returns Err carrying the thrown value on transport failure', async () => {
+      const failure = new TypeError('fetch failed');
+      vi.stubGlobal('fetch', vi.fn().mockRejectedValue(failure));
+      const result = await fromFetch('https://example.test');
+      expect(isErr(result)).toBe(true);
+      expect((result as { error: unknown }).error).toBe(failure);
+    });
+
+    it('returns Err with an AbortError DOMException for a pre-aborted signal', async () => {
+      const controller = new AbortController();
+      controller.abort();
+      const result = await fromFetch('http://127.0.0.1:1', { signal: controller.signal });
+      expect(isErr(result)).toBe(true);
+      const error = (result as { error: unknown }).error;
+      expect(error).toBeInstanceOf(DOMException);
+      expect((error as DOMException).name).toBe('AbortError');
+    });
+  });
+});