adsa-cli 0.1.1 → 0.1.2

package/README.md

@@ -58,6 +58,10 @@ the version checked out in front of them instead of reading files and guessing.
 
 `npx adsa-cli rubric` prints what 1, 3 and 5 mean for each.
 
+`--out <dir>` puts every artifact of a run together somewhere else — the report, the
+score, the badge and the history — and reads the previous score from there too, so a
+repository can be audited without writing anything into it.
+
 ## Commands
 
 ```

package/bin/adsa.mjs

@@ -11,14 +11,14 @@
  *   adsa badge                    the README badge for the committed score
  */
 import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { loadConfig, resolveTarget } from "../lib/config.mjs";
 import { scan } from "../lib/scan.mjs";
 import { RUBRIC, score, scoreFile } from "../lib/score.mjs";
 import { buildTodo, html, markdown } from "../lib/report.mjs";
 import { badgeEndpoint, badgeMarkdown } from "../lib/badge.mjs";
-import { isDir } from "../lib/fsx.mjs";
+import { exists, isDir } from "../lib/fsx.mjs";
 import { DIR, appendHistory, compare, readHistory, write } from "../lib/history.mjs";
 import { FIXES, applyFix } from "../lib/fix.mjs";
 import { evaluate, taskFile } from "../lib/eval.mjs";
@@ -47,7 +47,7 @@ Usage
 
 Options
   --json                      Machine-readable output
-  --out <dir>                 Where to write the report (default: .adsa)
+  --out <dir>                 Write every artifact here instead of .adsa/
   --gate                      Exit non-zero if the score dropped, or is below --min
   --min <n>                   Minimum acceptable total for --gate
   --dry-run                   fix: show what would change, write nothing
@@ -157,9 +157,13 @@ function cmdAudit(dir, flags, out, json) {
         return 1;
     }
     const scored = score(facts, config);
-    const outDir = flags.out || DIR;
+    // Everything one run writes lands together. --out is read from where the command
+    // was typed, so an absolute path is absolute and a relative one is relative to
+    // the reader, not to the repository being audited.
+    const artefacts = flags.out ? resolve(process.cwd(), flags.out) : join(root, DIR);
+    const fresh = !exists(join(artefacts, "score.json"));
     const file = scoreFile(facts, scored);
-    const previous = readJson(join(root, DIR, "score.json"));
+    const previous = readJson(join(artefacts, "score.json"));
     const delta = compare(previous, file);
 
     if (flags.json) {
@@ -191,14 +195,25 @@ function cmdAudit(dir, flags, out, json) {
         }
     }
 
-    const history = appendHistory(root, { date: file.generatedAt, total: file.total, max: file.max, dimensions: file.dimensions });
-    write(join(root, DIR, "score.json"), file);
-    write(join(root, DIR, "badge.json"), badgeEndpoint(file.total, file.max));
-    const reportDir = join(root, outDir);
-    mkdirSync(reportDir, { recursive: true });
-    writeFileSync(join(reportDir, "report.html"), html(facts, scored, history));
-    writeFileSync(join(reportDir, "report.md"), markdown(facts, scored));
-    if (!flags.json && !flags.quiet) out(dim(`\nReport: ${join(outDir, "report.html")} · score: ${join(DIR, "score.json")}`));
+    const history = appendHistory(artefacts, { date: file.generatedAt, total: file.total, max: file.max, dimensions: file.dimensions });
+    write(join(artefacts, "score.json"), file);
+    write(join(artefacts, "badge.json"), badgeEndpoint(file.total, file.max));
+    mkdirSync(artefacts, { recursive: true });
+    writeFileSync(join(artefacts, "report.html"), html(facts, scored, history));
+    writeFileSync(join(artefacts, "report.md"), markdown(facts, scored));
+    // A path that climbs out of the current directory reads better absolute than as
+    // a ladder of "..".
+    const near = relative(process.cwd(), artefacts);
+    const shown = !near ? "." : near.startsWith("..") ? artefacts : near;
+    if (!flags.json && !flags.quiet) {
+        out(dim(`\nReport: ${join(shown, "report.html")} · score: ${join(shown, "score.json")}`));
+        // Say once what the directory is for, rather than leave someone to guess
+        // whether a new folder in their repository belongs in the commit.
+        if (fresh && !flags.out && exists(join(root, ".git"))) {
+            out(dim("  score.json, badge.json and history.json are meant to be committed — the badge and the gate read them."));
+            out(dim("  report.html and report.md are rewritten every run; ignore them if you would rather not carry them."));
+        }
+    }
 
     if (flags.gate) {
         const floor = flags.min ?? config.minScore ?? (previous ? previous.total : null);

package/lib/history.mjs

@@ -5,22 +5,24 @@ import { readJson } from "./fsx.mjs";
 
 export const DIR = ".adsa";
 
-export function historyPath(root) {
-    return join(root, DIR, "history.json");
+/** Takes the directory the run writes into, not the repository root: with --out
+ *  that is somewhere else entirely, and the history has to travel with the score. */
+export function historyPath(dir) {
+    return join(dir, "history.json");
 }
 
-export function readHistory(root) {
-    const json = readJson(historyPath(root));
+export function readHistory(dir) {
+    const json = readJson(historyPath(dir));
     return Array.isArray(json) ? json : [];
 }
 
 /** Appends a run, collapsing same-day reruns so the file does not grow per invocation. */
-export function appendHistory(root, entry) {
-    const history = readHistory(root);
+export function appendHistory(dir, entry) {
+    const history = readHistory(dir);
     const day = entry.date.slice(0, 10);
     const filtered = history.filter((h) => h.date.slice(0, 10) !== day);
     filtered.push(entry);
-    write(historyPath(root), filtered);
+    write(historyPath(dir), filtered);
     return filtered;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "adsa-cli",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "description": "Score a design system on how well coding agents can use it, then fix what is missing.",
     "type": "module",
     "bin": {