@descent-vtt/spec-harness 0.6.0 → 0.8.0

package/dist/context.js

@@ -9,12 +9,15 @@
  * they fill what the budget leaves, in the order the brief cites them, and
  * the rest are named rather than dropped silently. So is a document whose
  * front matter is never closed, whose status cannot be read, rather than
- * shown as one without a status, and a pattern in the scope, a protection or
- * a ruling's path the guard cannot read, with spec-core's reason and what the
- * guard does without it, rather than listed as one it can.
+ * shown as one without a status, and a line of front matter that is not
+ * `key: value`, passed over with any status written on it; and a pattern in
+ * the scope, a protection or a ruling's path the guard cannot read, with
+ * spec-core's reason and what the guard does without it, rather than listed
+ * as one it can; and one a leading `/` roots, which names no path the guard
+ * decides.
  */
 import { sameId } from './branch.js';
-import { whyUnreadable } from './guard.js';
+import { rooted, whyUnreadable } from './guard.js';
 /**
  * spec-guard's answer to `query --json`, read. It exits 2 both when no spec
  * file matched its patterns - a repository that keeps none, or keeps them
@@ -47,23 +50,36 @@ export function readRules(answer) {
 function list(items) {
     return items.map((item) => `- \`${item}\``).join('\n');
 }
+/** An unread line of front matter: where it is, as written, and spec-core's reason. */
+function unreadLine(found) {
+    return `- \`${found.path}\`, line ${found.line}, \`${found.text}\`: ${found.reason}`;
+}
 /**
  * Each pattern a line, as the guard reads it: as written, or with spec-core's
  * reason the guard cannot read it and what the guard does without it. The
  * guard's own compile decides, so the packet and the guard cannot disagree.
+ * A pattern a leading `/` roots, or one of whose alternatives it roots, is
+ * marked with `rootedNote`, and counted when every alternative is rooted.
  */
