@ecoma-io/archkeep 0.14.0 → 0.15.0

package/src/report/snapshot-text.mjs

@@ -0,0 +1,123 @@
+/**
+ * Formatters two snapshot-transition reports share — `history-text.mjs` and
+ * `evolution-text.mjs` render the same transition shape (a graph diff, notes,
+ * and a short kind label), and a second copy of these helpers is where the
+ * two renders would drift: one day "code drift" means one thing in `history`
+ * and another in `evolution`, and no gate compares rendered prose.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * Neutralises control and terminal-escape sequences in a name or value before
+ * it is printed, so a crafted project/tag/edge name cannot inject escape
+ * sequences into a consumer's terminal (`SECURITY.md`). Real project names are
+ * ordinary characters and pass through untouched; only C0 control characters
+ * (which includes the ESC byte) and DEL become visible escapes.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanitize(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/[\x00-\x1F\x7F]/g, (c) => {
+    if (c === "\n") return "\\n";
+    if (c === "\t") return "\\t";
+    if (c === "\r") return "\\r";
+    return `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`;
+  });
+}
+
+/**
+ * One project as a line, same shape as `graph-text.mjs`.
+ *
+ * @param {{name: string, root: string, tags: string[]}} project
+ * @returns {string}
+ */
+export function formatProject(project) {
+  const tags =
+    project.tags.length > 0 ? ` [${project.tags.map((t) => sanitize(t)).join(", ")}]` : "";
+  return `  ${sanitize(project.name)}  ${sanitize(project.root)}${tags}`;
+}
+
+/**
+ * One edge as a line, same shape as `graph-text.mjs`.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+export function formatEdge(edge) {
+  return `  ${sanitize(edge.source)} → ${sanitize(edge.target)} (${sanitize(edge.type)})`;
+}
+
+/**
+ * One metadata change as a line, same shape as `diff-text.mjs`.
+ *
+ * @param {{field: string, baseline: *, head: *}} change
+ * @returns {string}
+ */
+export function formatChange(change) {
+  const formatValue = (v) => {
+    if (Array.isArray(v)) return v.length > 0 ? v.map((x) => sanitize(x)).join(", ") : "(none)";
+    if (v === null || v === undefined) return "(none)";
+    return sanitize(String(v));
+  };
+  return `  ${change.field}  ${formatValue(change.baseline)} → ${formatValue(change.head)}`;
+}
+
+/**
+ * How the architecture actually changed between two snapshots: the added and
+ * removed projects and edges rendered as one line each. Changed projects
+ * render their changed fields beneath the project line, like `diff`.
+ *
+ * @param {object} changes The `computeDiff` payload.
+ * @returns {string[]}
+ */
+export function formatChanges(changes) {
+  const lines = [];
+  if (changes.addedProjects.length > 0) {
+    const word = changes.addedProjects.length === 1 ? "project" : "projects";
+    lines.push(`+ ${changes.addedProjects.length} added ${word}`);
+    for (const project of changes.addedProjects) lines.push(formatProject(project));
+  }
+  if (changes.removedProjects.length > 0) {
+    const word = changes.removedProjects.length === 1 ? "project" : "projects";
+    lines.push(`- ${changes.removedProjects.length} removed ${word}`);
+    for (const project of changes.removedProjects) lines.push(formatProject(project));
+  }
+  if (changes.changedProjects.length > 0) {
+    const word = changes.changedProjects.length === 1 ? "project" : "projects";
+    lines.push(`~ ${changes.changedProjects.length} changed ${word}`);
+    for (const project of changes.changedProjects) {
+      lines.push(`  ${project.name}`);
+      for (const change of project.changes) lines.push(formatChange(change));
+    }
+  }
+  if (changes.addedEdges.length > 0) {
+    const word = changes.addedEdges.length === 1 ? "edge" : "edges";
+    lines.push(`+ ${changes.addedEdges.length} added ${word}`);
+    for (const edge of changes.addedEdges) lines.push(formatEdge(edge));
+  }
+  if (changes.removedEdges.length > 0) {
+    const word = changes.removedEdges.length === 1 ? "edge" : "edges";
+    lines.push(`- ${changes.removedEdges.length} removed ${word}`);
+    for (const edge of changes.removedEdges) lines.push(formatEdge(edge));
+  }
+  return lines;
+}
+
+/**
+ * Classifies one transition into the short "kind" a reader skims for.
+ *
+ * @param {{architectureChanged: boolean, codeDrift: boolean, policyChanged: boolean|null,
+ *   providerChanged: boolean}} transition
+ * @returns {string}
+ */
+export function transitionKind(transition) {
+  if (transition.architectureChanged) return "architecture";
+  if (transition.providerChanged) return "provider";
+  if (transition.policyChanged === true) return "policy";
+  if (transition.codeDrift) return "code drift";
+  return "unchanged";
+}

package/src/report/trajectory-text.mjs

