dsh-permission-rules 0.3.0 → 0.4.1

package/src/config.ts

@@ -64,6 +64,17 @@ export interface Config {
    * policy in production before enforcing it.
    */
   enforce?: boolean
+  /**
+   * Whether to keep appending audit events to the session log on hosts
+   * whose `Session.append` predates the `ignorable` envelope marker
+   * (the `0.1.0-rc.6` line). Defaults to `false`: such hosts write the
+   * events UNMARKED, which makes the session unresumable on stricter
+   * hosts, so the runtime detects the host and disables session-log audit
+   * with a one-time warning instead. Set `true` to opt back into the
+   * in-session audit trail (and accept that those sessions may need
+   * `scripts/repair-session-logs.mjs` before loading on a newer harness).
+   */
+  allowUnmarkedAudit?: boolean
 }
 
 /** Config after {@link resolveConfig}: every optional field has its explicit default. */
@@ -82,6 +93,7 @@ export interface ResolvedConfig {
   readonly searchUp: boolean
   readonly maxGlobStars: number
   readonly enforce: boolean
+  readonly allowUnmarkedAudit: boolean
 }
 
 /** Schemastery schema: the loader validates and fills defaults before `apply`. */
@@ -100,6 +112,7 @@ export const Config: z<Config> = z.object({
   searchUp: z.boolean().default(false),
   maxGlobStars: z.number().default(2),
   enforce: z.boolean().default(true),
+  allowUnmarkedAudit: z.boolean().default(false),
 })
 
 /**
@@ -142,6 +155,7 @@ export function resolveConfig(config: Config = {}): ResolvedConfig {
   assertBoolean('searchUp', searchUp)
   assertBoolean('caseInsensitivePaths', config.caseInsensitivePaths ?? process.platform === 'win32')
   assertBoolean('enforce', config.enforce ?? true)
+  assertBoolean('allowUnmarkedAudit', config.allowUnmarkedAudit ?? false)
   return {
     rulesFile,
     fallbackPath: config.fallbackPath,
@@ -157,6 +171,7 @@ export function resolveConfig(config: Config = {}): ResolvedConfig {
     searchUp,
     maxGlobStars,
     enforce: config.enforce ?? true,
+    allowUnmarkedAudit: config.allowUnmarkedAudit ?? false,
   }
 }
 

package/src/events.ts

@@ -17,9 +17,16 @@
  * downstream — an auditable "what would the policy have done" trail.
  *
  * The event is appended with the envelope's `ignorable: true` marker (see
- * {@link AuditAppend}), so a harness build whose generated event vocabulary
- * does not include this out-of-repo type still loads the log — it skips the
- * audit record instead of refusing the whole session.
+ * {@link AuditAppend}). Harness builds that honor the marker (post-rc.6)
+ * stamp it on the envelope and skip unknown ignorable records when loading,
+ * so the audit can never refuse a session. Builds whose `Session.append`
+ * predates the marker — the `0.1.0-rc.6` line — silently DROP the options
+ * bag: the event then lands UNMARKED and makes the session unresumable on
+ * hosts with required-on-read semantics (`SessionFormatUnsupportedError`).
+ * The runtime detects this at first use (peer version pre-check plus a
+ * probe of the appended envelope) and disables session-log audit on such
+ * hosts with a one-time warning; `allowUnmarkedAudit: true` opts back in,
+ * and `scripts/repair-session-logs.mjs` repairs already-polluted logs.
  * @module dsh-permission-rules/events
  */
 
