@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/lib/language.mjs

@@ -7,122 +7,125 @@
 // decomposed spelling (base letter + combining mark) is caught exactly like the precomposed one, and a loanword such as
 // `naive`, `facade` or `Muller` (no tone mark, no Vietnamese letter) is never a hit.
 import path from 'node:path';
-
 /** One Vietnamese letter, precomposed (NFC): the Vietnamese-specific base letters, tone-marked vowels and the Latin Extended Additional block. */
 export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìíò-õùúýĂăĐđĨĩŨũƠơƯưẠ-ỿ]/;
-
 /** Whether `text` holds a Vietnamese letter, in NFC or NFD spelling. */
 export const hasSecondLanguage = (text) => typeof text === 'string' && SECOND_LANGUAGE_LETTER.test(text.normalize('NFC'));
-
 /** Every line of `text` with a Vietnamese letter: `[{ line, column }]`, both 1-based. */
 function secondLanguageHits(text) {
-  const hits = [];
-  String(text).split(/\r?\n/).forEach((raw, index) => {
-    const match = SECOND_LANGUAGE_LETTER.exec(raw.normalize('NFC'));
-    if (match) hits.push({ line: index + 1, column: match.index + 1 });
-  });
-  return hits;
+    const hits = [];
+    String(text).split(/\r?\n/).forEach((raw, index) => {
+        const match = SECOND_LANGUAGE_LETTER.exec(raw.normalize('NFC'));
+        if (match)
+            hits.push({ line: index + 1, column: match.index + 1 });
+    });
+    return hits;
 }
-
 /** The named bindings of an import from the backend message catalog contract. */
 function messageCatalogBindings(ts, statement) {
-  if (!ts.isImportDeclaration(statement) || statement.moduleSpecifier.text !== '@modules/platform/i18n') return null;
-  return statement.importClause?.namedBindings ?? null;
+    if (!ts.isImportDeclaration(statement) || statement.moduleSpecifier.text !== '@modules/platform/i18n')
+        return null;
+    return statement.importClause?.namedBindings ?? null;
 }
