@0xcraft/powershot 1.0.1 → 1.1.1

package/dist/selftest.js

@@ -50,9 +50,10 @@ import { sarif } from './report/sarif.js';
 import { markdown } from './report/markdown.js';
 import { wrap } from './report/terminal.js';
 import { highlight, isJsx } from './report/highlight.js';
-import { normalizeName, readEnvManifest, relPath } from './ground.js';
+import { buildGround, normalizeName, readEnvManifest, relPath } from './ground.js';
 import { incompleteReasons } from './bench.js';
 import { PACKAGE_NAME, PACKAGE_VERSION } from './package-meta.js';
+import { addedLinesFromPatch, createReviewPayload, GitHubPullRequestApi, inlineMarker, parseReviewFindings, reconcileInlineComments, selectInlineComments, syncInlineComments, } from './github/inline-comments.js';
 const root = '/repo';
 /** Build a Ground by hand so verifiers are testable without git or a real repo. */
 function ground(files, deps = []) {
@@ -89,7 +90,7 @@ function ground(files, deps = []) {
             symbolIndex.set(key, list);
         }
     }
-    return { root, project, beforeProject, changed, files: entries, symbolIndex, deps: new Set(deps), depsFor: () => new Set(deps), typed: false, internalPrefixes: [], foreign: [] };
+    return { root, sourceFiles: project.getSourceFiles(), configFiles: [], beforeProject, changed, files: entries, symbolIndex, deps: new Set(deps), depsFor: () => new Set(deps), typed: false, internalPrefixes: [], foreign: [] };
 }
 let failures = 0;
 function check(name, fn) {
@@ -653,6 +654,210 @@ const sample = [
     { id: 'F2', class: 'judged', check: 'plausible-logic', severity: 'low', confidence: 'tentative',
         file: 'src/b.ts', line: 9, title: 'off by one' },
 ];
+check('GitHub patches expose only added right-side lines for inline comments', () => {
+    const patch = [
+        '@@ -1,3 +1,4 @@',
+        ' context',
+        '-old',
+        '+new',
+        '+extra',
+        ' tail',
+        '@@ -20,0 +22,2 @@',
+        '+later',
+        '\',
+        '+latest',
+    ].join('\n');
+    assert.deepEqual([...addedLinesFromPatch(patch)], [2, 3, 22, 23]);
+});
+check('inline review selects only proven medium-or-higher verified findings on added lines', () => {
+    const finding = (overrides) => ({
+        id: 'F', class: 'verified', check: 'phantom-dep', severity: 'high', confidence: 'proven',
+        file: 'src/a.ts', line: 3, title: 'finding', ...overrides,
+    });
+    const findings = [
+        finding({ id: 'critical', severity: 'critical', line: 4, title: 'critical finding' }),
+        finding({ id: 'medium', severity: 'medium', line: 3, title: 'medium finding' }),
+        finding({ id: 'context', line: 2 }),
+        finding({ id: 'low', severity: 'low' }),
+        finding({ id: 'judged', class: 'judged' }),
+        finding({ id: 'firm', confidence: 'firm' }),
+        finding({ id: 'other-file', file: 'src/missing.ts' }),
+    ];
+    const files = [{ filename: 'src/a.ts', patch: '@@ -2,1 +2,3 @@\n context\n+first\n+second' }];
+    assert.deepEqual(selectInlineComments(findings, files).map((comment) => comment.line), [4, 3]);
+    assert.deepEqual(selectInlineComments(findings, files, 1).map((comment) => comment.line), [4]);
+    assert.deepEqual(selectInlineComments(findings, files, 0), []);
+    const many = Array.from({ length: 12 }, (_, index) => finding({ line: index + 3, title: `finding ${index}` }));
+    const manyPatch = '@@ -2,0 +3,12 @@\n' + many.map((_, index) => `+line ${index}`).join('\n');
+    assert.equal(selectInlineComments(many, [{ filename: 'src/a.ts', patch: manyPatch }], 100).length, 10);
+});
+check('inline comment markdown renders finding prose literally and carries a stable marker', () => {
+    const finding = {
+        id: 'F1', class: 'verified', check: 'check`id', severity: 'high', confidence: 'proven',
+        file: 'src/a.ts', line: 3, title: '@team <img src=x> [click](https://example.invalid)',
+        evidence: { oracle: 'manifest', detail: 'line one\n> forged quote' },
+    };
+    const [comment] = selectInlineComments([finding], [{ filename: finding.file, patch: '@@ -2,0 +3,1 @@\n+line' }]);
+    assert.ok(comment);
+    assert.equal(comment.body.includes('@team'), false);
+    assert.equal(comment.body.includes('<img'), false);
+    assert.equal(comment.body.includes('[click]('), false);
+    assert.equal(comment.body.endsWith(inlineMarker(finding)), true);
+    assert.equal(comment.body.match(/<!-- powershot:inline:/g)?.length, 1);
+});
+check('inline publishing rejects a malformed machine report instead of silently dropping it', () => {
+    assert.deepEqual(parseReviewFindings(JSON.stringify({ findings: [sample[0]] })), [sample[0]]);
+    assert.throws(() => parseReviewFindings(JSON.stringify({ findings: [{ ...sample[0], line: 0 }] })), /invalid contract/);
+    assert.throws(() => parseReviewFindings('{}'), /findings array/);
+});
+check('inline reruns keep exact bot comments, batch only missing ones, and retire stale bot copies', () => {
+    const findings = [
+        { id: 'F1', class: 'verified', check: 'a', severity: 'critical', confidence: 'proven', file: 'a.ts', line: 1, title: 'one' },
+        { id: 'F2', class: 'verified', check: 'b', severity: 'high', confidence: 'proven', file: 'b.ts', line: 2, title: 'two' },
+    ];
+    const desired = selectInlineComments(findings, [
+        { filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' },
+        { filename: 'b.ts', patch: '@@ -1,0 +2,1 @@\n+two' },
+    ]);
+    const existing = [
+        { id: 1, path: desired[0].path, line: desired[0].line, body: desired[0].body, user: { login: 'github-actions[bot]' } },
+        { id: 2, path: desired[0].path, line: desired[0].line, body: desired[0].body, user: { login: 'github-actions[bot]' } },
+        { id: 3, path: desired[0].path, line: desired[0].line, body: 'old\n' + inlineMarker(findings[0]), user: { login: 'github-actions[bot]' } },
+        { id: 4, path: desired[1].path, line: desired[1].line, body: desired[1].body, user: { login: 'human' } },
+        { id: 5, path: desired[0].path, line: desired[0].line, body: 'discussion', user: { login: 'human' }, inReplyToId: 2 },
+        { id: 6, path: desired[0].path, line: desired[0].line, body: 'discussed old\n' + inlineMarker(findings[0]), user: { login: 'github-actions[bot]' } },
+        { id: 7, path: desired[0].path, line: desired[0].line, body: 'still investigating', user: { login: 'human' }, inReplyToId: 6 },
+    ];
+    const plan = reconcileInlineComments(desired, existing);
+    assert.equal(plan.kept, 1);
+    assert.deepEqual(plan.create, [desired[1]]);
+    assert.deepEqual(plan.staleIds, [1, 3]);
+    const settled = reconcileInlineComments(desired, desired.map((comment, index) => ({
+        id: index + 10, path: comment.path, line: comment.line, body: comment.body,
+        user: { login: 'github-actions[bot]' },
+    })));
+    assert.deepEqual(settled, { create: [], staleIds: [], kept: 2 });
+});
+check('the batched GitHub review carries the required comment body and current commit', () => {
+    const comment = { path: 'a.ts', line: 1, side: 'RIGHT', body: 'finding' };
+    const payload = createReviewPayload('a'.repeat(40), [comment]);
+    assert.equal(payload.commit_id, 'a'.repeat(40));
+    assert.equal(payload.event, 'COMMENT');
+    assert.match(payload.body, /1 proven verified finding/);
+    assert.deepEqual(payload.comments, [comment]);
+});
+await checkAsync('the GitHub client paginates files, submits the review contract, and treats delete 404 as settled', async () => {
+    const originalFetch = globalThis.fetch;
+    const calls = [];
+    const json = (value, init = {}) => new Response(JSON.stringify(value), { status: 200, ...init });
+    const fakeFetch = async (input, init) => {
+        const url = String(input);
+        const method = init?.method ?? 'GET';
+        const body = typeof init?.body === 'string' ? init.body : undefined;
+        calls.push({ url, method, body });
+        assert.equal(new Headers(init?.headers).get('authorization'), 'Bearer token');
+        if (url.endsWith('/pulls/7'))
+            return json({ head: { sha: 'a'.repeat(40) } });
+        if (url.includes('/pulls/7/files') && !url.includes('page=2')) {
+            return json([{ filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' }], {
+                headers: { link: '<https://api.github.test/repos/acme/repo/pulls/7/files?per_page=100&page=2>; rel="next"' },
+            });
+        }
+        if (url.includes('/pulls/7/files') && url.includes('page=2')) {
+            return json([{ filename: 'b.bin' }]);
+        }
+        if (url.includes('/pulls/7/comments')) {
+            return json([
+                { id: 9, path: 'a.ts', line: 1, body: 'old', user: { login: 'github-actions[bot]' } },
+                { id: 10, path: 'a.ts', line: 1, body: 'reply', in_reply_to_id: 9, user: { login: 'human' } },
+            ]);
+        }
+        if (method === 'POST' && url.endsWith('/pulls/7/reviews'))
+            return json({ id: 1 });
+        if (method === 'DELETE' && url.endsWith('/pulls/comments/9'))
+            return json({ message: 'gone' }, { status: 404 });
+        return json({ message: 'unexpected request' }, { status: 500 });
+    };
+    globalThis.fetch = fakeFetch;
+    try {
+        const api = new GitHubPullRequestApi('https://api.github.test', 'token', 'acme', 'repo', 7);
+        assert.equal(await api.headSha(), 'a'.repeat(40));
+        assert.deepEqual(await api.listFiles(), [
+            { filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' },
+            { filename: 'b.bin', patch: undefined },
+        ]);
+        const comments = await api.listReviewComments();
+        assert.equal(comments[0]?.id, 9);
+        assert.equal(comments[1]?.inReplyToId, 9);
+        await api.createReview('a'.repeat(40), [{ path: 'a.ts', line: 1, side: 'RIGHT', body: 'finding' }]);
+        await api.deleteReviewComment(9);
+    }
+    finally {
+        globalThis.fetch = originalFetch;
+    }
+    const submitted = calls.find((call) => call.method === 'POST');
+    assert.ok(submitted?.body);
+    assert.deepEqual(JSON.parse(submitted.body), {
+        commit_id: 'a'.repeat(40),
+        body: 'PowerShot posted 1 proven verified finding(s) on changed lines.',
+        event: 'COMMENT',
+        comments: [{ path: 'a.ts', line: 1, side: 'RIGHT', body: 'finding' }],
+    });
+    assert.equal(calls.filter((call) => call.url.includes('/files')).length, 2);
+});
+await checkAsync('inline synchronization creates one review before removing stale comments', async () => {
+    const finding = {
+        id: 'F1', class: 'verified', check: 'a', severity: 'high', confidence: 'proven',
+        file: 'a.ts', line: 1, title: 'one',
+    };
+    const events = [];
+    const api = {
+        headSha: async () => 'a'.repeat(40),
+        listFiles: async () => [{ filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' }],
+        listReviewComments: async () => [{
+                id: 7, path: 'old.ts', line: 1,
+                body: 'old\n<!-- powershot:inline:v1:0123456789abcdef01234567 -->',
+                user: { login: 'github-actions[bot]' },
+            }],
+        createReview: async (commitId, comments) => {
+            events.push(`create:${commitId}:${comments.length}`);
+        },
+        deleteReviewComment: async (id) => {
+            events.push(`delete:${id}`);
+        },
+    };
+    const result = await syncInlineComments(api, [finding], 'a'.repeat(40));
+    assert.deepEqual(events, [`create:${'a'.repeat(40)}:1`, 'delete:7']);
+    assert.deepEqual(result, { outdated: false, desired: 1, created: 1, kept: 0, retired: 1 });
+});
+await checkAsync('inline synchronization makes no writes for an outdated pull request head', async () => {
+    let reads = 0;
+    const api = {
+        headSha: async () => 'b'.repeat(40),
+        listFiles: async () => { reads++; return []; },
+        listReviewComments: async () => { reads++; return []; },
+        createReview: async () => { throw new Error('must not create'); },
+        deleteReviewComment: async () => { throw new Error('must not delete'); },
+    };
+    const result = await syncInlineComments(api, [], 'a'.repeat(40));
+    assert.equal(reads, 0);
+    assert.deepEqual(result, { outdated: true, desired: 0, created: 0, kept: 0, retired: 0 });
+});
+await checkAsync('inline synchronization makes no writes when the pull request head changes during reads', async () => {
+    let headReads = 0;
+    let writes = 0;
+    const api = {
+        headSha: async () => ++headReads === 1 ? 'a'.repeat(40) : 'b'.repeat(40),
+        listFiles: async () => [{ filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' }],
+        listReviewComments: async () => [],
+        createReview: async () => { writes++; },
+        deleteReviewComment: async () => { writes++; },
+    };
+    const result = await syncInlineComments(api, [sample[0]], 'a'.repeat(40));
+    assert.equal(headReads, 2);
+    assert.equal(writes, 0);
+    assert.deepEqual(result, { outdated: true, desired: 0, created: 0, kept: 0, retired: 0 });
+});
 check('nested modules use the native package import map', () => {
     const manifest = JSON.parse(readFileSync(join(process.cwd(), 'package.json'), 'utf8'));
     assert.equal(manifest.imports?.['#app/*.js'], './dist/*.js');
@@ -687,7 +892,9 @@ check('self-review publishes machine findings only for a complete verdict', () =
     const workflow = readFileSync(join(process.cwd(), '.github', 'workflows', 'review.yml'), 'utf8');
     assert.equal(workflow.match(/node "\$PSH" review/g)?.length, 1);
     assert.match(workflow, /name: Check out the untrusted review target[\s\S]+allow-unsafe-pr-checkout: true/);
+    assert.match(workflow, /name: Install the target type environment[\s\S]+working-directory: target[\s\S]+npm ci --ignore-scripts/);
     assert.match(workflow, /steps\.review\.outputs\.status == '0' \|\| steps\.review\.outputs\.status == '1'/);
+    assert.match(workflow, /sarif_file: powershot\.sarif\s+checkout_path: target\s+ref: refs\/pull\/\$\{\{ github\.event\.pull_request\.number \}\}\/head\s+sha: \$\{\{ github\.event\.pull_request\.head\.sha \}\}/);
 });
 check('the public action persists judge answers and publishes only a verdict', () => {
     const action = readFileSync(join(process.cwd(), 'action.yml'), 'utf8');
@@ -696,17 +903,23 @@ check('the public action persists judge answers and publishes only a verdict', (
     assert.match(action, /restore-keys:/);
     assert.match(action, /upload-sarif:\s*\n\s+description: [^\n]+\n\s+default: 'true'/);
     assert.match(action, /Upload SARIF[\s\S]+inputs\.upload-sarif == 'true'[\s\S]+steps\.review\.outputs\.complete == 'true'/);
+    assert.match(action, /inline-comments:\s*\n\s+description: [^\n]+\n\s+default: 'false'/);
+    assert.match(action, /Post inline comments[\s\S]+inputs\.inline-comments == 'true'[\s\S]+steps\.review\.outputs\.complete == 'true'/);
+    assert.match(action, /node "\$GITHUB_ACTION_PATH\/dist\/github\/inline-comments\.js"/);
 });
 check('published CI examples preserve one verdict and its exit status', () => {
     const action = readFileSync(join(process.cwd(), 'examples', 'github-actions', 'action.yml'), 'utf8');
     const github = readFileSync(join(process.cwd(), 'examples', 'github-actions', 'cli.yml'), 'utf8');
     const gitlab = readFileSync(join(process.cwd(), 'examples', 'gitlab', '.gitlab-ci.yml'), 'utf8');
     assert.match(action, /upload-sarif: 'true'/);
-    assert.match(github, /npm install --global --ignore-scripts @0xcraft\/powershot@1\.0\.1/);
+    assert.match(action, /inline-comments: 'true'/);
+    assert.match(action, /runs-on: ubuntu-24\.04/);
+    assert.match(action, /npm ci --ignore-scripts[\s\S]+uses: xcrft\/powershot@v1/);
+    assert.match(github, /npm install --global --ignore-scripts @0xcraft\/powershot@1\.1\.1/);
     assert.equal(github.match(/psh review/g)?.length, 1);
     assert.match(github, /--report markdown=powershot\.md[\s\S]+--report sarif=powershot\.sarif/);
     assert.match(github, /\|\| STATUS=\$\?[\s\S]+case "\$STATUS"/);
-    assert.match(gitlab, /npm install --global --ignore-scripts @0xcraft\/powershot@1\.0\.1/);
+    assert.match(gitlab, /npm install --global --ignore-scripts @0xcraft\/powershot@1\.1\.1/);
     assert.equal(gitlab.match(/psh review/g)?.length, 1);
     assert.match(gitlab, /--format codequality > gl-code-quality-report\.json \|\| STATUS=\$\?/);
     assert.match(gitlab, /test "\$STATUS" -le 1 \|\| exit "\$STATUS"/);
@@ -1168,6 +1381,155 @@ check('refuses to run without a tsconfig rather than guessing', () => {
     const g = ground([{ path: 'a.ts', after: 'export const x = totallyUnknownGlobal\n' }]);
     assert.equal(phantomApi.run(g).length, 0);
 });
+await checkAsync('an unresolved type environment is partial, not a proven phantom API', async () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), 'psh-phantom-api-types-')));
+    try {
+        mkdirSync(join(dir, 'src'));
+        writeFileSync(join(dir, 'tsconfig.json'), JSON.stringify({
+            compilerOptions: {
+                target: 'ES2023', module: 'ESNext', moduleResolution: 'Bundler', lib: ['ES2023'], strict: true,
+            },
+            include: ['src'],
+        }));
+        const source = "import { fileURLToPath } from 'node:url'\nexport const here = fileURLToPath(import.meta.url)\n";
+        writeFileSync(join(dir, 'src', 'a.ts'), source);
+        const result = await review({
+            root: dir,
+            range: {},
+            changes: [{ path: 'src/a.ts', added: new Set([1, 2]) }],
+            config: loadConfig(dir),
+            verifyOnly: true,
+            checks: ['phantom-api'],
+        });
+        assert.deepEqual(result.findings, []);
+        assert.deepEqual(result.plan?.items()[0]?.missing, ['types']);
+        assert.deepEqual(result.skippedChecks, [{ check: 'phantom-api', missing: 'types' }]);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+await checkAsync('phantom-api still proves a property error with a complete type environment', async () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), 'psh-phantom-api-complete-')));
+    try {
+        mkdirSync(join(dir, 'src'));
+        writeFileSync(join(dir, 'tsconfig.json'), JSON.stringify({
+            compilerOptions: {
+                target: 'ES2023', module: 'ESNext', moduleResolution: 'Bundler', lib: ['ES2023'], strict: true,
+            },
+            include: ['src'],
+        }));
+        const source = "export const value = 'ok'.definitelyMissing()\n";
+        writeFileSync(join(dir, 'src', 'a.ts'), source);
+        const result = await review({
+            root: dir,
+            range: {},
+            changes: [{ path: 'src/a.ts', added: new Set([1]) }],
+            config: loadConfig(dir),
+            verifyOnly: true,
+            checks: ['phantom-api'],
+        });
+        assert.equal(result.findings.length, 1);
+        assert.equal(result.findings[0]?.check, 'phantom-api');
+        assert.equal(result.findings[0]?.confidence, 'proven');
+        assert.deepEqual(result.skippedChecks, []);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+await checkAsync('nested solution and leaf configs type both source and excluded test files', async () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), 'psh-nested-tsconfig-')));
+    try {
+        const web = join(dir, 'packages', 'web');
+        mkdirSync(join(web, 'src'), { recursive: true });
+        writeFileSync(join(web, 'tsconfig.json'), JSON.stringify({
+            files: [],
+            references: [{ path: './tsconfig.app.json' }],
+        }));
+        writeFileSync(join(web, 'tsconfig.app.json'), JSON.stringify({
+            compilerOptions: {
+                target: 'ES2023', module: 'ESNext', moduleResolution: 'Bundler', strict: true,
+            },
+            include: ['src'],
+            exclude: ['src/**/*.test.ts'],
+        }));
+        writeFileSync(join(web, 'src', 'existing.ts'), "export const existing = 'ok'\n");
+        writeFileSync(join(web, 'src', 'app.ts'), "export const app = 'ok'.definitelyMissing()\n");
+        writeFileSync(join(web, 'src', 'app.test.ts'), "export const test = 'ok'.alsoMissing()\n");
+        // An unrelated broken project must never be opened just because it is somewhere
+        // in the same monorepo.
+        mkdirSync(join(dir, 'packages', 'unrelated'), { recursive: true });
+        writeFileSync(join(dir, 'packages', 'unrelated', 'tsconfig.json'), '{broken');
+        const changes = [
+            { path: 'packages/web/src/app.ts', added: new Set([1]) },
+            { path: 'packages/web/src/app.test.ts', added: new Set([1]) },
+        ];
+        const result = await review({
+            root: dir,
+            range: {},
+            changes,
+            config: loadConfig(dir),
+            verifyOnly: true,
+            checks: ['phantom-api'],
+        });
+        assert.equal(result.findings.length, 2);
+        assert.deepEqual(result.skippedChecks, []);
+        assert.deepEqual(result.plan?.items().map((item) => item.missing), [undefined, undefined]);
+        const g = await buildGround(dir, changes);
+        assert.deepEqual(g.configFiles, ['packages/web/tsconfig.app.json']);
+        assert.deepEqual(g.files.map((file) => file.typed), [true, true]);
+        assert.equal(g.sourceFiles.length, 3);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+await checkAsync('one review can reuse several independent package projects', async () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), 'psh-many-projects-')));
+    try {
+        const changes = [];
+        for (const name of ['api', 'web']) {
+            const packageDir = join(dir, 'packages', name);
+            mkdirSync(join(packageDir, 'src'), { recursive: true });
+            writeFileSync(join(packageDir, 'tsconfig.json'), JSON.stringify({
+                compilerOptions: { target: 'ES2023', module: 'ESNext', strict: true },
+                include: ['src'],
+            }));
+            writeFileSync(join(packageDir, 'src', 'one.ts'), 'export const one = 1\n');
+            writeFileSync(join(packageDir, 'src', 'two.ts'), 'export const two = 2\n');
+            changes.push({ path: 'packages/' + name + '/src/one.ts', added: new Set([1]) }, { path: 'packages/' + name + '/src/two.ts', added: new Set([1]) });
+        }
+        const g = await buildGround(dir, changes);
+        assert.deepEqual(g.configFiles, [
+            'packages/api/tsconfig.json',
+            'packages/web/tsconfig.json',
+        ]);
+        assert.deepEqual(g.files.map((file) => file.typed), [true, true, true, true]);
+        assert.equal(g.sourceFiles.length, 4);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+await checkAsync('a configless repository parses changed files without loading the monorepo', async () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), 'psh-focused-ground-')));
+    try {
+        mkdirSync(join(dir, 'changed'), { recursive: true });
+        writeFileSync(join(dir, 'changed', 'one.ts'), 'export const one = 1\n');
+        for (let i = 0; i < 100; i++) {
+            const packageDir = join(dir, 'packages', 'package-' + i);
+            mkdirSync(packageDir, { recursive: true });
+            writeFileSync(join(packageDir, 'unrelated.ts'), 'export const unrelated = ' + i + '\n');
+            writeFileSync(join(packageDir, 'tsconfig.json'), '{broken');
+        }
+        const g = await buildGround(dir, [{ path: 'changed/one.ts', added: new Set([1]) }]);
+        assert.equal(g.sourceFiles.length, 1);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
 console.log('\nhelpers');
 check('extractJsonArray survives prose and code fences', () => {
     assert.deepEqual(extractJsonArray('Sure!\n```json\n[{"a":1}]\n```\n'), [{ a: 1 }]);

package/dist/verifiers/phantom-config.js

@@ -47,10 +47,11 @@ export const phantomConfig = {
         const manifest = g.envManifest;
         if (!manifest)
             return [];
-        // a key used elsewhere in the codebase is a documentation gap, not an invention
+        // A key used elsewhere in the relevant project is established configuration,
+        // even if the shared manifest is behind. Suppress that lower-signal case.
         const usedElsewhere = new Set();
         const changedPaths = new Set(g.changed.map((c) => c.path));
-        for (const sf of g.project.getSourceFiles()) {
+        for (const sf of g.sourceFiles) {
             const path = relPath(sf, g.root);
             if (changedPaths.has(path) || path.includes('node_modules'))
                 continue;
@@ -71,17 +72,17 @@ export const phantomConfig = {
                     class: 'verified',
                     check: 'phantom-config',
                     severity: 'medium',
-                    // The manifest is not the process environment. What the oracle settles is
-                    // that nothing in the repository declares or uses this key — a deployment
+                    // The manifest is not the process environment. The exact observation is
+                    // only that the checked-in manifest does not declare the key; a deployment
                     // can still set it, so "will be undefined" is an inference, not a fact.
                     confidence: 'firm',
                     file: relPath(sf, g.root),
                     line: read.line,
                     span: locate(sf, read.start, read.width).span,
-                    title: 'Reads process.env.' + read.name + ', which is not declared in ' + manifest.file + ' or used anywhere else',
+                    title: 'Reads process.env.' + read.name + ', which is not declared in ' + manifest.file,
                     evidence: {
                         oracle: manifest.file,
-                        detail: 'the key appears in no manifest entry and in no other source file',
+                        detail: 'the key appears in no manifest entry',
                     },
                     fix: 'Add ' + read.name + ' to ' + manifest.file + ', or drop the reference if it was invented',
                 });

package/docs/architecture.md

@@ -59,7 +59,7 @@ engine. The engine does not depend on a workflow provider or terminal layout.
 |---|---|---|
 | `src/cli/` | Argument parsing, command dispatch, report publication, exit mapping | Review algorithms |
 | `src/review.ts` | One review run and its stage orchestration | CLI parsing or presentation |
-| `src/ground.ts` | TypeScript project, parse trees, manifests, symbol index | Check selection |
+| `src/ground.ts` | Change-scoped TypeScript projects, parse trees, manifests, symbol index | Check selection |
 | `src/plan.ts` | File selection and per-file capability accounting | Finding generation |
 | `src/manifest.ts` | Completion state and the authoritative run record | Rendering |
 | `src/verifiers/` | Deterministic check implementations | Model calls |
@@ -126,6 +126,20 @@ A run can contain a typed TypeScript file beside a Python file or a TypeScript f
 excluded from `tsconfig`. Capabilities therefore live on each selected file. A checker
 available somewhere in the run is not evidence that it inspected every file.
 
+### Monorepo grounding follows the change
+
+For each changed TypeScript or JavaScript file, grounding inspects only its ancestor
+directories for `tsconfig.json` and `tsconfig.*.json`. The nearest config that owns
+the file wins. Empty solution configs yield to their leaf configs, and an excluded
+test can reuse the closest non-empty leaf project when its type environment resolves.
+Projects and directory listings are cached across files, then their source closures
+are deduplicated for syntax searches and symbol indexing.
+
+There is deliberately no repository-wide fallback glob. When no relevant config
+exists, only changed files are parsed and type-dependent capabilities remain absent.
+That keeps a configless or mixed-language monorepo proportional to the review rather
+than to the repository.
+
 ### The manifest owns completion
 
 Findings alone cannot distinguish a clean review from an interrupted or unsupported

package/docs/ci.md

@@ -27,7 +27,8 @@ There are two independent decisions:
 ## GitHub Action
 
 The action runs one review, adds a job summary, uploads SARIF when enabled, and can
-maintain one pull-request comment.
+maintain one pull-request comment. Its opt-in inline mode posts a bounded batched
+review on changed lines.
 
 ```yaml
 name: PowerShot
@@ -42,23 +43,41 @@ permissions:
 
 jobs:
   review:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
+      - run: npm ci --ignore-scripts
+
       - uses: xcrft/powershot@v1
         with:
           verify-only: 'true'
           upload-sarif: 'true'
           comment: 'true'
+          inline-comments: 'true'
           fail-on-findings: 'true'
 ```
 
+Type-aware checks use the checked-out project's declarations, so install its
+dependencies before PowerShot. Lifecycle scripts are disabled here because pull
+request code is untrusted; use the equivalent safe install for another package
+manager. For a monorepo without a root install, repeat the safe install step with the
+relevant package `working-directory`. PowerShot finds nested `tsconfig.json` and
+`tsconfig.*.json` files automatically; the workflow does not need to list projects.
+
 Set `upload-sarif: 'false'` and omit `security-events: write` when GitHub code scanning
 is unavailable or the workflow should not publish SARIF.
 
+`inline-comments: 'true'` requires `pull-requests: write`. It publishes at most ten
+findings as one review. Only deterministic `verified` findings with `proven`
+confidence, severity `medium` or higher, and a GitHub-confirmed added line qualify.
+Findings on context lines or files whose patch GitHub omitted stay in the full report.
+Reruns preserve exact bot comments, create only missing comments, and remove stale
+PowerShot inline copies without replies. Human comments and replied-to discussions
+are never modified.
+
 The major tag follows compatible `1.x` releases. Pin a full commit SHA in a protected
 required workflow when immutable dependencies are required. The copy-paste version
 lives at [`examples/github-actions/action.yml`](../examples/github-actions/action.yml).
@@ -73,6 +92,7 @@ lives at [`examples/github-actions/action.yml`](../examples/github-actions/actio
 | `checks` | empty | Select comma-separated check ids |
 | `upload-sarif` | `true` | Upload a complete SARIF report to GitHub code scanning |
 | `comment` | `true` | Maintain a pull-request comment |
+| `inline-comments` | `false` | Post up to ten proven verified findings as one inline review |
 | `fail-on-findings` | `false` | Turn a complete finding verdict into a failed job |
 | `approve` | `false` | Approve only a complete, clean review |
 
@@ -88,7 +108,7 @@ step inside a larger quality job. The complete example is
 The core pattern is:
 
 ```bash
-npm install --global --ignore-scripts @0xcraft/powershot@1.0.1
+npm install --global --ignore-scripts @0xcraft/powershot@1.1.1
 
 STATUS=0
 psh review --verify-only \

package/examples/github-actions/action.yml

@@ -10,15 +10,21 @@ permissions:
 
 jobs:
   review:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
+      # Type-aware checks need the repository's declared types. Keep lifecycle
+      # scripts disabled when pull-request code is not trusted. In a monorepo,
+      # install at the workspace root or set working-directory to the package root.
+      - run: npm ci --ignore-scripts
+
       - uses: xcrft/powershot@v1
         with:
           verify-only: 'true'
           upload-sarif: 'true'
           comment: 'true'
+          inline-comments: 'true'
           fail-on-findings: 'true'

package/examples/github-actions/cli.yml

@@ -19,7 +19,7 @@ jobs:
           node-version: '24'
 
       - name: Install PowerShot
-        run: npm install --global --ignore-scripts @0xcraft/powershot@1.0.1
+        run: npm install --global --ignore-scripts @0xcraft/powershot@1.1.1
 
       - name: Review pull request
         env:

package/examples/gitlab/.gitlab-ci.yml

@@ -5,7 +5,7 @@ powershot:
   variables:
     GIT_DEPTH: "0"
   before_script:
-    - npm install --global --ignore-scripts @0xcraft/powershot@1.0.1
+    - npm install --global --ignore-scripts @0xcraft/powershot@1.1.1
   script:
     - |
       STATUS=0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xcraft/powershot",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Oracle-first code review for machine-written code, with deterministic verification and CI-ready reports.",
   "license": "Apache-2.0",
   "author": "aglumova <alina.glumova@gmail.com>",