projscan 4.3.1 → 4.4.0

package/dist/types/inspection.d.ts

@@ -0,0 +1,47 @@
+import type { ExportInfo, ImportInfo, Issue } from './common.js';
+import type { FileHotspot } from './hotspots.js';
+export interface FileInspection {
+    relativePath: string;
+    exists: boolean;
+    reason?: string;
+    purpose: string;
+    lineCount: number;
+    sizeBytes: number;
+    imports: ImportInfo[];
+    exports: ExportInfo[];
+    potentialIssues: string[];
+    hotspot: FileHotspot | null;
+    issues: Issue[];
+    /** AST-derived McCabe complexity. null when no language adapter parsed this file. */
+    cyclomaticComplexity?: number | null;
+    /** Number of files that import this one. null when graph unavailable. */
+    fanIn?: number | null;
+    /** Number of locally-resolved imports this file makes. null when graph unavailable. */
+    fanOut?: number | null;
+    /** Adapter id (e.g. 'javascript', 'python'). Set when the graph was available. */
+    language?: string;
+    /**
+     * Per-function McCabe CC (0.13.0+). Sorted by cyclomaticComplexity desc.
+     * Empty array when the file has no functions or the adapter doesn't yet
+     * support per-function granularity.
+     */
+    functions?: FunctionDetail[];
+}
+/**
+ * Per-function CC entry exposed via projscan_file. Mirrors the internal
+ * `FunctionInfo` from `core/ast.ts` but is part of the stable API surface.
+ */
+export interface FunctionDetail {
+    name: string;
+    /** 1-based start line. */
+    line: number;
+    /** 1-based end line. */
+    endLine: number;
+    cyclomaticComplexity: number;
+    /**
+     * Approximate fan-in (0.15.0+): count of other files whose `callSites`
+     * include this function's bare name. Name-based and approximate; absent
+     * when the graph couldn't compute it.
+     */
+    fanIn?: number;
+}

package/dist/types/inspection.js

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

package/dist/types/inspection.js.map

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

package/dist/types/mcp.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A reversible deprecation marker (3.8 deprecation pass). Present on a tool
+ * means "still works, but slated for removal in 4.0 - prefer `replacedBy`".
+ */
+export interface ToolDeprecation {
+    /** Version the deprecation was announced in (e.g. "3.8.0"). */
+    since: string;
+    /** The recommended replacement (tool name for MCP, invocation for CLI). */
+    replacedBy: string;
+    /** Optional one-line rationale shown to humans/agents. */
+    note?: string;
+}
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    /** Set when the tool is deprecated and scheduled for removal in 4.0. */
+    deprecated?: ToolDeprecation;
+}
+export interface McpPromptArgument {
+    name: string;
+    description: string;
+    required?: boolean;
+}
+export interface McpPromptDefinition {
+    name: string;
+    description: string;
+    arguments?: McpPromptArgument[];
+}
+export interface McpResourceDefinition {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}

package/dist/types/mcp.js

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

package/dist/types/mcp.js.map

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

package/dist/types/pluginDx.d.ts

@@ -0,0 +1,42 @@
+import type { Issue, IssueSeverity } from './common.js';
+export interface PluginTestResult {
+    schemaVersion: 1;
+    manifestPath: string;
+    ok: boolean;
+    diagnostics: Array<{
+        code: string;
+        severity: IssueSeverity;
+        message: string;
+    }>;
+    trust: {
+        localOnly: true;
+        previewFlag: 'PROJSCAN_PLUGINS_PREVIEW=1';
+        reminder: string;
+    };
+    commands: {
+        validate: string;
+        test: string;
+        execute: string;
+        enable: string;
+    };
+    execution: {
+        requested: boolean;
+        executed: boolean;
+        mode: 'static' | 'execute';
+        note: string;
+    };
+    context: {
+        requested: boolean;
+        capabilities: Array<'semanticGraph' | 'dataflow'>;
+        note: string;
+    };
+    analyzer?: {
+        issues: Issue[];
+    };
+    reporter?: {
+        outputs: Array<{
+            command: string;
+            text: string;
+        }>;
+    };
+}

package/dist/types/pluginDx.js

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

package/dist/types/pluginDx.js.map

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

package/dist/types/prDiff.d.ts

