@geastack/compiler 1.0.15

package/dist/cli-coverage.js

@@ -0,0 +1,329 @@
+import { relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { compile } from './compiler.js';
+import { nodeOfOperation, operationOfResult } from './identity/ids.js';
+import { capabilityFamilies, familyOf, isCapabilityKey } from './ir/certify.js';
+import { obligationKinds } from './preflight/obligations.js';
+import { dynamicReasons } from './representation/model.js';
+import { primitiveFamilies } from './semantics/model/coverage.js';
+import { findProjectFile } from './semantics/program.js';
+const isRecord = (value) => typeof value === 'object' && value !== null;
+const parseArguments = (argv) => {
+    let entry = null;
+    let projectFileName = 'discover';
+    let plugin = null;
+    const pluginOptions = new Map();
+    let json = false;
+    let derived = true;
+    let boxed = true;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index] ?? '';
+        if (argument === '--project') {
+            projectFileName = argv[index + 1] ?? null;
+            index += 1;
+        }
+        else if (argument === '--no-project') {
+            projectFileName = null;
+        }
+        else if (argument === '--plugin') {
+            plugin = argv[index + 1] ?? null;
+            index += 1;
+        }
+        else if (argument === '--plugin-option') {
+            const pair = argv[index + 1] ?? '';
+            const split = pair.indexOf('=');
+            if (split > 0)
+                pluginOptions.set(pair.slice(0, split), pair.slice(split + 1));
+            index += 1;
+        }
+        else if (argument === '--json') {
+            json = true;
+        }
+        else if (argument === '--no-derived') {
+            derived = false;
+        }
+        else if (argument === '--no-boxed') {
+            boxed = false;
+        }
+        else if (!argument.startsWith('--') && entry === null) {
+            entry = argument;
+        }
+    }
+    return { entry, projectFileName, plugin, pluginOptions, json, derived, boxed };
+};
+/**
+ * The plugin module's factory, the same contract `analyze` reads: the default
+ * export, or the one exported function, called with no arguments. A host such
+ * as node-compat (`plugin/v2.mjs`) exports `geatscNodePluginV2` this way.
+ */
+const loadPlugin = async (modulePath) => {
+    const loaded = await import(pathToFileURL(resolve(modulePath)).href);
+    if (!isRecord(loaded))
+        return null;
+    const exported = loaded['default'] ?? Object.values(loaded).find((value) => typeof value === 'function');
+    if (typeof exported !== 'function')
+        return null;
+    const plugin = exported();
+    if (!isRecord(plugin) || typeof plugin['instantiate'] !== 'function' || typeof plugin['name'] !== 'string')
+        return null;
+    return plugin;
+};
+// ---------------------------------------------------------------------------
+// The code tables. Order is the contract: a new entry goes at the END.
+// ---------------------------------------------------------------------------
+const emissionCategories = [
+    'call',
+    'construct',
+    'compute',
+    'class-property',
+    'class-static-property',
+    'tagged-union-property',
+    'try',
+    'value-conversion',
+    'test',
+    'super-initialize',
+    'regexp-property',
+    'value-definition',
+    'spread-copy',
+    'return',
+    'receiver',
+    'host-method',
+    'host-call',
+    'element',
+    'date-property',
+    'data-view-property',
+    'array-buffer-property',
+    'allocate-callable',
+    'allocate-array-object'
+];
+const dynamicReasonLabels = {
+    'opt-in-fallback': 'dynamic fallback requested (--dynamic-fallback)',
+    'tostring-of-unknown': 'ToString of a value the program never narrows',
+    'thrown-error-carrier': 'a thrown value; JavaScript does not type throws',
+    'unasserted-json-parse': 'JSON.parse with no `as T`',
+    'declared-any-never-narrowed': 'declared any/unknown and never narrowed'
+};
+const code = (layer, index) => `G${layer}${String(index).padStart(3, '0')}`;
+const tableCode = (layer, table, key) => {
+    const index = table.indexOf(key);
+    return code(layer, index < 0 ? 999 : index + 1);
+};
+/** The obligation kind a `preflight/...` diagnostic row came from, by joining on its id. */
+const obligationIndex = (result) => new Map(result.preflight.obligations.map((obligation) => [`preflight/${obligation.id}`, obligation]));
+/**
+ * The emitter's category, read off the refusal text it wrote
+ * (`cpp emission refuses to lower "<kind>": ...`, `emit-context.ts`). The
+ * reason is the one place the emitter states its category to a caller, and it
+ * is quoted on purpose so this read is a fixed-delimiter slice, not a guess.
+ */
+const emissionCategoryOf = (reason) => {
+    const marker = 'refuses to lower "';
+    const start = reason.indexOf(marker);
+    if (start < 0)
+        return '';
+    const from = start + marker.length;
+    const end = reason.indexOf('"', from);
+    return end < 0 ? '' : reason.slice(from, end);
+};
+const diagnosticRow = (diagnostic, obligations) => {
+    const location = diagnostic.location;
+    const base = { file: location?.file ?? null, line: location?.line ?? 0, column: location?.column ?? 0, count: 1 };
+    if (diagnostic.id.startsWith('checker/')) {
+        return { ...base, code: code(1, 0), status: 'typecheck', layer: 'typecheck', message: diagnostic.message };
+    }
+    if (diagnostic.id.startsWith('census/')) {
+        const family = diagnostic.missingPrimitive;
+        const rowCode = family === null ? code(2, 0) : tableCode(2, primitiveFamilies, family);
+        return { ...base, code: rowCode, status: statusOf(diagnostic), layer: 'census', message: diagnostic.message };
+    }
+    if (diagnostic.id.startsWith('representation/')) {
+        return { ...base, code: code(3, 1), status: statusOf(diagnostic), layer: 'representation', message: diagnostic.message };
+    }
+    if (diagnostic.id.startsWith('preflight/')) {
+        const obligation = obligations.get(diagnostic.id);
+        const rowCode = obligation ? tableCode(4, obligationKinds, obligation.kind) : code(4, 999);
+        const layer = obligation ? `preflight/${obligation.kind}` : 'preflight';
+        return { ...base, code: rowCode, status: statusOf(diagnostic), layer, message: diagnostic.message };
+    }
+    return { ...base, code: code(1, 999), status: statusOf(diagnostic), layer: 'frontend', message: diagnostic.message };
+};
+const statusOf = (diagnostic) => diagnostic.severity === 'derived' ? 'derived' : diagnostic.severity === 'unsupported' ? 'unsupported' : 'refused';
+const componentRow = (rowCode, layer, owner, reason) => ({
+    file: null,
+    line: 0,
+    column: 0,
+    code: rowCode,
+    status: 'refused',
+    layer,
+    message: `${owner}: ${reason}`,
+    count: 1
+});
+/**
+ * Every selected carrier that is the box, placed at the operation that
+ * produced it. Several results of one operation (a call's value and its
+ * completion, say) box for one reason at one place; those fold into one row
+ * with a count so a hundred rows do not stand for one line.
+ */
+const boxedRows = (result) => {
+    const folded = new Map();
+    for (const [resultId, carrier] of result.representations.plan.selected) {
+        if (carrier.kind !== 'dynamic')
+            continue;
+        let location = null;
+        try {
+            location = result.locationOfNode(nodeOfOperation(operationOfResult(resultId)));
+        }
+        catch {
+            location = null;
+        }
+        const rowCode = tableCode(8, dynamicReasons, carrier.reason);
+        const key = `${location?.file ?? ''}|${location?.line ?? 0}|${location?.column ?? 0}|${rowCode}`;
+        const existing = folded.get(key);
+        if (existing) {
+            folded.set(key, { ...existing, count: existing.count + 1 });
+            continue;
+        }
+        folded.set(key, {
+            file: location?.file ?? null,
+            line: location?.line ?? 0,
+            column: location?.column ?? 0,
+            code: rowCode,
+            status: 'boxed',
+            layer: 'carrier',
+            message: `boxed as gea::Value: ${dynamicReasonLabels[carrier.reason] ?? carrier.reason}`,
+            count: 1
+        });
+    }
+    return [...folded.values()];
+};
+const collectRows = (result, options) => {
+    const obligations = obligationIndex(result);
+    const rows = [];
+    for (const diagnostic of result.diagnostics.diagnostics) {
+        if (!options.derived && diagnostic.severity === 'derived')
+            continue;
+        rows.push(diagnosticRow(diagnostic, obligations));
+    }
+    for (const blocker of result.loweringBlockers)
+        rows.push(componentRow(code(5, 1), 'lowering', blocker.owner, blocker.reason));
+    for (const refusal of result.emissionRefusals) {
+        rows.push(componentRow(tableCode(6, emissionCategories, emissionCategoryOf(refusal.reason)), 'emission', refusal.owner, refusal.reason));
+    }
+    for (const blocker of result.abiBlockers)
+        rows.push(componentRow(code(7, 1), 'abi', blocker.functionId, blocker.reason));
+    // The certification's refusals are `CompileResult.refusals` at stage
+    // `certify`, never diagnostics: they are read off the lowered IR, after the
+    // sweep that gates lowering has already run (the certifier has already passed). Keyed by capability family so the same missing recipe demanded from
+    // many bodies is one code.
+    for (const refusal of result.refusals) {
+        // A certify-stage refusal always carries a capability key; the other
+        // stages' sentinel keys (`abi:blocked`, ...) are excluded by the stage test.
+        if (refusal.stage !== 'certify' || !isCapabilityKey(refusal.key))
+            continue;
+        rows.push(componentRow(tableCode(9, capabilityFamilies, familyOf(refusal.key)), `certify/${familyOf(refusal.key)}`, refusal.owner, `${refusal.key}: ${refusal.reason}`));
+    }
+    if (options.boxed)
+        rows.push(...boxedRows(result));
+    return rows;
+};
+const summarize = (result) => {
+    const carriers = result.representations.plan.selected.size;
+    const boxed = [...result.representations.plan.selected.values()].filter((carrier) => carrier.kind === 'dynamic').length;
+    const diagnostics = result.diagnostics.diagnostics;
+    const typecheckErrors = diagnostics.filter((row) => row.id.startsWith('checker/')).length;
+    return {
+        operations: result.graph.operations.size,
+        carriers,
+        native: carriers - boxed,
+        boxed,
+        refusedRoots: diagnostics.filter((row) => row.severity === 'root' && !row.id.startsWith('checker/')).length,
+        derived: diagnostics.filter((row) => row.severity === 'derived').length,
+        unsupported: diagnostics.filter((row) => row.severity === 'unsupported').length,
+        typecheckErrors,
+        loweringBlockers: result.loweringBlockers.length,
+        emissionRefusals: result.emissionRefusals.length,
+        abiBlockers: result.abiBlockers.length,
+        certifyRefusals: result.refusals.filter((refusal) => refusal.stage === 'certify').length,
+        certified: result.certificate !== null,
+        emittedLines: result.source === null ? 0 : result.source.split('\n').length
+    };
+};
+const compareRows = (left, right) => {
+    const leftFile = left.file ?? '~';
+    const rightFile = right.file ?? '~';
+    if (leftFile !== rightFile)
+        return leftFile < rightFile ? -1 : 1;
+    if (left.line !== right.line)
+        return left.line - right.line;
+    if (left.column !== right.column)
+        return left.column - right.column;
+    return left.code < right.code ? -1 : left.code > right.code ? 1 : 0;
+};
+const renderText = (entry, project, rows, summary) => {
+    const cwd = process.cwd();
+    const lines = [];
+    lines.push(`coverage  ${relative(cwd, entry)}  (project: ${project ? relative(cwd, project) : 'none'})`);
+    let currentFile = undefined;
+    for (const row of rows) {
+        if (row.file !== currentFile) {
+            currentFile = row.file;
+            lines.push('');
+            lines.push(row.file === null ? '(no source position)' : relative(cwd, row.file));
+        }
+        const where = row.file === null ? '' : `${row.line}:${row.column}`;
+        const times = row.count > 1 ? ` (x${row.count})` : '';
+        lines.push(`  ${where.padEnd(9)} ${row.code}  ${row.status.padEnd(11)} ${row.message}${times}`);
+    }
+    lines.push('');
+    lines.push(`summary: ${summary.operations} operations, ${summary.carriers} carriers (${summary.native} native, ${summary.boxed} boxed); ` +
+        `${summary.refusedRoots} refused root(s), ${summary.derived} derived, ${summary.unsupported} unsupported, ${summary.typecheckErrors} typecheck error(s); ` +
+        `${summary.loweringBlockers} lowering blocker(s), ${summary.certifyRefusals} capability refusal(s), ` +
+        `${summary.emissionRefusals} emission refusal(s), ${summary.abiBlockers} abi blocker(s)`);
+    lines.push(summary.certified
+        ? `certificate: minted; emitted ${summary.emittedLines} line(s) of C++`
+        : 'certificate: not minted; nothing is emitted');
+    const byCode = new Map();
+    for (const row of rows) {
+        const bucket = byCode.get(row.code) ?? { layer: row.layer, count: 0 };
+        bucket.count += row.count;
+        byCode.set(row.code, bucket);
+    }
+    if (byCode.size > 0) {
+        lines.push('by code:');
+        for (const [rowCode, bucket] of [...byCode.entries()].sort(([left], [right]) => (left < right ? -1 : 1))) {
+            lines.push(`  ${rowCode}  ${bucket.layer.padEnd(30)} x${bucket.count}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+};
+export const runCoverage = async (argv) => {
+    const parsed = parseArguments(argv);
+    if (parsed.entry === null) {
+        process.stderr.write('usage: geatsc coverage <entry> [--project <tsconfig.json>] [--no-project] [--plugin <module>] [--plugin-option k=v]... [--json] [--no-derived] [--no-boxed]\n');
+        return 1;
+    }
+    const entry = resolve(parsed.entry);
+    const plugin = parsed.plugin === null ? null : await loadPlugin(parsed.plugin);
+    if (parsed.plugin !== null && plugin === null) {
+        process.stderr.write(`coverage: ${parsed.plugin} does not export a compiler plugin factory\n`);
+        return 1;
+    }
+    const projectFileName = parsed.projectFileName === 'discover'
+        ? findProjectFile(entry.slice(0, Math.max(0, entry.lastIndexOf('/'))) || '.')
+        : parsed.projectFileName;
+    const result = compile({
+        rootFileNames: [entry],
+        projectFileName,
+        ...(plugin ? { plugins: [plugin] } : {}),
+        pluginOptions: new Map(parsed.pluginOptions)
+    });
+    const rows = [...collectRows(result, parsed)].sort(compareRows);
+    const summary = summarize(result);
+    if (parsed.json) {
+        process.stdout.write(`${JSON.stringify({ entry, project: projectFileName, summary, rows }, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(renderText(entry, projectFileName, rows, summary));
+    }
+    return summary.certified && summary.loweringBlockers === 0 && summary.emissionRefusals === 0 ? 0 : 1;
+};

package/dist/cli-emit.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runs the pipeline and writes what it produced.
+ *
+ * The certificate gate is not re-litigated here: `compile` refuses to lower
+ * anything without one, so `source === null` is already the complete answer
+ * that this program is not yet compilable, and this command's job is to report
+ * that with the same detail the diagnostic CLI would rather than to write a
+ * partial unit the caller would try to build.
+ */
+export declare const runEmit: (argv: readonly string[], moduleGraph?: boolean) => Promise<number>;