@opentask/taskin-task-manager 3.1.0 → 3.2.0

package/src/ordenar-tarefas/ordenar-tarefas.test.ts

@@ -0,0 +1,92 @@
+import type { Task } from '@opentask/taskin-types';
+import { parseGroupId, parseTaskId } from '@opentask/taskin-types';
+import { describe, expect, it } from 'vitest';
+import { agruparTarefas, ordenarTarefas } from './ordenar-tarefas.js';
+
+const t = (id: string, extra: Partial<Task> = {}): Task =>
+  ({ id: parseTaskId(id), title: `Tarefa ${id}`, status: 'pending', type: 'feat', ...extra }) as Task;
+
+const ids = (ts: readonly Task[]) => ts.map((x) => String(x.id));
+
+/**
+ * A ordenacao que o dashboard ja usava, agora onde as tres superficies alcancam.
+ *
+ * Ela vivia em `use-prioritization.ts`, dentro do pacote **Vue** — inalcancavel
+ * para a CLI e para o servidor MCP. O `taskin list` devolvia as tarefas na
+ * ordem em que o provider as achava, que na pratica e por id: a coluna de
+ * prioridade subia e descia sem padrao, e quem lia precisava reordenar de
+ * cabeca. Foi assim que um agente autonomo escolheu uma tarefa de prioridade 30
+ * tendo uma de 255 na mesma lista.
+ */
+describe('ordenarTarefas', () => {
+  it('manual ordena por prioridade, com quem nao tem por ultimo', () => {
+    const tarefas = [t('001', { order: 30 }), t('002'), t('003', { order: 10 })];
+
+    expect(ids(ordenarTarefas(tarefas, 'manual'))).toEqual(['003', '001', '002']);
+  });
+
+  it('manual e estavel entre empatados', () => {
+    const tarefas = [t('001', { order: 10 }), t('002', { order: 10 }), t('003', { order: 10 })];
+
+    expect(ids(ordenarTarefas(tarefas, 'manual'))).toEqual(['001', '002', '003']);
+  });
+
+  it('difficulty ordena do mais facil ao mais dificil, e o inverso', () => {
+    const tarefas = [t('001', { difficulty: 5 }), t('002', { difficulty: 1 }), t('003', { difficulty: 3 })];
+
+    expect(ids(ordenarTarefas(tarefas, 'diff-asc'))).toEqual(['002', '003', '001']);
+    expect(ids(ordenarTarefas(tarefas, 'diff-desc'))).toEqual(['001', '003', '002']);
+  });
+
+  it('nao altera a lista recebida', () => {
+    const tarefas = [t('001', { order: 30 }), t('002', { order: 10 })];
+    ordenarTarefas(tarefas, 'manual');
+
+    expect(ids(tarefas)).toEqual(['001', '002']);
+  });
+});
+
+/**
+ * Agrupar e separado de ordenar, e de proposito.
+ *
+ * No dashboard as duas coisas vinham juntas porque a arvore era so para
+ * desenhar caixas. Na saida de maquina quem consome decide — e separar deixa a
+ * CLI ordenar sem agrupar quando ninguem pediu grupo.
+ */
+describe('agruparTarefas', () => {
+  const g1 = parseGroupId('g-1');
+
+  it('junta membros do mesmo grupo, esteja onde estiver na ordem', () => {
+    const tarefas = [t('001', { groupId: g1 }), t('002'), t('003', { groupId: g1 })];
+
+    const nos = agruparTarefas(tarefas, { 'g-1': 'Sprint' });
+
+    expect(nos).toHaveLength(2);
+    expect(nos[0]).toMatchObject({ kind: 'group', groupId: 'g-1', groupName: 'Sprint', hidden: 0 });
+    expect(nos[0]?.kind === 'group' && ids(nos[0].tasks)).toEqual(['001', '003']);
+  });
+
+  /*
+   * O grupo parcial, decidido: mostra os membros que casam, e diz quantos o
+   * filtro escondeu. Nunca alarga o filtro para trazer o grupo inteiro.
+   */
+  it('diz quantos membros o filtro deixou de fora', () => {
+    const tarefas = [t('001', { groupId: g1 })];
+
+    const nos = agruparTarefas(tarefas, { 'g-1': 'Sprint' }, { 'g-1': 7 });
+
+    expect(nos[0]).toMatchObject({ kind: 'group', hidden: 6 });
+  });
+
+  it('tarefa sem grupo fica solta, na ordem em que veio', () => {
+    const nos = agruparTarefas([t('001'), t('002')], {});
+
+    expect(nos.map((n) => n.kind)).toEqual(['task', 'task']);
+  });
+
+  it('grupo sem nome no registro ainda aparece, pelo id', () => {
+    const nos = agruparTarefas([t('001', { groupId: g1 })], {});
+
+    expect(nos[0]).toMatchObject({ kind: 'group', groupId: 'g-1', groupName: undefined });
+  });
+});

