Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
name: CI

on:
push:
branches: [ main, improve-and-package ]
pull_request:
branches: [ main ]

jobs:
test:
name: Pester (${{ matrix.os }})
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ ubuntu-latest, macos-latest, windows-latest ]

steps:
- uses: actions/checkout@v4

- name: Validate module manifest
shell: pwsh
run: Test-ModuleManifest ./NetDiagram-PS/NetDiagram-PS.psd1

- name: Install Pester
shell: pwsh
run: Install-Module -Name Pester -MinimumVersion 5.0.0 -Force -Scope CurrentUser -SkipPublisherCheck

- name: Run Pester tests
shell: pwsh
run: |
$config = New-PesterConfiguration
$config.Run.Path = './tests/NetDiagram.Tests.ps1'
$config.Output.Verbosity = 'Detailed'
$config.Run.Exit = $true
Invoke-Pester -Configuration $config

lint:
name: PSScriptAnalyzer
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Install PSScriptAnalyzer
shell: pwsh
run: Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser

- name: Run analyzer (fail on errors)
shell: pwsh
run: |
$results = Invoke-ScriptAnalyzer -Path ./NetDiagram-PS -Recurse -Severity Error
$results | Format-Table -AutoSize
if ($results) { throw "PSScriptAnalyzer reported $($results.Count) error(s)" }
25 changes: 25 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,31 @@ All notable changes to NetDiagram-PS will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.2.0] - 2025-11-02

### Fixed
- **SNMP discovery on macOS/Linux** - `Invoke-SnmpWalk` hard-coded `snmpwalk.exe`, so
SNMP neighbor discovery never worked on the platforms added in 1.1.0. It now resolves
`snmpwalk` (Unix) or `snmpwalk.exe` (Windows) from PATH.
- Pester suite no longer asserts a stale hard-coded module version; the version test now
reads the manifest, and the module path is built with `Join-Path` (no literal backslash),
so tests run on macOS/Linux as well as Windows.

### Changed
- **Minimum PowerShell raised to 7.4.** The reachability functions use
`Test-Connection -TimeoutSeconds`, which only exists in PowerShell 7.4+. The manifest
previously advertised 7.0, on which those calls error.
- Added `CompatiblePSEditions = @('Core')` to the manifest.
- LICENSE copyright holder and README license section aligned with the manifest (MIT,
Jacob Yoby).

### Added
- Additional Pester tests for `Get-MACVendor`, `Get-CommonSNMPStrings`,
`Resolve-IPHostname`, `Invoke-SnmpWalk` (missing-binary path), and the private
`Test-IPInSubnet` helper.
- `PUBLISHING.md` documenting the PowerShell Gallery release process.
- GitHub Actions workflow running the Pester suite on Windows, macOS, and Linux.

## [1.1.0] - 2025-10-31

### Added
Expand Down
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2025 NetDiagram-PS Contributors
Copyright (c) 2025 Jacob Yoby

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
7 changes: 4 additions & 3 deletions NetDiagram-PS/NetDiagram-PS.psd1
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
@{
RootModule = 'NetDiagram-PS.psm1'
ModuleVersion = '1.1.0'
ModuleVersion = '1.2.0'
GUID = 'a8f7e9c4-6d2b-4a1c-9e3f-7b8c9d0e1f2a'
Author = 'Jacob Yoby'
CompanyName = 'NetDiagram-PS'
Copyright = '(c) 2025 Jacob Yoby. All rights reserved.'
Description = 'Automatically discover your network topology and generate professional draw.io diagrams with Cisco icons, SNMP discovery, and multi-level device detection.'
PowerShellVersion = '7.0'
PowerShellVersion = '7.4'
CompatiblePSEditions = @('Core')

FunctionsToExport = @(
# Core inventory and topology
Expand Down Expand Up @@ -41,7 +42,7 @@
LicenseUri = 'https://github.com/jacobyoby/PSNetMap/blob/main/LICENSE'
ProjectUri = 'https://github.com/jacobyoby/PSNetMap'
IconUri = ''
ReleaseNotes = 'Version 1.1.0 - Cross-platform support for Windows, macOS, and Linux with native command integration'
ReleaseNotes = 'Version 1.2.0 - Fixed SNMP discovery on macOS/Linux (snmpwalk binary resolution), raised the minimum PowerShell version to 7.4 (Test-Connection -TimeoutSeconds), added CompatiblePSEditions, expanded the Pester suite, and documented the PowerShell Gallery publish path.'
}
}
}
36 changes: 24 additions & 12 deletions NetDiagram-PS/NetDiagram-PS.psm1
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#Requires -Version 7.0
#Requires -Version 7.4

