@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/artifacts/corpus-tools/radar-init.js

@@ -0,0 +1,93 @@
+/**
+ * radar-init — scaffold a radar/freshness sidecar for a REF (#1498).
+ *
+ * Faithful port of corpus/radar_init.py scaffold(): pulls title/authors from the
+ * citation sidecar and GRADE from the analysis doc, defaults the refresh cadence
+ * from GRADE (shared cadenceForGrade) and the cluster from the externalized
+ * cluster map, and stamps `documentation/radar/REF-XXX-radar.md`. Skip-if-exists;
+ * dry-run unless `write`.
+ *
+ * @source historical: corpus/radar_init.py (scaffold, main --all-missing)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { cadenceForGrade } from '../corpus-views/corpus-config.js';
+import { readAnalysisGrade, readCitationMeta, analysisRelPath, loadClusterMap, listCitationRefs, listRadarRefs, } from './radar-shared.js';
+function todayUtc() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Build the `../…` link from documentation/radar/ to the analysis doc. */
+function analysisLink(relPath, refId) {
+    if (!relPath)
+        return `../references/${refId}-*.md`;
+    const segs = relPath.split(path.sep);
+    // documentation/references/REF.md -> ../references/REF.md
+    return segs[0] === 'documentation' ? `../${segs.slice(1).join('/')}` : `../${segs.join('/')}`;
+}
+/** Render the radar-sidecar markdown body. Mirrors radar_init.scaffold()'s line block. */
+function renderSidecar(args) {
+    const { refId, title, authors, grade, cadence, cluster, today, analysisRel } = args;
+    const link = analysisLink(analysisRel, refId);
+    const analysisName = analysisRel ? analysisRel.split(path.sep).pop() : 'n/a';
+    const lines = [
+        '---',
+        `ref: ${refId}`,
+        `title: "${title}"`,
+        'type: radar',
+        `refresh-cadence: ${cadence}`,
+        `last-refreshed: ${today}`,
+        'last-refreshed-by: radar-init-scaffold',
+    ];
+    if (cluster)
+        lines.push(`cluster: ${cluster}`);
+    lines.push(`grade-original: ${grade}`, `grade-current: ${grade}`, 'grade-trajectory: stable', 'sources-searched: []    # populate on first refresh', '---', '', `# ${refId} Radar`, '', `**Paper**: [citation sidecar](../citations/${refId}-citations.md) · [analysis doc](${link})`, `**Title**: ${title}`);
+    if (authors.length) {
+        const display = authors.slice(0, 3);
+        const suffix = authors.length > 3 ? ' et al.' : '';
+        lines.push(`**Authors**: ${display.join(', ')}${suffix}`);
+    }
+    lines.push(`**Last refreshed**: ${today}`, '**Next refresh due**: — (compute from cadence)', '**Refresh rationale**: Initial scaffold. Full multi-vector signal gather pending first `/radar refresh` invocation.', '', '---', '', '## 1. GRADE Re-Assessment', '', '| Attribute | At Induction | Current | Δ |', '|---|---|---|---|', `| GRADE letter | ${grade} | ${grade} | — |`, '| Peer-reviewed | — | — | — |', '| Replication status | — | — | — |', '| Retraction status | clean | clean | — |', '| Author active | — | — | — |', '', '**Rationale**: Initial scaffold, no re-assessment performed yet.', '', '## 2. Citation Signals', '', `**As of ${today}** — pending first refresh.`, '', '## 3. Implementation / Code Signals', '', 'Pending first refresh.', '', '## 4. News & Discussion', '', 'Pending first refresh.', '', '## 5. Retractions / Corrections / Concerns', '', '| Category | Status | Detail |', '|---|---|---|', `| Retraction Watch | unchecked (scaffold created ${today}) | — |`, '| PubPeer | unchecked | — |', '| Formal corrigenda | none known | — |', '| Methodology critiques | none known | — |', '| Reproducibility attempts | — | — |', '', '## 6. Notable Links', '', '**Primary**:', `- Analysis doc: [${analysisName}](${link})`, `- Citation sidecar: [${refId}-citations.md](../citations/${refId}-citations.md)`, '- PDF: (in `pdfs/full/`)', '', '## 7. Open Questions / Watch Items', '', 'Pending first refresh — what should we watch for?', '', '## 8. Refresh History', '', '| Date | Refreshed by | GRADE before → after | Key changes |', '|---|---|---|---|', `| ${today} | radar-init-scaffold | — → ${grade} | Initial scaffold (no signals gathered yet) |`, '');
+    return lines.join('\n');
+}
+/** Scaffold a radar sidecar for one REF. */
+export function scaffoldRadar(corpusRoot, refId, opts = {}) {
+    const outRel = path.join('documentation', 'radar', `${refId}-radar.md`);
+    const citationPath = path.join(corpusRoot, 'documentation', 'citations', `${refId}-citations.md`);
+    if (!fs.existsSync(citationPath)) {
+        return { refId, status: 'skip', message: `SKIP ${refId}: no citation sidecar found`, outPath: outRel };
+    }
+    const { title, authors } = readCitationMeta(corpusRoot, refId);
+    const grade = readAnalysisGrade(corpusRoot, refId);
+    const cadence = opts.cadence || cadenceForGrade(grade);
+    const resolve = opts.clusterResolver ?? loadClusterMap(corpusRoot);
+    const cluster = opts.cluster ?? resolve(refId);
+    const today = opts.today || todayUtc();
+    const content = renderSidecar({
+        refId,
+        title,
+        authors,
+        grade,
+        cadence,
+        cluster,
+        today,
+        analysisRel: analysisRelPath(corpusRoot, refId),
+    });
+    const outAbs = path.join(corpusRoot, outRel);
+    if (!opts.write) {
+        return { refId, status: 'dry-run', message: `DRY-RUN ${refId}: would write ${outRel} (${content.length} chars)`, outPath: outRel, content };
+    }
+    if (fs.existsSync(outAbs)) {
+        return { refId, status: 'skip', message: `SKIP ${refId}: radar already exists at ${outRel}`, outPath: outRel };
+    }
+    fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+    fs.writeFileSync(outAbs, content, 'utf-8');
+    return { refId, status: 'wrote', message: `WROTE ${outRel}`, outPath: outRel, content };
+}
+/** Scaffold radars for every REF with a citation sidecar but no radar yet. */
+export function radarInitMissing(corpusRoot, opts = {}) {
+    const haveRadar = new Set(listRadarRefs(corpusRoot));
+    const missing = listCitationRefs(corpusRoot).filter((r) => !haveRadar.has(r));
+    const clusterResolver = opts.clusterResolver ?? loadClusterMap(corpusRoot);
+    return missing.map((refId) => scaffoldRadar(corpusRoot, refId, { ...opts, clusterResolver }));
+}
+//# sourceMappingURL=radar-init.js.map

