docmeta 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Shared types for docmeta.
+ *
+ * The pipeline is: load files -> extract metadata (format-specific) ->
+ * resolve a schema set per file -> validate against each schema -> report.
+ * Everything after extraction operates only on `ExtractedMetadata`, so new
+ * input formats never touch validation, resolution, or reporting.
+ */
+/** Result of pulling a metadata block out of a single document. */
+interface ExtractedMetadata {
+    /** Parsed metadata key/values. `{}` when a block is present but empty. */
+    data: Record<string, unknown>;
+    /** Whether a metadata block was found at all. */
+    present: boolean;
+    /** Name of the extractor/format that produced this (e.g. "markdown"). */
+    format: string;
+    /**
+     * Map a JSON Pointer (Ajv `instancePath`, e.g. "/tags/0") or a bare top-level
+     * key to its 1-based source line, for precise annotations. Returns undefined
+     * when no position is known.
+     */
+    lineFor(pointer: string): number | undefined;
+}
+/** A pluggable metadata extractor for one document format. */
+interface MetadataExtractor {
+    /** Stable name, also used as `ExtractedMetadata.format`. */
+    name: string;
+    /** Lowercase file extensions this extractor handles, incl. dot (e.g. ".md"). */
+    extensions: string[];
+    /** Whether this extractor is wired up (false for roadmap stubs). */
+    implemented: boolean;
+    /** Extract metadata from raw file content. */
+    extract(content: string, filePath: string): ExtractedMetadata;
+}
+/** A single schema violation for one file, attributed to one schema. */
+interface FieldError {
+    /** Schema id/ref that produced this error (e.g. "google:okf:0.1"). */
+    schema: string;
+    /** Ajv instancePath, e.g. "/tags/0" or "" for the root. */
+    instancePath: string;
+    /** Human-readable message. */
+    message: string;
+    /** 1-based source line, when known. */
+    line?: number;
+    /** 1-based column, when known. */
+    col?: number;
+}
+/** Validation outcome for a single file. */
+interface ValidationResult {
+    /** Absolute or cwd-relative path of the file. */
+    file: string;
+    /** Extractor/format used. */
+    format: string;
+    /** Whether validation passed against every schema in the set. */
+    ok: boolean;
+    /** Schema ids/refs the file was validated against. */
+    schemas: string[];
+    /** All violations, across every schema in the set. */
+    errors: FieldError[];
+}
+/** Aggregate run summary. */
+interface RunSummary {
+    files: number;
+    passed: number;
+    failed: number;
+    errors: number;
+}
+/** An operational/usage failure that should map to exit code 2. */
+declare class DocmetaError extends Error {
+    constructor(message: string);
+}
+
+interface ValidateOptions {
+    inputs: string[];
+    cliSchemas?: string[];
+    exts?: string[];
+    exclude?: string[];
+    /** `--as` format override (extractor name). */
+    as?: string;
+    configPath?: string;
+    cwd?: string;
+    /** Content for the `-` (stdin) input, injected by the CLI/tests. */
+    stdinContent?: string;
+}
+interface ValidateRun {
+    results: ValidationResult[];
+    summary: RunSummary;
+}
+declare function runValidate(opts: ValidateOptions): Promise<ValidateRun>;
+
+interface GetOptions {
+    fields: string[];
+    inputs: string[];
+    as?: string;
+    exclude?: string[];
+    exts?: string[];
+    configPath?: string;
+    cwd?: string;
+    /** Content for the `-` (stdin) input, injected by the CLI/tests. */
+    stdinContent?: string;
+}
+interface GetFileResult {
+    file: string;
+    present: boolean;
+    values: Record<string, unknown>;
+}
+declare function runGet(opts: GetOptions): Promise<GetFileResult[]>;
+
+interface BuiltinInfo {
+    id: string;
+    title: string;
+    description: string;
+}
+declare function listBuiltins(): BuiltinInfo[];
+type RefKind = "builtin" | "file" | "url";
+declare function classifyRef(ref: string): {
+    kind: RefKind;
+    ref: string;
+};
+interface LoadSchemaOptions {
+    /** Abort a remote fetch after this many ms (default 10_000). */
+    timeoutMs?: number;
+}
+/** Load and return the JSON Schema object for a reference. */
+declare function loadSchema(ref: string, options?: LoadSchemaOptions): Promise<Record<string, unknown>>;
+
+/**
+ * `schemas` command core. Reports built-in schemas and supported input formats.
+ */
+
+interface SchemasInfo {
+    builtins: BuiltinInfo[];
+    formats: {
+        name: string;
+        extensions: string[];
+        implemented: boolean;
+    }[];
+}
+declare function getSchemasInfo(): SchemasInfo;
+
+declare class Validator {
+    private ajvByDialect;
+    private cache;
+    private ajvFor;
+    private compile;
+    /**
+     * Validate `data` against every schema in `refs`. Returns all violations,
+     * each tagged with the schema that produced it and a source line via
+     * `lineFor`.
+     */
+    validate(data: Record<string, unknown>, refs: string[], lineFor: (pointer: string) => number | undefined): Promise<FieldError[]>;
+}
+
+interface SchemaOverride {
+    files: string;
+    schemas: string[];
+}
+interface DocmetaConfig {
+    paths?: string[];
+    exclude?: string[];
+    schemas?: string[];
+    overrides?: SchemaOverride[];
+}
+/** Parse and validate config YAML text. */
+declare function parseConfig(text: string, source: string): DocmetaConfig;
+/**
+ * Load config from an explicit path (error if missing) or by discovery in cwd.
+ * Returns null when no config is found via discovery.
+ */
+declare function loadConfig(explicitPath?: string, cwd?: string): Promise<{
+    config: DocmetaConfig;
+    path: string;
+} | null>;
+
+declare const DEFAULT_SCHEMA = "google:okf:0.1";
+interface ResolveParams {
+    /** File path (relative is fine) used for override glob matching. */
+    filePath: string;
+    /** `$schema` value pulled from the file's metadata. */
+    fileSchema?: unknown;
+    /** Repeatable `--schema` values; non-empty means override. */
+    cliSchemas?: string[];
+    /** Loaded config, if any. */
+    config?: DocmetaConfig | null;
+}
+declare function resolveSchemaSet(params: ResolveParams): string[];
+
+/**
+ * Reporters render validation results to a string. The command layer writes
+ * the result to stdout; diagnostics go to stderr separately.
+ */
+
+type ReportFormat = "pretty" | "json" | "github";
+interface ReportOptions {
+    color?: boolean;
+    /** In pretty output, omit passing files. */
+    quiet?: boolean;
+}
+declare function render(format: ReportFormat, results: ValidationResult[], summary: RunSummary, opts?: ReportOptions): string;
+
+export { DEFAULT_SCHEMA, type DocmetaConfig, DocmetaError, type ExtractedMetadata, type FieldError, type GetFileResult, type GetOptions, type MetadataExtractor, type ReportFormat, type RunSummary, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, classifyRef, getSchemasInfo, listBuiltins, loadConfig, loadSchema, parseConfig, render, resolveSchemaSet, runGet, runValidate };

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_SCHEMA,
+  DocmetaError,
+  Validator,
+  classifyRef,
+  getSchemasInfo,
+  listBuiltins,
+  loadConfig,
+  loadSchema,
+  parseConfig,
+  render,
+  resolveSchemaSet,
+  runGet,
+  runValidate
+} from "./chunk-NTXC32C4.js";
+export {
+  DEFAULT_SCHEMA,
+  DocmetaError,
+  Validator,
+  classifyRef,
+  getSchemasInfo,
+  listBuiltins,
+  loadConfig,
+  loadSchema,
+  parseConfig,
+  render,
+  resolveSchemaSet,
+  runGet,
+  runValidate
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "docmeta",
+  "version": "0.1.0",
+  "description": "Validate the presence and format of document metadata (Markdown frontmatter and more) against JSON Schema. CI-friendly.",
+  "type": "module",
+  "bin": {
+    "docmeta": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hawkeyexl/docmeta.git"
+  },
+  "homepage": "https://hawkeyexl.github.io/docmeta/",
+  "bugs": {
+    "url": "https://github.com/hawkeyexl/docmeta/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "docs:check-cli": "node scripts/check-cli-reference.mjs",
+    "commitlint": "commitlint --edit",
+    "semantic-release": "semantic-release",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "frontmatter",
+    "metadata",
+    "json-schema",
+    "markdown",
+    "validation",
+    "cli",
+    "ci",
+    "okf"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@xmldom/xmldom": "^0.9.10",
+    "ajv": "^8.17.1",
+    "ajv-draft-04": "^1.0.0",
+    "ajv-formats": "^3.0.1",
+    "commander": "^15.0.0",
+    "fast-glob": "^3.3.2",
+    "parse5": "^8.0.1",
+    "picocolors": "^1.1.1",
+    "picomatch": "^4.0.4",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.8",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/node": "^26.0.1",
+    "@types/picomatch": "^4.0.3",
+    "husky": "^9.1.7",
+    "semantic-release": "^25.0.3",
+    "tsup": "^8.3.5",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}