-
 /** The local type names imported from the backend message catalog contract. */
 function messageBundleImports(ts, source) {
-  const named = new Set();
-  const namespaces = new Set();
-  for (const statement of source.statements) {
-    const bindings = messageCatalogBindings(ts, statement);
-    if (!bindings) continue;
-    if (ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
-    for (const entry of ts.isNamedImports(bindings) ? bindings.elements : []) {
-      if ((entry.propertyName ?? entry.name).text === 'MessageBundle') named.add(entry.name.text);
+    const named = new Set();
+    const namespaces = new Set();
+    for (const statement of source.statements) {
+        const bindings = messageCatalogBindings(ts, statement);
+        if (!bindings)
+            continue;
+        if (ts.isNamespaceImport(bindings))
+            namespaces.add(bindings.name.text);
+        for (const entry of ts.isNamedImports(bindings) ? bindings.elements : []) {
+            if ((entry.propertyName ?? entry.name).text === 'MessageBundle')
+                named.add(entry.name.text);
+        }
     }
-  }
-  return { named, namespaces };
+    return { named, namespaces };
 }
-
 /** A declaration that introduces a same-named local type or namespace. */
 function declaresTypeName(ts, statement, name) {
-  if (statement.name?.text !== name) return false;
-  return [ts.isTypeAliasDeclaration, ts.isInterfaceDeclaration, ts.isClassDeclaration, ts.isEnumDeclaration, ts.isModuleDeclaration]
-    .some(predicate => predicate(statement));
+    if (statement.name?.text !== name)
+        return false;
+    return [ts.isTypeAliasDeclaration, ts.isInterfaceDeclaration, ts.isClassDeclaration, ts.isEnumDeclaration, ts.isModuleDeclaration]
+        .some(predicate => predicate(statement));
 }
-
 /** A type reference bound to the imported MessageBundle contract, including import aliases. */
 function isMessageBundleType(ts, type, imports) {
-  if (!type || !ts.isTypeReferenceNode(type)) return false;
-  const name = type.typeName;
-  if (ts.isIdentifier(name)) return imports.named.has(name.text) && !shadowsImportedType(ts, type, name.text);
-  return ts.isQualifiedName(name) && ts.isIdentifier(name.left)
-    && imports.namespaces.has(name.left.text) && name.right.text === 'MessageBundle' && !shadowsImportedType(ts, type, name.left.text);
+    if (!type || !ts.isTypeReferenceNode(type))
+        return false;
+    const name = type.typeName;
+    if (ts.isIdentifier(name))
+        return imports.named.has(name.text) && !shadowsImportedType(ts, type, name.text);
+    return ts.isQualifiedName(name) && ts.isIdentifier(name.left)
+        && imports.namespaces.has(name.left.text) && name.right.text === 'MessageBundle' && !shadowsImportedType(ts, type, name.left.text);
 }
-
 /** A local declaration or generic type parameter takes precedence over a same-named import. */
 function shadowsImportedType(ts, node, name) {
-  for (let scope = node.parent; scope; scope = scope.parent) {
-    if (scope.typeParameters?.some(parameter => parameter.name.text === name)) return true;
-    if (scope.statements?.some(statement => declaresTypeName(ts, statement, name))) return true;
-  }
-  return false;
+    for (let scope = node.parent; scope; scope = scope.parent) {
+        const scoped = scope;
+        if (scoped.typeParameters?.some(parameter => parameter.name.text === name))
+            return true;
+        if (scoped.statements?.some(statement => declaresTypeName(ts, statement, name)))
+            return true;
+    }
+    return false;
 }
-
 /** The literal object supplied by a variable typed with the imported MessageBundle contract. */
 function messageCatalogObject(ts, node, imports) {
-  if (!ts.isVariableDeclaration(node) || !node.initializer) return null;
-  let value = node.initializer;
-  const type = ts.isSatisfiesExpression(value) ? value.type : node.type;
-  if (ts.isSatisfiesExpression(value)) value = value.expression;
-  return isMessageBundleType(ts, type, imports) && ts.isObjectLiteralExpression(value) ? value : null;
+    if (!ts.isVariableDeclaration(node) || !node.initializer)
+        return null;
+    let value = node.initializer;
+    const type = ts.isSatisfiesExpression(value) ? value.type : node.type;
+    if (ts.isSatisfiesExpression(value))
+        value = value.expression;
+    return isMessageBundleType(ts, type, imports) && ts.isObjectLiteralExpression(value) ? value : null;
 }
-
 /** Literal string values in the Vietnamese locale of one message catalog. */
 function vietnameseValueRanges(ts, catalog, source) {
-  const ranges = [];
-  for (const locale of catalog.properties) {
-    if (!ts.isPropertyAssignment(locale) || locale.name.text !== 'vi' || !ts.isObjectLiteralExpression(locale.initializer)) continue;
-    for (const message of locale.initializer.properties) {
-      if (ts.isPropertyAssignment(message) && ts.isStringLiteralLike(message.initializer))
-        ranges.push({ start: message.initializer.getStart(source), end: message.initializer.end });
+    const ranges = [];
+    for (const locale of catalog.properties) {
+        if (!ts.isPropertyAssignment(locale) || locale.name.text !== 'vi' || !ts.isObjectLiteralExpression(locale.initializer))
+            continue;
+        for (const message of locale.initializer.properties) {
+            if (ts.isPropertyAssignment(message) && ts.isStringLiteralLike(message.initializer))
+                ranges.push({ start: message.initializer.getStart(source), end: message.initializer.end });
+        }
     }
-  }
-  return ranges;
+    return ranges;
 }
-
 /** Literal Vietnamese message values of typed catalogs; keys, comments, English values and expressions remain source. */
 function messageBundleValueRanges(ts, source) {
-  const imports = messageBundleImports(ts, source);
-  const ranges = [];
-  const visit = (node) => {
-    const catalog = messageCatalogObject(ts, node, imports);
-    if (catalog) ranges.push(...vietnameseValueRanges(ts, catalog, source));
-    ts.forEachChild(node, visit);
-  };
-  visit(source);
-  return ranges;
+    const imports = messageBundleImports(ts, source);
+    const ranges = [];
+    const visit = (node) => {
+        const catalog = messageCatalogObject(ts, node, imports);
+        if (catalog)
+            ranges.push(...vietnameseValueRanges(ts, catalog, source));
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return ranges;
 }
-
 /** Source-language hits, treating only literal vi values of typed backend MessageBundle objects as translated product data. */
 export function sourceLanguageHits(rel, text, ts) {
-  if (!hasSecondLanguage(text)) return [];
-  if (!ts || !/\.[cm]?tsx?$/.test(rel)) return secondLanguageHits(text);
-  const source = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true);
-  let sourceText = text;
-  for (const range of messageBundleValueRanges(ts, source).sort((left, right) => right.start - left.start)) {
-    sourceText = sourceText.slice(0, range.start) + sourceText.slice(range.start, range.end).replace(/[^\r\n]/g, ' ') + sourceText.slice(range.end);
-  }
-  return secondLanguageHits(sourceText);
+    if (!hasSecondLanguage(text))
+        return [];
+    if (!ts || !/\.[cm]?tsx?$/.test(rel))
+        return secondLanguageHits(text);
+    const source = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true);
+    let sourceText = text;
+    for (const range of messageBundleValueRanges(ts, source).sort((left, right) => right.start - left.start)) {
+        sourceText = sourceText.slice(0, range.start) + sourceText.slice(range.start, range.end).replace(/[^\r\n]/g, ' ') + sourceText.slice(range.end);
+    }
+    return secondLanguageHits(sourceText);
 }
-
 /**
  * The Vietnamese fields of one failure-code entry: the operator text the owner mandated for the failure-code catalog
  * (scripts/checks/check-failure-codes.mjs types the entry with exactly these). causes_vi is the list companion of the three scalar fields.
  */
 export const FAILURE_CODE_VIETNAMESE_FIELDS = Object.freeze(['title_vi', 'meaning_vi', 'nextStep_vi', 'causes_vi']);
-
 /**
  * The fields of a document that carry deliberate Vietnamese text, keyed by file: a declared field-level exception of that file's
  * typed content, never a path pattern over content. `fields` are block keys (the key's own value and its list items are exempt);
@@ -139,91 +142,92 @@ export const FAILURE_CODE_VIETNAMESE_FIELDS = Object.freeze(['title_vi', 'meanin
  * owner's reading of the same rule.
  */
 export const DECLARED_VIETNAMESE_FIELDS = Object.freeze({
-  'modules/kernel/failure-codes.yaml': Object.freeze({ fields: FAILURE_CODE_VIETNAMESE_FIELDS }),
-  'modules/ops/_labels.yaml': Object.freeze({ flowFields: Object.freeze(['vi']) }),
-  'modules/goal/archetypes.yaml': Object.freeze({
-    fields: Object.freeze([
-      'buildIntent', 'canonIntent', 'e2eIntent', 'uatIntent', 'proofNegation', 'proofStateCue', 'integrationIntent', 'brandIntent',
-      'phrases', 'requires', 'excludes', 'backend', 'frontend', 'package',
-    ]),
-  }),
-  'modules/goal/source-phrases.yaml': Object.freeze({
-    fields: Object.freeze([
-      'prefer', 'avoid', 'only', 'negation', 'refused', 'accept', 'golden',
-      'missingPaths', 'grantTooNarrow', 'toolTimeout', 'testGap', 'checkerUnavailable',
-      'supervisorVerbs', 'ownerWord', 'orWord', 'beyondAuthority', 'ownerOnly', 'workerDied', 'contractConflict', 'decision',
-      'product', 'grammar', 'knowledge', 'sourceLabel', 'internalVocabulary', 'actor', 'success',
-      'wizard', 'form', 'dashboard', 'gap', 'anatomy', 'otpLabel',
-    ]),
-  }),
+    'modules/kernel/failure-codes.yaml': Object.freeze({ fields: FAILURE_CODE_VIETNAMESE_FIELDS }),
+    'modules/ops/_labels.yaml': Object.freeze({ flowFields: Object.freeze(['vi']) }),
+    'modules/goal/archetypes.yaml': Object.freeze({
+        fields: Object.freeze([
+            'buildIntent', 'canonIntent', 'e2eIntent', 'uatIntent', 'proofNegation', 'proofStateCue', 'integrationIntent', 'brandIntent',
+            'phrases', 'requires', 'excludes', 'backend', 'frontend', 'package',
+        ]),
+    }),
+    'modules/goal/source-phrases.yaml': Object.freeze({
+        fields: Object.freeze([
+            'prefer', 'avoid', 'only', 'negation', 'refused', 'accept', 'golden',
+            'missingPaths', 'grantTooNarrow', 'toolTimeout', 'testGap', 'checkerUnavailable',
+            'supervisorVerbs', 'ownerWord', 'orWord', 'beyondAuthority', 'ownerOnly', 'workerDied', 'contractConflict', 'decision',
+            'product', 'grammar', 'knowledge', 'sourceLabel', 'internalVocabulary', 'actor', 'success',
+            'wizard', 'form', 'dashboard', 'gap', 'anatomy', 'otpLabel',
+        ]),
+    }),
 });
-
 /**
  * The Vietnamese catalog of owner-visible messages (scripts/lib/i18n.mjs): modules/i18n/messages/<area>.yaml, a list of
  * `{en, vi}` entries keyed from the English source. The `vi` field (block or inline flow) is the declared Vietnamese.
  */
 const I18N_CATALOG_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']), flowFields: Object.freeze(['vi']) });
 const I18N_CATALOG_DIR = 'modules/i18n/messages/';
-
 /** The `vi` field of an op manifest's text objects (modules/schemas/op.schema.yaml $defs text). */
 const OP_MANIFEST_VIETNAMESE_FIELDS = Object.freeze({ fields: Object.freeze(['vi']) });
 const OP_MANIFEST_DIR = 'modules/ops/ops/';
 /** The declared Vietnamese fields of `rel`: its own entry, or the op-manifest text field for a manifest of modules/ops/ops. */
 const declaredVietnameseFieldsOf = (rel) => DECLARED_VIETNAMESE_FIELDS[rel]
-  ?? (rel.startsWith(I18N_CATALOG_DIR) && !rel.slice(I18N_CATALOG_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? I18N_CATALOG_VIETNAMESE_FIELDS : null)
-  ?? (rel.startsWith(OP_MANIFEST_DIR) && !rel.slice(OP_MANIFEST_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? OP_MANIFEST_VIETNAMESE_FIELDS : null);
-
+    ?? (rel.startsWith(I18N_CATALOG_DIR) && !rel.slice(I18N_CATALOG_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? I18N_CATALOG_VIETNAMESE_FIELDS : null)
+    ?? (rel.startsWith(OP_MANIFEST_DIR) && !rel.slice(OP_MANIFEST_DIR.length).includes('/') && /\.ya?ml$/.test(rel) ? OP_MANIFEST_VIETNAMESE_FIELDS : null);
 /**
  * The slots whose files may carry another language, and why: a catalog is product copy in two languages, and an i18n
  * fixture reproduces a real localized string a parser or formatter must accept. Placement is the whole marker - there is no
  * comment pragma and no path pattern. The slots are declared in knowledge/hfs/slots.yaml.
  */
 const LOCALIZED_TEXT_SLOTS = Object.freeze([
-  'be.domain.messages', 'be.feature.messages', 'be.tests.fixtures.i18n',
-  'fe.modules.i18n', 'fe.package.i18n',
+    'be.domain.messages', 'be.feature.messages', 'be.tests.fixtures.i18n',
+    'fe.modules.i18n', 'fe.package.i18n',
 ]);
-
 /** Whether a document (Markdown or YAML) of `slot` is exempt: only catalogue and fixture DATA (YAML) is; Markdown is prose and never is. */
 export const isLocalizedDataFile = (rel, slot) => LOCALIZED_TEXT_SLOTS.includes(slot) && /\.ya?ml$/.test(rel);
-
 /**
  * The key each line of a YAML text belongs to: a `key:` line owns itself, and every deeper-indented line after it (a list item,
  * a folded block, a wrapped scalar) belongs to the same key. A line at or above the key's indent that is not a key belongs to none.
  */
 function yamlKeyOfEachLine(text) {
-  let key = null;
-  let keyIndent = -1;
-  return String(text).split(/\r?\n/).map((raw) => {
-    if (raw.trim() === '') return key;
-    const indent = raw.length - raw.trimStart().length;
-    const own = /^(\s*(?:-\s+)?)([A-Za-z_][\w-]*)\s*:(?:\s|$)/.exec(raw);
-    if (own) { key = own[2]; keyIndent = own[1].length; return key; }
-    // a list item may sit at the key's own indent (`key:` then `- item` at the same column)
-    if (indent > keyIndent || (indent === keyIndent && /^\s*-\s/.test(raw))) return key;
-    key = null;
-    keyIndent = -1;
-    return null;
-  });
+    let key = null;
+    let keyIndent = -1;
+    return String(text).split(/\r?\n/).map((raw) => {
+        if (raw.trim() === '')
+            return key;
+        const indent = raw.length - raw.trimStart().length;
+        const own = /^(\s*(?:-\s+)?)([A-Za-z_][\w-]*)\s*:(?:\s|$)/.exec(raw);
+        if (own) {
+            key = own[2];
+            keyIndent = own[1].length;
+            return key;
+        }
+        // a list item may sit at the key's own indent (`key:` then `- item` at the same column)
+        if (indent > keyIndent || (indent === keyIndent && /^\s*-\s/.test(raw)))
+            return key;
+        key = null;
+        keyIndent = -1;
+        return null;
+    });
 }
-
 /** The Vietnamese hits of a document, minus the declared field-level exceptions of `rel` (a repository-relative POSIX path). */
 export function documentLanguageHits(rel, text) {
-  const declared = declaredVietnameseFieldsOf(rel);
-  const hits = secondLanguageHits(text);
-  if (!declared) return hits;
-  const keys = yamlKeyOfEachLine(text);
-  const lines = String(text).split(/\r?\n/);
-  return hits.filter((hit) => {
-    if (declared.fields?.includes(keys[hit.line - 1])) return false;
-    if (!declared.flowFields) return true;
-    // an inline flow map: drop the declared fields' values and judge what is left of the line
-    const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(String.raw`\b${field}\s*:\s*(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^,}]*)`, 'g'), ''), lines[hit.line - 1]);
-    return hasSecondLanguage(rest);
-  });
+    const declared = declaredVietnameseFieldsOf(rel);
+    const hits = secondLanguageHits(text);
+    if (!declared)
+        return hits;
+    const keys = yamlKeyOfEachLine(text);
+    const lines = String(text).split(/\r?\n/);
+    return hits.filter((hit) => {
+        if (declared.fields?.includes(keys[hit.line - 1] ?? ''))
+            return false;
+        if (!declared.flowFields)
+            return true;
+        // an inline flow map: drop the declared fields' values and judge what is left of the line
+        const rest = declared.flowFields.reduce((line, field) => line.replace(new RegExp(String.raw `\b${field}\s*:\s*(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^,}]*)`, 'g'), ''), lines[hit.line - 1]);
+        return hasSecondLanguage(rest);
+    });
 }
-
 /** The file extensions of a prose document (Markdown and YAML). */
 const DOCUMENT_EXTENSIONS = Object.freeze(['.md', '.yaml', '.yml']);
-
 /** Whether `rel` is a document a language check reads. */
 export const isDocument = (rel) => DOCUMENT_EXTENSIONS.includes(path.posix.extname(rel));

package/runtime/scripts/lib/list.d.mts

@@ -0,0 +1,17 @@
+export declare const list: <T = unknown>(v: unknown) => T[];
+/** `v` as an array: itself when already one, [] for null/undefined, else [v]. */
+export declare const asList: <T = unknown>(v: unknown) => T[];
+/** The object entries of `v` (a non-array reads as []). */
+export declare const objectList: <T extends object = Record<string, unknown>>(v: unknown) => T[];
+/** Every entry of `v` a non-empty string (`blank: false` also rejects all-whitespace entries). */
+export declare const stringList: (v: unknown, { blank }?: {
+    blank?: boolean;
+}) => v is string[];
+/** A non-empty list of distinct values, all accepted by the supplied predicate. */
+export declare const nonemptyUniqueList: <T = unknown>(values: unknown, accepts: (entry: T) => boolean) => values is T[];
+/** The items of a `sep`-separated list: trimmed, empties dropped; `dedupe` keeps first occurrences only. */
+export declare const splitList: (v: unknown, { sep, dedupe }?: {
+    sep?: string | RegExp;
+    dedupe?: boolean;
+}) => string[];
+export { byCodeUnit } from '../../engine/by-code-unit.mjs';

package/runtime/scripts/lib/list.mjs

@@ -2,30 +2,25 @@
 // `v` when it already is an array, else []. Scalars are NOT wrapped: a caller that wants
 // `[v]` for a lone value writes its own coercion (see contract-version's list).
 export const list = (v) => (Array.isArray(v) ? v : []);
-
 /** `v` as an array: itself when already one, [] for null/undefined, else [v]. */
 export const asList = (v) => {
-  if (Array.isArray(v)) return v;
-  if (v == null) return [];
-  return [v];
+    if (Array.isArray(v))
+        return v;
+    if (v == null)
+        return [];
+    return [v];
 };
-
 /** The object entries of `v` (a non-array reads as []). */
 export const objectList = (v) => (Array.isArray(v) ? v : []).filter((item) => item && typeof item === 'object');
-
 /** Every entry of `v` a non-empty string (`blank: false` also rejects all-whitespace entries). */
-export const stringList = (v, { blank = true } = {}) =>
-  Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0 && (blank || s.trim().length > 0));
-
+export const stringList = (v, { blank = true } = {}) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0 && (blank || s.trim().length > 0));
 /** A non-empty list of distinct values, all accepted by the supplied predicate. */
 export const nonemptyUniqueList = (values, accepts) => Array.isArray(values) && values.length > 0
-  && values.every((entry) => accepts(entry)) && new Set(values).size === values.length;
-
+    && values.every((entry) => accepts(entry)) && new Set(values).size === values.length;
 /** The items of a `sep`-separated list: trimmed, empties dropped; `dedupe` keeps first occurrences only. */
 export const splitList = (v, { sep = ',', dedupe = false } = {}) => {
-  const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);
-  return dedupe ? [...new Set(items)] : items;
+    const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);
+    return dedupe ? [...new Set(items)] : items;
 };