package/dist/src/artifacts/corpus-tools/radar-report.js

@@ -0,0 +1,118 @@
+/**
+ * radar-report — aggregate radar sidecars into a corpus/cluster freshness report (#1498).
+ *
+ * Port of corpus/radar_report.py: totals, overdue count, per-cluster / per-GRADE
+ * / per-trajectory breakdowns, an overdue table (most-overdue-first), and a
+ * per-radar summary with the §1 GRADE-reassessment rationale snippet. Reuses the
+ * shared loader + staleness helper.
+ *
+ * @source historical: corpus/radar_report.py
+ */
+import { computeStaleness } from '../corpus-views/corpus-config.js';
+import { loadRadars } from './radar-shared.js';
+/** Extract the first prose line from a `## <prefix>` section (skips tables/rules). */
+function sectionSnippet(text, prefix) {
+    const lines = text.split('\n');
+    let inSection = false;
+    const buf = [];
+    for (const line of lines) {
+        if (line.startsWith('## ')) {
+            if (inSection)
+                break;
+            if (line.startsWith(prefix)) {
+                inSection = true;
+                continue;
+            }
+        }
+        if (inSection)
+            buf.push(line);
+    }
+    for (const raw of buf) {
+        const line = raw.trim();
+        if (line && !line.startsWith('|') && !line.startsWith('---'))
+            return line.slice(0, 200);
+    }
+    return '';
+}
+function toRow(doc, today) {
+    const s = computeStaleness(doc.meta.refreshCadence, doc.meta.lastRefreshed, today);
+    return {
+        refId: doc.refId,
+        cluster: doc.meta.cluster ?? '',
+        grade: doc.meta.gradeCurrent ?? doc.meta.gradeOriginal ?? '?',
+        trajectory: doc.meta.gradeTrajectory ?? 'stable',
+        cadence: doc.meta.refreshCadence ?? '?',
+        lastRefreshed: doc.meta.lastRefreshed ?? '',
+        daysSince: s.daysSince,
+        overdueDays: s.overdueDays,
+        isStale: s.isStale,
+        text: doc.text,
+    };
+}
+function countBy(rows, key) {
+    const m = new Map();
+    for (const r of rows) {
+        const k = key(r);
+        if (!m.has(k))
+            m.set(k, []);
+        m.get(k).push(r);
+    }
+    return m;
+}
+/** Build the markdown freshness report. Returns a "no radars" note when empty. */
+export function renderRadarReport(corpusRoot, opts = {}) {
+    const iso = opts.today ?? new Date().toISOString().slice(0, 10);
+    const today = new Date(`${iso}T00:00:00Z`);
+    let docs = loadRadars(corpusRoot);
+    if (opts.cluster)
+        docs = docs.filter((d) => (d.meta.cluster ?? '') === opts.cluster);
+    if (!docs.length) {
+        return opts.cluster ? `No radars matched cluster \`${opts.cluster}\`.\n` : 'No radar sidecars yet.\n';
+    }
+    const rows = docs.map((d) => toRow(d, today));
+    const stale = rows.filter((r) => r.isStale);
+    const byCluster = countBy(rows, (r) => r.cluster || '(untagged)');
+    const byGrade = countBy(rows, (r) => r.grade);
+    const byTrajectory = countBy(rows, (r) => r.trajectory);
+    const sortedKeys = (m) => [...m.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const tag = opts.cluster ? ` — cluster \`${opts.cluster}\`` : '';
+    const lines = [
+        `# Radar Report ${iso}${tag}`,
+        '',
+        `**Total radars**: ${rows.length}`,
+        `**Overdue (stale)**: ${stale.length}`,
+        '',
+        '## Clusters',
+        '',
+        '| Cluster | Count | Stale |',
+        '|---|---:|---:|',
+    ];
+    for (const c of sortedKeys(byCluster)) {
+        const members = byCluster.get(c);
+        lines.push(`| ${c} | ${members.length} | ${members.filter((m) => m.isStale).length} |`);
+    }
+    lines.push('', '## GRADE Distribution', '', '| Grade | Count |', '|---|---:|');
+    for (const g of sortedKeys(byGrade))
+        lines.push(`| ${g || '?'} | ${byGrade.get(g).length} |`);
+    lines.push('', '## GRADE Trajectories', '', '| Trajectory | Count |', '|---|---:|');
+    for (const t of sortedKeys(byTrajectory))
+        lines.push(`| ${t || '?'} | ${byTrajectory.get(t).length} |`);
+    if (stale.length) {
+        lines.push('', '## Overdue Refreshes', '', '| REF | Cadence | Last refresh | Overdue days | GRADE | Cluster |', '|---|---|---|---:|---|---|');
+        for (const s of [...stale].sort((a, b) => (b.overdueDays ?? 0) - (a.overdueDays ?? 0))) {
+            lines.push(`| ${s.refId} | ${s.cadence} | ${s.lastRefreshed} | ${s.overdueDays} | ${s.grade} | ${s.cluster} |`);
+        }
+    }
+    lines.push('', '## Individual Radars', '');
+    for (const r of rows) {
+        lines.push(`### ${r.refId} — grade **${r.grade}**, trajectory \`${r.trajectory}\`, cadence \`${r.cadence}\``, '');
+        lines.push(`- Cluster: ${r.cluster || '(none)'}`);
+        lines.push(`- Last refreshed: ${r.lastRefreshed || '?'} (${r.daysSince ?? '?'} days ago)`);
+        const snippet = sectionSnippet(r.text, '## 1.');
+        if (snippet)
+            lines.push(`- Rationale: ${snippet}`);
+        lines.push('');
+    }
+    return lines.join('\n').replace(/\s+$/, '') + '\n';
+}
+//# sourceMappingURL=radar-report.js.map

package/dist/src/artifacts/corpus-tools/radar-shared.js

@@ -0,0 +1,189 @@
+/**
+ * Shared primitives for the radar/freshness subsystem (#1498).
+ *
+ * Write-side counterpart to the read-only corpus-views renderers. Ports the
+ * common helpers from corpus/radar_init.py + radar_report.py:
+ *  - externalized cluster map (mechanism only — the literal REF-range table
+ *    from radar_init.guess_cluster is NOT ported; the corpus supplies its own
+ *    `documentation/radar/clusters.yaml`, per the #1498 "don't port the literal
+ *    ranges" requirement),
+ *  - GRADE extraction from the analysis doc (improved over the Python source:
+ *    also matches the `**Quality**: A-` form the canonical/expanded reference
+ *    templates use, and preserves the +/- sign the Python `([A-D])` dropped),
+ *  - citation-sidecar title/authors,
+ *  - the radar-sidecar loader.
+ *
+ * @source historical: corpus/radar_init.py, corpus/radar_report.py
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { load as loadYaml } from 'js-yaml';
+import { parseFrontmatter, extractRadar } from '../corpus-views/ref-parser.js';
+const RADAR_DIR = ['documentation', 'radar'];
+const REFS_DIR = ['documentation', 'references'];
+const CITES_DIR = ['documentation', 'citations'];
+function radarDir(corpusRoot) {
+    return path.join(corpusRoot, ...RADAR_DIR);
+}
+/** List REF ids that have a radar sidecar (`documentation/radar/REF-*-radar.md`). */
+export function listRadarRefs(corpusRoot) {
+    try {
+        return fs
+            .readdirSync(radarDir(corpusRoot))
+            .filter((f) => /^REF-\d{3,4}[a-z]?-radar\.md$/.test(f))
+            .map((f) => f.replace(/-radar\.md$/, ''))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** List REF ids that have a citation sidecar (`documentation/citations/REF-*-citations.md`). */
+export function listCitationRefs(corpusRoot) {
+    try {
+        return fs
+            .readdirSync(path.join(corpusRoot, ...CITES_DIR))
+            .filter((f) => /^REF-\d{3,4}[a-z]?-citations\.md$/.test(f))
+            .map((f) => f.replace(/-citations\.md$/, ''))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Build a REF-id → cluster-tag resolver from `documentation/radar/clusters.yaml`.
+ *
+ * Format (corpus-supplied; absent file → resolver always returns ''):
+ *   cluster-tag:
+ *     - "599"        # a single REF number
+ *     - "600-605"    # an inclusive REF-number range
+ *
+ * Mirrors the *behavior* of radar_init.guess_cluster (number-range → tag) without
+ * porting its hardcoded ranges.
+ */
+export function loadClusterMap(corpusRoot) {
+    const file = path.join(radarDir(corpusRoot), 'clusters.yaml');
+    let raw;
+    try {
+        raw = loadYaml(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return () => '';
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return () => '';
+    // Flatten to ordered [low, high, tag] rules; singletons are low===high.
+    const rules = [];
+    for (const [tag, spec] of Object.entries(raw)) {
+        const entries = Array.isArray(spec) ? spec : [spec];
+        for (const e of entries) {
+            const s = String(e).trim();
+            const range = s.match(/^(\d+)\s*-\s*(\d+)$/);
+            if (range) {
+                rules.push([parseInt(range[1], 10), parseInt(range[2], 10), tag]);
+            }
+            else if (/^\d+$/.test(s)) {
+                const n = parseInt(s, 10);
+                rules.push([n, n, tag]);
+            }
+        }
+    }
+    return (refId) => {
+        const m = refId.match(/^REF-(\d+)/);
+        if (!m)
+            return '';
+        const n = parseInt(m[1], 10);
+        for (const [low, high, tag] of rules) {
+            if (n >= low && n <= high)
+                return tag;
+        }
+        return '';
+    };
+}
+/** GRADE patterns, tried in order. Each captures a letter plus optional +/- sign. */
+const GRADE_PATTERNS = [
+    // Canonical/expanded reference templates: §14/§20 Document Classification.
+    /\*\*Quality\*\*:\s*([A-D][+-]?)/,
+    // radar_init.py forms (sign-preserving; the Python source dropped the sign).
+    /GRADE[^|\n]*\|\s*\*{0,2}([A-D][+-]?)\*{0,2}/,
+    /\*\*GRADE[^:]*:\*\*\s*([A-D][+-]?)/,
+    /\bGRADE\s*[-—:]\s*([A-D][+-]?)/,
+];
+/**
+ * Extract the GRADE letter (with sign, e.g. `A-`) from the REF analysis doc.
+ * Scans `documentation/references/REF-XXX-*.md` (skipping templates). Returns
+ * `?` when no GRADE is found. Improves on radar_init.read_analysis_grade by
+ * matching the `**Quality**:` classification form and preserving the sign.
+ */
+export function readAnalysisGrade(corpusRoot, refId) {
+    for (const file of analysisFiles(corpusRoot, refId)) {
+        const text = fs.readFileSync(file, 'utf-8');
+        for (const pat of GRADE_PATTERNS) {
+            const m = text.match(pat);
+            if (m)
+                return m[1].toUpperCase();
+        }
+    }
+    return '?';
+}
+/** Analysis-doc files for a REF (references/REF-XXX-*.md), excluding TEMPLATE-* . */
+function analysisFiles(corpusRoot, refId) {
+    const dir = path.join(corpusRoot, ...REFS_DIR);
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.startsWith(`${refId}-`) && f.endsWith('.md') && !f.startsWith('TEMPLATE'))
+            .sort()
+            .map((f) => path.join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+/** Corpus-relative path of the first analysis doc for a REF, or null. */
+export function analysisRelPath(corpusRoot, refId) {
+    const files = analysisFiles(corpusRoot, refId);
+    return files.length ? path.relative(corpusRoot, files[0]) : null;
+}
+/** Title + author display names parsed from the citation sidecar frontmatter. */
+export function readCitationMeta(corpusRoot, refId) {
+    const p = path.join(corpusRoot, ...CITES_DIR, `${refId}-citations.md`);
+    if (!fs.existsSync(p))
+        return { title: '', authors: [] };
+    const fm = parseFrontmatter(fs.readFileSync(p, 'utf-8'));
+    const title = typeof fm.title === 'string' ? fm.title.trim() : '';
+    const authors = [];
+    if (Array.isArray(fm.authors)) {
+        for (const a of fm.authors) {
+            if (a && typeof a === 'object' && 'name' in a && a.name) {
+                authors.push(String(a.name).trim());
+            }
+            else if (typeof a === 'string' && a.trim()) {
+                authors.push(a.trim());
+            }
+        }
+    }
+    return { title, authors };
+}
+/** Load every radar sidecar in the corpus (parsed meta + title + raw body). */
+export function loadRadars(corpusRoot) {
+    const out = [];
+    for (const refId of listRadarRefs(corpusRoot)) {
+        const meta = extractRadar(corpusRoot, refId);
+        if (!meta)
+            continue;
+        const full = path.join(radarDir(corpusRoot), `${refId}-radar.md`);
+        const text = fs.readFileSync(full, 'utf-8');
+        const fm = parseFrontmatter(text);
+        out.push({
+            refId,
+            meta,
+            title: typeof fm.title === 'string' ? fm.title.trim() : null,
+            relPath: path.relative(corpusRoot, full),
+            text,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=radar-shared.js.map

package/dist/src/artifacts/corpus-tools/radar-status.js

@@ -0,0 +1,68 @@
+/**
+ * radar-status — overdue/freshness report over all radar sidecars (#1498).
+ *
+ * Port of corpus/radar_staleness.py: computes staleness for every radar sidecar
+ * (shared computeStaleness), sorts most-overdue-first, and renders table / csv /
+ * list. on-demand and undatable radars sort last (no overdue).
+ *
+ * @source historical: corpus/radar_staleness.py
+ */
+import { computeStaleness } from '../corpus-views/corpus-config.js';
+import { loadRadars } from './radar-shared.js';
+function asOf(today) {
+    const iso = today ?? new Date().toISOString().slice(0, 10);
+    return new Date(`${iso}T00:00:00Z`);
+}
+/** Compute one status row per radar sidecar, sorted most-overdue-first. */
+export function radarStatusRows(corpusRoot, opts = {}) {
+    const today = asOf(opts.today);
+    const rows = loadRadars(corpusRoot).map((doc) => {
+        const s = computeStaleness(doc.meta.refreshCadence, doc.meta.lastRefreshed, today);
+        return {
+            refId: doc.refId,
+            cadence: doc.meta.refreshCadence ?? '?',
+            lastRefreshed: doc.meta.lastRefreshed ?? '',
+            daysSince: s.daysSince,
+            overdueDays: s.overdueDays,
+            isStale: s.isStale,
+            grade: doc.meta.gradeCurrent ?? doc.meta.gradeOriginal ?? '?',
+            trajectory: doc.meta.gradeTrajectory ?? 'stable',
+            cluster: doc.meta.cluster ?? '',
+        };
+    });
+    const filtered = opts.staleOnly ? rows.filter((r) => r.isStale) : rows;
+    // Most overdue first; non-overdue (null) sort after; ties by REF id.
+    return filtered.sort((a, b) => {
+        const ao = a.overdueDays ?? -Infinity;
+        const bo = b.overdueDays ?? -Infinity;
+        if (ao !== bo)
+            return bo - ao;
+        return a.refId < b.refId ? -1 : a.refId > b.refId ? 1 : 0;
+    });
+}
+/** Render status rows as a markdown table, CSV, or plain list. */
+export function renderRadarStatus(rows, format = 'table') {
+    if (format === 'csv') {
+        const head = 'ref,cadence,last_refreshed,days_since,overdue_days,is_stale,grade,trajectory,cluster';
+        const body = rows.map((r) => `${r.refId},${r.cadence},${r.lastRefreshed},${r.daysSince ?? ''},${r.overdueDays ?? ''},${r.isStale},${r.grade},${r.trajectory},${r.cluster}`);
+        return [head, ...body].join('\n') + '\n';
+    }
+    if (format === 'list') {
+        return (rows
+            .map((r) => {
+            const tag = r.isStale ? `OVERDUE +${r.overdueDays}d` : r.overdueDays === null ? 'n/a' : `ok (${-r.overdueDays}d left)`;
+            return `- ${r.refId} [${r.grade}] ${r.cadence} — last ${r.lastRefreshed || '?'} — ${tag}`;
+        })
+            .join('\n') + '\n');
+    }
+    // table
+    const lines = [
+        '| REF | GRADE | Cadence | Last Refreshed | Days Since | Overdue (days) | Stale |',
+        '|---|---|---|---|---:|---:|---|',
+    ];
+    for (const r of rows) {
+        lines.push(`| ${r.refId} | ${r.grade} | ${r.cadence} | ${r.lastRefreshed || '—'} | ${r.daysSince ?? '—'} | ${r.overdueDays ?? '—'} | ${r.isStale ? 'yes' : 'no'} |`);
+    }
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=radar-status.js.map