open-backlog 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +309 -2
- package/dist/cli/main.d.ts +2 -0
- package/dist/cli/main.js +18 -0
- package/dist/cli/run.d.ts +27 -0
- package/dist/cli/run.js +486 -0
- package/dist/core/add.d.ts +37 -0
- package/dist/core/add.js +99 -0
- package/dist/core/fix.d.ts +30 -0
- package/dist/core/fix.js +87 -0
- package/dist/core/git.d.ts +93 -0
- package/dist/core/git.js +267 -0
- package/dist/core/hierarchy.d.ts +62 -0
- package/dist/core/hierarchy.js +78 -0
- package/dist/core/ids.d.ts +14 -0
- package/dist/core/ids.js +25 -0
- package/dist/core/index.d.ts +36 -0
- package/dist/core/index.js +25 -0
- package/dist/core/init.d.ts +35 -0
- package/dist/core/init.js +77 -0
- package/dist/core/list.d.ts +40 -0
- package/dist/core/list.js +79 -0
- package/dist/core/read.d.ts +18 -0
- package/dist/core/read.js +151 -0
- package/dist/core/rules.d.ts +18 -0
- package/dist/core/rules.js +21 -0
- package/dist/core/show.d.ts +38 -0
- package/dist/core/show.js +87 -0
- package/dist/core/spec.d.ts +4 -0
- package/dist/core/spec.js +4 -0
- package/dist/core/types.d.ts +70 -0
- package/dist/core/types.js +10 -0
- package/dist/core/validate.d.ts +28 -0
- package/dist/core/validate.js +227 -0
- package/dist/core/write.d.ts +56 -0
- package/dist/core/write.js +160 -0
- package/dist/core/yaml.d.ts +13 -0
- package/dist/core/yaml.js +28 -0
- package/package.json +52 -4
- package/schema/0.1/config.schema.json +32 -0
- package/schema/0.1/item.schema.json +91 -0
package/dist/core/fix.js
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { readFileSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { addedIn, commit, isAncestor, message, move, nextId, repoRoot } from './git.js';
|
|
4
|
+
import { compareIds } from './ids.js';
|
|
5
|
+
import { loadBacklog } from './read.js';
|
|
6
|
+
import { BacklogError } from './types.js';
|
|
7
|
+
import { setFields, updateItem } from './write.js';
|
|
8
|
+
/** Orders two copies of an ID by when git added them: older first; uncommitted is newest. */
|
|
9
|
+
function older(dir, a, b) {
|
|
10
|
+
if (a.added && b.added && a.added.hash !== b.added.hash) {
|
|
11
|
+
if (isAncestor(dir, a.added.hash, b.added.hash))
|
|
12
|
+
return -1;
|
|
13
|
+
if (isAncestor(dir, b.added.hash, a.added.hash))
|
|
14
|
+
return 1;
|
|
15
|
+
if (a.added.time !== b.added.time)
|
|
16
|
+
return a.added.time - b.added.time;
|
|
17
|
+
}
|
|
18
|
+
else if (a.added && !b.added)
|
|
19
|
+
return -1;
|
|
20
|
+
else if (!a.added && b.added)
|
|
21
|
+
return 1;
|
|
22
|
+
return a.item.path < b.item.path ? -1 : 1;
|
|
23
|
+
}
|
|
24
|
+
/** The next free ID for an item of its type, under its parent. */
|
|
25
|
+
function nextFor(b, item) {
|
|
26
|
+
if (item.type === 'capability')
|
|
27
|
+
return nextId(b, undefined, true);
|
|
28
|
+
if (item.type === 'epic')
|
|
29
|
+
return nextId(b);
|
|
30
|
+
return nextId(b, item.parent ?? item.id.split('.').slice(0, -1).join('.'));
|
|
31
|
+
}
|
|
32
|
+
/** The first set of items sharing an ID, in ID order, so a parent is fixed before its children. */
|
|
33
|
+
function firstDuplicate(b) {
|
|
34
|
+
const ids = [...new Set(b.items.map(i => i.id))].sort(compareIds);
|
|
35
|
+
for (const id of ids) {
|
|
36
|
+
const same = b.items.filter(i => i.id === id);
|
|
37
|
+
if (same.length > 1)
|
|
38
|
+
return same;
|
|
39
|
+
}
|
|
40
|
+
return null;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Renumbers duplicate IDs in the backlog in `dir` and commits every change in one commit
|
|
44
|
+
* ("ob: renumber 2.3.5 to 2.3.6"), unless `commit` is false. Needs git, to tell which copy is
|
|
45
|
+
* newer. Returns what it changed (empty if there were no duplicates).
|
|
46
|
+
*/
|
|
47
|
+
export function fixDuplicates(dir, opts = {}) {
|
|
48
|
+
let b = loadBacklog(dir);
|
|
49
|
+
if (firstDuplicate(b) && !repoRoot(b.dir)) {
|
|
50
|
+
throw new BacklogError('--fix needs git history to tell which of two items with the same id is newer; this backlog is not in a git repository');
|
|
51
|
+
}
|
|
52
|
+
const renumbered = [];
|
|
53
|
+
const touched = [];
|
|
54
|
+
for (let guard = b.items.length; guard > 0; guard--) {
|
|
55
|
+
const same = firstDuplicate(b);
|
|
56
|
+
if (!same)
|
|
57
|
+
break;
|
|
58
|
+
const copies = same.map(item => ({ item, added: addedIn(join(b.dir, item.path)) })).sort((x, y) => older(b.dir, x, y));
|
|
59
|
+
const [keep, ...newer] = copies;
|
|
60
|
+
if (!keep)
|
|
61
|
+
break;
|
|
62
|
+
const item = newer[0]?.item;
|
|
63
|
+
const cB = newer[0]?.added ?? null;
|
|
64
|
+
if (!item)
|
|
65
|
+
break;
|
|
66
|
+
const to = nextFor(b, item);
|
|
67
|
+
const name = item.path.slice(item.path.lastIndexOf('/') + 1);
|
|
68
|
+
// The file name's ID is replaced (or, if it has none, put in front); its slug stays.
|
|
69
|
+
const rest = item.file ? name.slice(item.file.id.length) : `-${name}`;
|
|
70
|
+
const newPath = `${item.path.slice(0, item.path.length - name.length)}${to}${rest}`;
|
|
71
|
+
// The children that came with it: added after it on its line of history, not the kept one's.
|
|
72
|
+
const children = b.items.filter(c => c.parent === item.id && c !== keep.item && c !== item).filter(c => {
|
|
73
|
+
const cc = addedIn(join(b.dir, c.path));
|
|
74
|
+
return cB !== null && cc !== null && isAncestor(b.dir, cB.hash, cc.hash) && !(keep.added && isAncestor(b.dir, keep.added.hash, cc.hash));
|
|
75
|
+
});
|
|
76
|
+
const from = join(b.dir, item.path), dest = join(b.dir, newPath);
|
|
77
|
+
writeFileSync(from, setFields(readFileSync(from, 'utf8'), { id: to }));
|
|
78
|
+
move(from, dest);
|
|
79
|
+
for (const c of children)
|
|
80
|
+
updateItem(b.dir, c, { parent: to });
|
|
81
|
+
touched.push(from, dest, ...children.map(c => join(b.dir, c.path)));
|
|
82
|
+
renumbered.push({ from: item.id, to, path: item.path, newPath, children: children.map(c => ({ id: c.id, path: c.path })) });
|
|
83
|
+
b = loadBacklog(dir);
|
|
84
|
+
}
|
|
85
|
+
const committed = renumbered.length > 0 && opts.commit !== false ? commit(touched, message.renumber(renumbered)) : false;
|
|
86
|
+
return { renumbered, committed };
|
|
87
|
+
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import type { Backlog, Item, Status } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Git (2.2.6, D2): ob runs the user's own `git`, with their environment, so their identity, SSH
|
|
4
|
+
* key or credential helper, hooks and settings all apply and ob needs no token. Outside a git
|
|
5
|
+
* repository everything still works except committing, pulling and pushing.
|
|
6
|
+
*/
|
|
7
|
+
/** Runs git in `cwd`; a failure is a BacklogError with git's own first line of complaint. */
|
|
8
|
+
export declare function git(cwd: string, args: string[]): string;
|
|
9
|
+
/** The top folder of the git repository holding `dir`, or null if it isn't in one (or git is missing). */
|
|
10
|
+
export declare function repoRoot(dir: string): string | null;
|
|
11
|
+
/** Commit messages ob writes (D3): one line, starting "ob:". */
|
|
12
|
+
export declare const message: {
|
|
13
|
+
move: (id: string, status: Status) => string;
|
|
14
|
+
add: (id: string, title: string) => string;
|
|
15
|
+
edit: (id: string, what: string) => string;
|
|
16
|
+
renumber: (changes: {
|
|
17
|
+
from: string;
|
|
18
|
+
to: string;
|
|
19
|
+
}[]) => string;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* Moves a file (absolute paths), making the destination folder. A tracked file moves with
|
|
23
|
+
* `git mv`, so git keeps its history; anything else, or anything outside git, is a plain rename.
|
|
24
|
+
*/
|
|
25
|
+
export declare function move(from: string, to: string): void;
|
|
26
|
+
/**
|
|
27
|
+
* Commits exactly these files (absolute paths; for a move, both the old and the new path) with
|
|
28
|
+
* the user's own identity, and nothing else that happens to be staged or changed. Returns false
|
|
29
|
+
* outside git, where there is nothing to commit to.
|
|
30
|
+
*/
|
|
31
|
+
export declare function commit(paths: string[], msg: string): boolean;
|
|
32
|
+
/** Uncommitted changes under these paths (or the whole repository): `git status --porcelain` lines. */
|
|
33
|
+
export declare function changes(dir: string, paths?: string[]): string[];
|
|
34
|
+
/** True when nothing under these paths (or the repository) has uncommitted changes; always true outside git. */
|
|
35
|
+
export declare function isClean(dir: string, paths?: string[]): boolean;
|
|
36
|
+
export interface LogEntry {
|
|
37
|
+
hash: string;
|
|
38
|
+
date: string;
|
|
39
|
+
author: string;
|
|
40
|
+
subject: string;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* A file's history, newest first, through its moves between status folders: every commit that
|
|
44
|
+
* touched a file of that name. Exact, unlike git's rename guessing (--follow), which can take two
|
|
45
|
+
* near-identical item files for one. Empty outside git or before the first commit.
|
|
46
|
+
*/
|
|
47
|
+
export declare function history(file: string): LogEntry[];
|
|
48
|
+
/**
|
|
49
|
+
* The commit that first added a file, or null if it isn't committed (or isn't in git). Items keep
|
|
50
|
+
* their file name when they move between status folders, so this is the oldest commit that added
|
|
51
|
+
* a file of that name anywhere: exact, where git's rename guessing (--follow) can mistake two
|
|
52
|
+
* similar small files for one.
|
|
53
|
+
*/
|
|
54
|
+
export declare function addedIn(file: string): {
|
|
55
|
+
hash: string;
|
|
56
|
+
time: number;
|
|
57
|
+
} | null;
|
|
58
|
+
/** True if commit `a` is an ancestor of commit `b` (or the same commit), in the repository holding `dir`. */
|
|
59
|
+
export declare function isAncestor(dir: string, a: string, b: string): boolean;
|
|
60
|
+
/** `git pull`, then `git push`, as the user's git is set up to do them (D3's Sync). */
|
|
61
|
+
export declare function pull(dir: string): string;
|
|
62
|
+
export declare function push(dir: string): string;
|
|
63
|
+
/**
|
|
64
|
+
* Every ID the backlog has ever used: the items there now (front matter and file names) and every
|
|
65
|
+
* item file deleted, or moved away, in git history ([id-numbers]).
|
|
66
|
+
*/
|
|
67
|
+
export declare function usedIds(b: Backlog): Set<string>;
|
|
68
|
+
/**
|
|
69
|
+
* The next ID ([id-numbers]): one more than the highest ever used under `parent` (a feature for
|
|
70
|
+
* story-level items, an epic for features), counting pruned items in git history, so a number is
|
|
71
|
+
* never used twice. With no parent: the next epic (epic 0 is kept for unplanned work, so the
|
|
72
|
+
* first is 1), or with `capability`, the next C number.
|
|
73
|
+
*/
|
|
74
|
+
export declare function nextId(b: Backlog, parent?: string, capability?: boolean): string;
|
|
75
|
+
/**
|
|
76
|
+
* Where a story-level item goes for a status: stories/todo/ or doing/, and stories/done/ or,
|
|
77
|
+
* with `done-folders: month` in config.yml, stories/done/YYYY-MM/ for the given day.
|
|
78
|
+
*/
|
|
79
|
+
export declare function statusPath(b: Backlog, item: Item, status: Status, day?: Date): string;
|
|
80
|
+
/** "2026-11" for a day, in local time: done/ subfolders and epic 0's features. */
|
|
81
|
+
export declare function monthOf(day: Date): string;
|
|
82
|
+
/**
|
|
83
|
+
* Moves a story-level item to a status, and commits the move alone ("ob: move 2.3.4 to doing")
|
|
84
|
+
* unless `commit` is false or the backlog isn't in git. Returns the new path and whether it
|
|
85
|
+
* committed.
|
|
86
|
+
*/
|
|
87
|
+
export declare function moveItem(b: Backlog, item: Item, status: Status, opts?: {
|
|
88
|
+
commit?: boolean;
|
|
89
|
+
day?: Date;
|
|
90
|
+
}): {
|
|
91
|
+
path: string;
|
|
92
|
+
committed: boolean;
|
|
93
|
+
};
|
package/dist/core/git.js
ADDED
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
import { execFileSync } from 'node:child_process';
|
|
2
|
+
import { existsSync, mkdirSync, realpathSync, renameSync } from 'node:fs';
|
|
3
|
+
import { basename, dirname, join, relative, resolve, sep } from 'node:path';
|
|
4
|
+
import { parseFileName } from './ids.js';
|
|
5
|
+
import { BacklogError } from './types.js';
|
|
6
|
+
/**
|
|
7
|
+
* Git (2.2.6, D2): ob runs the user's own `git`, with their environment, so their identity, SSH
|
|
8
|
+
* key or credential helper, hooks and settings all apply and ob needs no token. Outside a git
|
|
9
|
+
* repository everything still works except committing, pulling and pushing.
|
|
10
|
+
*/
|
|
11
|
+
/** Runs git in `cwd`; a failure is a BacklogError with git's own first line of complaint. */
|
|
12
|
+
export function git(cwd, args) {
|
|
13
|
+
try {
|
|
14
|
+
return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
|
|
15
|
+
}
|
|
16
|
+
catch (e) {
|
|
17
|
+
const err = e;
|
|
18
|
+
if (err.code === 'ENOENT')
|
|
19
|
+
throw new BacklogError('git is not installed, or not on your PATH');
|
|
20
|
+
const said = (err.stderr ?? '').split('\n').map(l => l.trim()).find(Boolean) ?? String(e);
|
|
21
|
+
throw new BacklogError(`git ${args[0] ?? ''}: ${said.replace(/^(fatal|error): /, '')}`);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
/** The top folder of the git repository holding `dir`, or null if it isn't in one (or git is missing). */
|
|
25
|
+
export function repoRoot(dir) {
|
|
26
|
+
try {
|
|
27
|
+
return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
return null;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
/** Commit messages ob writes (D3): one line, starting "ob:". */
|
|
34
|
+
export const message = {
|
|
35
|
+
move: (id, status) => `ob: move ${id} to ${status}`,
|
|
36
|
+
add: (id, title) => `ob: add ${id} ${title}`,
|
|
37
|
+
edit: (id, what) => `ob: edit ${id} ${what}`,
|
|
38
|
+
renumber: (changes) => `ob: renumber ${changes.map(c => `${c.from} to ${c.to}`).join(', ')}`,
|
|
39
|
+
};
|
|
40
|
+
/**
|
|
41
|
+
* Paths for git: relative to the repository's top, with "/". git gives that top as a real path,
|
|
42
|
+
* so each path is resolved through symlinks first (on macOS, /var is /private/var), including
|
|
43
|
+
* paths that don't exist yet, such as where a file is moving to.
|
|
44
|
+
*/
|
|
45
|
+
function forGit(root, paths) {
|
|
46
|
+
return paths.map(p => relative(root, realPath(p)).split(sep).join('/') || '.');
|
|
47
|
+
}
|
|
48
|
+
/** A path with its deepest existing folder resolved through symlinks. */
|
|
49
|
+
function realPath(p) {
|
|
50
|
+
const rest = [];
|
|
51
|
+
let dir = resolve(p);
|
|
52
|
+
while (!existsSync(dir) && dirname(dir) !== dir) {
|
|
53
|
+
rest.unshift(basename(dir));
|
|
54
|
+
dir = dirname(dir);
|
|
55
|
+
}
|
|
56
|
+
return join(realpathSync(dir), ...rest);
|
|
57
|
+
}
|
|
58
|
+
/** True if the last commit has the file (so a move away from it is a change to commit). */
|
|
59
|
+
function inHead(root, file) {
|
|
60
|
+
if (!hasCommits(root))
|
|
61
|
+
return false;
|
|
62
|
+
try {
|
|
63
|
+
execFileSync('git', ['cat-file', '-e', `HEAD:${forGit(root, [file])[0] ?? ''}`], { cwd: root, stdio: 'ignore' });
|
|
64
|
+
return true;
|
|
65
|
+
}
|
|
66
|
+
catch {
|
|
67
|
+
return false;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
/** True if git tracks the file. */
|
|
71
|
+
function tracked(root, file) {
|
|
72
|
+
try {
|
|
73
|
+
execFileSync('git', ['ls-files', '--error-unmatch', '--', ...forGit(root, [file])], { cwd: root, stdio: 'ignore' });
|
|
74
|
+
return true;
|
|
75
|
+
}
|
|
76
|
+
catch {
|
|
77
|
+
return false;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Moves a file (absolute paths), making the destination folder. A tracked file moves with
|
|
82
|
+
* `git mv`, so git keeps its history; anything else, or anything outside git, is a plain rename.
|
|
83
|
+
*/
|
|
84
|
+
export function move(from, to) {
|
|
85
|
+
if (existsSync(to))
|
|
86
|
+
throw new BacklogError(`${to}: already exists`, to);
|
|
87
|
+
mkdirSync(dirname(to), { recursive: true });
|
|
88
|
+
const root = repoRoot(dirname(from));
|
|
89
|
+
if (root && tracked(root, from))
|
|
90
|
+
git(root, ['mv', '--', ...forGit(root, [from, to])]);
|
|
91
|
+
else
|
|
92
|
+
renameSync(from, to);
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Commits exactly these files (absolute paths; for a move, both the old and the new path) with
|
|
96
|
+
* the user's own identity, and nothing else that happens to be staged or changed. Returns false
|
|
97
|
+
* outside git, where there is nothing to commit to.
|
|
98
|
+
*/
|
|
99
|
+
export function commit(paths, msg) {
|
|
100
|
+
const start = paths.map(p => dirname(p)).find(d => existsSync(d));
|
|
101
|
+
const root = start ? repoRoot(start) : null;
|
|
102
|
+
if (!root)
|
|
103
|
+
return false;
|
|
104
|
+
// Stage what is there, or what git still tracks (a deletion); a path git mv already moved away
|
|
105
|
+
// is neither, but the commit below still records its side of the rename.
|
|
106
|
+
const toAdd = paths.filter(p => existsSync(p) || tracked(root, p));
|
|
107
|
+
if (toAdd.length)
|
|
108
|
+
git(root, ['add', '-A', '--', ...forGit(root, toAdd)]);
|
|
109
|
+
// A path git never knew (an untracked file renamed away) can't be named in the commit.
|
|
110
|
+
const known = paths.filter(p => toAdd.includes(p) || inHead(root, p));
|
|
111
|
+
git(root, ['commit', '--quiet', '-m', msg, '--', ...forGit(root, known)]);
|
|
112
|
+
return true;
|
|
113
|
+
}
|
|
114
|
+
/** Uncommitted changes under these paths (or the whole repository): `git status --porcelain` lines. */
|
|
115
|
+
export function changes(dir, paths = []) {
|
|
116
|
+
const root = repoRoot(dir);
|
|
117
|
+
if (!root)
|
|
118
|
+
return [];
|
|
119
|
+
return git(root, ['status', '--porcelain', '--untracked-files=all', '--', ...forGit(root, paths.length ? paths : [root])])
|
|
120
|
+
.split('\n').filter(Boolean);
|
|
121
|
+
}
|
|
122
|
+
/** True when nothing under these paths (or the repository) has uncommitted changes; always true outside git. */
|
|
123
|
+
export function isClean(dir, paths = []) {
|
|
124
|
+
return changes(dir, paths).length === 0;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* A file's history, newest first, through its moves between status folders: every commit that
|
|
128
|
+
* touched a file of that name. Exact, unlike git's rename guessing (--follow), which can take two
|
|
129
|
+
* near-identical item files for one. Empty outside git or before the first commit.
|
|
130
|
+
*/
|
|
131
|
+
export function history(file) {
|
|
132
|
+
const root = repoRoot(dirname(file));
|
|
133
|
+
if (!root || !hasCommits(root))
|
|
134
|
+
return [];
|
|
135
|
+
return git(root, ['log', '--no-renames', '--date=short', '--format=%h%x09%ad%x09%an%x09%s', '--', nameGlob(file)])
|
|
136
|
+
.split('\n').filter(Boolean).map(l => {
|
|
137
|
+
const [hash = '', date = '', author = '', ...subject] = l.split('\t');
|
|
138
|
+
return { hash, date, author, subject: subject.join('\t') };
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
/** A pathspec for every file with this file's name, anywhere in the repository. */
|
|
142
|
+
function nameGlob(file) {
|
|
143
|
+
return `:(glob)**/${basename(file).replace(/[*?[\]\\]/g, '\\$&')}`;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* The commit that first added a file, or null if it isn't committed (or isn't in git). Items keep
|
|
147
|
+
* their file name when they move between status folders, so this is the oldest commit that added
|
|
148
|
+
* a file of that name anywhere: exact, where git's rename guessing (--follow) can mistake two
|
|
149
|
+
* similar small files for one.
|
|
150
|
+
*/
|
|
151
|
+
export function addedIn(file) {
|
|
152
|
+
const root = repoRoot(dirname(file));
|
|
153
|
+
if (!root || !hasCommits(root))
|
|
154
|
+
return null;
|
|
155
|
+
const lines = git(root, ['log', '--no-renames', '--diff-filter=A', '--format=%H %ct', '--', nameGlob(file)]).split('\n').filter(Boolean);
|
|
156
|
+
const [hash, time] = (lines[lines.length - 1] ?? '').split(' ');
|
|
157
|
+
return hash ? { hash, time: Number(time) } : null;
|
|
158
|
+
}
|
|
159
|
+
/** True if commit `a` is an ancestor of commit `b` (or the same commit), in the repository holding `dir`. */
|
|
160
|
+
export function isAncestor(dir, a, b) {
|
|
161
|
+
const root = repoRoot(dir);
|
|
162
|
+
if (!root)
|
|
163
|
+
return false;
|
|
164
|
+
try {
|
|
165
|
+
execFileSync('git', ['merge-base', '--is-ancestor', a, b], { cwd: root, stdio: 'ignore' });
|
|
166
|
+
return true;
|
|
167
|
+
}
|
|
168
|
+
catch {
|
|
169
|
+
return false;
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
/** `git pull`, then `git push`, as the user's git is set up to do them (D3's Sync). */
|
|
173
|
+
export function pull(dir) {
|
|
174
|
+
return git(requireRepo(dir), ['pull']);
|
|
175
|
+
}
|
|
176
|
+
export function push(dir) {
|
|
177
|
+
return git(requireRepo(dir), ['push']);
|
|
178
|
+
}
|
|
179
|
+
function requireRepo(dir) {
|
|
180
|
+
const root = repoRoot(dir);
|
|
181
|
+
if (!root)
|
|
182
|
+
throw new BacklogError(`${dir} is not in a git repository, so there is nothing to pull or push`);
|
|
183
|
+
return root;
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* Every ID the backlog has ever used: the items there now (front matter and file names) and every
|
|
187
|
+
* item file deleted, or moved away, in git history ([id-numbers]).
|
|
188
|
+
*/
|
|
189
|
+
export function usedIds(b) {
|
|
190
|
+
const ids = new Set();
|
|
191
|
+
for (const i of b.items) {
|
|
192
|
+
ids.add(i.id);
|
|
193
|
+
if (i.file)
|
|
194
|
+
ids.add(i.file.id);
|
|
195
|
+
}
|
|
196
|
+
const root = repoRoot(b.dir);
|
|
197
|
+
// A repository with no commits yet (just after git init) has no history to count.
|
|
198
|
+
if (root && hasCommits(root)) {
|
|
199
|
+
// --no-renames shows a move as a delete and an add, so the old name counts too.
|
|
200
|
+
const deleted = git(root, ['log', '--no-renames', '--diff-filter=D', '--name-only', '--format=', '--', ...forGit(root, [b.dir])]);
|
|
201
|
+
for (const path of deleted.split('\n').filter(Boolean)) {
|
|
202
|
+
const parsed = parseFileName(path.slice(path.lastIndexOf('/') + 1));
|
|
203
|
+
if (parsed)
|
|
204
|
+
ids.add(parsed.id);
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
return ids;
|
|
208
|
+
}
|
|
209
|
+
/** True once the repository has a first commit (git log fails before that). */
|
|
210
|
+
function hasCommits(root) {
|
|
211
|
+
try {
|
|
212
|
+
execFileSync('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd: root, stdio: 'ignore' });
|
|
213
|
+
return true;
|
|
214
|
+
}
|
|
215
|
+
catch {
|
|
216
|
+
return false;
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* The next ID ([id-numbers]): one more than the highest ever used under `parent` (a feature for
|
|
221
|
+
* story-level items, an epic for features), counting pruned items in git history, so a number is
|
|
222
|
+
* never used twice. With no parent: the next epic (epic 0 is kept for unplanned work, so the
|
|
223
|
+
* first is 1), or with `capability`, the next C number.
|
|
224
|
+
*/
|
|
225
|
+
export function nextId(b, parent, capability = false) {
|
|
226
|
+
const used = [...usedIds(b)];
|
|
227
|
+
if (capability) {
|
|
228
|
+
const n = Math.max(0, ...used.filter(id => /^C\d+$/.test(id)).map(id => Number(id.slice(1))));
|
|
229
|
+
return `C${n + 1}`;
|
|
230
|
+
}
|
|
231
|
+
const prefix = parent === undefined ? '' : `${parent}.`;
|
|
232
|
+
const depth = parent === undefined ? 1 : parent.split('.').length + 1;
|
|
233
|
+
const numbers = used
|
|
234
|
+
.filter(id => /^\d+(\.\d+)*$/.test(id) && id.startsWith(prefix) && id.split('.').length === depth)
|
|
235
|
+
.map(id => Number(id.split('.').pop()));
|
|
236
|
+
return `${prefix}${Math.max(0, ...numbers) + 1}`;
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* Where a story-level item goes for a status: stories/todo/ or doing/, and stories/done/ or,
|
|
240
|
+
* with `done-folders: month` in config.yml, stories/done/YYYY-MM/ for the given day.
|
|
241
|
+
*/
|
|
242
|
+
export function statusPath(b, item, status, day = new Date()) {
|
|
243
|
+
const name = item.path.slice(item.path.lastIndexOf('/') + 1);
|
|
244
|
+
if (status !== 'done')
|
|
245
|
+
return `stories/${status}/${name}`;
|
|
246
|
+
if (b.config['done-folders'] !== 'month')
|
|
247
|
+
return `stories/done/${name}`;
|
|
248
|
+
return `stories/done/${monthOf(day)}/${name}`;
|
|
249
|
+
}
|
|
250
|
+
/** "2026-11" for a day, in local time: done/ subfolders and epic 0's features. */
|
|
251
|
+
export function monthOf(day) {
|
|
252
|
+
return `${day.getFullYear()}-${String(day.getMonth() + 1).padStart(2, '0')}`;
|
|
253
|
+
}
|
|
254
|
+
/**
|
|
255
|
+
* Moves a story-level item to a status, and commits the move alone ("ob: move 2.3.4 to doing")
|
|
256
|
+
* unless `commit` is false or the backlog isn't in git. Returns the new path and whether it
|
|
257
|
+
* committed.
|
|
258
|
+
*/
|
|
259
|
+
export function moveItem(b, item, status, opts = {}) {
|
|
260
|
+
if (item.status === status)
|
|
261
|
+
return { path: item.path, committed: false };
|
|
262
|
+
const to = statusPath(b, item, status, opts.day);
|
|
263
|
+
const fromAbs = join(b.dir, item.path), toAbs = join(b.dir, to);
|
|
264
|
+
move(fromAbs, toAbs);
|
|
265
|
+
const committed = opts.commit === false ? false : commit([fromAbs, toAbs], message.move(item.id, status));
|
|
266
|
+
return { path: to, committed };
|
|
267
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import type { Item, Status } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* The hierarchy and progress (2.2.4). Children are never written down (spec section 2): an
|
|
4
|
+
* item's children are the items whose `parent` is its `id`. Progress is worked out from the
|
|
5
|
+
* story-level items, never stored ([not-stored]).
|
|
6
|
+
*/
|
|
7
|
+
export declare const STORY_LEVEL_TYPES: string[];
|
|
8
|
+
export declare const isStoryLevel: (item: Item) => boolean;
|
|
9
|
+
export interface Progress {
|
|
10
|
+
/** Story-level items under it, by status. One outside a status folder counts in `total` only. */
|
|
11
|
+
done: number;
|
|
12
|
+
doing: number;
|
|
13
|
+
todo: number;
|
|
14
|
+
total: number;
|
|
15
|
+
/** done / total, rounded; 0 when there are none. */
|
|
16
|
+
percent: number;
|
|
17
|
+
/** The same, weighted by `estimate` (items without a number count 0). */
|
|
18
|
+
estimate: {
|
|
19
|
+
done: number;
|
|
20
|
+
total: number;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* As the spec says: a feature is done when all its story-level items are done and in progress
|
|
24
|
+
* when any is in doing or done; an epic is done when all its features are, a capability when
|
|
25
|
+
* all its epics are. Nothing under it: todo.
|
|
26
|
+
*/
|
|
27
|
+
status: Status;
|
|
28
|
+
}
|
|
29
|
+
export interface Node {
|
|
30
|
+
item: Item;
|
|
31
|
+
/** The node its `parent` names, if that item is in the backlog. */
|
|
32
|
+
parent: Node | null;
|
|
33
|
+
/** Ordered by ID. */
|
|
34
|
+
children: Node[];
|
|
35
|
+
}
|
|
36
|
+
export interface Tree {
|
|
37
|
+
/** Items with no parent, or whose parent isn't in the backlog; ordered by ID. */
|
|
38
|
+
roots: Node[];
|
|
39
|
+
/** Items whose `parent` names no item in the backlog (validation reports [parent-exists]). */
|
|
40
|
+
orphans: Node[];
|
|
41
|
+
/** Each ID's node (the first, if an ID is used twice; validation reports [id-unique]). */
|
|
42
|
+
byId: Map<string, Node>;
|
|
43
|
+
}
|
|
44
|
+
/** Links every item to its parent and gives every item its children. */
|
|
45
|
+
export declare function buildTree(items: Item[]): Tree;
|
|
46
|
+
/** Progress of any node; for a story-level item, its own status as one item. */
|
|
47
|
+
export declare function progressOf(node: Node): Progress;
|
|
48
|
+
/**
|
|
49
|
+
* Build order: every item by its ID, part by part as numbers (2.3.9 before 2.3.10), each parent
|
|
50
|
+
* before what is filed under it, capabilities first. It reads top to bottom like a plan.
|
|
51
|
+
*/
|
|
52
|
+
export declare function buildOrder(items: Item[]): Item[];
|
|
53
|
+
/**
|
|
54
|
+
* The order within one status folder (a board column): items with a `rank` first, lowest first,
|
|
55
|
+
* then the rest by ID (spec section 4).
|
|
56
|
+
*/
|
|
57
|
+
export declare function columnOrder(items: Item[]): Item[];
|
|
58
|
+
/** The tree depth first, each node with its depth: for printing an indented outline. */
|
|
59
|
+
export declare function walk(tree: Tree): {
|
|
60
|
+
node: Node;
|
|
61
|
+
depth: number;
|
|
62
|
+
}[];
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import { compareIds } from './ids.js';
|
|
2
|
+
/**
|
|
3
|
+
* The hierarchy and progress (2.2.4). Children are never written down (spec section 2): an
|
|
4
|
+
* item's children are the items whose `parent` is its `id`. Progress is worked out from the
|
|
5
|
+
* story-level items, never stored ([not-stored]).
|
|
6
|
+
*/
|
|
7
|
+
export const STORY_LEVEL_TYPES = ['story', 'bug', 'spike', 'task'];
|
|
8
|
+
export const isStoryLevel = (item) => STORY_LEVEL_TYPES.includes(item.type);
|
|
9
|
+
/** Links every item to its parent and gives every item its children. */
|
|
10
|
+
export function buildTree(items) {
|
|
11
|
+
const byId = new Map();
|
|
12
|
+
const nodes = [...items].sort((a, b) => compareIds(a.id, b.id)).map(item => ({ item, parent: null, children: [] }));
|
|
13
|
+
for (const n of nodes)
|
|
14
|
+
if (!byId.has(n.item.id))
|
|
15
|
+
byId.set(n.item.id, n);
|
|
16
|
+
const roots = [], orphans = [];
|
|
17
|
+
for (const n of nodes) {
|
|
18
|
+
const pid = n.item.parent;
|
|
19
|
+
const parent = pid === undefined ? undefined : byId.get(pid);
|
|
20
|
+
if (parent && parent !== n) {
|
|
21
|
+
n.parent = parent;
|
|
22
|
+
parent.children.push(n);
|
|
23
|
+
}
|
|
24
|
+
else {
|
|
25
|
+
roots.push(n);
|
|
26
|
+
if (pid !== undefined)
|
|
27
|
+
orphans.push(n);
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
return { roots, orphans, byId };
|
|
31
|
+
}
|
|
32
|
+
/** Progress of any node; for a story-level item, its own status as one item. */
|
|
33
|
+
export function progressOf(node) {
|
|
34
|
+
if (isStoryLevel(node.item)) {
|
|
35
|
+
const s = node.item.status;
|
|
36
|
+
const est = estimateOf(node.item);
|
|
37
|
+
return finish({ done: s === 'done' ? 1 : 0, doing: s === 'doing' ? 1 : 0, todo: s === 'todo' ? 1 : 0, total: 1,
|
|
38
|
+
estimate: { done: s === 'done' ? est : 0, total: est } }, s ?? 'todo');
|
|
39
|
+
}
|
|
40
|
+
const parts = node.children.map(progressOf);
|
|
41
|
+
const sum = (f) => parts.reduce((a, p) => a + f(p), 0);
|
|
42
|
+
const counts = {
|
|
43
|
+
done: sum(p => p.done), doing: sum(p => p.doing), todo: sum(p => p.todo), total: sum(p => p.total),
|
|
44
|
+
estimate: { done: sum(p => p.estimate.done), total: sum(p => p.estimate.total) },
|
|
45
|
+
};
|
|
46
|
+
const status = parts.length > 0 && parts.every(p => p.status === 'done') ? 'done'
|
|
47
|
+
: parts.some(p => p.status !== 'todo') ? 'doing' : 'todo';
|
|
48
|
+
return finish(counts, status);
|
|
49
|
+
}
|
|
50
|
+
function finish(c, status) {
|
|
51
|
+
return { ...c, percent: c.total ? Math.round((c.done / c.total) * 100) : 0, status };
|
|
52
|
+
}
|
|
53
|
+
function estimateOf(item) {
|
|
54
|
+
const e = item.fields['estimate'];
|
|
55
|
+
return typeof e === 'number' && Number.isFinite(e) && e >= 0 ? e : 0;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Build order: every item by its ID, part by part as numbers (2.3.9 before 2.3.10), each parent
|
|
59
|
+
* before what is filed under it, capabilities first. It reads top to bottom like a plan.
|
|
60
|
+
*/
|
|
61
|
+
export function buildOrder(items) {
|
|
62
|
+
return [...items].sort((a, b) => compareIds(a.id, b.id));
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* The order within one status folder (a board column): items with a `rank` first, lowest first,
|
|
66
|
+
* then the rest by ID (spec section 4).
|
|
67
|
+
*/
|
|
68
|
+
export function columnOrder(items) {
|
|
69
|
+
const rank = (i) => (typeof i.fields['rank'] === 'number' ? i.fields['rank'] : Infinity);
|
|
70
|
+
return [...items].sort((a, b) => rank(a) - rank(b) || compareIds(a.id, b.id));
|
|
71
|
+
}
|
|
72
|
+
/** The tree depth first, each node with its depth: for printing an indented outline. */
|
|
73
|
+
export function walk(tree) {
|
|
74
|
+
const out = [];
|
|
75
|
+
const visit = (n, depth) => { out.push({ node: n, depth }); n.children.forEach(c => visit(c, depth + 1)); };
|
|
76
|
+
tree.roots.forEach(r => visit(r, 0));
|
|
77
|
+
return out;
|
|
78
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IDs (spec section 2): epic `2`, feature `2.3`, story-level `2.3.4`, capability `C1`. Always
|
|
3
|
+
* text, never numbers ([read-as-text]): `1.10` is the tenth feature of epic 1, not 1.1.
|
|
4
|
+
*/
|
|
5
|
+
/** A file name's ID and slug: `2.3.4-ob-move.md` → 2.3.4 and ob-move. Null if it has no ID. */
|
|
6
|
+
export declare function parseFileName(name: string): {
|
|
7
|
+
id: string;
|
|
8
|
+
slug: string;
|
|
9
|
+
} | null;
|
|
10
|
+
/**
|
|
11
|
+
* Orders IDs as the spec does: capabilities first, then by each part as a number, so 1.2 comes
|
|
12
|
+
* before 1.10, and a parent before its children.
|
|
13
|
+
*/
|
|
14
|
+
export declare function compareIds(a: string, b: string): number;
|
package/dist/core/ids.js
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IDs (spec section 2): epic `2`, feature `2.3`, story-level `2.3.4`, capability `C1`. Always
|
|
3
|
+
* text, never numbers ([read-as-text]): `1.10` is the tenth feature of epic 1, not 1.1.
|
|
4
|
+
*/
|
|
5
|
+
/** A file name's ID and slug: `2.3.4-ob-move.md` → 2.3.4 and ob-move. Null if it has no ID. */
|
|
6
|
+
export function parseFileName(name) {
|
|
7
|
+
const m = /^(C\d+|\d+(?:\.\d+)*)-(.+)\.md$/.exec(name);
|
|
8
|
+
return m?.[1] && m[2] ? { id: m[1], slug: m[2] } : null;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Orders IDs as the spec does: capabilities first, then by each part as a number, so 1.2 comes
|
|
12
|
+
* before 1.10, and a parent before its children.
|
|
13
|
+
*/
|
|
14
|
+
export function compareIds(a, b) {
|
|
15
|
+
const capA = a.startsWith('C'), capB = b.startsWith('C');
|
|
16
|
+
if (capA !== capB)
|
|
17
|
+
return capA ? -1 : 1;
|
|
18
|
+
const pa = a.replace(/^C/, '').split('.').map(Number), pb = b.replace(/^C/, '').split('.').map(Number);
|
|
19
|
+
for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
|
|
20
|
+
const x = pa[i] ?? -1, y = pb[i] ?? -1;
|
|
21
|
+
if (x !== y)
|
|
22
|
+
return x - y;
|
|
23
|
+
}
|
|
24
|
+
return a < b ? -1 : a > b ? 1 : 0;
|
|
25
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* open-backlog: the core library (D1). It reads, parses and validates an Open Backlog and
|
|
3
|
+
* assigns IDs; the ob command (src/cli/) and the board (open-backlog-board) are both built on
|
|
4
|
+
* it, so they can't disagree about the rules. It never imports the CLI.
|
|
5
|
+
*
|
|
6
|
+
* import { readBacklog } from 'open-backlog';
|
|
7
|
+
* const backlog = readBacklog(); // from the working directory, walking up
|
|
8
|
+
* updateItem(backlog.dir, item, { assignee: 'ana' }); // one value changes, nothing else
|
|
9
|
+
*
|
|
10
|
+
* Git (the user's own, D2) and the next ID ([id-numbers]) are in git.ts (2.2.6).
|
|
11
|
+
*/
|
|
12
|
+
export { SPEC_URL, SPEC_VERSION } from './spec.js';
|
|
13
|
+
export { addItem, ITEM_TYPES, SLUG_PATTERN, UNPLANNED_TYPES } from './add.js';
|
|
14
|
+
export type { AddOptions, Added } from './add.js';
|
|
15
|
+
export { fixDuplicates } from './fix.js';
|
|
16
|
+
export type { Renumbered } from './fix.js';
|
|
17
|
+
export { addedIn, changes, commit, git, history, isAncestor, isClean, message, monthOf, move, moveItem, nextId, pull, push, repoRoot, statusPath, usedIds } from './git.js';
|
|
18
|
+
export type { LogEntry } from './git.js';
|
|
19
|
+
export { initBacklog, initDir, INIT_FOLDERS, INIT_README, NAME_PATTERN } from './init.js';
|
|
20
|
+
export type { InitOptions, InitResult } from './init.js';
|
|
21
|
+
export { buildOrder, buildTree, columnOrder, isStoryLevel, progressOf, STORY_LEVEL_TYPES, walk } from './hierarchy.js';
|
|
22
|
+
export type { Node, Progress, Tree } from './hierarchy.js';
|
|
23
|
+
export { compareIds, parseFileName } from './ids.js';
|
|
24
|
+
export { listItems, recentlyDone, reposOf } from './list.js';
|
|
25
|
+
export type { ListFilters, Listed, ListOptions } from './list.js';
|
|
26
|
+
export { showItem } from './show.js';
|
|
27
|
+
export type { Shown } from './show.js';
|
|
28
|
+
export { findBacklog, loadBacklog, readBacklog, statusOf } from './read.js';
|
|
29
|
+
export { BacklogError } from './types.js';
|
|
30
|
+
export { RULE, RULES } from './rules.js';
|
|
31
|
+
export type { Rule, Severity } from './rules.js';
|
|
32
|
+
export { formatProblem, validate, validateDir } from './validate.js';
|
|
33
|
+
export type { Problem } from './validate.js';
|
|
34
|
+
export { createItem, folderFor, formatValue, newItemPath, newItemText, setFields, slugify, updateItem } from './write.js';
|
|
35
|
+
export type { FieldValue, NewItem } from './write.js';
|
|
36
|
+
export type { Backlog, Config, FileError, Item, ItemFolder, ItemType, Person, Sprint, Status } from './types.js';
|