docs: initial

.config/typedoc.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["../label/exports.ts"],
+  "readme": "none",
+  "out": "../docs/label",
+  "plugin": ["typedoc-plugin-markdown"],
+  "hidePageHeader": true,
+  "flattenOutputFiles": true,
+  "indexFormat": "table",
+  "outputFileStrategy": "members",
+  "entryFileName": "index",
+  "excludeInternal": true,
+  "disableSources": true
+}

.gitignore

@@ -28,3 +28,6 @@ log/
 **/*/typings/auto-generated
 
 modern.config.local.*
+
+tsdoc-metadata.json
+temp/

README.md

@@ -1,2 +1,17 @@
 # @109cafe/label
 
+A library for parsing, resolving, and querying Bazel-like labels.
+
+This package provides:
+
+- [TargetQuery](docs/label/Class.TargetQuery.md) for querying targets
+- [BazelLikeSpec](docs/label/Class.BazelLikeSpec.md) for implementing your own Bazel-like label specification
+- [parse](docs/label/Function.parse.md) for parsing labels
+- [build](docs/label/Function.build.md) for building labels
+- [resolve](docs/label/Function.resolve.md) for resolving labels
+
+This package is filesystem-agnostic so that you can use it in any JavaScript runtime.
+
+If you'd like to build a Bazel-like query in Node.js with `node:fs` and `glob`, please refer to the [@109cafe/dummy implementation](./dummy-spec/dummy-spec.ts).
+
+[API References](docs/label/index.md)

biome.json

@@ -12,11 +12,11 @@
     }
   },
   "files": {
-    "ignore": ["worker-configuration.d.ts", "**/gen/**", "**/*.gen.*"]
+    "ignore": ["worker-configuration.d.ts", "**/gen/**", "**/*.gen.*", "**/docs/**"]
   },
   "overrides": [
     {
-      "include": [".vscode/*.json", "**/tsconfig.json"],
+      "include": [".vscode/*.json", "**/tsconfig.json", "**/api-extractor.json"],
       "json": { "parser": { "allowComments": true, "allowTrailingCommas": true } }
     }
   ],

docs/label/Class.BazelLikeSpec.md

