@lepid-labs/weft-core 0.1.0

package/dist/validate/run.js

@@ -0,0 +1,90 @@
+import { NO_HISTORY, graphHistory } from "./history.js";
+import { VALIDATOR_ERROR_RULE, defaultRegistry } from "./registry.js";
+/** Resolve a rule's severity: the user's config wins over the rule's own default. */
+function severityFor(rule, config) {
+    return config.rules?.[rule.id] ?? rule.defaultSeverity;
+}
+/**
+ * Whether running this registry under this config will read git history.
+ *
+ * Exported so a caller that builds the graph itself — the service — can pay
+ * for one full history walk up front and hand the result to both the indexer
+ * and {@link validateManifest}, instead of each walking on its own.
+ */
+export function registryWantsHistory(registry, config) {
+    return registry.validators.some((validator) => validator.needsHistory && validator.rules.some((rule) => severityFor(rule, config) !== "off"));
+}
+/**
+ * Run every registered check over a built manifest.
+ *
+ * Validation is a separate stage from extraction on purpose: it reads the
+ * finished graph and never mutates it, so a check can be added without touching
+ * the indexer.
+ */
+export async function validateManifest(manifest, config, registry = defaultRegistry(), precomputedHistory) {
+    const nodes = new Map(manifest.nodes.map((node) => [node.id, node]));
+    const enabled = new Map();
+    const rulesRun = [];
+    const rulesSkipped = [];
+    for (const rule of registry.rules) {
+        const severity = severityFor(rule, config);
+        if (severity === "off") {
+            rulesSkipped.push(rule.id);
+            continue;
+        }
+        enabled.set(rule.id, severity);
+        rulesRun.push(rule.id);
+    }
+    const unknownRules = Object.keys(config.rules ?? {}).filter((id) => !registry.rule(id));
+    // Gathered once for every check that wants it, and skipped outright when
+    // none is enabled — reading git history is the only IO validation does.
+    // A caller who already walked history passes it in instead.
+    const wantsHistory = registryWantsHistory(registry, config);
+    const history = wantsHistory ? (precomputedHistory ?? (await graphHistory(config))) : NO_HISTORY;
+    const context = {
+        manifest,
+        config,
+        nodes,
+        history,
+        isEnabled: (ruleId) => enabled.has(ruleId),
+    };
+    const diagnostics = [];
+    // A rule turned off still reaches here if a validator ran for its other
+    // rules, so drop findings whose rule is not enabled.
+    const record = (finding) => {
+        const severity = enabled.get(finding.rule);
+        if (severity)
+            diagnostics.push({ ...finding, severity });
+    };
+    for (const validator of registry.validators) {
+        // Skip a validator whose every rule is off rather than running work it
+        // would only throw away.
+        if (!validator.rules.some((rule) => enabled.has(rule.id)))
+            continue;
+        let findings;
+        try {
+            findings = await validator.run(context);
+        }
+        catch (err) {
+            // One bad validator must not take down the run — report it as a
+            // diagnostic and let the remaining checks finish.
+            record({
+                rule: VALIDATOR_ERROR_RULE.id,
+                message: `Validator for ${validator.rules.map((rule) => rule.id).join(", ")} threw: ${err.message}`,
+                target: { kind: "graph" },
+            });
+            continue;
+        }
+        for (const finding of findings) {
+            if (!validator.rules.some((rule) => rule.id === finding.rule)) {
+                throw new Error(`weft validate: a validator reported rule "${finding.rule}", which it does not declare`);
+            }
+            record(finding);
+        }
+    }
+    const counts = { error: 0, warn: 0, info: 0 };
+    for (const diagnostic of diagnostics)
+        counts[diagnostic.severity]++;
+    return { diagnostics, counts, rulesRun, rulesSkipped, unknownRules };
+}
+//# sourceMappingURL=run.js.map

package/dist/validate/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/validate/run.ts"],"names":[],"mappings":"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"}

package/dist/validate/types.d.ts