package/src/ordenar-tarefas/ordenar-tarefas.ts

@@ -0,0 +1,135 @@
+import type { Task } from '@opentask/taskin-types';
+
+/**
+ * Como uma listagem pode ser ordenada.
+ *
+ * O mesmo vocabulario que o quadro de priorizacao do dashboard usa. Manter as
+ * grafias iguais entre as superficies vale mais que elegancia local: quem le a
+ * documentacao de uma reconhece a outra.
+ *
+ * @public
+ */
+export type ModoDeOrdenacao = 'manual' | 'diff-asc' | 'diff-desc';
+
+/**
+ * O que a ordenacao precisa saber, e nada alem disso.
+ *
+ * Exigir `Task` inteira deixaria a funcao inalcancavel para quem tem outra
+ * forma de tarefa — o quadro de priorizacao do dashboard, por exemplo, usa um
+ * modelo de tela proprio. Pedir so os dois campos que ela le e o que permite as
+ * duas superficies compartilharem a regra em vez de cada uma ter a sua copia.
+ *
+ * @public
+ */
+export interface OrdenavelPorPrioridade {
+  readonly order?: number;
+  readonly difficulty?: number;
+}
+
+/** Um no da listagem: uma tarefa solta, ou um grupo com os membros que casaram. */
+export type NoDaListagem<TTask extends Task = Task> =
+  | { readonly kind: 'task'; readonly task: TTask }
+  | {
+      readonly kind: 'group';
+      readonly groupId: string;
+      /** `undefined` quando o registro nao conhece o grupo. */
+      readonly groupName: string | undefined;
+      readonly tasks: readonly TTask[];
+      /** Quantos membros o filtro deixou de fora. Zero quando o grupo veio inteiro. */
+      readonly hidden: number;
+    };
+
+/**
+ * Ordena uma listagem, sem alterar a lista recebida.
+ *
+ * Vivia dentro do pacote Vue do dashboard, inalcancavel para a CLI e para o
+ * servidor MCP — e por isso `taskin list` devolvia as tarefas na ordem em que o
+ * provider as achava, que na pratica e por id.
+ *
+ * `manual` usa o `order`, com quem nao tem por ultimo e estabilidade no resto.
+ * Os dois modos de dificuldade usam o `difficulty`.
+ *
+ * @public
+ */
+export function ordenarTarefas<TTask extends OrdenavelPorPrioridade>(
+  tarefas: readonly TTask[],
+  modo: ModoDeOrdenacao = 'manual',
+): TTask[] {
+  const comIndice = tarefas.map((task, index) => ({ task, index }));
+
+  const campo = (t: TTask) => (modo === 'manual' ? t.order : t.difficulty);
+  const sinal = modo === 'diff-desc' ? -1 : 1;
+
+  comIndice.sort((a, b) => {
+    const va = campo(a.task);
+    const vb = campo(b.task);
+
+    // Quem nao tem valor vai para o fim, qualquer que seja a direcao.
+    if (va === undefined && vb === undefined) return a.index - b.index;
+    if (va === undefined) return 1;
+    if (vb === undefined) return -1;
+    if (va !== vb) return (va - vb) * sinal;
+
+    return a.index - b.index;
+  });
+
+  return comIndice.map(({ task }) => task);
+}
+
+/**
+ * Junta os membros de um grupo num no so, **por identidade**.
+ *
+ * Separado de {@link ordenarTarefas} de proposito. No dashboard as duas coisas
+ * vinham juntas porque a arvore existia para desenhar caixas; aqui quem consome
+ * decide se quer agrupar.
+ *
+ * Agrupa pelo `groupId`, e nao por adjacencia: membros separados por um filtro
+ * ou por uma ordenacao continuam sendo **um** grupo. Agrupar por adjacencia era
+ * o defeito da task-072, que partia o mesmo grupo em dois nos com o mesmo nome.
+ *
+ * @param tarefas - Ja ordenadas; a ordem dos grupos segue a do primeiro membro
+ * @param nomes - O que o registro de grupos sabe, por id
+ * @param totais - Quantos membros cada grupo tem **antes** do filtro. O que
+ *   falta vira `hidden`, para o leitor saber que nao esta vendo o grupo inteiro
+ *   em vez de o filtro se alargar sozinho e trazer o resto.
+ * @public
+ */
+export function agruparTarefas<TTask extends Task>(
+  tarefas: readonly TTask[],
+  nomes: Readonly<Record<string, string>> = {},
+  totais: Readonly<Record<string, number>> = {},
+): NoDaListagem<TTask>[] {
+  const nos: NoDaListagem<TTask>[] = [];
+  const porGrupo = new Map<string, TTask[]>();
+
+  for (const task of tarefas) {
+    const id = task.groupId === undefined ? undefined : String(task.groupId);
+
+    if (id === undefined) {
+      nos.push({ kind: 'task', task });
+      continue;
+    }
+
+    const existente = porGrupo.get(id);
+    if (existente) {
+      existente.push(task);
+      continue;
+    }
+
+    const membros = [task];
+    porGrupo.set(id, membros);
+    nos.push({
+      kind: 'group',
+      groupId: id,
+      groupName: nomes[id],
+      tasks: membros,
+      hidden: 0,
+    });
+  }
+
+  return nos.map((no) =>
+    no.kind === 'group'
+      ? { ...no, hidden: Math.max(0, (totais[no.groupId] ?? no.tasks.length) - no.tasks.length) }
+      : no,
+  );
+}

