@intentius/chant 0.124.28 → 0.124.29

package/src/workspace/declaration.schema.json

@@ -179,6 +179,58 @@
           "$ref": "#/$defs/ciGreen"
         }
       }
+    },
+    "retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": true
+      },
+      "description": "How long chant lifecycle gc keeps each kind of stored record (#4036). A kind or field left out keeps its default: changeSets 14 days; releases 14 days and the newest 10 of each member; runEvents 14 days and the newest 100. Whatever the policy, gc never prunes a release an environment runs, what a pending gate binds, or a change set a gate names with a kept release. Read from the declaration at base. Added in schema 1 by chant 0.124.29, so a declaration that uses it sets minReader to 0.124.29 or newer.",
+      "properties": {
+        "changeSets": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Stored change sets, _change-sets/<digest>.json on chant/lifecycle.",
+          "properties": {
+            "days": { "$ref": "#/$defs/retentionDays" }
+          }
+        },
+        "releases": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Releases, _releases/<digest>.json on chant/lifecycle, with the template bytes only they name. A release stays promotable for days after its newest cut, and the newest keep releases of each member stay promotable at any age, unless their commit is revoked.",
+          "properties": {
+            "days": { "$ref": "#/$defs/retentionDays" },
+            "keep": { "$ref": "#/$defs/retentionKeep" }
+          }
+        },
+        "runEvents": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Run event files, <git-common-dir>/chant/run-events/<run>.jsonl on each host. A file is kept for days after its last write, and the newest keep files at any age.",
+          "properties": {
+            "days": { "$ref": "#/$defs/retentionDays" },
+            "keep": { "$ref": "#/$defs/retentionKeep" }
+          }
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": true
+      },
+      "description": "How chant workspace metrics counts the DORA metrics (#4039). Added in schema 1 by chant 0.124.29, so a declaration that uses it sets minReader to 0.124.29 or newer.",
+      "properties": {
+        "failureWindowDays": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 365,
+          "description": "A deploy counts as failed when, within this many days after it, the commit it deployed is revoked or the environment is rolled back from it. The default is 7."
+        }
+      }
     }
   },
   "patternProperties": {
@@ -186,6 +238,18 @@
   },
   "additionalProperties": false,
   "$defs": {
+    "retentionDays": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 36500,
+      "description": "Days a record is kept past its last write or use. 0 lets every record go that no never-prune rule keeps."
+    },
+    "retentionKeep": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100000,
+      "description": "How many of the newest are kept at any age."
+    },
     "name": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",

package/src/workspace/declaration.test.ts

@@ -421,3 +421,31 @@ describe("diagram artifacts (#2764)", () => {
     expect(failure(base([member([diagram({ render: "../out.svg" })])])).code).toBe("declaration-invalid");
   });
 });
+
+describe("retention (#4036)", () => {
+  test("the block is read as written, without x- keys, and is null when absent", () => {
+    expect(parse(base([])).retention).toBeNull();
+    const d = parse(base([], { minReader: "0.80.0", retention: { changeSets: { days: 30 }, releases: { keep: 3 }, runEvents: { days: 2, keep: 5 }, "x-why": "audits" } }));
+    expect(d.retention).toEqual({ changeSets: { days: 30 }, releases: { keep: 3 }, runEvents: { days: 2, keep: 5 } });
+  });
+
+  test("an unknown kind or field, a negative or fractional number, and keep on changeSets are refused", () => {
+    for (const retention of [{ plans: { days: 1 } }, { releases: { days: -1 } }, { releases: { days: 1.5 } }, { changeSets: { keep: 2 } }, { runEvents: { hours: 2 } }]) {
+      expect(failure(base([], { retention })).code).toBe("declaration-invalid");
+    }
+  });
+});
+
+describe("metrics (#4039)", () => {
+  test("failureWindowDays is read as written, without x- keys, and the block is null when absent", () => {
+    expect(parse(base([])).metrics).toBeNull();
+    expect(parse(base([], { minReader: "0.80.0", metrics: { failureWindowDays: 14, "x-why": "weekly" } })).metrics).toEqual({ failureWindowDays: 14 });
+    expect(parse(base([], { metrics: {} })).metrics).toEqual({});
+  });
+
+  test("an unknown field, 0, a fraction and more than a year are refused", () => {
+    for (const metrics of [{ window: 7 }, { failureWindowDays: 0 }, { failureWindowDays: 1.5 }, { failureWindowDays: 366 }]) {
+      expect(failure(base([], { metrics })).code).toBe("declaration-invalid");
+    }
+  });
+});

package/src/workspace/declaration.ts

