@0xcraft/powershot 1.1.0 → 1.1.1

package/README.md

@@ -211,6 +211,8 @@ The composite action is the shortest setup for GitHub:
   with:
     fetch-depth: 0
 
+- run: npm ci --ignore-scripts
+
 - uses: xcrft/powershot@v1
   with:
     verify-only: 'true'
@@ -220,6 +222,18 @@ The composite action is the shortest setup for GitHub:
     fail-on-findings: 'true'
 ```
 
+Install the checked-out project's dependencies before PowerShot so TypeScript can
+resolve its declared ambient types. The example disables lifecycle scripts because
+pull-request code is untrusted; use the equivalent safe install for another package
+manager. In a monorepo, install from the workspace root or add safe install steps for
+the affected package roots.
+
+PowerShot discovers `tsconfig.json` and `tsconfig.*.json` along the ancestor chain of
+each changed file. One review can use several independent package projects, skip
+empty solution configs in favour of their leaf configs, and type-check test files
+that a production config excludes. Discovery is change-scoped: unrelated packages
+and configless source trees are not crawled just to build the TypeScript ground.
+
 `@v1` follows compatible `1.x` releases. Pin the action to a full commit SHA in a
 protected required workflow when immutable dependencies are required.
 

package/dist/ground.js

@@ -1,33 +1,174 @@
 import { Project, SyntaxKind } from 'ts-morph';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { decode } from './text.js';
-import { join, dirname } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { packFor, parse } from './lang/packs.js';
 import { insideRepo, isSymlink, repoPath } from './fspolicy.js';
 const CODE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+const TS_CONFIG = /^tsconfig(?:\..+)?\.json$/i;
+const MISSING_TYPE_PREFIXES = [
+    'Cannot find global type',
+    'Cannot find global value',
+    'Cannot find module',
+    'Cannot find name',
+    'Cannot find type definition file',
+    'Could not find a declaration file for module',
+];
+/**
+ * A property diagnostic is only exact when the file's ambient types resolved.
+ * Missing modules, globals, or declaration files can remove interface
+ * augmentations and manufacture downstream errors such as `ImportMeta.url`.
+ */
+function hasTypeEnvironmentGap(sf) {
+    return sf.getPreEmitDiagnostics().some((diagnostic) => {
+        const message = diagnostic.getMessageText();
+        const head = typeof message === 'string' ? message : message.getMessageText();
+        return MISSING_TYPE_PREFIXES.some((prefix) => head.startsWith(prefix)) || /^File .+ not found/.test(head);
+    });
+}
 export function normalizeName(n) {
     return n.toLowerCase().replace(/[^a-z0-9]/g, '');
 }
-/**
- * Walks up, but never past `stop`.
- *
- * A tsconfig above the repository is somebody else's, and letting one configure the
- * program that reviews this repository lets a parent directory decide what is
- * type-checked and where paths resolve to.
- */
-function findUp(from, name, stop = from) {
-    let dir = from;
-    for (;;) {
-        const p = join(dir, name);
-        if (existsSync(p))
-            return p;
-        if (dir === stop)
-            return undefined;
+/** A lexical repository containment check for paths that have already been resolved. */
+function isWithin(root, path) {
+    const rel = relative(root, path);
+    return rel === '' || (rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel));
+}
+/** Directories from a changed file up to the repository root, nearest first. */
+function ancestorDirectories(root, absPath) {
+    const out = [];
+    let dir = dirname(absPath);
+    while (isWithin(root, dir)) {
+        out.push(dir);
+        if (dir === root)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return out;
+}
+/** Only inspect the directory chain of changed files; never crawl the monorepo. */
+function configsInDirectory(dir, cache) {
+    const known = cache.get(dir);
+    if (known)
+        return known;
+    let configs = [];
+    try {
+        configs = readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && TS_CONFIG.test(entry.name))
+            .map((entry) => join(dir, entry.name))
+            .sort();
+    }
+    catch {
+        // An unreadable ancestor contributes no project; the file remains syntax-only.
+    }
+    cache.set(dir, configs);
+    return configs;
+}
+function configuredProject(root, configPath) {
+    try {
+        const project = new Project({ tsConfigFilePath: configPath });
+        const owned = new Set();
+        const sourceAncestors = new Set();
+        for (const sf of project.getSourceFiles()) {
+            const abs = resolve(sf.getFilePath());
+            const safe = insideRepo(root, abs);
+            if (!safe || repoPath(root, abs).split('/').includes('node_modules'))
+                continue;
+            owned.add(repoPath(root, abs));
+            let dir = dirname(abs);
+            while (isWithin(root, dir)) {
+                sourceAncestors.add(dir);
+                if (dir === root)
+                    break;
+                const parent = dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        return { configPath, project, owned, sourceAncestors, sourceCount: owned.size };
+    }
+    catch {
+        // A broken candidate beside a usable leaf config must not take down the review.
+        return undefined;
+    }
+}
+function directoryDepth(root, dir) {
+    const rel = repoPath(root, dir);
+    return rel === '' ? 0 : rel.split('/').length;
+}
+function sourceAffinity(root, candidate, absPath) {
+    let dir = dirname(absPath);
+    while (isWithin(root, dir)) {
+        if (candidate.sourceAncestors.has(dir))
+            return directoryDepth(root, dir);
+        if (dir === root)
+            break;
         const parent = dirname(dir);
         if (parent === dir)
-            return undefined;
+            break;
         dir = parent;
     }
+    return -1;
+}
+function nameAffinity(root, configPath, absPath) {
+    const base = basename(configPath);
+    const name = base.slice('tsconfig'.length, -'.json'.length).replace(/^\./, '');
+    if (name === '')
+        return 0;
+    const tokens = new Set(repoPath(root, absPath).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+    return name
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean)
+        .filter((token) => tokens.has(token)).length;
+}
+/** Prefer the leaf project whose existing sources live closest to this file. */
+function bestProject(root, candidates, absPath) {
+    return [...candidates].sort((a, b) => sourceAffinity(root, b, absPath) - sourceAffinity(root, a, absPath) ||
+        nameAffinity(root, b.configPath, absPath) - nameAffinity(root, a.configPath, absPath) ||
+        a.sourceCount - b.sourceCount ||
+        a.configPath.localeCompare(b.configPath))[0];
+}
+function looksLikeTest(path) {
+    return /(?:^|[/\\])(?:__tests__|tests?)(?:[/\\]|$)/i.test(path) || /\.(?:test|spec)\.[^.]+$/i.test(path);
+}
+/**
+ * Resolve one changed file at the nearest useful project boundary.
+ *
+ * Solution configs (`files: []`) do not claim a type environment. If a sibling leaf
+ * config owns the file it wins; if every leaf excludes the file (common for tests),
+ * the closest suitable non-empty leaf supplies compiler options and references.
+ * Selecting that local leaf avoids opening a repository-wide parent.
+ */
+function projectForFile(root, absPath, directoryCache, projectCache) {
+    const rel = repoPath(root, absPath);
+    for (const dir of ancestorDirectories(root, absPath)) {
+        const configPaths = [...configsInDirectory(dir, directoryCache)].sort((a, b) => nameAffinity(root, b, absPath) - nameAffinity(root, a, absPath) || a.localeCompare(b));
+        const projects = [];
+        for (const configPath of configPaths) {
+            if (!projectCache.has(configPath)) {
+                projectCache.set(configPath, configuredProject(root, configPath));
+            }
+            const project = projectCache.get(configPath);
+            if (!project)
+                continue;
+            // Config names such as `test`, `app`, and `node` are ranked against the file
+            // path, so the first owner is the most specific without opening every sibling.
+            if (project.owned.has(rel))
+                return project;
+            projects.push(project);
+        }
+        const boundaryDepth = directoryDepth(root, dir);
+        const leaves = projects.filter((project) => project.sourceCount > 0 &&
+            (sourceAffinity(root, project, absPath) > boundaryDepth || looksLikeTest(absPath)));
+        if (leaves.length > 0)
+            return bestProject(root, leaves, absPath);
+    }
+    return undefined;
 }
 function depsIn(pkgPath) {
     const deps = new Set();
@@ -70,36 +211,45 @@ function makeDepsFor(root) {
     };
 }
 /**
- * Build the oracle once per run: a type-checked project over the working tree,
- * a syntax-only project holding the base-ref versions, and a symbol index.
+ * Build the oracle once per run: focused type-checked projects for the changed
+ * packages, a syntax-only project for unconfigured changes and the base-ref trees,
+ * and one deduplicated symbol index over the relevant project closures.
  */
 export async function buildGround(root, changed, signal) {
-    const tsConfigFilePath = findUp(root, 'tsconfig.json');
-    const typed = Boolean(tsConfigFilePath);
-    const project = typed
-        ? new Project({ tsConfigFilePath })
-        : new Project({ compilerOptions: { allowJs: true, checkJs: false } });
-    if (!typed)
-        project.addSourceFilesAtPaths([`${root}/**/*.{ts,tsx,js,jsx,mts,cts}`, `!${root}/**/node_modules/**`]);
-    // What the tsconfig itself owns. A file added past this point is present for
-    // reading, but the checker has no program for it — asking one for diagnostics
-    // throws from inside TypeScript, which took the whole review down with it.
-    const owned = new Set(project.getSourceFiles().map((f) => repoPath(root, String(f.getFilePath()))));
-    // A changed file may be new, or excluded from tsconfig — make sure it is present.
-    // `readable` is the gate for every file that becomes reviewable: the glob above
-    // follows symlinks, so passing this on the way in is not enough on its own.
+    root = resolve(root);
+    const directoryCache = new Map();
+    const projectCache = new Map();
+    const selectedProjects = new Set();
+    const assigned = new Map();
+    const syntaxProject = new Project({ compilerOptions: { allowJs: true, checkJs: false } });
+    // `readable` is the gate for every file that becomes reviewable. A tsconfig glob
+    // can follow symlinks, so selected project closures are checked again below too.
     const readable = (path) => {
         const abs = insideRepo(root, path);
         return abs && !isSymlink(abs) ? abs : undefined;
     };
     for (const c of changed) {
+        if (signal?.aborted)
+            break;
         if (!CODE_EXT.test(c.path))
             continue;
         const abs = readable(c.path);
-        if (!abs)
+        if (!abs || !existsSync(abs))
             continue;
-        if (!project.getSourceFile(abs) && existsSync(abs))
-            project.addSourceFileAtPath(abs);
+        const configured = projectForFile(root, abs, directoryCache, projectCache);
+        if (configured) {
+            selectedProjects.add(configured);
+            assigned.set(c.path, configured);
+            // Tests and tooling files are often excluded from the production build config.
+            // Adding one explicitly keeps the leaf project's compiler options and imports.
+            if (!configured.project.getSourceFile(abs))
+                configured.project.addSourceFileAtPath(abs);
+        }
+        else if (!syntaxProject.getSourceFile(abs)) {
+            // No recursive glob: a configless million-file repository still loads only the
+            // files in the review.
+            syntaxProject.addSourceFileAtPath(abs);
+        }
     }
     const beforeProject = new Project({ useInMemoryFileSystem: true });
     const files = [];
@@ -109,79 +259,78 @@ export async function buildGround(root, changed, signal) {
         const abs = readable(c.path);
         if (!abs)
             continue;
-        const sf = project.getSourceFile(abs);
+        const configured = assigned.get(c.path);
+        const sf = configured?.project.getSourceFile(abs) ?? syntaxProject.getSourceFile(abs);
         if (!sf)
             continue;
         const before = c.before === undefined ? undefined : beforeProject.createSourceFile(`/before/${c.path}`, c.before, { overwrite: true });
-        files.push({ sf, changed: c, before, typed: typed && owned.has(repoPath(root, c.path)) });
+        files.push({
+            sf,
+            changed: c,
+            before,
+            // A bound program with unresolved ambient types is not an exact type oracle.
+            // Keep the file reviewable, but make type-dependent checks explicitly partial.
+            typed: configured !== undefined && !hasTypeEnvironmentGap(sf),
+        });
     }
+    const projects = [...selectedProjects].map((selected) => selected.project);
+    if (syntaxProject.getSourceFiles().length > 0)
+        projects.push(syntaxProject);
+    const sourceFiles = uniqueSourceFiles(root, files.map((file) => file.sf), projects);
+    const configFiles = [...selectedProjects]
+        .map((selected) => repoPath(root, selected.configPath))
+        .sort();
+    const typed = files.some((file) => file.typed);
+    const depsFor = makeDepsFor(root);
     return {
         root,
-        project,
+        sourceFiles,
+        configFiles,
         beforeProject,
         changed,
         files,
-        symbolIndex: buildSymbolIndex(project, root),
-        deps: makeDepsFor(root)(join(root, 'x.ts')),
-        depsFor: makeDepsFor(root),
+        symbolIndex: buildSymbolIndex(sourceFiles, root),
+        deps: depsFor(join(root, 'x.ts')),
+        depsFor,
         typed,
-        internalPrefixes: pathAliasPrefixes(project, root),
+        internalPrefixes: pathAliasPrefixes(projects),
         foreign: await parseForeign(root, changed, signal),
         envManifest: readEnvManifest(root),
     };
 }
+/** Prefer changed-file SourceFiles, then add each relevant project source once. */
+function uniqueSourceFiles(root, preferred, projects) {
+    const byPath = new Map();
+    const add = (sf) => {
+        const abs = resolve(sf.getFilePath());
+        if (!insideRepo(root, abs))
+            return;
+        const rel = repoPath(root, abs);
+        if (rel.split('/').includes('node_modules') || byPath.has(rel))
+            return;
+        byPath.set(rel, sf);
+    };
+    for (const sf of preferred)
+        add(sf);
+    for (const project of projects)
+        for (const sf of project.getSourceFiles())
+            add(sf);
+    return [...byPath.values()];
+}
 /**
  * Prefixes that `compilerOptions.paths` maps back into the repo — `@/*` and friends.
  * They look like package names but resolve to local files, so treating them as
  * dependencies would be wrong.
  */