@@ -0,0 +1,101 @@
+import type { Manifest, Severity, WeftConfig, WeftEdge, WeftNode } from "../types.js";
+/** What a diagnostic concerns: a document (optionally one anchor in it), an edge, or the graph itself. */
+export type DiagnosticTarget = {
+    kind: "node";
+    node: string;
+    anchor?: string;
+} | {
+    kind: "edge";
+    edge: WeftEdge;
+} | {
+    kind: "graph";
+};
+/**
+ * A validator's output. Deliberately carries no severity — that is resolved by
+ * the runner from the rule's default and the user's config, so the same finding
+ * can be an error in one project and a warning in another. A rule that needs two
+ * severities (a hard failure and a softer "known pending" variant) declares two
+ * rule ids, which also makes each independently configurable.
+ */
+export interface Finding {
+    /** Id of the rule reporting this, which must be one the validator declares. */
+    rule: string;
+    /** Human-readable description of what is wrong. */
+    message: string;
+    target: DiagnosticTarget;
+    /** Optional suggestion for how to fix it. */
+    hint?: string;
+    /** Optional rule-specific payload, carried through to JSON output. */
+    data?: Record<string, unknown>;
+}
+/** A finding with its severity resolved. This is what consumers report on. */
+export interface Diagnostic extends Finding {
+    severity: Severity;
+}
+/** A single check a validator can report. Declared up front so config and `--list-rules` can see it without running anything. */
+export interface Rule {
+    /** Stable id used in config and in output, e.g. "edge-target-missing". */
+    id: string;
+    /** One-line description of what the rule checks. */
+    description: string;
+    /** Severity used when config does not override it. */
+    defaultSeverity: Severity;
+}
+/**
+ * What git knows about the indexed files, keyed by node id rather than by path
+ * so a validator never repeats the project-namespacing the runner already did.
+ *
+ * Empty when no rule needed it, when the project is not a git repository, or
+ * when git could not answer. A check reading this must treat empty as "nothing
+ * to say" rather than as evidence.
+ */
+export interface GraphHistory {
+    /**
+     * Every blob each node has ever held, following renames. Two nodes whose
+     * sets intersect held identical content at some point.
+     */
+    blobs: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Node id a path moved to, for ids that are no longer in the graph. */
+    renames: ReadonlyMap<string, string>;
+}
+/** Everything a validator gets to work with. Read-only — validation never mutates the graph. */
+export interface ValidationContext {
+    manifest: Manifest;
+    config: WeftConfig;
+    /** Nodes by id, prebuilt so every validator does not rescan the node list. */
+    nodes: ReadonlyMap<string, WeftNode>;
+    /**
+     * What git knows about these files. Gathered once by the runner, and only
+     * when a rule that declared a need for it is enabled — a project running
+     * without the history-based checks pays for no subprocess.
+     */
+    history: GraphHistory;
+    /** False when the rule is configured "off". Lets an expensive validator skip work it would only throw away. */
+    isEnabled(ruleId: string): boolean;
+}
+/** A registered check. `rules` declares every rule id `run` may emit. */
+export interface Validator {
+    rules: Rule[];
+    /**
+     * True when the check reads `context.history`. Declared rather than inferred
+     * so the runner can skip the git walk entirely when nothing enabled wants it.
+     */
+    needsHistory?: boolean;
+    run(context: ValidationContext): Finding[] | Promise<Finding[]>;
+}
+export interface ValidationResult {
+    diagnostics: Diagnostic[];
+    /** How many diagnostics of each severity. `counts.error` drives the `weft check` exit code. */
+    counts: Record<Severity, number>;
+    /** Rule ids that ran. */
+    rulesRun: string[];
+    /** Rule ids skipped because config set them to "off". */
+    rulesSkipped: string[];
+    /**
+     * Rule ids named in config that no validator declares. Reported rather than
+     * rejected: a config written against a newer Weft, or against a check that is
+     * installed elsewhere, should not stop the run.
+     */
+    unknownRules: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/validate/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/validate/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtF,0GAA0G;AAC1G,MAAM,MAAM,gBAAgB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACvB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,gBAAgB,CAAC;IACzB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,8EAA8E;AAC9E,MAAM,WAAW,UAAW,SAAQ,OAAO;IAC1C,QAAQ,EAAE,QAAQ,CAAC;CACnB;AAED,iIAAiI;AACjI,MAAM,WAAW,IAAI;IACpB,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,eAAe,EAAE,QAAQ,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,wEAAwE;IACxE,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,gGAAgG;AAChG,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,8EAA8E;IAC9E,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACrC;;;;OAIG;IACH,OAAO,EAAE,YAAY,CAAC;IACtB,+GAA+G;IAC/G,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,GAAG,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,gBAAgB;IAChC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjC,yBAAyB;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;;;;OAIG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CACvB"}

package/dist/validate/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/validate/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/validate/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@lepid-labs/weft-core",
+  "version": "0.1.0",
+  "description": "Weft's document graph: indexing, links, validation and search over a docs tree",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lepid-Labs/weft.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/Lepid-Labs/weft#readme",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    }
+  },
+  "dependencies": {
+    "chokidar": "^4.0.0",
+    "github-slugger": "^2.0.0",
+    "glob": "^11.0.0",
+    "mdast-util-to-string": "^4.0.0",
+    "minisearch": "^7.0.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.0",
+    "unist-util-visit": "^5.0.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}