package/src/task-manager.ts

@@ -1,7 +1,10 @@
 import type { Task, TaskId, TaskStatus } from '@opentask/taskin-types';
+import type { IGroupRegistry } from './group-registry.types';
+import { numerarPrioridade } from './numerar-prioridade/index';
 import type {
   CreateTaskOptions,
   CreateTaskResult,
+  CriterioEmAberto,
   ITaskManager,
   ITaskProvider,
   LintResult,
@@ -76,6 +79,62 @@ export class TaskManager<TTask extends Task = Task> implements ITaskManager<TTas
     return await this.taskProvider.getAllTasks();
   }
 
+  /** Repassa o registro do provider, quando ele tem um. */
+  get groupRegistry(): IGroupRegistry | undefined {
+    return (this.taskProvider as { groupRegistry?: IGroupRegistry }).groupRegistry;
+  }
+
+  async prioritizeAll(options: { dryRun?: boolean } = {}): Promise<{
+    total: number;
+    withoutPriority: number;
+    changed: number;
+  }> {
+    const tarefas = await this.taskProvider.getAllTasks();
+
+    /*
+     * Quem ja tem numero define a ordem; quem nao tem entra depois, na sequencia
+     * em que o provider devolveu.
+     */
+    const ordenadas = [...tarefas].sort((a, b) => {
+      if (a.order === undefined && b.order === undefined) return 0;
+      if (a.order === undefined) return 1;
+      if (b.order === undefined) return -1;
+      return a.order - b.order;
+    });
+
+    const mudancas = numerarPrioridade(ordenadas);
+    const semNumero = tarefas.filter((t) => t.order === undefined).length;
+
+    if (!options.dryRun) {
+      for (const tarefa of mudancas) {
+        await this.taskProvider.updateTask(tarefa as TTask);
+      }
+    }
+
+    return { total: tarefas.length, withoutPriority: semNumero, changed: mudancas.length };
+  }
+
+  /**
+   * Conclui a tarefa e **relata** o que ficou em aberto.
+   *
+   * Avisa, e nao recusa. Fechar uma tarefa e um gesto que acontece uma vez,
+   * muitas vezes com pressa; recusar ali torna o comando fragil e ensina a
+   * contornar. O portao duro vive no `lint`, que roda em CI e quebra o build —
+   * aqui o papel e dizer, no momento em que a pessoa ainda esta olhando, o que
+   * ficou para tras.
+   *
+   * Um provider sem a capacidade conclui sem portao nenhum.
+   */
+  async finishTaskComRelato(taskId: TaskId): Promise<{ task: TTask; blockers: CriterioEmAberto[] }> {
+    const task = await this.taskProvider.findTask(taskId);
+    if (!task) throw new Error(`Task with ID '${taskId}' not found.`);
+
+    const blockers = (await this.taskProvider.getCompletionBlockers?.(task)) ?? [];
+    const atualizada = await this.finishTask(taskId);
+
+    return { task: atualizada, blockers };
+  }
+
   async finishTask(taskId: TaskId): Promise<TTask> {
     const task = await this.taskProvider.findTask(taskId);
 

package/src/task-manager.types.ts

@@ -1,4 +1,5 @@
 import type { Task, TaskId, TaskType } from '@opentask/taskin-types';
+import type { IGroupRegistry } from './group-registry.types.js';
 
 /**
  * Options for creating a new task
@@ -40,6 +41,14 @@ export type ValidationSeverity = 'error' | 'warning' | 'info';
  * A validation error or warning found during linting
  * @public
  */
+/** Um criterio que ainda impede a conclusao. */
+export interface CriterioEmAberto {
+  /** O texto do item, como escrito. */
+  readonly texto: string;
+  /** Onde ele esta, quando a fonte sabe dizer. */
+  readonly linha?: number;
+}
+
 export interface ValidationIssue {
   /** The file or task that has the issue */
   file: string;
@@ -130,6 +139,20 @@ export interface ITaskProvider<TTask extends Task = Task> {
    * @returns The lint result with any validation issues found
    */
   lint: (fix?: boolean) => Promise<LintResult>;
+
+  /**
+   * Os criterios de conclusao que ainda bloqueiam esta tarefa, se a fonte tiver
+   * o conceito.
+   *
+   * **Opcional de proposito.** Checklist e uma forma do provider de arquivos: o
+   * Jira tem subtarefas, o GitHub tem itens de lista na descricao. Um provider
+   * sem nada equivalente simplesmente nao implementa, e o `finishTask` conclui
+   * sem portao — em vez de chamar algo que falha.
+   *
+   * O conceito e de dominio ("o que falta para isto estar pronto?"); a
+   * representacao e de provider.
+   */
+  getCompletionBlockers?: (task: TTask) => Promise<CriterioEmAberto[]>;
 }
 
 /**
@@ -166,6 +189,52 @@ export interface ITaskManager<TTask extends Task = Task> {
    */
   getAllTasks: () => Promise<TTask[]>;
 
+  /**
+   * Da a cada tarefa um numero de prioridade, de uma vez.
+   *
+   * E operacao de dominio, e nao um `updateTask` generico, por dois motivos.
+   *
+   * O primeiro e de desenho: a regra da numeracao — preservar a ordem, manter o
+   * numero de quem ja tem, abrir espaco quando faltar — passa a viver num lugar
+   * so, em vez de ser reescrita pela CLI e pelo servidor MCP.
+   *
+   * O segundo e de tipo: um metodo que **consome** `TTask` torna a interface
+   * contravariante nele, e um `ITaskManager<TarefaEspecifica>` deixa de poder
+   * ser usado onde se espera `ITaskManager<Task>`. Uma operacao que so devolve
+   * numeros nao tem esse problema.
+   *
+   * Existe porque um projeto **meio numerado** cobra caro: mover uma tarefa do
+   * meio da regiao sem numero reescreve todos os antecessores — 124 arquivos num
+   * projeto de 500, medido. Depois desta operacao, todo movimento custa um.
+   *
+   * @param options - `dryRun` apenas conta, sem gravar
+   * @returns Quantas existem, quantas estavam sem numero, e quantas mudaram
+   */
+  /**
+   * Os grupos, quando a fonte tem o conceito — `undefined` quando nao tem.
+   *
+   * Opcional de proposito: o GitHub mapeia para milestone, o Redmine para
+   * categoria, e uma fonte sem nada equivalente simplesmente nao oferece. Quem
+   * consome descobre pela ausencia, em vez de chamar algo que falha.
+   */
+  readonly groupRegistry?: IGroupRegistry;
+
+  /**
+   * Conclui a tarefa e relata os criterios que ficaram em aberto.
+   *
+   * Avisa, e nao recusa: fechar e um gesto unico, muitas vezes com pressa, e
+   * recusar ali torna o comando fragil. O portao duro vive no `lint`.
+   *
+   * O relato vem vazio quando o provider nao tem o conceito de checklist.
+   */
+  finishTaskComRelato: (taskId: TaskId) => Promise<{ task: TTask; blockers: CriterioEmAberto[] }>;
+
+  prioritizeAll: (options?: { dryRun?: boolean }) => Promise<{
+    total: number;
+    withoutPriority: number;
+    changed: number;
+  }>;
+
   /**
    * Mark a task as ready for review.
    * Transitions the task from 'in-progress' to 'in-review' status.
@@ -209,4 +278,18 @@ export interface ITaskManager<TTask extends Task = Task> {
    * @returns The lint result with any validation issues found
    */
   lint: (fix?: boolean) => Promise<LintResult>;
+
+  /**
+   * Os criterios de conclusao que ainda bloqueiam esta tarefa, se a fonte tiver
+   * o conceito.
+   *
+   * **Opcional de proposito.** Checklist e uma forma do provider de arquivos: o
+   * Jira tem subtarefas, o GitHub tem itens de lista na descricao. Um provider
+   * sem nada equivalente simplesmente nao implementa, e o `finishTask` conclui
+   * sem portao — em vez de chamar algo que falha.
+   *
+   * O conceito e de dominio ("o que falta para isto estar pronto?"); a
+   * representacao e de provider.
+   */
+  getCompletionBlockers?: (task: TTask) => Promise<CriterioEmAberto[]>;
 }

package/src/testing.ts

@@ -0,0 +1,8 @@
+/**
+ * Contratos que as implementacoes provam contra si mesmas.
+ *
+ * Exportado por `@opentask/taskin-task-manager/testing` para o `vitest` nunca
+ * entrar no grafo de execucao do pacote.
+ */
+export * from './group-registry.contract.js';
+export * from './user-registry.contract.js';

package/src/user-registry.contract.ts

@@ -40,7 +40,7 @@ export function runUserRegistryContractTests(createSubject: () => Promise<IUserR
         const user = registry.resolveUser('joao.silva');
         expect(user).toBeDefined();
         expect(user!.id).toBe('joao.silva');
-        expect(user!.avatar).toMatch(/^https:\/\/www\.gravatar\.com\/avatar\/[a-f0-9]{32}\?d=mp$/);
+        expect(user!.avatarHash).toMatch(/^[a-f0-9]{32}$/);
       });
 
       it('should return user by name (case-insensitive)', async () => {
@@ -54,7 +54,7 @@ export function runUserRegistryContractTests(createSubject: () => Promise<IUserR
         const user = registry.resolveUser('Maria Souza');
         expect(user).toBeDefined();
         expect(user!.id).toBe('maria');
-        expect(user!.avatar).toMatch(/^https:\/\/www\.gravatar\.com\/avatar\/[a-f0-9]{32}\?d=mp$/);
+        expect(user!.avatarHash).toMatch(/^[a-f0-9]{32}$/);
       });
 
       it('should return undefined for unknown user', async () => {
@@ -65,21 +65,21 @@ export function runUserRegistryContractTests(createSubject: () => Promise<IUserR
     });
 
     describe('createTemporaryUser', () => {
-      it('should create user with Gravatar URL', async () => {
+      it('should create user with an avatar identity hash', async () => {
         const registry = await createSubject();
         const user = registry.createTemporaryUser('Carlos');
 
         expect(user.id).toBe('carlos');
         expect(user.name).toBe('Carlos');
         expect(user.email).toBe('carlos@example.com');
-        expect(user.avatar).toMatch(/^https:\/\/www\.gravatar\.com\/avatar\/[a-f0-9]{32}\?d=mp$/);
+        expect(user.avatarHash).toMatch(/^[a-f0-9]{32}$/);
       });
 
-      it('should create different Gravatar URLs for different inputs', async () => {
+      it('should create different avatar hashes for different inputs', async () => {
         const registry = await createSubject();
         const user1 = registry.createTemporaryUser('Alice');
         const user2 = registry.createTemporaryUser('Bob');
-        expect(user1.avatar).not.toBe(user2.avatar);
+        expect(user1.avatarHash).not.toBe(user2.avatarHash);
       });
     });