patram 0.10.0 → 0.12.0

package/lib/parse/parse-claims.d.ts

@@ -11,16 +11,12 @@ export function parseSourceFile(parse_input: ParseClaimsInput, parse_options?: {
 /**
  * Build parser options from repo config.
  *
- * @param {{ fields?: Record<string, { multiple?: boolean }>, mappings?: Record<string, { emit?: unknown, node?: unknown }> } | undefined} repo_config
+ * @param {{ fields?: Record<string, { many?: boolean }> } | undefined} repo_config
  * @returns {{ multi_value_directive_names: Set<string> }}
  */
 export function createParseOptions(repo_config: {
     fields?: Record<string, {
-        multiple?: boolean;
-    }>;
-    mappings?: Record<string, {
-        emit?: unknown;
-        node?: unknown;
+        many?: boolean;
     }>;
 } | undefined): {
     multi_value_directive_names: Set<string>;

package/lib/parse/parse-claims.js

@@ -20,13 +20,13 @@ import {
  * Routes each source file to markdown or JSDoc claim parsing and keeps claim
  * extraction on one entrypoint.
  *
- * Kind: parse
- * Status: active
- * Uses Term: ../../docs/reference/terms/claim.md
- * Uses Term: ../../docs/reference/terms/document.md
- * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../../docs/decisions/jsdoc-metadata-directive-syntax.md
- * Implements: ../../docs/tasks/v0/parse-claims.md
+ * kind: parse
+ * status: active
+ * uses_term: ../../docs/reference/terms/claim.md
+ * uses_term: ../../docs/reference/terms/document.md
+ * tracked_in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../../docs/decisions/jsdoc-metadata-directive-syntax.md
+ * implements: ../../docs/tasks/v0/parse-claims.md
  * @patram
  * @see {@link ./markdown/parse-markdown-claims.js}
  * @see {@link ./jsdoc/parse-jsdoc-claims.js}
@@ -59,7 +59,7 @@ export function parseSourceFile(parse_input, parse_options) {
 /**
  * Build parser options from repo config.
  *
- * @param {{ fields?: Record<string, { multiple?: boolean }>, mappings?: Record<string, { emit?: unknown, node?: unknown }> } | undefined} repo_config
+ * @param {{ fields?: Record<string, { many?: boolean }> } | undefined} repo_config
  * @returns {{ multi_value_directive_names: Set<string> }}
  */
 export function createParseOptions(repo_config) {
@@ -69,7 +69,7 @@ export function createParseOptions(repo_config) {
 }
 
 /**
- * @param {{ fields?: Record<string, { multiple?: boolean }>, mappings?: Record<string, { emit?: unknown, node?: unknown }> } | undefined} repo_config
+ * @param {{ fields?: Record<string, { many?: boolean }> } | undefined} repo_config
  * @returns {Set<string>}
  */
 function collectMultiValueDirectiveNames(repo_config) {
@@ -77,60 +77,18 @@ function collectMultiValueDirectiveNames(repo_config) {
   const multi_value_directive_names = new Set();
 
   collectMultipleFieldNames(repo_config?.fields, multi_value_directive_names);
-  collectEmitOnlyDirectiveNames(
-    repo_config?.mappings,
-    multi_value_directive_names,
-  );
 
   return multi_value_directive_names;
 }
 
 /**
- * @param {Record<string, { multiple?: boolean }> | undefined} fields
+ * @param {Record<string, { many?: boolean }> | undefined} fields
  * @param {Set<string>} multi_value_directive_names
  */
 function collectMultipleFieldNames(fields, multi_value_directive_names) {
   for (const [field_name, field_definition] of Object.entries(fields ?? {})) {
-    if (field_definition.multiple === true) {
+    if (field_definition.many === true) {
       multi_value_directive_names.add(field_name);
     }
   }
 }
-
-/**
- * @param {Record<string, { emit?: unknown, node?: unknown }> | undefined} mappings
- * @param {Set<string>} multi_value_directive_names
- */
-function collectEmitOnlyDirectiveNames(mappings, multi_value_directive_names) {
-  for (const [mapping_name, mapping_definition] of Object.entries(
-    mappings ?? {},
-  )) {
-    const directive_name = resolveEmitOnlyDirectiveName(
-      mapping_name,
-      mapping_definition,
-    );
-
-    if (directive_name) {
-      multi_value_directive_names.add(directive_name);
-    }
-  }
-}
-
-/**
- * @param {string} mapping_name
- * @param {{ emit?: unknown, node?: unknown }} mapping_definition
- * @returns {string | null}
- */
-function resolveEmitOnlyDirectiveName(mapping_name, mapping_definition) {
-  const directive_match = mapping_name.match(/^[^.]+\.directive\.(.+)$/du);
-
-  if (
-    !directive_match ||
-    mapping_definition.emit === undefined ||
-    mapping_definition.node !== undefined
-  ) {
-    return null;
-  }
-
-  return directive_match[1];
-}

package/lib/parse/tagged-fenced/tagged-fenced-blocks.d.ts

@@ -4,10 +4,10 @@
  * Loads or extracts one markdown file worth of tagged fenced blocks and
  * provides exact-match selection helpers.
  *
- * Kind: parse
- * Status: active
- * Tracked in: ../../../docs/plans/v0/tagged-fenced-block-extraction.md
- * Decided by: ../../../docs/decisions/tagged-fenced-block-extraction.md
+ * kind: parse
+ * status: active
+ * tracked_in: ../../../docs/plans/v0/tagged-fenced-block-extraction.md
+ * decided_by: ../../../docs/decisions/tagged-fenced-block-extraction.md
  * @patram
  * @see {@link ../../../docs/decisions/tagged-fenced-block-extraction.md}
  */

package/lib/parse/tagged-fenced/tagged-fenced-blocks.js

@@ -18,10 +18,10 @@ import { extractTaggedFencedBlocksFromSource } from './tagged-fenced-block-parse
  * Loads or extracts one markdown file worth of tagged fenced blocks and
  * provides exact-match selection helpers.
  *
- * Kind: parse
- * Status: active
- * Tracked in: ../../../docs/plans/v0/tagged-fenced-block-extraction.md
- * Decided by: ../../../docs/decisions/tagged-fenced-block-extraction.md
+ * kind: parse
+ * status: active
+ * tracked_in: ../../../docs/plans/v0/tagged-fenced-block-extraction.md
+ * decided_by: ../../../docs/decisions/tagged-fenced-block-extraction.md
  * @patram
  * @see {@link ../../../docs/decisions/tagged-fenced-block-extraction.md}
  */

package/lib/parse/yaml/parse-yaml-claims.js

@@ -16,10 +16,10 @@ import { YAML_SOURCE_FILE_EXTENSIONS } from '../../config/source-file-defaults.j
  * Parses standalone YAML metadata files and front matter with one projection
  * model for top-level scalar directives.
  *
- * Kind: parse
- * Status: active
- * Tracked in: ../../../docs/plans/v0/yaml-source-and-front-matter.md
- * Decided by: ../../../docs/decisions/yaml-source-and-front-matter.md
+ * kind: parse
+ * status: active
+ * tracked_in: ../../../docs/plans/v0/yaml-source-and-front-matter.md
+ * decided_by: ../../../docs/decisions/yaml-source-and-front-matter.md
  * @patram
  * @see {@link ../parse-claims.js}
  * @see {@link ../markdown/parse-markdown-directives.js}

package/lib/patram.d.ts

@@ -5,7 +5,7 @@ export {
   selectTaggedBlocks,
 } from './parse/tagged-fenced/tagged-fenced-blocks.js';
 
-export { parseWhereClause } from './graph/query/parse.js';
+export { parseQueryExpression } from './graph/query/parse-query.js';
 export { getQuerySemanticDiagnostics } from './graph/query/inspect.js';
 export { loadProjectGraph } from './graph/load-project-graph.js';
 export { queryGraph } from './graph/query/execute.js';
@@ -48,8 +48,8 @@ export type PatramParsedTerm =
   import('./graph/parse-where-clause.types.d.ts').ParsedTerm;
 export type PatramParsedExpression =
   import('./graph/parse-where-clause.types.d.ts').ParsedExpression;
-export type PatramParseWhereClauseResult =
-  import('./graph/parse-where-clause.types.d.ts').ParseWhereClauseResult;
+export type PatramParseQueryResult =
+  import('./graph/parse-where-clause.types.d.ts').ParseQueryResult;
 export type PatramQuerySource =
   | {
       kind: 'ad_hoc';
@@ -59,6 +59,12 @@ export type PatramQuerySource =
       name: string;
     };
 
+export interface PatramQueryGraphOptions {
+  bindings?: Record<string, string>;
+  limit?: number;
+  offset?: number;
+}
+
 export interface PatramProjectGraphResult {
   claims: import('./parse/parse-claims.types.d.ts').PatramClaim[];
   config: import('./config/load-patram-config.types.d.ts').PatramRepoConfig;

package/lib/patram.js

@@ -5,7 +5,7 @@ export {
   selectTaggedBlocks,
 } from './parse/tagged-fenced/tagged-fenced-blocks.js';
 
-export { parseWhereClause } from './graph/query/parse.js';
+export { parseQueryExpression } from './graph/query/parse-query.js';
 export { getQuerySemanticDiagnostics } from './graph/query/inspect.js';
 export { loadProjectGraph } from './graph/load-project-graph.js';
 export { queryGraph } from './graph/query/execute.js';

package/lib/scan/discover-fields.js

@@ -2,20 +2,20 @@
 /**
  * @import { ClaimOrigin, PatramClaim } from '../parse/parse-claims.types.ts';
  * @import {
- *   DiscoveredFieldMultiplicity,
  *   DiscoveredFieldTypeName,
- *   FieldDiscoveryClassUsage,
  *   FieldDiscoveryEvidenceReference,
  *   FieldDiscoveryMultiplicitySuggestion,
+ *   FieldDiscoveryOnUsage,
  *   FieldDiscoveryResult,
  *   FieldDiscoverySuggestion,
+ *   FieldDiscoveryTargetSuggestion,
  *   FieldDiscoveryTypeSuggestion,
  * } from './discover-fields.types.ts';
  */
 
 import { readFile } from 'node:fs/promises';
 import process from 'node:process';
-import { resolve } from 'node:path';
+import { posix, resolve } from 'node:path';
 
 import { DEFAULT_INCLUDE_PATTERNS } from '../config/source-file-defaults.js';
 import { listSourceFiles } from './list-source-files.js';
@@ -26,21 +26,8 @@ import {
 } from '../parse/markdown/parse-markdown-directives.js';
 import { isPathLikeTarget } from '../parse/claim-helpers.js';
 
-/**
- * Field discovery from source claims.
- *
- * Scans the repository source files directly, infers likely metadata fields,
- * and reports advisory suggestions without requiring repo config to load.
- *
- * Kind: discovery
- * Status: active
- * Tracked in: ../../docs/plans/v1/field-model-redesign.md
- * Decided by: ../../docs/decisions/field-discovery-workflow.md
- * @patram
- * @see {@link ../output/render-field-discovery.js}
- */
-
 const TYPE_NAME_ORDER = /** @type {const} */ ([
+  'ref',
   'integer',
   'date_time',
   'date',
@@ -57,7 +44,11 @@ const ENUM_PATTERN = /^[a-z0-9_][a-z0-9_-]*$/du;
 const PATH_PATTERN = /^[a-z0-9_.-]+\.[a-z0-9]+$/du;
 
 /**
- * @typedef {FieldDiscoveryClassUsage & { confidence: number }} InferredFieldClassUsage
+ * @typedef {FieldDiscoveryOnUsage & { confidence: number }} InferredFieldOnUsage
+ */
+
+/**
+ * @typedef {FieldDiscoveryTargetSuggestion & { confidence: number }} InferredFieldTargetSuggestion
  */
 
 /**
@@ -98,20 +89,10 @@ export async function discoverFields(
   );
   /** @type {FieldObservation[]} */
   const field_observations = parse_results.flatMap((parse_result) => {
-    /** @type {Set<string>} */
-    const document_classes = new Set();
-
-    for (const claim of parse_result.claims) {
-      if (
-        claim.type === 'directive' &&
-        claim.name === 'kind' &&
-        typeof claim.value === 'string' &&
-        claim.value.length > 0
-      ) {
-        document_classes.add(claim.value);
-      }
-    }
-
+    const document_types = inferDocumentTypes(
+      parse_result.path,
+      parse_result.claims,
+    );
     const allowed_markdown_lines = collectAllowedMarkdownDirectiveLines(
       parse_result.path,
       parse_result.source_text,
@@ -132,11 +113,11 @@ export async function discoverFields(
 
       return [
         {
-          class_names: new Set(document_classes),
           document_id: claim.document_id,
           name: claim.name,
           normalized_value: normalizeDiscoveryValue(claim.value),
           origin: claim.origin,
+          type_names: new Set(document_types),
           value: claim.value,
         },
       ];
@@ -188,20 +169,28 @@ export async function discoverFields(
  * @returns {FieldDiscoverySuggestion}
  */
 function buildFieldSuggestion(field_bucket) {
-  const type_result = inferFieldType(field_bucket.observations);
+  const target_result = inferFieldTarget(field_bucket.observations);
+  const type_result = inferFieldType(field_bucket.observations, target_result);
   const multiplicity_result = inferFieldMultiplicity(field_bucket.observations);
-  const class_usage_result = inferFieldClassUsage(field_bucket.observations);
+  const on_result = inferFieldOn(field_bucket.observations);
   const evidence_references = buildEvidenceReferences(
     field_bucket.observations,
   );
   const conflicting_evidence = buildEvidenceReferences(
-    field_bucket.observations.filter(
-      (field_observation) =>
+    field_bucket.observations.filter((field_observation) => {
+      if (type_result.name === 'ref') {
+        return (
+          scoreFieldValue(field_observation.normalized_value, 'path') === 0
+        );
+      }
+
+      return (
         scoreFieldValue(
           field_observation.normalized_value,
           type_result.name,
-        ) === 0,
-    ),
+        ) === 0
+      );
+    }),
   );
 
   return {
@@ -209,16 +198,17 @@ function buildFieldSuggestion(field_bucket) {
       Math.round(
         ((type_result.confidence +
           multiplicity_result.confidence +
-          class_usage_result.confidence) /
+          on_result.confidence) /
           3) *
           100,
       ) / 100,
     conflicting_evidence,
     evidence_references,
-    likely_class_usage: {
-      classes: class_usage_result.classes,
-    },
     likely_multiplicity: multiplicity_result,
+    likely_on: {
+      types: on_result.types,
+    },
+    likely_to: type_result.name === 'ref' ? target_result : undefined,
     likely_type: type_result,
     name: field_bucket.name,
   };
@@ -288,29 +278,29 @@ function inferFieldMultiplicity(observations) {
 
 /**
  * @param {FieldObservation[]} observations
- * @returns {InferredFieldClassUsage}
+ * @returns {InferredFieldOnUsage}
  */
-function inferFieldClassUsage(observations) {
+function inferFieldOn(observations) {
   /** @type {Map<string, number>} */
-  const class_counts = new Map();
+  const type_counts = new Map();
   let documented_observation_count = 0;
 
   for (const observation of observations) {
-    if (observation.class_names.size === 0) {
+    if (observation.type_names.size === 0) {
       continue;
     }
 
     documented_observation_count += 1;
 
-    for (const class_name of observation.class_names) {
-      class_counts.set(class_name, (class_counts.get(class_name) ?? 0) + 1);
+    for (const type_name of observation.type_names) {
+      type_counts.set(type_name, (type_counts.get(type_name) ?? 0) + 1);
     }
   }
 
-  if (class_counts.size === 0) {
+  if (type_counts.size === 0) {
     return {
       confidence: 0.2,
-      classes: ['document'],
+      types: ['document'],
     };
   }
 
@@ -319,17 +309,25 @@ function inferFieldClassUsage(observations) {
       Math.round(
         (documented_observation_count / Math.max(observations.length, 1)) * 100,
       ) / 100,
-    classes: [...class_counts.keys()].sort((left_class, right_class) =>
-      left_class.localeCompare(right_class, 'en'),
+    types: [...type_counts.keys()].sort((left_type, right_type) =>
+      left_type.localeCompare(right_type, 'en'),
     ),
   };
 }
 
 /**
  * @param {FieldObservation[]} observations
+ * @param {InferredFieldTargetSuggestion | undefined} target_result
  * @returns {FieldDiscoveryTypeSuggestion}
  */
-function inferFieldType(observations) {
+function inferFieldType(observations, target_result) {
+  if (target_result && scoreFieldType(observations, 'path') >= 0.9) {
+    return {
+      confidence: target_result.confidence,
+      name: 'ref',
+    };
+  }
+
   /** @type {FieldDiscoveryTypeSuggestion[]} */
   const type_candidates = TYPE_NAME_ORDER.map((type_name) => ({
     confidence: scoreFieldType(observations, type_name),
@@ -350,6 +348,38 @@ function inferFieldType(observations) {
   return type_candidates[0];
 }
 
+/**
+ * @param {FieldObservation[]} observations
+ * @returns {InferredFieldTargetSuggestion | undefined}
+ */
+function inferFieldTarget(observations) {
+  /** @type {Map<string, number>} */
+  const target_counts = new Map();
+  let path_observation_count = 0;
+
+  for (const observation of observations) {
+    const target_type = inferTargetTypeFromObservation(observation);
+
+    if (!target_type) {
+      continue;
+    }
+
+    path_observation_count += 1;
+    target_counts.set(target_type, (target_counts.get(target_type) ?? 0) + 1);
+  }
+
+  if (path_observation_count === 0 || target_counts.size !== 1) {
+    return undefined;
+  }
+
+  const [type_name, count] = [...target_counts.entries()][0];
+
+  return {
+    confidence: Math.round((count / path_observation_count) * 100) / 100,
+    type: type_name,
+  };
+}
+
 /**
  * @param {FieldDiscoveryEvidenceReference} left_reference
  * @param {FieldDiscoveryEvidenceReference} right_reference
@@ -434,16 +464,17 @@ const FIELD_TYPE_SCORERS = {
           value.includes(']')
         ? 0.8
         : 1,
+  ref: () => 0,
   string: () => 0.5,
 };
 
 /**
  * @typedef {{
- *   class_names: Set<string>,
  *   document_id: string,
  *   name: string,
  *   normalized_value: string,
  *   origin: ClaimOrigin,
+ *   type_names: Set<string>,
  *   value: string,
  * }} FieldObservation
  */
@@ -551,6 +582,114 @@ function normalizeDiscoveryValue(value) {
   return trimmed_value;
 }
 
+/**
+ * @param {string} source_path
+ * @param {PatramClaim[]} claims
+ * @returns {string[]}
+ */
+function inferDocumentTypes(source_path, claims) {
+  /** @type {Set<string>} */
+  const document_types = new Set();
+  const path_type = inferPathBackedType(source_path);
+
+  if (path_type) {
+    document_types.add(path_type);
+  }
+
+  for (const claim of claims) {
+    if (
+      claim.type === 'directive' &&
+      (claim.name === 'command' || claim.name === 'term') &&
+      typeof claim.value === 'string' &&
+      claim.value.length > 0
+    ) {
+      document_types.add(claim.name);
+    }
+  }
+
+  return [...document_types].sort((left_type, right_type) =>
+    left_type.localeCompare(right_type, 'en'),
+  );
+}
+
+/**
+ * @param {string} source_path
+ * @returns {string | null}
+ */
+function inferPathBackedType(source_path) {
+  if (source_path.startsWith('docs/conventions/')) {
+    return 'convention';
+  }
+
+  if (source_path.startsWith('docs/decisions/')) {
+    return 'decision';
+  }
+
+  if (source_path.startsWith('docs/plans/')) {
+    return 'plan';
+  }
+
+  if (source_path.startsWith('docs/research/')) {
+    return 'idea';
+  }
+
+  if (source_path.startsWith('docs/roadmap/')) {
+    return 'roadmap';
+  }
+
+  if (source_path.startsWith('docs/tasks/')) {
+    return 'task';
+  }
+
+  return null;
+}
+
+/**
+ * @param {FieldObservation} observation
+ * @returns {string | null}
+ */
+function inferTargetTypeFromObservation(observation) {
+  const value = resolveDiscoveryTargetPath(
+    observation.origin.path,
+    observation.normalized_value,
+  );
+
+  if (
+    !value.includes('/') &&
+    !PATH_PATTERN.test(value) &&
+    !value.startsWith('docs/') &&
+    !value.startsWith('lib/') &&
+    !value.startsWith('test/')
+  ) {
+    return null;
+  }
+
+  if (value.startsWith('docs/reference/commands/')) {
+    return 'command';
+  }
+
+  if (value.startsWith('docs/reference/terms/')) {
+    return 'term';
+  }
+
+  return inferPathBackedType(value) ?? 'document';
+}
+
+/**
+ * @param {string} source_path
+ * @param {string} target_value
+ * @returns {string}
+ */
+function resolveDiscoveryTargetPath(source_path, target_value) {
+  if (target_value.startsWith('./') || target_value.startsWith('../')) {
+    const parent_directory = posix.dirname(source_path);
+
+    return posix.normalize(posix.join(parent_directory, target_value));
+  }
+
+  return target_value;
+}
+
 /**
  * @param {string} field_name
  * @returns {boolean}

package/lib/scan/list-source-files.d.ts

@@ -4,10 +4,10 @@
  * Expands include globs into stable repo-relative file lists for indexing and
  * broken-link validation.
  *
- * Kind: scan
- * Status: active
- * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../../docs/decisions/source-scan.md
+ * kind: scan
+ * status: active
+ * tracked_in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../../docs/decisions/source-scan.md
  * @patram
  * @see {@link ../graph/load-project-graph.js}
  * @see {@link ../../docs/decisions/source-scan.md}

package/lib/scan/list-source-files.js

@@ -7,10 +7,10 @@ import { listMatchingFiles } from './list-repo-files.js';
  * Expands include globs into stable repo-relative file lists for indexing and
  * broken-link validation.
  *
- * Kind: scan
- * Status: active
- * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../../docs/decisions/source-scan.md
+ * kind: scan
+ * status: active
+ * tracked_in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../../docs/decisions/source-scan.md
  * @patram
  * @see {@link ../graph/load-project-graph.js}
  * @see {@link ../../docs/decisions/source-scan.md}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patram",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "main": "./lib/patram.js",
   "types": "./lib/patram.d.ts",
@@ -67,6 +67,7 @@
     "ansis": "^4.2.0",
     "beautiful-mermaid": "^1.1.3",
     "globby": "^16.1.1",
+    "jsonc-parser": "^3.3.1",
     "md4x": "^0.0.25",
     "shiki": "^4.0.2",
     "string-width": "^8.2.0",