-function patternLines(patterns, consequence) {
+function patternLines(patterns, consequence, rootedNote) {
     const unreadable = [];
+    let rootedWhole = 0;
     const lines = patterns.map((pattern) => {
         const reason = whyUnreadable(pattern);
-        if (reason === null)
-            return `- \`${pattern}\``;
+        if (reason === null) {
+            const root = rooted(pattern);
+            if (root === null)
+                return `- \`${pattern}\``;
+            if (root === 'whole')
+                rootedWhole += 1;
+            return `- \`${pattern}\`, ${rootedNote[root]}`;
+        }
         unreadable.push({ pattern, reason });
         return `- \`${pattern}\`, which the guard cannot read: ${reason}; ${consequence}`;
     });
-    return { lines, unreadable };
+    return { lines, unreadable, rootedWhole };
 }
-function rulesSection(rules, scopeUnread) {
+function rulesSection(rules, scopeUnread, scopeRooted) {
     if ('none' in rules)
         return `spec-guard holds no rule over this scope: ${rules.none}.`;
     if ('unavailable' in rules) {
@@ -73,8 +89,11 @@ function rulesSection(rules, scopeUnread) {
         // With no pattern of the scope readable, spec-guard was asked about no
         // path, so an empty answer is no answer: "no rule" would tell the agent
         // the code it writes is unconstrained.
-        return scopeUnread
-            ? 'The scope could not be read: no pattern in `affectedFiles` can be read, so spec-guard was not asked for the rules over it. Treat every ADR as binding until the scope is fixed.'
+        if (scopeUnread) {
+            return 'The scope could not be read: no pattern in `affectedFiles` can be read, so spec-guard was not asked for the rules over it. Treat every ADR as binding until the scope is fixed.';
+        }
+        return scopeRooted
+            ? "No pattern in `affectedFiles` puts a path in the scope: each is rooted at the filesystem's root or cannot be read, so spec-guard was not asked for the rules over it. Treat every ADR as binding until the scope is fixed."
             : 'spec-guard holds no rule over this scope.';
     }
     const byDocument = new Map();
@@ -90,15 +109,19 @@ function rulesSection(rules, scopeUnread) {
     return parts.join('\n').trimEnd();
 }
 /**
- * A brief's title without the id it repeats: `012 - Rotate tokens` read as
- * `Rotate tokens`, and the same with an en or an em dash, which `spec-brief
- * new` writes, or with a colon after the id. Only the brief's own id is taken
- * off: `Fix - the login bug` is a title, not an id and a title.
+ * A brief's title without the id it repeats, by the rules spec-brief reads
+ * it with: the brief's own id, then an em dash, which `spec-brief new`
+ * writes, an en dash, a full-width colon or a colon, spaced or not, or a
+ * hyphen with a space on each side; `012 - Rotate tokens`, `012\u2014Rotate
+ * tokens` and `012\uFF1ARotate tokens` read as `Rotate tokens`. A bare hyphen
+ * is part of a word or a number, as in `001-2 migration`, and only the
+ * brief's own id is taken off: `Fix - the login bug` is a title, and so is
+ * `0010 \u2014 x` on brief 001.
  */
 export function titleOf(brief) {
     if (brief.title === null)
         return null;
-    return brief.title.replace(/^\s*([^\s:]+)(?:\s+[-\u2013\u2014]|:)\s+/, (whole, first) => (sameId(first, brief.id) ? '' : whole));
+    return brief.title.replace(/^\s*([^\s:\uFF1A\u2013\u2014]+)(?:\s*[:\uFF1A\u2013\u2014]\s*|\s+-\s+)(?=\S)/, (whole, first) => sameId(first, brief.id) ? '' : whole);
 }
 /** Renders the packet, filling the budget with cited documents in the order the brief cites them. */
 export function renderContext(input) {
@@ -128,20 +151,36 @@ export function renderContext(input) {
             .map((ruling) => {
             const paths = ruling.paths.map((pattern) => {
                 const reason = whyUnreadable(pattern);
-                if (reason === null)
+                if (reason === null) {
+                    // A rooted path can be read, and names no path the guard decides.
+                    const root = rooted(pattern);
+                    if (root === 'whole')
+                        return `\`${pattern}\` (which a leading \`/\` roots at the filesystem's root; it allows nothing)`;
+                    if (root === 'part')
+                        return `\`${pattern}\` (an alternative of which a leading \`/\` roots at the filesystem's root; that alternative allows nothing)`;
                     return `\`${pattern}\``;
+                }
                 unreadableRulingPaths.push({ ruling: ruling.id, pattern, reason });
                 return `\`${pattern}\` (which the guard cannot read: ${reason}; it allows nothing)`;
             });
             return `- ${ruling.id}, signed by ${ruling.signer}: ${paths.join(', ')}`;
         })
             .join('\n');
-    const mayWrite = patternLines(brief.affectedFiles, 'it puts no path in the scope');
+    // A rooted pattern can be read and puts no path in the scope: every path
+    // the guard decides is repository-relative. spec-guard is not asked about it.
+    const mayWrite = patternLines(brief.affectedFiles, 'it puts no path in the scope', {
+        whole: "which a leading `/` roots at the filesystem's root: it puts no path in the scope, and spec-guard is not asked about it",
+        part: "an alternative of which a leading `/` roots at the filesystem's root: that alternative puts no path in the scope, and spec-guard is not asked about it",
+    });
     const unreadableScope = mayWrite.unreadable;
     // While a protection the guard cannot read stands, the guard refuses every
     // write, and no ruling waives it; a write to the brief is let through,
-    // since that is where it is fixed.
-    const mustNot = patternLines(brief.protectedFiles, 'until it is fixed, the guard refuses every write but to the brief');
+    // since that is where it is fixed. A rooted protection can be read, and
+    // protects nothing: the file it was meant to protect is the round's to write.
+    const mustNot = patternLines(brief.protectedFiles, 'until it is fixed, the guard refuses every write but to the brief', {
+        whole: "which a leading `/` roots at the filesystem's root: it protects no path",
+        part: "an alternative of which a leading `/` roots at the filesystem's root: that alternative protects no path",
+    });
     const unreadableProtections = mustNot.unreadable;
     const scope = [
         '## Scope, as the guard reads it',
@@ -163,7 +202,8 @@ export function renderContext(input) {
     });
     const dependencies = ['## Depends on', '', waiting.length === 0 ? '- nothing' : waiting.join('\n'), ''].join('\n');
     const scopeUnread = mayWrite.lines.length > 0 && unreadableScope.length === mayWrite.lines.length;
-    const rules = ['## Rules in force for this scope', '', rulesSection(input.rules, scopeUnread), ''].join('\n');
+    const scopeRooted = mayWrite.rootedWhole > 0 && unreadableScope.length + mayWrite.rootedWhole === mayWrite.lines.length;
+    const rules = ['## Rules in force for this scope', '', rulesSection(input.rules, scopeUnread, scopeRooted), ''].join('\n');
     const howTo = [
         '## How this round works',
         '',
@@ -178,6 +218,7 @@ export function renderContext(input) {
     const omitted = [];
     const unresolved = [];
     const unclosed = [];
+    const unreadableFrontMatter = [];
     const documents = [];
     let used = fixed.length;
     for (const cited of input.cited) {
@@ -189,6 +230,8 @@ export function renderContext(input) {
         // unread either way, and the fix is the same.
         if (cited.unclosedFrontMatter === true)
             unclosed.push(cited.path);
+        for (const line of cited.unreadableFrontMatter ?? [])
+            unreadableFrontMatter.push({ path: cited.path, ...line });
         const heading = `### \`${cited.path}\`${cited.title === null ? '' : ` - ${cited.title}`}${cited.status === null ? '' : ` (${cited.status})`}`;
         const block = [heading, '', '````markdown', cited.text.trimEnd(), '````', ''].join('\n');
         if (used + block.length > input.budget) {
@@ -211,12 +254,17 @@ export function renderContext(input) {
     if (unclosed.length > 0) {
         citedSection.push('Front matter opened on line 1 and never closed, so the status was not read; close the block with `---` on a line of its own:', list(unclosed), '');
     }
+    // The last note: the section is trimmed at its end, so no blank line follows it.
+    if (unreadableFrontMatter.length > 0) {
+        citedSection.push('Front matter lines that are not `key: value` were not read, so a status written on one, if any, was not read either:', unreadableFrontMatter.map(unreadLine).join('\n'));
+    }
     return {
         markdown: `${fixed}\n${citedSection.join('\n').trimEnd()}\n`,
         included,
         omitted,
         unresolved,
         unclosedFrontMatter: unclosed,
+        unreadableFrontMatter,
         unreadableScope,
         unreadableProtections,
         unreadableRulingPaths,

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What an agent needs to start a round, and nothing it does not.\n *\n * The brief in full - it is the contract, and a summary of a contract is a\n * different contract. Then what the brief implies but does not say: the scope\n * as the guard will read it, the rulings already signed, the briefs it waits\n * on, the rules spec-guard holds the scope's code to, and the documents the\n * brief cites. The cited documents are the one part that can be large, so\n * they fill what the budget leaves, in the order the brief cites them, and\n * the rest are named rather than dropped silently. So is a document whose\n * front matter is never closed, whose status cannot be read, rather than\n * shown as one without a status, and a pattern in the scope, a protection or\n * a ruling's path the guard cannot read, with spec-core's reason and what the\n * guard does without it, rather than listed as one it can.\n */\n\nimport { sameId } from './branch.js';\nimport { whyUnreadable } from './guard.js';\nimport type { BriefRow } from './types.js';\n\nexport interface CitedDocument {\n  readonly path: string;\n  readonly title: string | null;\n  readonly status: string | null;\n  /** `null` when the link does not resolve to a readable file. */\n  readonly text: string | null;\n  /** YAML front matter opened on line 1 and never closed, so no status was read from it. */\n  readonly unclosedFrontMatter?: boolean | undefined;\n}\n\nexport interface RuleInForce {\n  readonly document: string;\n  readonly line: number;\n  readonly kind: string;\n  readonly description: string;\n  readonly reason: string | null;\n}\n\n/**\n * The rules in force for the scope; `none` when spec-guard reads no\n * specification here, so none can be in force; `unavailable` when the rules\n * could not be read.\n */\nexport type Rules = readonly RuleInForce[] | { readonly none: string } | { readonly unavailable: string };\n\ninterface QueryDocument {\n  readonly specFiles?: unknown;\n  readonly results?: readonly { readonly rules?: readonly (RuleInForce & { readonly reason?: string | null; readonly inForce?: boolean })[] }[];\n}\n\n/**\n * spec-guard's answer to `query --json`, read. It exits 2 both when no spec\n * file matched its patterns - a repository that keeps none, or keeps them\n * where it does not look - and when it could not read the specs it has; only\n * the first prints a document, one with no spec file in it, so that is how\n * the two are told apart. What it said on stderr is the reason for the second.\n */\nexport function readRules(answer: { readonly code: number; readonly document: unknown; readonly stderr: string }): Rules {\n  const document = (answer.document ?? {}) as QueryDocument;\n  if (answer.code !== 0) {\n    if (Array.isArray(document.specFiles) && document.specFiles.length === 0) {\n      return { none: 'no spec file matched its patterns (\"specs\" in its configuration, docs/**/*.md by default)' };\n    }\n    const said = (answer.stderr.trim().split('\\n')[0] ?? '').replace(/^spec-guard:\\s*/, '');\n    return { unavailable: said === '' ? `spec-guard exited ${answer.code}` : `spec-guard exited ${answer.code}: ${said}` };\n  }\n  const seen = new Set<string>();\n  const out: RuleInForce[] = [];\n  for (const result of document.results ?? []) {\n    for (const rule of result.rules ?? []) {\n      const key = `${rule.document}:${rule.line}`;\n      if (rule.inForce === false || seen.has(key)) continue;\n      seen.add(key);\n      out.push({ document: rule.document, line: rule.line, kind: rule.kind, description: rule.description, reason: rule.reason ?? null });\n    }\n  }\n  return out;\n}\n\nexport interface RulingInForce {\n  readonly id: string;\n  readonly paths: readonly string[];\n  readonly signer: string;\n}\n\nexport interface ContextInput {\n  readonly brief: BriefRow;\n  readonly briefText: string;\n  readonly dependencies: readonly BriefRow[];\n  readonly cited: readonly CitedDocument[];\n  /** The rules in force for the scope, none because spec-guard reads no specification, or why they could not be read. */\n  readonly rules: Rules;\n  readonly rulings: readonly RulingInForce[];\n  readonly branch: string | null;\n  readonly base: string | null;\n  readonly budget: number;\n}\n\n/** A pattern in the brief's scope or protections that the guard cannot read, with spec-core's reason. */\nexport interface UnreadablePattern {\n  readonly pattern: string;\n  readonly reason: string;\n}\n\n/** A path of a ruling in force that the guard cannot read, with the ruling's id and spec-core's reason. */\nexport interface UnreadableRulingPath extends UnreadablePattern {\n  readonly ruling: string;\n}\n\nexport interface ContextPacket {\n  readonly markdown: string;\n  /** Cited documents included whole. */\n  readonly included: readonly string[];\n  /** Cited documents named but left out for the budget. */\n  readonly omitted: readonly string[];\n  /** Links in the brief that resolve to nothing. */\n  readonly unresolved: readonly string[];\n  /** Cited documents whose front matter opens on line 1 and is never closed, so no status was read from them. */\n  readonly unclosedFrontMatter: readonly string[];\n  /** Patterns in `affectedFiles` the guard cannot read, in the brief's order: each puts no path in the scope. */\n  readonly unreadableScope: readonly UnreadablePattern[];\n  /** Patterns in `protectedFiles` the guard cannot read, in the brief's order: while one stands, the guard refuses every write but to the brief. */\n  readonly unreadableProtections: readonly UnreadablePattern[];\n  /** Paths of the rulings in force the guard cannot read, in the order the rulings are listed: each allows nothing. */\n  readonly unreadableRulingPaths: readonly UnreadableRulingPath[];\n}\n\nfunction list(items: readonly string[]): string {\n  return items.map((item) => `- \\`${item}\\``).join('\\n');\n}\n\n/**\n * Each pattern a line, as the guard reads it: as written, or with spec-core's\n * reason the guard cannot read it and what the guard does without it. The\n * guard's own compile decides, so the packet and the guard cannot disagree.\n */\nfunction patternLines(patterns: readonly string[], consequence: string): { lines: string[]; unreadable: UnreadablePattern[] } {\n  const unreadable: UnreadablePattern[] = [];\n  const lines = patterns.map((pattern) => {\n    const reason = whyUnreadable(pattern);\n    if (reason === null) return `- \\`${pattern}\\``;\n    unreadable.push({ pattern, reason });\n    return `- \\`${pattern}\\`, which the guard cannot read: ${reason}; ${consequence}`;\n  });\n  return { lines, unreadable };\n}\n\nfunction rulesSection(rules: Rules, scopeUnread: boolean): string {\n  if ('none' in rules) return `spec-guard holds no rule over this scope: ${rules.none}.`;\n  if ('unavailable' in rules) {\n    return `The rules spec-guard holds this code to could not be read: ${rules.unavailable}. Treat every ADR as binding until they can.`;\n  }\n  if (rules.length === 0) {\n    // With no pattern of the scope readable, spec-guard was asked about no\n    // path, so an empty answer is no answer: \"no rule\" would tell the agent\n    // the code it writes is unconstrained.\n    return scopeUnread\n      ? 'The scope could not be read: no pattern in `affectedFiles` can be read, so spec-guard was not asked for the rules over it. Treat every ADR as binding until the scope is fixed.'\n      : 'spec-guard holds no rule over this scope.';\n  }\n  const byDocument = new Map<string, RuleInForce[]>();\n  for (const rule of rules) byDocument.set(rule.document, [...(byDocument.get(rule.document) ?? []), rule]);\n  const parts: string[] = [];\n  for (const [document, found] of byDocument) {\n    parts.push(`### ${document}`, '');\n    for (const rule of found) parts.push(`- line ${rule.line}: ${rule.description}${rule.reason === null ? '' : ` - ${rule.reason}`}`);\n    parts.push('');\n  }\n  return parts.join('\\n').trimEnd();\n}\n\n/**\n * A brief's title without the id it repeats: `012 - Rotate tokens` read as\n * `Rotate tokens`, and the same with an en or an em dash, which `spec-brief\n * new` writes, or with a colon after the id. Only the brief's own id is taken\n * off: `Fix - the login bug` is a title, not an id and a title.\n */\nexport function titleOf(brief: Pick<BriefRow, 'id' | 'title'>): string | null {\n  if (brief.title === null) return null;\n  return brief.title.replace(/^\\s*([^\\s:]+)(?:\\s+[-\\u2013\\u2014]|:)\\s+/, (whole, first: string) => (sameId(first, brief.id) ? '' : whole));\n}\n\n/** Renders the packet, filling the budget with cited documents in the order the brief cites them. */\nexport function renderContext(input: ContextInput): ContextPacket {\n  const { brief } = input;\n  const title = titleOf(brief);\n  const header = [\n    `# Round ${brief.id}${title === null ? '' : `: ${title}`}`,\n    '',\n    [\n      `Status ${brief.status ?? 'unknown'}`,\n      brief.wave === null ? null : `wave ${brief.wave}`,\n      input.branch === null ? null : `branch \\`${input.branch}\\``,\n      input.base === null ? null : `measured from \\`${input.base}\\``,\n    ]\n      .filter((part) => part !== null)\n      .join(' · '),\n    '',\n  ].join('\\n');\n\n  const contract = ['## The contract', '', `\\`${brief.file}\\`, in full:`, '', '````markdown', input.briefText.trimEnd(), '````', ''].join('\\n');\n\n  // The guard passes over a ruling's path it cannot read, so the path allows\n  // nothing. The paths share a line, so the note is in parentheses, closed\n  // before the next path.\n  const unreadableRulingPaths: UnreadableRulingPath[] = [];\n  const rulings =\n    input.rulings.length === 0\n      ? '- none'\n      : input.rulings\n          .map((ruling) => {\n            const paths = ruling.paths.map((pattern) => {\n              const reason = whyUnreadable(pattern);\n              if (reason === null) return `\\`${pattern}\\``;\n              unreadableRulingPaths.push({ ruling: ruling.id, pattern, reason });\n              return `\\`${pattern}\\` (which the guard cannot read: ${reason}; it allows nothing)`;\n            });\n            return `- ${ruling.id}, signed by ${ruling.signer}: ${paths.join(', ')}`;\n          })\n          .join('\\n');\n  const mayWrite = patternLines(brief.affectedFiles, 'it puts no path in the scope');\n  const unreadableScope = mayWrite.unreadable;\n  // While a protection the guard cannot read stands, the guard refuses every\n  // write, and no ruling waives it; a write to the brief is let through,\n  // since that is where it is fixed.\n  const mustNot = patternLines(brief.protectedFiles, 'until it is fixed, the guard refuses every write but to the brief');\n  const unreadableProtections = mustNot.unreadable;\n  const scope = [\n    '## Scope, as the guard reads it',\n    '',\n    'May write:',\n    mayWrite.lines.length === 0 ? '- nothing declared: every write is outside the scope' : mayWrite.lines.join('\\n'),\n    '',\n    'Must not change without a ruling:',\n    mustNot.lines.length === 0 ? '- nothing declared' : mustNot.lines.join('\\n'),\n    '',\n    'Rulings in force:',\n    rulings,\n    '',\n  ].join('\\n');\n\n  const waiting = input.dependencies.map((dependency) => {\n    const state = dependency.phase === 'archived' ? 'archived, done' : `still ${dependency.status ?? 'live'}`;\n    const named = titleOf(dependency);\n    return `- ${dependency.id}${named === null ? '' : ` ${named}`}: ${state}`;\n  });\n  const dependencies = ['## Depends on', '', waiting.length === 0 ? '- nothing' : waiting.join('\\n'), ''].join('\\n');\n\n  const scopeUnread = mayWrite.lines.length > 0 && unreadableScope.length === mayWrite.lines.length;\n  const rules = ['## Rules in force for this scope', '', rulesSection(input.rules, scopeUnread), ''].join('\\n');\n\n  const howTo = [\n    '## How this round works',\n    '',\n    '- Before writing a file, ask whether the round may: `spec-harness guard <path>`, or the `check_path` tool.',\n    '- A protected file is changed only under a ruling a person signs. If the round cannot be done without one, stop and ask: `spec-harness escalate --path <file> --reason <why>`, or the `request_escalation` tool. Do not work around it.',\n    '- Every box in the brief ends ticked, or with a note under it that starts with a disposition (`**Delegated`, `**Accepted debt`, `**Rejected`, or what the repository configures).',\n    '- When the work is done, run `spec-harness audit` and fix what it reports. The archive is a person\\'s decision, not the round\\'s.',\n    '',\n  ].join('\\n');\n\n  const fixed = [header, contract, scope, dependencies, rules, howTo].join('\\n');\n  const included: string[] = [];\n  const omitted: string[] = [];\n  const unresolved: string[] = [];\n  const unclosed: string[] = [];\n  const documents: string[] = [];\n  let used = fixed.length;\n  for (const cited of input.cited) {\n    if (cited.text === null) {\n      unresolved.push(cited.path);\n      continue;\n    }\n    // Named whether or not the budget leaves room for it: the status is\n    // unread either way, and the fix is the same.\n    if (cited.unclosedFrontMatter === true) unclosed.push(cited.path);\n    const heading = `### \\`${cited.path}\\`${cited.title === null ? '' : ` - ${cited.title}`}${cited.status === null ? '' : ` (${cited.status})`}`;\n    const block = [heading, '', '````markdown', cited.text.trimEnd(), '````', ''].join('\\n');\n    if (used + block.length > input.budget) {\n      omitted.push(cited.path);\n      continue;\n    }\n    used += block.length;\n    included.push(cited.path);\n    documents.push(block);\n  }\n  const citedSection = ['## Documents the brief cites', ''];\n  if (documents.length === 0 && omitted.length === 0 && unresolved.length === 0) citedSection.push('None.', '');\n  citedSection.push(...documents);\n  if (omitted.length > 0) {\n    citedSection.push(`Left out to stay within ${input.budget} characters; read them when the work reaches them:`, list(omitted), '');\n  }\n  if (unresolved.length > 0) citedSection.push('Cited but not found in the repository:', list(unresolved), '');\n  if (unclosed.length > 0) {\n    citedSection.push('Front matter opened on line 1 and never closed, so the status was not read; close the block with `---` on a line of its own:', list(unclosed), '');\n  }\n\n  return {\n    markdown: `${fixed}\\n${citedSection.join('\\n').trimEnd()}\\n`,\n    included,\n    omitted,\n    unresolved,\n    unclosedFrontMatter: unclosed,\n    unreadableScope,\n    unreadableProtections,\n    unreadableRulingPaths,\n  };\n}\n"]}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What an agent needs to start a round, and nothing it does not.\n *\n * The brief in full - it is the contract, and a summary of a contract is a\n * different contract. Then what the brief implies but does not say: the scope\n * as the guard will read it, the rulings already signed, the briefs it waits\n * on, the rules spec-guard holds the scope's code to, and the documents the\n * brief cites. The cited documents are the one part that can be large, so\n * they fill what the budget leaves, in the order the brief cites them, and\n * the rest are named rather than dropped silently. So is a document whose\n * front matter is never closed, whose status cannot be read, rather than\n * shown as one without a status, and a line of front matter that is not\n * `key: value`, passed over with any status written on it; and a pattern in\n * the scope, a protection or a ruling's path the guard cannot read, with\n * spec-core's reason and what the guard does without it, rather than listed\n * as one it can; and one a leading `/` roots, which names no path the guard\n * decides.\n */\n\nimport { sameId } from './branch.js';\nimport type { UnreadableFrontMatterLine } from './document.js';\nimport { rooted, whyUnreadable } from './guard.js';\nimport type { BriefRow } from './types.js';\n\nexport interface CitedDocument {\n  readonly path: string;\n  readonly title: string | null;\n  readonly status: string | null;\n  /** `null` when the link does not resolve to a readable file. */\n  readonly text: string | null;\n  /** YAML front matter opened on line 1 and never closed, so no status was read from it. */\n  readonly unclosedFrontMatter?: boolean | undefined;\n  /** Lines of its front matter that are not `key: value`, passed over with any status written on them. */\n  readonly unreadableFrontMatter?: readonly UnreadableFrontMatterLine[] | undefined;\n}\n\nexport interface RuleInForce {\n  readonly document: string;\n  readonly line: number;\n  readonly kind: string;\n  readonly description: string;\n  readonly reason: string | null;\n}\n\n/**\n * The rules in force for the scope; `none` when spec-guard reads no\n * specification here, so none can be in force; `unavailable` when the rules\n * could not be read.\n */\nexport type Rules = readonly RuleInForce[] | { readonly none: string } | { readonly unavailable: string };\n\ninterface QueryDocument {\n  readonly specFiles?: unknown;\n  readonly results?: readonly { readonly rules?: readonly (RuleInForce & { readonly reason?: string | null; readonly inForce?: boolean })[] }[];\n}\n\n/**\n * spec-guard's answer to `query --json`, read. It exits 2 both when no spec\n * file matched its patterns - a repository that keeps none, or keeps them\n * where it does not look - and when it could not read the specs it has; only\n * the first prints a document, one with no spec file in it, so that is how\n * the two are told apart. What it said on stderr is the reason for the second.\n */\nexport function readRules(answer: { readonly code: number; readonly document: unknown; readonly stderr: string }): Rules {\n  const document = (answer.document ?? {}) as QueryDocument;\n  if (answer.code !== 0) {\n    if (Array.isArray(document.specFiles) && document.specFiles.length === 0) {\n      return { none: 'no spec file matched its patterns (\"specs\" in its configuration, docs/**/*.md by default)' };\n    }\n    const said = (answer.stderr.trim().split('\\n')[0] ?? '').replace(/^spec-guard:\\s*/, '');\n    return { unavailable: said === '' ? `spec-guard exited ${answer.code}` : `spec-guard exited ${answer.code}: ${said}` };\n  }\n  const seen = new Set<string>();\n  const out: RuleInForce[] = [];\n  for (const result of document.results ?? []) {\n    for (const rule of result.rules ?? []) {\n      const key = `${rule.document}:${rule.line}`;\n      if (rule.inForce === false || seen.has(key)) continue;\n      seen.add(key);\n      out.push({ document: rule.document, line: rule.line, kind: rule.kind, description: rule.description, reason: rule.reason ?? null });\n    }\n  }\n  return out;\n}\n\nexport interface RulingInForce {\n  readonly id: string;\n  readonly paths: readonly string[];\n  readonly signer: string;\n}\n\nexport interface ContextInput {\n  readonly brief: BriefRow;\n  readonly briefText: string;\n  readonly dependencies: readonly BriefRow[];\n  readonly cited: readonly CitedDocument[];\n  /** The rules in force for the scope, none because spec-guard reads no specification, or why they could not be read. */\n  readonly rules: Rules;\n  readonly rulings: readonly RulingInForce[];\n  readonly branch: string | null;\n  readonly base: string | null;\n  readonly budget: number;\n}\n\n/** A pattern in the brief's scope or protections that the guard cannot read, with spec-core's reason. */\nexport interface UnreadablePattern {\n  readonly pattern: string;\n  readonly reason: string;\n}\n\n/** A line of a cited document's front matter that is not `key: value`, with spec-core's reason. */\nexport interface UnreadableFrontMatter extends UnreadableFrontMatterLine {\n  readonly path: string;\n}\n\n/** A path of a ruling in force that the guard cannot read, with the ruling's id and spec-core's reason. */\nexport interface UnreadableRulingPath extends UnreadablePattern {\n  readonly ruling: string;\n}\n\nexport interface ContextPacket {\n  readonly markdown: string;\n  /** Cited documents included whole. */\n  readonly included: readonly string[];\n  /** Cited documents named but left out for the budget. */\n  readonly omitted: readonly string[];\n  /** Links in the brief that resolve to nothing. */\n  readonly unresolved: readonly string[];\n  /** Cited documents whose front matter opens on line 1 and is never closed, so no status was read from them. */\n  readonly unclosedFrontMatter: readonly string[];\n  /** Lines of cited documents' front matter that are not `key: value`, in the order the brief cites them: a status written on one was not read. */\n  readonly unreadableFrontMatter: readonly UnreadableFrontMatter[];\n  /** Patterns in `affectedFiles` the guard cannot read, in the brief's order: each puts no path in the scope. */\n  readonly unreadableScope: readonly UnreadablePattern[];\n  /** Patterns in `protectedFiles` the guard cannot read, in the brief's order: while one stands, the guard refuses every write but to the brief. */\n  readonly unreadableProtections: readonly UnreadablePattern[];\n  /** Paths of the rulings in force the guard cannot read, in the order the rulings are listed: each allows nothing. */\n  readonly unreadableRulingPaths: readonly UnreadableRulingPath[];\n}\n\nfunction list(items: readonly string[]): string {\n  return items.map((item) => `- \\`${item}\\``).join('\\n');\n}\n\n/** An unread line of front matter: where it is, as written, and spec-core's reason. */\nfunction unreadLine(found: UnreadableFrontMatter): string {\n  return `- \\`${found.path}\\`, line ${found.line}, \\`${found.text}\\`: ${found.reason}`;\n}\n\n/**\n * Each pattern a line, as the guard reads it: as written, or with spec-core's\n * reason the guard cannot read it and what the guard does without it. The\n * guard's own compile decides, so the packet and the guard cannot disagree.\n * A pattern a leading `/` roots, or one of whose alternatives it roots, is\n * marked with `rootedNote`, and counted when every alternative is rooted.\n */\nfunction patternLines(\n  patterns: readonly string[],\n  consequence: string,\n  rootedNote: { readonly whole: string; readonly part: string },\n): { lines: string[]; unreadable: UnreadablePattern[]; rootedWhole: number } {\n  const unreadable: UnreadablePattern[] = [];\n  let rootedWhole = 0;\n  const lines = patterns.map((pattern) => {\n    const reason = whyUnreadable(pattern);\n    if (reason === null) {\n      const root = rooted(pattern);\n      if (root === null) return `- \\`${pattern}\\``;\n      if (root === 'whole') rootedWhole += 1;\n      return `- \\`${pattern}\\`, ${rootedNote[root]}`;\n    }\n    unreadable.push({ pattern, reason });\n    return `- \\`${pattern}\\`, which the guard cannot read: ${reason}; ${consequence}`;\n  });\n  return { lines, unreadable, rootedWhole };\n}\n\nfunction rulesSection(rules: Rules, scopeUnread: boolean, scopeRooted: boolean): string {\n  if ('none' in rules) return `spec-guard holds no rule over this scope: ${rules.none}.`;\n  if ('unavailable' in rules) {\n    return `The rules spec-guard holds this code to could not be read: ${rules.unavailable}. Treat every ADR as binding until they can.`;\n  }\n  if (rules.length === 0) {\n    // With no pattern of the scope readable, spec-guard was asked about no\n    // path, so an empty answer is no answer: \"no rule\" would tell the agent\n    // the code it writes is unconstrained.\n    if (scopeUnread) {\n      return 'The scope could not be read: no pattern in `affectedFiles` can be read, so spec-guard was not asked for the rules over it. Treat every ADR as binding until the scope is fixed.';\n    }\n    return scopeRooted\n      ? \"No pattern in `affectedFiles` puts a path in the scope: each is rooted at the filesystem's root or cannot be read, so spec-guard was not asked for the rules over it. Treat every ADR as binding until the scope is fixed.\"\n      : 'spec-guard holds no rule over this scope.';\n  }\n  const byDocument = new Map<string, RuleInForce[]>();\n  for (const rule of rules) byDocument.set(rule.document, [...(byDocument.get(rule.document) ?? []), rule]);\n  const parts: string[] = [];\n  for (const [document, found] of byDocument) {\n    parts.push(`### ${document}`, '');\n    for (const rule of found) parts.push(`- line ${rule.line}: ${rule.description}${rule.reason === null ? '' : ` - ${rule.reason}`}`);\n    parts.push('');\n  }\n  return parts.join('\\n').trimEnd();\n}\n\n/**\n * A brief's title without the id it repeats, by the rules spec-brief reads\n * it with: the brief's own id, then an em dash, which `spec-brief new`\n * writes, an en dash, a full-width colon or a colon, spaced or not, or a\n * hyphen with a space on each side; `012 - Rotate tokens`, `012\\u2014Rotate\n * tokens` and `012\\uFF1ARotate tokens` read as `Rotate tokens`. A bare hyphen\n * is part of a word or a number, as in `001-2 migration`, and only the\n * brief's own id is taken off: `Fix - the login bug` is a title, and so is\n * `0010 \\u2014 x` on brief 001.\n */\nexport function titleOf(brief: Pick<BriefRow, 'id' | 'title'>): string | null {\n  if (brief.title === null) return null;\n  return brief.title.replace(/^\\s*([^\\s:\\uFF1A\\u2013\\u2014]+)(?:\\s*[:\\uFF1A\\u2013\\u2014]\\s*|\\s+-\\s+)(?=\\S)/, (whole, first: string) =>\n    sameId(first, brief.id) ? '' : whole,\n  );\n}\n\n/** Renders the packet, filling the budget with cited documents in the order the brief cites them. */\nexport function renderContext(input: ContextInput): ContextPacket {\n  const { brief } = input;\n  const title = titleOf(brief);\n  const header = [\n    `# Round ${brief.id}${title === null ? '' : `: ${title}`}`,\n    '',\n    [\n      `Status ${brief.status ?? 'unknown'}`,\n      brief.wave === null ? null : `wave ${brief.wave}`,\n      input.branch === null ? null : `branch \\`${input.branch}\\``,\n      input.base === null ? null : `measured from \\`${input.base}\\``,\n    ]\n      .filter((part) => part !== null)\n      .join(' · '),\n    '',\n  ].join('\\n');\n\n  const contract = ['## The contract', '', `\\`${brief.file}\\`, in full:`, '', '````markdown', input.briefText.trimEnd(), '````', ''].join('\\n');\n\n  // The guard passes over a ruling's path it cannot read, so the path allows\n  // nothing. The paths share a line, so the note is in parentheses, closed\n  // before the next path.\n  const unreadableRulingPaths: UnreadableRulingPath[] = [];\n  const rulings =\n    input.rulings.length === 0\n      ? '- none'\n      : input.rulings\n          .map((ruling) => {\n            const paths = ruling.paths.map((pattern) => {\n              const reason = whyUnreadable(pattern);\n              if (reason === null) {\n                // A rooted path can be read, and names no path the guard decides.\n                const root = rooted(pattern);\n                if (root === 'whole') return `\\`${pattern}\\` (which a leading \\`/\\` roots at the filesystem's root; it allows nothing)`;\n                if (root === 'part') return `\\`${pattern}\\` (an alternative of which a leading \\`/\\` roots at the filesystem's root; that alternative allows nothing)`;\n                return `\\`${pattern}\\``;\n              }\n              unreadableRulingPaths.push({ ruling: ruling.id, pattern, reason });\n              return `\\`${pattern}\\` (which the guard cannot read: ${reason}; it allows nothing)`;\n            });\n            return `- ${ruling.id}, signed by ${ruling.signer}: ${paths.join(', ')}`;\n          })\n          .join('\\n');\n  // A rooted pattern can be read and puts no path in the scope: every path\n  // the guard decides is repository-relative. spec-guard is not asked about it.\n  const mayWrite = patternLines(brief.affectedFiles, 'it puts no path in the scope', {\n    whole: \"which a leading `/` roots at the filesystem's root: it puts no path in the scope, and spec-guard is not asked about it\",\n    part: \"an alternative of which a leading `/` roots at the filesystem's root: that alternative puts no path in the scope, and spec-guard is not asked about it\",\n  });\n  const unreadableScope = mayWrite.unreadable;\n  // While a protection the guard cannot read stands, the guard refuses every\n  // write, and no ruling waives it; a write to the brief is let through,\n  // since that is where it is fixed. A rooted protection can be read, and\n  // protects nothing: the file it was meant to protect is the round's to write.\n  const mustNot = patternLines(brief.protectedFiles, 'until it is fixed, the guard refuses every write but to the brief', {\n    whole: \"which a leading `/` roots at the filesystem's root: it protects no path\",\n    part: \"an alternative of which a leading `/` roots at the filesystem's root: that alternative protects no path\",\n  });\n  const unreadableProtections = mustNot.unreadable;\n  const scope = [\n    '## Scope, as the guard reads it',\n    '',\n    'May write:',\n    mayWrite.lines.length === 0 ? '- nothing declared: every write is outside the scope' : mayWrite.lines.join('\\n'),\n    '',\n    'Must not change without a ruling:',\n    mustNot.lines.length === 0 ? '- nothing declared' : mustNot.lines.join('\\n'),\n    '',\n    'Rulings in force:',\n    rulings,\n    '',\n  ].join('\\n');\n\n  const waiting = input.dependencies.map((dependency) => {\n    const state = dependency.phase === 'archived' ? 'archived, done' : `still ${dependency.status ?? 'live'}`;\n    const named = titleOf(dependency);\n    return `- ${dependency.id}${named === null ? '' : ` ${named}`}: ${state}`;\n  });\n  const dependencies = ['## Depends on', '', waiting.length === 0 ? '- nothing' : waiting.join('\\n'), ''].join('\\n');\n\n  const scopeUnread = mayWrite.lines.length > 0 && unreadableScope.length === mayWrite.lines.length;\n  const scopeRooted = mayWrite.rootedWhole > 0 && unreadableScope.length + mayWrite.rootedWhole === mayWrite.lines.length;\n  const rules = ['## Rules in force for this scope', '', rulesSection(input.rules, scopeUnread, scopeRooted), ''].join('\\n');\n\n  const howTo = [\n    '## How this round works',\n    '',\n    '- Before writing a file, ask whether the round may: `spec-harness guard <path>`, or the `check_path` tool.',\n    '- A protected file is changed only under a ruling a person signs. If the round cannot be done without one, stop and ask: `spec-harness escalate --path <file> --reason <why>`, or the `request_escalation` tool. Do not work around it.',\n    '- Every box in the brief ends ticked, or with a note under it that starts with a disposition (`**Delegated`, `**Accepted debt`, `**Rejected`, or what the repository configures).',\n    '- When the work is done, run `spec-harness audit` and fix what it reports. The archive is a person\\'s decision, not the round\\'s.',\n    '',\n  ].join('\\n');\n\n  const fixed = [header, contract, scope, dependencies, rules, howTo].join('\\n');\n  const included: string[] = [];\n  const omitted: string[] = [];\n  const unresolved: string[] = [];\n  const unclosed: string[] = [];\n  const unreadableFrontMatter: UnreadableFrontMatter[] = [];\n  const documents: string[] = [];\n  let used = fixed.length;\n  for (const cited of input.cited) {\n    if (cited.text === null) {\n      unresolved.push(cited.path);\n      continue;\n    }\n    // Named whether or not the budget leaves room for it: the status is\n    // unread either way, and the fix is the same.\n    if (cited.unclosedFrontMatter === true) unclosed.push(cited.path);\n    for (const line of cited.unreadableFrontMatter ?? []) unreadableFrontMatter.push({ path: cited.path, ...line });\n    const heading = `### \\`${cited.path}\\`${cited.title === null ? '' : ` - ${cited.title}`}${cited.status === null ? '' : ` (${cited.status})`}`;\n    const block = [heading, '', '````markdown', cited.text.trimEnd(), '````', ''].join('\\n');\n    if (used + block.length > input.budget) {\n      omitted.push(cited.path);\n      continue;\n    }\n    used += block.length;\n    included.push(cited.path);\n    documents.push(block);\n  }\n  const citedSection = ['## Documents the brief cites', ''];\n  if (documents.length === 0 && omitted.length === 0 && unresolved.length === 0) citedSection.push('None.', '');\n  citedSection.push(...documents);\n  if (omitted.length > 0) {\n    citedSection.push(`Left out to stay within ${input.budget} characters; read them when the work reaches them:`, list(omitted), '');\n  }\n  if (unresolved.length > 0) citedSection.push('Cited but not found in the repository:', list(unresolved), '');\n  if (unclosed.length > 0) {\n    citedSection.push('Front matter opened on line 1 and never closed, so the status was not read; close the block with `---` on a line of its own:', list(unclosed), '');\n  }\n  // The last note: the section is trimmed at its end, so no blank line follows it.\n  if (unreadableFrontMatter.length > 0) {\n    citedSection.push(\n      'Front matter lines that are not `key: value` were not read, so a status written on one, if any, was not read either:',\n      unreadableFrontMatter.map(unreadLine).join('\\n'),\n    );\n  }\n\n  return {\n    markdown: `${fixed}\\n${citedSection.join('\\n').trimEnd()}\\n`,\n    included,\n    omitted,\n    unresolved,\n    unclosedFrontMatter: unclosed,\n    unreadableFrontMatter,\n    unreadableScope,\n    unreadableProtections,\n    unreadableRulingPaths,\n  };\n}\n"]}

package/dist/document.d.ts

@@ -19,6 +19,15 @@ export interface SectionTables {
     /** 0-based index of the line after the section's last table row, or `null` when it has no table. */
     readonly tableEndLine: number | null;
 }
+/** A line of front matter spec-core's reader passes over, since it is not `key: value`. */
+export interface UnreadableFrontMatterLine {
+    /** 1-based. */
+    readonly line: number;
+    /** The line as written. */
+    readonly text: string;
+    /** spec-core's reason it was not read. */
+    readonly reason: string;
+}
 export interface DocumentReader {
     codeBlocks(text: string): CodeBlock[];
     sectionAt(text: string, line: number): string | null;
@@ -27,13 +36,17 @@ export interface DocumentReader {
     sectionTables(text: string, section: string): SectionTables;
     citations(text: string): Citation[];
     /**
-     * The first level-one heading, and the front matter's status. YAML front
+     * The first level-one heading, and the front matter's `status`. YAML front
      * matter opened on line 1 and never closed is `unclosedFrontMatter`: none
-     * of it is read, so a status its author wrote there reads as none.
+     * of it is read, so a status its author wrote there reads as none. A line
+     * of closed YAML front matter that is not `key: value` is in
+     * `unreadableFrontMatter`: it is passed over, and a status written on it
+     * with it, as `status accepted` without its colon writes one.
      */
     titleAndStatus(text: string): {
         readonly title: string | null;
         readonly status: string | null;
         readonly unclosedFrontMatter: boolean;
+        readonly unreadableFrontMatter: readonly UnreadableFrontMatterLine[];
     };
 }

package/dist/document.js.map

@@ -1 +1 @@
-{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * What the harness reads out of a brief or a cited document, through\n * spec-core's Markdown scanner so that code and comments are never mistaken\n * for structure: fenced blocks with their info strings, the section a line\n * sits in, a section's tables, the relative links a document cites, and a\n * document's title and status.\n */\n\nimport type { CodeBlock } from './probe.js';\nimport type { TableView } from './rulings.js';\n\nexport interface Citation {\n  readonly target: string;\n  /** 1-based. */\n  readonly line: number;\n}\n\nexport interface SectionTables {\n  readonly tables: readonly TableView[];\n  /** 1-based line of the section's heading, or `null` when there is no such section. */\n  readonly headingLine: number | null;\n  /** 0-based index of the line after the section's last table row, or `null` when it has no table. */\n  readonly tableEndLine: number | null;\n}\n\nexport interface DocumentReader {\n  codeBlocks(text: string): CodeBlock[];\n  sectionAt(text: string, line: number): string | null;\n  /** Every section a line sits in, outermost first: a `###` under a `##` is in both. */\n  sectionsAt(text: string, line: number): string[];\n  sectionTables(text: string, section: string): SectionTables;\n  citations(text: string): Citation[];\n  /**\n   * The first level-one heading, and the front matter's status. YAML front\n   * matter opened on line 1 and never closed is `unclosedFrontMatter`: none\n   * of it is read, so a status its author wrote there reads as none.\n   */\n  titleAndStatus(text: string): { readonly title: string | null; readonly status: string | null; readonly unclosedFrontMatter: boolean };\n}\n"]}
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * What the harness reads out of a brief or a cited document, through\n * spec-core's Markdown scanner so that code and comments are never mistaken\n * for structure: fenced blocks with their info strings, the section a line\n * sits in, a section's tables, the relative links a document cites, and a\n * document's title and status.\n */\n\nimport type { CodeBlock } from './probe.js';\nimport type { TableView } from './rulings.js';\n\nexport interface Citation {\n  readonly target: string;\n  /** 1-based. */\n  readonly line: number;\n}\n\nexport interface SectionTables {\n  readonly tables: readonly TableView[];\n  /** 1-based line of the section's heading, or `null` when there is no such section. */\n  readonly headingLine: number | null;\n  /** 0-based index of the line after the section's last table row, or `null` when it has no table. */\n  readonly tableEndLine: number | null;\n}\n\n/** A line of front matter spec-core's reader passes over, since it is not `key: value`. */\nexport interface UnreadableFrontMatterLine {\n  /** 1-based. */\n  readonly line: number;\n  /** The line as written. */\n  readonly text: string;\n  /** spec-core's reason it was not read. */\n  readonly reason: string;\n}\n\nexport interface DocumentReader {\n  codeBlocks(text: string): CodeBlock[];\n  sectionAt(text: string, line: number): string | null;\n  /** Every section a line sits in, outermost first: a `###` under a `##` is in both. */\n  sectionsAt(text: string, line: number): string[];\n  sectionTables(text: string, section: string): SectionTables;\n  citations(text: string): Citation[];\n  /**\n   * The first level-one heading, and the front matter's `status`. YAML front\n   * matter opened on line 1 and never closed is `unclosedFrontMatter`: none\n   * of it is read, so a status its author wrote there reads as none. A line\n   * of closed YAML front matter that is not `key: value` is in\n   * `unreadableFrontMatter`: it is passed over, and a status written on it\n   * with it, as `status accepted` without its colon writes one.\n   */\n  titleAndStatus(text: string): {\n    readonly title: string | null;\n    readonly status: string | null;\n    readonly unclosedFrontMatter: boolean;\n    readonly unreadableFrontMatter: readonly UnreadableFrontMatterLine[];\n  };\n}\n"]}

package/dist/formats.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Findings in the formats a forge reads beside a change: GitLab Code Quality,
+ * SARIF 2.1.0 and GitHub workflow commands (spec-core ADR-0005).
+ *
+ * The shapes are the siblings': spec-brief's severities and its hint in the
+ * text, spec-guard's fingerprint of a finding's identity. Pure: the command
+ * prints what these return.
+ */
+import type { Finding } from './types.js';
+/** The formats that place findings, which `audit` and `premises` print. */
+export type FindingFormat = 'gitlab' | 'sarif' | 'github';
+export declare const FINDING_FORMATS: readonly FindingFormat[];
+export interface FormatOptions {
+    /** Where a finding with no file of its own is placed: the brief the command is about. */
+    readonly file: string;
+    /** This tool's version, which SARIF names. */
+    readonly version: string;
+    /** What the run measured, which SARIF carries as a note beside its results. */
+    readonly summary?: string | undefined;
+}
+/** GitLab Code Quality: a JSON array of issues, which a merge request shows beside the lines they are on. */
+export declare function formatGitlab(findings: readonly Finding[], options: FormatOptions): string;
+/**
+ * SARIF 2.1.0, for code scanning. What the run measured is a note in the
+ * invocation, SARIF's place for what happened in a run that is not a finding,
+ * so a page with no result still says what was checked.
+ */
+export declare function formatSarif(findings: readonly Finding[], options: FormatOptions): string;
+/** GitHub Actions workflow commands, one line each, which a job's log turns into annotations on the diff. */
+export declare function formatGithub(findings: readonly Finding[], options: FormatOptions): string;
+export declare function formatFindings(format: FindingFormat, findings: readonly Finding[], options: FormatOptions): string;

package/dist/formats.js

@@ -0,0 +1,127 @@
+/**
+ * Findings in the formats a forge reads beside a change: GitLab Code Quality,
+ * SARIF 2.1.0 and GitHub workflow commands (spec-core ADR-0005).
+ *
+ * The shapes are the siblings': spec-brief's severities and its hint in the
+ * text, spec-guard's fingerprint of a finding's identity. Pure: the command
+ * prints what these return.
+ */
+import { createHash } from 'node:crypto';
+import { RULES } from './audit.js';
+export const FINDING_FORMATS = ['gitlab', 'sarif', 'github'];
+/**
+ * GitLab's severities. An error fails the run, but it is not the crash or the
+ * security hole `critical` and `blocker` say in GitLab's own reports, so the
+ * scale tops out at `major`, as spec-brief's does.
+ */
+const GITLAB_SEVERITY = { error: 'major', warning: 'minor', note: 'info' };
+const SARIF_LEVEL = { error: 'error', warning: 'warning', note: 'note' };
+const GITHUB_COMMAND = { error: 'error', warning: 'warning', note: 'notice' };
+/**
+ * Each finding with its place and its fingerprint. A finding about a whole
+ * brief is placed on the brief's first line. The fingerprint is the SHA-256
+ * of the finding's identity - its rule, its file and its subject - and never
+ * of its message, hint or line: GitLab tells a new finding from one it has
+ * seen by it, so a reworded message or a line added above must not read as
+ * one problem fixed and another found. Two findings with one identity are
+ * told apart by the order they come in.
+ */
+function place(findings, fallback) {
+    const seen = new Map();
+    return findings.map((finding) => {
+        const file = finding.file ?? fallback;
+        const identity = [finding.rule, file, finding.subject ?? ''].join('\u0000');
+        const repeat = seen.get(identity) ?? 0;
+        seen.set(identity, repeat + 1);
+        const fingerprint = createHash('sha256').update(repeat === 0 ? identity : `${identity}\u0000${repeat}`).digest('hex');
+        return { finding, file, line: Math.max(finding.line ?? 1, 1), fingerprint };
+    });
+}
+/**
+ * The message and the next action, which every format carries (spec-core
+ * ADR-0005). A message a sibling ended with a full stop keeps one.
+ */
+function text(finding) {
+    return `${finding.message.replace(/\.$/, '')}. ${finding.hint}`;
+}
+/** GitLab Code Quality: a JSON array of issues, which a merge request shows beside the lines they are on. */
+export function formatGitlab(findings, options) {
+    const issues = place(findings, options.file).map(({ finding, file, line, fingerprint }) => ({
+        description: text(finding),
+        check_name: finding.rule,
+        fingerprint,
+        severity: GITLAB_SEVERITY[finding.severity],
+        location: { path: file, lines: { begin: line } },
+    }));
+    return `${JSON.stringify(issues, null, 2)}\n`;
+}
+/** How SARIF describes a rule: the audit's own words, or the archive rule spec-brief gave. */
+function describeRule(id) {
+    if (id.startsWith('archive/'))
+        return `A reason spec-brief's archive gives: ${id.slice('archive/'.length)}.`;
+    return RULES[id] ?? id;
+}
+/**
+ * SARIF 2.1.0, for code scanning. What the run measured is a note in the
+ * invocation, SARIF's place for what happened in a run that is not a finding,
+ * so a page with no result still says what was checked.
+ */
+export function formatSarif(findings, options) {
+    const placed = place(findings, options.file);
+    const ids = [...new Set(findings.map((finding) => finding.rule))].sort();
+    const document = {
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                ...(options.summary === undefined
+                    ? {}
+                    : { invocations: [{ executionSuccessful: true, toolExecutionNotifications: [{ level: 'note', message: { text: options.summary } }] }] }),
+                tool: {
+                    driver: {
+                        name: 'spec-harness',
+                        version: options.version,
+                        informationUri: 'https://github.com/DescentVTT/spec-harness',
+                        rules: ids.map((id) => ({ id, shortDescription: { text: describeRule(id) } })),
+                    },
+                },
+                results: placed.map(({ finding, file, line, fingerprint }) => ({
+                    ruleId: finding.rule,
+                    level: SARIF_LEVEL[finding.severity],
+                    message: { text: text(finding) },
+                    locations: [{ physicalLocation: { artifactLocation: { uri: file, uriBaseId: '%SRCROOT%' }, region: { startLine: line } } }],
+                    partialFingerprints: { specHarnessFinding: fingerprint },
+                })),
+            },
+        ],
+    };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+/** A workflow command's message: `%`, and the line breaks that would end the command. */
+function escapeData(value) {
+    return value.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+/** A workflow command's property: as a message, and the `:` and `,` that would end the property. */
+function escapeProperty(value) {
+    return escapeData(value).replace(/:/g, '%3A').replace(/,/g, '%2C');
+}
+/** GitHub Actions workflow commands, one line each, which a job's log turns into annotations on the diff. */
+export function formatGithub(findings, options) {
+    return place(findings, options.file)
+        .map(({ finding, file, line }) => {
+        const properties = `file=${escapeProperty(file)},line=${line},title=${escapeProperty(`spec-harness ${finding.rule}`)}`;
+        return `::${GITHUB_COMMAND[finding.severity]} ${properties}::${escapeData(text(finding))}\n`;
+    })
+        .join('');
+}
+export function formatFindings(format, findings, options) {
+    switch (format) {
+        case 'gitlab':
+            return formatGitlab(findings, options);
+        case 'sarif':
+            return formatSarif(findings, options);
+        case 'github':
+            return formatGithub(findings, options);
+    }
+}
+//# sourceMappingURL=formats.js.map

package/dist/formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.js","sourceRoot":"","sources":["../src/formats.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Findings in the formats a forge reads beside a change: GitLab Code Quality,\n * SARIF 2.1.0 and GitHub workflow commands (spec-core ADR-0005).\n *\n * The shapes are the siblings': spec-brief's severities and its hint in the\n * text, spec-guard's fingerprint of a finding's identity. Pure: the command\n * prints what these return.\n */\n\nimport { createHash } from 'node:crypto';\n\nimport { RULES } from './audit.js';\nimport type { Finding, Severity } from './types.js';\n\n/** The formats that place findings, which `audit` and `premises` print. */\nexport type FindingFormat = 'gitlab' | 'sarif' | 'github';\n\nexport const FINDING_FORMATS: readonly FindingFormat[] = ['gitlab', 'sarif', 'github'];\n\nexport interface FormatOptions {\n  /** Where a finding with no file of its own is placed: the brief the command is about. */\n  readonly file: string;\n  /** This tool's version, which SARIF names. */\n  readonly version: string;\n  /** What the run measured, which SARIF carries as a note beside its results. */\n  readonly summary?: string | undefined;\n}\n\n/**\n * GitLab's severities. An error fails the run, but it is not the crash or the\n * security hole `critical` and `blocker` say in GitLab's own reports, so the\n * scale tops out at `major`, as spec-brief's does.\n */\nconst GITLAB_SEVERITY: Readonly<Record<Severity, string>> = { error: 'major', warning: 'minor', note: 'info' };\nconst SARIF_LEVEL: Readonly<Record<Severity, string>> = { error: 'error', warning: 'warning', note: 'note' };\nconst GITHUB_COMMAND: Readonly<Record<Severity, string>> = { error: 'error', warning: 'warning', note: 'notice' };\n\ninterface Placed {\n  readonly finding: Finding;\n  readonly file: string;\n  readonly line: number;\n  readonly fingerprint: string;\n}\n\n/**\n * Each finding with its place and its fingerprint. A finding about a whole\n * brief is placed on the brief's first line. The fingerprint is the SHA-256\n * of the finding's identity - its rule, its file and its subject - and never\n * of its message, hint or line: GitLab tells a new finding from one it has\n * seen by it, so a reworded message or a line added above must not read as\n * one problem fixed and another found. Two findings with one identity are\n * told apart by the order they come in.\n */\nfunction place(findings: readonly Finding[], fallback: string): Placed[] {\n  const seen = new Map<string, number>();\n  return findings.map((finding) => {\n    const file = finding.file ?? fallback;\n    const identity = [finding.rule, file, finding.subject ?? ''].join('\\u0000');\n    const repeat = seen.get(identity) ?? 0;\n    seen.set(identity, repeat + 1);\n    const fingerprint = createHash('sha256').update(repeat === 0 ? identity : `${identity}\\u0000${repeat}`).digest('hex');\n    return { finding, file, line: Math.max(finding.line ?? 1, 1), fingerprint };\n  });\n}\n\n/**\n * The message and the next action, which every format carries (spec-core\n * ADR-0005). A message a sibling ended with a full stop keeps one.\n */\nfunction text(finding: Finding): string {\n  return `${finding.message.replace(/\\.$/, '')}. ${finding.hint}`;\n}\n\n/** GitLab Code Quality: a JSON array of issues, which a merge request shows beside the lines they are on. */\nexport function formatGitlab(findings: readonly Finding[], options: FormatOptions): string {\n  const issues = place(findings, options.file).map(({ finding, file, line, fingerprint }) => ({\n    description: text(finding),\n    check_name: finding.rule,\n    fingerprint,\n    severity: GITLAB_SEVERITY[finding.severity],\n    location: { path: file, lines: { begin: line } },\n  }));\n  return `${JSON.stringify(issues, null, 2)}\\n`;\n}\n\n/** How SARIF describes a rule: the audit's own words, or the archive rule spec-brief gave. */\nfunction describeRule(id: string): string {\n  if (id.startsWith('archive/')) return `A reason spec-brief's archive gives: ${id.slice('archive/'.length)}.`;\n  return RULES[id] ?? id;\n}\n\n/**\n * SARIF 2.1.0, for code scanning. What the run measured is a note in the\n * invocation, SARIF's place for what happened in a run that is not a finding,\n * so a page with no result still says what was checked.\n */\nexport function formatSarif(findings: readonly Finding[], options: FormatOptions): string {\n  const placed = place(findings, options.file);\n  const ids = [...new Set(findings.map((finding) => finding.rule))].sort();\n  const document = {\n    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',\n    version: '2.1.0',\n    runs: [\n      {\n        ...(options.summary === undefined\n          ? {}\n          : { invocations: [{ executionSuccessful: true, toolExecutionNotifications: [{ level: 'note', message: { text: options.summary } }] }] }),\n        tool: {\n          driver: {\n            name: 'spec-harness',\n            version: options.version,\n            informationUri: 'https://github.com/DescentVTT/spec-harness',\n            rules: ids.map((id) => ({ id, shortDescription: { text: describeRule(id) } })),\n          },\n        },\n        results: placed.map(({ finding, file, line, fingerprint }) => ({\n          ruleId: finding.rule,\n          level: SARIF_LEVEL[finding.severity],\n          message: { text: text(finding) },\n          locations: [{ physicalLocation: { artifactLocation: { uri: file, uriBaseId: '%SRCROOT%' }, region: { startLine: line } } }],\n          partialFingerprints: { specHarnessFinding: fingerprint },\n        })),\n      },\n    ],\n  };\n  return `${JSON.stringify(document, null, 2)}\\n`;\n}\n\n/** A workflow command's message: `%`, and the line breaks that would end the command. */\nfunction escapeData(value: string): string {\n  return value.replace(/%/g, '%25').replace(/\\r/g, '%0D').replace(/\\n/g, '%0A');\n}\n\n/** A workflow command's property: as a message, and the `:` and `,` that would end the property. */\nfunction escapeProperty(value: string): string {\n  return escapeData(value).replace(/:/g, '%3A').replace(/,/g, '%2C');\n}\n\n/** GitHub Actions workflow commands, one line each, which a job's log turns into annotations on the diff. */\nexport function formatGithub(findings: readonly Finding[], options: FormatOptions): string {\n  return place(findings, options.file)\n    .map(({ finding, file, line }) => {\n      const properties = `file=${escapeProperty(file)},line=${line},title=${escapeProperty(`spec-harness ${finding.rule}`)}`;\n      return `::${GITHUB_COMMAND[finding.severity]} ${properties}::${escapeData(text(finding))}\\n`;\n    })\n    .join('');\n}\n\nexport function formatFindings(format: FindingFormat, findings: readonly Finding[], options: FormatOptions): string {\n  switch (format) {\n    case 'gitlab':\n      return formatGitlab(findings, options);\n    case 'sarif':\n      return formatSarif(findings, options);\n    case 'github':\n      return formatGithub(findings, options);\n  }\n}\n"]}

package/dist/git.d.ts

@@ -21,6 +21,12 @@ export declare class GitError extends Error {
 export declare function workTreeRoot(cwd: string): Promise<string | null>;
 /** The git directory every worktree of this repository shares. */
 export declare function commonDirectory(cwd: string): Promise<string | null>;
+/**
+ * Where git runs the hook `name` from, absolute: `core.hooksPath` read as git
+ * reads it - relative to the work tree, absolute, or under `~` - and a linked
+ * worktree's shared hooks. `null` when git cannot say, before 2.31.
+ */
+export declare function hookPath(name: string, cwd: string): Promise<string | null>;
 /** The checked-out branch's short name, or `null` on a detached head. */
 export declare function currentBranch(cwd: string): Promise<string | null>;
 /** The remote's default branch as a local ref, such as `origin/main`, or `null`. */

package/dist/git.js

@@ -36,6 +36,14 @@ export async function workTreeRoot(cwd) {
 export async function commonDirectory(cwd) {
     return value(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
 }
+/**
+ * Where git runs the hook `name` from, absolute: `core.hooksPath` read as git
+ * reads it - relative to the work tree, absolute, or under `~` - and a linked
+ * worktree's shared hooks. `null` when git cannot say, before 2.31.
+ */
+export async function hookPath(name, cwd) {
+    return value(['rev-parse', '--path-format=absolute', '--git-path', `hooks/${name}`], cwd);
+}
 /** The checked-out branch's short name, or `null` on a detached head. */
 export async function currentBranch(cwd) {
     return value(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd);