@pfdsl/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 takasek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# @pfdsl/core
+
+Core pipeline for the PFDSL process-flow DSL: lex → parse → normalize → build graph → validate → sort → format.
+
+## Install
+
+```bash
+pnpm add @pfdsl/core
+```
+
+Requires Node ≥ 18 (ESM only).
+
+## Quick start
+
+```ts
+import { format } from '@pfdsl/core';
+
+const source = `
+[requirement, constraint] >> design -> spec
+spec >>? design
+`;
+
+const { output, diagnostics } = format(source);
+const errors = diagnostics.filter(d => d.severity === 'error');
+
+if (errors.length === 0) {
+  console.log(output);
+}
+```
+
+`format()` is idempotent: `format(format(x).output).output === format(x).output`.
+
+## API
+
+### `format(source: string): FormatResult`
+
+Run the full pipeline and return canonical text plus all diagnostics.
+
+```ts
+interface FormatResult {
+  output: string;          // canonical edge list, one edge per line
+  diagnostics: Diagnostic[]; // frontmatter + lex + parse + normalize + validate
+}
+```
+
+### Stage-by-stage API
+
+For tools that need intermediate state (LSP, exporters):
+
+```ts
+import {
+  parse,             // source → { document, frontmatter, diagnostics }
+  normalizeDocument, // document → { edges, nodeKinds, diagnostics }
+  buildGraph,        // edges → graph (primary + feedback + nodes)
+  validateGraph,     // graph → diagnostics
+  sortEdges,         // edges + graph → canonically sorted edges
+  formatEdges,       // sorted edges → text
+} from '@pfdsl/core';
+
+const { document, frontmatter, diagnostics: parseDiags } = parse(source);
+const { edges, nodeKinds } = normalizeDocument(document, frontmatter);
+const graph = buildGraph(edges, nodeKinds);
+const validateDiags = validateGraph(edges, graph, frontmatter);
+const sorted = sortEdges(edges, graph);
+const text = formatEdges(sorted);
+```
+
+All AST / token / diagnostic / graph types are exported as type-only.
+
+## DSL syntax (cheat sheet)
+
+```pfdsl
+---                              # optional YAML frontmatter
+artifact:
+  spec:
+    label: 仕様書
+process:
+  design:
+    label: 設計
+  build:
+    label: 実装
+    parts: [design]              # composition (build is decomposed into design)
+---
+
+# Edges
+A >> P                           # A is input to process P
+P -> B                           # P produces artifact B
+A >>? P                          # feedback edge (semantic only)
+
+# Chain
+A >> P -> B >> Q -> C            # A→P→B→Q→C, multiple segments
+
+# Set notation (Cartesian product)
+[a, b] >> P -> [x, y]            # 2 inputs × 2 outputs = 4 edges
+
+# Line continuation
+[a, b, c]
+  >> P -> result                 # leading-op continuation OK
+A >> P
+  -> B                           # continuation before -> OK
+
+# Comments and blank lines
+# this is a comment
+[a, b]                           # blank line below would terminate the statement
+  >> P -> X
+```
+
+Full grammar and validation rules: see [docs/spec/spec.md](../../docs/spec/spec.md).
+
+## Diagnostics
+
+Errors and warnings are returned in `diagnostics` arrays, never thrown.
+Each diagnostic carries:
+
+```ts
+interface Diagnostic {
+  severity: 'error' | 'warning' | 'info';
+  code: string;       // FM001, L001, P005, N002, V003, ...
+  message: string;
+  range: { start: Position; end: Position };
+}
+```
+
+Code prefixes: `FM` frontmatter, `L` lexer, `P` parser, `N` normalizer, `V` validator.
+
+## Validation rules
+
+- **V001** Each artifact must have at most one producing process (single source).
+- **V002 / V003** Every process must have ≥1 input and ≥1 output.
+- **V004 – V006** `parts:` declarations must reference processes, must not self-reference, and must not form cycles.
+
+## Canonical ordering
+
+`sortEdges` produces a stable order independent of input ordering:
+
+1. Connected component (by smallest node ID in component)
+2. Topological rank (longest path from a source artifact)
+3. Edge kind (`input` < `feedback` < `output`)
+4. Lexicographic tiebreak
+
+This makes `format()` output suitable for diffing and version control.
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @pfdsl/core build
+pnpm --filter @pfdsl/core test
+pnpm --filter @pfdsl/core typecheck
+```

package/dist/index.d.ts

@@ -0,0 +1,432 @@
+type TokenType = "ARROW_FEEDBACK" | "ARROW_INPUT" | "ARROW_OUTPUT" | "LBRACKET" | "RBRACKET" | "COMMA" | "SEMICOLON" | "NEWLINE" | "COMMENT" | "ID" | "EOF";
+interface Position {
+    line: number;
+    column: number;
+    offset: number;
+}
+interface Token {
+    type: TokenType;
+    value: string;
+    raw: string;
+    start: Position;
+    end: Position;
+}
+
+type DiagnosticSeverity = "error" | "warning" | "info";
+interface Range {
+    start: Position;
+    end: Position;
+}
+interface Diagnostic {
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    range: Range;
+}
+
+declare const STATUS_VALUES: readonly ["done", "wip", "todo", "blocked"];
+type Status = (typeof STATUS_VALUES)[number];
+declare const STYLE_ATTRS: readonly ["fillcolor", "color", "fontcolor", "style", "penwidth"];
+type StyleAttr = (typeof STYLE_ATTRS)[number];
+type NodeStyle = Partial<Record<StyleAttr, string>>;
+interface ArtifactMeta {
+    label?: string;
+    description?: string;
+    owner?: string;
+    externalStakeholders?: string[];
+    parts?: string[];
+    /** Optional positive-integer node index (pfd-tools D{index}). Namespace independent from processes. */
+    index?: number;
+    status?: Status;
+    tags?: string[];
+    group?: string;
+    criteria?: string;
+    location?: string | string[];
+    revises?: string;
+    [key: string]: unknown;
+}
+interface ProcessMeta {
+    label?: string;
+    description?: string;
+    owner?: string;
+    externalStakeholders?: string[];
+    /** Optional positive-integer node index (pfd-tools P{index}). Namespace independent from artifacts. */
+    index?: number;
+    group?: string;
+    tags?: string[];
+    command?: string;
+    /** Relative path to a child .pfdsl expanded as a subflow view-link (§2.9.3). */
+    subflow?: string;
+    /** Optional 1:1 boundary rename map (parent id → child id) for a subflow (§2.9.3). */
+    boundary?: Record<string, string>;
+    [key: string]: unknown;
+}
+interface GroupMeta {
+    label?: string;
+    color?: string;
+    parent?: string;
+    [key: string]: unknown;
+}
+interface TagMeta {
+    label?: string;
+    description?: string;
+    style?: NodeStyle;
+    [key: string]: unknown;
+}
+interface Frontmatter {
+    title?: string;
+    version?: string | number;
+    dslVersion?: string;
+    description?: string;
+    tags?: string[];
+    layout?: {
+        direction?: "LR" | "RL" | "TB" | "BT";
+        maxWidth?: number;
+        [key: string]: unknown;
+    };
+    artifact?: Record<string, ArtifactMeta>;
+    process?: Record<string, ProcessMeta>;
+    group?: Record<string, GroupMeta>;
+    tag?: Record<string, TagMeta>;
+    statusStyles?: Partial<Record<Status, NodeStyle>>;
+    /** Relative path(s) to preset file(s) inherited for presentation keys (§2.9.4). */
+    extends?: string | string[];
+    [key: string]: unknown;
+}
+interface LoadResult {
+    frontmatter: Frontmatter | null;
+    body: string;
+    bodyStartLine: number;
+    diagnostics: Diagnostic[];
+}
+
+interface IdNode {
+    type: "id";
+    value: string;
+    raw: string;
+    start: Position;
+    end: Position;
+}
+interface ArtifactExpr {
+    type: "artifact-expr";
+    ids: IdNode[];
+    start: Position;
+    end: Position;
+}
+interface ChainSegment {
+    op: ">>" | ">>?";
+    process: IdNode;
+    /** null when chain ends with bare `>> process` (output defined elsewhere) */
+    output: ArtifactExpr | null;
+}
+interface ChainStatement {
+    type: "chain";
+    head: ArtifactExpr;
+    segments: ChainSegment[];
+    start: Position;
+    end: Position;
+}
+interface InputEdgeStatement {
+    type: "input-edge";
+    artifact: ArtifactExpr;
+    process: IdNode;
+    start: Position;
+    end: Position;
+}
+interface FeedbackEdgeStatement {
+    type: "feedback-edge";
+    artifact: ArtifactExpr;
+    process: IdNode;
+    start: Position;
+    end: Position;
+}
+interface OutputEdgeStatement {
+    type: "output-edge";
+    process: IdNode;
+    artifact: ArtifactExpr;
+    start: Position;
+    end: Position;
+}
+interface NodeDeclStatement {
+    type: "node-decl";
+    id: IdNode;
+    start: Position;
+    end: Position;
+}
+type Statement = ChainStatement | InputEdgeStatement | FeedbackEdgeStatement | OutputEdgeStatement | NodeDeclStatement;
+interface Document {
+    type: "document";
+    statements: Statement[];
+}
+
+type NormalizedEdge = {
+    kind: "input";
+    artifact: string;
+    process: string;
+} | {
+    kind: "feedback";
+    artifact: string;
+    process: string;
+} | {
+    kind: "output";
+    process: string;
+    artifact: string;
+};
+
+type NodeKind = "artifact" | "process" | "group";
+interface PrimaryEdge {
+    from: string;
+    to: string;
+    kind: "input" | "output";
+}
+interface FeedbackEdge {
+    artifact: string;
+    process: string;
+}
+interface Graph {
+    nodes: Map<string, NodeKind>;
+    primaryEdges: PrimaryEdge[];
+    feedbackEdges: FeedbackEdge[];
+}
+
+interface AuditResult {
+    /** Artifacts produced by a process but not consumed by any process */
+    terminals: string[];
+    /** Artifacts consumed by a process but not produced by any process */
+    externalInputs: string[];
+}
+/**
+ * Inspect the primary graph for terminal artifacts and external inputs.
+ *
+ * Feedback edges are ignored: only `input` and `output` edges count as
+ * production/consumption in the primary graph.
+ *
+ * Artifacts with a non-empty `externalStakeholders` list are treated as
+ * having an external consumer and are excluded from terminals.
+ */
+declare function auditGraph(edges: NormalizedEdge[], nodeKinds: Map<string, NodeKind>, artifactMeta?: Record<string, ArtifactMeta>): AuditResult;
+
+declare function formatEdges(sortedEdges: NormalizedEdge[], sortedIsolated?: string[]): string;
+declare function formatAsFlows(sortedEdges: NormalizedEdge[], sortedIsolated?: string[]): string;
+
+declare function loadFrontmatter(source: string): LoadResult;
+
+declare function buildGraph(edges: NormalizedEdge[], nodeKinds: Map<string, NodeKind>): Graph;
+
+interface NormalizeResult {
+    edges: NormalizedEdge[];
+    nodeKinds: Map<string, "artifact" | "process" | "group">;
+    isolatedNodes: Set<string>;
+    diagnostics: Diagnostic[];
+}
+declare function normalize(doc: Document, fm: Frontmatter | null): NormalizeResult;
+
+declare function sortIsolated(isolatedNodes: Set<string>): string[];
+declare function sortEdges(edges: NormalizedEdge[], graph: Graph): NormalizedEdge[];
+
+interface ValidateOptions {
+    strict?: boolean;
+    source?: string;
+}
+declare function validate(edges: NormalizedEdge[], nodeKinds: Map<string, NodeKind>, fm: Frontmatter | null, options?: ValidateOptions): Diagnostic[];
+
+interface DiffReport {
+    addedNodes: string[];
+    removedNodes: string[];
+    changedNodes: string[];
+    addedEdges: string[];
+    removedEdges: string[];
+    addedFeedback: string[];
+    removedFeedback: string[];
+}
+declare function diffGraphs(a: Graph, b: Graph, fmA?: Frontmatter | null, fmB?: Frontmatter | null): DiffReport;
+
+declare const ID_PATTERN: RegExp;
+interface LexResult {
+    tokens: Token[];
+    diagnostics: Diagnostic[];
+}
+
+interface ParseResult {
+    document: Document;
+    diagnostics: Diagnostic[];
+}
+
+interface IndexChange {
+    kind: NodeKind;
+    id: string;
+    /** Existing index, or null when the node had none. */
+    from: number | null;
+    to: number;
+}
+interface ReindexResult {
+    /** Source with index: assignments applied (unchanged on error). */
+    output: string;
+    /** Nodes whose index was assigned or changed (unchanged ones omitted). */
+    changes: IndexChange[];
+    diagnostics: Diagnostic[];
+}
+interface ReindexOptions {
+    /** Reassign every node from 1 (default: keep existing, fill only gaps). */
+    renumber?: boolean;
+}
+/**
+ * Assign integer `index:` values to nodes in topological order, with
+ * independent counters for processes and artifacts. Default mode fills only
+ * nodes lacking an index; `renumber` reassigns all from 1. Edits are applied
+ * surgically to the front matter text to preserve comments and formatting.
+ */
+declare function reindex(source: string, opts?: ReindexOptions): ReindexResult;
+
+type SortKey = "index" | "topological" | "group" | "id";
+interface SortOptions {
+    by: SortKey[];
+}
+interface SortResult {
+    output: string;
+    changed: boolean;
+    diagnostics: Diagnostic[];
+}
+declare function sort(source: string, opts: SortOptions): SortResult;
+
+declare function resolveMeta(fm: Frontmatter | null | undefined, kind: "artifact", id: string): ArtifactMeta | undefined;
+declare function resolveMeta(fm: Frontmatter | null | undefined, kind: "process", id: string): ProcessMeta | undefined;
+declare function resolveMeta(fm: Frontmatter | null | undefined, kind: "group", id: string): GroupMeta | undefined;
+declare function resolveMeta(fm: Frontmatter | null | undefined, kind: "artifact" | "process", id: string): ArtifactMeta | ProcessMeta | undefined;
+declare function resolveMeta(fm: Frontmatter | null | undefined, kind: NodeKind, id: string): ArtifactMeta | ProcessMeta | GroupMeta | undefined;
+
+/**
+ * Result of resolving a cross-file reference (`subflow:` / `extends:`).
+ * Relative paths resolve against the containing file's directory (§2.9.2).
+ * Absolute paths and URLs are rejected.
+ */
+type RefResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: "absolute" | "url";
+};
+/**
+ * Resolve a relative cross-file reference against the containing file (§2.9.2).
+ * Absolute paths and URLs (`://`) are not permitted.
+ */
+declare function resolveRefPath(fromFile: string, ref: string): RefResult;
+/** A subflow reference: the declaring process id and the child path. */
+interface SubflowRef {
+    process: string;
+    ref: string;
+}
+/** Collect the `extends:` preset references from a frontmatter, in order (§2.9.4). */
+declare function collectExtendsRefs(fm: Frontmatter): string[];
+/** Collect the `subflow:` references declared by processes (§2.9.3). */
+declare function collectSubflowRefs(fm: Frontmatter): SubflowRef[];
+/** A document with at least its parsed frontmatter (what the loader walks). */
+interface DocWithFrontmatter {
+    frontmatter: Frontmatter | null;
+}
+interface LoadedGraph<T> {
+    /** Resolved absolute path → loaded document, including the entry. */
+    docs: Map<string, T>;
+    /** Cross-file diagnostics: missing path (V021), circular subflow (V022). */
+    diagnostics: Diagnostic[];
+}
+/**
+ * Recursively load an entry .pfdsl and its `subflow:` children (§2.9.3 / §15.11).
+ * `load` reads + analyzes a file by absolute path, returning null when absent.
+ * Detects self-referential and multi-hop subflow cycles (V022) and missing
+ * paths (V021). Shared children reached by multiple parents load once.
+ */
+declare function loadSubflowGraph<T extends DocWithFrontmatter>(entryPath: string, load: (path: string) => T | null): LoadedGraph<T>;
+/**
+ * Compute the set of "open input" artifacts in a flow:
+ * artifacts that appear in the flow but have NO output edge producing them (§15.11).
+ */
+declare function computeOpenInputs(edges: NormalizedEdge[]): Set<string>;
+/**
+ * Compute the set of "terminal" artifacts in a flow:
+ * artifacts that appear in the flow but are consumed by NEITHER `>>` (input) NOR `>>?` (feedback) (§15.11).
+ */
+declare function computeTerminals(edges: NormalizedEdge[]): Set<string>;
+/** Context for validating a single subflow boundary (§15.11). */
+interface SubflowBoundaryContext {
+    processId: string;
+    /** Artifact IDs from parent's `>>` (normal input, NOT feedback) edges into this process. */
+    parentNormalInputs: Set<string>;
+    /** Artifact IDs from parent's `->` (output) edges from this process. */
+    parentOutputs: Set<string>;
+    /** boundary: map from frontmatter (parent_id → child_id). Empty object if no boundary. */
+    boundaryMap: Record<string, string>;
+    childOpenInputs: Set<string>;
+    childTerminals: Set<string>;
+}
+/**
+ * Validate the boundary between a parent process and its subflow child (§15.11).
+ * Returns V025 diagnostics for any violations.
+ */
+declare function validateSubflowBoundary(ctx: SubflowBoundaryContext): Diagnostic[];
+/**
+ * Recursively load an entry file and its `extends:` preset chain (§2.9.4 / §15.12).
+ * `load` reads + analyzes a file by absolute path, returning null when absent.
+ * Detects self-referential and multi-hop extends cycles (V027) and missing
+ * paths / invalid paths (V026). Diamond-shaped presets (same file reachable via
+ * multiple paths) are loaded only once — not treated as a cycle.
+ */
+declare function loadExtendsChain<T extends DocWithFrontmatter>(entryPath: string, load: (path: string) => T | null): LoadedGraph<T>;
+/**
+ * Validate that a preset file only contains presentation-layer keys (§2.9.5).
+ * Returns V028 diagnostics for every forbidden key found.
+ */
+declare function validatePresetKeys(path: string, fm: Frontmatter | null): Diagnostic[];
+/** The merged presentation values resolved from an extends chain. */
+interface ResolvedPresentation {
+    statusStyles: Frontmatter["statusStyles"];
+    tag: Frontmatter["tag"];
+    group: Frontmatter["group"];
+}
+/**
+ * Merge statusStyles / tag / group from a sequence of frontmatters in order
+ * (lowest priority first, local last). Each element's values override the
+ * previous at attribute level (§2.9.4 "属性レベル深マージ").
+ */
+declare function resolvePresentation(chain: {
+    path: string;
+    fm: Frontmatter | null;
+}[]): ResolvedPresentation;
+
+interface ParseDocResult {
+    document: Document;
+    frontmatter: Frontmatter | null;
+    bodyStartLine: number;
+    diagnostics: Diagnostic[];
+}
+interface FormatResult {
+    output: string;
+    diagnostics: Diagnostic[];
+}
+interface AnalyzeResult {
+    document: Document;
+    frontmatter: Frontmatter | null;
+    bodyStartLine: number;
+    edges: NormalizedEdge[];
+    nodeKinds: Map<string, NodeKind>;
+    isolatedNodes: Set<string>;
+    graph: Graph;
+    diagnostics: Diagnostic[];
+}
+declare function parse(source: string): ParseDocResult;
+
+declare function hasErrors(diags: readonly Diagnostic[]): boolean;
+
+interface AnalyzeOptions {
+    strict?: boolean;
+}
+declare function analyze(source: string, opts?: AnalyzeOptions): AnalyzeResult;
+interface FormatOptions {
+    style?: "flat" | "flows";
+    skipValidation?: boolean;
+}
+
+declare function format(source: string, opts?: FormatOptions): FormatResult;
+
+export { type AnalyzeOptions, type AnalyzeResult, type ArtifactExpr, type ArtifactMeta, type AuditResult, type ChainSegment, type ChainStatement, type Diagnostic, type DiagnosticSeverity, type DiffReport, type DocWithFrontmatter, type Document, type FeedbackEdge, type FeedbackEdgeStatement, type FormatOptions, type FormatResult, type Frontmatter, type Graph, type GroupMeta, ID_PATTERN, type IdNode, type IndexChange, type InputEdgeStatement, type LexResult, type LoadResult, type LoadedGraph, type NodeDeclStatement, type NodeKind, type NodeStyle, type NormalizeResult, type NormalizedEdge, type OutputEdgeStatement, type ParseDocResult, type ParseResult, type Position, type PrimaryEdge, type ProcessMeta, type Range, type ReindexOptions, type ReindexResult, type ResolvedPresentation, STATUS_VALUES, STYLE_ATTRS, type SortKey, type SortOptions, type SortResult, type Statement, type Status, type StyleAttr, type SubflowBoundaryContext, type SubflowRef, type Token, type TokenType, type ValidateOptions, analyze, auditGraph, buildGraph, collectExtendsRefs, collectSubflowRefs, computeOpenInputs, computeTerminals, diffGraphs, format, formatAsFlows, formatEdges, hasErrors, loadExtendsChain, loadFrontmatter, loadSubflowGraph, normalize as normalizeDocument, parse, reindex, resolveMeta, resolvePresentation, resolveRefPath, sort, sortEdges, sortIsolated, validate as validateGraph, validatePresetKeys, validateSubflowBoundary };