mizcausevic-dev/wellknown-index-aggregator

Purpose and principal workflow

This Node.js library and CLI turns Kinetic Gain disclosure JSON files into a /.well-known/index.json index, while reporting integrity issues such as missing IDs, duplicate IDs, and broken references. The workflow starts when a CLI user or automation invokes wk-index with a disclosure directory; alternatively, a library consumer calls the exported API with loaded documents. The tool scans local files, identifies and indexes documents, then prints or writes the index or a full report. It does not use a network, LLM, or external schema validator.

Components

Entry points and input

• CLI — src/cli.ts: Parses options, loads the requested directory, runs index construction, emits findings, and writes output to stdout or a file; --strict returns an error status when integrity errors exist.

• Public library API — src/index.ts: Re-exports index construction, rendering, document loading, detection helpers, and public types for library consumers.

• CLI user or automation — null repository path: Invokes the CLI with arguments, including the input directory and optional output/report settings.

• Disclosure directory — null repository path: Supplies local JSON disclosure files to the loader.

• Index consumer or output destination — null repository path: Receives the generated index through stdout or the CLI-selected output file.

• Directory loader — src/load.ts: Recursively reads .json files, requires each top-level value to be an object, and returns filename/body pairs sorted by filename.

Document interpretation and index construction

• Disclosure detection and routing — src/detect.ts: Identifies kinds from version keys and extracts IDs, versions, references, and canonical well-known paths.

• Index builder and integrity checks — src/build.ts: Builds entries; reports unknown kinds, missing IDs or versions, duplicate IDs, and references to IDs not present in the indexed set; sorts entries and calculates counts and ok.

• Index renderer — src/build.ts: Converts report entries to formatted JSON with a generated timestamp; the CLI uses this for index-only output, while report mode serializes the full report directly.

• Public data contracts — src/types.ts: Defines input documents, kinds, entries, findings, reports, and build options shared by the library and CLI.

Relationships

• CLI user or automation -> CLI: Invokes wk-index with arguments; the package declares the executable entry point and the CLI parses its arguments.

• Disclosure directory -> Directory loader: Supplies the directory scanned recursively for JSON files.

• CLI -> Directory loader: Calls loadDir with the requested directory.

• Directory loader -> Disclosure detection and routing: Passes parsed document bodies and source filenames to the builder, which uses detection helpers.

• CLI -> Index builder and integrity checks: Calls buildIndex with loaded documents and optional base URL.

• Index builder and integrity checks -> Disclosure detection and routing: Calls helpers to determine kind, ID, version, references, and output path.

• CLI -> Index renderer: Calls toIndexJson when producing index-only output; report mode instead serializes the report in the CLI.

• CLI -> Index consumer or output destination: Writes output to stdout by default or to the --out file; the CLI also prints findings to stderr.

• Public library API -> Index builder and integrity checks: Re-exports buildIndex for library consumers.

• Public library API -> Directory loader: Re-exports loadDir for library consumers.

• Public library API -> Index renderer: Re-exports toIndexJson for library consumers.

Coverage limits

Source excerpts establish the CLI, library exports, file loading, detection, index construction, and output behavior. The downstream publication or serving of the generated index is not shown; the README describes composing with a separate disclosure-rendering operator, but that operator is external to this repository.