@@ -77,12 +84,27 @@ export interface AuditDecision {
 /**
  * `Session.append` narrowed to this plugin's audit event. The options bag
  * exists only on host builds that expose the `ignorable` envelope-marker
- * surface (post-rc.6 `@deepseek-ai/dsh-session`); an rc.6 host accepts and
- * ignores the third argument, appending the identical event without the
- * marker — no behavior change, no failure either way.
+ * surface (post-rc.6 `@deepseek-ai/dsh-session`); an rc.6 host accepts the
+ * call but silently drops the third argument — the event is appended
+ * WITHOUT the marker, which is exactly what breaks later resume on stricter
+ * hosts. The runtime treats the marker as optional-but-probed: see
+ * {@link isMarkedAuditEvent}.
  */
 export type AuditAppend = (
   type: 'permissionRules/decision',
   data: AuditDecision,
   options?: { ignorable?: true },
 ) => unknown
+
+/**
+ * Whether an `append` call actually honored the `ignorable` marker: the
+ * logged event returned by the host carries `ignorable === true` on
+ * marker-aware builds and nothing on pre-marker builds. `false` (or any
+ * non-event return) means the host dropped the marker and the event landed
+ * unmarked — the runtime then degrades instead of polluting further logs.
+ * @param result - the return value of the audit append.
+ * @returns true only when the marker is present on the returned envelope.
+ */
+export function isMarkedAuditEvent(result: unknown): boolean {
+  return typeof result === 'object' && result !== null && (result as { ignorable?: unknown }).ignorable === true
+}

package/src/index.ts

@@ -22,7 +22,7 @@ export const name = 'permission-rules'
 export const inject = ['commands', 'tools']
 
 export { apply }
-export { PermissionRulesRuntime } from './runtime.ts'
+export { PermissionRulesRuntime, isUnmarkedHostVersion } from './runtime.ts'
 export * from './config.ts'
 export * from './events.ts'
 export * from './rules.ts'

package/src/prose.ts

@@ -34,6 +34,8 @@ export interface UiProse {
   decisionsHeader: (shown: number, total: number) => string
   /** Line shown when the session log holds no audit decisions. */
   noDecisions: string
+  /** Notice appended to `/rules decisions` when session-log audit is disabled on this host (ignorable marker not honored). */
+  auditDisabledNotice: string
   /** Rejection of a malformed decisions count. */
   invalidDecisionsCount: (arg: string) => string
   /** One audit-decision row (dry-run rows mark the actual outcome). */
@@ -48,6 +50,8 @@ export interface UiProse {
   testUnknownFlag: (flag: string) => string
   /** Rejection of a malformed `/rules test` flag (missing value, bad KEY=VALUE). */
   testBadFlag: (flag: string) => string
+  /** Rejection of an unknown `--platform` value. */
+  testBadPlatform: (value: string) => string
   /** Usage hint of `/rules test`. */
   testUsage: string
   /** Warning naming shadowed (unreachable) rules by 1-based number. */
@@ -68,6 +72,8 @@ export interface DescribeTokens {
   platform: string
   disabled: string
   tags: string
+  /** Prefix of the per-rule source-file attribution. */
+  src: string
 }
 
 /** Truncate long reasons/descriptions in one-line displays. */
@@ -84,9 +90,10 @@ const EN: UiProse = {
   lastReloadWarning: error => `Warning: the last reload failed (${error}); the rules listed above are the previous ones.`,
   dryRunNotice: 'Dry-run mode (enforce: false): deny/ask hits are audit-logged only — every call is passed through.',
   unknownArg: arg => `Unknown /rules argument "${arg}". ${EN.usage}`,
-  usage: 'Usage: /rules [reload | decisions [n] | test <tool> <json-args>]',
+  usage: 'Usage: /rules [list | reload | decisions [n] | test <tool> <json-args>]',
   decisionsHeader: (shown, total) => `Last ${shown} of ${total} permission decision(s) for this session:`,
   noDecisions: 'No permission decisions recorded in this session yet.',
+  auditDisabledNotice: 'Session-log audit is disabled on this host: its Session.append predates the ignorable marker and would make sessions unresumable elsewhere (set allowUnmarkedAudit: true to opt back in).',
   invalidDecisionsCount: arg => `Invalid decisions count "${arg}": give a positive integer (default 10).`,
   decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : ` (rule ${ruleIndex + 1})`
@@ -99,7 +106,8 @@ const EN: UiProse = {
   testBadJson: text => `Invalid JSON arguments "${text}": the arguments must parse as JSON.`,
   testUnknownFlag: flag => `Unknown /rules test flag "${flag}". ${EN.testUsage}`,
   testBadFlag: flag => `Invalid /rules test flag "${flag}": expected a value. ${EN.testUsage}`,
-  testUsage: 'Usage: /rules test [--cwd <dir>] [--env KEY=VALUE]... [--agent <selector>]... <tool> <json-args>, e.g. /rules test bash {"command":"git push origin main"}',
+  testBadPlatform: value => `Unknown platform "${value}" in --platform: expected one of aix, android, darwin, freebsd, linux, openbsd, sunos, win32. ${EN.testUsage}`,
+  testUsage: 'Usage: /rules test [--cwd <dir>] [--env KEY=VALUE]... [--agent <selector>]... [--platform <name>] <tool> <json-args>, e.g. /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `Warning: rule${numbers.length > 1 ? 's' : ''} ${numbers.join(', ')} ${numbers.length > 1 ? 'are' : 'is'} unreachable (shadowed by an earlier catch-all rule).`,
   emptySource: '(no rule file — empty rule set)',
 }
@@ -113,9 +121,10 @@ const ZH: UiProse = {
   lastReloadWarning: error => `警告：上次重载失败（${error}）；以上列出的是之前的规则。`,
   dryRunNotice: '干跑模式（enforce: false）：deny/ask 命中仅写入审计日志——所有调用照常透传。',
   unknownArg: arg => `未知的 /rules 参数 "${arg}"。${ZH.usage}`,
-  usage: '用法：/rules [reload | decisions [n] | test <工具名> <json-参数>]',
+  usage: '用法：/rules [list | reload | decisions [n] | test <工具名> <json-参数>]',
   decisionsHeader: (shown, total) => `本会话最近 ${shown}/${total} 条权限裁决：`,
   noDecisions: '本会话还没有记录任何权限裁决。',
+  auditDisabledNotice: '本宿主上会话日志审计已停用：其 Session.append 早于 ignorable 标记支持，会令会话在其他宿主上无法恢复（设 allowUnmarkedAudit: true 可重新开启）。',
   invalidDecisionsCount: arg => `无效的裁决条数 "${arg}"：请给正整数（默认 10）。`,
   decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : `（规则 ${ruleIndex + 1}）`
@@ -128,7 +137,8 @@ const ZH: UiProse = {
   testBadJson: text => `无效的 JSON 参数 "${text}"：参数必须能被解析为 JSON。`,
   testUnknownFlag: flag => `未知的 /rules test 标志 "${flag}"。${ZH.testUsage}`,
   testBadFlag: flag => `无效的 /rules test 标志 "${flag}"：缺少取值。${ZH.testUsage}`,
-  testUsage: '用法：/rules test [--cwd <目录>] [--env 键=值]... [--agent <选择器>]... <工具名> <json-参数>，例如 /rules test bash {"command":"git push origin main"}',
+  testBadPlatform: value => `未知的平台 "${value}"（--platform）：应为 aix、android、darwin、freebsd、linux、openbsd、sunos、win32 之一。${ZH.testUsage}`,
+  testUsage: '用法：/rules test [--cwd <目录>] [--env 键=值]... [--agent <选择器>]... [--platform <平台名>] <工具名> <json-参数>，例如 /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `警告：规则 ${numbers.join('、')} 不可达（被前面的通配规则遮蔽）。`,
   emptySource: '（无规则文件——空规则集）',
 }
@@ -142,9 +152,10 @@ const ES: UiProse = {
   lastReloadWarning: error => `Aviso: la última recarga falló (${error}); las reglas mostradas son las anteriores.`,
   dryRunNotice: 'Modo simulación (enforce: false): los aciertos deny/ask solo se registran en auditoría — todas las llamadas pasan.',
   unknownArg: arg => `Argumento de /rules desconocido "${arg}". ${ES.usage}`,
-  usage: 'Uso: /rules [reload | decisions [n] | test <herramienta> <json-args>]',
+  usage: 'Uso: /rules [list | reload | decisions [n] | test <herramienta> <json-args>]',
   decisionsHeader: (shown, total) => `Últimas ${shown} de ${total} decisión(es) de permiso de esta sesión:`,
   noDecisions: 'Esta sesión aún no registra decisiones de permiso.',
+  auditDisabledNotice: 'La auditoría del registro de sesión está desactivada en este host: su Session.append es anterior al marcador ignorable y haría las sesiones irrecuperables en otros hosts (establece allowUnmarkedAudit: true para reactivarla).',
   invalidDecisionsCount: arg => `Cantidad de decisiones inválida "${arg}": indique un entero positivo (por defecto 10).`,
   decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : ` (regla ${ruleIndex + 1})`
@@ -157,7 +168,8 @@ const ES: UiProse = {
   testBadJson: text => `Argumentos JSON inválidos "${text}": los argumentos deben poderse analizar como JSON.`,
   testUnknownFlag: flag => `Bandera de /rules test desconocida "${flag}". ${ES.testUsage}`,
   testBadFlag: flag => `Bandera de /rules test inválida "${flag}": falta un valor. ${ES.testUsage}`,
-  testUsage: 'Uso: /rules test [--cwd <dir>] [--env CLAVE=VALOR]... [--agent <selector>]... <herramienta> <json-args>, p. ej. /rules test bash {"command":"git push origin main"}',
+  testBadPlatform: value => `Plataforma desconocida "${value}" en --platform: se esperaba una de aix, android, darwin, freebsd, linux, openbsd, sunos, win32. ${ES.testUsage}`,
+  testUsage: 'Uso: /rules test [--cwd <dir>] [--env CLAVE=VALOR]... [--agent <selector>]... [--platform <nombre>] <herramienta> <json-args>, p. ej. /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `Aviso: ${numbers.length > 1 ? 'las reglas' : 'la regla'} ${numbers.join(', ')} ${numbers.length > 1 ? 'son inalcanzables' : 'es inalcanzable'} (tapada por una regla general anterior).`,
   emptySource: '(sin archivo de reglas — conjunto vacío)',
 }
@@ -171,9 +183,10 @@ const PT: UiProse = {
   lastReloadWarning: error => `Aviso: a última recarga falhou (${error}); as regras listadas são as anteriores.`,
   dryRunNotice: 'Modo simulação (enforce: false): acertos deny/ask são apenas registrados na auditoria — todas as chamadas passam.',
   unknownArg: arg => `Argumento de /rules desconhecido "${arg}". ${PT.usage}`,
-  usage: 'Uso: /rules [reload | decisions [n] | test <ferramenta> <json-args>]',
+  usage: 'Uso: /rules [list | reload | decisions [n] | test <ferramenta> <json-args>]',
   decisionsHeader: (shown, total) => `Últimas ${shown} de ${total} decisão(ões) de permissão desta sessão:`,
   noDecisions: 'Esta sessão ainda não registrou decisões de permissão.',
+  auditDisabledNotice: 'A auditoria do registro da sessão está desativada neste host: seu Session.append é anterior ao marcador ignorable e tornaria as sessões irrecuperáveis em outros hosts (defina allowUnmarkedAudit: true para reativar).',
   invalidDecisionsCount: arg => `Quantidade de decisões inválida "${arg}": informe um inteiro positivo (padrão 10).`,
   decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : ` (regra ${ruleIndex + 1})`
@@ -186,7 +199,8 @@ const PT: UiProse = {
   testBadJson: text => `Argumentos JSON inválidos "${text}": os argumentos precisam ser JSON analisável.`,
   testUnknownFlag: flag => `Sinalizador de /rules test desconhecido "${flag}". ${PT.testUsage}`,
   testBadFlag: flag => `Sinalizador de /rules test inválido "${flag}": falta um valor. ${PT.testUsage}`,
-  testUsage: 'Uso: /rules test [--cwd <dir>] [--env CHAVE=VALOR]... [--agent <seletor>]... <ferramenta> <json-args>, ex.: /rules test bash {"command":"git push origin main"}',
+  testBadPlatform: value => `Plataforma desconhecida "${value}" em --platform: esperava-se uma de aix, android, darwin, freebsd, linux, openbsd, sunos, win32. ${PT.testUsage}`,
+  testUsage: 'Uso: /rules test [--cwd <dir>] [--env CHAVE=VALOR]... [--agent <seletor>]... [--platform <nome>] <ferramenta> <json-args>, ex.: /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `Aviso: ${numbers.length > 1 ? 'as regras' : 'a regra'} ${numbers.join(', ')} ${numbers.length > 1 ? 'são inalcançáveis' : 'é inalcançável'} (encoberta por uma regra geral anterior).`,
   emptySource: '(sem arquivo de regras — conjunto vazio)',
 }
@@ -200,9 +214,10 @@ const HI: UiProse = {
   lastReloadWarning: error => `चेतावनी: अंतिम पुनः लोड विफल रहा (${error}); ऊपर सूचीबद्ध नियम पिछले वाले हैं।`,
   dryRunNotice: 'ड्राई-रन मोड (enforce: false): deny/ask हिट केवल ऑडिट में दर्ज होते हैं — हर कॉल पास हो जाती है।',
   unknownArg: arg => `अज्ञात /rules तर्क "${arg}"। ${HI.usage}`,
-  usage: 'उपयोग: /rules [reload | decisions [n] | test <टूल> <json-args>]',
+  usage: 'उपयोग: /rules [list | reload | decisions [n] | test <टूल> <json-args>]',
   decisionsHeader: (shown, total) => `इस सत्र के अंतिम ${shown}/${total} अनुमति निर्णय:`,
   noDecisions: 'इस सत्र में अभी कोई अनुमति निर्णय दर्ज नहीं है।',
+  auditDisabledNotice: 'इस होस्ट पर सत्र-लॉग ऑडिट अक्षम है: इसका Session.append ignorable मार्कर से पुराना है और सत्र अन्य होस्ट पर अप्राप्य बन जाते (पुनः चालू करने के लिए allowUnmarkedAudit: true सेट करें)।',
   invalidDecisionsCount: arg => `अमान्य निर्णय-संख्या "${arg}": एक धनात्मक पूर्णांक दें (डिफ़ॉल्ट 10)।`,
   decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : ` (नियम ${ruleIndex + 1})`
@@ -215,7 +230,8 @@ const HI: UiProse = {
   testBadJson: text => `अमान्य JSON तर्क "${text}": तर्क JSON के रूप में पार्स होने चाहिए।`,
   testUnknownFlag: flag => `अज्ञात /rules test फ़्लैग "${flag}"। ${HI.testUsage}`,
   testBadFlag: flag => `अमान्य /rules test फ़्लैग "${flag}": मान गायब है। ${HI.testUsage}`,
-  testUsage: 'उपयोग: /rules test [--cwd <dir>] [--env KEY=मान]... [--agent <चयनकर्ता>]... <टूल> <json-args>, जैसे /rules test bash {"command":"git push origin main"}',
+  testBadPlatform: value => `अज्ञात प्लेटफ़ॉर्म "${value}" (--platform): aix, android, darwin, freebsd, linux, openbsd, sunos, win32 में से एक अपेक्षित। ${HI.testUsage}`,
+  testUsage: 'उपयोग: /rules test [--cwd <dir>] [--env KEY=मान]... [--agent <चयनकर्ता>]... [--platform <नाम>] <टूल> <json-args>, जैसे /rules test bash {"command":"git push origin main"}',
   unreachableWarning: numbers => `चेतावनी: नियम ${numbers.join(', ')} अप्राप्य हैं (पहले वाले सर्व-मिलान नियम से ढके हुए)।`,
   emptySource: '(कोई नियम फ़ाइल नहीं — खाली नियम-समूह)',
 }
@@ -225,9 +241,9 @@ export const UI_PROSE: Readonly<Record<UiLanguage, UiProse>> = { en: EN, zh: ZH,
 
 /** `describeRule` match-dimension tokens by language. */
 export const DESCRIBE_TOKENS: Readonly<Record<UiLanguage, DescribeTokens>> = {
-  en: { allTools: 'all tools', tools: 'tools', agents: 'agents', params: 'params', paths: 'paths', absent: 'absent', when: 'when', platform: 'platform', disabled: 'disabled', tags: 'tags' },
-  zh: { allTools: '全部工具', tools: '工具', agents: '代理', params: '参数', paths: '路径', absent: '缺省键', when: '条件', platform: '平台', disabled: '已禁用', tags: '标签' },
-  es: { allTools: 'todas las herramientas', tools: 'herramientas', agents: 'agentes', params: 'parámetros', paths: 'rutas', absent: 'ausentes', when: 'cuándo', platform: 'plataforma', disabled: 'deshabilitada', tags: 'etiquetas' },
-  pt: { allTools: 'todas as ferramentas', tools: 'ferramentas', agents: 'agentes', params: 'parâmetros', paths: 'caminhos', absent: 'ausentes', when: 'quando', platform: 'plataforma', disabled: 'desativada', tags: 'etiquetas' },
-  hi: { allTools: 'सभी टूल', tools: 'टूल', agents: 'एजेंट', params: 'पैरामीटर', paths: 'पथ', absent: 'अनुपस्थित', when: 'शर्त', platform: 'प्लेटफ़ॉर्म', disabled: 'अक्षम', tags: 'टैग' },
+  en: { allTools: 'all tools', tools: 'tools', agents: 'agents', params: 'params', paths: 'paths', absent: 'absent', when: 'when', platform: 'platform', disabled: 'disabled', tags: 'tags', src: 'src' },
+  zh: { allTools: '全部工具', tools: '工具', agents: '代理', params: '参数', paths: '路径', absent: '缺省键', when: '条件', platform: '平台', disabled: '已禁用', tags: '标签', src: '来源' },
+  es: { allTools: 'todas las herramientas', tools: 'herramientas', agents: 'agentes', params: 'parámetros', paths: 'rutas', absent: 'ausentes', when: 'cuándo', platform: 'plataforma', disabled: 'deshabilitada', tags: 'etiquetas', src: 'origen' },
+  pt: { allTools: 'todas as ferramentas', tools: 'ferramentas', agents: 'agentes', params: 'parâmetros', paths: 'caminhos', absent: 'ausentes', when: 'quando', platform: 'plataforma', disabled: 'desativada', tags: 'etiquetas', src: 'origem' },
+  hi: { allTools: 'सभी टूल', tools: 'टूल', agents: 'एजेंट', params: 'पैरामीटर', paths: 'पथ', absent: 'अनुपस्थित', when: 'शर्त', platform: 'प्लेटफ़ॉर्म', disabled: 'अक्षम', tags: 'टैग', src: 'स्रोत' },
 }

package/src/rules.ts

@@ -321,12 +321,16 @@ function isCatchAll(rule: CompiledRule): boolean {
 /**
  * One-line human summary of a compiled rule, for `/rules` output. The
  * 1-based number, action, match dimensions, and reason render first; a
- * disabled marker, tags, and a truncated description follow.
+ * disabled marker, tags, and a truncated description follow. When `source`
+ * is provided (multi-file chains), the rule's origin file is attributed on
+ * the line.
  * @param rule - the compiled rule.
  * @param tokens - dimension-prefix vocabulary for the configured language.
+ * @param source - display path of the rule's source file, when the listing
+ *   spans several files.
  * @returns a single display line.
  */
-export function describeRule(rule: CompiledRule, tokens: DescribeTokens): string {
+export function describeRule(rule: CompiledRule, tokens: DescribeTokens, source?: string): string {
   const parts: string[] = []
   if (rule.source.match.tools.length > 0) parts.push(`${tokens.tools}:${rule.source.match.tools.join(',')}`)
   if (rule.source.match.agents.length > 0) parts.push(`${tokens.agents}:${rule.source.match.agents.join(',')}`)
@@ -343,9 +347,10 @@ export function describeRule(rule: CompiledRule, tokens: DescribeTokens): string
   if (whenParts.length > 0 || platformPart.length > 0) parts.push(`${tokens.when}:${whenParts}${whenParts.length > 0 && platformPart.length > 0 ? ' ' : ''}${platformPart}`)
   const match = parts.length > 0 ? `[${parts.join(' ')}]` : `[${tokens.allTools}]`
   const disabled = rule.enabled ? '' : ` (${tokens.disabled})`
+  const sourcePart = source !== undefined && source.length > 0 ? ` [${tokens.src}:${source}]` : ''
   const description = rule.description !== undefined ? ` (${truncate(rule.description, DISPLAY_TRUNCATE)})` : ''
   const tags = rule.tags.length > 0 ? ` [${tokens.tags}:${rule.tags.join(',')}]` : ''
-  return `${rule.index + 1}. ${rule.action}${disabled} ${match}: ${truncate(rule.reason, DISPLAY_TRUNCATE)}${description}${tags}`
+  return `${rule.index + 1}. ${rule.action}${disabled} ${match}${sourcePart}: ${truncate(rule.reason, DISPLAY_TRUNCATE)}${description}${tags}`
 }
 
 /** The localized dimension-prefix vocabulary {@link describeRule} renders. */
@@ -360,6 +365,8 @@ export interface DescribeTokens {
   readonly platform: string
   readonly disabled: string
   readonly tags: string
+  /** Prefix of the per-rule source-file attribution. */
+  readonly src: string
 }
 
 /** Cut a display string at `limit` characters, marking truncation with `…`. */