@@ -16,6 +16,7 @@
  * runs. The level-0 goldens (#2526) fail if a level-0 command loads it.
  */
 
+import { RETENTION_KINDS, type RetentionOverride } from "../lifecycle/retention-policy";
 import schema from "./declaration.schema.json" with { type: "json" };
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
@@ -601,6 +602,19 @@ export interface Declaration {
   identity: IdentityPolicy | null;
   /** What the workspace's CI decides about its commits (#3573), or null when the declaration has no `ci` block. */
   ci: CiDeclaration | null;
+  /**
+   * The `retention` block as written (#4036): the kinds and fields it sets,
+   * which `resolveRetention` (../lifecycle/retention-policy.ts) lays over the
+   * defaults. Null when the declaration has no `retention` block.
+   */
+  retention: RetentionOverride | null;
+  /**
+   * The `metrics` block (#4039): `failureWindowDays`, the days after a deploy
+   * in which a revocation or a rollback counts it as failed, when set. Null
+   * when the declaration has no `metrics` block; `chant workspace metrics`
+   * then uses 7.
+   */
+  metrics: { failureWindowDays?: number } | null;
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -977,6 +991,8 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     agents,
     identity: identityOf(obj.identity),
     ci,
+    retention: retentionOf(obj.retention),
+    metrics: metricsOf(obj.metrics),
     file,
   };
   written.set(declaration, raw);
@@ -1047,6 +1063,28 @@ function identityOf(raw: unknown): IdentityPolicy | null {
  * The `ci` block, already validated by the schema, with its defaults and the
  * rule the schema can't say (#3573): every phase `require` names is declared.
  */
+/** The `metrics` block, already validated by the schema, without its `x-` keys (#4039). */
+function metricsOf(raw: unknown): { failureWindowDays?: number } | null {
+  if (!raw || typeof raw !== "object") return null;
+  const days = (raw as { failureWindowDays?: unknown }).failureWindowDays;
+  return typeof days === "number" ? { failureWindowDays: days } : {};
+}
+
+/** The `retention` block, already validated by the schema, without its `x-` keys (#4036). */
+function retentionOf(raw: unknown): RetentionOverride | null {
+  if (!raw || typeof raw !== "object") return null;
+  const out: RetentionOverride = {};
+  for (const kind of RETENTION_KINDS) {
+    const k = (raw as Record<string, Record<string, unknown> | undefined>)[kind];
+    if (!k) continue;
+    out[kind] = {
+      ...(typeof k.days === "number" ? { days: k.days } : {}),
+      ...(typeof k.keep === "number" ? { keep: k.keep } : {}),
+    };
+  }
+  return out;
+}
+
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
   const block = raw as { green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped }>; require: string[]; signedSince?: string; source?: CiSource } };

package/src/workspace/declared-kinds.ts

@@ -43,6 +43,22 @@ export interface DeclaredKind {
    * and when its records can't be read (`records` reports why).
    */
   acceptance?: DeclaredAcceptance[];
+  /**
+   * For a flag kind (#4024), read with `flags: true`: each current flag
+   * record, with its `flag-stale` warning when it is due for removal. Absent
+   * for any other kind, when the kind wasn't loaded, and when its records
+   * can't be read (`records` reports why).
+   */
+  flags?: DeclaredFlag[];
+}
+
+/** One flag record, as `check` reads it for WSP118 (#4024). */
+export interface DeclaredFlag {
+  flag: string;
+  /** The record file on disk, absolute. */
+  file: string;
+  /** The record's `flag-stale` warning, when the flag is due for removal; null otherwise. */
+  stale: string | null;
 }
 
 /** One work record's acceptance criteria, counted, as `ls`, `status` and `check` read them (#2772). */
@@ -72,7 +88,7 @@ export async function loadDeclaredKinds(
   declaration: Declaration,
   tree: WorkspaceTree,
   rootOnDisk: string,
-  options: { load?: boolean; acceptance?: boolean; at?: string } = {},
+  options: { load?: boolean; acceptance?: boolean; flags?: boolean; at?: string } = {},
 ): Promise<DeclaredKind[]> {
   const declared = declaredRecordKinds(declaration);
   if (declared.length === 0) return [];
@@ -96,6 +112,10 @@ export async function loadDeclaredKinds(
         const counted = await countAcceptance(file, rootOnDisk, options.at);
         if (counted) entry.acceptance = counted;
       }
+      if (loaded.kind.flag && options.flags) {
+        const flags = await readFlags(file, rootOnDisk, options.at);
+        if (flags) entry.flags = flags;
+      }
       out.push(entry);
     } catch (err) {
       if (!(err instanceof records.RecordReadError)) throw err;
@@ -128,6 +148,25 @@ async function countAcceptance(file: string, rootOnDisk: string, at: string | un
   }
 }
 
+/** A flag kind's current records with their stale warnings (#4024), or undefined when they can't be read. */
+async function readFlags(file: string, rootOnDisk: string, at: string | undefined): Promise<DeclaredFlag[] | undefined> {
+  const { readRecordsFor } = await import("./records-cli");
+  const { RecordReadError } = await import("./records");
+  try {
+    const read = await readRecordsFor({ kind: file, cwd: rootOnDisk, current: true, ...(at !== undefined ? { at } : {}) });
+    return read.result.records
+      .filter((r): r is typeof r & { id: string } => r.id !== null)
+      .map((r) => ({
+        flag: r.id,
+        file: join(read.root, ...r.path.split("/")),
+        stale: r.warnings.find((w) => w.code === "flag-stale")?.message ?? null,
+      }));
+  } catch (err) {
+    if (err instanceof RecordReadError) return undefined;
+    throw err;
+  }
+}
+
 /** An answer kind's points file (ws-058), read from `tree` and validated as `points ask` reads it. */
 async function checkPoints(abs: string, rootOnDisk: string, tree: WorkspaceTree): Promise<NonNullable<DeclaredKind["points"]>> {
   const file = relative(rootOnDisk, abs).split(sep).join("/");