Netscoot Analyze

---
name: netscoot-analyze
description: >-
  Use to analyze a repository's solution/project state and to verify that a refactor is complete. Read-only inventory, consistency, and reference detection across .NET, PowerShell, Unity, and native projects. Triggers on "what projects are in this solution," "are the sln and slnx in sync," "do the solutions agree on membership," "find dangling references or orphaned projects," "find references to <path>," "where else does <X> appear," "what would break if I moved <X>," "is the rename/refactor complete," "check for stragglers," "what engine moves <file>," "does this env have what netscoot needs," "why does my .sln keep coming back," "check the editor solution guards." For moving or restructuring, use restructure-dotnet, restructure-powershell, restructure-unity or restructure-native instead.
---

# Netscoot: analysis and post-refactor sanity (cross-engine, read-only)

Purpose (full overview: the [netscoot README](https://github.com/kappasims/netscoot)): structured
answers to "what's in this repository," "is this rename actually done," "where else does X
appear," "what would break if I moved Y" without ad-hoc Grep/Read over `.sln`/`.slnx`/`.csproj`.

Every cmdlet here is **read-only**: nothing is moved, no file is rewritten. The actual moves belong
to the project-type-specific skills (`restructure-dotnet`, `restructure-powershell`,
`restructure-unity`, `restructure-native`).

## Map a question to the right cmdlet

| Question | Cmdlet |
| --- | --- |
| What projects are in this solution? Any orphans? Solution folders or solution items? | `Get-SolutionInventory` |
| Are `.sln` and `.slnx` in sync? Do solutions agree on membership? | `Test-SolutionConsistency` |
| Any dangling solution entries or broken `<ProjectReference>`s? | `Repair-SolutionReferences` (no flags is report-only) |
| Where else does this path/file appear in build scripts, CI, hooks, container files? | `Find-PathReference -Path <old-id-or-path>` |
| Did I miss any references after the rename? Is the refactor complete? | `Find-PathReference -Path <old-id-or-path>` (see the canonical pattern below) |
| What engine would move this file? Can netscoot handle it? | `Resolve-MoveEngine -Path <file>` |
| Does this environment have what netscoot needs? | `Get-NetscootCapability` |
| Will my `.slnx` consolidation stay durable, or will VS Code re-create a `.sln`? | `Test-EditorSolutionGuard` |

Output is structured: each cmdlet returns typed `Netscoot.<Kind>` objects, except
`Resolve-MoveEngine`, which returns the engine name as a string. So the agent can filter and assert
on rows rather than parsing text. Default Format.ps1xml table views are tuned for the common
columns, and the full record is always there for `Select-Object`.

## Canonical post-refactor sanity check

When a refactor, rename, or move appears done, run this from the repository root:

```powershell
Find-PathReference -Path <old identifier or path>
```

Run it over the OLD identifier (a moved file's old path, a renamed type, a removed namespace, an
old DLL name in build scripts). The output is structured (`File`, `Line`, `Confidence`, `Text`)
and the cmdlet emits the warning *"These are not auto-reconciled - review and fix them by hand."*
That is the agent-readable signal that references survive in places the move machinery does not
touch: build scripts, CI YAML, git hooks, container files, documentation snippets. Use it BEFORE
declaring a rename "complete." If it returns rows, fix them by hand and re-run. A zero-row result
with no warning is the all-clear.

This is the canonical "did I miss anything" pattern, so do not substitute an ad-hoc `Grep`.
`Find-PathReference` already knows which file kinds are candidates, applies a confidence rating, and
excludes paths the move machinery already reconciled. By default it scans only the non-canonical
automation file class (build/CI/hooks/containers), which skips source files. Add `-AllFiles` to
search every text file under the repository (caches/vendored dirs and binaries still excluded). Use
it for a renamed type or namespace, which lives in source files, and for the thorough "search
literally everywhere" pass when the default returns nothing but you suspect a reference survives.

## Load the module

Load the netscoot module that ships with this plugin:
`Import-Module "${CLAUDE_PLUGIN_ROOT}/Netscoot/Netscoot.psd1"`.

## Cross-engine, not engine-specific

These cmdlets cover all four engine families. `Repair-SolutionReferences` needs the dotnet CLI, and
the others only read files. For the actual MOVES, route by project type:

- `restructure-dotnet` for `.csproj`/`.fsproj`/`.vbproj` and solutions.
- `restructure-powershell` for `.ps1` scripts and PowerShell modules.
- `restructure-unity` for Unity assets, asmdefs, and `.meta` pairs.
- `restructure-native` for `.vcxproj` (Windows-only).

The analyzers here intentionally do NOT decide between those routes. That is `Resolve-MoveEngine`'s
job (use it explicitly when the answer matters).