@@ -0,0 +1,41 @@
+export interface ExportRename {
+    from: string;
+    to: string;
+}
+export interface FileAstDiff {
+    relativePath: string;
+    status: 'added' | 'removed' | 'modified';
+    exportsAdded: string[];
+    exportsRemoved: string[];
+    /**
+     * Heuristically-detected renames (0.11). When an export disappears from
+     * base AND a similar new name appears in head AND no other export matches,
+     * we report it here instead of as a +/- pair. Removed/added lists exclude
+     * any names that ended up in renames.
+     */
+    exportsRenamed: ExportRename[];
+    importsAdded: string[];
+    importsRemoved: string[];
+    callsAdded: string[];
+    callsRemoved: string[];
+    /** CC(head) - CC(base). null when either side wasn't AST-parsed. */
+    cyclomaticDelta: number | null;
+    /** fanIn(head) - fanIn(base). null when graph entry missing on either side. */
+    fanInDelta: number | null;
+}
+export interface PrDiffReport {
+    available: boolean;
+    reason?: string;
+    base: {
+        ref: string;
+        resolvedSha: string | null;
+    };
+    head: {
+        ref: string;
+        resolvedSha: string | null;
+    };
+    filesAdded: string[];
+    filesRemoved: string[];
+    filesModified: FileAstDiff[];
+    totalFilesChanged: number;
+}

package/dist/types/prDiff.js

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

package/dist/types/prDiff.js.map

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

package/dist/types/preflight.d.ts

@@ -0,0 +1,122 @@
+import type { IssueSeverity } from './common.js';
+import type { HealthScore } from './analysis.js';
+type PreflightReviewVerdict = 'ok' | 'review' | 'block';
+export type PreflightMode = 'before_edit' | 'before_commit' | 'before_merge';
+export type PreflightVerdict = 'proceed' | 'caution' | 'block';
+export type PreflightReasonSource = 'doctor' | 'review' | 'taint' | 'session' | 'plugin' | 'supply-chain' | 'memory' | 'changed-files' | 'hotspots' | 'git' | 'format' | 'release' | 'coordination';
+export interface PreflightReason {
+    severity: IssueSeverity;
+    source: PreflightReasonSource;
+    message: string;
+    file?: string;
+    issueId?: string;
+    tool?: string;
+}
+export interface PreflightRequiredCheck {
+    name: string;
+    status: 'pass' | 'warn' | 'fail' | 'unavailable';
+    reason?: string;
+}
+export interface PreflightSuggestedAction {
+    label: string;
+    command?: string;
+    tool?: string;
+    args?: Record<string, unknown>;
+}
+export interface PreflightReleaseScaleEvidence {
+    detected: boolean;
+    changedFiles: number;
+    threshold: number;
+    reviewVerdict?: PreflightReviewVerdict;
+    reviewSummary?: string;
+    concreteBlockers: string[];
+    explanation: string;
+}
+export interface PreflightEvidence {
+    health?: {
+        score: number;
+        grade: HealthScore['grade'];
+        errors: number;
+        warnings: number;
+        infos: number;
+    };
+    changedFiles?: {
+        available: boolean;
+        count: number;
+        files: string[];
+        reason?: string;
+    };
+    review?: {
+        available: boolean;
+        verdict?: PreflightReviewVerdict;
+        summary?: string;
+        reason?: string;
+    };
+    session?: {
+        kind?: 'remembered-session';
+        id: string;
+        touchedFiles: string[];
+        totalTouchedFiles?: number;
+        eventCount: number;
+        note?: string;
+        truncated?: boolean;
+    };
+    riskSources?: {
+        currentWorktree: {
+            kind: 'current-worktree';
+            available: boolean;
+            count: number;
+            files: string[];
+            baseRef: string | null;
+            reason?: string;
+        };
+        sessionMemory: {
+            kind: 'remembered-session';
+            id: string;
+            touchedFiles: string[];
+            totalTouchedFiles: number;
+            eventCount: number;
+            note: string;
+            truncated?: boolean;
+        };
+    };
+    hotspots?: {
+        touched: Array<{
+            file: string;
+            riskScore: number;
+        }>;
+    };
+    plugins?: {
+        enabled: boolean;
+        errorIssues: number;
+        warningIssues: number;
+    };
+    supplyChain?: {
+        errorIssues: number;
+        warningIssues: number;
+    };
+    releaseScale?: PreflightReleaseScaleEvidence;
+    coordination?: {
+        available: boolean;
+        readiness: 'clear' | 'caution' | 'conflicted';
+        worktreeCount: number;
+        collisions: {
+            high: number;
+            medium: number;
+        };
+        contendedClaims: number;
+    };
+}
+export interface PreflightReport {
+    schemaVersion: 1;
+    mode: PreflightMode;
+    verdict: PreflightVerdict;
+    summary: string;
+    reasons: PreflightReason[];
+    evidence: PreflightEvidence;
+    requiredChecks: PreflightRequiredCheck[];
+    suggestedNextActions: PreflightSuggestedAction[];
+    toolCalls: PreflightSuggestedAction[];
+    truncated?: boolean;
+}
+export {};