<#
.SYNOPSIS
Expand All @@ -11,7 +11,7 @@ Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

# Module-level variables
$script:ModuleVersion = '1.1.0'
$script:ModuleVersion = '1.2.0'

#region Helper Functions

Expand Down Expand Up @@ -217,9 +217,10 @@ function Test-DeviceReachability {
function Invoke-SnmpWalk {
<#
.SYNOPSIS
Invokes snmpwalk.exe against a target device
Invokes the net-snmp snmpwalk binary against a target device
.DESCRIPTION
Calls snmpwalk.exe directly (must be in PATH) with specified OID and credentials.
Calls snmpwalk directly (must be in PATH) with specified OID and credentials.
Resolves 'snmpwalk' on macOS/Linux and 'snmpwalk.exe' on Windows.
Returns raw output lines.
.PARAMETER TargetIP
IP address to query
Expand Down Expand Up @@ -252,10 +253,18 @@ function Invoke-SnmpWalk {
[int]$TimeoutSeconds = 2
)

# Check if snmpwalk.exe is available
$snmpWalkPath = Get-Command -Name 'snmpwalk.exe' -ErrorAction SilentlyContinue
if (-not $snmpWalkPath) {
throw "snmpwalk.exe not found in PATH. Please install net-snmp tools."
# Locate the snmpwalk binary. It is 'snmpwalk.exe' on Windows and 'snmpwalk'
# on macOS/Linux, so probe for both rather than assuming the Windows name.
$snmpWalkCmd = $null
foreach ($candidate in @('snmpwalk', 'snmpwalk.exe')) {
$found = Get-Command -Name $candidate -ErrorAction SilentlyContinue
if ($found) {
$snmpWalkCmd = $found.Source
break
}
}
if (-not $snmpWalkCmd) {
throw "snmpwalk not found in PATH. Please install net-snmp tools (brew install net-snmp, apt install snmp, or choco install net-snmp)."
}

try {
Expand All @@ -267,12 +276,12 @@ function Invoke-SnmpWalk {
$OID
)

Write-Verbose "Running: snmpwalk.exe $($arguments -join ' ')"
Write-Verbose "Running: $snmpWalkCmd $($arguments -join ' ')"

$output = & snmpwalk.exe @arguments 2>&1
$output = & $snmpWalkCmd @arguments 2>&1

if ($LASTEXITCODE -ne 0) {
Write-Warning "snmpwalk.exe failed for $TargetIP with exit code $LASTEXITCODE"
Write-Warning "snmpwalk failed for $TargetIP with exit code $LASTEXITCODE"
return @()
}

Expand Down Expand Up @@ -520,11 +529,14 @@ function Test-IPInSubnet {
$ipValue = [System.BitConverter]::ToUInt32($ipBytes, 0)
$networkValue = [System.BitConverter]::ToUInt32($networkBytes, 0)

# Build the prefix mask. Compute in UInt64 to avoid the int overflow that
# '[uint32]0xFFFFFFFF -shl n' triggers (0xFFFFFFFF parses as int -1), then
# truncate back to 32 bits.
$mask = if ($prefixLength -eq 0) {
[uint32]0
}
else {
[uint32]0xFFFFFFFF -shl (32 - $prefixLength)
[uint32]((([uint64]4294967295) -shl (32 - $prefixLength)) -band [uint64]4294967295)
}

return (($ipValue -band $mask) -eq ($networkValue -band $mask))
Expand Down
86 changes: 86 additions & 0 deletions PUBLISHING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Publishing NetDiagram-PS

This document describes how NetDiagram-PS is validated and published to the
[PowerShell Gallery](https://www.powershellgallery.com/).

## Prerequisites

- PowerShell 7.4+
- A PowerShell Gallery account and an **API key** (Account → API Keys)
- Modules used for validation/publishing:

```powershell
Install-Module -Name Pester -MinimumVersion 5.0.0 -Force
Install-Module -Name PSScriptAnalyzer -Force
# PowerShellGet v2 ships with PowerShell; Publish-Module comes from it
```

## 1. Validate the manifest

```powershell
Test-ModuleManifest ./NetDiagram-PS/NetDiagram-PS.psd1
```

This must succeed with no errors. It confirms the manifest parses, the
`RootModule` resolves, and `FunctionsToExport` matches the module.

## 2. Lint

```powershell
Invoke-ScriptAnalyzer -Path ./NetDiagram-PS -Recurse -Severity Warning,Error
```

Resolve anything at `Error` severity before publishing. Warnings are advisory.

## 3. Run the test suite

```powershell
Invoke-Pester -Path ./tests/NetDiagram.Tests.ps1 -Output Detailed
```

All tests must pass on the target platform(s).

## 4. Dry-run the publish

`Publish-Module` has no true `-WhatIf` for content, so verify what will be
packed by pointing at the module folder and confirming the version is new:

```powershell
$manifest = Import-PowerShellDataFile ./NetDiagram-PS/NetDiagram-PS.psd1
$manifest.ModuleVersion # must be greater than the version already on the Gallery
Find-Module NetDiagram-PS -ErrorAction SilentlyContinue # what's live now (if anything)
```

Bump `ModuleVersion` in `NetDiagram-PS.psd1` and add a `CHANGELOG.md` entry for
any release. The Gallery rejects re-publishing an existing version.

## 5. Publish

```powershell
$apiKey = '<your-powershell-gallery-api-key>' # do NOT commit this
Publish-Module -Path ./NetDiagram-PS -NuGetApiKey $apiKey -Verbose
```

Notes:
- `-Path` points at the **module folder** (`NetDiagram-PS/`), not the repo root.
- The manifest's `PrivateData.PSData` already supplies `Tags`, `LicenseUri`,
`ProjectUri`, and `ReleaseNotes`, which populate the Gallery listing.
- After publishing, confirm with `Find-Module NetDiagram-PS`.

## 6. Tag the release

```powershell
git tag v<version>
git push origin v<version>
```

## Release checklist

- [ ] `ModuleVersion` bumped in `NetDiagram-PS.psd1`
- [ ] `PrivateData.PSData.ReleaseNotes` updated
- [ ] `CHANGELOG.md` entry added
- [ ] `Test-ModuleManifest` passes
- [ ] `Invoke-ScriptAnalyzer` clean (no Errors)
- [ ] `Invoke-Pester` green
- [ ] `Publish-Module` succeeded and `Find-Module` shows the new version
- [ ] Git tag pushed
24 changes: 22 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The wizard performs the following actions:

## Prerequisites

- **PowerShell 7.0+** (required, cross-platform)
- **PowerShell 7.4+** (required, cross-platform — 7.4 is the current LTS and provides `Test-Connection -TimeoutSeconds`)
- Windows: https://aka.ms/powershell
- macOS: `brew install --cask powershell` or download from https://aka.ms/powershell
- Linux: Follow instructions at https://aka.ms/powershell
Expand All @@ -47,6 +47,26 @@ The wizard performs the following actions:

---

## Installation

### From PowerShell Gallery (once published)

```powershell
Install-Module -Name NetDiagram-PS -Scope CurrentUser
Import-Module NetDiagram-PS
```

### From source (clone)

```powershell
git clone https://github.com/jacobyoby/PSNetMap.git
Import-Module ./PSNetMap/NetDiagram-PS/NetDiagram-PS.psd1
```

See [PUBLISHING.md](PUBLISHING.md) for how the module is packaged and released to the Gallery.

---

## Usage

### Method 1: Quick Start Wizard (recommended)
Expand Down Expand Up @@ -360,7 +380,7 @@ Contributions welcome! Please:

## License

This project is provided as-is for educational and professional use.
Released under the [MIT License](LICENSE). Copyright (c) 2025 Jacob Yoby.

---

Expand Down
4 changes: 2 additions & 2 deletions STRUCTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,5 +73,5 @@ For the easiest experience, run the wizard:

---

**Last Updated:** 2025-11-01
**Module Version:** 1.0.1
**Last Updated:** 2025-11-02
**Module Version:** 1.1.0
2 changes: 1 addition & 1 deletion examples/New-NetworkDiagram.ps1
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
#!/usr/bin/env pwsh
#Requires -Version 7.0
#Requires -Version 7.4

<#
.SYNOPSIS
Expand Down
Loading
Loading