-
 // The comparator of a bare `sort()` (UTF-16 code-unit order) is owned by the engine, which cannot import scripts/lib.
 export { byCodeUnit } from '../../engine/by-code-unit.mjs';

package/runtime/scripts/lib/loosening-budgets.d.mts

@@ -0,0 +1,12 @@
+/** A pin of the design-truths manifest `budgets` list: the ruleParams node and the numbers it must hold, and the per-slot `budget` ceilings. */
+export interface BudgetPin {
+    params?: {
+        under?: string;
+        ceilings?: Record<string, number>;
+        floors?: Record<string, number>;
+        equals?: Record<string, unknown>;
+    };
+    slots?: Record<string, Record<string, number>>;
+}
+/** What the YAML `text` of a pinned file holds against its pin: the details of every budget raised, lowered or gone (an unreadable file is one). */
+export declare function budgetRecords(text: string, pin: BudgetPin): string[];

package/runtime/scripts/lib/loosening-budgets.mjs

@@ -3,42 +3,48 @@
 // ceiling or lowering a floor in the slot manifests loosens the gate, and so does a budget that is gone. The pin names the file, the ruleParams node
 // and the numbers, and the per-slot `budget` maps; the check reads each file's YAML and compares.
 import { parseYaml } from '../../engine/yaml.mjs';
