import npa, { npa2, npaTry, npaTry2 } from '@yarn-tool/npm-package-arg-util';

// Parse a package with version (legacy, strict name validation)
// 解析帶版本的套件（舊版，嚴格名稱驗證）
const result = npa('lodash@4.17.21');
console.log(result.name);    // 'lodash'
console.log(result.type);    // 'version'
console.log(result.rawSpec); // '4.17.21'
console.log(result.fetchSpec); // '4.17.21'

// Parse with flexible options (new version)
// 使用靈活選項解析（新版本）
const result2 = npa2('lodash@^4.17.0', {
  allowedType: ['version', 'range']
});

// Parse a scoped package / 解析範圍套件
const scoped = npa('@types/node@^18.0.0');
console.log(scoped.name);   // '@types/node'
console.log(scoped.scope);  // '@types'
console.log(scoped.escapedName); // '@types%2fnode'

// Safe parsing without errors / 安全解析不拋出錯誤
const safe = npaTry('invalid-package-argument');
console.log(safe); // undefined if parsing fails / 如果解析失敗則為 undefined

import { npa2, npaTry2 } from '@yarn-tool/npm-package-arg-util';
import type { IOptionsNpaUtil } from '@yarn-tool/npm-package-arg-util';

// Options for parsing
// 解析選項
const options: IOptionsNpaUtil = {
  // Base directory for resolving relative paths
  // 解析相對路徑的基礎目錄
  where: process.cwd(),
  
  // Whether to validate that result has a name
  // 是否驗證結果有名稱
  shouldHasName: true,
  
  // Array of allowed result types
  // 允許的結果類型陣列
  allowedType: ['version', 'range', 'tag'],
};

// Parse with options
// 使用選項解析
const result = npa2('lodash@^4.17.0', options);

// Parse GitHub repo without name validation
// 解析 GitHub 儲存庫但不驗證名稱
const gitRepo = npa2('user/repo#branch', {
  shouldHasName: false
});

import { 
  isAliasResult, 
  isFileResult, 
  isRegistryResult, 
  isHostedGitResult, 
  isURLResult 
} from '@yarn-tool/npm-package-arg-util/lib/detect';

const result = npa('lodash@^4.17.0');

if (isRegistryResult(result)) {
  // TypeScript knows result is RegistryResult
  // TypeScript 知道 result 是 RegistryResult
  console.log('Package from npm registry / 來自 npm registry 的套件');
  console.log('fetchSpec:', result.fetchSpec); // '^4.17.0'
}

if (isHostedGitResult(result)) {
  // TypeScript knows result is HostedGitResult
  // TypeScript 知道 result 是 HostedGitResult
  console.log('Package from GitHub/GitLab / 來自 GitHub/GitLab 的套件');
  console.log('domain:', result.hosted?.domain); // 'github.com'
}

import { 
  assertNpaResultHasName, 
  assertNpaResultByType, 
  assertNpaResultAll 
} from '@yarn-tool/npm-package-arg-util/lib/assert';

const result = npa('lodash@4.17.21');

// Assert result has a valid name
// 斷言結果具有有效名稱
assertNpaResultHasName(result);

// Assert result has specific type
// 斷言結果具有特定類型
assertNpaResultByType(result, 'version');

// Comprehensive validation with options
// 使用選項進行全面驗證
assertNpaResultAll(result, {
  shouldHasName: true,
  allowedType: ['version', 'range'],
});

import { getSemverFromNpaResult } from '@yarn-tool/npm-package-arg-util';

const result = npa('lodash@^4.17.21');
const version = getSemverFromNpaResult(result);
console.log(version); // '^4.17.21'

// Works with aliases too / 也適用於別名
const alias = npa('my-lodash@npm:lodash@4.17.21');
const aliasVersion = getSemverFromNpaResult(alias);
console.log(aliasVersion); // '4.17.21'

// Package without version returns '*'
// 沒有版本的套件返回 '*'
const noVersion = npa('lodash');
console.log(getSemverFromNpaResult(noVersion)); // '*'

import { parsePackageName } from '@yarn-tool/npm-package-arg-util/lib/parseArgvPkgName';

const parsed = parsePackageName('@types/node@^18.0.0');
console.log(parsed);
// {
//   type: 'range',
//   name: '@types/node',
//   scope: '@types',
//   subname: 'node',
//   semver: '^18.0.0',
//   result: ...
// }

import { packageNameToTypes } from '@yarn-tool/npm-package-arg-util/lib/packageNameToTypes';

// Convert simple package / 轉換簡單套件
const types1 = packageNameToTypes('lodash');
console.log(types1.name); // '@types/lodash'

// Convert scoped package (uses double underscore) / 轉換範圍套件（使用雙底線）
const types2 = packageNameToTypes('@next/typescript');
console.log(types2.name); // '@types/next__typescript'

// Package already @types / 已經是 @types 的套件
const types3 = packageNameToTypes('@types/node');
console.log(types3.name); // '@types/node'

import { generatePackageArg } from '@yarn-tool/npm-package-arg-util/lib/generatePackageArg';

// Without version / 不含版本
const arg1 = generatePackageArg({ name: 'lodash' });
console.log(arg1); // 'lodash'

// With version / 含版本
const arg2 = generatePackageArg({ name: 'lodash', semver: '^4.17.0' }, true);
console.log(arg2); // 'lodash@^4.17.0'

interface IOptionsNpaUtil {
  /** Base directory for resolving relative paths / 解析相對路徑的基礎目錄 */
  where?: string;
  
  /** Whether to validate that result has a name / 是否驗證結果有名稱 */
  shouldHasName?: boolean;
  
  /** Array of allowed result types / 允許的結果類型陣列 */
  allowedType?: IResultType[];
  
  /** Custom npa function to use / 使用的自定義 npa 函數 */
  npa?: typeof _npa;
}

// Union type for all result types with names
// 所有帶有名稱的結果類型的聯合類型
type IResult = AliasResult | FileResult | RegistryResult | HostedGitResult | URLResult;

// Union type including results without names (git URLs, etc.)
// 包含沒有名稱的結果的聯合類型（git URL 等）
type IResultAll = IResult | Result;

// Result type string
// 結果類型字串
type IResultType = 'alias' | 'file' | 'directory' | 'version' | 'range' | 'tag' | 'git' | 'remote';