patram 0.0.2

package/lib/parse-claims.test.js

@@ -0,0 +1,113 @@
+import { expect, it } from 'vitest';
+
+import { parseClaims } from './parse-claims.js';
+
+it('extracts markdown title, links and directives as neutral claims', () => {
+  const claims = parseClaims({
+    path: 'docs/patram.md',
+    source: createMarkdownSource(),
+  });
+
+  expect(claims).toEqual(createExpectedMarkdownClaims());
+});
+
+it('uses the first line as a plain markdown title', () => {
+  const claims = parseClaims({
+    path: 'docs/plain-title.md',
+    source: ['Patram Plain Title', '', 'Body text.'].join('\n'),
+  });
+
+  expect(claims).toEqual([
+    {
+      document_id: 'doc:docs/plain-title.md',
+      id: 'claim:doc:docs/plain-title.md:1',
+      origin: {
+        column: 1,
+        line: 1,
+        path: 'docs/plain-title.md',
+      },
+      type: 'document.title',
+      value: 'Patram Plain Title',
+    },
+  ]);
+});
+
+it('returns no claims for unsupported file types', () => {
+  const claims = parseClaims({
+    path: 'bin/patram.js',
+    source: 'console.log("Patram");',
+  });
+
+  expect(claims).toEqual([]);
+});
+
+it('returns no claims for extensionless files', () => {
+  const claims = parseClaims({
+    path: 'README',
+    source: '# Patram',
+  });
+
+  expect(claims).toEqual([]);
+});
+
+/**
+ * Create markdown input for parser tests.
+ *
+ * @returns {string}
+ */
+function createMarkdownSource() {
+  return [
+    '# Patram',
+    '',
+    'Read the [graph design](./graph-v0.md).',
+    'Defined by: terms/patram.md',
+  ].join('\n');
+}
+
+/**
+ * Create the expected markdown claims.
+ *
+ * @returns {object[]}
+ */
+function createExpectedMarkdownClaims() {
+  return [
+    {
+      document_id: 'doc:docs/patram.md',
+      id: 'claim:doc:docs/patram.md:1',
+      origin: {
+        column: 1,
+        line: 1,
+        path: 'docs/patram.md',
+      },
+      type: 'document.title',
+      value: 'Patram',
+    },
+    {
+      document_id: 'doc:docs/patram.md',
+      id: 'claim:doc:docs/patram.md:2',
+      origin: {
+        column: 10,
+        line: 3,
+        path: 'docs/patram.md',
+      },
+      type: 'markdown.link',
+      value: {
+        target: './graph-v0.md',
+        text: 'graph design',
+      },
+    },
+    {
+      document_id: 'doc:docs/patram.md',
+      id: 'claim:doc:docs/patram.md:3',
+      name: 'defined_by',
+      origin: {
+        column: 1,
+        line: 4,
+        path: 'docs/patram.md',
+      },
+      parser: 'markdown',
+      type: 'directive',
+      value: 'terms/patram.md',
+    },
+  ];
+}

package/lib/parse-claims.types.ts

@@ -0,0 +1,27 @@
+export interface ParseClaimsInput {
+  path: string;
+  source: string;
+}
+
+export interface ClaimOrigin {
+  path: string;
+  line: number;
+  column: number;
+}
+
+export interface PatramClaim {
+  document_id: string;
+  id: string;
+  name?: string;
+  origin: ClaimOrigin;
+  parser?: string;
+  type: string;
+  value: string | { target: string; text: string };
+}
+
+export type PatramClaimFields = Omit<
+  PatramClaim,
+  'document_id' | 'id' | 'origin' | 'type'
+> & {
+  origin?: ClaimOrigin;
+};

package/lib/patram-config.js

