council-review 0.1.1 → 0.2.0

package/README.md

@@ -20,12 +20,22 @@ handoff prompt addressed to a coding agent (`HANDOFF.md`).
 npm install -g council-review
 ```
 
-For unreleased changes from `main`, install straight from GitHub instead:
+For unreleased changes from `main`, build from a clone:
 
 ```
-npm install -g github:ad-005/council-review
+git clone https://github.com/ad-005/council-review
+cd council-review
+npm install
+npm pack
+npm install -g ./council-review-*.tgz
 ```
 
+Installing straight from the git URL is unreliable across npm versions: on the npm bundled with
+Node 22 (10.x) `npm install -g github:ad-005/council-review` fails, because npm installs no
+dependencies into its temporary clone and the `prepare` build cannot run; npm 12 fixed that but
+disables git fetching by default, so it needs `--allow-git=all`. `npx github:ad-005/council-review`
+works on npm 10, and needs `--allow-git=all` on npm 12.
+
 Requires the `pi` coding-agent CLI (`@earendil-works/pi-coding-agent`) on `PATH`, authenticated
 for at least one provider through `pi`'s own credential store — a key that exists only as a shell
 variable never reaches a reviewer, because reviewer processes get a tight environment allowlist.

package/dist/blast-radius.d.ts

@@ -0,0 +1,228 @@
+import type { ResolvedScope } from './scope.js';
+/** Maximum callers shown per symbol at render time. */
+export declare const BLAST_RADIUS_CALLERS_LIMIT = 20;
+/** `--limit` passed to every `callers` query: one past the render cap, so a full page
+ *  proves truncation and the block can disclose it instead of rendering a truncated
+ *  list as complete. The binary reports no total count, so this detects truncation
+ *  honestly without claiming an exact hidden remainder. */
+export declare const BLAST_RADIUS_CALLERS_QUERY_LIMIT: number;
+/** `impact` is traced when a symbol's caller count exceeds this, or when the symbol's kind
+ *  marks it as shared surface (see `IMPACT_ALWAYS_KINDS`). Keeps the common small-change
+ *  case to one query per symbol. */
+export declare const BLAST_RADIUS_IMPACT_CALLER_THRESHOLD = 2;
+/** Symbol kinds treated as exported/shared surface: `impact` is always traced for these,
+ *  even with few direct callers. */
+export declare const IMPACT_ALWAYS_KINDS: ReadonlySet<string>;
+/** Per-query subprocess timeout. */
+export declare const BLAST_RADIUS_QUERY_TIMEOUT_MS = 60000;
+/** Maximum concurrent `codegraph` subprocesses. */
+export declare const BLAST_RADIUS_CONCURRENCY = 4;
+export type PatchFileStatus = 'modified' | 'added' | 'deleted' | 'renamed';
+export interface PatchHunk {
+    /** 1-based start line on the new-file (+) side. 0 for a pure context-less deletion hunk
+     *  (`+0,0`), which maps to no end-state symbol. */
+    start: number;
+    /** Number of new-side lines in the hunk (0 for deletion-only hunks). */
+    count: number;
+}
+export interface PatchFile {
+    /** Post-image path, or the pre-image path for deleted files. */
+    path: string;
+    /** Pre-image path. */
+    oldPath: string;
+    status: PatchFileStatus;
+    hunks: PatchHunk[];
+}
+/**
+ * Parses a unified `git diff` into per-file paths, hunk ranges, and change kinds. Pure
+ * function of its input. Handles new files (`--- /dev/null`), deleted files
+ * (`+++ /dev/null`), renames (`rename from/to` or differing `---`/`+++` paths), binary
+ * diffs (emitted with zero hunks so they still feed the `affected` query), and multi-hunk
+ * files. Only headers are inspected, and `---`/`+++` path headers are only accepted
+ * before the first hunk header of each file section (real headers always precede the
+ * hunks, including `/dev/null` ones): a deleted `-- x` or added `++ y` content line
+ * would otherwise mimic a path header once prefixed with `-`/`+` and corrupt the paths.
+ */
+export declare function parsePatchHunks(patch: string): PatchFile[];
+export interface FileSymbol {
+    name: string;
+    kind: string;
+    startLine: number;
+}
+export type SymbolsOnlyParse = {
+    status: 'ok';
+    symbols: FileSymbol[];
+    dependents: string[];
+} | {
+    status: 'not-in-index';
+} | {
+    status: 'malformed';
+};
+/**
+ * Parses `codegraph node --file <rel> --symbols-only` (text; the one subcommand with no
+ * JSON mode). `not-in-index` (the binary's `No indexed file matches` message) and
+ * `malformed` are distinct: the former names a removed/unindexed file, the latter degrades
+ * that file to a file-level entry while other files keep symbol granularity. Unparseable
+ * lines inside an otherwise well-formed map are ignored for forward compatibility; only a
+ * map with no `**Symbols**` section at all is `malformed`.
+ */
+export declare function parseSymbolsOnlyMap(output: string): SymbolsOnlyParse;
+export interface ChangedSymbol {
+    name: string;
+    kind: string;
+    file: string;
+    startLine: number;
+}
+/**
+ * Maps each hunk to its enclosing symbol: the last symbol with
+ * `startLine <= hunk.start` in the same file (end lines are inferred positionally, so a
+ * hunk above the first symbol maps to nothing). Deduped and sorted by
+ * (file, startLine, name).
+ */
+export declare function mapHunksToSymbols(file: string, hunks: readonly PatchHunk[], symbols: readonly FileSymbol[]): ChangedSymbol[];
+/** `node --file <rel> --symbols-only`: the per-file symbol map (text output). */
+export declare function buildNodeSymbolsOnlyArgv(snapshotRoot: string, relPath: string): string[];
+/** `callers -j`: direct callers of one symbol as JSON. Name-only: codegraph v1.6.0
+ *  accepts no file scope for `callers` (verified empirically — no flag, no
+ *  `file:symbol` syntax), so same-named symbols elsewhere merge into the result. */
+export declare function buildCallersArgv(snapshotRoot: string, symbol: string, limit?: number): string[];
+/** `impact -j`: transitive impact of one symbol as JSON. Name-only, like `callers`:
+ *  no file scope exists, so same-named symbols elsewhere merge into the result. */
+export declare function buildImpactArgv(snapshotRoot: string, symbol: string, depth: number): string[];
+/** `affected -j`: affected tests for all changed files in one call. */
+export declare function buildAffectedArgv(snapshotRoot: string, files: readonly string[]): string[];
+export interface CodeRef {
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+}
+export type RefsParse = {
+    status: 'ok';
+    refs: CodeRef[];
+} | {
+    status: 'not-found';
+} | {
+    status: 'malformed';
+};
+export type AffectedParse = {
+    status: 'ok';
+    changedFiles: string[];
+    affectedTests: string[];
+} | {
+    status: 'malformed';
+};
+/** Parses `callers -j` (`{ symbol, callers: [...] }`). Unknown symbols yield `not-found`,
+ *  not `malformed`. */
+export declare function parseCallersJson(output: string): RefsParse;
+/** Parses `impact -j` (`{ symbol, depth, ..., affected: [...] }`). */
+export declare function parseImpactJson(output: string): RefsParse;
+/** Parses `affected -j` (`{ changedFiles: [...], affectedTests: [...] }`). Unknown files
+ *  simply contribute no tests — there is no not-found shape. */
+export declare function parseAffectedJson(output: string): AffectedParse;
+/**
+ * Best-effort filtering for one symbol's refs (callers or impact nodes):
+ * - drops same-name symbols from other files (ambiguous with this symbol's own
+ *   definition; a same-name ref only counts with a file match),
+ * - drops file-level-only (`kind: 'file'`) refs unless nothing else references the
+ *   symbol, in which case they are kept rather than reporting zero refs,
+ * - dedupes and sorts (codepoint order) for determinism.
+ *
+ * Residual over-approximation, stated explicitly: the queries are name-only —
+ * codegraph v1.6.0 offers no file scoping for `callers`/`impact` (verified empirically:
+ * no flag, no `file:symbol` syntax) and the JSON exposes no resolved definition site
+ * for caller refs, which carry caller identity only. When two files define the same
+ * symbol name, their callers merge indistinguishably and this filter cannot attribute
+ * them, so the block over-approximates by design. Only same-name definition entries
+ * (notably `impact` root nodes) are attributable, via the file match above.
+ */
+export declare function filterRefs(refs: readonly CodeRef[], opts: {
+    symbolName: string;
+    symbolFile: string;
+}): CodeRef[];
+/**
+ * Whether `impact` is worth tracing for a symbol: always for shared-surface kinds, or
+ * when the caller count exceeds the threshold (narrowly-referenced private symbols keep
+ * the run to one query each).
+ */
+export declare function shouldTraceImpact(symbol: Pick<ChangedSymbol, 'kind'>, callerCount: number): boolean;
+export type SymbolQueryFailure = 'query-failed' | 'parse-failed';
+export interface SymbolBlast {
+    symbol: ChangedSymbol;
+    /** Filtered direct callers. Null when the callers query itself failed. */
+    callers: CodeRef[] | null;
+    /** True when the callers query returned a full page (`BLAST_RADIUS_CALLERS_QUERY_LIMIT`
+     *  raw refs), proving truncation: more callers may exist beyond those listed. */
+    callersTruncated?: boolean;
+    /** Filtered transitive impact, minus the symbol's own root entry. Null when impact was
+     *  not traced (below threshold) or its query failed — see `impactTraced`/`failure`. */
+    impact: CodeRef[] | null;
+    impactTraced: boolean;
+    /** Set when a per-symbol query failed; the symbol still renders with an in-block note. */
+    failure?: SymbolQueryFailure;
+}
+export interface FileFallbackBlast {
+    file: string;
+    /** Best-effort dependents from the symbol-map header; empty when unknown. */
+    dependents: string[];
+}
+export interface RenderInput {
+    symbols: readonly SymbolBlast[];
+    fileFallbacks: readonly FileFallbackBlast[];
+    removedSymbols: readonly ChangedSymbol[];
+    /** Files deleted by the patch. */
+    removedFiles: readonly string[];
+    /** Files present in the patch but absent from the index (not deleted). */
+    unindexedFiles: readonly string[];
+    affectedTests: readonly string[];
+    /** `affected` query outcome when no test list could be produced. */
+    affectedFailure?: SymbolQueryFailure;
+    /** Symbols cut by `maxSymbols` (sorted first, so these are the trailing ones). */
+    omittedSymbols: number;
+    omittedTests?: number;
+    depth: number;
+    maxBlockChars: number;
+}
+/**
+ * Renders the blast-radius block: compact text with `file:line` anchors. Inputs are
+ * re-sorted defensively so rendering is a pure, deterministic function. Overflow (symbol
+ * cap) and removals are disclosed in-block; when the rendered text exceeds
+ * `maxBlockChars` it is truncated to exactly the cap with a trailing truncation note.
+ */
+export declare function renderBlastRadiusBlock(input: RenderInput): string;
+export type BlastRadiusReason = 'disabled' | 'index-unavailable' | 'query-failed' | 'parse-failed' | 'empty';
+export interface BlastRadiusStats {
+    /** Traced changed symbols rendered in the block (excludes removed/file-level entries). */
+    symbols: number;
+    /** Total callers listed across traced symbols. */
+    callers: number;
+    /** Affected tests listed. */
+    tests: number;
+}
+export interface BlastRadiusResult {
+    available: boolean;
+    reason?: BlastRadiusReason;
+    /** The rendered block, or '' when unavailable. */
+    block: string;
+    stats: BlastRadiusStats;
+}
+export interface ComputeBlastRadiusOptions {
+    enabled?: boolean;
+    indexAvailable?: boolean;
+    bin?: string;
+    depth?: number;
+    maxSymbols?: number;
+    maxBlockChars?: number;
+    timeoutMs?: number;
+    concurrency?: number;
+}
+/**
+ * Computes the blast radius for one run. Never throws for a blast-radius outcome: every
+ * spawn failure, timeout, and parse failure degrades to a reason (or, where a per-file /
+ * per-symbol fallback applies, to a partial block with an in-block note), as do
+ * data-dependent argv-validation failures (odd paths from the diff, odd symbol names
+ * from the index). Throws only for caller bugs (invalid snapshot root / options),
+ * matching `buildCodegraphArgv`'s validate-then-spawn precedent.
+ */
+export declare function computeBlastRadius(snapshotRoot: string, scope: ResolvedScope, opts?: ComputeBlastRadiusOptions): Promise<BlastRadiusResult>;
+//# sourceMappingURL=blast-radius.d.ts.map

package/dist/blast-radius.d.ts.map

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