diff --git a/docs/guides/managed/nuget-nupkg.md b/docs/guides/managed/nuget-nupkg.md index 217e52584a..bdcb5f231d 100644 --- a/docs/guides/managed/nuget-nupkg.md +++ b/docs/guides/managed/nuget-nupkg.md @@ -46,15 +46,21 @@ relationship diagnostics apply the same exclusion. `dependency_groups` lists each `.nuspec` dependency group with its `target_framework` and dependencies (`id`, `version` range as spelled, `include`, `exclude`, `development_dependency`). Ungrouped dependencies appear -as a group with `target_framework: null`. Version ranges are recorded as text; -restore results are unknown. +as a group with `target_framework: null` when the `.nuspec` has no ``. +Beside `` elements, in any `` element, they are omitted and +a limitation gives their count: NuGet's restore-time reader ignores them, and +`nuget pack` refuses that mix. Version ranges are recorded as text; restore +results are unknown. `contents` lists file ZIP members with the stored ZIP `name`, a logical `path` (backslashes as `/`, leading `./` removed), uncompressed and compressed sizes, an `encrypted` flag, and a `path`-derived `role` (`lib`, `ref`, `runtimes`, `native`, `analyzers`, `build`, `buildTransitive`, `buildMultiTargeting`, -`content`, `contentFiles`, `tools`, `nuspec`, `opc`, or `unknown`). Directory -markers are omitted. Encrypted members are listed and not extracted. +`content`, `contentFiles`, `tools`, `nuspec`, `opc`, or `unknown`). `opc` marks +OPC packaging parts: `[Content_Types].xml`, `.rels` relationship parts, and +members under `_rels/` or `package/`, where `nuget pack` writes the core +properties `.psmdcp`. Directory markers are omitted. Encrypted members are +listed and not extracted. Unflagged non-ASCII names use the ZIP CP437 fallback unless a valid Unicode Path extra field supplies the name. For fallback names, limitations identify the member, retain the exact raw filename bytes as hex, and mark the source encoding diff --git a/docs/specs/artifacts/nuget-nupkg/spec.md b/docs/specs/artifacts/nuget-nupkg/spec.md index a6c08aa245..1a96206c57 100644 --- a/docs/specs/artifacts/nuget-nupkg/spec.md +++ b/docs/specs/artifacts/nuget-nupkg/spec.md @@ -16,11 +16,13 @@ executing anything in it or contacting a NuGet feed. `.nuspec`. Missing, ambiguous or malformed manifests succeed with the ZIP inventory, `identity: null` and an explicit limitation. - Report `identity`, `license`, `repository` and `dependency_groups` as spelled - in the `.nuspec`. Ungrouped dependencies form a group with - `target_framework: null`. Version ranges stay text; restore results are - unknown. + in the `.nuspec`. Without any ``, ungrouped dependencies form a group + with `target_framework: null`. Beside groups, in any `` element, + they are omitted with a limitation that counts them, as NuGet's restore-time + reader ignores them. Version ranges stay text; restore results are unknown. - List file ZIP members with sizes, an `encrypted` flag and a path-derived - NuGet folder `role`. Omit directory markers. + NuGet folder `role`. `[Content_Types].xml`, `.rels` parts, and members under + `_rels/` or `package/` are OPC packaging parts. Omit directory markers. - Bound the file size, ZIP entry count and `.nuspec` bytes with named allowances. Enforce the entry allowance while enumerating the ZIP. Refuse a file that is not a valid ZIP without a partial inventory. diff --git a/src/domain/nuget/nupkg.test.ts b/src/domain/nuget/nupkg.test.ts index fb37676a90..95b9a7b09b 100644 --- a/src/domain/nuget/nupkg.test.ts +++ b/src/domain/nuget/nupkg.test.ts @@ -103,5 +103,15 @@ it("derives NuGet folder roles from ZIP names", () => { expect(nugetNupkgEntryRole("Demo.Package.nuspec")).toBe("nuspec"); expect(nugetNupkgEntryRole("_rels/.rels")).toBe("opc"); expect(nugetNupkgEntryRole("[Content_Types].xml")).toBe("opc"); + expect( + nugetNupkgEntryRole( + "package/services/metadata/core-properties/0f07893ec48a4e929e4f9637270a574f.psmdcp", + ), + ).toBe("opc"); + expect(nugetNupkgEntryRole("PACKAGE\\services\\metadata\\x.psmdcp")).toBe( + "opc", + ); + expect(nugetNupkgEntryRole("package.txt")).toBe("unknown"); + expect(nugetNupkgEntryRole("lib/package/Demo.dll")).toBe("lib"); expect(nugetNupkgEntryRole("README.md")).toBe("unknown"); }); diff --git a/src/domain/nuget/nupkg.ts b/src/domain/nuget/nupkg.ts index 833526983e..211ed4644f 100644 --- a/src/domain/nuget/nupkg.ts +++ b/src/domain/nuget/nupkg.ts @@ -64,9 +64,13 @@ export const nugetNupkgLogicalPath = (name: string): string => export const nugetNupkgEntryRole = (name: string): NugetNupkgEntryRole => { const logical = nugetNupkgLogicalPath(name); const lower = logical.toLowerCase(); + // NuGet excludes `_rels/`, `package/` and `[Content_Types].xml` from package + // files; `nuget pack` writes the OPC core properties part under + // `package/services/metadata/core-properties/`. if ( lower === "[content_types].xml" || lower.startsWith("_rels/") || + lower.startsWith("package/") || lower.endsWith(".rels") ) return "opc"; diff --git a/src/nuget/NugetNupkgParser.test.ts b/src/nuget/NugetNupkgParser.test.ts index 2431daaeeb..43d62162c1 100644 --- a/src/nuget/NugetNupkgParser.test.ts +++ b/src/nuget/NugetNupkgParser.test.ts @@ -141,6 +141,9 @@ it("reads identity, license, repository, dependency groups and folder roles", as ); expect(report.coverage.status).toBe("complete"); expect(report.limitations).toContain(NUPKG_LIMITATIONS.memberRoles); + expect(report.limitations).not.toContainEqual( + expect.stringContaining("beside elements were omitted"), + ); }); it("keeps the stored ZIP member name beside its logical path", async () => { @@ -185,8 +188,50 @@ it("records ungrouped dependencies as a group with a null target framework", asy ], }, ]); + expect(report.limitations).not.toContain( + NUPKG_LIMITATIONS.ungroupedBesideGroups(1), + ); }); +const NET8_GROUP = + ''; + +it.for([ + ["in one element", `\n ${NET8_GROUP}`], + [ + "in a separate element", + `${NET8_GROUP}\n `, + ], +])( + "omits ungrouped dependencies beside groups %s, as NuGet does", + async ([, opening]) => { + const bytes = await nugetNupkgFixture({ + nuspec: ungroupedNuspec.replace("", opening!), + includeRels: false, + }); + const report = nugetNupkgSchema.parse( + await parseNugetNupkg(bytes, artifactOf(bytes), defaults), + ); + expect(report.dependency_groups).toEqual([ + { + target_framework: "net8.0", + dependencies: [ + { + id: "Bar", + version: "2.0.0", + include: null, + exclude: null, + development_dependency: null, + }, + ], + }, + ]); + expect(report.limitations).toContain( + NUPKG_LIMITATIONS.ungroupedBesideGroups(1), + ); + }, +); + it("inventories a package with no .nuspec and leaves identity unknown", async () => { const bytes = await nugetNupkgMissingNuspecFixture(); const report = nugetNupkgSchema.parse( diff --git a/src/nuget/NugetNupkgParser.ts b/src/nuget/NugetNupkgParser.ts index 4f5262638c..2ac530de90 100644 --- a/src/nuget/NugetNupkgParser.ts +++ b/src/nuget/NugetNupkgParser.ts @@ -44,6 +44,8 @@ export const NUPKG_LIMITATIONS = { ambiguousRootNuspec: "Multiple root .nuspec members are present; identity was not decoded.", malformedNuspec: "The selected .nuspec is not well-formed XML.", + ungroupedBesideGroups: (count: number): string => + `${String(count)} ungrouped element(s) beside elements were omitted: NuGet's restore-time NuspecReader reads only the groups when any group is present, and nuget pack refuses this mix.`, } as const; const BASE_LIMITATIONS = [ @@ -280,11 +282,17 @@ const parseBooleanAttribute = (value: string | null): boolean | null => { const parseDependencies = ( metadata: Element, + limitations: string[], ): NugetNupkg["dependency_groups"] => { - const container = firstNamed(metadata, "dependencies"); - if (container === undefined) return []; - const groups = childrenNamed(container, "group"); - const ungrouped = childrenNamed(container, "dependency"); + // NuspecReader walks every element, with one decision about + // groups across all of them. + const containers = childrenNamed(metadata, "dependencies"); + const groups = containers.flatMap((container) => + childrenNamed(container, "group"), + ); + const ungrouped = containers.flatMap((container) => + childrenNamed(container, "dependency"), + ); const readDependency = ( element: Element, ): NugetNupkg["dependency_groups"][number]["dependencies"][number] => ({ @@ -302,18 +310,15 @@ const parseDependencies = ( target_framework: attribute(element, "targetFramework"), dependencies: childrenNamed(element, "dependency").map(readDependency), }); - if (groups.length > 0) - return [ - ...groups.map(fromGroup), - ...(ungrouped.length === 0 - ? [] - : [ - { - target_framework: null, - dependencies: ungrouped.map(readDependency), - }, - ]), - ]; + // NuGet's NuspecReader reads ungrouped dependencies only when no group is + // present, so those beside groups never reach restore. + if (groups.length > 0) { + if (ungrouped.length > 0) + limitations.push( + NUPKG_LIMITATIONS.ungroupedBesideGroups(ungrouped.length), + ); + return groups.map(fromGroup); + } if (ungrouped.length === 0) return []; return [ { target_framework: null, dependencies: ungrouped.map(readDependency) }, @@ -393,7 +398,7 @@ const parseNuspecDocument = ( commit: attribute(repositoryElement, "commit"), branch: attribute(repositoryElement, "branch"), }, - dependency_groups: parseDependencies(metadata), + dependency_groups: parseDependencies(metadata, limitations), }; };