-function pathAliasPrefixes(project, root) {
+function pathAliasPrefixes(projects) {
     const prefixes = new Set();
-    for (const pattern of Object.keys(project.getCompilerOptions().paths ?? {})) {
-        prefixes.add(pattern.replace(/\*$/, ''));
-    }
-    // a workspace declares its aliases in each package's tsconfig, and the root config
-    // often only `extends` a shared base — so the root's paths are not the whole story
-    for (const file of tsconfigsIn(root)) {
-        try {
-            const raw = readFileSync(file, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|\s)\/\/.*$/gm, '$1');
-            const parsed = JSON.parse(raw.replace(/,(\s*[}\]])/g, '$1'));
-            for (const pattern of Object.keys(parsed?.compilerOptions?.paths ?? {})) {
-                prefixes.add(String(pattern).replace(/\*$/, ''));
-            }
-        }
-        catch {
-            // an unreadable or non-standard tsconfig simply contributes no aliases
+    for (const project of projects) {
+        for (const pattern of Object.keys(project.getCompilerOptions().paths ?? {})) {
+            prefixes.add(pattern.replace(/\*$/, ''));
         }
     }
     return [...prefixes];
 }
-/** every tsconfig in the repo, capped so a huge monorepo cannot stall the run */
-function tsconfigsIn(root) {
-    const out = [];
-    const walk = (dir, depth) => {
-        if (depth > 4 || out.length > 60)
-            return;
-        let entries;
-        try {
-            entries = readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const e of entries) {
-            if (e.name === 'node_modules' || e.name.startsWith('.'))
-                continue;
-            const full = join(dir, e.name);
-            if (e.isDirectory())
-                walk(full, depth + 1);
-            else if (e.name === 'tsconfig.json')
-                out.push(full);
-        }
-    };
-    walk(root, 0);
-    return out;
-}
 /**
  * Changed files the TypeScript project cannot hold. Nine of the checks need only a
  * parse tree, so a Python or Go file is reviewable the moment its grammar loads —
@@ -235,9 +384,9 @@ async function parseForeign(root, changed, signal) {
     }
     return out;
 }
-function buildSymbolIndex(project, root) {
+function buildSymbolIndex(sourceFiles, root) {
     const index = new Map();
-    for (const sf of project.getSourceFiles()) {
+    for (const sf of sourceFiles) {
         const path = String(sf.getFilePath());
         // the project glob follows symlinked directories, so what it loaded is not
         // proof of where the file is

package/dist/judges/tools.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { relPath } from '#app/ground.js';
-import { insideRepo } from '#app/fspolicy.js';
+import { insideRepo, repoPath } from '#app/fspolicy.js';
 const MAX_BYTES = 60_000;
 const MAX_MATCHES = 40;
 export const TOOLS = [
@@ -58,7 +58,7 @@ function readFile(g, input) {
     const abs = insideRepo(g.root, path);
     if (!abs)
         return 'Refused: that path is outside the repository or is not readable for review.';
-    const inProject = g.project.getSourceFile(abs);
+    const inProject = g.sourceFiles.find((file) => relPath(file, g.root) === repoPath(g.root, abs));
     const text = inProject ? inProject.getFullText() : readFileSync(abs, 'utf8');
     const lines = text.split('\n');
     const start = Math.max(1, Number(input.start ?? 1));
@@ -79,7 +79,7 @@ function grep(g, input) {
     }
     const filter = input.path_contains === undefined ? undefined : String(input.path_contains);
     const hits = [];
-    for (const sf of g.project.getSourceFiles()) {
+    for (const sf of g.sourceFiles) {
         const abs = sf.getFilePath();
         // the project glob can pull in a file through a symlinked directory, so the
         // boundary is re-checked here rather than trusted from how the file got loaded
@@ -98,13 +98,13 @@ function grep(g, input) {
                 return hits.join('\n') + '\n… more matches not shown';
         }
     }
-    return hits.length > 0 ? hits.join('\n') : 'No matches.';
+    return hits.length > 0 ? hits.join('\n') : 'No matches in the relevant project files.';
 }
 function references(g, input) {
     const symbol = String(input.symbol ?? '');
     if (!symbol)
         return 'No symbol given.';
-    for (const sf of g.project.getSourceFiles()) {
+    for (const sf of g.sourceFiles) {
         const path = String(sf.getFilePath());
         if (path.includes('/node_modules/') || !insideRepo(g.root, path))
             continue;
@@ -117,9 +117,9 @@ function references(g, input) {
             .map((n) => relPath(n.getSourceFile(), g.root) + ':' + n.getStartLineNumber())
             .filter((r) => !r.includes('node_modules'));
         return refs.length === 0
-            ? symbol + ' is declared in ' + relPath(sf, g.root) + ' and referenced nowhere.'
+            ? symbol + ' is declared in ' + relPath(sf, g.root) + ' and referenced nowhere in its project.'
             : symbol + ' declared in ' + relPath(sf, g.root) + ', referenced at:\n' + [...new Set(refs)].slice(0, MAX_MATCHES).join('\n');
     }
-    return 'No declaration named ' + symbol + ' found in the project.';
+    return 'No declaration named ' + symbol + ' found in the relevant projects.';
 }
 //# sourceMappingURL=tools.js.map

package/dist/review.js

@@ -146,8 +146,10 @@ export async function review(opts) {
     const manifest = opts.manifest;
     const groundDone = stage('ground');
     const g = await buildGround(root, changed, opts.signal);
-    groundDone(g.project.getSourceFiles().length + ' files · ' + g.symbolIndex.size + ' symbols' +
-        (g.typed ? '' : ' · no tsconfig, phantom-api disabled'));
+    groundDone(g.sourceFiles.length + ' files · ' + g.symbolIndex.size + ' symbols' +
+        (g.configFiles.length === 0
+            ? ' · no usable relevant tsconfig, type checks disabled'
+            : ' · ' + g.configFiles.length + ' project(s)' + (g.typed ? '' : ' · type environment incomplete')));
     const wanted = (v) => {
         const id = v.id ?? v.name;
         return opts.checks

package/dist/selftest.js

@@ -50,7 +50,7 @@ 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';
@@ -90,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) {
@@ -892,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');
@@ -912,11 +914,12 @@ check('published CI examples preserve one verdict and its exit status', () => {
     assert.match(action, /upload-sarif: 'true'/);
     assert.match(action, /inline-comments: 'true'/);
     assert.match(action, /runs-on: ubuntu-24\.04/);
-    assert.match(github, /npm install --global --ignore-scripts @0xcraft\/powershot@1\.1\.0/);
+    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\.1\.0/);
+    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"/);
@@ -1378,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

@@ -49,6 +49,8 @@ jobs:
         with:
           fetch-depth: 0
 
+      - run: npm ci --ignore-scripts
+
       - uses: xcrft/powershot@v1
         with:
           verify-only: 'true'
@@ -58,6 +60,13 @@ jobs:
           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.
 
@@ -99,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.1.0
+npm install --global --ignore-scripts @0xcraft/powershot@1.1.1
 
 STATUS=0
 psh review --verify-only \

package/examples/github-actions/action.yml

@@ -16,6 +16,11 @@ jobs:
         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'

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.1.0
+        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.1.0
+    - 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.1.0",
+  "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>",