@@ -0,0 +1,143 @@
+/**
+ * The terminal report for the `trajectory` command: the aggregate signals
+ * across a snapshot history, with what each number is a claim about.
+ *
+ * Every line states counts, never judgments — the report has no "better", no
+ * score, no direction adjective. The header names the observation basis (one
+ * observation is one stored graph snapshot, not a commit or a day), an
+ * insufficient history says so instead of printing zeros, and the disclosures
+ * line prints even when every count is zero, so a reader can tell "nothing
+ * was incomparable" from "the report forgot to say".
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * Neutralises control and terminal-escape sequences before anything reaches
+ * the terminal (`SECURITY.md`) — the same sanitation every other renderer
+ * applies. Only paths and snapshot filenames are printed here; project and
+ * edge identities stay aggregated precisely so nothing name-shaped needs to.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function sanitize(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/[\x00-\x1F\x7F]/g, (c) => {
+    if (c === "\n") return "\\n";
+    if (c === "\t") return "\\t";
+    if (c === "\r") return "\\r";
+    return `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`;
+  });
+}
+
+/**
+ * A delta with its sign, so +2 / -1 / 0 read as movement rather as bare
+ * magnitudes. Zero prints unsigned — it is the absence of movement, not a
+ * positive one.
+ *
+ * @param {number|null} value
+ * @returns {string}
+ */
+function signed(value) {
+  if (value === null) return "n/a";
+  if (value > 0) return `+${value}`;
+  return `${value}`;
+}
+
+/**
+ * A count that is either established or explicitly unavailable. `null`
+ * renders as `n/a` beside the reason the header already stated — never as a
+ * zero that would claim a measurement.
+ *
+ * @param {number|null} value
+ * @returns {string}
+ */
+function counted(value) {
+  return value === null ? "n/a" : `${value}`;
+}
+
+/**
+ * One structural axis as one line: endpoints, then events, then persistence.
+ *
+ * @param {{first: number, current: number, delta: number|null,
+ *   addedEvents: number|null, removedEvents: number|null,
+ *   changedEvents: number|null, introduced: number|null, resolved: number|null,
+ *   persistent: number|null}} axis
+ * @param {boolean} withChanged Whether the axis carries a changed-event count
+ *   (projects do; edges do not — a type flip is remove+add under the triple
+ *   identity).
+ * @returns {string}
+ */
+function formatAxis(axis, withChanged) {
+  const parts = [
+    `first ${axis.first}`,
+    `current ${axis.current}`,
+    `delta ${signed(axis.delta)}`,
+    `added ${counted(axis.addedEvents)}`,
+    `removed ${counted(axis.removedEvents)}`,
+  ];
+  if (withChanged) parts.push(`changed ${counted(axis.changedEvents)}`);
+  parts.push(
+    `introduced ${counted(axis.introduced)}`,
+    `resolved ${counted(axis.resolved)}`,
+    `persistent ${counted(axis.persistent)}`,
+  );
+  return parts.join(" · ");
+}
+
+/**
+ * The whole trajectory report.
+ *
+ * @param {{trajectory: {dir: string, observations: {count: number, basis: string,
+ *   first: string|null, last: string|null, withProvenance: number,
+ *   dirtyProvenance: number}, available: boolean, unavailableReason: string|null,
+ *   transitions: {count: number, architecture: number, policy: number,
+ *     provider: number, codeDrift: number, incomparable: number, unchanged: number},
+ *   disclosures: {policyOneSided: number, provenanceOneSided: number, crossRepo: number},
+ *   projects: object, edges: object}, coverage: object}} input
+ * @returns {string}
+ */
+export function formatTrajectoryReport({ trajectory, coverage }) {
+  const sections = [];
+
+  const observations = trajectory.observations;
+  sections.push(`trajectory  ${trajectory.dir}`);
+  sections.push(
+    `${observations.count} observation${observations.count === 1 ? "" : "s"} ` +
+      `(${observations.basis}), ${trajectory.transitions.count} transition${
+        trajectory.transitions.count === 1 ? "" : "s"
+      }`,
+  );
+
+  if (!trajectory.available) {
+    // Named, not implied: a one-snapshot history cannot show movement, and
+    // every derived number below stays n/a rather than reading as a zero.
+    sections.push(
+      `✖ ${trajectory.unavailableReason}: a trajectory needs at least two observations — ` +
+        "derived values are unavailable, not zero",
+    );
+  }
+
+  const t = trajectory.transitions;
+  sections.push(
+    `signals  architecture ${t.architecture} · policy ${t.policy} · provider ${t.provider} · ` +
+      `code drift ${t.codeDrift} · incomparable ${t.incomparable} · unchanged ${t.unchanged}`,
+  );
+  sections.push(`projects  ${formatAxis(trajectory.projects, true)}`);
+  sections.push(`edges     ${formatAxis(trajectory.edges, false)}`);
+
+  const d = trajectory.disclosures;
+  sections.push(
+    `disclosures  policy incomparable ${d.policyOneSided} · provenance incomparable ` +
+      `${d.provenanceOneSided} · cross-repo ${d.crossRepo} · ` +
+      `dirty captures ${observations.dirtyProvenance} · with provenance ${observations.withProvenance}`,
+  );
+
+  for (const note of coverage.notes) {
+    sections.push(sanitize(note));
+  }
+
+  return sections.join("\n");
+}

package/src/tsconfig-paths.mjs

@@ -77,6 +77,7 @@
  * says (`tsconfigPathsFacts` there).
  */
 import { posix } from "node:path";
+import { stripTrailingSlashes } from "./path-util.mjs";
 
 /**
  * What a hygiene finding means — one entry per `messageId`, the arrangement
@@ -116,7 +117,7 @@ function probeDirectory(target, base, root) {
   // candidates live in its parent.
   const dir =
     prefix === "" || prefix.endsWith("/")
-      ? joined.replace(/\/+$/u, "") || "/"
+      ? stripTrailingSlashes(joined) || "/"
       : posix.dirname(joined);
   if (dir === root) return "";
   return dir.startsWith(`${root}/`) ? dir.slice(root.length + 1) : null;
@@ -144,7 +145,7 @@ function probeDirectory(target, base, root) {
  *   verdict; `malformed` is for `../cli.mjs` to refuse loudly, never to skip.
  */
 export function judgeTsconfigPaths({ paths, base, workspaceRoot, tsConfig, directoryExists }) {
-  const root = workspaceRoot.replace(/\/+$/u, "");
+  const root = stripTrailingSlashes(workspaceRoot);
   const findings = [];
   const malformed = [];
   let aliases = 0;