@@ -0,0 +1,194 @@
+/**
+ * @import { PatramConfig } from './patram-config.types.ts';
+ * @import { RefinementCtx } from 'zod';
+ */
+
+import { z } from 'zod';
+
+const KIND_NAME_SCHEMA = z.string().min(1);
+const RELATION_NAME_SCHEMA = z.string().min(1);
+const CLAIM_TYPE_SCHEMA = z.string().min(1);
+const TARGET_SCHEMA = z.enum(['path']);
+
+const kind_definition_schema = z
+  .object({
+    builtin: z.boolean().optional(),
+    label: z.string().min(1).optional(),
+  })
+  .strict();
+
+const relation_definition_schema = z
+  .object({
+    builtin: z.boolean().optional(),
+    from: z.array(KIND_NAME_SCHEMA).min(1),
+    to: z.array(KIND_NAME_SCHEMA).min(1),
+  })
+  .strict();
+
+const mapping_node_schema = z
+  .object({
+    field: z.string().min(1),
+    kind: KIND_NAME_SCHEMA,
+  })
+  .strict();
+
+const mapping_emit_schema = z
+  .object({
+    relation: RELATION_NAME_SCHEMA,
+    target: TARGET_SCHEMA,
+    target_kind: KIND_NAME_SCHEMA,
+  })
+  .strict();
+
+const mapping_definition_schema = z
+  .object({
+    emit: mapping_emit_schema.optional(),
+    node: mapping_node_schema.optional(),
+  })
+  .strict()
+  .superRefine(validateMappingDefinition);
+
+export const patramConfigSchema = z
+  .object({
+    $schema: z.url().optional(),
+    kinds: z.record(KIND_NAME_SCHEMA, kind_definition_schema),
+    mappings: z.record(CLAIM_TYPE_SCHEMA, mapping_definition_schema),
+    relations: z.record(RELATION_NAME_SCHEMA, relation_definition_schema),
+  })
+  .strict()
+  .superRefine(validatePatramConfigReferences);
+
+/**
+ * Parse and validate Patram JSON configuration.
+ *
+ * @param {unknown} config_json
+ * @returns {PatramConfig}
+ */
+export function parsePatramConfig(config_json) {
+  return patramConfigSchema.parse(config_json);
+}
+
+/**
+ * @param {{ emit?: unknown, node?: unknown }} mapping_definition
+ * @param {RefinementCtx} refinement_context
+ */
+function validateMappingDefinition(mapping_definition, refinement_context) {
+  if (mapping_definition.emit || mapping_definition.node) {
+    return;
+  }
+
+  refinement_context.addIssue({
+    code: 'custom',
+    message: 'Mapping must define at least one of "emit" or "node".',
+  });
+}
+
+/**
+ * @param {PatramConfig} config_json
+ * @param {RefinementCtx} refinement_context
+ */
+function validatePatramConfigReferences(config_json, refinement_context) {
+  validateRelationKinds(config_json, refinement_context);
+  validateMappingKinds(config_json, refinement_context);
+  validateMappingRelations(config_json, refinement_context);
+}
+
+/**
+ * @param {PatramConfig} config_json
+ * @param {RefinementCtx} refinement_context
+ */
+function validateRelationKinds(config_json, refinement_context) {
+  for (const [relation_name, relation_definition] of Object.entries(
+    config_json.relations,
+  )) {
+    validateReferencedKinds(
+      relation_definition.from,
+      config_json.kinds,
+      ['relations', relation_name, 'from'],
+      refinement_context,
+    );
+    validateReferencedKinds(
+      relation_definition.to,
+      config_json.kinds,
+      ['relations', relation_name, 'to'],
+      refinement_context,
+    );
+  }
+}
+
+/**
+ * @param {PatramConfig} config_json
+ * @param {RefinementCtx} refinement_context
+ */
+function validateMappingKinds(config_json, refinement_context) {
+  for (const [mapping_name, mapping_definition] of Object.entries(
+    config_json.mappings,
+  )) {
+    if (mapping_definition.emit) {
+      validateReferencedKinds(
+        [mapping_definition.emit.target_kind],
+        config_json.kinds,
+        ['mappings', mapping_name, 'emit', 'target_kind'],
+        refinement_context,
+      );
+    }
+
+    if (mapping_definition.node) {
+      validateReferencedKinds(
+        [mapping_definition.node.kind],
+        config_json.kinds,
+        ['mappings', mapping_name, 'node', 'kind'],
+        refinement_context,
+      );
+    }
+  }
+}
+
+/**
+ * @param {PatramConfig} config_json
+ * @param {RefinementCtx} refinement_context
+ */
+function validateMappingRelations(config_json, refinement_context) {
+  for (const [mapping_name, mapping_definition] of Object.entries(
+    config_json.mappings,
+  )) {
+    if (!mapping_definition.emit) {
+      continue;
+    }
+
+    if (config_json.relations[mapping_definition.emit.relation]) {
+      continue;
+    }
+
+    refinement_context.addIssue({
+      code: 'custom',
+      message: `Unknown relation "${mapping_definition.emit.relation}".`,
+      path: ['mappings', mapping_name, 'emit', 'relation'],
+    });
+  }
+}
+
+/**
+ * @param {string[]} referenced_kinds
+ * @param {Record<string, unknown>} known_kinds
+ * @param {(string | number)[]} issue_path
+ * @param {RefinementCtx} refinement_context
+ */
+function validateReferencedKinds(
+  referenced_kinds,
+  known_kinds,
+  issue_path,
+  refinement_context,
+) {
+  for (const referenced_kind of referenced_kinds) {
+    if (known_kinds[referenced_kind]) {
+      continue;
+    }
+
+    refinement_context.addIssue({
+      code: 'custom',
+      message: `Unknown kind "${referenced_kind}".`,
+      path: issue_path,
+    });
+  }
+}

