feat: add flag schema inspection

[privatenumber]

Context

Cleye needs to reason about the same flag recognition surface that type-flag uses internally for conflict checks, strict-mode suggestions, and help metadata. Today that requires Cleye to reconstruct parser rules for camel/kebab names, aliases, single-character flags, and boolean negation.

This PR proposes the smallest type-flag-side inspection surface for that integration work.

Changes

• Add inspectFlags(schema, options?)
• Export InspectFlagsOptions and InspectedFlag
• Refactor existing flag-name and alias normalization into shared internal utilities used by both parsing and inspection
• Document the helper as an integration API, not a primary user-facing feature
• Add runtime and type coverage for:
  • camelCase plus acronym kebab names
  • aliases
  • single-character flag names
  • array and boolean metadata
  • boolean negation tokens
  • explicit no* flag precedence over negation
  • validation parity with typeFlag()

API Sketch

const inspected = inspectFlags({
	getID: String,
	verbose: {
		type: Boolean,
		alias: 'v',
	},
}, { booleanNegation: true });

inspected[0].tokens; // ['--getID', '--get-id']
inspected[1].tokens; // ['--verbose', '-v', '--no-verbose', '--no-v']

typeFlag() does not allocate this metadata during normal parsing. Inspection is opt-in and should remain tree-shakable for consumers that do not import it.

Follow-Up

If this API shape looks reasonable, the next step is to prototype Cleye against it and measure whether it removes local recognition duplication without growing the emitted bundle.

[github-actions]

📊 Package size report   9%↑

File	Before (Size / Gzip)	After (Size / Gzip)
dist/index.d.ts	7.2 kB / 2.6 kB	17%↑8.5 kB / 13%↑2.9 kB
dist/index.mjs	3.9 kB / 1.9 kB	25%↑4.8 kB / 20%↑2.3 kB
README.md	17.3 kB / 5.9 kB	6%↑18.3 kB / 5%↑6.2 kB
Total (Includes all files)	36.7 kB / 14.4 kB	9%↑39.9 kB / 7%↑15.4 kB
Tarball size	13.3 kB	7%↑14.2 kB

Unchanged files

File	Size (Size / Gzip)
LICENSE	1.1 kB / 667 B
package.json	1.3 kB / 615 B
skills/type-flag/SKILL.md	5.8 kB / 2.7 kB

_{🤖 This report was automatically generated by pkg-size-action}