explico 0.1.0

package/src/reference/label.ts

@@ -0,0 +1,47 @@
+/**
+ * Display label for a notation entry (Phase C1b, replacing the authored
+ * `title`). Default = the key humanized: split on `-`/`.`, upper-case known
+ * acronyms, capitalize the first word. An entry may still set an explicit
+ * `label` where the humanized key would read wrong.
+ */
+
+const ACRONYMS = new Map<string, string>([
+  ['cds', 'CDS'],
+  ['cdx', 'CDX'],
+  ['isda', 'ISDA'],
+  ['pv', 'PV'],
+  ['npv', 'NPV'],
+  ['lgd', 'LGD'],
+  ['ytm', 'YTM'],
+  ['rop', 'RoP'],
+]);
+
+// Adjacent key words that stay hyphenated (compound modifiers) rather than
+// becoming a space.
+const COMPOUNDS = new Set([
+  'risk-neutral',
+  'real-world',
+  'price-yield',
+  'market-standard',
+  'risk-free',
+]);
+
+export function humanizeKey(key: string): string {
+  const words = key.split(/[-.]/).filter(Boolean);
+  const cased = words.map((word, index) => {
+    const acronym = ACRONYMS.get(word);
+    if (acronym) return acronym;
+    return index === 0 ? word.charAt(0).toUpperCase() + word.slice(1) : word;
+  });
+  let out = cased[0] ?? '';
+  for (let i = 1; i < cased.length; i += 1) {
+    const joiner = COMPOUNDS.has(`${words[i - 1]}-${words[i]}`) ? '-' : ' ';
+    out += joiner + cased[i];
+  }
+  return out;
+}
+
+/** The label an entry resolves to: an explicit `label`, else the humanized key. */
+export function resolveLabel(key: string, label?: string): string {
+  return label && label.trim().length > 0 ? label : humanizeKey(key);
+}

package/src/reference/lint-ignore.ts

@@ -0,0 +1,75 @@
+/**
+ * The one reviewed suppression registry for consistency checks (Step D6).
+ *
+ * A corpus-level finding (a glyph that resolves to more than one meaning, a
+ * unit outside the controlled vocabulary, …) is a violation unless it is
+ * acknowledged here, in `lint-ignore.yml` at the repository root, with a
+ * reason. Silent suppression is disallowed: there is no per-file pragma and no
+ * inline comment that turns a check off.
+ *
+ * File grammar — one acknowledgement per line:
+ *
+ *     <check-code>[:<detail>] — <reason>
+ *
+ * `<detail>` is optional and narrows the acknowledgement (a glyph for
+ * `glyph-unique-in-corpus`, a notation key otherwise); with no detail the line
+ * acknowledges every finding of that code. The separator is an em dash (`—`),
+ * or `--` / ` - ` in ASCII. Blank lines and `#` comments are ignored.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const IGNORE_PATH = join(process.cwd(), 'lint-ignore.yml');
+
+export interface LintIgnoreEntry {
+  readonly code: string;
+  readonly detail?: string;
+  readonly reason: string;
+}
+
+export interface LintIgnore {
+  readonly entries: readonly LintIgnoreEntry[];
+  /** True when a `<code>` (optionally `<code>:<detail>`) finding is acknowledged. */
+  matches(code: string, detail?: string): boolean;
+}
+
+const LINE =
+  /^-\s*([a-z0-9-]+)(?::([^\s—-][^—-]*?))?\s*(?:—|--|\s-\s)\s*(.+?)\s*$/;
+
+export function parseLintIgnore(text: string): LintIgnoreEntry[] {
+  const entries: LintIgnoreEntry[] = [];
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.replace(/#.*$/, '').trim();
+    if (line === '' || line === 'ignore:' || line === '[]') continue;
+    const match = LINE.exec(line);
+    if (!match) {
+      throw new Error(
+        `lint-ignore.yml: expected "- <code>[:<detail>] — <reason>", got ${JSON.stringify(rawLine)}`,
+      );
+    }
+    const [, code, detail, reason] = match;
+    entries.push({
+      code: code as string,
+      ...(detail && detail.trim() ? { detail: detail.trim() } : {}),
+      reason: (reason as string).trim(),
+    });
+  }
+  return entries;
+}
+
+export function loadLintIgnore(): LintIgnore {
+  const entries = existsSync(IGNORE_PATH)
+    ? parseLintIgnore(readFileSync(IGNORE_PATH, 'utf8'))
+    : [];
+  return {
+    entries,
+    matches(code, detail) {
+      return entries.some(
+        (entry) =>
+          entry.code === code &&
+          (entry.detail === undefined || entry.detail === detail),
+      );
+    },
+  };
+}