metascope 0.1.0

package/readme.md

@@ -0,0 +1,548 @@
+<!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->
+
+<!-- title -->
+
+# metascope
+
+<!-- /title -->
+
+<!-- badges -->
+
+[![NPM Package metascope](https://img.shields.io/npm/v/metascope.svg)](https://npmjs.com/package/metascope)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<!-- /badges -->
+
+<!-- short-description -->
+
+**A CLI tool and TypeScript library to easily extract metadata from all kinds of software repositories.**
+
+<!-- /short-description -->
+
+> [!NOTE]
+>
+> Metascope is under development. Expect breaking changes until a 1.0 release.
+
+## Overview
+
+Metascope aggregates metadata from a local code repository into a single monolithic JSON object. Given a project directory, it checks multiple sources in parallel — local git history, package manifests, the GitHub API, the NPM registry, lines of code analysis, and more — and returns a JSON object containing everything it could find.
+
+From there, an (optional) template system lets you refine and transform the output to reflect exactly which fields you need, useful for archival purposes, populating dashboards, or feeding data into other tools. The template system also provides a spec-compliant implementation of the [CodeMeta](https://codemeta.github.io/) vocabulary, allowing easy generation of `codemeta.json` files for a semantically normalized view of a variety of project types.
+
+Highlights:
+
+- **A wide net**\
+  Metascope pulls project metadata from many available sources: `package.json`, `pyproject.toml`, NPM, PyPI, GitHub, git, filesystem stats, and [more](#sources).
+
+- **Graceful degradation**\
+  Each source checks its own availability before extraction. Missing tools, unavailable APIs, or absent credentials are silently skipped — you always get back whatever data _is_ available.
+
+- **Parallel extraction**\
+  After an initial codemeta pass for discovery hints (package name, repository URL, keywords), all remaining sources are checked and extracted concurrently.
+
+- **Typed templates**\
+  The `defineTemplate()` helper provides full autocomplete on available fields. TypeScript infers the return type from your template function, so `getMetadata()` returns exactly the shape you need.
+
+- **CLI and library**\
+  Use it as a command-line tool for quick inspection or pipe-friendly JSON output, or import it as a library for programmatic access with full type safety.
+
+## Getting started
+
+### Dependencies
+
+Metascope requires [Node.js](https://nodejs.org/) 22.17+. It is implemented in TypeScript, ships as ESM, and bundles complete type definitions.
+
+Metascope also requires a recent version of [git](https://git-scm.com/) on your path for quickly identifying ignored files and aggregating repository statistics.
+
+Optional external tools:
+
+- [GitHub CLI](https://cli.github.com)\
+  Used as a fallback for GitHub API authentication if no token is provided via `--github-token` or `$GITHUB_TOKEN`. It's trivially installed from [Homebrew](https://brew.sh/): `brew install gh`.
+
+### Installation
+
+Invoke directly on the current directory:
+
+```sh
+npx metascope
+```
+
+...or install locally:
+
+```sh
+npm install metascope
+```
+
+...or install globally:
+
+```sh
+npm install --global metascope
+```
+
+If you're using PNPM, you can safely ignore the build scripts for the tree-sitter dependencies, since we're only interested in their bundled WASM implementations.
+
+In your `pnpm-workspace.yaml`:
+
+```yaml
+ignoredBuiltDependencies:
+  - tree-sitter-python
+  - tree-sitter-ruby
+```
+
+## Usage
+
+### CLI
+
+<!-- cli-help -->
+
+#### Command: `metascope`
+
+Extract metadata from a code repository.
+
+Usage:
+
+```txt
+metascope [path]
+```
+
+| Positional Argument | Description            | Type     | Default |
+| ------------------- | ---------------------- | -------- | ------- |
+| `path`              | Project directory path | `string` | `"."`   |
+
+| Option                 | Description                                                                                                                                                                | Type      | Default |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
+| `--template`<br>`-t`   | Built-in template name (`codemeta`, `frontmatter`, `project`) or path to a custom template file                                                                            | `string`  |         |
+| `--github-token`       | GitHub API token (or set `$GITHUB_TOKEN`)                                                                                                                                  | `string`  |         |
+| `--author-name`        | Optional author name(s) for ownership checks in templates                                                                                                                  | `array`   |         |
+| `--github-account`     | Optional GitHub account name(s) for ownership checks in templates                                                                                                          | `array`   |         |
+| `--absolute`           | Output absolute paths. Use `--no-absolute` for relative paths.                                                                                                             | `boolean` | `true`  |
+| `--offline`            | Skip sources requiring network requests                                                                                                                                    | `boolean` | `false` |
+| `--no-ignore`          | Include files ignored by .gitignore in the file tree                                                                                                                       | `boolean` | `false` |
+| `--recursive`<br>`-r`  | Search for metadata files recursively in subdirectories                                                                                                                    | `boolean` | `false` |
+| `--workspaces`<br>`-w` | Include workspace-specific metadata in monorepos; pass a `boolean` to enable or disable auto-detection, or pass one or more `string`s to explicitly define workspace paths |           | `true`  |
+| `--verbose`            | Run with verbose logging                                                                                                                                                   | `boolean` | `false` |
+| `--help`<br>`-h`       | Show help                                                                                                                                                                  | `boolean` |         |
+| `--version`<br>`-v`    | Show version number                                                                                                                                                        | `boolean` |         |
+
+<!-- /cli-help -->
+
+#### Examples
+
+##### Basic metadata extraction
+
+Extract all available metadata from the current directory:
+
+```sh
+metascope
+```
+
+Output is pretty-printed JSON when writing to a terminal, compact JSON when piped.
+
+##### Scan a specific directory
+
+```sh
+metascope /path/to/project
+```
+
+##### Use a built-in template
+
+```sh
+metascope --template project
+```
+
+##### Pass template data for ownership checks
+
+Some preset templates return information based on the (relative) ownership status of a repo. This requires additional context data, which can be passed in via additional CLI flags:
+
+```sh
+metascope --template project --author-name "Jane Doe" --github-account janedoe
+```
+
+Multiple values are supported:
+
+```sh
+metascope --template project --author-name "Jane Doe" "John Doe" --github-account janedoe johndoe
+```
+
+##### Use a custom template file
+
+```sh
+metascope --template ./my-template.ts
+```
+
+Where `my-template.ts` might look like:
+
+```ts
+import { defineTemplate, helpers } from 'metascope'
+
+export default defineTemplate(({ codemetaJson, github, gitStats }) => {
+  const codemeta = helpers.firstOf(codemetaJson)
+  const git = helpers.firstOf(gitStats)
+  const gh = helpers.firstOf(github)
+  return {
+    commits: git?.data.commitCount,
+    name: codemeta?.data.name,
+    stars: gh?.data.stargazerCount,
+    version: codemeta?.data.version,
+  }
+})
+```
+
+##### Pipe compact JSON to another tool
+
+```sh
+metascope | jq '.github.stargazerCount'
+```
+
+##### Provide a GitHub token
+
+An optional GitHub token can allow access to metadata about private repositories, and raises the request limit if you're operating on a large collection of repositories:
+
+```sh
+metascope --github-token ghp_xxxxxxxxxxxx
+```
+
+Or set the `GITHUB_TOKEN` environment variable, or authenticate via `gh auth login`. Metascope will attempt to find a credential without bothering you.
+
+##### Verbose logging
+
+```sh
+metascope --verbose
+```
+
+Logs source availability checks, extraction durations, and other diagnostics to stderr.
+
+### API
+
+The `metascope` library exports `getMetadata` as its primary function, `defineTemplate` for type-safe template authoring, and a `helpers` namespace with utility functions for working with metadata in templates.
+
+#### `getMetadata`
+
+```ts
+// Without a template — returns full MetadataContext
+function getMetadata(options: GetMetadataOptions): Promise<MetadataContext>
+
+// With a template — returns the template's return type
+function getMetadata<T>(options: GetMetadataTemplateOptions<T>): Promise<T>
+```
+
+The function accepts a project directory path, optional credentials, and an optional template (a built-in name or a template function). It returns a promise resolving to either the full `MetadataContext` or the shaped output of your template.
+
+All `undefined` values and empty source objects are deep-stripped from the output before returning.
+
+#### `defineTemplate`
+
+```ts
+function defineTemplate<T>(
+  transform: (context: MetadataContext, templateData: TemplateData) => T,
+): Template<T>
+```
+
+An identity wrapper that provides autocomplete and type inference when authoring templates. The optional second `templateData` argument provides user-supplied values (like author names or GitHub accounts) for parameterized ownership checks. Templates that don't need it can simply ignore the argument. Template developers can pass additional values as needed.
+
+#### Examples
+
+##### Get all metadata
+
+```ts
+import { getMetadata, helpers } from 'metascope'
+
+const metadata = await getMetadata({ path: '.' })
+console.log(helpers.firstOf(metadata.codemetaJson)?.data.name)
+console.log(helpers.firstOf(metadata.github)?.data.stargazerCount)
+console.log(helpers.firstOf(metadata.gitStats)?.data.commitCount)
+```
+
+_See [output sample](./docs/metascope-basic.json) for this repository._
+
+##### Get shaped metadata via a template
+
+```ts
+import { defineTemplate, getMetadata, helpers } from 'metascope'
+
+const template = defineTemplate(({ codemetaJson, github }) => ({
+  name: helpers.firstOf(codemetaJson)?.data.name,
+  stars: helpers.firstOf(github)?.data.stargazerCount,
+}))
+
+// Result is typed as { name: ..., stars: ... }
+const result = await getMetadata({ path: '.', template })
+```
+
+##### Provide credentials
+
+```ts
+import { getMetadata } from 'metascope'
+
+const metadata = await getMetadata({
+  credentials: { githubToken: 'ghp_xxxxxxxxxxxx' },
+  path: '.',
+})
+```
+
+Credential resolution follows a precedence chain: explicit options > environment variables > CLI tool fallbacks (e.g. `gh auth token`). This makes metascope work in both CI environments and local development without configuration.
+
+##### Pass template data
+
+```ts
+import { defineTemplate, getMetadata, helpers } from 'metascope'
+
+const template = defineTemplate(({ codemetaJson }, { authorName }) => {
+  const codemeta = helpers.firstOf(codemetaJson)
+  return {
+    isAuthoredByMe: codemeta?.data.author?.some((a) => a.name === authorName),
+    name: codemeta?.data.name,
+  }
+})
+
+const result = await getMetadata({
+  path: '.',
+  template,
+  templateData: { authorName: 'Jane Doe' },
+})
+```
+
+##### Use a built-in template
+
+```ts
+import { getMetadata } from 'metascope'
+
+const result = await getMetadata({ path: '.', template: 'frontmatter' })
+```
+
+## Sources
+
+Metascope extracts data from a wide range of data sources:
+
+### Local Files
+
+| Ecosystem  | Organization                                                                                            | Metascope Key                 | Source Specifications                                                                               |
+| ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------- |
+| Agnostic   |                                                                                                         | `readmeFile`                  | `README.md` (and variants)                                                                          |
+| Agnostic   | [CodeMeta (v1)](https://codemeta.github.io/)                                                            | `codemetaJson`                | [`codemeta.json`](https://raw.githubusercontent.com/codemeta/codemeta/1.0/codemeta.jsonld)          |
+| Agnostic   | [CodeMeta (v2)](https://codemeta.github.io/)                                                            | `codemetaJson`                | [`codemeta.json`](https://raw.githubusercontent.com/codemeta/codemeta/2.0/codemeta.jsonld)          |
+| Agnostic   | [CodeMeta (v3.1)](https://codemeta.github.io/)                                                          | `codemetaJson`                | [`codemeta.json`](https://raw.githubusercontent.com/codemeta/codemeta/3.1/codemeta.jsonld)          |
+| Agnostic   | [CodeMeta (v3)](https://codemeta.github.io/)                                                            | `codemetaJson`                | [`codemeta.json`](https://raw.githubusercontent.com/codemeta/codemeta/3.0/codemeta.jsonld)          |
+| Agnostic   | [Documented below](#about-metadatajson)                                                                 | `metadataFile`                | `metadata.json` (and `.yaml` / `.yml` variants)                                                     |
+| Agnostic   | [Git](https://git-scm.com/)                                                                             | `gitConfig`                   | `.git/config`                                                                                       |
+| Agnostic   | [Public Code](https://publiccode.net/)                                                                  | `publiccodeYaml`              | [`publiccode.yml`](https://yml.publiccode.tools/schema.core.html) (Also matches `.yaml`)            |
+| Agnostic   | [SPDX](https://spdx.org/)                                                                               | `licenseFile`                 | `LICENSE`, `LICENCE`, `COPYING`, `UNLICENSE` (and `.md`/`.txt` variants)                            |
+| Apple      | [Apple Info.plist](https://developer.apple.com/documentation/bundleresources/information-property-list) | `xcodeInfoPlist`              | [`Info.plist`](https://developer.apple.com/documentation/bundleresources/information-property-list) |
+| Apple      | [Xcode Project](https://developer.apple.com/xcode/)                                                     | `xcodeProjectPbxproj`         | [`*.xcodeproj/project.pbxproj`](https://developer.apple.com/documentation/xcode)                    |
+| C++        | [Arduino Library](https://docs.arduino.cc/arduino-cli/library-specification/)                           | `arduinoLibraryProperties`    | [`library.properties`](https://docs.arduino.cc/arduino-cli/library-specification/)                  |
+| C++        | [Cinder CinderBlock](https://libcinder.org/docs/guides/cinder-blocks/index.html)                        | `cinderCinderblockXml`        | [`cinderblock.xml`](https://libcinder.org/docs/guides/cinder-blocks/index.html)                     |
+| C++        | [openFrameworks Addon (Legacy)](https://openframeworks.cc/)                                             | `openframeworksInstallXml`    | [`install.xml`](https://openframeworks.cc/) (Legacy format, replaced by `addon_config.mk`)          |
+| C++        | [openFrameworks Addon](https://openframeworks.cc/)                                                      | `openframeworksAddonConfigMk` | [`addon_config.mk`](https://github.com/openframeworks/ofxAddonTemplate)                             |
+| Go         | [Go Modules](https://go.dev/ref/mod)                                                                    | `goGoMod`                     | [`go.mod`](https://go.dev/doc/modules/gomod-ref)                                                    |
+| Go         | [GoReleaser](https://goreleaser.com/)                                                                   | `goGoreleaserYaml`            | [`.goreleaser.yaml`](https://goreleaser.com/customization/) (Also matches `.yml`)                   |
+| Java       | [Maven](https://search.maven.org/)                                                                      | `javaPomXml`                  | [`pom.xml`](https://maven.apache.org/pom.html)                                                      |
+| Java       | [Processing Library](https://github.com/benfry/processing4/wiki/Library-Guidelines)                     | `processingLibraryProperties` | [`library.properties`](https://github.com/benfry/processing4/wiki/Library-Guidelines)               |
+| Java       | [Processing Sketch](https://processing.org/)                                                            | `processingSketchProperties`  | [`sketch.properties`](https://github.com/benfry/processing4) (Not really specified...)              |
+| JavaScript | [NPM](https://www.npmjs.com/)                                                                           | `nodePackageJson`             | [`package.json`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json)                       |
+| Obsidian   | [Obsidian](https://obsidian.md/)                                                                        | `obsidianPluginManifestJson`  | [`manifest.json`](https://docs.obsidian.md/Reference/Manifest)                                      |
+| Python     | [PyPi (Distutils)](https://pypi.org/)                                                                   | `pythonSetupCfg`              | [`setup.cfg`](https://docs.python.org/3/distutils/apiref.html#distutils.config)                     |
+| Python     | [PyPi (Distutils)](https://pypi.org/)                                                                   | `pythonSetupPy`               | [`setup.py`](https://docs.python.org/3/distutils/setupscript.html)                                  |
+| Python     | [PyPi (pep-0621)](https://pypi.org/)                                                                    | `pythonPyprojectToml`         | [`pyproject.toml`](https://peps.python.org/pep-0621/)                                               |
+| Python     | [PyPi (PKG-INFO)](https://pypi.org/)                                                                    | `pythonPkgInfo`               | [`.egg-info/PKG-INFO`](https://packaging.python.org/en/latest/specifications/)                      |
+| Ruby       | [Ruby Gems](https://rubygems.org/)                                                                      | `rubyGemspec`                 | [`*.gemspec`](https://guides.rubygems.org/specification-reference/)                                 |
+| Rust       | [Crates](https://crates.io/)                                                                            | `rustCargoToml`               | [`Cargo.toml`](https://doc.rust-lang.org/cargo/reference/manifest.html)                             |
+
+### Local Tools
+
+| Ecosystem | Organization                | Metascope Key       | Source Specifications                                                                                                                              |
+| --------- | --------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Agnostic  |                             | `dependencyUpdates` | Dependency freshness (outdated packages, libyears)                                                                                                 |
+| Agnostic  |                             | `fileStats`         | Filesystem metadata (file counts, directory counts, total size)                                                                                    |
+| Agnostic  | [Git](https://git-scm.com/) | `gitStats`          | Git CLI statistics (commits, branches, tags, contributors)                                                                                         |
+| Agnostic  | None                        | `codeStats`         | Lines of code analysis from [tokei](https://github.com/XAMPPRocky/tokei) via [bundled native bindings](https://github.com/kitschpatrol/napi-tokei) |
+
+### Remote Sources
+
+You can skip network calls by passing `--offline` to the CLI.
+
+| Ecosystem  | Organization                                                                            | Metascope Key            | Source Specifications                                                |
+| ---------- | --------------------------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------- |
+| Agnostic   | [GitHub Repository Metadata](https://docs.github.com/rest/repos/repos#get-a-repository) | `github`                 | _GitHub GraphQL metadata_                                            |
+| JavaScript | [NPM Registry](https://www.npmjs.com/)                                                  | `nodeNpmRegistry`        | _NPM registry API_ (download counts, publish dates, latest version)  |
+| Obsidian   | [Obsidian Community Plugins](https://obsidian.md/plugins)                               | `obsidianPluginRegistry` | _Obsidian community plugin stats_ (download counts)                  |
+| Python     | [PyPI Registry](https://pypi.org/)                                                      | `pythonPypiRegistry`     | _PyPI registry API_ (download counts, publish dates, latest version) |
+
+### About metadata.json
+
+Metascope supports a minimalist `metadata.json` (or `.yaml`) file is supported, which can capture the minimal metadata required to populate a GitHub project's repository page's description, homepage, and topics.
+
+This is a non-standard format that exists primarily for use in combination with [github-action-repo-sync](https://github.com/kitschpatrol/github-action-repo-sync).
+
+| Key           | Key Aliases                  | CodeMeta Property | Notes                                                                         |
+| ------------- | ---------------------------- | ----------------- | ----------------------------------------------------------------------------- |
+| `description` | _None_                       | `description`     | String description of project                                                 |
+| `homepage`    | `url` `repository` `website` | `url`             | For repository values, git+ prefix and .git suffix are automatically stripped |
+| `keywords`    | `tags` `topics`              | `keywords`        | Array of strings, or a single comma-delimited string                          |
+
+If multiple key aliases are present in the object, priority for populating the associated `codemeta.json` goes to the key, then falls through to key aliases in the order shown above. (E.g. homepage takes priority over url.)
+
+_If you have more metadata to define but your project lacks a canonical package specification format, then creating a `codemeta.json` file is recommended over the non-standard `metadata.json`._
+
+## Templates
+
+Metascope provides a basic templating / output transformation functionality to compose its output into more compact and focused representations.
+
+### Built-in templates
+
+Three built-in templates are available by name. Pass the name as the `template` option on the CLI or in the API.
+
+#### `codemeta`
+
+The [CodeMeta](https://codemeta.github.io/) template provides a standard way to describe software using [JSON-LD](https://json-ld.org/) and [schema.org](https://schema.org/) terms. Most software projects already have rich metadata in manifests and other files (e.g. `package.json`, `Cargo.toml`, `pyproject.toml`, `LICENSE`, etc.), but the name and structure of semantically equivalent metadata is often inconsistent across ecosystems.
+
+It leverages the [crosswalk](https://codemeta.github.io/crosswalk/) data generously compiled by CodeMeta contributors to assist in automating the mapping of various metadata formats to the CodeMeta standard. Where crosswalk data is unavailable or incomplete, heuristics are used instead.
+
+This tool always outputs [CodeMeta v3.1](https://w3id.org/codemeta/3.1) files. When ingesting `codemeta.json` files defined in the older [CodeMeta 1](https://doi.org/10.5063/SCHEMA/CODEMETA-1.0) and [CodeMeta v2](https://doi.org/10.5063/SCHEMA/CODEMETA-2.0) contexts, all simple key re-mappings as defined in the crosswalk table are applied. However, some more nuanced conditional transformations (like the reassignment of copyright holding agents in v1) are not implemented.
+
+More mature Python-based tools like [codemetapy](https://github.com/proycon/codemetapy) and [codemeta-harvester](https://github.com/proycon/codemeta-harvester) perform a similar task, and either of these are recommended if you need `codemeta.json` output and aren't limited to a Node.js runtime.
+
+Note that Metascope and its its author is not affiliated with the CodeMeta project / governing bodies.
+
+```sh
+metascope --template codemeta
+```
+
+_See an [output sample](./docs/metascope-template-codemeta.json) from the `codemeta` template run against this repository._
+
+#### `frontmatter`
+
+A compact, non-nested, polyglot overview of the project. Designed for Obsidian frontmatter — flat keys with natural language names, blending all available sources into a single trackable snapshot. Uses `null` for missing values to ensure stable keys.
+
+```sh
+metascope --template frontmatter
+```
+
+_See an [output sample](./docs/metascope-template-frontmatter.json) from the `frontmatter` template run against this repository._
+
+#### `project`
+
+I needed this one for a legacy internal dashboard application. Includes ownership checks via `authorName` and `githubAccount` template data.
+
+```sh
+metascope --template project --author-name "Jane Doe" --github-account janedoe
+```
+
+_See an [output sample](./docs/metascope-template-project.json) from the `project` template run against this repository._
+
+### Defining a custom template
+
+Templates are pure functions that receive the full `MetadataContext` and an optional `TemplateData` object, and return whatever shape you like. They are applied _after_ all sources have been extracted, so all available data is accessible.
+
+Yes, you can just pipe output to [jq](https://jqlang.org/) and filter / transform as you please, but for complex templates with a lot of logic, TypeScript can be nicer to work with.
+
+Use `defineTemplate()` for type inference and autocomplete.
+
+Many helper functions for working with template data are also under the `helpers` namespace:
+
+```ts
+// In e.g. "metascope-template.ts":
+import { defineTemplate, helpers } from 'metascope'
+
+export default defineTemplate(({ codemetaJson, codeStats, github, gitStats }) => {
+  const codemeta = helpers.firstOf(codemetaJson)
+  const git = helpers.firstOf(gitStats)
+  const gh = helpers.firstOf(github)
+  const loc = helpers.firstOf(codeStats)
+  return {
+    commits: git?.data.commitCount,
+    forks: gh?.data.forkCount,
+    linesOfCode: loc?.data.total?.code,
+    name: codemeta?.data.name,
+    stars: gh?.data.stargazerCount,
+    version: codemeta?.data.version,
+  }
+})
+```
+
+### Passing template data
+
+The second argument to a template function is a `TemplateData` object with optional `authorName` and `githubAccount` fields. This lets templates parameterize ownership checks instead of hardcoding author names:
+
+```ts
+import { defineTemplate, helpers } from 'metascope'
+
+export default defineTemplate(({ codemetaJson }, { authorName, githubAccount }) => {
+  const codemeta = helpers.firstOf(codemetaJson)
+  const authors = codemeta?.data.author?.map((a) => a.name) ?? []
+  const repo = codemeta?.data.codeRepository?.toLowerCase() ?? ''
+  return {
+    isMyProject: authors.includes(authorName),
+    isOnMyGitHub: typeof githubAccount === 'string' && repo.includes(`/${githubAccount}/`),
+    name: codemeta?.data.name,
+  }
+})
+```
+
+Values for the built-in templates are provided via the `--author-name` and `--github-account` CLI flags, or via the `templateData` option in the API. Templates that don't need this data can simply omit the second argument.
+
+### Using a custom template via the CLI
+
+```sh
+metascope --template ./metascope-template.ts
+```
+
+Template files are loaded via [jiti](https://github.com/unjs/jiti), so TypeScript works out of the box without a build step.
+
+## Background
+
+Metascope was built to support automated generation of project dashboards, badges, and documentation where a single source of truth for project metadata is useful. Rather than querying each API individually, metascope handles the discovery, authentication, and aggregation in one pass for a wide variety of project types.
+
+### Related projects
+
+- [codemeta](https://codemeta.github.io/)\
+  Standard shared metadata vocabulary (JSON-LD)
+- [codemetapy](https://github.com/proycon/codemetapy)\
+  Translate software metadata into the CodeMeta vocabulary (Python)
+- [codemeta-harvester](https://github.com/proycon/codemeta-harvester)\
+  Aggregate software metadata into the CodeMeta vocabulary from source repositories and service endpoints (Python)
+- [bibliothecary](https://github.com/librariesio/bibliothecary)\
+  Manifest discovery and parsing for [libraries.io](https://libraries.io/) (Ruby)
+- [diggity](https://github.com/carbonetes/diggity)\
+  Generates SBOMs for container images, filesystems, archives, and more (Go)
+- [SOMEF](https://github.com/KnowledgeCaptureAndDiscovery/somef/)\
+  Software Metadata Extraction Framework (Python)
+- [Upstream Ontologist](https://github.com/jelmer/upstream-ontologist)\
+  A common interface for finding metadata about upstream software projects (Rust)
+- [GrimoireLab](https://chaoss.github.io/grimoirelab/)\
+  Platform for software development analytics and insights (Python)
+- [OSS Review Toolkit](https://oss-review-toolkit.org/ort/)\
+  A suite of CLI tools to automate software compliance checks (Kotlin)
+- [Git Truck](https://github.com/git-truck/git-truck)\
+  Repository visualization. (TypeScript)
+
+## Slop factor
+
+_Medium._
+
+The architecture and non-boilerplate parts of the documentation were human-driven, but sizable chunks of the implementation were mostly Claude Code's doing and have been subject to only moderate post-facto human scrutiny.
+
+## Maintainers
+
+[@kitschpatrol](https://github.com/kitschpatrol)
+
+## Acknowledgments
+
+Thank you to the [CodeMeta Project Management Committee and contributors](https://codemeta.github.io/governance/people/) for their development and stewardship of the standard.
+
+Jacob Peddicord's [askalono](https://github.com/jpeddicord/askalono) project inspired the [Dice-Sørensen](https://en.wikipedia.org/wiki/Dice-S%C3%B8rensen_coefficient) scoring strategy used for classifying arbitrary license text.
+
+<!-- contributing -->
+
+## Contributing
+
+[Issues](https://github.com/kitschpatrol/metascope/issues) and pull requests are welcome.
+
+<!-- /contributing -->
+
+<!-- license -->
+
+## License
+
+[MIT](license.txt) © Eric Mika
+
+<!-- /license -->