egehan 0.0.0-stage → 0.1.0
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 +79 -2
- package/assets/dictionary/narratives.en.json +660 -0
- package/assets/dictionary/narratives.tr.json +660 -0
- package/assets/schema/egehan-report.schema.json +354 -0
- package/assets/spec/rules.json +272 -0
- package/assets/templates/egehan-book.html +2027 -0
- package/assets/templates/hook.sh +41 -0
- package/dist/artifacts.d.ts +21 -0
- package/dist/artifacts.js +32 -0
- package/dist/capsule/capsule.d.ts +35 -0
- package/dist/capsule/capsule.js +123 -0
- package/dist/capsule/storage.d.ts +15 -0
- package/dist/capsule/storage.js +52 -0
- package/dist/cli/commands/capsule.d.ts +20 -0
- package/dist/cli/commands/capsule.js +94 -0
- package/dist/cli/commands/generate.d.ts +23 -0
- package/dist/cli/commands/generate.js +47 -0
- package/dist/cli/commands/hook.d.ts +14 -0
- package/dist/cli/commands/hook.js +120 -0
- package/dist/cli/commands/init.d.ts +16 -0
- package/dist/cli/commands/init.js +92 -0
- package/dist/cli/commands/stats.d.ts +14 -0
- package/dist/cli/commands/stats.js +112 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +167 -0
- package/dist/cli/output.d.ts +26 -0
- package/dist/cli/output.js +87 -0
- package/dist/cli/prompt.d.ts +21 -0
- package/dist/cli/prompt.js +63 -0
- package/dist/config/config.d.ts +51 -0
- package/dist/config/config.js +160 -0
- package/dist/detect/projectType.d.ts +34 -0
- package/dist/detect/projectType.js +95 -0
- package/dist/engine/buildReport.d.ts +32 -0
- package/dist/engine/buildReport.js +188 -0
- package/dist/engine/chapters.d.ts +20 -0
- package/dist/engine/chapters.js +33 -0
- package/dist/engine/classifier.d.ts +21 -0
- package/dist/engine/classifier.js +119 -0
- package/dist/engine/conventional.d.ts +15 -0
- package/dist/engine/conventional.js +137 -0
- package/dist/engine/datetime.d.ts +47 -0
- package/dist/engine/datetime.js +100 -0
- package/dist/engine/milestones.d.ts +6 -0
- package/dist/engine/milestones.js +109 -0
- package/dist/engine/narrator.d.ts +71 -0
- package/dist/engine/narrator.js +189 -0
- package/dist/engine/prepare.d.ts +36 -0
- package/dist/engine/prepare.js +46 -0
- package/dist/engine/privacy.d.ts +45 -0
- package/dist/engine/privacy.js +110 -0
- package/dist/engine/pulse.d.ts +17 -0
- package/dist/engine/pulse.js +205 -0
- package/dist/engine/templating.d.ts +40 -0
- package/dist/engine/templating.js +64 -0
- package/dist/engine/types.d.ts +205 -0
- package/dist/engine/types.js +9 -0
- package/dist/git/logReader.d.ts +37 -0
- package/dist/git/logReader.js +133 -0
- package/dist/git/repository.d.ts +14 -0
- package/dist/git/repository.js +61 -0
- package/dist/git/runGit.d.ts +21 -0
- package/dist/git/runGit.js +74 -0
- package/dist/hooks/block.d.ts +27 -0
- package/dist/hooks/block.js +62 -0
- package/dist/hooks/manager.d.ts +47 -0
- package/dist/hooks/manager.js +153 -0
- package/dist/index.d.ts +34 -0
- package/dist/index.js +26 -0
- package/dist/pipeline.d.ts +35 -0
- package/dist/pipeline.js +80 -0
- package/dist/renderers/html.d.ts +6 -0
- package/dist/renderers/html.js +117 -0
- package/dist/renderers/markdown.d.ts +4 -0
- package/dist/renderers/markdown.js +168 -0
- package/dist/spec/assets.d.ts +14 -0
- package/dist/spec/assets.js +98 -0
- package/dist/spec/dictionary.d.ts +100 -0
- package/dist/spec/dictionary.js +39 -0
- package/dist/spec/rules.d.ts +191 -0
- package/dist/spec/rules.js +15 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +20 -0
- package/package.json +55 -4
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { availableLanguages } from '../spec/dictionary.js';
|
|
4
|
+
/**
|
|
5
|
+
* `.egehanrc.json` — the per-project settings file.
|
|
6
|
+
*
|
|
7
|
+
* Validation is strict and the messages name the offending key and the accepted values. A config
|
|
8
|
+
* file is edited by hand, usually months after it was written, and "invalid configuration" with no
|
|
9
|
+
* further detail is how a tool teaches people to delete the file and start over.
|
|
10
|
+
*
|
|
11
|
+
* Note what is *not* here: nothing that would change the narration for one machine but not
|
|
12
|
+
* another. Language and tone are project-wide decisions recorded in the file, so two developers
|
|
13
|
+
* running the tool on the same repository produce the same chronicle.
|
|
14
|
+
*/
|
|
15
|
+
export const TONES = ['poetic', 'minimalist', 'humorous'];
|
|
16
|
+
/**
|
|
17
|
+
* Output formats.
|
|
18
|
+
*
|
|
19
|
+
* `both` means the two artifacts a project keeps — the Markdown chronicle and the interactive
|
|
20
|
+
* HTML timeline. The JSON report is a separate opt-in because it is the machine format: it carries
|
|
21
|
+
* the generation timestamp and is meant for tooling, not for reading.
|
|
22
|
+
*/
|
|
23
|
+
export const FORMATS = ['md', 'html', 'json', 'both', 'all'];
|
|
24
|
+
export const THEMES = ['auto', 'light', 'dark'];
|
|
25
|
+
export class ConfigError extends Error {
|
|
26
|
+
constructor(message) {
|
|
27
|
+
super(message);
|
|
28
|
+
this.name = 'ConfigError';
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
export function defaultConfig(rules) {
|
|
32
|
+
return {
|
|
33
|
+
projectName: null,
|
|
34
|
+
dedication: null,
|
|
35
|
+
language: 'en',
|
|
36
|
+
tone: 'poetic',
|
|
37
|
+
theme: 'auto',
|
|
38
|
+
// The privacy default comes from the rules file, not from this code, so it is reviewable in
|
|
39
|
+
// one place alongside the reason it exists.
|
|
40
|
+
redactEmails: rules.privacy.redactEmailsByDefault,
|
|
41
|
+
anonymizeAuthors: false,
|
|
42
|
+
includeMergeCommits: false,
|
|
43
|
+
format: 'both',
|
|
44
|
+
output: '.',
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
export function configPath(root, rules) {
|
|
48
|
+
return join(root, rules.output.configFileName);
|
|
49
|
+
}
|
|
50
|
+
export function configExists(root, rules) {
|
|
51
|
+
return existsSync(configPath(root, rules));
|
|
52
|
+
}
|
|
53
|
+
/** Reads `.egehanrc.json` when present, merged over the defaults. */
|
|
54
|
+
export function loadConfig(root, rules) {
|
|
55
|
+
const path = configPath(root, rules);
|
|
56
|
+
if (!existsSync(path))
|
|
57
|
+
return defaultConfig(rules);
|
|
58
|
+
let parsed;
|
|
59
|
+
try {
|
|
60
|
+
parsed = JSON.parse(readFileSync(path, 'utf8'));
|
|
61
|
+
}
|
|
62
|
+
catch (error) {
|
|
63
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
64
|
+
throw new ConfigError(`${rules.output.configFileName} is not valid JSON: ${reason}`);
|
|
65
|
+
}
|
|
66
|
+
return mergeConfig(defaultConfig(rules), parsed, rules.output.configFileName);
|
|
67
|
+
}
|
|
68
|
+
/** Applies a partial object (a config file or CLI flags) over a base config, validating as it goes. */
|
|
69
|
+
export function mergeConfig(base, patch, source) {
|
|
70
|
+
if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) {
|
|
71
|
+
throw new ConfigError(`${source} must contain a JSON object`);
|
|
72
|
+
}
|
|
73
|
+
const raw = patch;
|
|
74
|
+
const known = new Set([
|
|
75
|
+
'projectName',
|
|
76
|
+
'dedication',
|
|
77
|
+
'language',
|
|
78
|
+
'tone',
|
|
79
|
+
'theme',
|
|
80
|
+
'redactEmails',
|
|
81
|
+
'anonymizeAuthors',
|
|
82
|
+
'includeMergeCommits',
|
|
83
|
+
'format',
|
|
84
|
+
'output',
|
|
85
|
+
]);
|
|
86
|
+
for (const key of Object.keys(raw)) {
|
|
87
|
+
if (key.startsWith('$'))
|
|
88
|
+
continue;
|
|
89
|
+
if (!known.has(key)) {
|
|
90
|
+
throw new ConfigError(`${source} has an unknown setting "${key}". Known settings: ${[...known].join(', ')}.`);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
return {
|
|
94
|
+
projectName: optionalString(raw, 'projectName', base.projectName, source),
|
|
95
|
+
dedication: optionalString(raw, 'dedication', base.dedication, source),
|
|
96
|
+
language: oneOf(raw, 'language', base.language, availableLanguages(), source),
|
|
97
|
+
tone: oneOf(raw, 'tone', base.tone, TONES, source),
|
|
98
|
+
theme: oneOf(raw, 'theme', base.theme, THEMES, source),
|
|
99
|
+
redactEmails: boolean(raw, 'redactEmails', base.redactEmails, source),
|
|
100
|
+
anonymizeAuthors: boolean(raw, 'anonymizeAuthors', base.anonymizeAuthors, source),
|
|
101
|
+
includeMergeCommits: boolean(raw, 'includeMergeCommits', base.includeMergeCommits, source),
|
|
102
|
+
format: oneOf(raw, 'format', base.format, FORMATS, source),
|
|
103
|
+
output: requiredString(raw, 'output', base.output, source),
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
function optionalString(raw, key, fallback, source) {
|
|
107
|
+
const value = raw[key];
|
|
108
|
+
if (value === undefined)
|
|
109
|
+
return fallback;
|
|
110
|
+
if (value === null)
|
|
111
|
+
return null;
|
|
112
|
+
if (typeof value !== 'string')
|
|
113
|
+
throw new ConfigError(`${source}: "${key}" must be a string or null`);
|
|
114
|
+
const trimmed = value.trim();
|
|
115
|
+
return trimmed === '' ? null : trimmed;
|
|
116
|
+
}
|
|
117
|
+
function requiredString(raw, key, fallback, source) {
|
|
118
|
+
const value = raw[key];
|
|
119
|
+
if (value === undefined)
|
|
120
|
+
return fallback;
|
|
121
|
+
if (typeof value !== 'string' || value.trim() === '') {
|
|
122
|
+
throw new ConfigError(`${source}: "${key}" must be a non-empty string`);
|
|
123
|
+
}
|
|
124
|
+
return value.trim();
|
|
125
|
+
}
|
|
126
|
+
function boolean(raw, key, fallback, source) {
|
|
127
|
+
const value = raw[key];
|
|
128
|
+
if (value === undefined)
|
|
129
|
+
return fallback;
|
|
130
|
+
if (typeof value !== 'boolean')
|
|
131
|
+
throw new ConfigError(`${source}: "${key}" must be true or false`);
|
|
132
|
+
return value;
|
|
133
|
+
}
|
|
134
|
+
function oneOf(raw, key, fallback, allowed, source) {
|
|
135
|
+
const value = raw[key];
|
|
136
|
+
if (value === undefined)
|
|
137
|
+
return fallback;
|
|
138
|
+
if (typeof value !== 'string' || !allowed.includes(value)) {
|
|
139
|
+
throw new ConfigError(`${source}: "${key}" must be one of ${allowed.join(', ')}`);
|
|
140
|
+
}
|
|
141
|
+
return value;
|
|
142
|
+
}
|
|
143
|
+
/** Serializes a config for `.egehanrc.json`, with a pointer to the schema for editors. */
|
|
144
|
+
export function serializeConfig(config) {
|
|
145
|
+
const body = {
|
|
146
|
+
$schema: 'https://github.com/BedirhanGurler/egehan/schema/egehanrc.schema.json',
|
|
147
|
+
projectName: config.projectName,
|
|
148
|
+
dedication: config.dedication,
|
|
149
|
+
language: config.language,
|
|
150
|
+
tone: config.tone,
|
|
151
|
+
theme: config.theme,
|
|
152
|
+
redactEmails: config.redactEmails,
|
|
153
|
+
anonymizeAuthors: config.anonymizeAuthors,
|
|
154
|
+
includeMergeCommits: config.includeMergeCommits,
|
|
155
|
+
format: config.format,
|
|
156
|
+
output: config.output,
|
|
157
|
+
};
|
|
158
|
+
return `${JSON.stringify(body, null, 2)}\n`;
|
|
159
|
+
}
|
|
160
|
+
//# sourceMappingURL=config.js.map
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { EgehanRules } from '../spec/rules.js';
|
|
2
|
+
import type { ProjectFlavor } from '../engine/types.js';
|
|
3
|
+
/**
|
|
4
|
+
* Works out what kind of project this is, so the narration can borrow its vocabulary — screens and
|
|
5
|
+
* touches for a mobile app, a backbone and data flow for a service.
|
|
6
|
+
*
|
|
7
|
+
* The scan is shallow by design (`rules.json → projectTypes.maxDepth`). Walking a whole repository
|
|
8
|
+
* to find a `.csproj` would make the tool slow on exactly the large repositories where it is most
|
|
9
|
+
* interesting, and a project's identity is declared at its root in practice.
|
|
10
|
+
*
|
|
11
|
+
* Detection is split from scanning so the rules can be tested against a synthetic file list rather
|
|
12
|
+
* than a temporary directory tree — the logic is the part worth testing, not `readdirSync`.
|
|
13
|
+
*/
|
|
14
|
+
export interface FileSystemView {
|
|
15
|
+
/** Repository-relative paths, always with `/` separators. */
|
|
16
|
+
readonly files: readonly string[];
|
|
17
|
+
readonly directories: readonly string[];
|
|
18
|
+
}
|
|
19
|
+
export interface ProjectTypeResult {
|
|
20
|
+
/** Detector ids, highest priority first. */
|
|
21
|
+
readonly detectedTypes: readonly string[];
|
|
22
|
+
readonly flavor: ProjectFlavor;
|
|
23
|
+
}
|
|
24
|
+
export declare function scanRepository(root: string, rules: EgehanRules): FileSystemView;
|
|
25
|
+
export declare function detectProjectTypes(view: FileSystemView, rules: EgehanRules): ProjectTypeResult;
|
|
26
|
+
/**
|
|
27
|
+
* A deliberately tiny glob matcher: `*` matches within one path segment, `**` crosses segments.
|
|
28
|
+
*
|
|
29
|
+
* That is the whole surface the detector patterns use, and a dependency for it would be a
|
|
30
|
+
* dependency in a published CLI that promises not to have any.
|
|
31
|
+
*/
|
|
32
|
+
export declare function matchesGlob(pattern: string, paths: readonly string[]): boolean;
|
|
33
|
+
export declare function globToRegExp(pattern: string): RegExp;
|
|
34
|
+
//# sourceMappingURL=projectType.d.ts.map
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import { readdirSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
export function scanRepository(root, rules) {
|
|
4
|
+
const ignored = new Set(rules.projectTypes.ignoreDirs);
|
|
5
|
+
const files = [];
|
|
6
|
+
const directories = [];
|
|
7
|
+
const walk = (absolute, relative, depth) => {
|
|
8
|
+
let entries;
|
|
9
|
+
try {
|
|
10
|
+
entries = readdirSync(absolute, { withFileTypes: true });
|
|
11
|
+
}
|
|
12
|
+
catch {
|
|
13
|
+
// An unreadable directory is not an error worth failing a chronicle over.
|
|
14
|
+
return;
|
|
15
|
+
}
|
|
16
|
+
for (const entry of entries) {
|
|
17
|
+
const childRelative = relative === '' ? entry.name : `${relative}/${entry.name}`;
|
|
18
|
+
if (entry.isDirectory()) {
|
|
19
|
+
if (ignored.has(entry.name) || entry.name.startsWith('.'))
|
|
20
|
+
continue;
|
|
21
|
+
directories.push(childRelative);
|
|
22
|
+
if (depth < rules.projectTypes.maxDepth) {
|
|
23
|
+
walk(join(absolute, entry.name), childRelative, depth + 1);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
else if (entry.isFile()) {
|
|
27
|
+
files.push(childRelative);
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
};
|
|
31
|
+
walk(root, '', 0);
|
|
32
|
+
return { files: files.sort(), directories: directories.sort() };
|
|
33
|
+
}
|
|
34
|
+
export function detectProjectTypes(view, rules) {
|
|
35
|
+
const fileSet = new Set(view.files);
|
|
36
|
+
const directorySet = new Set(view.directories);
|
|
37
|
+
const matched = rules.projectTypes.detectors
|
|
38
|
+
.filter((detector) => {
|
|
39
|
+
if (detector.anyFile?.some((file) => fileSet.has(file)) === true)
|
|
40
|
+
return true;
|
|
41
|
+
if (detector.anyGlob?.some((pattern) => matchesGlob(pattern, view.files)) === true)
|
|
42
|
+
return true;
|
|
43
|
+
if (detector.allDirs !== undefined && detector.allDirs.length > 0) {
|
|
44
|
+
return detector.allDirs.every((directory) => directorySet.has(directory));
|
|
45
|
+
}
|
|
46
|
+
return false;
|
|
47
|
+
})
|
|
48
|
+
// Priority descending, then id, so equal priorities cannot reorder between runs.
|
|
49
|
+
.sort((a, b) => b.priority - a.priority || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
|
|
50
|
+
const strongest = matched[0];
|
|
51
|
+
return {
|
|
52
|
+
detectedTypes: matched.map((detector) => detector.id),
|
|
53
|
+
flavor: (strongest?.flavor ?? rules.projectTypes.fallbackFlavor),
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* A deliberately tiny glob matcher: `*` matches within one path segment, `**` crosses segments.
|
|
58
|
+
*
|
|
59
|
+
* That is the whole surface the detector patterns use, and a dependency for it would be a
|
|
60
|
+
* dependency in a published CLI that promises not to have any.
|
|
61
|
+
*/
|
|
62
|
+
export function matchesGlob(pattern, paths) {
|
|
63
|
+
const regex = globToRegExp(pattern);
|
|
64
|
+
return paths.some((path) => regex.test(path));
|
|
65
|
+
}
|
|
66
|
+
export function globToRegExp(pattern) {
|
|
67
|
+
let source = '';
|
|
68
|
+
for (let index = 0; index < pattern.length; index += 1) {
|
|
69
|
+
const char = pattern[index];
|
|
70
|
+
if (char === '*') {
|
|
71
|
+
if (pattern[index + 1] === '*') {
|
|
72
|
+
// `**/` may also match zero directories, so `**/*.csproj` matches a root-level file too.
|
|
73
|
+
if (pattern[index + 2] === '/') {
|
|
74
|
+
source += '(?:[^/]+/)*';
|
|
75
|
+
index += 2;
|
|
76
|
+
}
|
|
77
|
+
else {
|
|
78
|
+
source += '.*';
|
|
79
|
+
index += 1;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
else {
|
|
83
|
+
source += '[^/]*';
|
|
84
|
+
}
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
if (char === '?') {
|
|
88
|
+
source += '[^/]';
|
|
89
|
+
continue;
|
|
90
|
+
}
|
|
91
|
+
source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
|
|
92
|
+
}
|
|
93
|
+
return new RegExp(`^${source}$`);
|
|
94
|
+
}
|
|
95
|
+
//# sourceMappingURL=projectType.js.map
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { EgehanReport, NormalizedCommit, ProjectInfo, ReportConfig, SealedCapsule } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Assembles the report.
|
|
4
|
+
*
|
|
5
|
+
* This is the only place in the engine that knows the whole pipeline, and it is deliberately
|
|
6
|
+
* boring: each stage is a pure function of the stage before it, and nothing here reads the
|
|
7
|
+
* filesystem, spawns a process or looks at the clock. `generatedAt` arrives as an argument rather
|
|
8
|
+
* than being read here, which is what lets the conformance tests compare two engines' output byte
|
|
9
|
+
* for byte.
|
|
10
|
+
*/
|
|
11
|
+
export interface BuildReportInput {
|
|
12
|
+
readonly commits: readonly NormalizedCommit[];
|
|
13
|
+
readonly project: Omit<ProjectInfo, 'dedication'> & {
|
|
14
|
+
readonly dedication: string | null;
|
|
15
|
+
};
|
|
16
|
+
readonly config: ReportConfig;
|
|
17
|
+
readonly range: {
|
|
18
|
+
readonly since: string | null;
|
|
19
|
+
readonly until: string | null;
|
|
20
|
+
readonly truncated: boolean;
|
|
21
|
+
};
|
|
22
|
+
readonly generator: {
|
|
23
|
+
readonly version: string;
|
|
24
|
+
readonly generatedAt: string;
|
|
25
|
+
};
|
|
26
|
+
readonly capsule: SealedCapsule | null;
|
|
27
|
+
}
|
|
28
|
+
export declare class EmptyHistoryError extends Error {
|
|
29
|
+
constructor(message: string);
|
|
30
|
+
}
|
|
31
|
+
export declare function buildReport(input: BuildReportInput): EgehanReport;
|
|
32
|
+
//# sourceMappingURL=buildReport.d.ts.map
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
import { loadDictionary } from '../spec/dictionary.js';
|
|
2
|
+
import { loadRules } from '../spec/rules.js';
|
|
3
|
+
import { classifyCommits } from './classifier.js';
|
|
4
|
+
import { classificationFor, groupIntoChapters } from './chapters.js';
|
|
5
|
+
import { inclusiveDaySpan } from './datetime.js';
|
|
6
|
+
import { computeMilestones } from './milestones.js';
|
|
7
|
+
import { createNarrationContext, narrateChapter, narrateEntry } from './narrator.js';
|
|
8
|
+
import { prepareCommits } from './prepare.js';
|
|
9
|
+
import { computePulse } from './pulse.js';
|
|
10
|
+
import { buildAuthors } from './privacy.js';
|
|
11
|
+
export class EmptyHistoryError extends Error {
|
|
12
|
+
constructor(message) {
|
|
13
|
+
super(message);
|
|
14
|
+
this.name = 'EmptyHistoryError';
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
export function buildReport(input) {
|
|
18
|
+
const rules = loadRules();
|
|
19
|
+
const dictionary = loadDictionary(input.config.language);
|
|
20
|
+
const commits = input.config.includeMergeCommits
|
|
21
|
+
? input.commits
|
|
22
|
+
: input.commits.filter((commit) => commit.parents.length <= 1);
|
|
23
|
+
if (commits.length === 0) {
|
|
24
|
+
throw new EmptyHistoryError(input.commits.length === 0
|
|
25
|
+
? 'This range contains no commits, so there is no story to tell yet.'
|
|
26
|
+
: 'This range contains only merge commits. Pass --include-merges to narrate them.');
|
|
27
|
+
}
|
|
28
|
+
const prepared = prepareCommits(commits, rules, {
|
|
29
|
+
language: input.config.language,
|
|
30
|
+
redactEmails: input.config.redactEmails,
|
|
31
|
+
});
|
|
32
|
+
const { authors, identityOf } = buildAuthors(commits, rules, {
|
|
33
|
+
redactEmails: input.config.redactEmails,
|
|
34
|
+
anonymizeAuthors: input.config.anonymizeAuthors,
|
|
35
|
+
language: input.config.language,
|
|
36
|
+
});
|
|
37
|
+
const context = createNarrationContext(dictionary, rules, input.config.tone, input.config.language, input.project.flavor);
|
|
38
|
+
const classifications = classifyCommits(prepared, rules);
|
|
39
|
+
const entries = prepared.map((commit) => {
|
|
40
|
+
const classification = classificationFor(classifications, commit);
|
|
41
|
+
const author = identityOf(commit.source);
|
|
42
|
+
const narrated = narrateEntry(commit, classification.category, classification.secondaryCategories, author.displayName, context);
|
|
43
|
+
return {
|
|
44
|
+
sha: commit.source.sha,
|
|
45
|
+
shortSha: commit.source.sha.slice(0, 7),
|
|
46
|
+
parents: commit.source.parents,
|
|
47
|
+
authorId: author.id,
|
|
48
|
+
authoredAt: commit.source.authoredAt,
|
|
49
|
+
committedAt: commit.source.committedAt,
|
|
50
|
+
tzOffsetMinutes: commit.authoredAt.offsetMinutes,
|
|
51
|
+
localHour: commit.authoredAt.hour,
|
|
52
|
+
localWeekday: commit.authoredAt.weekday,
|
|
53
|
+
subject: commit.subject,
|
|
54
|
+
cleanSubject: commit.cleanSubject,
|
|
55
|
+
conventional: commit.conventional,
|
|
56
|
+
tags: commit.tags,
|
|
57
|
+
stats: {
|
|
58
|
+
filesCount: commit.filesCount,
|
|
59
|
+
insertions: commit.insertions,
|
|
60
|
+
deletions: commit.deletions,
|
|
61
|
+
sizeBucket: commit.sizeBucket,
|
|
62
|
+
},
|
|
63
|
+
category: classification.category,
|
|
64
|
+
secondaryCategories: classification.secondaryCategories,
|
|
65
|
+
narrative: narrated.narrative,
|
|
66
|
+
isMerge: commit.isMerge,
|
|
67
|
+
variantIndex: narrated.variantIndex,
|
|
68
|
+
};
|
|
69
|
+
});
|
|
70
|
+
const chapters = groupIntoChapters(prepared, classifications, rules).map((group, index) => toChapter(group.category, group.commits, index, identityOf, context));
|
|
71
|
+
const pulse = computePulse(prepared, rules, context);
|
|
72
|
+
const milestones = computeMilestones(prepared, pulse, rules, context);
|
|
73
|
+
const firstCommit = prepared[0];
|
|
74
|
+
const lastCommit = prepared[prepared.length - 1];
|
|
75
|
+
return {
|
|
76
|
+
schemaVersion: rules.schemaVersion,
|
|
77
|
+
generator: {
|
|
78
|
+
name: 'egehan',
|
|
79
|
+
version: input.generator.version,
|
|
80
|
+
platform: 'node',
|
|
81
|
+
specVersion: rules.specVersion,
|
|
82
|
+
dictionaryVersion: dictionary.version,
|
|
83
|
+
generatedAt: input.generator.generatedAt,
|
|
84
|
+
},
|
|
85
|
+
project: input.project,
|
|
86
|
+
config: input.config,
|
|
87
|
+
range: {
|
|
88
|
+
since: input.range.since,
|
|
89
|
+
until: input.range.until,
|
|
90
|
+
firstCommitAt: firstCommit.source.authoredAt,
|
|
91
|
+
lastCommitAt: lastCommit.source.authoredAt,
|
|
92
|
+
days: inclusiveDaySpan(firstCommit.authoredAt, lastCommit.authoredAt),
|
|
93
|
+
truncated: input.range.truncated,
|
|
94
|
+
},
|
|
95
|
+
totals: computeTotals(prepared, entries, authors.length),
|
|
96
|
+
authors,
|
|
97
|
+
chapters,
|
|
98
|
+
entries,
|
|
99
|
+
pulse,
|
|
100
|
+
milestones,
|
|
101
|
+
capsule: input.capsule,
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
function toChapter(category, commits, index, identityOf, context) {
|
|
105
|
+
const first = commits[0];
|
|
106
|
+
const last = commits[commits.length - 1];
|
|
107
|
+
const files = new Set();
|
|
108
|
+
const authorIds = new Set();
|
|
109
|
+
let insertions = 0;
|
|
110
|
+
let deletions = 0;
|
|
111
|
+
for (const commit of commits) {
|
|
112
|
+
insertions += commit.insertions;
|
|
113
|
+
deletions += commit.deletions;
|
|
114
|
+
authorIds.add(identityOf(commit.source).id);
|
|
115
|
+
for (const file of commit.source.files)
|
|
116
|
+
files.add(file.path);
|
|
117
|
+
}
|
|
118
|
+
const narrated = narrateChapter({
|
|
119
|
+
category,
|
|
120
|
+
commits: commits.length,
|
|
121
|
+
insertions,
|
|
122
|
+
deletions,
|
|
123
|
+
filesCount: files.size,
|
|
124
|
+
authorsCount: authorIds.size,
|
|
125
|
+
from: first.authoredAt,
|
|
126
|
+
to: last.authoredAt,
|
|
127
|
+
seedSha: first.source.sha,
|
|
128
|
+
}, context);
|
|
129
|
+
return {
|
|
130
|
+
id: `chapter-${String(index + 1).padStart(3, '0')}`,
|
|
131
|
+
category,
|
|
132
|
+
title: narrated.title,
|
|
133
|
+
narrative: narrated.narrative,
|
|
134
|
+
from: first.source.authoredAt,
|
|
135
|
+
to: last.source.authoredAt,
|
|
136
|
+
entryShas: commits.map((commit) => commit.source.sha),
|
|
137
|
+
stats: {
|
|
138
|
+
commits: commits.length,
|
|
139
|
+
insertions,
|
|
140
|
+
deletions,
|
|
141
|
+
filesCount: files.size,
|
|
142
|
+
// Sorted, because a Set's iteration order is an implementation detail and this value is
|
|
143
|
+
// compared across engines.
|
|
144
|
+
authorIds: [...authorIds].sort(),
|
|
145
|
+
},
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
function computeTotals(prepared, entries, authorCount) {
|
|
149
|
+
const files = new Set();
|
|
150
|
+
const byCategory = {
|
|
151
|
+
birth: 0,
|
|
152
|
+
'first-steps': 0,
|
|
153
|
+
'growing-pains': 0,
|
|
154
|
+
'midnight-oil': 0,
|
|
155
|
+
milestone: 0,
|
|
156
|
+
evolution: 0,
|
|
157
|
+
};
|
|
158
|
+
const byType = {};
|
|
159
|
+
let insertions = 0;
|
|
160
|
+
let deletions = 0;
|
|
161
|
+
let tags = 0;
|
|
162
|
+
let mergeCommits = 0;
|
|
163
|
+
for (const commit of prepared) {
|
|
164
|
+
insertions += commit.insertions;
|
|
165
|
+
deletions += commit.deletions;
|
|
166
|
+
tags += commit.tags.length;
|
|
167
|
+
if (commit.isMerge)
|
|
168
|
+
mergeCommits += 1;
|
|
169
|
+
for (const file of commit.source.files)
|
|
170
|
+
files.add(file.path);
|
|
171
|
+
byType[commit.conventional.type] = (byType[commit.conventional.type] ?? 0) + 1;
|
|
172
|
+
}
|
|
173
|
+
for (const entry of entries) {
|
|
174
|
+
byCategory[entry.category] += 1;
|
|
175
|
+
}
|
|
176
|
+
return {
|
|
177
|
+
commits: prepared.length,
|
|
178
|
+
authors: authorCount,
|
|
179
|
+
insertions,
|
|
180
|
+
deletions,
|
|
181
|
+
filesTouched: files.size,
|
|
182
|
+
tags,
|
|
183
|
+
mergeCommits,
|
|
184
|
+
byCategory,
|
|
185
|
+
byType,
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
//# sourceMappingURL=buildReport.js.map
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { EgehanRules } from '../spec/rules.js';
|
|
2
|
+
import type { Classification } from './classifier.js';
|
|
3
|
+
import type { PreparedCommit } from './prepare.js';
|
|
4
|
+
import type { Category } from './types.js';
|
|
5
|
+
/**
|
|
6
|
+
* Groups commits into chapters, so the chronicle reads as a story instead of a list.
|
|
7
|
+
*
|
|
8
|
+
* A chapter is a run of consecutive commits sharing a primary category. Two rules break a run
|
|
9
|
+
* early, both from `rules.json → chapters`: a chapter never grows past `maxEntriesPerChapter`
|
|
10
|
+
* (nobody reads a eighty-commit wall of text), and a gap longer than `maxGapHoursWithinChapter`
|
|
11
|
+
* starts a new one — a project that was dormant for three months and then saw more evolution
|
|
12
|
+
* commits lived through two separate periods, not one.
|
|
13
|
+
*/
|
|
14
|
+
export interface ChapterGroup {
|
|
15
|
+
readonly category: Category;
|
|
16
|
+
readonly commits: readonly PreparedCommit[];
|
|
17
|
+
}
|
|
18
|
+
export declare function groupIntoChapters(commits: readonly PreparedCommit[], classifications: ReadonlyMap<string, Classification>, rules: EgehanRules): ChapterGroup[];
|
|
19
|
+
export declare function classificationFor(classifications: ReadonlyMap<string, Classification>, commit: PreparedCommit): Classification;
|
|
20
|
+
//# sourceMappingURL=chapters.d.ts.map
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { hoursBetween } from './datetime.js';
|
|
2
|
+
export function groupIntoChapters(commits, classifications, rules) {
|
|
3
|
+
const { maxEntriesPerChapter, maxGapHoursWithinChapter } = rules.chapters;
|
|
4
|
+
const groups = [];
|
|
5
|
+
let current = null;
|
|
6
|
+
for (const commit of commits) {
|
|
7
|
+
const category = classificationFor(classifications, commit).category;
|
|
8
|
+
if (current !== null) {
|
|
9
|
+
const previous = current.commits[current.commits.length - 1];
|
|
10
|
+
const continuesChapter = current.category === category &&
|
|
11
|
+
current.commits.length < maxEntriesPerChapter &&
|
|
12
|
+
(previous === undefined ||
|
|
13
|
+
hoursBetween(previous.authoredAt, commit.authoredAt) <= maxGapHoursWithinChapter);
|
|
14
|
+
if (continuesChapter) {
|
|
15
|
+
current.commits.push(commit);
|
|
16
|
+
continue;
|
|
17
|
+
}
|
|
18
|
+
groups.push({ category: current.category, commits: current.commits });
|
|
19
|
+
}
|
|
20
|
+
current = { category, commits: [commit] };
|
|
21
|
+
}
|
|
22
|
+
if (current !== null)
|
|
23
|
+
groups.push({ category: current.category, commits: current.commits });
|
|
24
|
+
return groups;
|
|
25
|
+
}
|
|
26
|
+
export function classificationFor(classifications, commit) {
|
|
27
|
+
const classification = classifications.get(commit.source.sha);
|
|
28
|
+
if (classification === undefined) {
|
|
29
|
+
throw new Error(`Commit ${commit.source.sha} was never classified`);
|
|
30
|
+
}
|
|
31
|
+
return classification;
|
|
32
|
+
}
|
|
33
|
+
//# sourceMappingURL=chapters.js.map
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { EgehanRules } from '../spec/rules.js';
|
|
2
|
+
import type { PreparedCommit } from './prepare.js';
|
|
3
|
+
import type { Category } from './types.js';
|
|
4
|
+
/**
|
|
5
|
+
* Places every commit in a chapter of the story.
|
|
6
|
+
*
|
|
7
|
+
* A commit is tested against all six categories. The first match in
|
|
8
|
+
* `rules.json → classification.evaluationOrder` becomes its primary category; the rest become
|
|
9
|
+
* secondary categories, and a secondary that is also a *modifier* category can contribute one
|
|
10
|
+
* extra clause to the sentence. That is how a deletion-heavy 02:41 refactor comes out as growing
|
|
11
|
+
* pains that also happened in the middle of the night, rather than having to choose one truth.
|
|
12
|
+
*
|
|
13
|
+
* Every threshold is read from the rules file. There is no number in this file that an engine in
|
|
14
|
+
* another language could not see.
|
|
15
|
+
*/
|
|
16
|
+
export interface Classification {
|
|
17
|
+
readonly category: Category;
|
|
18
|
+
readonly secondaryCategories: readonly Category[];
|
|
19
|
+
}
|
|
20
|
+
export declare function classifyCommits(commits: readonly PreparedCommit[], rules: EgehanRules): Map<string, Classification>;
|
|
21
|
+
//# sourceMappingURL=classifier.d.ts.map
|