package/dist/types/preflight.js

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

package/dist/types/preflight.js.map

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

package/dist/types/qualityScorecard.d.ts

@@ -0,0 +1,34 @@
+import type { HealthScore } from './analysis.js';
+import type { PreflightSuggestedAction } from './preflight.js';
+import type { FixFirstRecommendation, WorkplanPriority } from './workplan.js';
+export type QualityScorecardVerdict = 'excellent' | 'healthy' | 'needs_attention' | 'blocked';
+export type QualityScorecardStatus = 'pass' | 'watch' | 'fail';
+export interface QualityScorecardDimension {
+    id: 'health' | 'security' | 'tests' | 'maintainability' | 'coordination';
+    label: string;
+    status: QualityScorecardStatus;
+    score: number;
+    summary: string;
+    evidence: string[];
+    commands: string[];
+}
+export interface QualityScorecardRisk {
+    id: string;
+    priority: WorkplanPriority;
+    title: string;
+    files: string[];
+    source: 'issue' | 'hotspot' | 'coordination';
+    command: string;
+}
+export interface QualityScorecardReport {
+    schemaVersion: 1;
+    verdict: QualityScorecardVerdict;
+    summary: string;
+    health: HealthScore;
+    dimensions: QualityScorecardDimension[];
+    topRisks: QualityScorecardRisk[];
+    fixFirst?: FixFirstRecommendation;
+    commands: string[];
+    suggestedNextActions: PreflightSuggestedAction[];
+    truncated?: boolean;
+}

package/dist/types/qualityScorecard.js

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

package/dist/types/qualityScorecard.js.map

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

package/dist/types/regressionPlan.d.ts

@@ -0,0 +1,32 @@
+import type { BugHuntVerdict } from './bugHunt.js';
+import type { PreflightSuggestedAction, PreflightVerdict } from './preflight.js';
+import type { WorkplanPriority, WorkplanVerification } from './workplan.js';
+export type RegressionPlanLevel = 'smoke' | 'focused' | 'full';
+export type RegressionPlanVerdict = 'ready' | 'needs_tests' | 'blocked';
+export interface RegressionPlanTarget {
+    id: string;
+    priority: WorkplanPriority;
+    source: 'baseline' | 'bug-hunt' | 'product-line' | 'preflight';
+    title: string;
+    why: string;
+    files: string[];
+    verification: WorkplanVerification;
+}
+export interface RegressionPlanReport {
+    schemaVersion: 1;
+    level: RegressionPlanLevel;
+    verdict: RegressionPlanVerdict;
+    summary: string;
+    releaseLines: string[];
+    evidence: {
+        healthScore: number;
+        bugHuntVerdict: BugHuntVerdict;
+        preflightVerdict: PreflightVerdict;
+        changedFiles: number;
+        touchedFiles: number;
+    };
+    targets: RegressionPlanTarget[];
+    commands: string[];
+    suggestedNextActions: PreflightSuggestedAction[];
+    truncated?: boolean;
+}

package/dist/types/regressionPlan.js

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

package/dist/types/regressionPlan.js.map

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

package/dist/types/releaseTrain.d.ts

@@ -0,0 +1,37 @@
+import type { PreflightSuggestedAction, PreflightVerdict } from './preflight.js';
+import type { WorkplanPriority, WorkplanVerification } from './workplan.js';
+export interface ReleaseTrainTrack {
+    line: string;
+    theme: string;
+    outcome: string;
+    includedInPlan: boolean;
+    scope: string[];
+    successCriteria: string[];
+}
+export interface ReleaseTrainTask {
+    id: string;
+    priority: WorkplanPriority;
+    title: string;
+    why: string;
+    track: string;
+    files: string[];
+    verification: WorkplanVerification;
+}
+export interface ReleaseTrainReport {
+    schemaVersion: 1;
+    currentVersion: string | null;
+    plan: {
+        policy: 'product-readiness-plan';
+        lines: string[];
+        readOnly: true;
+    };
+    readiness: {
+        verdict: PreflightVerdict;
+        blockers: number;
+        cautions: number;
+        summary: string;
+    };
+    tracks: ReleaseTrainTrack[];
+    tasks: ReleaseTrainTask[];
+    suggestedNextActions: PreflightSuggestedAction[];
+}