package/lib/patram-config.test.js

@@ -0,0 +1,147 @@
+import { expect, it } from 'vitest';
+
+import graph_v0_config from '../docs/graph-v0.config.json' with { type: 'json' };
+import { parsePatramConfig } from './patram-config.js';
+
+it('parses the documented v0 config example', () => {
+  const config_json = parsePatramConfig(graph_v0_config);
+
+  expect(config_json.kinds.term.label).toBe('Term');
+  expect(config_json.mappings['markdown.directive.defined_by'].emit).toEqual({
+    relation: 'defines',
+    target: 'path',
+    target_kind: 'term',
+  });
+});
+
+it('rejects mappings that reference unknown relations', () => {
+  const issues = getIssues(createMissingRelationConfig());
+
+  expect(issues).toContainEqual(
+    expect.objectContaining({
+      message: 'Unknown relation "missing_relation".',
+      path: ['mappings', 'markdown.link', 'emit', 'relation'],
+    }),
+  );
+});
+
+it('rejects mappings that reference unknown kinds', () => {
+  const issues = getIssues(createUnknownKindConfig());
+
+  expect(issues).toContainEqual(
+    expect.objectContaining({
+      message: 'Unknown kind "term".',
+      path: [
+        'mappings',
+        'markdown.directive.defined_by',
+        'emit',
+        'target_kind',
+      ],
+    }),
+  );
+});
+
+it('rejects mappings without semantic output', () => {
+  const issues = getIssues(createEmptyMappingConfig());
+
+  expect(issues).toContainEqual(
+    expect.objectContaining({
+      message: 'Mapping must define at least one of "emit" or "node".',
+      path: ['mappings', 'document.title'],
+    }),
+  );
+});
+
+/**
+ * Create a config with an unknown relation reference.
+ *
+ * @returns {object}
+ */
+function createMissingRelationConfig() {
+  return {
+    kinds: {
+      document: {
+        builtin: true,
+      },
+    },
+    mappings: {
+      'markdown.link': {
+        emit: {
+          relation: 'missing_relation',
+          target: 'path',
+          target_kind: 'document',
+        },
+      },
+    },
+    relations: {},
+  };
+}
+
+/**
+ * Create a config with an unknown kind reference.
+ *
+ * @returns {object}
+ */
+function createUnknownKindConfig() {
+  return {
+    kinds: {
+      document: {
+        builtin: true,
+      },
+    },
+    mappings: {
+      'markdown.directive.defined_by': {
+        emit: {
+          relation: 'links_to',
+          target: 'path',
+          target_kind: 'term',
+        },
+      },
+    },
+    relations: {
+      links_to: {
+        from: ['document'],
+        to: ['document'],
+      },
+    },
+  };
+}
+
+/**
+ * Create a config with an empty mapping definition.
+ *
+ * @returns {object}
+ */
+function createEmptyMappingConfig() {
+  return {
+    kinds: {
+      document: {
+        builtin: true,
+      },
+    },
+    mappings: {
+      'document.title': {},
+    },
+    relations: {},
+  };
+}
+
+/**
+ * Parse config and return validation issues.
+ *
+ * @param {object} config_json
+ * @returns {unknown[]}
+ */
+function getIssues(config_json) {
+  try {
+    parsePatramConfig(config_json);
+  } catch (error) {
+    if (error instanceof Error && 'issues' in error) {
+      return /** @type {{ issues: unknown[] }} */ (error).issues;
+    }
+
+    throw error;
+  }
+
+  throw new Error('Expected configuration parsing to fail.');
+}