-
+// reason: same dotted-path read of parsed YAML as BudgetDocument.
 const at = (node, dotted) => (dotted ? dotted.split('.').reduce((value, key) => value?.[key], node) : node);
 const isNumber = (value) => typeof value === 'number';
-
 function paramRecords(doc, params) {
-  const base = at(doc, params.under);
-  const found = [];
-  for (const [key, max] of Object.entries(params.ceilings ?? {})) {
-    const value = at(base, key);
-    if (!isNumber(value) || value > max) found.push(`${key} ${value ?? 'missing'}, the ceiling is ${max}`);
-  }
-  for (const [key, min] of Object.entries(params.floors ?? {})) {
-    const value = at(base, key);
-    if (!isNumber(value) || value < min) found.push(`${key} ${value ?? 'missing'}, the floor is ${min}`);
-  }
-  for (const [key, want] of Object.entries(params.equals ?? {})) {
-    if (at(base, key) !== want) found.push(`${key} ${at(base, key) ?? 'missing'}, the canon says ${want}`);
-  }
-  return found;
+    const base = at(doc, params.under);
+    const found = [];
+    for (const [key, max] of Object.entries(params.ceilings ?? {})) {
+        const value = at(base, key);
+        if (!isNumber(value) || value > max)
+            found.push(`${key} ${value ?? 'missing'}, the ceiling is ${max}`);
+    }
+    for (const [key, min] of Object.entries(params.floors ?? {})) {
+        const value = at(base, key);
+        if (!isNumber(value) || value < min)
+            found.push(`${key} ${value ?? 'missing'}, the floor is ${min}`);
+    }
+    for (const [key, want] of Object.entries(params.equals ?? {})) {
+        if (at(base, key) !== want)
+            found.push(`${key} ${at(base, key) ?? 'missing'}, the canon says ${want}`);
+    }
+    return found;
 }
