@intentius/chant 0.124.46 → 0.124.48

package/src/workspace/dbt-project-common.ts

@@ -0,0 +1,113 @@
+/**
+ * What the dbt readers share (#3932, #3935): YAML and line helpers, the
+ * `quoting:` rules, and the project's `model-paths`.
+ */
+
+import { posix } from "node:path";
+import type { KindReadGap } from "./kind-link-readers";
+import { joinPath, skippedDir, type WorkspaceTree } from "./tree";
+
+export const DBT_PROJECT_FILE = "dbt_project.yml";
+export const DEFAULT_MODEL_PATHS = ["models"];
+
+/** The dialects whose naming the reader follows; the member's `dialect` field picks one. */
+export const DBT_DIALECTS = ["postgres", "clickhouse"] as const;
+export type Dialect = (typeof DBT_DIALECTS)[number];
+
+export interface Quoting {
+  schema: boolean;
+  identifier: boolean;
+}
+
+export const isTemplated = (v: string) => /\{\{|\{%/.test(v);
+export const isObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** A name as text: a string, or a number or boolean YAML read as one. */
+export function scalar(v: unknown): string | undefined {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return undefined;
+}
+
+/** Whether an entry is enabled: `enabled`, or `config.enabled`. A templated value is a gap, and the entry is left out. */
+export function readEnabled(entry: Record<string, unknown>, file: string, line: number, where: string, gaps: KindReadGap[]): boolean {
+  const config = isObject(entry.config) ? entry.config : {};
+  const raw = entry.enabled ?? config.enabled;
+  if (raw === undefined || raw === null || raw === true) return true;
+  if (raw === false) return false;
+  gaps.push({ file, line, message: `${where}: enabled is ${JSON.stringify(raw)}, which chant does not render; it was not read` });
+  return false;
+}
+
+/** `base` with a `quoting:` block's schema and identifier applied. A value that isn't a boolean is a gap and keeps the base. */
+export function readQuoting(base: Quoting, raw: unknown, file: string, line: number, where: string, gaps: KindReadGap[]): Quoting {
+  if (raw === undefined || raw === null) return base;
+  if (!isObject(raw)) {
+    gaps.push({ file, line, message: `${where} is not a mapping; the quoting above it applies` });
+    return base;
+  }
+  const out = { ...base };
+  for (const key of ["schema", "identifier"] as const) {
+    const v = raw[key];
+    if (v === undefined) continue;
+    if (typeof v === "boolean") out[key] = v;
+    else gaps.push({ file, line, message: `${where}.${key} is ${JSON.stringify(v)}, not true or false; the quoting above it applies` });
+  }
+  return out;
+}
+
+/** Every `.yml` and `.yaml` file under tree-relative directory `dir`, skipping dot directories and node_modules. */
+export function yamlFiles(tree: WorkspaceTree, dir: string): string[] {
+  if (dir !== "" && tree.stat(dir) !== "dir") return [];
+  const out: string[] = [];
+  const walk = (at: string) => {
+    for (const e of tree.list(at) ?? []) {
+      const path = joinPath(at, e.name);
+      if (e.type === "dir") {
+        if (!skippedDir(e.name)) walk(path);
+      } else if (/\.ya?ml$/.test(e.name)) {
+        out.push(path);
+      }
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+export function lines(text: string): string[] {
+  return text.replace(/\r\n/g, "\n").split("\n");
+}
+
+export function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** The line (from 1) of top-level key `key`, or 1. */
+export function keyLine(fileLines: string[], key: string): number {
+  const re = new RegExp(`^${escapeRegExp(key)}\\s*:`);
+  const i = fileLines.findIndex((l) => re.test(l));
+  return i < 0 ? 1 : i + 1;
+}
+
+/**
+ * The line of the first `name: <value>` entry after line `from`, or `from`
+ * itself. Sources, tables and columns are listed in file order, so
+ * searching on from the parent's line finds each one's own line. A file in
+ * flow style has no such lines, and its entries are reported at the parent.
+ */
+export function nameLine(fileLines: string[], value: string | undefined, from: number): number {
+  return value === undefined ? from : valueLineOf(fileLines, "name", value, from);
+}
+
+/** The line of the first `<key>:` after line `from`, or `from`. */
+export function valueLine(fileLines: string[], key: string, from: number): number {
+  const re = new RegExp(`^\\s*(?:-\\s+)?${escapeRegExp(key)}\\s*:`);
+  for (let i = Math.max(from, 0); i < fileLines.length; i++) if (re.test(fileLines[i])) return i + 1;
+  return from;
+}
+
+export function valueLineOf(fileLines: string[], key: string, value: string, from: number): number {
+  const re = new RegExp(`^\\s*(?:-\\s+)?${escapeRegExp(key)}\\s*:\\s*(["']?)${escapeRegExp(value)}\\1\\s*(?:#.*)?$`);
+  for (let i = Math.max(from, 0); i < fileLines.length; i++) if (re.test(fileLines[i])) return i + 1;
+  return from;
+}

package/src/workspace/dbt-project-reader.ts

@@ -27,27 +27,33 @@
  * - The producer is the member the `sqlMember` field names. Unset, each link
  *   leaves the producer to `resolveLinks`, which picks the one member that
  *   exposes the table.
+ *
+ * The same pass reads the project's models as outputs (#3935); see
+ * `./dbt-models-reader.ts`.
  */
 
 import { posix } from "node:path";
 import { parseYAMLDocument, YAMLParseError } from "../yaml";
 import type { KindLinkRead, KindReadGap, KindReadLink, KindReaderInput } from "./kind-link-readers";
-import { joinPath, skippedDir, type WorkspaceTree } from "./tree";
-
-export const DBT_PROJECT_FILE = "dbt_project.yml";
-const DEFAULT_MODEL_PATHS = ["models"];
-
-/** The dialects whose naming the reader follows; the member's `dialect` field picks one. */
-export const DBT_DIALECTS = ["postgres", "clickhouse"] as const;
-type Dialect = (typeof DBT_DIALECTS)[number];
-
-interface Quoting {
-  schema: boolean;
-  identifier: boolean;
-}
-
-const isTemplated = (v: string) => /\{\{|\{%/.test(v);
-const isObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+import { joinPath } from "./tree";
+import { readDbtModels } from "./dbt-models-reader";
+import {
+  DBT_PROJECT_FILE,
+  DEFAULT_MODEL_PATHS,
+  isObject,
+  isTemplated,
+  keyLine,
+  lines,
+  nameLine,
+  readEnabled,
+  readQuoting,
+  scalar,
+  valueLine,
+  yamlFiles,
+  type Dialect,
+} from "./dbt-project-common";
+
+export { DBT_DIALECTS, DBT_PROJECT_FILE } from "./dbt-project-common";
 
 export function readDbtProject(input: KindReaderInput): KindLinkRead {
   const { dir, tree, fields } = input;
@@ -63,11 +69,11 @@ export function readDbtProject(input: KindReaderInput): KindLinkRead {
   try {
     project = parseYAMLDocument(tree.read(projectFile));
   } catch (err) {
-    gaps.push({ file: projectFile, line: err instanceof YAMLParseError ? err.line : 1, message: `${DBT_PROJECT_FILE} could not be read (${(err as Error).message}), so no source was read` });
+    gaps.push({ file: projectFile, line: err instanceof YAMLParseError ? err.line : 1, message: `${DBT_PROJECT_FILE} could not be read (${(err as Error).message}), so no source was read`, outputs: true });
     return result;
   }
   if (!isObject(project)) {
-    gaps.push({ file: projectFile, line: 1, message: `${DBT_PROJECT_FILE} is not a mapping, so no source was read` });
+    gaps.push({ file: projectFile, line: 1, message: `${DBT_PROJECT_FILE} is not a mapping, so no source was read`, outputs: true });
     return result;
   }
   const projectLines = lines(tree.read(projectFile));
@@ -77,17 +83,17 @@ export function readDbtProject(input: KindReaderInput): KindLinkRead {
   const rawPaths = key ? project[key] : DEFAULT_MODEL_PATHS;
   const paths: string[] = [];
   if (!Array.isArray(rawPaths)) {
-    gaps.push({ file: projectFile, line: keyLine(projectLines, key ?? ""), message: `${key} is not a list, so no source was read` });
+    gaps.push({ file: projectFile, line: keyLine(projectLines, key ?? ""), message: `${key} is not a list, so no source was read`, outputs: true });
     return result;
   }
   for (const p of rawPaths) {
     if (typeof p !== "string" || isTemplated(p)) {
-      gaps.push({ file: projectFile, line: keyLine(projectLines, key ?? ""), message: `${key} entry ${JSON.stringify(p)} is not a plain path; its sources were not read` });
+      gaps.push({ file: projectFile, line: keyLine(projectLines, key ?? ""), message: `${key} entry ${JSON.stringify(p)} is not a plain path; its sources were not read`, outputs: true });
       continue;
     }
     const at = posix.normalize(joinPath(dir, p));
     if (at.startsWith("../") || at === ".." || posix.isAbsolute(p)) {
-      gaps.push({ file: projectFile, line: keyLine(projectLines, key ?? ""), message: `${key} entry ${p} lies outside the workspace; its sources were not read` });
+      gaps.push({ file: projectFile, line: keyLine(projectLines, key ?? ""), message: `${key} entry ${p} lies outside the workspace; its sources were not read`, outputs: true });
       continue;
     }
     paths.push(at === "." ? "" : at);
@@ -106,7 +112,7 @@ export function readDbtProject(input: KindReaderInput): KindLinkRead {
       text = tree.read(file);
       doc = parseYAMLDocument(text);
     } catch (err) {
-      gaps.push({ file, line: err instanceof YAMLParseError ? err.line : 1, message: `the file could not be read as YAML (${(err as Error).message}); any sources in it were not read` });
+      gaps.push({ file, line: err instanceof YAMLParseError ? err.line : 1, message: `the file could not be read as YAML (${(err as Error).message}); any sources or models in it were not read`, outputs: true });
       continue;
     }
     if (!isObject(doc) || doc.sources === undefined || doc.sources === null) continue;
@@ -197,95 +203,6 @@ export function readDbtProject(input: KindReaderInput): KindLinkRead {
       }
     }
   }
+  readDbtModels({ input, project, projectFile, paths, quoting, dialect, result });
   return result;
 }
-
-/** A name as text: a string, or a number or boolean YAML read as one. */
-function scalar(v: unknown): string | undefined {
-  if (typeof v === "string") return v;
-  if (typeof v === "number" || typeof v === "boolean") return String(v);
-  return undefined;
-}
-
-/** Whether an entry is enabled: `enabled`, or `config.enabled`. A templated value is a gap, and the entry is left out. */
-function readEnabled(entry: Record<string, unknown>, file: string, line: number, where: string, gaps: KindReadGap[]): boolean {
-  const config = isObject(entry.config) ? entry.config : {};
-  const raw = entry.enabled ?? config.enabled;
-  if (raw === undefined || raw === null || raw === true) return true;
-  if (raw === false) return false;
-  gaps.push({ file, line, message: `${where}: enabled is ${JSON.stringify(raw)}, which chant does not render; it was not read` });
-  return false;
-}
-
-/** `base` with a `quoting:` block's schema and identifier applied. A value that isn't a boolean is a gap and keeps the base. */
-function readQuoting(base: Quoting, raw: unknown, file: string, line: number, where: string, gaps: KindReadGap[]): Quoting {
-  if (raw === undefined || raw === null) return base;
-  if (!isObject(raw)) {
-    gaps.push({ file, line, message: `${where} is not a mapping; the quoting above it applies` });
-    return base;
-  }
-  const out = { ...base };
-  for (const key of ["schema", "identifier"] as const) {
-    const v = raw[key];
-    if (v === undefined) continue;
-    if (typeof v === "boolean") out[key] = v;
-    else gaps.push({ file, line, message: `${where}.${key} is ${JSON.stringify(v)}, not true or false; the quoting above it applies` });
-  }
-  return out;
-}
-
-/** Every `.yml` and `.yaml` file under tree-relative directory `dir`, skipping dot directories and node_modules. */
-function yamlFiles(tree: WorkspaceTree, dir: string): string[] {
-  if (dir !== "" && tree.stat(dir) !== "dir") return [];
-  const out: string[] = [];
-  const walk = (at: string) => {
-    for (const e of tree.list(at) ?? []) {
-      const path = joinPath(at, e.name);
-      if (e.type === "dir") {
-        if (!skippedDir(e.name)) walk(path);
-      } else if (/\.ya?ml$/.test(e.name)) {
-        out.push(path);
-      }
-    }
-  };
-  walk(dir);
-  return out;
-}
-
-function lines(text: string): string[] {
-  return text.replace(/\r\n/g, "\n").split("\n");
-}
-
-function escapeRegExp(text: string): string {
-  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/** The line (from 1) of top-level key `key`, or 1. */
-function keyLine(fileLines: string[], key: string): number {
-  const re = new RegExp(`^${escapeRegExp(key)}\\s*:`);
-  const i = fileLines.findIndex((l) => re.test(l));
-  return i < 0 ? 1 : i + 1;
-}
-
-/**
- * The line of the first `name: <value>` entry after line `from`, or `from`
- * itself. Sources, tables and columns are listed in file order, so
- * searching on from the parent's line finds each one's own line. A file in
- * flow style has no such lines, and its entries are reported at the parent.
- */
-function nameLine(fileLines: string[], value: string | undefined, from: number): number {
-  return value === undefined ? from : valueLineOf(fileLines, "name", value, from);
-}
-
-/** The line of the first `<key>:` after line `from`, or `from`. */
-function valueLine(fileLines: string[], key: string, from: number): number {
-  const re = new RegExp(`^\\s*(?:-\\s+)?${escapeRegExp(key)}\\s*:`);
-  for (let i = Math.max(from, 0); i < fileLines.length; i++) if (re.test(fileLines[i])) return i + 1;
-  return from;
-}
-
-function valueLineOf(fileLines: string[], key: string, value: string, from: number): number {
-  const re = new RegExp(`^\\s*(?:-\\s+)?${escapeRegExp(key)}\\s*:\\s*(["']?)${escapeRegExp(value)}\\1\\s*(?:#.*)?$`);
-  for (let i = Math.max(from, 0); i < fileLines.length; i++) if (re.test(fileLines[i])) return i + 1;
-  return from;
-}

package/src/workspace/decision-rank.ts

@@ -0,0 +1,40 @@
+/**
+ * How decisions are ranked, most relevant first: the order of `why.decisions`
+ * in the intent graph (#3034) and of a gate's `decisions` in `workspace
+ * status` (#3616). One comparator, so the two reads can't drift apart.
+ */
+
+/** Why a decision is in `why`, most relevant first (#3034). */
+export type WhyRelevance = "carried" | "path" | "contract" | "issue" | "member" | "related";
+
+const ORDER: readonly WhyRelevance[] = ["carried", "path", "contract", "issue", "member", "related"];
+
+/** What the ranking reads of one decision. */
+export interface DecisionRankKey {
+  /** The decision's node id, `record:<kind>/<id>`: the last tie-break. */
+  id: string;
+  /** Not superseded. */
+  current: boolean;
+  relevance: WhyRelevance;
+  /** How many of the region's current lines were made as its own work; 0 when history isn't read. */
+  lines: number;
+  /** Its state is one its kind closes. */
+  closed: boolean;
+  /** The length of its longest `path:` entry covering the region: a narrower path is more specific. */
+  specificity: number;
+  /** The date of the commit that decided it, or null. */
+  decidedOn: string | null;
+}
+
+/** Current first, then relevance, own lines, closed, specificity, newest decided, and id. */
+export function compareDecisionRank(a: DecisionRankKey, b: DecisionRankKey): number {
+  return (
+    Number(b.current) - Number(a.current) ||
+    ORDER.indexOf(a.relevance) - ORDER.indexOf(b.relevance) ||
+    b.lines - a.lines ||
+    Number(b.closed) - Number(a.closed) ||
+    b.specificity - a.specificity ||
+    (b.decidedOn ?? "").localeCompare(a.decidedOn ?? "") ||
+    a.id.localeCompare(b.id)
+  );
+}

package/src/workspace/declaration.schema.json

@@ -30,6 +30,13 @@
       "$ref": "#/$defs/version",
       "description": "The oldest chant that may read this declaration. An older chant refuses it with reader-too-old."
     },
+    "scope": {
+      "enum": [
+        "repo",
+        "org"
+      ],
+      "description": "What the workspace spans (#3168). repo, the default, is one repository's workspace. org is an org-level workspace: it holds only members of kind repo, each a reference to another repository's workspace, and chant workspace check fails any other member (WSP013). A warden generates an org workspace from its policy, or checks one against the forge's repository list with chant workspace check --forge-repos. Added in schema 1 by chant 0.124.47, so a declaration that uses it sets minReader to 0.124.47 or newer."
+    },
     "members": {
       "type": "array",
       "description": "Members and example groups, in the order readers list them.",
@@ -161,6 +168,13 @@
               "class": {
                 "$ref": "#/$defs/className",
                 "description": "The principal class the signer must be in, read from the role grants at base (#3080, ws-079): human, runner, service, or a domain class a pinned package supplies. A class no pinned package supplies lets no approval through (fail closed). Absent: any signer the signers file lists."
+              },
+              "quorum": {
+                "description": "The approval rules an Op gate of this name takes (#4324), in place of the Op's own approval.quorum: one rule or a list, each with count, and optionally targets globs over the run's environment and roles from .chant/trust.json at base. Read at base, so a change can't lower the quorum its own run needs. notAuthor is refused: an Op gate has no pull request to read the author from. Added in schema 1 by chant 0.124.47, so a declaration that uses it sets minReader to 0.124.47 or newer.",
+                "oneOf": [
+                  { "$ref": "#/$defs/gateQuorumRule" },
+                  { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/gateQuorumRule" } }
+                ]
               }
             }
           }
@@ -446,6 +460,18 @@
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]{0,39}$"
     },
+    "gateQuorumRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["count"],
+      "description": "One approval rule (#4290): count distinct human approvers, from roles when it names them.",
+      "properties": {
+        "targets": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Globs over the run's environment: * within one / segment, ** across segments, ? one character. Absent: every run. A rule with targets never covers a run with no environment." },
+        "count": { "type": "integer", "minimum": 1, "description": "Distinct human approvers the rule needs." },
+        "roles": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Only an approver .chant/trust.json at base gives one of these roles counts, and only with an approval sealed by a signer listed at base." },
+        "notAuthor": { "type": "boolean", "description": "Refused on an Op gate, which has no author to judge by." }
+      }
+    },
     "className": {
       "type": "string",
       "pattern": "^(?!x-)[a-z][a-z0-9-]{0,39}$",
@@ -573,7 +599,6 @@
       "description": "A member (#2524 D2). Its directory leaves the root project, and it gets its own build, lint and ledger.",
       "required": [
         "name",
-        "dir",
         "kind"
       ],
       "properties": {
@@ -586,7 +611,10 @@
         },
         "kind": {
           "$ref": "#/$defs/kindName",
-          "description": "How to read the member: chant, workspace, other, or a kind a pinned plugin supplies (#2535)."
+          "description": "How to read the member: chant, workspace, repo, other, or a kind a pinned plugin supplies (#2535). Every kind but repo needs dir; a repo member has repo instead (#3168)."
+        },
+        "repo": {
+          "$ref": "#/$defs/repoRef"
         },
         "roles": {
           "type": "array",
@@ -685,6 +713,10 @@
           "type": "boolean",
           "description": "Whether the member goes with an export (#2524 D10, #2552). chant workspace export writes only members that set travel to true into the export member, and refuses to name one that does not. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer."
         },
+        "acceptWorkspaceGates": {
+          "type": "boolean",
+          "description": "Whether an approval of a workspace gate may stand in for this member's own gates (#2554, ws-039). It does only when the approval's digest covers the plan the member's run reached its gate with, and only when the declaration at base sets this to true; a working-tree change never opts a member in. Absent or false, a workspace gate never satisfies this member's gates. Added in schema 1 by chant 0.124.47, so a declaration that uses it sets minReader to 0.124.47 or newer."
+        },
         "security": {
           "type": "array",
           "uniqueItems": true,
@@ -706,28 +738,91 @@
         "^x-": true
       },
       "additionalProperties": false,
-      "if": {
-        "type": "object",
-        "properties": {
-          "kind": {
-            "const": "other"
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "other"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "type": "object",
+            "properties": {
+              "because": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "because"
+            ]
           }
         },
-        "required": [
-          "kind"
-        ]
-      },
-      "then": {
-        "type": "object",
-        "properties": {
-          "because": {
-            "type": "string"
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "repo"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "repo"
+            ],
+            "properties": {
+              "repo": true,
+              "dir": false
+            }
+          },
+          "else": {
+            "required": [
+              "dir"
+            ],
+            "properties": {
+              "dir": true,
+              "repo": false
+            }
           }
+        }
+      ]
+    },
+    "repoRef": {
+      "type": "object",
+      "description": "Another repository's workspace, named by URL and pinned revision (#3168). A member of kind repo carries it and has no dir. chant reads that workspace read-only through the other repository's own read contract, its chant workspace graph at the revision, the way it reads a nested workspace member, and never writes there. Added in schema 1 by chant 0.124.47, so a declaration that uses it sets minReader to 0.124.47 or newer.",
+      "required": [
+        "url",
+        "rev"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "pattern": "^[^\\s]+$",
+          "description": "Where git fetches the repository from: an https, ssh or file URL, a local path, or an scp-style git@host:org/repo. A URL that carries a password or token is refused when it is read."
         },
-        "required": [
-          "because"
-        ]
-      }
+        "rev": {
+          "type": "string",
+          "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$",
+          "description": "The pinned revision, a full commit id. A branch or tag is not a pin."
+        },
+        "workspace": {
+          "$ref": "#/$defs/dir",
+          "description": "The workspace root inside that repository, relative to its git root. Defaults to \".\"."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
     },
     "memberFields": {
       "type": "object",
@@ -1696,10 +1791,24 @@
       ],
       "properties": {
         "branch": {
-          "type": "string",
-          "minLength": 1,
-          "pattern": "^[^\\s~^:?*\\[\\\\]+$",
-          "description": "The branch whose commits are tagged, such as main. Only its first-parent commits count."
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^[^\\s~^:?*\\[\\\\]+$"
+            },
+            {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[^\\s~^:?*\\[\\\\]+$"
+              }
+            }
+          ],
+          "description": "The branch whose commits are tagged, such as main. Only its first-parent commits count. A list judges each branch, so a branch ci.branches routes members to gets a green verdict and can release (#4325); the first is the trunk that readers use when they are not told a branch. A string reads as it always did."
         },
         "window": {
           "type": "string",