cli-jaw 2.2.4-preview.20260703203439 → 2.2.5

package/scripts/check-strict-baseline.mjs

@@ -106,6 +106,8 @@ function scanText(src, filename = 'inline.ts') {
     let any = 0;
     let debt = 0;
     let allow = 0;
+    let nonNull = 0;
+    let unknownCast = 0;
     function visit(node) {
         if (isAnyKeyword(node)) {
             const marker = leadingMarkerOnLine(src, node.getStart(sf));
@@ -113,10 +115,17 @@ function scanText(src, filename = 'inline.ts') {
             else if (marker === 'allow') allow++;
             else any++;
         }
+        if (node.kind === ts.SyntaxKind.NonNullExpression) nonNull++;
+        // `expr as unknown as T` — outer AsExpression whose inner expression is `as unknown`
+        if (ts.isAsExpression(node)
+            && ts.isAsExpression(node.expression)
+            && node.expression.type.kind === ts.SyntaxKind.UnknownKeyword) {
+            unknownCast++;
+        }
         ts.forEachChild(node, visit);
     }
     visit(sf);
-    return { any, debt, allow };
+    return { any, debt, allow, nonNull, unknownCast };
 }
 
 function scanFile(file) {
@@ -125,12 +134,14 @@ function scanFile(file) {
 }
 
 function countDir(absDir) {
-    const result = { any: 0, debt: 0, allow: 0 };
+    const result = { any: 0, debt: 0, allow: 0, nonNull: 0, unknownCast: 0 };
     for (const file of filesForPath(absDir)) {
         const r = scanFile(file);
         result.any += r.any;
         result.debt += r.debt;
         result.allow += r.allow;
+        result.nonNull += r.nonNull;
+        result.unknownCast += r.unknownCast;
     }
     return result;
 }
@@ -224,6 +235,19 @@ function main() {
     console.log('');
 
     console.log('## strict-baseline typecheck gates');
+
+    // Warn-only radar (WP4 4.5): non-null assertions and `as unknown as` double
+    // casts are tracked for visibility, not gated. Promote to the frozen
+    // baseline table once counts stabilize.
+    console.log('## escape-hatch radar (warn-only, not gated)');
+    console.log('| dir | non-null ! | as-unknown-as |');
+    console.log('|-----|-----------:|--------------:|');
+    for (const dir of TRACKED_DIRS) {
+        const l = live[dir];
+        console.log(`| ${dir} | ${l.nonNull} | ${l.unknownCast} |`);
+    }
+    console.log('');
+
     const rootTypecheck = runTypecheck(['tsc', '--noEmit']);
     console.log(`root: ${rootTypecheck.ok ? 'ok' : `fail (${rootTypecheck.status ?? 'unknown'})`}`);
     if (!rootTypecheck.ok) regressions.push(`root typecheck failed:\n${rootTypecheck.output}`);

package/scripts/docs/check-docs.mts

@@ -0,0 +1,87 @@
+// Phase 2A docs drift checker: compares live AST-extracted inventories
+// (commands, routes) against the summary claims in structure/*.md.
+// No generated JSON is committed; this computes live and compares.
+// Usage: npx tsx scripts/docs/check-docs.mts [--json]
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import { extractCommands } from './extract-commands.mts';
+import { extractRoutes } from './extract-routes.mts';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, '../..');
+
+interface DriftIssue {
+    doc: string;
+    claim: string;
+    actual: string;
+}
+
+function firstMatch(text: string, re: RegExp): string | null {
+    const m = text.match(re);
+    return m?.[1] ?? null;
+}
+
+export async function checkDocs(): Promise<DriftIssue[]> {
+    const issues: DriftIssue[] = [];
+
+    const [commands, routes, commandsDoc, serverApiDoc, indexDoc] = await Promise.all([
+        extractCommands(),
+        extractRoutes(),
+        readFile(join(root, 'structure/commands.md'), 'utf8'),
+        readFile(join(root, 'structure/server_api.md'), 'utf8'),
+        readFile(join(root, 'structure/INDEX.md'), 'utf8'),
+    ]);
+
+    // commands.md summary line claims
+    const docTotal = firstMatch(commandsDoc, /slash registry는 (\d+)개 커맨드/);
+    if (docTotal !== null && Number(docTotal) !== commands.totals.total) {
+        issues.push({ doc: 'structure/commands.md', claim: `slash registry ${docTotal}`, actual: String(commands.totals.total) });
+    }
+    const docNonHidden = firstMatch(commandsDoc, /non-hidden은 (\d+)개/);
+    if (docNonHidden !== null && Number(docNonHidden) !== commands.totals.nonHidden) {
+        issues.push({ doc: 'structure/commands.md', claim: `non-hidden ${docNonHidden}`, actual: String(commands.totals.nonHidden) });
+    }
+    const docCli = firstMatch(commandsDoc, /CLI (\d+) \/ Web/);
+    if (docCli !== null && Number(docCli) !== commands.totals.cliVisible) {
+        issues.push({ doc: 'structure/commands.md', claim: `CLI ${docCli}`, actual: String(commands.totals.cliVisible) });
+    }
+    const docWeb = firstMatch(commandsDoc, /Web (\d+) \/ Telegram/);
+    if (docWeb !== null && Number(docWeb) !== commands.totals.webVisible) {
+        issues.push({ doc: 'structure/commands.md', claim: `Web ${docWeb}`, actual: String(commands.totals.webVisible) });
+    }
+    const docRuntimes = firstMatch(commandsDoc, /(\d+)개다\.\s*$/m);
+    if (docRuntimes !== null && Number(docRuntimes) !== commands.runtimes.count) {
+        issues.push({ doc: 'structure/commands.md', claim: `runtimes ${docRuntimes}`, actual: String(commands.runtimes.count) });
+    }
+
+    // server_api.md + INDEX.md route totals
+    for (const [docName, text] of [['structure/server_api.md', serverApiDoc], ['structure/INDEX.md', indexDoc]] as const) {
+        for (const m of text.matchAll(/총 (\d+)개(?:의)? route handler/g)) {
+            if (Number(m[1]) !== routes.core.total) {
+                issues.push({ doc: docName, claim: `route handlers ${m[1]}`, actual: String(routes.core.total) });
+            }
+        }
+        for (const m of text.matchAll(/API 엔드포인트는 (\d+)개/g)) {
+            if (Number(m[1]) !== routes.core.apiTotal) {
+                issues.push({ doc: docName, claim: `API endpoints ${m[1]}`, actual: String(routes.core.apiTotal) });
+            }
+        }
+    }
+
+    return issues;
+}
+
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].split('/').pop() ?? '')) {
+    const issues = await checkDocs();
+    if (process.argv.includes('--json')) {
+        console.log(JSON.stringify({ ok: issues.length === 0, issues }, null, 2));
+    } else if (issues.length === 0) {
+        console.log('docs:check PASSED — commands/routes summaries match live inventory');
+    } else {
+        console.error(`docs:check FAILED — ${issues.length} drift issue(s):`);
+        for (const i of issues) console.error(`  - ${i.doc}: doc says "${i.claim}" vs actual ${i.actual}`);
+    }
+    process.exit(issues.length === 0 ? 0 : 1);
+}

