@vibe-agent-toolkit/resources 0.1.39-rc.1 → 0.1.39-rc.2

package/src/resource-registry.ts

@@ -22,8 +22,9 @@ import {
   type FrontmatterExternalUrl,
 } from './frontmatter-link-validator.js';
 import { validateFrontmatter } from './frontmatter-validator.js';
+import { parseHtml } from './html-link-parser.js';
 import { parseMarkdown } from './link-parser.js';
-import { validateLink, type ValidateLinkOptions } from './link-validator.js';
+import { fragmentIndexEntry, validateLink, type FragmentIndex, type ValidateLinkOptions } from './link-validator.js';
 import type { ResourceCollectionInterface } from './resource-collection-interface.js';
 import type { SHA256 } from './schemas/checksum.js';
 import type { ProjectConfig } from './schemas/project-config.js';
@@ -31,6 +32,27 @@ import type { HeadingNode, ResourceMetadata } from './schemas/resource-metadata.
 import type { ValidationResult } from './schemas/validation-result.js';
 import { issueLocation, matchesGlobPattern, splitHrefAnchor } from './utils.js';
 
+/**
+ * Typed error thrown when two resources produce the same ID.
+ *
+ * Carries the authoritative id and both paths so callers can record accurate
+ * issue data without re-deriving the id from the file path (which would be
+ * wrong when the id came from a frontmatter `idField` value).
+ */
+export class DuplicateResourceIdError extends Error {
+  readonly id: string;
+  readonly existingPath: string;
+  readonly conflictingPath: string;
+
+  constructor(id: string, conflictingPath: string, existingPath: string) {
+    super(`Duplicate resource ID '${id}': '${conflictingPath}' conflicts with '${existingPath}'`);
+    this.name = 'DuplicateResourceIdError';
+    this.id = id;
+    this.existingPath = existingPath;
+    this.conflictingPath = conflictingPath;
+  }
+}
+
 /**
  * Options for crawling directories to add resources.
  */
@@ -169,6 +191,12 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    */
   private readonly frontmatterExternalUrlsByResource: Map<string, FrontmatterExternalUrl[]> = new Map();
 