package/dist/types/releaseTrain.js

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

package/dist/types/releaseTrain.js.map

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

package/dist/types/review.d.ts

@@ -0,0 +1,203 @@
+import type { DataflowRiskConfidence, DataflowRiskKind, DataflowRiskSeverity, GraphEvidenceSummary } from './graph.js';
+import type { PrDiffReport } from './prDiff.js';
+import type { ReviewContractChange } from './reviewContract.js';
+/**
+ * One changed file enriched with risk signals. The agent calling
+ * projscan_review uses these to decide which files need careful review.
+ */
+export interface ReviewFile {
+    relativePath: string;
+    status: 'added' | 'removed' | 'modified';
+    /** Hotspot risk score for the head version. null when file isn't in the hotspot scope. */
+    riskScore: number | null;
+    /** Cyclomatic complexity at head. null when no AST adapter parsed it. */
+    cyclomaticComplexity: number | null;
+    /** Delta from the structural diff (mirrors FileAstDiff.cyclomaticDelta). null when file was added/removed. */
+    cyclomaticDelta: number | null;
+    /** Number of exports added in this PR. */
+    exportsAdded: number;
+    /** Number of exports removed in this PR. */
+    exportsRemoved: number;
+    /** Number of imports added. */
+    importsAdded: number;
+    /** Number of imports removed. */
+    importsRemoved: number;
+    /** 1.9+ - set when `projscan_review` was called with an `intent` arg. Absent otherwise. */
+    intentAlignment?: 'expected' | 'unexpected' | 'out-of-scope' | 'unknown';
+}
+/**
+ * A circular import that exists at head and either didn't exist at base or
+ * grew. Surfaced separately from the file list so reviewers see at-a-glance
+ * whether the PR introduces new architectural debt.
+ */
+export interface ReviewCycle {
+    files: string[];
+    size: number;
+    /**
+     * 'new' = no overlap with any base cycle; 'expanded' = at least one new
+     * file added to an existing cycle.
+     */
+    classification: 'new' | 'expanded';
+    /** 1.9+ - set when `projscan_review` was called with an `intent` arg. Absent otherwise. */
+    intentAlignment?: 'expected' | 'unexpected' | 'out-of-scope' | 'unknown';
+}
+/**
+ * A function whose CC newly crossed a worry threshold (>= 10) at head, or
+ * was added with high CC, or jumped by 5+ since base.
+ */
+export interface ReviewFunction {
+    file: string;
+    name: string;
+    line: number;
+    endLine: number;
+    cyclomaticComplexity: number;
+    /** CC at base. null when the function did not exist at base. */
+    baseCc: number | null;
+    /** Why this function shows up. */
+    reason: 'added' | 'jumped' | 'crossed-threshold';
+    /** 1.9+ - set when `projscan_review` was called with an `intent` arg. Absent otherwise. */
+    intentAlignment?: 'expected' | 'unexpected' | 'out-of-scope' | 'unknown';
+}
+/**
+ * 1.6+ - A taint flow that is NEW at head (not present at base). Mirrors
+ * the core TaintFlow shape but is intentionally light - review summaries
+ * should be readable in a glance, so we drop the per-step file list and
+ * keep only the source/sink, the function pair, and the path length.
+ */
+export interface ReviewTaintFlow {
+    sourceFn: string;
+    sinkFn: string;
+    source: string;
+    sink: string;
+    /** Hop count from source function to sink function, inclusive of both ends. */
+    pathLength: number;
+    /** First and last files in the path; same value when length = 1. */
+    files: string[];
+    /** 1.9+ - set when `projscan_review` was called with an `intent` arg. Absent otherwise. */
+    intentAlignment?: 'expected' | 'unexpected' | 'out-of-scope' | 'unknown';
+}
+/**
+ * 3.0+ - Review-time dataflow risks that are not represented by legacy
+ * taint reachability, especially bridge helpers that call both a source
+ * wrapper and a sink wrapper.
+ */
+export interface ReviewDataflowRisk {
+    kind: DataflowRiskKind;
+    sourceFn: string;
+    sinkFn: string;
+    bridgeFn?: string;
+    source: string;
+    sink: string;
+    pathLength: number;
+    files: string[];
+    severity: DataflowRiskSeverity;
+    confidence: DataflowRiskConfidence;
+    intentAlignment?: 'expected' | 'unexpected' | 'out-of-scope' | 'unknown';
+}
+/** Workspace-package-scoped dependency change. Aggregates root + workspaces. */
+export interface ReviewDependencyChange {
+    /** Workspace name; '' for the root manifest. */
+    workspace: string;
+    manifestFile: string;
+    added: Array<{
+        name: string;
+        version: string;
+        kind: 'dep' | 'dev';
+    }>;
+    removed: Array<{
+        name: string;
+        version: string;
+        kind: 'dep' | 'dev';
+    }>;
+    bumped: Array<{
+        name: string;
+        from: string;
+        to: string;
+        kind: 'dep' | 'dev';
+    }>;
+    /** 1.9+ - set when `projscan_review` was called with an `intent` arg. Absent otherwise. */
+    intentAlignment?: 'expected' | 'unexpected' | 'out-of-scope' | 'unknown';
+}
+/**
+ * 1.5+ - `projscan_review` can shape its response at three tiers based
+ * on a `max_cost_tokens` budget passed by the caller: full (no budget
+ * or large budget), summary (3K-7K tokens), verdict-only (<3K).
+ * Selected by `selectReviewTier` and surfaced as the `tier` field on
+ * the response.
+ */
+export type ReviewTier = 'full' | 'summary' | 'verdict-only';
+export interface ReviewReport {
+    available: boolean;
+    reason?: string;
+    base: {
+        ref: string;
+        resolvedSha: string | null;
+    };
+    head: {
+        ref: string;
+        resolvedSha: string | null;
+    };
+    /** The structural diff (same shape as projscan_pr_diff). */
+    prDiff: PrDiffReport;
+    /** Each changed file annotated with risk + CC + delta. Sorted by risk desc. */
+    changedFiles: ReviewFile[];
+    /** Cycles introduced or expanded by this PR. Empty when none. */
+    newCycles: ReviewCycle[];
+    /** Functions that meaningfully grew or were added with high CC. Sorted by CC desc. */
+    riskyFunctions: ReviewFunction[];
+    /** package.json deltas across root + workspaces. */
+    dependencyChanges: ReviewDependencyChange[];
+    /**
+     * 2.1+ - additive public contract changes such as export and package
+     * entrypoint changes. Empty or absent when no contract signal is available.
+     */
+    contractChanges?: ReviewContractChange[];
+    /**
+     * 1.6+ - NEW source-to-sink taint flows introduced by this PR. Each
+     * entry is a flow that exists at head but didn't exist at base
+     * (matched by sourceFn + sinkFn pair). Empty when taint is unavailable
+     * (no per-function callSites at either side).
+     */
+    newTaintFlows: ReviewTaintFlow[];
+    /**
+     * 3.0+ - NEW dataflow risks introduced by this PR that are outside the
+     * legacy source-to-sink taint flow list. Empty when unavailable or clean.
+     */
+    newDataflowRisks: ReviewDataflowRisk[];
+    /** 3.5+ - compact graph/dataflow evidence for review consumers. */
+    graphEvidence?: GraphEvidenceSummary;
+    /** 'ok' = ship it; 'review' = needs careful look; 'block' = strongly suggests rework. */
+    verdict: 'ok' | 'review' | 'block';
+    /** One-line bullets explaining the verdict. */
+    summary: string[];
+    /**
+     * 1.5+ - which tier this report was shaped at. Absent when the full
+     * report is returned without budget shaping.
+     */
+    tier?: ReviewTier;
+    /**
+     * 1.9+ - the parsed intent the agent passed (if any). Echo of the
+     * raw string + the parser's classified action + extracted scope
+     * tokens. Absent when `intent` arg wasn't provided.
+     */
+    intent?: {
+        raw: string;
+        action: 'feature' | 'fix' | 'refactor' | 'perf' | 'test' | 'docs' | 'chore' | 'remove' | 'unknown';
+        scopeTokens: string[];
+    };
+    /**
+     * 1.9+ - per-alignment totals across all findings + a small sample
+     * of "notable" (unexpected / out-of-scope) findings. Absent when
+     * no intent was provided. Verdict is NOT affected by intent -
+     * verdict stays structural.
+     */
+    intentAnalysis?: {
+        totals: Record<'expected' | 'unexpected' | 'out-of-scope' | 'unknown', number>;
+        notable: Array<{
+            kind: 'file' | 'function' | 'cycle' | 'taint' | 'dataflow' | 'dependency';
+            label: string;
+            alignment: 'expected' | 'unexpected' | 'out-of-scope' | 'unknown';
+            reason: string;
+        }>;
+    };
+}

package/dist/types/review.js

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

package/dist/types/review.js.map

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