@@ -0,0 +1,123 @@
+[@109cafe/label](index.md) / BazelLikeSpec
+
+# Class: `abstract` BazelLikeSpec\<Target\>
+
+An abstract spec for Bazel-like build systems
+
+## Type Parameters
+
+• **Target** *extends* [`BazelTarget`](TypeAlias.BazelTarget.md)
+
+## Implements
+
+- [`Spec`](Interface.Spec.md)\<`Target`\>
+
+## Constructors
+
+### new BazelLikeSpec()
+
+> **new BazelLikeSpec**\<`Target`\>(): [`BazelLikeSpec`](Class.BazelLikeSpec.md)\<`Target`\>
+
+#### Returns
+
+[`BazelLikeSpec`](Class.BazelLikeSpec.md)\<`Target`\>
+
+## Methods
+
+### extract()
+
+> **extract**(`targets`, `target`): `null` \| `string` \| `string`[]
+
+Extract targets from a package
+
+#### Parameters
+
+• **targets**: `Record`\<`string`, `Target`\>
+
+the map returned by `load`
+
+• **target**: `string`
+
+the target name in a label
+
+#### Returns
+
+`null` \| `string` \| `string`[]
+
+the matched target names or `null` if not found
+
+#### Implementation of
+
+[`Spec`](Interface.Spec.md).[`extract`](Interface.Spec.md#extract)
+
+***
+
+### load()
+
+> `abstract` **load**(`pkg`): `Promise`\<`Record`\<`string`, `Target`\>\>
+
+Load targets from a package
+
+#### Parameters
+
+• **pkg**: [`ExactLabel`](Interface.ExactLabel.md)
+
+the label that is returned by `lookup`
+
+#### Returns
+
+`Promise`\<`Record`\<`string`, `Target`\>\>
+
+a `<TargetName, Target>` map for the package
+
+#### Implementation of
+
+[`Spec`](Interface.Spec.md).[`load`](Interface.Spec.md#load)
+
+***
+
+### lookup()
+
+> `abstract` **lookup**(`label`): `Promise`\<[`ExactLabel`](Interface.ExactLabel.md)[]\>
+
+Lookup packages by label. Typically, it should return a list label for the `BUILD` files of these packages.
+
+#### Parameters
+
+• **label**: [`Label`](Interface.Label.md)
+
+the label to lookup
+
+#### Returns
+
+`Promise`\<[`ExactLabel`](Interface.ExactLabel.md)[]\>
+
+a list of matched packages presented by `ExactLabel`
+
+#### Implementation of
+
+[`Spec`](Interface.Spec.md).[`lookup`](Interface.Spec.md#lookup)
+
+***
+
+### validate()
+
+> **validate**(`label`): `undefined` \| "\`...\` can only be used with wildcard targets"
+
+Validate a label
+
+#### Parameters
+
+• **label**: [`Label`](Interface.Label.md)
+
+the label to validate
+
+#### Returns
+
+`undefined` \| "\`...\` can only be used with wildcard targets"
+
+a string or an `Error` for invalid label, and falsy values for valid label
+
+#### Implementation of
+
+[`Spec`](Interface.Spec.md).[`validate`](Interface.Spec.md#validate)

docs/label/Class.CannotResolveFromSubPackages.md

@@ -0,0 +1,153 @@
+[@109cafe/label](index.md) / CannotResolveFromSubPackages
+
+# Class: CannotResolveFromSubPackages
+
+Exception for resolving from sub-packages
+
+## Extends
+
+- `Error`
+
+## Constructors
+
+### new CannotResolveFromSubPackages()
+
+> **new CannotResolveFromSubPackages**(`label`): [`CannotResolveFromSubPackages`](Class.CannotResolveFromSubPackages.md)
+
+#### Parameters
+
+• **label**: [`Label`](Interface.Label.md)
+
+#### Returns
+
+[`CannotResolveFromSubPackages`](Class.CannotResolveFromSubPackages.md)
+
+#### Overrides
+
+`Error.constructor`
+
+## Properties
+
+### cause?
+
+> `optional` **cause**: `unknown`
+
+#### Inherited from
+
+`Error.cause`
+
+***
+
+### label
+
+> **label**: [`Label`](Interface.Label.md)
+
+***
+
+### message
+
+> **message**: `string`
+
+#### Inherited from
+
+`Error.message`
+
+***
+
+### name
+
+> **name**: `string`
+
+#### Inherited from
+
+`Error.name`
+
+***
+
+### stack?
+
+> `optional` **stack**: `string`
+
+#### Inherited from
+
+`Error.stack`
+
+***
+
+### prepareStackTrace()?
+
+> `static` `optional` **prepareStackTrace**: (`err`, `stackTraces`) => `any`
+
+Optional override for formatting stack traces
+
+#### Parameters
+
+• **err**: `Error`
+
+• **stackTraces**: `CallSite`[]
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+`Error.prepareStackTrace`
+
+***
+
+### stackTraceLimit
+
+> `static` **stackTraceLimit**: `number`
+
+#### Inherited from
+
+`Error.stackTraceLimit`
+
+## Methods
+
+### captureStackTrace()
+
+#### captureStackTrace(targetObject, constructorOpt)
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`
+
+Create .stack property on a target object
+
+##### Parameters
+
+• **targetObject**: `object`
+
+• **constructorOpt?**: `Function`
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+`Error.captureStackTrace`
+
+#### captureStackTrace(targetObject, constructorOpt)
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`
+
+Create .stack property on a target object
+
+##### Parameters
+
+• **targetObject**: `object`
+
+• **constructorOpt?**: `Function`
+
+##### Returns
+
+`void`
+
+##### Inherited from
+
+`Error.captureStackTrace`