projscan 4.7.0 → 4.9.1

package/dist/core/pluginReporterLoading.d.ts

@@ -0,0 +1,41 @@
+import type { PluginDiagnostic, PluginReporterCommand, PluginReporterManifest } from './pluginManifestValidation.js';
+export interface PluginReporterContext<TPayload = unknown> {
+    command: PluginReporterCommand;
+    rootPath: string;
+    manifest: PluginReporterManifest;
+    payload: TPayload;
+}
+export interface PluginReporterExports {
+    render: (context: PluginReporterContext) => Promise<string> | string;
+}
+export interface LoadedReporterPlugin {
+    manifest: PluginReporterManifest;
+    /** Absolute path to the manifest file on disk. */
+    manifestPath: string;
+    /** Absolute path to the resolved module entry point. */
+    modulePath: string;
+    exports: PluginReporterExports;
+}
+export type PluginReporterResolveResult = {
+    ok: true;
+    plugin: LoadedReporterPlugin;
+} | {
+    ok: false;
+    reason: string;
+    diagnostic: PluginDiagnostic;
+};
+export type PluginReporterRenderResult = {
+    ok: true;
+    output: string;
+} | {
+    ok: false;
+    reason: string;
+    diagnostic: PluginDiagnostic;
+};
+export interface PluginReporterResolveOptions {
+    pluginsEnabled: boolean;
+    previewFlag: string;
+}
+export declare function resolveReporterPlugin(rootPath: string, reporterName: string, command: PluginReporterCommand, options: PluginReporterResolveOptions): Promise<PluginReporterResolveResult>;
+export declare function renderReporterPlugin(plugin: LoadedReporterPlugin, context: PluginReporterContext): Promise<PluginReporterRenderResult>;
+export declare function loadReporterPlugin(manifest: PluginReporterManifest, manifestPath: string): Promise<PluginReporterResolveResult>;

package/dist/core/pluginReporterLoading.js

@@ -0,0 +1,105 @@
+import path from 'node:path';
+import { discoverPluginManifests } from './pluginManifestDiscovery.js';
+import { assertPluginModuleReadable, describePluginModuleLoadError, importPluginModule, } from './pluginModuleLoading.js';
+import { getPluginTrustStatus } from './pluginTrust.js';
+export async function resolveReporterPlugin(rootPath, reporterName, command, options) {
+    if (!options.pluginsEnabled) {
+        return pluginRuntimeFail({
+            code: 'plugins-disabled',
+            message: `reporter plugins require ${options.previewFlag}=1`,
+            hint: `Set ${options.previewFlag}=1 in the environment to enable plugin reporters.`,
+        });
+    }
+    const entries = await discoverPluginManifests(rootPath);
+    const reporters = entries.filter((entry) => entry.manifest?.kind === 'reporter');
+    const entry = reporters.find((candidate) => candidate.manifest.name === reporterName);
+    if (!entry) {
+        return pluginRuntimeFail({
+            code: 'reporter-not-found',
+            message: `reporter plugin "${reporterName}" was not found`,
+            hint: 'Run `projscan plugin list` to see discovered reporter plugins.',
+        });
+    }
+    if (!entry.manifest.commands.includes(command)) {
+        return pluginRuntimeFail({
+            code: 'reporter-unsupported-command',
+            message: `reporter plugin "${reporterName}" does not support command "${command}"`,
+            hint: `Add "${command}" to the reporter manifest's commands array or choose a different reporter.`,
+        });
+    }
+    return loadReporterPlugin(entry.manifest, entry.manifestPath);
+}
+export async function renderReporterPlugin(plugin, context) {
+    try {
+        const output = await plugin.exports.render(context);
+        if (typeof output !== 'string') {
+            return pluginRuntimeFail({
+                code: 'reporter-render-error',
+                message: `reporter plugin "${plugin.manifest.name}" returned ${typeof output}; expected string`,
+                hint: 'Reporter render(context) must return text for stdout.',
+            });
+        }
+        return { ok: true, output };
+    }
+    catch (err) {
+        return pluginRuntimeFail({
+            code: 'reporter-render-error',
+            message: `reporter plugin "${plugin.manifest.name}" failed during render: ${formatError(err)}`,
+            hint: 'Fix the reporter render(context) implementation and try again.',
+        });
+    }
+}
+export async function loadReporterPlugin(manifest, manifestPath) {
+    const modulePath = path.resolve(path.dirname(manifestPath), manifest.module);
+    try {
+        await assertPluginModuleReadable(manifest.module, modulePath);
+        // Importing a reporter executes local code, so trust must be checked first.
+        const trust = await getPluginTrustStatus(modulePath);
+        if (trust.status !== 'trusted') {
+            return pluginRuntimeFail(untrustedReporterDiagnostic(manifest.name, trust.status));
+        }
+        const mod = await importPluginModule(modulePath);
+        const exportsObj = (mod.default ?? mod);
+        if (typeof exportsObj.render !== 'function') {
+            return pluginRuntimeFail({
+                code: 'invalid-reporter-export',
+                message: `reporter plugin "${manifest.name}" missing required export "render"`,
+                hint: 'Use export default { render(context) { ... } } or export a named render function.',
+            });
+        }
+        return {
+            ok: true,
+            plugin: {
+                manifest,
+                manifestPath,
+                modulePath,
+                exports: { render: exportsObj.render },
+            },
+        };
+    }
+    catch (err) {
+        const detail = describePluginModuleLoadError(err, manifest.module, modulePath, 'reporter manifest');
+        return pluginRuntimeFail({
+            code: 'reporter-load-error',
+            message: `reporter plugin "${manifest.name}" failed to load: ${detail.message}`,
+            hint: detail.hint ?? 'Check the reporter module path and module syntax.',
+        });
+    }
+}
+function untrustedReporterDiagnostic(name, status) {
+    const changed = status === 'changed';
+    return {
+        code: 'plugin-untrusted',
+        message: changed
+            ? `reporter plugin "${name}" changed since it was trusted; not executed`
+            : `reporter plugin "${name}" is not trusted; not executed`,
+        hint: `${changed ? 'Re-run' : 'Run'} \`projscan plugin trust ${name}\` to approve this reporter.`,
+    };
+}
+function pluginRuntimeFail(diagnostic) {
+    return { ok: false, reason: diagnostic.message, diagnostic };
+}
+function formatError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=pluginReporterLoading.js.map

