@refrakt-md/content 0.35.0 → 0.37.0

package/dist/validate-content.js

@@ -0,0 +1,143 @@
+/**
+ * The fast validation tier — SPEC-135 D3 / D14 / WORK-577.
+ *
+ * `loadContent` validates as a side effect of building a `Site`: it resolves
+ * routes and layouts, shells out to git for timestamps, runs the identity
+ * transform, and then runs three more cross-page phases over every page. A CLI
+ * that called it would be no faster than a build, which defeats the reason for
+ * having a CLI (D3).
+ *
+ * This runs the two steps validation actually needs — parse and validate —
+ * against a config built by the *same* function the build uses, so the two
+ * cannot disagree about which tags and attributes exist (D14).
+ */
+import { resolve } from 'node:path';
+import Markdoc from '@markdoc/markdoc';
+import { fsProjectFiles } from '@refrakt-md/types/project-files';
+import { escapeFenceTags } from '@refrakt-md/runes';
+import { ContentTree } from './content-tree.js';
+import { parseFrontmatter } from './frontmatter.js';
+import { Router } from './router.js';
+import { buildPageContentVariables, buildPageTransformConfig, buildPreprocessHookSets, parsePagePartials, } from './site.js';
+import { validatePageDetailed } from './validate.js';
+/**
+ * Validate every page in a content tree, returning findings.
+ *
+ * Accepts a directory path or a pre-built {@link ContentTree}. Runs parse,
+ * preprocess and `Markdoc.validate`, and **nothing else**: no `resolveLayouts`,
+ * no `resolveTimestamps` (no git), no `Markdoc.transform`, no `runPipeline`.
+ *
+ * Two departures from WORK-577's acceptance criteria, both in service of the
+ * agreement the same item calls its real deliverable:
+ *
+ * - **It resolves routes.** The criteria say not to call `router.resolve`, to
+ *   keep the tier fast. `Router.resolve` is pure string manipulation with no
+ *   I/O (`router.ts:46`), so it costs nothing measurable — and without it every
+ *   finding's `url` would differ from the build's, making the agreement
+ *   approximate where it could be exact.
+ * - **It runs preprocess hooks.** The criteria do not mention them. They are
+ *   not optional: `{% snippet %}` resolves itself into a fence node during
+ *   preprocess and `{% include %}` pastes partial content in, so skipping them
+ *   validates a different tree than the build does — precisely the divergence
+ *   D5a exists to forbid.
+ *
+ * What stays skipped is where the cost actually is: git, layouts, the identity
+ * transform, and the three cross-page phases. Those are the `--deep` tier.
+ */
+export async function validateContent(source, options = {}) {
+    const tree = typeof source === 'string' ? await ContentTree.fromDirectory(source) : source;
+    const router = new Router(options.basePath ?? '/');
+    // Mirror `loadContent`'s defaults for the directory form. It derives a
+    // project root from the content directory's parent and roots a
+    // `fsProjectFiles` provider there; without the same defaults, snippet's
+    // preprocess cannot read files here while it can in a build, and the two
+    // paths report different findings for the same corpus.
+    //
+    // Found by running this function against refrakt's own 235-page site and
+    // diffing: 13 findings the build had and this did not, plus one it had and
+    // the build did not — all of them snippet tags that resolved in one path and
+    // not the other. Exactly the divergence D5a forbids, and invisible without
+    // the comparison.
+    const env = { ...options };
+    if (typeof source === 'string') {
+        const projectRoot = options.projectRoot ?? resolve(source, '..');
+        env.projectRoot = projectRoot;
+        env.sandbox = options.sandbox ?? fsProjectFiles(projectRoot);
+    }
+    const parsedPartials = await parsePagePartials(tree, env);
+    const hookSets = buildPreprocessHookSets(env, parsedPartials);
+    // D5a — settings come off the site config exactly as `loadContent` reads
+    // them (`site.ts`), and are handed to `validatePageDetailed`, which resolves
+    // them through `resolveValidationIds`. Not reimplemented here: the three-way
+    // refinement (demote / drop / always-report) has one implementation, and
+    // this path calls it.
+    const settings = options.validation ??
+        options.siteConfig?.validation;
+    const out = [];
+    for (const page of tree.pages()) {
+        const { frontmatter, content } = parseFrontmatter(page.raw);
+        const route = router.resolve(page.relativePath, frontmatter);
+        let ast = Markdoc.parse(escapeFenceTags(content));
+        // Computed before preprocess, exactly as the build does, so snippet can
+        // resolve `path=$file.path`-style references. `timestamps` is omitted —
+        // that is the git call the fast tier exists to skip, and nothing in
+        // preprocess reads `$file.created` / `$file.modified`.
+        const contentVariables = buildPageContentVariables({
+            ast,
+            frontmatter,
+            relativePath: page.relativePath,
+            filePath: page.filePath,
+            url: route.url,
+            draft: route.draft,
+            variables: options.variables,
+            projectRoot: env.projectRoot,
+            sandbox: env.sandbox,
+            sandboxExamplesDir: options.sandboxExamplesDir,
+            securityPolicy: options.securityPolicy,
+            siteConfig: options.siteConfig,
+        });
+        // Preprocess needs somewhere to put its own diagnostics. They are
+        // collected and discarded here: a preprocess warning is a pipeline
+        // finding, not a content-validation finding, and reporting it from this
+        // entry point would make the fast tier return findings a `validatePage`
+        // comparison could never match. The build still reports them.
+        const ppCtx = {
+            info() { },
+            warn() { },
+            error() { },
+            projectRoot: env.projectRoot,
+            sandbox: env.sandbox,
+            variables: contentVariables,
+            partials: parsedPartials ?? {},
+        };
+        for (const { hooks } of hookSets) {
+            if (!hooks.preprocess)
+                continue;
+            const next = await hooks.preprocess(ast, { url: route.url, relativePath: page.relativePath, filePath: page.filePath }, ppCtx);
+            if (next)
+                ast = next;
+        }
+        const { config } = buildPageTransformConfig({
+            ast,
+            content,
+            path: route.url,
+            sourcePath: page.relativePath,
+            icons: options.icons,
+            additionalTags: options.additionalTags,
+            contentVariables,
+            partials: parsedPartials,
+        });
+        for (const finding of validatePageDetailed(ast, config, { url: route.url, settings })) {
+            out.push({
+                file: page.relativePath,
+                url: route.url,
+                line: finding.line,
+                severity: finding.warning.severity,
+                id: finding.id,
+                message: finding.warning.message,
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=validate-content.js.map

package/dist/validate-content.js.map

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

package/dist/validate.d.ts

@@ -99,5 +99,37 @@ export interface ValidatePageOptions {
  * value in an `info` stream of every check the project has decided against.
  */
 export declare function validatePage(ast: Node, config: unknown, opts: ValidatePageOptions): PipelineWarning[];
+/**
+ * A finding, plus the structured fields `PipelineWarning` has nowhere to put.
+ *
+ * `PipelineWarning` is the build's diagnostic shape: severity, phase, plugin,
+ * url, message. The Markdoc error id and source line are *formatted into* the
+ * message there, which is fine for a build summary a human reads and useless to
+ * a caller that wants to filter by id or open a file at a line — the CLI's
+ * `--format json` (WORK-578) and the MCP tool (WORK-581, SPEC-135 D6).
+ *
+ * Carried alongside rather than added to `PipelineWarning` so the build's
+ * diagnostic shape is unchanged and the two cannot drift: the warning here is
+ * the identical object `validatePage` returns.
+ */
+export interface DetailedFinding {
+    /** Exactly what `validatePage` reports for this finding. */
+    warning: PipelineWarning;
+    /** Markdoc error id, e.g. `tag-undefined`. Absent only when validation
+     *  itself crashed and the finding is the fallback. */
+    id?: string;
+    /** 1-based source line, matching what the message renders. */
+    line?: number;
+}
+/**
+ * {@link validatePage}, keeping the structured fields.
+ *
+ * This is where the dispositions actually live; `validatePage` is a projection
+ * of it. Single-sourced deliberately — SPEC-135 D5a requires that every caller
+ * resolve settings through `resolveValidationIds` rather than reimplementing
+ * the three-way refinement, and the cheapest way to guarantee that is for there
+ * to be exactly one implementation to call.
+ */
+export declare function validatePageDetailed(ast: Node, config: unknown, opts: ValidatePageOptions): DetailedFinding[];
 export {};
 //# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAiB,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;;;;;GAYG;AAEH,4EAA4E;AAC5E,KAAK,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAenD,CAAC;AAmBF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAE3D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC;kDAC8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB;8CAC0C;IAC1C,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED,eAAO,MAAM,2BAA2B,EAAE,kBAAsC,CAAC;AAEjF,sDAAsD;AACtD,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,GAAG,CAAC,MAAM,CAAC,CAI/E;AASD,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B;;;;uEAImE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAC3B,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,mBAAmB,GACvB,eAAe,EAAE,CA+CnB"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAiB,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;;;;;GAYG;AAEH,4EAA4E;AAC5E,KAAK,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAenD,CAAC;AAmBF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAE3D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC;kDAC8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB;8CAC0C;IAC1C,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED,eAAO,MAAM,2BAA2B,EAAE,kBAAsC,CAAC;AAEjF,sDAAsD;AACtD,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,GAAG,CAAC,MAAM,CAAC,CAI/E;AASD,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B;;;;uEAImE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAC3B,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,mBAAmB,GACvB,eAAe,EAAE,CAEnB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC/B,4DAA4D;IAC5D,OAAO,EAAE,eAAe,CAAC;IACzB;0DACsD;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,mBAAmB,GACvB,eAAe,EAAE,CAwDnB"}

package/dist/validate.js

@@ -97,6 +97,18 @@ function demotedIds(settings) {
  * value in an `info` stream of every check the project has decided against.
  */
 export function validatePage(ast, config, opts) {
+    return validatePageDetailed(ast, config, opts).map((f) => f.warning);
+}
+/**
+ * {@link validatePage}, keeping the structured fields.
+ *
+ * This is where the dispositions actually live; `validatePage` is a projection
+ * of it. Single-sourced deliberately — SPEC-135 D5a requires that every caller
+ * resolve settings through `resolveValidationIds` rather than reimplementing
+ * the three-way refinement, and the cheapest way to guarantee that is for there
+ * to be exactly one implementation to call.
+ */
+export function validatePageDetailed(ast, config, opts) {
     const settings = opts.settings ?? DEFAULT_VALIDATION_SETTINGS;
     const allowed = resolveValidationIds(settings);
     const demoted = demotedIds(settings);
@@ -108,11 +120,13 @@ export function validatePage(ast, config, opts) {
     catch (err) {
         return [
             {
-                severity: 'warning',
-                phase: 'validate',
-                pluginName,
-                url: opts.url,
-                message: `content validation could not run: ${err.message}`,
+                warning: {
+                    severity: 'warning',
+                    phase: 'validate',
+                    pluginName,
+                    url: opts.url,
+                    message: `content validation could not run: ${err.message}`,
+                },
             },
         ];
     }
@@ -133,12 +147,19 @@ export function validatePage(ast, config, opts) {
                 continue;
             }
         }
+        const rawLine = finding.lines?.[0];
         out.push({
-            severity,
-            phase: 'validate',
-            pluginName,
-            url: opts.url,
-            message: formatFinding(finding, opts.contributedBy),
+            warning: {
+                severity,
+                phase: 'validate',
+                pluginName,
+                url: opts.url,
+                message: formatFinding(finding, opts.contributedBy),
+            },
+            id,
+            // `formatFinding` renders `line + 1`; match it so a caller and the
+            // message never disagree about which line is meant.
+            line: typeof rawLine === 'number' ? rawLine + 1 : undefined,
         });
     }
     return out;

package/dist/validate.js.map

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

package/frontmatter.schema.json

@@ -78,6 +78,13 @@
     "modified": {
       "description": "Last-modified date (ISO 8601), overriding what git history or the filesystem reports.",
       "type": "string"
+    },
+    "documents": {
+      "description": "Repository paths this page is about. Read by `refrakt stale` and the `refrakt.stale` MCP tool to rank documentation against the code it describes, and to answer \"I am about to change these files — what documents them?\". Unlike a review marker this does not decay: it names the page's subject, which survives every edit to the code. Paths are repo-root-relative POSIX; one that resolves to no file is reported as an error, because the author asserted the relationship. Does not cascade from a `_layout.md`.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
     }
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@refrakt-md/content",
   "description": "Content loading and transformation pipeline",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./edges": {
+      "types": "./dist/edges/index.d.ts",
+      "default": "./dist/edges/index.js"
     }
   },
   "files": [
@@ -30,10 +34,10 @@
     "build": "tsc"
   },
   "dependencies": {
-    "@refrakt-md/highlight": "0.35.0",
-    "@refrakt-md/runes": "0.35.0",
-    "@refrakt-md/transform": "0.35.0",
-    "@refrakt-md/types": "0.35.0",
+    "@refrakt-md/highlight": "0.37.0",
+    "@refrakt-md/runes": "0.37.0",
+    "@refrakt-md/transform": "0.37.0",
+    "@refrakt-md/types": "0.37.0",
     "@markdoc/markdoc": "0.4.0",
     "yaml": "^2.4.0"
   }