+  /**
+   * Collisions recorded by addResources() when two files produce the same resource id.
+   * Cleared by clear(). Surfaced as DUPLICATE_RESOURCE_ID issues in validate().
+   */
+  private duplicateIdCollisions: Array<{ id: string; existingPath: string; conflictingPath: string }> = [];
+
   constructor(options?: ResourceRegistryOptions) {
     if (options?.baseDir !== undefined) {
       this.baseDir = options.baseDir;
@@ -233,9 +261,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       // Check for duplicate ID
       const existingById = registry.resourcesById.get(resource.id);
       if (existingById) {
-        throw new Error(
-          `Duplicate resource ID '${resource.id}': '${resource.filePath}' conflicts with '${existingById.filePath}'`
-        );
+        throw new DuplicateResourceIdError(resource.id, resource.filePath, existingById.filePath);
       }
 
       // Add to path index
@@ -304,8 +330,12 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Normalize path to absolute
     const absolutePath = safePath.resolve(filePath);
 
-    // Parse the markdown file (needed before ID generation for frontmatter lookup)
-    const parseResult = await parseMarkdown(absolutePath);
+    // Parse the file — HTML or markdown depending on extension
+    const lowerPath = absolutePath.toLowerCase();
+    const isHtml = lowerPath.endsWith('.html') || lowerPath.endsWith('.htm');
+    const parseResult = isHtml
+      ? await parseHtml(absolutePath)
+      : await parseMarkdown(absolutePath);
 
     // Generate ID using priority chain: frontmatter field → relative path → filename stem
     const id = this.generateId(absolutePath, parseResult.frontmatter);
@@ -313,9 +343,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Check for duplicate ID (allow re-adding same file path)
     const existingById = this.resourcesById.get(id);
     if (existingById && existingById.filePath !== absolutePath) {
-      throw new Error(
-        `Duplicate resource ID '${id}': '${absolutePath}' conflicts with '${existingById.filePath}'`
-      );
+      throw new DuplicateResourceIdError(id, absolutePath, existingById.filePath);
     }
 
     // Get file modified time
@@ -336,6 +364,8 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       filePath: absolutePath,
       links: parseResult.links,
       headings: parseResult.headings,
+      ...(parseResult.anchors !== undefined && { anchors: parseResult.anchors }),
+      ...(parseResult.parseErrors !== undefined && { parseErrors: parseResult.parseErrors }),
       ...(parseResult.frontmatter !== undefined && { frontmatter: parseResult.frontmatter }),
       ...(parseResult.frontmatterError !== undefined && { frontmatterError: parseResult.frontmatterError }),
       sizeBytes: parseResult.sizeBytes,
@@ -372,7 +402,20 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   async addResources(filePaths: string[]): Promise<ResourceMetadata[]> {
     const results: ResourceMetadata[] = [];
     for (const fp of filePaths) {
-      results.push(await this.addResource(fp));
+      try {
+        results.push(await this.addResource(fp));
+      } catch (error) {
+        if (error instanceof DuplicateResourceIdError) {
+          this.duplicateIdCollisions.push({
+            id: error.id,
+            existingPath: error.existingPath,
+            conflictingPath: error.conflictingPath,
+          });
+          // First-added wins; skip conflicting file and continue crawling.
+        } else {
+          throw error;
+        }
+      }
     }
     return results;
   }
@@ -396,7 +439,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   async crawl(options: CrawlOptions): Promise<ResourceMetadata[]> {
     const {
       baseDir,
-      include = ['**/*.md'],
+      include = ['**/*.md', '**/*.html', '**/*.htm'],
       exclude = ['**/node_modules/**', '**/.git/**', '**/dist/**'],
       followSymlinks = false,
     } = options;
@@ -442,12 +485,48 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     return issues;
   }
 
+  /**
+   * Emit MALFORMED_HTML issues from each resource's HTML parse errors.
+   * @private
+   */
+  private collectHtmlParseErrors(): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    for (const resource of this.resourcesByPath.values()) {
+      for (const parseError of resource.parseErrors ?? []) {
+        issues.push(
+          createRegistryIssue(
+            'MALFORMED_HTML',
+            `Malformed HTML: ${parseError.message}`,
+            {
+              location: issueLocation(resource.filePath, this.baseDir),
+              ...(parseError.line !== undefined && { line: parseError.line }),
+            },
+          ),
+        );
+      }
+    }
+    return issues;
+  }
+
+  /**
+   * Emit DUPLICATE_RESOURCE_ID errors for collisions recorded by addResources().
+   * @private
+   */
+  private collectDuplicateIdErrors(): ValidationIssue[] {
+    return this.duplicateIdCollisions.map(({ id, existingPath, conflictingPath }) =>
+      createRegistryIssue(
+        'DUPLICATE_RESOURCE_ID',
+        `Two files resolve to the same resource id '${id}': '${issueLocation(existingPath, this.baseDir)}' and '${issueLocation(conflictingPath, this.baseDir)}'. Rename one of the files so they produce distinct resource ids.`,
+      ),
+    );
+  }
+
   /**
    * Validate all links in all resources.
    * @private
    */
   private async validateAllLinks(
-    headingsByFile: Map<string, HeadingNode[]>,
+    fragmentsByFile: FragmentIndex,
     skipGitIgnoreCheck: boolean
   ): Promise<ValidationIssue[]> {
     const issues: ValidationIssue[] = [];
@@ -463,7 +542,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
               ...(this.gitTracker !== undefined && { gitTracker: this.gitTracker })
             };
 
-        const issue = await validateLink(link, resource.filePath, headingsByFile, validateOptions);
+        const issue = await validateLink(link, resource.filePath, fragmentsByFile, validateOptions);
         if (issue) {
           issues.push(issue);
         }
@@ -501,7 +580,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    * @private
    */
   private async validateCollectionFrontmatter(
-    headingsByFile: Map<string, HeadingNode[]>,
+    fragmentsByFile: FragmentIndex,
     skipGitIgnoreCheck: boolean,
   ): Promise<ValidationIssue[]> {
     const issues: ValidationIssue[] = [];
@@ -523,7 +602,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       const collectionIssues = await this.validateResourceCollectionSchemas(
         resource,
         fsPromises,
-        headingsByFile,
+        fragmentsByFile,
         skipGitIgnoreCheck,
       );
       issues.push(...collectionIssues);
@@ -539,7 +618,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   private async validateResourceCollectionSchemas(
     resource: ResourceMetadata,
     fsModule: typeof fs,
-    headingsByFile: Map<string, HeadingNode[]>,
+    fragmentsByFile: FragmentIndex,
     skipGitIgnoreCheck: boolean,
   ): Promise<ValidationIssue[]> {
     const issues: ValidationIssue[] = [];
@@ -560,7 +639,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         resource,
         collection.validation,
         fsModule,
-        headingsByFile,
+        fragmentsByFile,
         skipGitIgnoreCheck,
       );
       issues.push(...collectionIssues);
@@ -577,7 +656,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     resource: ResourceMetadata,
     validation: NonNullable<NonNullable<ProjectConfig['resources']>['collections']>[string]['validation'],
     fsModule: typeof fs,
-    headingsByFile: Map<string, HeadingNode[]>,
+    fragmentsByFile: FragmentIndex,
     skipGitIgnoreCheck: boolean,
   ): Promise<ValidationIssue[]> {
     if (!validation?.frontmatterSchema) {
@@ -620,7 +699,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
           resource.frontmatter,
           schema,
           resource.filePath,
-          headingsByFile,
+          fragmentsByFile,
           linkOptions,
         );
         issues.push(...linkIssues);
@@ -679,8 +758,8 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   async validate(options?: ValidateOptions): Promise<ValidationResult> {
     const startTime = Date.now();
 
-    // Build headings map for validation
-    const headingsByFile = this.buildHeadingsByFileMap();
+    // Build fragment index for anchor validation
+    const fragmentsByFile = this.buildFragmentIndex();
 
     // Reset frontmatter external URL state for this validation run
     this.frontmatterExternalUrlsByResource.clear();
@@ -688,19 +767,21 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Collect all validation issues
     const issues: ValidationIssue[] = [];
 
-    // Check for YAML parsing errors first
-    issues.push(...this.collectYamlErrors());
+    // Surface parse-time diagnostics: YAML frontmatter errors first, then HTML
+    // well-formedness, then duplicate-id collisions. Combined into one push() call
+    // (SonarCloud S7778).
+    issues.push(...this.collectYamlErrors(), ...this.collectHtmlParseErrors(), ...this.collectDuplicateIdErrors());
 
     // Validate each link in each resource
     const linkIssues = await this.validateAllLinks(
-      headingsByFile,
+      fragmentsByFile,
       options?.skipGitIgnoreCheck ?? false
     );
     issues.push(...linkIssues);
 
     // Per-collection frontmatter validation
     const collectionFrontmatterIssues = await this.validateCollectionFrontmatter(
-      headingsByFile,
+      fragmentsByFile,
       options?.skipGitIgnoreCheck ?? false,
     );
     issues.push(...collectionFrontmatterIssues);
@@ -1044,6 +1125,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     this.resourcesById.clear();
     this.resourcesByName.clear();
     this.resourcesByChecksum.clear();
+    this.duplicateIdCollisions = [];
   }
 
   /**
@@ -1253,14 +1335,20 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   }
 
   /**
-   * Build a map of file paths to their heading trees.
-   *
-   * Used for link validation.
+   * Build a format-neutral fragment index for anchor validation: each file's
+   * absolute path → the set of valid fragment targets. Markdown contributes
+   * heading slugs (lowercased); HTML contributes its `id`/`name` anchors.
    */
-  private buildHeadingsByFileMap(): Map<string, HeadingNode[]> {
-    const map = new Map<string, HeadingNode[]>();
+  private buildFragmentIndex(): FragmentIndex {
+    const map: FragmentIndex = new Map();
     for (const resource of this.resourcesByPath.values()) {
-      map.set(resource.filePath, resource.headings);
+      const fragments = new Set<string>();
+      collectHeadingSlugs(resource.headings, fragments);
+      for (const anchor of resource.anchors ?? []) {
+        fragments.add(anchor);
+      }
+      // Policy (case-sensitive ids vs folded slugs) is derived from the file type.
+      map.set(resource.filePath, fragmentIndexEntry(resource.filePath, fragments));
     }
     return map;
   }
@@ -1318,29 +1406,47 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   }
 }
 
+/** Recursively collect lowercased heading slugs into `out`. */
+function collectHeadingSlugs(headings: HeadingNode[], out: Set<string>): void {
+  for (const heading of headings) {
+    out.add(heading.slug.toLowerCase());
+    if (heading.children) {
+      collectHeadingSlugs(heading.children, out);
+    }
+  }
+}
+
 /**
  * Generate an ID from a file path.
  *
+ * Every resource id includes a `-<ext>` suffix derived from the file extension
+ * (dot stripped, lowercased). This makes ids from different file types distinct
+ * even when the stem is identical (e.g. `foo.md` → `foo-md`, `foo.html` → `foo-html`).
+ * Extensionless files (e.g. `Makefile`) receive no suffix.
+ *
  * When `baseDir` is provided, computes a relative path from baseDir and uses the full
  * directory structure in the ID. When no `baseDir`, uses the filename stem only.
  *
  * @param filePath - Absolute file path
  * @param baseDir - Base directory for relative path computation (optional)
- * @returns Generated ID in kebab-case
+ * @returns Generated ID in kebab-case with `-<ext>` suffix
  *
  * @example
  * ```typescript
- * // Without baseDir: filename stem only
- * generateIdFromPath('/project/docs/User Guide.md')  // 'user-guide'
- * generateIdFromPath('/project/README.md')            // 'readme'
+ * // Without baseDir: filename stem + extension suffix
+ * generateIdFromPath('/project/docs/User Guide.md')  // 'user-guide-md'
+ * generateIdFromPath('/project/README.md')            // 'readme-md'
+ * generateIdFromPath('/project/page.html')            // 'page-html'
+ * generateIdFromPath('/project/Makefile')             // 'makefile'
  *
- * // With baseDir: relative path
- * generateIdFromPath('/project/docs/concepts/core/overview.md', '/project/docs')  // 'concepts-core-overview'
- * generateIdFromPath('/project/docs/guide.md', '/project/docs')                   // 'guide'
+ * // With baseDir: relative path + extension suffix
+ * generateIdFromPath('/project/docs/concepts/core/overview.md', '/project/docs')  // 'concepts-core-overview-md'
+ * generateIdFromPath('/project/docs/guide.md', '/project/docs')                   // 'guide-md'
  * ```
  */
 export function generateIdFromPath(filePath: string, baseDir?: string): string {
   let rawId: string;
+  let extSuffix = '';
 
   if (baseDir) {
     // Compute relative path from baseDir, remove extension
@@ -1349,11 +1455,23 @@ export function generateIdFromPath(filePath: string, baseDir?: string): string {
     const withoutExt = ext ? relativePath.slice(0, -ext.length) : relativePath;
     // Normalize path separators to forward slashes (cross-platform), then replace with hyphens
     rawId = toForwardSlash(withoutExt).replaceAll('/', '-');
+    if (ext) {
+      // Strip the leading dot; lowercasing happens in the kebab pipeline below
+      extSuffix = `-${ext.slice(1)}`;
+    }
   } else {
     // Fallback: basename only (no directory context)
-    rawId = path.basename(filePath, path.extname(filePath));
+    const ext = path.extname(filePath);
+    rawId = path.basename(filePath, ext);
+    if (ext) {
+      extSuffix = `-${ext.slice(1)}`;
+    }
   }
 
+  // Append extension suffix before the kebab pipeline so hyphen-collapse and
+  // trim apply uniformly (e.g. suffixed-.md → 'suffixed--md' → 'suffixed-md')
+  rawId = `${rawId}${extSuffix}`;
+
   // Convert to kebab-case:
   // 1. Replace underscores and spaces with hyphens
   // 2. Convert to lowercase

package/src/schemas/link-auth.ts

@@ -0,0 +1,146 @@
+/**
+ * Zod schema for `resources.linkAuth` config.
+ *
+ * Validates the shape of an adopter's linkAuth configuration: providers
+ * (each either a `use: <macro>` reference or a full inline provider) plus
+ * an optional cache config. Strict — typos in provider field names are
+ * errors, per Postel's law ("writing our output → conservative").
+ *
+ * Provider entries accept EITHER:
+ *   - `{ use: <name>, ...overrides }` — reference a shipped macro by name;
+ *     override fields are deep-merged on top at expansion time. Overrides
+ *     are NOT strictly typed at this layer because they must match the
+ *     macro's shape, which we cannot see until expansion. A typo in an
+ *     override silently no-ops; the full provider shape is validated
+ *     after expansion (slice 2 wires that).
+ *   - A full inline `{ match, rewrite, auth, token, check }` — every field
+ *     required, every nested object strict.
+ *
+ * Mirrors the runtime types in `@vibe-agent-toolkit/utils`'s `link-auth/`
+ * module. Keep these aligned: a config that parses here must satisfy the
+ * `Provider` / `LinkAuthConfig` interfaces over there.
+ *
+ * Per design issue #113 §4 (vocabulary) and §5 (macros).
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Leaf types
+// ---------------------------------------------------------------------------
+
+export const ProviderMatchSchema = z
+  .object({
+    host: z.string().min(1).describe('Glob matched against URL hostname'),
+    excludeHost: z
+      .array(z.string().min(1))
+      .optional()
+      .describe('Globs that, if any match the hostname, exclude this provider'),
+  })
+  .strict()
+  .describe('Provider selection — match.host + optional excludeHost globs');
+
+export const RewriteRuleSchema = z
+  .object({
+    when: z.string().min(1).describe('Regex source (RFC-style, JavaScript-compatible) matched against the URL'),
+    vars: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe('Computed variables, each a template that references captures from `when`'),
+    to: z.string().min(1).describe('URL template — interpolates ${capture} and ${var}'),
+  })
+  .strict()
+  .describe('A single rewrite rule (one entry in a provider\'s ordered rewrite list)');
+
+export const ProviderAuthSchema = z
+  .object({
+    headers: z
+      .record(z.string(), z.string())
+      .describe('Header name → value template. Values interpolate ${token} and any capture/var.'),
+  })
+  .strict()
+  .describe('Auth headers attached to the authenticated fetch');
+
+export const TokenSourceSchema = z
+  .union([
+    z.object({ env: z.string().min(1) }).strict(),
+    z
+      .object({
+        command: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),
+      })
+      .strict(),
+  ])
+  .describe('A single token source — env var, or argv command (preferred), or convenience string');
+
+export const ProviderCheckSchema = z
+  .object({
+    method: z.enum(['GET', 'HEAD']),
+    aliveStatus: z
+      .array(z.number().int().min(100).max(599))
+      .min(1)
+      .describe('HTTP status codes meaning the URL is alive (per host semantics)'),
+    notFoundMeaning: z
+      .enum(['ambiguous', 'dead'])
+      .describe(
+        'Per-host: does 404 mean "dead" (honest 404 host like Graph) or "ambiguous" (masking host like GitHub)?',
+      ),
+  })
+  .strict()
+  .describe('Status-to-outcome classifier (consumed by the resources layer, not the pure engine)');
+
+// ---------------------------------------------------------------------------
+// Provider entry (inline OR macro reference)
+// ---------------------------------------------------------------------------
+
+const InlineProviderSchema = z
+  .object({
+    match: ProviderMatchSchema,
+    rewrite: z.array(RewriteRuleSchema).min(1).describe('Ordered rewrite rules — first matching wins'),
+    auth: ProviderAuthSchema,
+    token: z.array(TokenSourceSchema).describe('Ordered token sources — first non-empty wins'),
+    check: ProviderCheckSchema,
+  })
+  .strict();
+
+const MacroProviderSchema = z
+  .object({
+    use: z.string().min(1).describe('Macro name (e.g. "github", "sharepoint")'),
+  })
+  .passthrough()
+  .describe(
+    'Reference a shipped macro by name. Override fields (match/rewrite/auth/token/check) deep-merge on top at expansion time.',
+  );
+
+export const ProviderEntrySchema = z
+  .union([MacroProviderSchema, InlineProviderSchema])
+  .describe('A provider entry — either { use: <macro>, ...overrides } or a full inline provider');
+
+// ---------------------------------------------------------------------------
+// Top-level linkAuth config
+// ---------------------------------------------------------------------------
+
+export const LinkAuthCacheSchema = z
+  .object({
+    ttlMinutes: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe('Content cache TTL in minutes (default 30 — used by slice 3 content-fetch)'),
+  })
+  .strict();
+
+export const LinkAuthConfigSchema = z
+  .object({
+    cache: LinkAuthCacheSchema.optional(),
+    providers: z
+      .array(ProviderEntrySchema)
+      .describe('Ordered list of providers — first claiming-by-host wins'),
+  })
+  .strict()
+  .describe('`resources.linkAuth` — authenticated external link resolution config');
+
+export type LinkAuthConfig = z.infer<typeof LinkAuthConfigSchema>;
+export type ProviderEntry = z.infer<typeof ProviderEntrySchema>;
+export type RewriteRule = z.infer<typeof RewriteRuleSchema>;
+export type TokenSource = z.infer<typeof TokenSourceSchema>;

package/src/schemas/project-config.ts

@@ -1,6 +1,8 @@
 import { ValidationConfigSchema } from '@vibe-agent-toolkit/agent-schema';
 import { z } from 'zod';
 
+import { LinkAuthConfigSchema } from './link-auth.js';
+
 /**
  * Official semver regex from https://semver.org/ (anchored).
  *
@@ -98,6 +100,8 @@ export const ResourcesConfigSchema = z.object({
     .describe('Named collections of resources'),
   validation: ValidationConfigSchema.optional()
     .describe('Validation framework config: severity overrides and per-code allow entries (applied inside ResourceRegistry.validate)'),
+  linkAuth: LinkAuthConfigSchema.optional()
+    .describe('Authenticated external link resolution config (issue #113 / link-auth engine)'),
 }).describe('Resources section of project configuration');
 
 export type ResourcesConfig = z.infer<typeof ResourcesConfigSchema>;

package/src/schemas/resource-metadata.ts

@@ -6,6 +6,7 @@ import { SHA256Schema } from './checksum.js';
  * Type of link found in markdown resources.
  *
  * - `local_file`: Link to a local file (relative or absolute path)
+ * - `local_directory`: Link to a local directory, e.g. a ref ending in `/`
  * - `anchor`: Link to a heading anchor (e.g., #heading-slug)
  * - `external`: HTTP/HTTPS URL to external resource
  * - `email`: Mailto link
@@ -13,6 +14,7 @@ import { SHA256Schema } from './checksum.js';
  */
 export const LinkTypeSchema = z.enum([
   'local_file',
+  'local_directory',
   'anchor',
   'external',
   'email',
@@ -36,6 +38,16 @@ export const LinkNodeTypeSchema = z.enum([
 
 export type LinkNodeType = z.infer<typeof LinkNodeTypeSchema>;
 
+/**
+ * Zod schema for an HTML well-formedness diagnostic.
+ */
+export const HtmlParseErrorSchema = z.object({
+  message: z.string().describe('parse5 error code (e.g. "missing-end-tag")'),
+  line: z.number().int().positive().optional().describe('1-based source line, when known'),
+}).describe('HTML well-formedness diagnostic');
+
+export type HtmlParseError = z.infer<typeof HtmlParseErrorSchema>;
+
 /**
  * Represents a heading node in the document's table of contents.
  *
@@ -96,6 +108,10 @@ export const ResourceMetadataSchema = z.object({
   filePath: z.string().describe('Absolute path to the resource file'),
   links: z.array(ResourceLinkSchema).describe('All links found in the resource'),
   headings: z.array(HeadingNodeSchema).describe('Document table of contents (top-level headings only; children are nested)'),
+  anchors: z.array(z.string()).optional()
+    .describe('Fragment targets for anchor validation (HTML id/name attributes)'),
+  parseErrors: z.array(HtmlParseErrorSchema).optional()
+    .describe('HTML well-formedness diagnostics (populated for HTML resources only)'),
   frontmatter: z.record(z.string(), z.unknown()).optional()
     .describe('Parsed YAML frontmatter (if present in markdown file)'),
   frontmatterError: z.string().optional()
@@ -106,6 +122,6 @@ export const ResourceMetadataSchema = z.object({
   checksum: SHA256Schema.describe('SHA-256 checksum of file content'),
   collections: z.array(z.string()).optional()
     .describe('Collection names this resource belongs to (populated when using config-based discovery)'),
-}).describe('Complete metadata for a markdown resource');
+}).strict().describe('Complete metadata for a markdown resource');
 
 export type ResourceMetadata = z.infer<typeof ResourceMetadataSchema>;