package/scripts/docs/extract-commands.mts

@@ -0,0 +1,215 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import process from 'node:process';
+import ts from 'typescript';
+import { CLI_KEYS } from '../../src/cli/registry.ts';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, '../..');
+const commandsPath = join(root, 'src/cli/commands.ts');
+
+const SURFACES = ['cli', 'web', 'telegram', 'discord'] as const;
+const CMDLINE_HIDDEN = new Set([
+    'help',
+    'clear',
+    'model',
+    'cli',
+    'fallback',
+    'status',
+    'reset',
+    'skill',
+    'employee',
+    'mcp',
+    'memory',
+    'browser',
+    'prompt',
+    'version',
+]);
+
+type SlashSurface = typeof SURFACES[number];
+type CapabilityValue = 'full' | 'readonly' | 'hidden' | 'blocked' | string;
+
+export interface CommandInventoryEntry {
+    name: string;
+    interfaces: string[];
+    hidden: boolean;
+    cli: boolean;
+    web: boolean;
+    telegram: boolean;
+    discord: boolean;
+    cmdline: boolean;
+    description?: string;
+}
+
+export interface CommandsInventory {
+    commands: CommandInventoryEntry[];
+    totals: {
+        total: number;
+        nonHidden: number;
+        cliVisible: number;
+        webVisible: number;
+        telegramVisible: number;
+        discordVisible: number;
+        cmdlineVisible: number;
+    };
+    runtimes: {
+        keys: string[];
+        count: number;
+    };
+}
+
+interface ParsedCommand {
+    name: string;
+    interfaces: string[];
+    category?: string;
+    hidden: boolean;
+    description?: string;
+    capability: Partial<Record<string, CapabilityValue>>;
+}
+
+function propertyNameText(name: ts.PropertyName): string | null {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
+    return null;
+}
+
+function objectProperty(node: ts.ObjectLiteralExpression, name: string): ts.Expression | null {
+    for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const propName = propertyNameText(prop.name);
+        if (propName === name) return prop.initializer;
+    }
+    return null;
+}
+
+function stringProperty(node: ts.ObjectLiteralExpression, name: string): string | undefined {
+    const value = objectProperty(node, name);
+    if (!value || !ts.isStringLiteralLike(value)) return undefined;
+    return value.text;
+}
+
+function booleanProperty(node: ts.ObjectLiteralExpression, name: string): boolean {
+    const value = objectProperty(node, name);
+    if (!value) return false;
+    if (value.kind === ts.SyntaxKind.TrueKeyword) return true;
+    if (value.kind === ts.SyntaxKind.FalseKeyword) return false;
+    throw new Error(`COMMANDS.${name} must be a boolean literal`);
+}
+
+function stringArrayProperty(node: ts.ObjectLiteralExpression, name: string): string[] {
+    const value = objectProperty(node, name);
+    if (!value || !ts.isArrayLiteralExpression(value)) return [];
+    return value.elements.map(element => {
+        if (!ts.isStringLiteralLike(element)) {
+            throw new Error(`COMMANDS.${name} must contain only string literals`);
+        }
+        return element.text;
+    });
+}
+
+function capabilityProperty(node: ts.ObjectLiteralExpression): Partial<Record<string, CapabilityValue>> {
+    const value = objectProperty(node, 'capability');
+    if (!value) return {};
+    if (!ts.isObjectLiteralExpression(value)) throw new Error('COMMANDS.capability must be an object literal');
+
+    const out: Partial<Record<string, CapabilityValue>> = {};
+    for (const prop of value.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const key = propertyNameText(prop.name);
+        const initializer = prop.initializer;
+        if (!key || !ts.isStringLiteralLike(initializer)) continue;
+        out[key] = initializer.text;
+    }
+    return out;
+}
+
+function findCommandsArray(sourceFile: ts.SourceFile): ts.ArrayLiteralExpression {
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement)) continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== 'COMMANDS') continue;
+            if (!declaration.initializer || !ts.isArrayLiteralExpression(declaration.initializer)) {
+                throw new Error('COMMANDS must be initialized with an array literal');
+            }
+            return declaration.initializer;
+        }
+    }
+    throw new Error('Unable to find COMMANDS array in src/cli/commands.ts');
+}
+
+function parseCommandObject(node: ts.ObjectLiteralExpression): ParsedCommand {
+    const name = stringProperty(node, 'name');
+    if (!name) throw new Error('COMMANDS entry is missing a string name');
+
+    const description = stringProperty(node, 'desc');
+    return {
+        name,
+        interfaces: stringArrayProperty(node, 'interfaces'),
+        category: stringProperty(node, 'category'),
+        hidden: booleanProperty(node, 'hidden'),
+        ...(description === undefined ? {} : { description }),
+        capability: capabilityProperty(node),
+    };
+}
+
+function visibleOnSlashSurface(command: ParsedCommand, surface: SlashSurface): boolean {
+    if (command.hidden) return false;
+    if (!command.interfaces.includes(surface)) return false;
+    const capability = command.capability[surface];
+    if (capability !== undefined) return capability !== 'hidden' && capability !== 'blocked';
+    return true;
+}
+
+function visibleOnCmdline(command: ParsedCommand): boolean {
+    return !CMDLINE_HIDDEN.has(command.name) && command.category !== 'workflow';
+}
+
+async function parseCommands(): Promise<ParsedCommand[]> {
+    const source = await readFile(commandsPath, 'utf8');
+    const sourceFile = ts.createSourceFile(commandsPath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const commandsArray = findCommandsArray(sourceFile);
+    return commandsArray.elements.map(element => {
+        if (!ts.isObjectLiteralExpression(element)) throw new Error('COMMANDS must contain only object literals');
+        return parseCommandObject(element);
+    });
+}
+
+export async function extractCommands(): Promise<CommandsInventory> {
+    const parsedCommands = await parseCommands();
+    const commands = parsedCommands
+        .map(command => ({
+            name: command.name,
+            interfaces: [...command.interfaces].sort(),
+            hidden: command.hidden,
+            cli: visibleOnSlashSurface(command, 'cli'),
+            web: visibleOnSlashSurface(command, 'web'),
+            telegram: visibleOnSlashSurface(command, 'telegram'),
+            discord: visibleOnSlashSurface(command, 'discord'),
+            cmdline: visibleOnCmdline(command),
+            ...(command.description === undefined ? {} : { description: command.description }),
+        }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+
+    return {
+        commands,
+        totals: {
+            total: commands.length,
+            nonHidden: commands.filter(command => !command.hidden).length,
+            cliVisible: commands.filter(command => command.cli).length,
+            webVisible: commands.filter(command => command.web).length,
+            telegramVisible: commands.filter(command => command.telegram).length,
+            discordVisible: commands.filter(command => command.discord).length,
+            cmdlineVisible: commands.filter(command => command.cmdline).length,
+        },
+        runtimes: {
+            keys: [...CLI_KEYS].sort(),
+            count: CLI_KEYS.length,
+        },
+    };
+}
+
+const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : '';
+if (import.meta.url === invokedPath) {
+    const inventory = await extractCommands();
+    process.stdout.write(`${JSON.stringify(inventory, null, 2)}\n`);
+}