-
 function slotRecords(doc, slots) {
-  const found = [];
-  for (const [id, ceilings] of Object.entries(slots ?? {})) {
-    const slot = (doc.slots ?? []).find((entry) => entry.id === id);
-    for (const [key, max] of Object.entries(ceilings)) {
-      const value = slot?.budget?.[key];
-      if (!isNumber(value) || value > max) found.push(`slot ${id} budget ${key} ${value ?? 'missing'}, the ceiling is ${max}`);
+    const found = [];
+    for (const [id, ceilings] of Object.entries(slots ?? {})) {
+        const slot = (doc.slots ?? []).find((entry) => entry.id === id);
+        for (const [key, max] of Object.entries(ceilings)) {
+            const value = slot?.budget?.[key];
+            if (!isNumber(value) || value > max)
+                found.push(`slot ${id} budget ${key} ${value ?? 'missing'}, the ceiling is ${max}`);
+        }
     }
-  }
-  return found;
+    return found;
 }
-
 /** What the YAML `text` of a pinned file holds against its pin: the details of every budget raised, lowered or gone (an unreadable file is one). */
 export function budgetRecords(text, pin) {
-  let doc;
-  try { doc = parseYaml(text); } catch { return ['the file is not readable YAML, so its budgets cannot be judged']; }
-  return [...(pin.params ? paramRecords(doc, pin.params) : []), ...slotRecords(doc, pin.slots)];
+    let doc;
+    try {
+        doc = parseYaml(text);
+    }
+    catch {
+        return ['the file is not readable YAML, so its budgets cannot be judged'];
+    }
+    return [...(pin.params ? paramRecords(doc, pin.params) : []), ...slotRecords(doc, pin.slots)];
 }

package/runtime/scripts/lib/loosening-config.d.mts

@@ -0,0 +1,64 @@
+/** The kinds of gate configuration file. */
+export type ConfigKind = 'codecov' | 'sonar' | 'jest' | 'eslint' | 'stylelint' | 'tsconfig' | 'ignorefile' | 'stack' | 'declaration';
+/** An entry of an ignore or exclude list; `list` is the class the manifest allows entries by. */
+export interface ListRecord {
+    list: string;
+    key: string;
+    item: string;
+    line: number;
+}
+/** A coverage target or threshold. */
+export interface NumberRecord {
+    key: string;
+    value: number;
+    line: number;
+}
+/** A yes/no switch that can relax a gate, or a tsconfig strictness option. */
+export interface SettingRecord {
+    key: string;
+    value: string;
+    line: number;
+}
+/** An ESLint or stylelint rule turned off or down. */
+export interface RuleOffRecord {
+    rule: string;
+    line: number;
+}
+/** A key a config states (a budget it states itself, a key that narrows what a tool runs). */
+export interface KeyRecord {
+    key: string;
+    line: number;
+}
+/** What a config file states. */
+export interface ConfigRecords {
+    lists: ListRecord[];
+    numbers: NumberRecord[];
+    settings: SettingRecord[];
+    rulesOff: RuleOffRecord[];
+    strictness: SettingRecord[];
+    budgets: KeyRecord[];
+    scope: KeyRecord[];
+}
+export declare const LIST: Readonly<{
+    coverage: "coverage-exclusions";
+    sonar: "sonar-exclusions";
+    cpd: "cpd-exclusions";
+    scope: "sonar-scope";
+    paths: "path-ignores";
+    jest: "jest-patterns";
+    issues: "issue-ignores";
+}>;
+/** The kind of gate configuration `file` is, or null. A JSON file that holds compilerOptions is a tsconfig whatever it is called (it may be extended). */
+export declare function configKindOf(file: string, text?: string): ConfigKind | null;
+/** Whether `file` may be a tsconfig by its extension: the check has to read it to know. */
+export declare const maybeTsconfig: (file: string) => boolean;
+/** Files whose name says, anywhere in it, that they hold exceptions, approvals or a baseline of findings; a schema file only describes one. */
+export declare function isExceptionFile(file: string): boolean;
+/** How many entries an exception file holds (parsed: a flow-style list counts like a block-style one; a text list counts its lines). */
+export declare function exceptionEntries(file: string, text: string): number;
+/** What the file of config `kind` states: { lists, numbers, settings, rulesOff, strictness, budgets, scope } (each possibly empty). */
+export declare function configRecords(kind: ConfigKind, text: string, file: string): ConfigRecords;
+/** `item` as a path core: no quotes, no leading dot-slash, globstar or slash, no trailing slash or star segment, so a folder spelled three ways is one entry. */
+export declare function coreOf(item: unknown): string;
+/** Whether the item was spelled as a path at any depth (`**` first), which a rooted allowance does not cover. */
+export declare const isAnyDepth: (item: unknown) => boolean;