feat: warn on unknown options and suggest the intended one

Author: danielroe

packages/nuxt-cli/src/main.ts

@@ -20,6 +20,7 @@ import { setupProxySupport } from './utils/network'
 import{withLocalBinPath}from'./utils/path-env'
 import{resolveProjectDir}from'./utils/paths'
 import{templateNames}from'./utils/templates/names'
+import{findUnknownFlags,suggestFlags}from'./utils/unknown-args'
 import{scheduleUpdateNudge}from'./utils/update-lazy'
 
 // Node.js only reads `NODE_USE_ENV_PROXY` during bootstrap, so this cannot make
@@ -68,6 +69,10 @@ const _main = defineCommand({
 process.exit(0)
 }
 
+if(command&&Object.hasOwn(commands,command)){
+awaitwarnUnknownFlags(command,ctx.rawArgs)
+}
+
 // allow running arbitrary commands if there's a locally registered binary with `nuxt-` prefix
 if(ctx.args.command&&!Object.hasOwn(commands,ctx.args.command)){
 constcwd=resolve(ctx.args.cwd)
@@ -93,4 +98,39 @@ const _main = defineCommand({
 },
 })
 
+/**
+ * Report long flags the resolved command does not declare. Unknown flags are
+ * otherwise parsed and silently ignored, so a misspelling looks like the flag
+ * simply had no effect.
+ */
+asyncfunctionwarnUnknownFlags(command: string,rawArgs: string[]): Promise<void>{
+letdef: CommandDef<any>
+try{
+def=awaitcommands[commandaskeyoftypeofcommands]()asCommandDef<any>
+constsubCommands=awaitresolveLazy(def.subCommands)
+constsubCommand=rawArgs.slice(1).find(arg=>!arg.startsWith('-'))
+if(subCommands&&subCommand&&Object.hasOwn(subCommands,subCommand)){
+def=awaitresolveLazy(subCommands[subCommand])asCommandDef<any>
+}
+}
+catch(err){
+debug('Could not check arguments:',err)
+return
+}
+
+constargsDef={ ...cwdArgs, ...awaitresolveLazy(def.args)}
+constunknown=findUnknownFlags(argsDef,rawArgs.slice(1))
+if(unknown.flags.length===0){
+return
+}
+
+for(const{ flag, suggestion }ofawaitsuggestFlags(unknown)){
+logger.warn(`Unknown option ${styleText('cyan',flag)}.${suggestion ? ` Did you mean ${styleText('cyan',suggestion)}?` : ''}`)
+}
+}
+
+functionresolveLazy<T>(value: T|(()=>T|Promise<T>)|undefined): Promise<T|undefined>{
+returnPromise.resolve(typeofvalue==='function' ? (valueas()=>T|Promise<T>)() : value)
+}
+
 exportconstmain=_mainasCommandDef<any>

packages/nuxt-cli/src/utils/unknown-args.ts

@@ -0,0 +1,79 @@
+importtype{ArgsDef}from'citty'
+
+/** Always accepted by citty, so never reported as unknown. */
+constBUILTIN_FLAGS=['help','version']
+
+/** Low enough to catch a wrong case (`--loglevel`) or a dropped letter, high enough not to invent a match. */
+constSUGGESTION_THRESHOLD=0.3
+
+constLEADING_DASHES_RE=/^--/
+constNEGATION_RE=/^no-/
+
+exportinterfaceUnknownFlags{
+flags: string[]
+known: string[]
+}
+
+/**
+ * Long flags in `rawArgs` that `argsDef` does not declare.
+ *
+ * Only `--long` forms are considered. A bundle of short flags (`-abc`) cannot be
+ * told apart from a single misspelled one, and guessing wrong is worse than
+ * staying quiet.
+ */
+exportfunctionfindUnknownFlags(argsDef: ArgsDef,rawArgs: string[]): UnknownFlags{
+constknown=newSet<string>(BUILTIN_FLAGS)
+for(const[name,def]ofObject.entries(argsDef)){
+known.add(name)
+constalias=(defas{alias?: string|string[]}).alias
+for(constentryofArray.isArray(alias) ? alias : alias ? [alias] : []){
+known.add(entry)
+}
+}
+
+constseparator=rawArgs.indexOf('--')
+constargv=separator===-1 ? rawArgs : rawArgs.slice(0,separator)
+
+constflags: string[]=[]
+for(constargofargv){
+if(!arg.startsWith('--')||arg==='--'){
+continue
+}
+constequals=arg.indexOf('=')
+constname=(equals===-1 ? arg : arg.slice(0,equals)).replace(LEADING_DASHES_RE,'')
+if(name&&!isKnown(known,name)&&!flags.includes(name)){
+flags.push(name)
+}
+}
+return{ flags,known: [...known]}
+}
+
+/**
+ * The declared flag each unknown flag was most likely meant to be. Resolved
+ * separately so the fuzzy matcher is only loaded once something is wrong.
+ */
+exportasyncfunctionsuggestFlags({ flags, known }: UnknownFlags): Promise<Array<{flag: string,suggestion?: string}>>{
+const{default: fuzzysort}=awaitimport('fuzzysort')
+returnflags.map((flag)=>{
+const[match]=fuzzysort.go(flag.replace(NEGATION_RE,''),known,{limit: 1,threshold: SUGGESTION_THRESHOLD})
+return{flag: `--${flag}`,suggestion: match&&`--${match.target}`}
+})
+}
+
+/**
+ * Dotted flags are declared either whole (`https.cert`) or as the object that
+ * holds them (`https`), and a boolean may be negated with a `no-` prefix.
+ */
+functionisKnown(known: Set<string>,name: string): boolean{
+for(constcandidateofnewSet([name,name.replace(NEGATION_RE,'')])){
+if(known.has(candidate)){
+returntrue
+}
+for(letdot=candidate.lastIndexOf('.');dot!==-1;dot=candidate.lastIndexOf('.',dot-1)){
+if(known.has(candidate.slice(0,dot))){
+returntrue
+}
+}
+}
+returnfalse
+}

packages/nuxt-cli/test/unit/unknown-args.spec.ts

@@ -0,0 +1,95 @@
+importtype{ArgsDef,CommandDef}from'citty'
+
+import{describe,expect,it}from'vitest'
+
+import{commands}from'../../src/commands'
+import{cwdArgs}from'../../src/commands/_shared'
+import{findUnknownFlags,suggestFlags}from'../../src/utils/unknown-args'
+
+constargsDef={
+'cwd': {type: 'string'},
+'json': {type: 'boolean'},
+'logLevel': {type: 'string'},
+'fork': {type: 'boolean'},
+'https': {type: 'boolean'},
+'open.url': {type: 'string'},
+'port': {type: 'string',alias: ['p']},
+}satisfiesArgsDef
+
+describe('findUnknownFlags',()=>{
+it('should accept declared flags, aliases and negations',()=>{
+const{ flags }=findUnknownFlags(argsDef,['--cwd=.','--json','--no-fork','--port','3000','--help','--version'])
+expect(flags).toEqual([])
+})
+
+it('should accept a dotted flag declared whole or by its parent',()=>{
+expect(findUnknownFlags(argsDef,['--open.url=/admin','--https.cert=x','--https.key','y']).flags).toEqual([])
+})
+
+it('should report a flag that is not declared',()=>{
+expect(findUnknownFlags(argsDef,['--strictport']).flags).toEqual(['strictport'])
+})
+
+it('should report each unknown flag once',()=>{
+expect(findUnknownFlags(argsDef,['--nope','--nope=1']).flags).toEqual(['nope'])
+})
+
+it('should ignore short flags and everything after a separator',()=>{
+expect(findUnknownFlags(argsDef,['-abc','-x','--','--nope']).flags).toEqual([])
+})
+
+it('should ignore positionals and a bare separator',()=>{
+expect(findUnknownFlags(argsDef,['build','./app','--']).flags).toEqual([])
+})
+})
+
+describe('suggestFlags',()=>{
+it('should suggest the declared flag a misspelling is closest to',async()=>{
+awaitexpect(suggestFlags(findUnknownFlags(argsDef,['--loglevel','--jsn']))).resolves.toEqual([
+{flag: '--loglevel',suggestion: '--logLevel'},
+{flag: '--jsn',suggestion: '--json'},
+])
+})
+
+it('should not invent a suggestion for an unrelated flag',async()=>{
+awaitexpect(suggestFlags(findUnknownFlags(argsDef,['--xyzzy']))).resolves.toEqual([{flag: '--xyzzy',suggestion: undefined}])
+})
+})
+
+describe('declared command arguments',()=>{
+it('should never be reported as unknown',async()=>{
+constreported: Record<string,string[]>={}
+
+for(constnameofObject.keys(commands)){
+for(const[commandName,def]ofawaitresolveCommands(name)){
+constargs=awaitresolveLazy((defasCommandDef<any>).args)??{}
+constargv: string[]=[]
+for(const[flag,definition]ofObject.entries(argsasArgsDef)){
+if((definitionas{type?: string}).type==='positional'){
+continue
+}
+argv.push(`--${flag}`)
+}
+const{ flags }=findUnknownFlags({ ...cwdArgs, ...args},argv)
+if(flags.length>0){
+reported[commandName]=flags
+}
+}
+}
+
+expect(reported).toEqual({})
+})
+})
+
+asyncfunctionresolveCommands(name: string): Promise<Array<[string,unknown]>>{
+constdef=awaitcommands[nameaskeyoftypeofcommands]()asCommandDef<any>
+constsubCommands=awaitresolveLazy(def.subCommands)
+if(!subCommands){
+return[[name,def]]
+}
+returnPromise.all(Object.entries(subCommands).map(async([subName,subDef])=>[`${name}${subName}`,awaitresolveLazy(subDef)]as[string,unknown]))
+}
+
+functionresolveLazy<T>(value: T|(()=>T|Promise<T>)|undefined): Promise<T|undefined>{
+returnPromise.resolve(typeofvalue==='function' ? (valueas()=>T|Promise<T>)() : value)
+}