package/dist/core/pluginReporterLoading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginReporterLoading.js","sourceRoot":"","sources":["../../src/core/pluginReporterLoading.ts"],"names":[],"mappings":"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"}

package/dist/core/pluginRuntimeTypes.d.ts

@@ -0,0 +1,20 @@
+import type { CodeGraph } from './codeGraph.js';
+import type { DataflowReport, FileEntry, Issue, SemanticGraphReport } from '../types.js';
+import type { PluginAnalyzerManifest } from './pluginManifestValidation.js';
+export interface PluginAnalyzerContext {
+    schemaVersion: 1;
+    getCodeGraph: () => Promise<CodeGraph>;
+    getSemanticGraph: () => Promise<SemanticGraphReport>;
+    getDataflow: () => Promise<DataflowReport>;
+}
+export interface PluginAnalyzerExports {
+    check: (rootPath: string, files: FileEntry[], context?: PluginAnalyzerContext) => Promise<Issue[]> | Issue[];
+}
+export interface LoadedPlugin {
+    manifest: PluginAnalyzerManifest;
+    /** Absolute path to the manifest file on disk. */
+    manifestPath: string;
+    /** Absolute path to the resolved module entry point. */
+    modulePath: string;
+    exports: PluginAnalyzerExports;
+}

package/dist/core/pluginRuntimeTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pluginRuntimeTypes.js.map

package/dist/core/pluginRuntimeTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginRuntimeTypes.js","sourceRoot":"","sources":["../../src/core/pluginRuntimeTypes.ts"],"names":[],"mappings":""}

package/dist/core/plugins.d.ts

@@ -1,6 +1,6 @@
-import type { CodeGraph } from './codeGraph.js';
-import type { FileEntry, Issue, DataflowReport, SemanticGraphReport } from '../types.js';
-import type { PluginAnalyzerManifest, PluginDiagnostic, PluginManifest, PluginReporterCommand, PluginReporterManifest } from './pluginManifestValidation.js';
+import type { PluginReporterResolveResult } from './pluginReporterLoading.js';
+import type { LoadedPlugin } from './pluginRuntimeTypes.js';
+import type { PluginReporterCommand } from './pluginManifestValidation.js';
 /**
  * Stable local plugin API (2.0+).
  *
@@ -16,83 +16,15 @@ import type { PluginAnalyzerManifest, PluginDiagnostic, PluginManifest, PluginRe
  * discipline as the rest of projscan.
  */
 export declare const PLUGIN_PREVIEW_FLAG = "PROJSCAN_PLUGINS_PREVIEW";
