@kaynooo/cli-code 0.17.0 → 0.17.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.
Files changed (3) hide show
  1. package/README.md +3 -2
  2. package/dist/cli.js +39 -18
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -33,13 +33,14 @@ src hotspots --since '3 months ago' --limit 10
33
33
 
34
34
  - `src todo-scan [path...]` prints `<file>:<line>: <comment>` for each comment holding `TODO`, `FIXME` or an `owner/repo#N` reference, over the same files as `src peek`. A comment opens with `//` (not a URL's), `/*`, `<!--`, a `#` or `--` standing alone, or the `*` of a block comment's line; in Markdown and HTML only `<!--` does.
35
35
  - `--stale` looks each referenced issue up with `ft issue <n>... -r <owner/repo> --json`, one call per repository, or with `gh api` for a repository Forgejo does not have (a GitHub one), keeps the comments naming a closed issue (`src/a.ts:3: kaynooo/kayjs#823 closed: ...`) and exits 1 when it finds one; a repository neither can reach is named on stderr and makes the run exit 2 when no stale comment was found, so a clean exit never hides an unchecked issue. `ft` is needed only for a reference it can look up.
36
- - `--json` prints `[{path, line, kind, text, refs}]`, each ref with its `state` under `--stale`.
36
+ - `--older <duration>` (`30d`, `12w`, `6m`) keeps the comments whose line last changed longer ago than that, dated by `git blame` (a file git cannot blame is left out), and shows each one's age. At most 100 comments are listed, the count of the rest after them (`--limit <n>`, `--full` for all).
37
+ - `--json` prints `[{path, line, kind, text, refs}]`, each ref with its `state` under `--stale`, never cut unless `--limit` is given.
37
38
 
38
39
  ## src hotspots
39
40
 
40
41
  - `src hotspots [dir]` ranks the source files by complexity times churn, so the files both hard to read and often edited come first: rank, score, churn, recent, complexity, lines, file and the file's most complex declaration. The files are the ones git keeps (`.gitignore` honoured).
41
42
  - Churn is the commits touching the file since `--since` (any date git reads, `6 months ago` by default), counted from one `git log`. The score uses `recent`, the commits weighted by age (half as much every `--half-life`, `90d` by default, `0` to count them alike), and leaves out the commits touching more than `--bulk` files (25), the format and rename sweeps. Complexity is the decision points of the file (`if`, loops, `case`, `catch`, `&&`, `||`, `??`, ternaries, `and`/`or`) plus one, counted with comments and strings blanked; it is computed in-house (js, ts, vue, svelte, astro, kay, php, py, go, rs, rb, java, kt, swift, cs, c, cpp, scala, dart, lua and shell files are ranked) so the bin needs no dependency and reads any language the same way.
42
- - `--limit <n>` (`-n`) sets how many files are listed (20, the count of the rest after them), `--full` lists all, `--json` is never cut unless `--limit` is given. `--all` keeps test files and generated files (`dist/`, `*.d.ts`, `*.min.js`, snapshots, files whose first lines say generated), `--json` prints `[{rank, path, score, churn, recent, complexity, worst, lines}]`. The most complex declaration is found from the indentation alone (a class is opened into its methods), so it reads any language the same way.
43
+ - `--limit <n>` (`-n`) sets how many files are listed (20, the count of the rest after them), `--full` lists all, `--json` is never cut unless `--limit` is given. `--all` keeps test files and generated files (`dist/`, `*.d.ts`, `*.min.js`, snapshots, files whose first lines say generated), `--json` prints `[{rank, path, score, churn, recent, changed, authors, solo, complexity, worst, lines}]` (`changed` the lines added and deleted). `--by-lines` scores the lines changed instead of the commits, and each row also shows its author count (`solo` when one author wrote every change). The most complex declaration is found from the indentation alone (a class is opened into its methods), so it reads any language the same way.
43
44
  - Exits 1 when no file has commits in the window, 2 on a usage error or outside a git repository.
44
45
 
45
46
  `~/.config/kaynooo-cli/hotspots.json` (`$XDG_CONFIG_HOME/kaynooo-cli/` when set) changes the defaults of `src hotspots`: `since` (a date as git reads it, `6 months ago`), `bulk` (25) and `limit` (20, the files listed).
package/dist/cli.js CHANGED
@@ -574,7 +574,27 @@ var init_format = __esm(() => {
574
574
  // ../kit/src/help.ts
575
575
  import process8 from "process";
576
576
  function usageLine(usage, colors = paint(process8.stdout)) {
577
- return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
577
+ const lines = usage.replace(USAGE_PREFIX, "").split(`
578
+ `);
579
+ const blank = lines.indexOf("");
580
+ const synopses = blank === -1 ? lines : lines.slice(0, blank);
581
+ const details = blank === -1 ? [] : lines.slice(blank + 1);
582
+ const colon = synopses[0].indexOf(": ");
583
+ const inline = synopses[0].slice(colon + 2);
584
+ const summary = colon === -1 ? details.shift() : `${inline.charAt(0).toUpperCase()}${inline.slice(1)}`;
585
+ if (colon !== -1)
586
+ synopses[0] = synopses[0].slice(0, colon);
587
+ const head = `${colors.bold("Usage:")} ${synopses.map((line) => line.replaceAll(OPTIONAL, (part) => colors.dim(part))).join(`
588
+ `)}`;
589
+ const lead = summary === undefined ? [] : ["", colors.bold(prose(summary, colors))];
590
+ const rest = details.length === 0 ? [] : ["", ...details.map((line) => prose(line, colors))];
591
+ return [head, ...lead, ...rest].join(`
592
+ `);
593
+ }
594
+ function prose(line, colors) {
595
+ if (colors.cyan("x") === "x")
596
+ return line;
597
+ return line.replaceAll(PROSE_MARKS, (match, code, flag) => code === undefined ? colors.cyan(flag ?? match) : colors.bold(code));
578
598
  }
579
599
  function helpText(usage, options, colors = paint(process8.stdout), { examples = [], exits = [] } = {}) {
580
600
  return [usageLine(usage, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exitRows(exits, colors), ...exampleRows(examples, colors)].join(`
@@ -623,13 +643,14 @@ function optionRows(options, colors = paint(process8.stdout)) {
623
643
  const width = Math.max(0, ...rows.map((row) => row.width));
624
644
  return rows.map((row) => row.description === "" ? ` ${row.flag}` : ` ${row.flag}${" ".repeat(width - row.width)} ${colors.dim(row.description)}`);
625
645
  }
626
- var OPTIONAL, USAGE_PREFIX, FULL_STOP, MAX_INLINE_CHOICES = 24;
646
+ var OPTIONAL, USAGE_PREFIX, FULL_STOP, PROSE_MARKS, MAX_INLINE_CHOICES = 24;
627
647
  var init_help = __esm(() => {
628
648
  init_mode();
629
649
  init_style();
630
650
  OPTIONAL = /(?<!\x1B)\[[^\]]+\]/g;
631
651
  USAGE_PREFIX = /^usage:\s*/i;
632
652
  FULL_STOP = /\.$/;
653
+ PROSE_MARKS = /`([^`\n]+)`|(?<![\w-])(--[a-z][\w-]*|-[a-z](?![\w-]))/gi;
633
654
  });
634
655
 
635
656
  // ../kit/src/text.ts
@@ -882,7 +903,7 @@ function nearestOption(message, options, allowNegative) {
882
903
  const meant = closest(word, known.map((flag) => flag.replace(DASHES, "")));
883
904
  return meant === undefined ? undefined : `did you mean ${known.find((flag) => flag.replace(DASHES, "") === meant)}?`;
884
905
  }
885
- var DASHES, Exit, UsageError, HelpShown, completion, OUTPUT_OPTIONS, UNKNOWN_OPTION;
906
+ var DASHES, EXIT, Exit, UsageError, HelpShown, completion, OUTPUT_OPTIONS, UNKNOWN_OPTION;
886
907
  var init_args = __esm(() => {
887
908
  init_format();
888
909
  init_help();
@@ -890,14 +911,21 @@ var init_args = __esm(() => {
890
911
  init_help();
891
912
  init_input();
892
913
  DASHES = /^-+/;
914
+ EXIT = Symbol.for("@kaynooo/cli-kit/Exit");
893
915
  Exit = class Exit extends Error {
894
916
  code;
895
917
  hint;
918
+ [EXIT] = true;
896
919
  constructor(message, code, hint) {
897
920
  super(message);
898
921
  this.code = code;
899
922
  this.hint = hint;
900
923
  }
924
+ static [Symbol.hasInstance](value) {
925
+ if (this !== Exit)
926
+ return Function.prototype[Symbol.hasInstance].call(this, value);
927
+ return typeof value === "object" && value !== null && value[EXIT] === true;
928
+ }
901
929
  };
902
930
  UsageError = class UsageError extends Exit {
903
931
  constructor(message, hint) {
@@ -1481,10 +1509,10 @@ function flagNames(argv) {
1481
1509
  const names = (end === -1 ? argv : argv.slice(0, end)).filter((word) => word.startsWith("-") && word !== "-").map((word) => word.includes("=") ? word.slice(0, word.indexOf("=")) : word);
1482
1510
  return [...new Set(names)].filter((name) => name.length <= LONGEST_NAME && FLAG_NAME.test(name));
1483
1511
  }
1484
- function usageEntry(bin, command, argv, code, now = new Date) {
1512
+ function usageEntry(bin, command, argv, code, { ms, now = new Date } = {}) {
1485
1513
  const unknown = code === 2 && usageError !== undefined ? UNKNOWN_OPTION2.exec(usageError)?.[1] : undefined;
1486
1514
  usageError = undefined;
1487
- return { at: now.toISOString(), bin, ...command === undefined ? {} : { command }, flags: flagNames(argv), code, ...unknown === undefined ? {} : { unknown } };
1515
+ return { at: now.toISOString(), bin, ...command === undefined ? {} : { command }, flags: flagNames(argv), code, ...unknown === undefined ? {} : { unknown }, ...ms === undefined ? {} : { ms: Math.round(ms) } };
1488
1516
  }
1489
1517
  function recordUsage(entry, env = process15.env) {
1490
1518
  if (!usageRecorded(env))
@@ -1787,7 +1815,7 @@ async function runCli(cli, argv = scriptArgs()) {
1787
1815
  notifyEnd(command === undefined ? cli.name : `${cli.name} ${command}`, code, performance.now() - started);
1788
1816
  if (cli.usage !== false) {
1789
1817
  try {
1790
- recordUsage(usageEntry(cli.name, command, argv, code));
1818
+ recordUsage(usageEntry(cli.name, command, argv, code, { ms: performance.now() - started }));
1791
1819
  } catch {}
1792
1820
  }
1793
1821
  return code;
@@ -2049,9 +2077,7 @@ var DEFAULT_HALF_LIFE = "90d";
2049
2077
  var DEFAULT_COUNT = configuredNumber("hotspots", "limit", 20);
2050
2078
  var USAGE = `src hotspots [options] [dir]: ranks the source files under dir (here by default) by complexity times churn, the ones both hard to read and often edited first, honouring .gitignore
2051
2079
 
2052
- Complexity is the count of decision points in the file (branches, loops, cases, catches, boolean operators, ternaries) plus one, churn the commits touching it since --since (${DEFAULT_SINCE}), score their product. A commit counts for less the older it is (half as much every --half-life, 0 for all alike) and a commit touching more than --bulk files, a format or rename sweep, is left out. --by-lines scores the lines changed instead of the commits. Each file also shows how many lines changed, its author count ("solo" when one author wrote every change) and its most complex declaration, found by indentation. Test files and generated or built files are left out unless --all.
2053
-
2054
- Lists at most ${DEFAULT_COUNT} files, the count of the rest after them (--limit <n>, --full for all); --json is never cut unless --limit is given.`;
2080
+ Complexity is the count of decision points in the file plus one, churn the commits touching it since --since, score their product. A commit counts for less the older it is, and one touching more files than --bulk, a format or rename sweep, is left out. Each file also shows its lines changed, its author count ("solo" when one author wrote every change) and its most complex declaration. Test files and generated or built files are left out unless --all.`;
2055
2081
  var EXITS = [[0, "it ranked the files"], [1, "no file has commits in the window"], [2, "a usage error or outside a git repository"]];
2056
2082
  var OPTIONS = {
2057
2083
  since: { type: "string", short: "s", description: `only count the commits since this date, as git reads it (${DEFAULT_SINCE})` },
@@ -2310,9 +2336,7 @@ src peek --refs <symbol> [path...] the lines naming the symbol, grouped
2310
2336
  src peek --outline <file>... the declarations and class members, a Markdown file's headings
2311
2337
  src peek --around <regex> [-C 3] [path...] the lines around each match, overlapping ones merged
2312
2338
  <output> | src peek [-C 3] the lines around each path:line the output opens a line with (errs, rg -n, grep -n, tsc, linters)
2313
- The paths default to the files git keeps here (.gitignore holds).
2314
- --refs lists at most 100 lines and --around prints at most 20 spans, the count of the rest after them (--limit <n>, --full for all).
2315
- --json prints spans as [{path, from, to, lines}], --refs as [{path, line, text}] ({definitions, references} with --defs-first), --outline as [{path, line, depth, text}], the lines never cut and the rows never counted off unless --limit is given.`;
2339
+ The paths default to the files git keeps here (\`.gitignore\` holds).`;
2316
2340
  var EXITS2 = [[0, "it printed something"], [1, "nothing is found, a file cannot be read or a span starts past the end"], [2, "a usage error or a path outside the repository"]];
2317
2341
  var REFS_LIMIT = 100;
2318
2342
  var AROUND_LIMIT = 20;
@@ -2325,7 +2349,7 @@ var OPTIONS2 = {
2325
2349
  "defs-first": { type: "boolean", description: "with --refs, print the symbol's declarations before its lines" },
2326
2350
  context: { type: "string", short: "C", description: "lines on each side of an --around match or a piped location (3)" },
2327
2351
  ...limitOptions(REFS_LIMIT),
2328
- json: jsonOption()
2352
+ json: jsonOption("spans [{path, from, to, lines}], --refs [{path, line, text}] ({definitions, references} with --defs-first), --outline [{path, line, depth, text}]")
2329
2353
  };
2330
2354
  var TARGET = /^(.+?):(\d+)(?:-(\d+))?$/;
2331
2355
  var LONGEST_LINE = 300;
@@ -2630,11 +2654,8 @@ async function lookUp(refs, cwd) {
2630
2654
  // src/todo-scan.ts
2631
2655
  var USAGE3 = `src todo-scan [options] [path...]: lists the TODO, FIXME, HACK, XXX and owner/repo#N comments under the paths (here by default), each as <file>:<line>: <comment>, honouring .gitignore
2632
2656
 
2633
- --older <duration> keeps only the comments whose line last changed longer ago than that (30d, 12w, 6m: git blame dates each one, a file git cannot blame is left out) and shows each one's age.
2634
-
2635
- --stale keeps only the comments naming a closed issue, each issue's state looked up with ft, or gh for a GitHub repository, and exits 1 when it finds one.
2636
-
2637
- Lists at most 100 comments, the count of the rest after them (--limit <n>, --full for all); --json is never cut unless --limit is given.`;
2657
+ --older <duration> keeps the comments whose line last changed longer ago than that (\`30d\`, \`12w\`, \`6m\`, dated by git blame) and shows each one's age.
2658
+ --stale keeps the comments naming a closed issue, looked up with \`ft\`, or \`gh\` for a GitHub repository, and exits 1 when it finds one.`;
2638
2659
  var EXITS3 = [[0, "it listed the comments or found no stale one"], [1, "--stale finds one"], [2, "a usage error or when --stale could not look a repository up (ft and gh both failed)"]];
2639
2660
  var LIST_LIMIT = 100;
2640
2661
  var DAY_MS3 = 86400000;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kaynooo/cli-code",
3
3
  "type": "module",
4
- "version": "0.17.0",
4
+ "version": "0.17.1",
5
5
  "description": "src: source read by spans, symbols and outlines in one call, the TODO and issue-reference comments of a repository with stale ones flagged, and the files ranked by complexity times git churn.",
6
6
  "author": "Kaynooo <contact@kaynooo.fr>",
7
7
  "license": "MIT",
@@ -40,6 +40,6 @@
40
40
  "@kaynooo/utils": "3.1.0"
41
41
  },
42
42
  "devDependencies": {
43
- "@kaynooo/cli-kit": "0.43.0"
43
+ "@kaynooo/cli-kit": "0.45.1"
44
44
  }
45
45
  }