package/lib/patram-config.types.ts

@@ -0,0 +1,33 @@
+export interface KindDefinition {
+  builtin?: boolean;
+  label?: string;
+}
+
+export interface RelationDefinition {
+  builtin?: boolean;
+  from: string[];
+  to: string[];
+}
+
+export interface MappingNodeDefinition {
+  field: string;
+  kind: string;
+}
+
+export interface MappingEmitDefinition {
+  relation: string;
+  target: 'path';
+  target_kind: string;
+}
+
+export interface MappingDefinition {
+  emit?: MappingEmitDefinition;
+  node?: MappingNodeDefinition;
+}
+
+export interface PatramConfig {
+  $schema?: string;
+  kinds: Record<string, KindDefinition>;
+  mappings: Record<string, MappingDefinition>;
+  relations: Record<string, RelationDefinition>;
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "patram",
+  "version": "0.0.2",
+  "type": "module",
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "bin": {
+    "patram": "./bin/patram.js"
+  },
+  "homepage": "https://github.com/mantoni/patram",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mantoni/patram.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "scripts": {
+    "all": "npm run check:lint && npm run check:format && npm run check:types && npm run test:unit && npm run test:coverage && npm run check:dupes",
+    "check:dupes": "jscpd --min-tokens 100 --min-lines 6 --mode mild --threshold 0 --reporters console --gitignore .",
+    "check:format": "prettier --check .",
+    "check:lint": "eslint .",
+    "check:staged": "lint-staged --quiet",
+    "check:types": "tsc",
+    "postversion": "git push && git push --tags",
+    "preversion": "npm run all",
+    "prepare": "husky",
+    "test": "npm run test:unit && npm run test:coverage",
+    "test:coverage": "vitest run --coverage",
+    "test:unit": "vitest run",
+    "version": "node scripts/update-changelog.js && git add CHANGELOG.md package.json package-lock.json"
+  },
+  "lint-staged": {
+    "*.{js,ts,json,md}": "prettier --check",
+    "*.{js,ts}": [
+      "eslint",
+      "vitest related --run --passWithNoTests"
+    ]
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.12.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "ansis": "^4.2.0",
+    "eslint": "^10.0.3",
+    "eslint-plugin-jsdoc": "^62.8.0",
+    "globals": "^17.4.0",
+    "husky": "^9.1.7",
+    "jscpd": "^4.0.8",
+    "lint-staged": "^16.2.6",
+    "prettier": "^3.5.3",
+    "slice-ansi": "^8.0.0",
+    "string-width": "^8.2.0",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.0",
+    "wrap-ansi": "^10.0.0"
+  }
+}