-export declare const PLUGIN_DIR = ".projscan-plugins";
-export declare const PLUGIN_MANIFEST_EXT = ".projscan-plugin.json";
+export { PLUGIN_DIR, PLUGIN_MANIFEST_EXT, discoverPluginManifests, readPluginManifestFile, } from './pluginManifestDiscovery.js';
+export type { PluginDiscoveryEntry, PluginManifestFileResult } from './pluginManifestDiscovery.js';
+export type { LoadedPlugin, PluginAnalyzerContext, PluginAnalyzerExports, } from './pluginRuntimeTypes.js';
+export { runAnalyzerPlugins } from './pluginAnalyzerRunning.js';
 export { PLUGIN_REPORTER_COMMANDS, PLUGIN_SCHEMA_VERSION, validateManifest, } from './pluginManifestValidation.js';
 export type { PluginAnalyzerManifest, PluginDiagnostic, PluginKind, PluginManifest, PluginReporterCommand, PluginReporterManifest, } from './pluginManifestValidation.js';
-export interface PluginAnalyzerContext {
-    schemaVersion: 1;
-    getCodeGraph: () => Promise<CodeGraph>;
-    getSemanticGraph: () => Promise<SemanticGraphReport>;
-    getDataflow: () => Promise<DataflowReport>;
-}
-export interface PluginAnalyzerExports {
-    check: (rootPath: string, files: FileEntry[], context?: PluginAnalyzerContext) => Promise<Issue[]> | Issue[];
-}
-export interface PluginReporterContext<TPayload = unknown> {
-    command: PluginReporterCommand;
-    rootPath: string;
-    manifest: PluginReporterManifest;
-    payload: TPayload;
-}
-export interface PluginReporterExports {
-    render: (context: PluginReporterContext) => Promise<string> | string;
-}
-export interface LoadedPlugin {
-    manifest: PluginAnalyzerManifest;
-    /** Absolute path to the manifest file on disk. */
-    manifestPath: string;
-    /** Absolute path to the resolved module entry point. */
-    modulePath: string;
-    exports: PluginAnalyzerExports;
-}
-export interface LoadedReporterPlugin {
-    manifest: PluginReporterManifest;
-    /** Absolute path to the manifest file on disk. */
-    manifestPath: string;
-    /** Absolute path to the resolved module entry point. */
-    modulePath: string;
-    exports: PluginReporterExports;
-}
-export interface PluginDiscoveryEntry {
-    manifestPath: string;
-    manifest: PluginManifest | null;
-    /** Set when the manifest failed to parse or validate. */
-    error?: string;
-    diagnostic?: PluginDiagnostic;
-}
-export type PluginManifestFileResult = {
-    ok: true;
-    manifest: PluginManifest;
-} | {
-    ok: false;
-    reason: string;
-    diagnostic: PluginDiagnostic;
-};
-export type PluginReporterResolveResult = {
-    ok: true;
-    plugin: LoadedReporterPlugin;
-} | {
-    ok: false;
-    reason: string;
-    diagnostic: PluginDiagnostic;
-};
-export type PluginReporterRenderResult = {
-    ok: true;
-    output: string;
-} | {
-    ok: false;
-    reason: string;
-    diagnostic: PluginDiagnostic;
-};
+export { renderReporterPlugin } from './pluginReporterLoading.js';
+export type { LoadedReporterPlugin, PluginReporterContext, PluginReporterExports, PluginReporterRenderResult, PluginReporterResolveResult, } from './pluginReporterLoading.js';
 export declare function pluginsEnabled(): boolean;
-export declare function readPluginManifestFile(manifestPath: string): Promise<PluginManifestFileResult>;
-/**
- * Discover every plugin manifest under `<root>/.projscan-plugins/`. Manifests
- * that fail to parse or validate are returned with `manifest: null` and an
- * `error` so the CLI / MCP tool can surface them without throwing.
- */
-export declare function discoverPluginManifests(rootPath: string): Promise<PluginDiscoveryEntry[]>;
 /**
  * Discover, validate, and dynamically import every plugin under the
  * project. Returns [] when the preview flag is off.
@@ -103,12 +35,3 @@ export declare function discoverPluginManifests(rootPath: string): Promise<Plugi
  */
 export declare function loadPlugins(rootPath: string): Promise<LoadedPlugin[]>;
 export declare function resolveReporterPlugin(rootPath: string, reporterName: string, command: PluginReporterCommand): Promise<PluginReporterResolveResult>;
-export declare function renderReporterPlugin(plugin: LoadedReporterPlugin, context: PluginReporterContext): Promise<PluginReporterRenderResult>;
-/**
- * Run every loaded analyzer plugin against `files`. Issues that don't pass
- * a tight shape check are dropped so a malformed plugin can't poison the
- * issue stream. Each plugin's output is also re-stamped with `id` prefixed
- * by the plugin name (so two plugins emitting the same local rule id can't
- * collide).
- */
-export declare function runAnalyzerPlugins(plugins: LoadedPlugin[], rootPath: string, files: FileEntry[], context?: PluginAnalyzerContext): Promise<Issue[]>;